emaui/docs/vessel-ownership-transfer.md

Vessel Ownership Transfer — mock implementation notes (for API integration)

Portal (owner-facing) + Backoffice (officer-facing) built as mock UI only, matching each app's existing mock-driven review-workflow convention. No backend calls anywhere. This doc exists to make wiring the real API fast — it says exactly what to replace and where.

What exists

Portal (apps/portal/src/app/features/vessel-transfer/)

• mock.ts — types + MOCK_VESSELS, MOCK_REQUESTS, addTransferRequest()
• pages/VesselTransferPage.tsx — list/status view (/vessel-transfers)
• pages/VesselTransferApplicationPage.tsx — 4-step submit wizard (/vessel-transfers/apply)

Backoffice (apps/backoffice/src/app/features/vessel-transfer/)

• pages/VesselTransferQueuePage.tsx — types + MOCK_REQUESTS, queue table, stats, quick-view drawer (/vessel-transfers)
• pages/VesselTransferReviewPage.tsx — full review, approve/reject, doc view/download (/vessel-transfers/:id)

Each app defines its own separate mock array (codebase convention: no shared domain types in libs/). They are not the same objects and don't sync — submitting in portal does not appear in the backoffice queue, and vice versa. That's the main thing a real API fixes.

Data shape mismatch to resolve

Portal's TransferRequest.currentOwner / newOwnerName are plain strings. Backoffice's TransferRequest.currentOwner / newOwner are full objects ({ name, idOrTin, phone, email, address }). The real API should standardize on the backoffice shape — it's the superset the officer review page needs.

Known gap: VesselTransferApplicationPage.tsx's wizard collects newOwnerIdOrTin, newOwnerPhone, newOwnerEmail, newOwnerAddress and shows them in the review step, but addTransferRequest() only persists newOwnerName — the rest are captured in UI state and silently dropped on submit. When wiring the real POST, send all of them (the fields already exist in component state, just not in the payload today).

Suggested API surface

• GET /vessels?ownerId=:id&status=approved — portal wizard's vessel <Select> (replaces MOCK_VESSELS.filter(v => v.approved) in VesselTransferApplicationPage.tsx).
• POST /vessel-transfers — submit. Body: vesselId, newOwner: {name, idOrTin, phone, email, address}, reason, document (file upload). Replaces addTransferRequest() in portal's mock.ts.
• GET /vessel-transfers?ownerId=:id — portal's "My Transfer Requests" list (VesselTransferPage.tsx).
• GET /vessel-transfers (officer, all + filters) — backoffice queue (VesselTransferQueuePage.tsx); search/status-filter can move server-side or stay client-side over the fetched page.
• GET /vessel-transfers/:id — backoffice review page and portal status detail both key off this.
• PATCH /vessel-transfers/:id — officer action. Body: { status: 'Under Review' | 'Approved' | 'Rejected', remarks? }. Replaces the in-place record.status = ... mutation in VesselTransferReviewPage.tsx. Backend should enforce remarks-required-on-Rejected (UI already gates this, but don't trust client-only validation).
• Document storage: real upload + signed URL for View, and a real download endpoint — today getDocUrl() in both CoCReviewPage-style DocViewers and this feature's VesselTransferReviewPage.tsx fake it with a hardcoded base64 PDF / placehold.co image.
• SMS/email: triggered server-side on submit and on every status change — UI currently just shows a toast claiming this happened (notify.success('... SMS and email ...')); no actual send anywhere.

Where to swap mock for real calls

• Portal: apps/portal/src/app/features/vessel-transfer/mock.ts (whole file), plus the useState/local reads of MOCK_VESSELS/MOCK_REQUESTS in both page files.
• Backoffice: the exported MOCK_REQUESTS/types block at the top of VesselTransferQueuePage.tsx, plus the direct record.status = ... mutation in VesselTransferReviewPage.tsx (swap for a mutation call + refetch/cache-invalidate).
• Both apps already have an RTK Query base (@ema-platform/api → baseApi.injectEndpoints, see apps/portal/.../payment/api/payment-api.ts or apps/backoffice/.../certification/api/certification-api.ts) — follow that pattern rather than the ad-hoc useApiQuery/useApiMutation escape hatch.