pn-new-crm/docs/admin-ux-backlog.md

# Admin / settings UX backlog — STATUS

Living tracker for the admin/UX backlog. Items are marked DONE or
REMAINING based on what landed in the autonomous-push session.

---

## DONE in the autonomous push

### Foundations

- **Currency API verified end-to-end**. `scripts/test-currency-api.ts`
  fetches live Frankfurter rates → upserts → reads back → converts.
  Inverse-rate drift confirmed at ≤0.001.
- **Storage abstraction audit complete**. Every byte path
  (signed EOIs, contracts, brochures, berth PDFs, files, avatars,
  branding logos) goes through `getStorageBackend()`. `/api/ready`
  and the system-monitoring health probe now check the active
  backend (S3 or filesystem) instead of always probing MinIO.

### User settings

- Country + Timezone selectors with cross-defaulting + auto-detect
  banner ("Looks like you're in Europe/Paris — Update?")
- Email change with verification flow (`user_email_changes` table,
  `/api/v1/me/email/confirm/<token>`, `/api/v1/me/email/cancel/<token>`)
- Password reset triggered via better-auth `requestPasswordReset`
- Profile photo upload + crop (square 256×256) via shared
  `<ImageCropperDialog>` + `/api/v1/me/avatar`

### Branding

- Logo upload + crop modal in admin/branding (uses the same shared
  cropper, persists via `/api/v1/admin/settings/image` → storage backend)
- Email header/footer HTML defaults injectable via "Insert default" button
- Brand colour picker, app-name field, logo URL all in one card

### Storage admin

- New layout: S3 config form FIRST, swap action SECOND
- Test connection button before any switch
- Two-button switch: "Switch + migrate" vs "Switch only" with warning modal
- `runMigration()` honours `skipMigration` flag

### Backup management

- Real `/admin/backup` page driven by new `backup_jobs` table
- `runBackup()` service spawns `pg_dump --format=custom`, streams to
  active storage backend, records size + path
- Download button presigns the .dump for offline restore
- Super-admin gated

### AI admin panel

- Dedicated `/admin/ai` page consolidating master switch +
  monthly token cap + provider credentials
- Per-feature settings (OCR, berth-PDF parser, recommender)
  linked from the same page

### Onboarding

- Real `/admin/onboarding` page with auto-checked steps
- Reads each setting key + lists endpoint (roles / users / tags) to
  decide completion
- Manual checkboxes for steps without an auto-detect signal
- Progress bar + "Mark done"/"Mark incomplete" buttons
- State persisted in `system_settings.onboarding_manual_status`

### Residential parity (full)

- New `residential_client_notes` + `residential_interest_notes`
  tables (mirror marina-side shape)
- Polymorphic `notes.service.ts` extended with two new entity types
  through verifyParent + listForEntity + create + update + delete
- New `<NotesList>` accepts `residential_clients` /
  `residential_interests` entity types
- Activity endpoints: `/api/v1/residential/clients/[id]/activity` +
  `/api/v1/residential/interests/[id]/activity`
- Notes endpoints: 4 new routes covering GET/POST/PATCH/DELETE
- `residential-client-tabs.tsx` + `residential-interest-tabs.tsx`
  built using the marina-side `DetailLayout` pattern (Overview +
  Notes + Activity tabs, Interests tab on the client)
- Detail header components mirror the marina-side strip
- `useBreadcrumbHint` wired into both detail components

### Residential pipeline stages — configurable

- New `residential-stages.service.ts` with list/save + orphan-check
- `/api/v1/residential/stages` GET/PUT
- `/admin/residential-stages` admin UI with reassign-on-remove
  modal (select new stage per affected interest before save)
- Validators relaxed from `z.enum(...)` to `z.string()` so any
  admin-defined stage id round-trips

### Documenso Phase 1 (EOI generate flow polish)

- Schema migrations applied:
  `document_signers.invited_at / opened_at / last_reminder_sent_at / signing_token`,
  `documents.completion_cc_emails / auto_reminder_interval_days`
- `transformSigningUrl()` now maps SignerRole → URL segment correctly
  (approver→cc, witness→witness) so emails don't land on `/sign/error`
