feat(kyc): expose decision fields (isRequired, canTrade, processStatus) so clients can stop re-implementing routing locally

[Blume1977]

Summary

The realunit-app's KycCubit (lib/screens/kyc/cubits/kyc/kyc_cubit.dart) was rebuilding the API's own routing rule client-side: a hardcoded _requiredStepNames set, an actionableStatuses set, and a _minLevelForActions = 30 threshold. That setup misroutes any high-level user whose Ident step has been re-issued by checkDfxApproval — exactly the 2026-05-21 incident report (user_data 338759: kycLevel 53 + an Outdated Ident step + a sequence-1 Ident step in InProgress → the app sends the user back to KycIdentPage even though the existing trading-relevant signals are all green).

The app shouldn't be deciding that. This PR surfaces the three signals it needs directly in the DTOs so it can render the verdict verbatim and stop second-guessing.

Wave 2.1 of DFXswiss/realunit-app docs/api-authority-plan.md. The companion app-side PR consumes these fields and deletes the local logic in one go (per the pair-PR convention defined in realunit-app#491).

What changes

KycStepDto.isRequired: boolean

Populated from requiredKycSteps(userData) at mapping time. Clients drop their own duplicate sets and iterate kycSteps.filter(s => s.isRequired) instead. The required-step list still lives in kyc.enum.ts — the DTO just exposes the per-user verdict.

UserKycDto.canTrade: boolean (/v2/user)

Authoritative trading-permission flag, computed in UserDtoMapper.computeCanTrade:

canTrade = !isKycTerminated && !isBlocked
        && kycLevel >= LEVEL_30
        && requiredKycSteps.every(rs => hasCompletedStep(rs))
        && no Ident/FinancialData step in Outdated/InProgress/InReview/OnHold/Failed

A level-50 user with an Outdated Ident now correctly reports canTrade: false. Comment in the mapper links back to the app-side plan.

KycLevelDto.processStatus: KycProcessStatus

High-level KYC process state for clients that don't need step granularity:

• InProgress — at least one required step is actionable by the user
• PendingReview — at least one required step is in backend review (InternalReview/ExternalReview/ManualReview/OnHold)
• Completed — all required steps Completed
• Failed — KYC terminated

Computed in KycInfoMapper.computeProcessStatus. Clients render this directly instead of inferring it from kycSteps.

How it threads through the mapper

KycInfoMapper.toDto computes requiredStepNames once and threads it through KycStepMapper.toStep(..., isRequired) + the new computeProcessStatus helper. KycStepMapper.toStep gains a third (optional) isRequired parameter — defaulted to false so the ~hundred existing call sites compile unchanged.

Why this is safe for old clients

All three additions are optional / nullable-shaped on the wire:

• KycStepDto.isRequired defaults to false if the caller doesn't pass isRequired to KycStepMapper.toStep (none of the existing call sites do)
• UserKycDto.canTrade is added as a new field; old clients ignore it
• KycLevelDto.processStatus is added as a new field; old clients ignore it

No schema reordering, no enum reordering, no breaking changes to existing responses.

Tests

• user-dto.mapper.spec.ts adds a fixture-based regression block that reproduces the 2026-05-21 user_data 338759 shape (level 50 + completed Ident + outdated Ident + in-progress Ident@seq 1 → canTrade: false) and the surrounding cases (clean level 50, level 20, outdated FinancialData, terminated KYC).
• new ConfigService() in beforeAll wires the Config singleton for sub-LEVEL_50 tradingLimit resolution. (UserDtoMapper.mapUser reaches into userData.tradingLimit, which uses Config.tradingLimits.monthlyDefaultWoKyc for sub-LEVEL_50.)
• KycInfoMapper.computeProcessStatus is exercised indirectly through the canTrade fixtures; if reviewers want a direct unit test on the helper it can be added.

Local verification

• npm run type-check — clean
• npm run lint — clean
• npm test — 943 / 943 passing (938 baseline kept green + 5 new tests)

Test plan

• Manual hit against DEV: GET /v2/user returns kyc.canTrade reflecting the rule for a couple of fixture accounts (clean level-50, level-50 with Outdated ident, level-20).
• Manual hit against DEV: GET /v2/kyc returns processStatus matching the visible state in the admin tool.
• Smoke: GET /v2/kyc response for user_data 338759 → processStatus: 'InProgress', the InProgress Ident step has isRequired: true.

Out of scope / follow-ups

• KycSessionDto.currentStep already carries everything the app needs for routing the actionable step; no change here.
• The other Wave-3 fields (UserV2Dto.capabilities, SellPaymentInfoDto.requiredWorkflow, RealUnitRegistrationStatus.ALREADY_REGISTERED) ship in a separate PR.

Companion app PR

App-side consumption + local-logic removal: opening immediately after this merges. Will reference Closes DFXswiss/api#NNNN (this PR).

[github-actions]

⚠️ Unverified Commits (2)

The following commits are not signed/verified:

• ae50abf feat(kyc): expose decision fields so clients can stop re-implementing routing locally (Blume1977)
• b6233a9 style: prettier (Blume1977)

How to sign commits

# SSH signing (recommended)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# Re-sign last commit
git commit --amend -S --no-edit
git push --force-with-lease