feat(user): add createSupportTicket capability with prerequisite hint

[TaprootFreak]

Narrow follow-up after #3767 was closed. That PR proposed a structured ActionCapability tree (170 LOC, 4 new DTOs, HttpMethod enum); @davidleomay correctly pointed out the endpoint paths are static and belong in Swagger docs, not on every `/v2/user` response. The pure-error pattern (his alternative suggestion) doesn't fit the actual UX requirement: the realunit-app needs to gate the support tile's tap before opening the ticket form, so the user is routed to the email-capture step first — a post-submit 400 means the user fills the form for nothing.

The compromise

• `UserCapabilitiesDto.createSupportTicket: { available, missingPrerequisite? }` — per-user runtime info only. The `available` flag and the `missingPrerequisite` discriminator are derived server-side from `userData.mail`. No endpoint paths in the response — those stay in Swagger.
• `MissingPrerequisite` is a closed enum (`Email`, `Phone`). The app maps the value to the matching capture flow; the backend owns which prerequisite blocks the action, the app owns how the prerequisite is rendered. That's where API-as-Decision-Authority draws the line.
• Mapper returns a discriminated union `{ available: true } | { available: false; missingPrerequisite }` so the compiler pins the invariant `!available implies missingPrerequisite defined`. The DTO class stays for Swagger schema generation (NestJS decorators don't model TS unions cleanly).
• `@ApiBadRequestResponse` decorator added on `POST /v1/support/issue` per @davidleomay's review — Swagger docs now name the email-prerequisite remediation path. Description deliberately not narrowed to the email case so other 400 causes (DTO validation, etc.) remain covered.

Size comparison vs #3767

	#3767 (closed)	this PR
Files	4	4
LOC	+177	+92
New classes / enums	4 DTOs + 1 enum	1 DTO + 1 enum + 1 TS union type
Endpoint hints in response	Yes (4-field nested structure)	No (Swagger only)

Backwards compatibility

• `createSupportTicket?` is optional on the schema (`@ApiPropertyOptional`) so client SDKs pinned to older API versions ignore the new field.
• Other `canEdit*` capability flags untouched.
• Existing service gate (`support-issue.service.ts:123` — `throw new BadRequestException('Mail is missing')`) is unchanged; this PR only adds the proactive Pre-Tap signal that mirrors the gate.

Tests

`user-dto.mapper.spec.ts` gains 4 fixtures:

• user with mail → `{ available: true }`
• user with mail = `null` → `{ available: false, missingPrerequisite: 'Email' }`
• user with mail = `''` → same (pins JS-truthy semantics against future gate drift)
• user with mail = `undefined` → same

Local verification

• `npm run type-check` — clean
• `npm run lint` — clean
• `npm run format:check` — clean
• `npm test` — 944 / 944 passing (940 baseline + 4 new tests)

Review history

Reviewed internally via subagent loop. Two iterations — first pass flagged 3 SHOULD-FIX (discriminated union for type-safety, JS-path-leak in Swagger description, controller decorator scope), all addressed. Final verdict "Ready".

Pair-PR

Closes V9 in `DFXswiss/realunit-app:docs/api-authority-audit.md`. Companion app PR coming on `DFXswiss/realunit-app` to consume the new capability and replace the local mail-gating logic.

cc @davidleomay — interested in your take on the compromise. The Swagger decorator is in (your suggestion); the per-user discriminator is the smallest additional surface I could find that lets the app pre-check before the user starts filling out the form.

[davidleomay]

MissingPrerequisite.PHONE is dead code

[TaprootFreak]

Right — YAGNI. Dropped in 3e26e1f. If a Phone-prerequisite gate gets added on the backend later, the enum extension is additive and backwards-compatible.

[TaprootFreak]

@davidleomay — explicit reasoning for why the PR landed where it did, including where we diverged from your suggestion:

What we adopted from your review (closed PR #3767)

1. Endpoint paths are static — they belong in Swagger, not in every /v2/user payload. Agreed. No { method, path } objects ship in this response. The realunit-app already knows where POST /v1/realunit/register/email lives (it calls it elsewhere already).
2. @ApiBadRequestResponse on POST /v1/support/issue. Added in this PR — Swagger docs now name the email-prerequisite remediation path so any integrator reading the docs sees the full flow.
3. Reduce complexity. From 170 LOC + 4 new DTOs + a new HttpMethod enum down to 92 LOC + 1 DTO + 1 enum (MissingPrerequisite) + 1 TS union type. ~50% smaller.

Where we diverged

Your stronger implicit position is "the app should attempt POST /support/issue, handle the 400 reactively, and use the Swagger-documented remediation". This PR keeps a small per-user runtime field (createSupportTicket.available + optional missingPrerequisite discriminator) on /v2/user. Reasoning, in order of weight:

1. The UX requirement is pre-tap gating, not post-submit recovery

Cyrill's explicit product requirement: when the support tile is tapped, if mail is missing, the user is routed into the email-capture step first, then to the ticket form. The tile itself stays unconditionally visible (per the recently-merged #588 — discoverable support for pre-signin onboarding). This requirement comes from the realunit-app being a pre-signin onboarding surface where many users land before registering an email — they need to discover support, and the path to enable it must be a single forward navigation, not "open form → fill it out → bounce off 400 → scroll to a settings page somewhere".

2. Reactive-error pattern means lost work and confusing UX

If the app attempts POST /support/issue first and reacts to the 400:

• The user has already opened the ticket form, picked a type/reason, typed a message
• On 400, the app would have to interrupt the flow — modal asking to add email, OR back-navigate and lose the typed content, OR push the email page on top of the create-ticket page and pop the stack on success (fragile state management)
• The 400 response is, deliberately, indistinguishable from other 400 causes (DTO validation, etc.) at the HTTP layer. The app would have to introspect the error body to decide whether to retry or surrender.

Pre-tap check makes all of that disappear: at the moment of intent (tile tap), the app already knows whether to push the form or the prerequisite step. Zero retries, zero lost form data, zero error-body parsing for control flow.

3. The runtime cost is bounded and small

The per-user payload added by this PR: 2 fields (available: boolean, missingPrerequisite?: 'Email' | 'Phone'). No nested arrays, no endpoint hints, no labels. Encoded JSON: ~50 bytes worst case. /v2/user is the canonical user-state endpoint; one more boolean-with-discriminator there is in the same order of magnitude as the existing four canEdit* flags this PR sits alongside.

What's not shipped:

• Endpoint paths (your point — they're static, they're in Swagger)
• Method verbs (same reason)
• Display labels (the app owns its i18n)
• Generic capability hierarchy (the original ActionCapability tree was abandoned)

4. Alternatives we considered and rejected

• Dedicated GET /v1/support/issue/preconditions endpoint. Extra round-trip per tap, more endpoints to version, more surface area. The /v2/user response is already fetched on app foreground and cached — riding on it is essentially free.
• Header-driven capabilities (Accept-Capabilities: support). More machinery than the simple optional field, and old clients still pay the dispatcher cost.
• Just a bool supportAvailable: bool. Was the original Wave-3 attempt (feat(user/realunit): expose user capabilities + structured ALREADY_REGISTERED status #3733 → refactor(user/realunit): drop UserCapabilitiesDto.supportAvailable #3761 rollback). A bool doesn't tell the app what's missing, so the app would have to encode "if !supportAvailable then mail must be missing" — which is a backend rule replicated in the frontend, the exact anti-pattern the audit V9 captures.

The missingPrerequisite discriminator is the smallest field that:

• (a) lets the app pre-check before opening the form,
• (b) carries no backend rule into the frontend (the app maps a typed enum value to a UI step, not "interpret why support is unavailable"),
• (c) extends cleanly when a future prerequisite type is added (e.g. Phone) without an app release for the "what does that mean" mapping — only for the UI of the new step.

5. How this aligns with the API authority plan

realunit-app/docs/api-authority-plan.md Wave 3 prescribed exactly this kind of capability surfacing (with the original bool variant). #3761 rolled that back because the UX requirement made the bool insufficient. This PR is the second attempt at Wave 3 with a discriminator that's expressive enough for the UX without re-creating the structural overhead of #3767.

---

Open question for you

Is the marginal per-user payload (the createSupportTicket field) tolerable given the UX rationale above? If yes — happy to mark the PR ready for review. If you'd push back further — happy to revisit by extracting the capability to an opt-in endpoint, but I'd want to be sure the per-tap round-trip is actually a worse trade than the /v2/user field before going that direction.

[davidleomay]

Makes sense, approved.