feat: split RealUnit register endpoint (#3057)

* feat: add register/email and register/complete endpoints.

* chore: RegistrationStatus naming.

* chore: remove duplicated code.

* fix: check for merge string.

Author: xlamn

src/subdomains/supporting/realunit/controllers/realunit.controller.ts

@@ -16,6 +16,7 @@ import {
   ApiAcceptedResponse,
   ApiBadRequestResponse,
   ApiBearerAuth,
+  ApiConflictResponse,
   ApiExcludeEndpoint,
   ApiOkResponse,
   ApiOperation,
@@ -50,6 +51,8 @@ import {
   RealUnitSingleReceiptPdfDto,
 } from '../dto/realunit-pdf.dto';
 import {
+  RealUnitEmailRegistrationDto,
+  RealUnitEmailRegistrationResponseDto,
   RealUnitRegistrationDto,
   RealUnitRegistrationResponseDto,
   RealUnitRegistrationStatus,
@@ -319,7 +322,55 @@ export class RealUnitController {
     return this.realunitService.confirmSell(jwt.user, +id, dto);
   }
 
-  // --- Registration Endpoint ---
+  // --- Registration Endpoints ---
+
+  @Post('register/email')
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard(), RoleGuard(UserRole.ACCOUNT), UserActiveGuard())
+  @ApiOperation({
+    summary: 'Step 1: Register email for RealUnit',
+    description:
+      'First step of RealUnit registration. Checks if email exists in DFX system. If exists and merge is possible, sends merge confirmation email. Otherwise registers email and sets KYC Level 10.',
+  })
+  @ApiOkResponse({ type: RealUnitEmailRegistrationResponseDto })
+  @ApiBadRequestResponse({ description: 'Email does not match verified email' })
+  @ApiConflictResponse({ description: 'Account already exists and merge not possible' })
+  async registerEmail(
+    @GetJwt() jwt: JwtPayload,
+    @Body() dto: RealUnitEmailRegistrationDto,
+  ): Promise<RealUnitEmailRegistrationResponseDto> {
+    const status = await this.realunitService.registerEmail(jwt.account, dto);
+    return { status };
+  }
+
+  @Post('register/complete')
+  @ApiBearerAuth()
+  @UseGuards(AuthGuard(), RoleGuard(UserRole.ACCOUNT), UserActiveGuard())
+  @ApiOperation({
+    summary: 'Step 2: Complete RealUnit registration',
+    description:
+      'Second step of RealUnit registration. Requires email registration to be completed. Validates personal data against DFX system and forwards to Aktionariat.',
+  })
+  @ApiOkResponse({ type: RealUnitRegistrationResponseDto })
+  @ApiAcceptedResponse({
+    type: RealUnitRegistrationResponseDto,
+    description: 'Registration accepted, manual review needed or forwarding to Aktionariat failed',
+  })
+  @ApiBadRequestResponse({
+    description: 'Invalid signature, wallet mismatch, email registration not completed, or data mismatch',
+  })
+  async completeRegistration(
+    @GetJwt() jwt: JwtPayload,
+    @Body() dto: RealUnitRegistrationDto,
+    @Res() res: Response,
+  ): Promise<void> {
+    const status = await this.realunitService.completeRegistration(jwt.account, dto);
+    const response: RealUnitRegistrationResponseDto = {
+      status: status,
+    };
+    const statusCode = status === RealUnitRegistrationStatus.COMPLETED ? HttpStatus.CREATED : HttpStatus.ACCEPTED;
+    res.status(statusCode).json(response);
+  }
 
   @Post('register')
   @ApiBearerAuth()

src/subdomains/supporting/realunit/dto/realunit-registration.dto.ts

@@ -26,13 +26,34 @@ export enum RealUnitUserType {
 export enum RealUnitRegistrationStatus {
   COMPLETED = 'completed',
   PENDING_REVIEW = 'pending_review',
+  MANUAL_REVIEW_DATA_MISMATCH = 'manual_review_data_mismatch',
+  FORWARDING_FAILED = 'forwarding_failed',
 }
 
 export class RealUnitRegistrationResponseDto {
   @ApiProperty({ enum: RealUnitRegistrationStatus })
   status: RealUnitRegistrationStatus;
 }
 
+export enum RealUnitEmailRegistrationStatus {
+  EMAIL_REGISTERED = 'email_registered',
+  MERGE_REQUESTED = 'merge_requested',
+}
+
+export class RealUnitEmailRegistrationDto {
+  @ApiProperty()
+  @IsNotEmpty()
+  @IsEmail()
+  @IsLowercase()
+  @Transform(Util.trim)
+  email: string;
+}
+
+export class RealUnitEmailRegistrationResponseDto {
+  @ApiProperty({ enum: RealUnitEmailRegistrationStatus })
+  status: RealUnitEmailRegistrationStatus;
+}
+
 export enum RealUnitLanguage {
   EN = 'EN',
   DE = 'DE',

src/subdomains/supporting/realunit/realunit.service.ts

@@ -34,6 +34,7 @@ import { KycStep } from 'src/subdomains/generic/kyc/entities/kyc-step.entity';
 import { KycStepName } from 'src/subdomains/generic/kyc/enums/kyc-step-name.enum';
 import { ReviewStatus } from 'src/subdomains/generic/kyc/enums/review-status.enum';
 import { KycService } from 'src/subdomains/generic/kyc/services/kyc.service';
+import { AccountMergeService } from 'src/subdomains/generic/user/models/account-merge/account-merge.service';
 import { AccountType } from 'src/subdomains/generic/user/models/user-data/account-type.enum';
 import { UserData } from 'src/subdomains/generic/user/models/user-data/user-data.entity';
 import { KycLevel } from 'src/subdomains/generic/user/models/user-data/user-data.enum';
@@ -52,7 +53,14 @@ import {
   TokenInfoClientResponse,
 } from './dto/client.dto';
 import { RealUnitDtoMapper } from './dto/realunit-dto.mapper';
-import { AktionariatRegistrationDto, RealUnitRegistrationDto, RealUnitUserType } from './dto/realunit-registration.dto';
+import {
+  AktionariatRegistrationDto,
+  RealUnitEmailRegistrationDto,
+  RealUnitEmailRegistrationStatus,
+  RealUnitRegistrationDto,
+  RealUnitRegistrationStatus,
+  RealUnitUserType,
+} from './dto/realunit-registration.dto';
 import { RealUnitSellConfirmDto, RealUnitSellDto, RealUnitSellPaymentInfoDto } from './dto/realunit-sell.dto';
 import {
   AccountHistoryDto,
@@ -98,6 +106,7 @@ export class RealUnitService {
     private readonly sellService: SellService,
     private readonly eip7702DelegationService: Eip7702DelegationService,
     private readonly transactionRequestService: TransactionRequestService,
+    private readonly accountMergeService: AccountMergeService,
   ) {
     this.ponderUrl = GetConfig().blockchain.realunit.graphUrl;
   }
@@ -341,6 +350,91 @@ export class RealUnitService {
     return !success;
   }
 
+  async registerEmail(userDataId: number, dto: RealUnitEmailRegistrationDto): Promise<RealUnitEmailRegistrationStatus> {
+    const userData = await this.userDataService.getUserData(userDataId, { users: true });
+    if (!userData) throw new NotFoundException('User not found');
+
+    if (!userData.mail) {
+      try {
+        await this.userDataService.trySetUserMail(userData, dto.email);
+      } catch (e) {
+        if (e instanceof ConflictException) {
+          if (e.message.includes('account merge request sent')) {
+            return RealUnitEmailRegistrationStatus.MERGE_REQUESTED;
+          }
+        }
+        throw e;
+      }
+    } else if (!Util.equalsIgnoreCase(dto.email, userData.mail)) {
+      throw new BadRequestException('Email does not match verified email');
+    }
+
+    if (userData.kycLevel < KycLevel.LEVEL_10) {
+      await this.kycService.initializeProcess(userData);
+    }
+
+    return RealUnitEmailRegistrationStatus.EMAIL_REGISTERED;
+  }
+
+  async completeRegistration(userDataId: number, dto: RealUnitRegistrationDto): Promise<RealUnitRegistrationStatus> {
+    await this.validateRegistrationDto(dto);
+
+    // get and validate user
+    const userData = await this.userService
+      .getUserByAddress(dto.walletAddress, {
+        userData: { kycSteps: true, users: true, country: true, organizationCountry: true },
+      })
+      .then((u) => u?.userData);
+
+    if (!userData) throw new NotFoundException('User not found');
+    if (userData.id !== userDataId) throw new BadRequestException('Wallet address does not belong to user');
+
+    if (userData.kycLevel < KycLevel.LEVEL_10 || !userData.mail) {
+      throw new BadRequestException('Email registration must be completed first');
+    }
+    if (!Util.equalsIgnoreCase(dto.email, userData.mail)) {
+      throw new BadRequestException('Email does not match registered email');
+    }
+
+    // duplicate check
+    if (userData.getNonFailedStepWith(KycStepName.REALUNIT_REGISTRATION)) {
+      throw new BadRequestException('RealUnit registration already exists');
+    }
+
+    // store data with internal review
+    const kycStep = await this.kycService.createCustomKycStep(
+      userData,
+      KycStepName.REALUNIT_REGISTRATION,
+      ReviewStatus.INTERNAL_REVIEW,
+      dto,
+    );
+
+    const hasExistingData = userData.firstname != null;
+    if (hasExistingData) {
+      const dataMatches = this.isPersonalDataMatching(userData, dto);
+      if (!dataMatches) {
+        await this.kycService.saveKycStepUpdate(kycStep.manualReview('Existing KYC data does not match'));
+        return RealUnitRegistrationStatus.MANUAL_REVIEW_DATA_MISMATCH;
+      }
+    } else {
+      await this.userDataService.updatePersonalData(userData, dto.kycData);
+    }
+
+    // forward to Aktionariat
+    const success = await this.forwardRegistration(kycStep, dto);
+    if (!success) return RealUnitRegistrationStatus.FORWARDING_FAILED;
+
+    // only update after successful forward
+    await this.userDataService.updateUserDataInternal(userData, {
+      nationality: await this.countryService.getCountryWithSymbol(dto.nationality),
+      birthday: new Date(dto.birthday),
+      language: dto.lang && (await this.languageService.getLanguageBySymbol(dto.lang)),
+      tin: dto.countryAndTINs?.length ? JSON.stringify(dto.countryAndTINs) : undefined,
+    });
+
+    return RealUnitRegistrationStatus.COMPLETED;
+  }
+
   private async validateRegistrationDto(dto: RealUnitRegistrationDto): Promise<void> {
     // signature validation
     if (!this.verifyRealUnitRegistrationSignature(dto)) {