- New `POST /api/v1/documents/[id]/send-invitation` endpoint with
  next-pending-signer auto-pick
- Per-port settings added: `documenso_developer_label`,
  `documenso_approver_label`, `documenso_developer_user_id`,
  `documenso_approver_user_id` (Phase 7 RBAC binding fields)

### Misc UI/UX

- Sidebar collapse removed (always expanded)
- Audit log filter inputs sized + dates widened
- Custom Settings section got a long-form description
- Reminder digest timezone uses `TimezoneCombobox`
- Port form: currency dropdown + timezone combobox + brand color
- Permissions count badge opens a modal with granted/denied
- Role names display-normalized via `prettifyRoleName`
- Sales email config: token list + tooltips on threshold + body fields
- Custom Fields page: amber heads-up about non-integration with
  search / recommender / audit / merge tokens
- Tag form: native `<input type="color">`
- FilterBar Select crash fixed (no empty-string item values)

---

## REMAINING — large pieces that didn't fit this push

### 1. Documenso Phase 2 — Webhook handler enhancement (~3-4 hours)

Cascading "your turn" emails when each signer completes; on-completion
PDF distribution; token-based recipient matching; idempotency lock.
File to extend: `src/app/api/webhooks/documenso/route.ts`. The
schema columns are already in place (Phase 1).

### 2. Documenso Phase 3 — Custom doc upload-to-Documenso (~6-8 hours)

Backend service `custom-document-upload.service.ts` + endpoint
`POST /api/v1/interests/[id]/upload-for-signing`. Accepts a PDF +
recipient list + field-placement JSON, calls `createDocument` →
`placeFields` → `sendDocument` on the per-port Documenso client.
Persists a row in `documents` table.

### 3. Documenso Phase 4 — Field placement UI (~10-14 hours)

The biggest piece. Needs:

- 4a: Recipient configurator dialog (~2-3h)
- 4b: PDF rendering with `react-pdf` (~3-4h)
- 4c: Auto-detect anchor scanner via `pdfjs-dist.getTextContent` (~4-6h)
- 4d: Drag-drop overlay using `dnd-kit` (~3-4h)
- 4e: Send button → calls Phase 3 endpoint (~1h)

Plan locked in `docs/documenso-build-plan.md` Phase 4 — the
field-detector regexes, the anchor patterns, and the type-to-bbox
sizing table are all spelled out.

### 4. Documenso Phase 5 — Embedded signing URL emission verification (~1-2 hours)

Verify the website's `/sign/<type>/<token>` page handles every signer
role + every documentType combination. Update website's
`signerMessages` map keyed on `(documentType, role)`. Apply the
nginx CORS block from `docs/documenso-integration-audit.md`.

### 5. Documenso Phase 6 — Polish items (deferred)

Auto-send delay, audit-log additions, per-document customisation,
document expiration, reminder rate-limit display, failed-webhook
recovery UI. Each ~2-3 hours; all deferred until Phases 1-4 ship.

### 6. Project Director — UI binding for the developer-user fields

Schema + setting keys are now in place
(`documenso_developer_user_id`, `documenso_approver_user_id` +
`documenso_developer_label` / `_approver_label`). The remaining
work is: add a "Linked to CRM user" dropdown in
`/admin/documenso/page.tsx` that lists port users; when bound,
auto-fill name/email from the user profile and mark name/email
fields read-only. Webhook handler can then match against the
linked user's email for in-CRM signing-status updates.

### 7. Custom-fields hardening (~ongoing)

Remediation paths for the heads-up banner concerns:

- **Search index**: extend the GIN tsvector to include
  customFieldValues content
- **Audit diff**: extend `diffEntity` to walk the
  customFieldValues blob
- **Merge tokens**: add `{{custom.<fieldName>}}` handling at
  template-render time, plus surface them in the merge-tokens UI

### 8. Documenso v2 webhook payload audit (small)

Risk #4 from `docs/documenso-build-plan.md` — confirm v2 payload
shape (`payload.documentId` vs `payload.id`, recipient.token vs
`recipient.recipientId`) against a live v2 instance before relying
on Phase 2 cascading emails.