docs(spec): documents hub + reservation agreements + visual polish (Phase A)
Captures the brainstorm output covering: - Documents hub at /[port]/documents replacing existing list - Document detail page with vertical signers panel, watchers, timeline - Generalised create-document wizard (HTML / PDF AcroForm / PDF overlay / Documenso-rendered + ad-hoc PDF upload) - Reservation agreements as a doc type with new CRM-side detail page - Email composer attachments + System-vs-User From selector (admin-gated) - Reminder framework polish (per-template cadence, per-doc override, per-doc disable, per-signer manual reminders); drops interests.reminderEnabled gating - Documenso v1.13.1/v2.x version-aware abstraction for field placement + void - System-wide visual polish (token additions, primitive components, sweep) - Test plan including click-everything sweep + expanded realapi round-trip - Build sequence: 11 PRs, ~3.5 weeks critical path Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Ciaccio
775
docs/superpowers/specs/2026-04-28-documents-hub-design.md
Normal file
775
docs/superpowers/specs/2026-04-28-documents-hub-design.md
Normal file
@@ -0,0 +1,775 @@
|
||||
# Documents Hub, Reservation Agreements, and Visual Polish (Phase A)
|
||||
|
||||
**Status:** Draft — awaiting final review
|
||||
**Date:** 2026-04-28
|
||||
**Phase:** A of D (B = Insights & Alerts; C = Website integration; D = Pre-prod ops)
|
||||
|
||||
## Overview
|
||||
|
||||
Phase A delivers a unified Documents Hub that tracks every signature-based document (EOI, Reservation Agreements, NDAs, ad-hoc uploads), generalises the existing single-purpose EOI dialog into a multi-format create-document wizard, builds the missing CRM-side reservation detail page with an end-to-end agreement workflow, polishes the reminder framework so non-EOI docs auto-remind correctly, and applies a system-wide visual upgrade to the polished-SaaS aesthetic the project already has tokens for.
|
||||
|
||||
The project already ships a usable CRM with auth, multi-tenancy, full client/yacht/company/interest/berth/reservation data model, an EOI dual-path (Documenso template + in-app PDF), socket-driven real-time updates, and 130 smoke specs. What's missing for the next release: a single place to see what documents need signing and chase the people who haven't signed.
|
||||
|
||||
## Scope boundaries
|
||||
|
||||
### In scope (this spec)
|
||||
|
||||
- New `/[port]/documents` hub page replacing the existing list
|
||||
- New `/[port]/documents/[id]` document detail page
|
||||
- Generalised create-document wizard supporting four template formats (HTML, PDF AcroForm fillable, PDF overlay-positioned, Documenso-rendered) plus ad-hoc PDF upload
|
||||
- New `/[port]/berth-reservations/[id]` reservation detail page with agreement-generation flow
|
||||
- Reservation Agreement as a first-class document type with default template seeded
|
||||
- Email composer extended with attachments and a System-vs-User From selector (admin-gated)
|
||||
- Reminder framework: per-template cadence, per-doc override, per-doc disable, per-signer manual reminders
|
||||
- Documenso version-aware abstraction layer covering field placement and document voiding across v1.13.1 and v2.x
|
||||
- System-wide visual polish: shadow scale, gradient layer, animation tokens, primitive components (`<StatusPill>`, `<KPITile>`, `<EmptyState>`, polished `<PageHeader>`), applied across all list and detail pages
|
||||
- Mobile-responsive sweep across every page touched
|
||||
- Comprehensive test coverage: unit, integration, smoke, exhaustive click-through, real-API round-trips, visual baseline regeneration
|
||||
|
||||
### Explicitly out of scope (deferred to later phases)
|
||||
|
||||
- Analytics dashboard, alert framework, interests-by-berth view, expense duplicate detection (Phase B)
|
||||
- Website-side integration: `/api/form/[token]/data` prefill endpoint, `/api/webhook/document-signed` callback receiver, public-endpoint shape compat (Phase C)
|
||||
- NocoDB to Postgres data migration, email deliverability (DKIM/SPF/DMARC), Sentry error reporting, audit log retention, performance baseline at 5k clients / 50k interests, backup/restore automation, production deploy readiness (Phase D)
|
||||
- Native in-CRM PDF field-placement editor (deferred until upload-path pain emerges; Phase A v1 ships with auto-placed footer signature fields and a "Customize fields in Documenso" link)
|
||||
- Word `.docx` template upload (deferred; PDF prioritized because Word adds LibreOffice/CloudConvert toolchain dependency without saving the field-placement step)
|
||||
- Per-interest "silence all reminders" toggle (was implicit in old `interests.reminderEnabled` gating which this spec drops; can be re-added as a bulk action if anyone misses it)
|
||||
|
||||
## Information architecture
|
||||
|
||||
### URL surface
|
||||
|
||||
```
|
||||
/[port]/documents hub (replaces existing list)
|
||||
/[port]/documents/[id] document detail (new)
|
||||
/[port]/documents/new create-document wizard (new)
|
||||
/[port]/berth-reservations/[id] reservation detail (new)
|
||||
/[port]/admin/templates existing; extended for new template formats
|
||||
/[port]/admin/email existing; one new toggle
|
||||
```
|
||||
|
||||
### Schema deltas
|
||||
|
||||
```
|
||||
documents — additions:
|
||||
+ reservation_id text null references berth_reservations(id)
|
||||
+ reminders_disabled boolean default false
|
||||
+ reminder_cadence_override int null
|
||||
|
||||
document_templates — additions:
|
||||
+ reminder_cadence_days int null (null = no auto-reminders)
|
||||
+ template_format text default 'html' ('html'|'pdf_form'|'pdf_overlay'|'documenso_render')
|
||||
+ source_file_id text null references files(id)
|
||||
+ documenso_template_id text null
|
||||
+ field_mapping jsonb default '{}' (pdf_form: { acroFieldName: mergeToken })
|
||||
+ overlay_positions jsonb default '[]' (pdf_overlay: [{token, page, x, y, fontSize}])
|
||||
|
||||
document_templates.body_html — relax to nullable (only required when template_format='html')
|
||||
|
||||
document_watchers — new table:
|
||||
document_id text not null references documents(id) on delete cascade
|
||||
user_id text not null references users(id)
|
||||
added_by text not null references users(id)
|
||||
added_at timestamptz default now()
|
||||
primary key (document_id, user_id)
|
||||
|
||||
documents indexes — additions:
|
||||
+ idx_docs_reservation on (reservation_id)
|
||||
+ idx_docs_status_port on (port_id, status) — powers tab counts cheaply
|
||||
|
||||
document_watchers indexes:
|
||||
+ idx_doc_watchers_doc on (document_id)
|
||||
+ idx_doc_watchers_user on (user_id)
|
||||
|
||||
documents.documentType enum — already includes 'reservation_agreement'; no migration needed
|
||||
documents.status enum — already accepts 'expired'; no migration needed
|
||||
documentSigners.status enum — pending|signed|declined; no migration needed
|
||||
```
|
||||
|
||||
Backfill (one statement, safe to run in same migration):
|
||||
|
||||
```sql
|
||||
UPDATE document_templates SET reminder_cadence_days = 1 WHERE template_type = 'eoi';
|
||||
```
|
||||
|
||||
This preserves the existing 1-day-effective reminder cadence for existing EOI templates. Admins can edit per-template later.
|
||||
|
||||
After running migration on a dev/staging server, restart `next dev` to flush postgres.js prepared-statement cache (existing project convention).
|
||||
|
||||
### Polymorphic ownership pattern
|
||||
|
||||
Documents already use the multi-FK pattern (`interest_id`, `client_id`, `yacht_id`, `company_id` as separate nullable columns). Adding `reservation_id` matches this. No conversion to polymorphic discriminator columns despite yachts and invoices using that pattern; staying consistent with the existing documents shape avoids a destructive migration.
|
||||
|
||||
### Service-layer changes
|
||||
|
||||
- `documents.service.ts`:
|
||||
- `createFromWizard(portId, data, meta)` — dispatches across template/upload paths
|
||||
- `createFromUpload(portId, data, meta)` — new upload-driven path; calls Documenso `createDocument`, stores file in MinIO via `files` service, mirrors to `documents` + `documentSigners`, optionally calls `sendDocument` if `sendImmediately`
|
||||
- `cancelDocument(documentId, portId, meta)` — user-initiated cancel; calls Documenso void, updates DB status, logs event
|
||||
- `composeSignedDocEmail(documentId, portId)` — returns prefilled `{ to, cc, subject, body, attachments, defaultSenderType }` for the composer
|
||||
- `getDocumentDetail(id, portId)` — single-roundtrip aggregator returning doc + signers + events + watchers + linked-entity summary
|
||||
|
||||
- `document-templates.ts`:
|
||||
- `generateAndSign` extended for new `template_format` values
|
||||
- `fillAcroForm(sourceFile, fieldMapping, mergeContext)` — pdf-lib AcroForm fill
|
||||
- `drawOverlay(sourceFile, overlayPositions, mergeContext)` — pdf-lib text-draw at positions
|
||||
- Documenso-render path uses existing `generateDocumentFromTemplate`
|
||||
|
||||
- `documenso-client.ts`:
|
||||
- `placeFields(docId, fields, portId?)` — version-aware bulk field placement
|
||||
- `placeDefaultSignatureFields(docId, recipientIds, portId?)` — auto-position one SIGNATURE per recipient at footer
|
||||
- `voidDocument(docId, portId?)` — version-aware doc void/delete
|
||||
- Coordinate normalization helpers (caller passes percent 0-100; converted to pixels for v1 using cached page dimensions)
|
||||
|
||||
- `document-reminders.ts`:
|
||||
- `sendReminderIfAllowed(documentId, portId, options?)` — extended signature with optional `signerId` and `auto: boolean`
|
||||
- `processReminderQueue(portId)` — query rewritten around `documents.reminder_cadence_override ?? template.reminder_cadence_days`; drops `interests.reminderEnabled` gating
|
||||
|
||||
- `notifications.service.ts`:
|
||||
- `notifyDocumentEvent(docId, eventType)` — fans out to creator + entity-assignee + watchers; existing socket events keep firing
|
||||
|
||||
- New: `reservation-agreement-context.ts`:
|
||||
- `buildReservationAgreementContext(reservationId, portId)` — joins reservation -> client + yacht + berth -> port; returns context shape for template merge
|
||||
|
||||
- `email-compose.service.ts`:
|
||||
- Validator extended: `{ senderType: 'system'|'user', accountId? (when user), attachments[] }`
|
||||
- System path: calls `lib/email/index.ts → sendEmail()` with `portId` + attachments; logs `documentEvents` row `signed_doc_emailed`; skips `email_messages`/`email_threads` writes
|
||||
- User path: existing flow, with attachments resolution from `files` table
|
||||
- Port-isolation: cross-port `fileId` returns 403
|
||||
|
||||
- `lib/email/index.ts`:
|
||||
- `SendEmailOptions.attachments?: Array<{ fileId, filename? }>` — fetches files from MinIO, passes to nodemailer
|
||||
|
||||
## Documents hub page
|
||||
|
||||
Replaces existing `/[port]/documents` list.
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
[ Header strip: title, KPI sub-line, "+ New document" button ]
|
||||
|
||||
[ Tabs: All | Awaiting them (count) | Awaiting me (count) | Completed | Expired ]
|
||||
|
||||
[ Search · Type · Status · Sent · Watcher filter chips · saved-view selector · overflow ]
|
||||
|
||||
[ Table:
|
||||
checkbox | Document | Type pill | Subject pill | Status (X/Y signed + dot) | Sent
|
||||
▾ expand row inline to show signers + watchers strip
|
||||
]
|
||||
|
||||
[ Sticky bulk-action bar appears when ≥1 row checked:
|
||||
"N selected" | Remind unsigned | Cancel | Export | pagination
|
||||
]
|
||||
```
|
||||
|
||||
### Tab queries
|
||||
|
||||
- All — every document in port
|
||||
- Awaiting them — `status IN ('sent','partially_signed')` AND has pending signer != current user
|
||||
- Awaiting me — at least one `documentSigners` row matching `signer_email = current user email` AND `status = 'pending'`
|
||||
- Completed — `status IN ('completed','signed')`
|
||||
- Expired — `status = 'expired'` OR (`status IN ('sent','partially_signed')` AND `expires_at < now()`)
|
||||
|
||||
Counts run cheap thanks to `idx_docs_status_port`.
|
||||
|
||||
### Filters and saved views
|
||||
|
||||
- Search: fuzzy match on title, subject name, signer email
|
||||
- Type: multi-select doc types
|
||||
- Status: multi-select status enum
|
||||
- Sent: date-range chips (Today, 7d, 30d, custom)
|
||||
- Watcher: filter by watching user
|
||||
- "Signature-based only" chip defaults to ON; toggle off to see non-signed docs (welcome letters etc.) as well, rendered with a "Delivered" pill
|
||||
- Saved-view integration: filter combos save to existing `saved_views` table
|
||||
|
||||
### Row anatomy
|
||||
|
||||
- Collapsed: name (links to detail), type pill (colored per type), subject pill (links to entity), status indicator (X/Y signed with progress dot), sent age
|
||||
- Expanded: per-signer rows with email, status pill, sent timestamp, signed timestamp, `[Remind]` and overflow `[...]` (resend invite, copy signing link, skip — skip is UI-only flag, not implemented in v1)
|
||||
- Watchers strip at bottom of expansion: chips + `+ Add watcher` autocomplete
|
||||
- Hover: row gets soft brand-soft gradient bg
|
||||
|
||||
### Real-time
|
||||
|
||||
Subscribes to existing `documents.service.ts`-emitted socket events: `document:created`, `document:updated`, `document:deleted`, `document:sent`, `document:completed`, `document:expired`, `document:cancelled`, `document:rejected`, `document:signer:signed`, `document:signer:opened`. All already fire today.
|
||||
|
||||
### Empty states
|
||||
|
||||
- No docs yet: illustration + 1-line explanation + `[+ New document]` CTA
|
||||
- Filtered empty: "No docs match these filters. Clear filters?"
|
||||
|
||||
### Mobile (< 768px)
|
||||
|
||||
- Tabs collapse into `<select>`
|
||||
- Filters collapse behind `[Filters]` button into a sheet
|
||||
- Rows stack as cards: title + status + age, expand to show signers
|
||||
- "+ New document" floats as FAB bottom-right
|
||||
|
||||
## Document detail page
|
||||
|
||||
New `/[port]/documents/[id]` page. No detail page exists today.
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
[ Breadcrumb: All documents ]
|
||||
|
||||
[ Header strip with gradient: title (editable inline), type pill, status pill, subtitle (subject link, creator, age) ]
|
||||
|
||||
[ Action bar — context-aware ]
|
||||
|
||||
[ Two-column body:
|
||||
Left (2fr):
|
||||
Signers panel (vertical list, replaces existing horizontal SigningProgress)
|
||||
Linked entity card
|
||||
Right (1fr):
|
||||
Watchers panel (chips + add)
|
||||
Activity timeline (from documentEvents)
|
||||
Notes (auto-saving editable text)
|
||||
Preview (PDF; tabbed Original/Signed when completed)
|
||||
]
|
||||
```
|
||||
|
||||
### Action bar by status
|
||||
|
||||
- `draft` — `[Send for signing]` `[Edit signers]` `[Delete]`
|
||||
- `sent | partially_signed` — `[Send reminder to all]` `[Resend invite]` `[Cancel]`
|
||||
- `completed` — `[Download signed PDF]` `[Email signed PDF to all signatories]`
|
||||
- `cancelled | rejected | expired` — `[Duplicate]`
|
||||
- Always `[...]` overflow: Duplicate, Move to other entity, View Documenso URL, Audit log
|
||||
|
||||
### Signers panel (vertical, replaces horizontal stepper)
|
||||
|
||||
Per-row:
|
||||
|
||||
- Numbered status circle (pending grey, signed green, declined red)
|
||||
- Name, email, role
|
||||
- Sent age, last-reminded age, signed timestamp
|
||||
- `[Remind]` button — disabled with countdown if cooldown active (24h-or-cadence) for auto mode; bypassed in manual mode
|
||||
- `[Copy signing link]` — copies `signingUrl` (hosted Documenso); overflow offers "Copy embed link" if `embeddedUrl` present (used by website embed at `/sign/[type]/[token]`)
|
||||
- `[...]` overflow: Resend invite, View signing history, Replace email (draft only)
|
||||
- Sequential mode: only current pending signer's `[Remind]` active; others greyed with tooltip
|
||||
|
||||
### Send-signed-PDF email flow
|
||||
|
||||
Action visible only when `status='completed' AND signedFileId IS NOT NULL`.
|
||||
|
||||
Click opens email composer drawer prefilled:
|
||||
|
||||
- From: dropdown defaulting to System (port-config noreply identity); Personal accounts available only when port admin enables `email.allowPersonalAccountSends`
|
||||
- To: union of `documentSigners.signerEmail` for the doc
|
||||
- Cc: empty; "Cc watchers" toggle adds users from `document_watchers`
|
||||
- Subject: `"Signed {document type} — {document title}"`
|
||||
- Body: from `signed_doc_completion` per-port template (new template type; default seeded for new ports)
|
||||
- Attachments: signed PDF auto-attached from `documents.signedFileId` (chip with filename + size; removable)
|
||||
|
||||
Send dispatch:
|
||||
|
||||
- System path: `lib/email/index.ts → sendEmail()` with portId + attachments; writes `documentEvents` row; skips email_messages/threads writes (no IMAP sync expected)
|
||||
- User path: `email-compose.service.ts` existing flow; writes email_messages + thread; subject to `allowPersonalAccountSends` gate (server-side enforces 403 on user senderType when toggle off)
|
||||
|
||||
### Backend additions
|
||||
|
||||
- `POST /api/v1/documents/[id]/cancel` — calls `cancelDocument` service; service calls Documenso void via new client function
|
||||
- `POST /api/v1/documents/[id]/remind` — accepts optional `{ signerId }`; passes `auto: false` to service
|
||||
- `GET /api/v1/documents/[id]/watchers` — list
|
||||
- `POST /api/v1/documents/[id]/watchers` — add `{ userId }`
|
||||
- `DELETE /api/v1/documents/[id]/watchers/[userId]` — remove
|
||||
- `POST /api/v1/documents/[id]/compose-completion-email` — returns prefilled draft
|
||||
|
||||
## Create-document wizard
|
||||
|
||||
Replaces `<EoiGenerateDialog>`. Single drawer/dialog, three steps.
|
||||
|
||||
### Step 1 — Type and source
|
||||
|
||||
```
|
||||
Render: ● Generate the PDF here (using template format below)
|
||||
○ Use a Documenso-stored template (Documenso renders + signs)
|
||||
|
||||
Format (when "Generate the PDF here" selected):
|
||||
● HTML (write inline)
|
||||
○ PDF (AcroForm fillable upload)
|
||||
○ PDF (overlay positioning)
|
||||
|
||||
Template: [ pick from port's templates of selected format ]
|
||||
OR
|
||||
Upload PDF: [ drop or pick file; preview renders inline ]
|
||||
|
||||
Document type: [ auto-derived from template, or picked from DOCUMENT_TYPES enum ]
|
||||
```
|
||||
|
||||
Signing destination is always Documenso. The "Render in CRM" vs "Render in Documenso" axis is about PDF generation only.
|
||||
|
||||
### Step 2 — Recipients
|
||||
|
||||
```
|
||||
Attached to: [ Interest #142 — Smith family Change ]
|
||||
↑ pre-filled if launched from a detail page
|
||||
|
||||
Signers: (hidden for documenso-render path; signers embedded in template)
|
||||
① name email role [✕]
|
||||
② name email role [✕]
|
||||
[+ Add signer] (autocomplete from clients/companies/users; or manual entry)
|
||||
Drag to reorder; signing-order assigned by row position
|
||||
|
||||
Signing mode: ● Sequential ○ Parallel
|
||||
|
||||
Watchers (optional): [chips] [+ Add watcher] (CRM users)
|
||||
|
||||
Reminder cadence:
|
||||
● Use template default (every 7 days)
|
||||
○ Override: [_____] days
|
||||
○ Disable for this document
|
||||
|
||||
[ For upload path only ]
|
||||
☑ Auto-place signature fields at footer (default; refine later in Documenso)
|
||||
```
|
||||
|
||||
### Step 3 — Review and send
|
||||
|
||||
```
|
||||
Title: [ EOI — Smith family ____________ ] (editable; default rendered from merge tokens)
|
||||
Notes (internal): [_____________]
|
||||
Preview: [ rendered PDF inline · 4 pages · scrollable ]
|
||||
Signing-order banner (multi-signer in-app/upload only): "Sequential — Carol must sign before Bob" [Switch to parallel]
|
||||
[← Back] [Save as draft] [Send →]
|
||||
```
|
||||
|
||||
Save as draft → status='draft'; `[Send for signing]` available later from detail page. Send → calls Documenso, status='sent', socket event fires.
|
||||
|
||||
### Documenso version-aware field placement
|
||||
|
||||
For upload path, `placeDefaultSignatureFields` auto-positions one SIGNATURE per recipient at last-page footer (staggered to avoid overlap). User can refine in Documenso via "Customize fields in Documenso" link on detail page.
|
||||
|
||||
`placeFields` and `placeDefaultSignatureFields` in `documenso-client.ts` hide v1/v2 differences:
|
||||
|
||||
- v1: `POST /api/v1/documents/{id}/fields` per field; pixel coordinates; requires page dimension lookup
|
||||
- v2: `POST /api/v2/envelope/field/create-many` bulk; percentage 0-100 coordinates; rich `fieldMeta`
|
||||
- Caller passes percentage; abstraction converts for v1 using cached page dimensions
|
||||
|
||||
### `createDocumentSchema` extension
|
||||
|
||||
```ts
|
||||
export const createDocumentSchema = z.object({
|
||||
source: z.enum(['template', 'upload']),
|
||||
templateId: z.string().uuid().optional(),
|
||||
uploadedFileId: z.string().uuid().optional(),
|
||||
|
||||
documentType: z.enum(DOCUMENT_TYPES),
|
||||
title: z.string().min(1).max(200),
|
||||
notes: z.string().optional(),
|
||||
|
||||
// Subject (exactly one required)
|
||||
interestId: z.string().uuid().optional(),
|
||||
reservationId: z.string().uuid().optional(),
|
||||
clientId: z.string().uuid().optional(),
|
||||
companyId: z.string().uuid().optional(),
|
||||
yachtId: z.string().uuid().optional(),
|
||||
|
||||
// Signers (required when render=in-app or source=upload)
|
||||
signers: z.array(z.object({
|
||||
signerName: z.string().min(1),
|
||||
signerEmail: z.string().email(),
|
||||
signerRole: z.enum(['client', 'sales', 'approver', 'developer', 'other']),
|
||||
signingOrder: z.number().int().min(1),
|
||||
})).optional(),
|
||||
signingMode: z.enum(['sequential', 'parallel']).default('sequential'),
|
||||
|
||||
pathway: z.enum(['documenso-template', 'inapp', 'upload']).optional(),
|
||||
|
||||
watchers: z.array(z.string().uuid()).optional(),
|
||||
|
||||
reminderCadenceOverride: z.number().int().min(1).max(365).nullable().optional(),
|
||||
remindersDisabled: z.boolean().default(false),
|
||||
|
||||
autoPlaceFields: z.boolean().default(true),
|
||||
|
||||
sendImmediately: z.boolean().default(true),
|
||||
}).refine(...one-subject-FK-required...);
|
||||
```
|
||||
|
||||
## Template formats
|
||||
|
||||
### Authoring paths
|
||||
|
||||
| Format | Authoring | Merge fields | Best for |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
|
||||
| HTML (existing) | Inline rich-text editor with merge tokens | Server-side substitution, rendered to PDF via pdfme | Welcome letters, acknowledgments, correspondence |
|
||||
| PDF (AcroForm fillable) | Admin uploads fillable PDF; UI scans AcroForm field names; admin maps each to a merge token | pdf-lib fills form at gen time | EOI, Reservation Agreement, NDA |
|
||||
| PDF (overlay positioning) | Admin uploads any PDF; UI specifies merge token positions per page+x+y+fontSize | pdf-lib draws text over PDF at positions | Quick wins where preparing AcroForm is overkill |
|
||||
| Documenso template reference | Admin enters Documenso template ID + label | None in CRM; Documenso owns it | Documenso-rendered signing flows |
|
||||
|
||||
### Generator dispatch
|
||||
|
||||
```ts
|
||||
switch (template.template_format) {
|
||||
case 'html': generatePdf(template.body_html, mergeContext);
|
||||
case 'pdf_form': fillAcroForm(template.source_file_id, template.field_mapping, mergeContext);
|
||||
case 'pdf_overlay': drawOverlay(template.source_file_id, template.overlay_positions, mergeContext);
|
||||
case 'documenso_render': documenso.generateDocumentFromTemplate(template.documenso_template_id, ...);
|
||||
}
|
||||
```
|
||||
|
||||
All four formats end at Documenso for signing — only PDF generation location differs. Non-signature templates (welcome letters etc.) skip the upload-to-Documenso step entirely; they render to PDF then get emailed.
|
||||
|
||||
### Admin template editor extension
|
||||
|
||||
Format picker added to `/admin/templates` editor:
|
||||
|
||||
- For PDF (AcroForm): file upload field, then two-column mapping UI (AcroForm field names ↔ merge tokens autocomplete from existing `MERGE_FIELDS` catalog)
|
||||
- For PDF (overlay): file upload, then per-token form with page/x/y/fontSize inputs (visual placement editor deferred)
|
||||
- For Documenso template: single text input + Test connection button calling `getDocumensoTemplate`
|
||||
- For HTML: existing inline editor unchanged
|
||||
|
||||
### Word (.docx) deferred
|
||||
|
||||
Reasons: LibreOffice headless adds significant install/memory/security surface; CloudConvert adds paid dependency and third-party data exposure; `docxtemplater` merge syntax incompatible with existing `{{token}}` convention; field placement still needs PDF flow afterwards. If marinas push back, the feasible path is `.docx → server-side conversion → PDF → existing AcroForm/overlay flow`. Not worth the engineering until requested.
|
||||
|
||||
## Reservation agreements as a doc type
|
||||
|
||||
### What differs from EOI's pattern
|
||||
|
||||
| Aspect | EOI | Reservation Agreement |
|
||||
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| Subject FK | `interestId` | `reservationId` |
|
||||
| Default template | Documenso EOI per port | Documenso reservation_agreement per port (seeded) |
|
||||
| Default signers | client + sales/approver | client + port admin |
|
||||
| Trigger | Manual on interest detail | Manual on reservation detail |
|
||||
| Lifecycle integration | None | Active reservations without an agreement get flagged in dashboard alert |
|
||||
| Final-PDF storage | `documents.signedFileId` only | `documents.signedFileId` AND mirrored to `berth_reservations.contractFileId` on completion |
|
||||
|
||||
### New CRM-side reservation detail page
|
||||
|
||||
`/[port]/berth-reservations/[id]` doesn't exist today (only the portal's `/portal/my-reservations`). Phase A builds it.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
[ Header: "Reservation #88 · M/Y Tate" status pill subtitle: berth, client, dates, tenure ]
|
||||
[ Action bar: Activate | Generate agreement | Cancel | ... ]
|
||||
[ Two columns:
|
||||
Left: Reservation details card
|
||||
Linked interest card
|
||||
Activity timeline
|
||||
Right: Agreement card (state-dependent: no agreement / in-flight / completed)
|
||||
]
|
||||
```
|
||||
|
||||
Agreement card states:
|
||||
|
||||
- No agreement yet: warning + `[Generate agreement →]`
|
||||
- In-flight (sent/partially_signed): "X/Y signed", per-signer status, `[View document →]` `[Send reminder]` `[Cancel]`
|
||||
- Completed: "Completed YYYY-MM-DD", `[Download signed PDF]` `[Email to all signatories]`, "Signed contract attached to reservation."
|
||||
|
||||
Generate-agreement button launches the wizard with prefills:
|
||||
|
||||
- `documentType='reservation_agreement'`
|
||||
- `templateId=<port's default>`
|
||||
- `reservationId=<current>`
|
||||
- Default signers from linked client + configurable port-admin user
|
||||
- Wizard step 1 pre-validated; user lands on step 2
|
||||
|
||||
### Backend additions
|
||||
|
||||
- Merge field catalog extended in `src/lib/templates/merge-fields.ts`:
|
||||
- `{{reservation.startDate}}` `{{reservation.endDate}}` `{{reservation.tenureType}}` `{{reservation.termSummary}}` `{{reservation.signedDate}}`
|
||||
- New service `reservation-agreement-context.ts.buildReservationAgreementContext(reservationId, portId)`
|
||||
- New seeder for default `reservation_agreement` template on port creation (HTML format; admins can switch to AcroForm/overlay later); template stored at `assets/templates/reservation-agreement-default.html`
|
||||
- Webhook handler extension: `handleDocumentCompleted` detects `documentType='reservation_agreement'` and sets `berth_reservations.contractFileId = doc.signedFileId` for the linked reservation
|
||||
- Dashboard alert query: active reservations without a completed agreement (LEFT JOIN against documents filtered on type+status); rows surface as a warning card
|
||||
|
||||
### Trade-off
|
||||
|
||||
`berth_reservations.contractFileId` becomes a denormalized convenience pointer duplicated with `documents.signedFileId` for the linked reservation. Updating it on completion costs one extra UPDATE. Benefit: anyone querying reservations directly (portal "My Reservations") doesn't need to join through documents to know which file is the contract.
|
||||
|
||||
## Reminder framework polish
|
||||
|
||||
### Problems with today's logic
|
||||
|
||||
1. Eligibility gated by `interests.reminderEnabled` — reservation agreements, NDAs, ad-hoc upload docs (no interest link) never auto-remind
|
||||
2. Hardcoded 24h cooldown — effective cadence is 1 day; can't slow down for low-urgency docs
|
||||
3. Always reminds lowest-pending signer — parallel-signing docs can't nudge a specific signer
|
||||
4. No per-doc disable
|
||||
|
||||
### New eligibility logic
|
||||
|
||||
```
|
||||
function isReminderDue(doc, template, lastReminderAt) {
|
||||
if (!['sent','partially_signed'].includes(doc.status)) return false;
|
||||
if (doc.documenso_id == null) return false;
|
||||
if (doc.reminders_disabled) return false;
|
||||
|
||||
const effectiveCadence = doc.reminder_cadence_override ?? template.reminder_cadence_days;
|
||||
if (effectiveCadence === null) return false;
|
||||
|
||||
if (lastReminderAt == null) return true;
|
||||
return (now - lastReminderAt) >= effectiveCadence * 24h;
|
||||
}
|
||||
```
|
||||
|
||||
`processReminderQueue` query rewritten:
|
||||
|
||||
```sql
|
||||
SELECT d.* FROM documents d
|
||||
LEFT JOIN document_templates t ON t.id = d.template_id
|
||||
WHERE d.port_id = $1
|
||||
AND d.status IN ('sent','partially_signed')
|
||||
AND d.documenso_id IS NOT NULL
|
||||
AND d.reminders_disabled = false
|
||||
AND COALESCE(d.reminder_cadence_override, t.reminder_cadence_days) IS NOT NULL;
|
||||
```
|
||||
|
||||
`interests.reminderEnabled` is dropped from the gating logic but the column stays for now (no migration). Future cleanup PR can drop the column.
|
||||
|
||||
### `sendReminderIfAllowed` extended signature
|
||||
|
||||
```ts
|
||||
export async function sendReminderIfAllowed(
|
||||
documentId: string,
|
||||
portId: string,
|
||||
options: {
|
||||
auto?: boolean; // true = cron; false (default) = manual
|
||||
signerId?: string; // optional — target a specific pending signer
|
||||
} = {},
|
||||
): Promise<{ sent: boolean; reason?: string; signerId?: string }>;
|
||||
```
|
||||
|
||||
Behaviour matrix:
|
||||
|
||||
| Mode | 9-16 window | Cadence cooldown | Manual cooldown |
|
||||
| ----------- | ----------- | ---------------- | ------------------------ |
|
||||
| auto: true | enforced | enforced | n/a |
|
||||
| auto: false | bypassed | bypassed | 30s client-side debounce |
|
||||
|
||||
Per-signer logic:
|
||||
|
||||
- If `signerId` provided in sequential-mode doc, signer must be the lowest-pending signer (otherwise reason='Signer is not next in sequence')
|
||||
- In parallel-mode doc, any pending signer can be reminded independently
|
||||
- Returns `{ sent, reason }` so caller can show toast on skip
|
||||
|
||||
### Admin and per-doc UI
|
||||
|
||||
Admin `/admin/templates` editor:
|
||||
|
||||
```
|
||||
Auto-reminders for this template:
|
||||
☑ Enabled Cadence: every [_____] days (1-365; default 7)
|
||||
☐ Disabled (manual reminders only)
|
||||
```
|
||||
|
||||
Doc detail page (Section 3) "Reminders" panel under signers, with edit drawer for per-doc override.
|
||||
|
||||
## Visual polish system
|
||||
|
||||
### Token additions
|
||||
|
||||
```
|
||||
--radius-sm: 0.375rem (existing)
|
||||
--radius-md: 0.5rem (NEW — default cards)
|
||||
--radius-lg: 0.625rem (NEW — sheets, dialogs)
|
||||
--radius-xl: 0.875rem (NEW — KPI tiles, hero strips)
|
||||
|
||||
--shadow-xs: 0 1px 2px 0 rgb(15 23 42 / 0.04)
|
||||
--shadow-sm: 0 2px 4px -1px rgb(15 23 42 / 0.06)
|
||||
--shadow-md: 0 4px 12px -2px rgb(15 23 42 / 0.08)
|
||||
--shadow-lg: 0 12px 32px -8px rgb(15 23 42 / 0.12)
|
||||
--shadow-glow: 0 0 0 4px rgb(58 123 200 / 0.12)
|
||||
|
||||
--gradient-brand: linear-gradient(135deg, #3a7bc8 0%, #2f6ab5 100%)
|
||||
--gradient-brand-soft: linear-gradient(135deg, #d8e5f4 0%, #ffffff 100%)
|
||||
--gradient-success: linear-gradient(135deg, #e8f5e9 0%, #ffffff 100%)
|
||||
--gradient-warning: linear-gradient(135deg, #fef3c7 0%, #ffffff 100%)
|
||||
|
||||
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1)
|
||||
--ease-smooth: cubic-bezier(0.4, 0, 0.2, 1)
|
||||
--duration-fast: 150ms
|
||||
--duration-base: 200ms
|
||||
--duration-slow: 300ms
|
||||
```
|
||||
|
||||
All exposed as Tailwind utilities.
|
||||
|
||||
### Existing token foundation (already in place; not changing)
|
||||
|
||||
- Full HSL shadcn token system (primary, secondary, muted, accent, destructive, border, input, ring, popover, card)
|
||||
- Brand palette `brand` (50-700, default `#3a7bc8`)
|
||||
- Navy palette `navy` (50-600, default `#1e2844` for sidebar)
|
||||
- Maritime accents: `sage`, `mint`, `teal`, `purple` with light/default/dark variants
|
||||
- Semantic `success` / `warning` with bg+border
|
||||
- Recharts chart-1 through chart-6 token system
|
||||
- Dark mode wired
|
||||
- Sidebar tokens separate from main palette
|
||||
|
||||
### New primitive components
|
||||
|
||||
- `<StatusPill status="...">` — colored-by-state pill (pending grey, sent brand, partial teal, completed success, expired warning, rejected destructive, cancelled muted-darker, active success, archived muted)
|
||||
- `<KPITile title value delta sparkline?>` — rounded-xl, shadow-sm, gradient-brand-soft border-top accent stripe; recharts mini sparkline using `--chart-1`
|
||||
- `<EmptyState icon title body actions>` — large icon in brand-soft circle, title, body, action buttons
|
||||
- `<PageHeader>` polished — gradient-brand-soft background, eyebrow optional, KPI sub-line, primary action right-aligned
|
||||
|
||||
### Component pattern updates
|
||||
|
||||
- List rows: hover gradient (subtle brand-soft 4% opacity), shadow-xs lift, animation `transition-all duration-base ease-smooth`; row-update from socket events animates 1s fade-in highlight
|
||||
- Detail pages: two-column responsive grammar (header strip → 2fr main + 1fr side; cards stack vertical < 768px)
|
||||
- Sidebar (already dark navy): active item gets 4px brand left-edge stripe instead of bg shift; section headers smaller-caps + brand-200 text
|
||||
- Topbar: search inset shadow + brand focus ring; "+ New" trigger gets `bg-gradient-brand`; notification bell gets badge spring animation; user avatar gets shadow-sm + 2px white ring
|
||||
- Forms: focus ring uses `--shadow-glow`; primary submit buttons get `bg-gradient-brand` with hover scale-1.01; inline validation gets destructive-bg pill with caret pointing up
|
||||
|
||||
### Loading skeleton system
|
||||
|
||||
- List pages: 8 skeleton rows matching column widths with subtle pulse
|
||||
- Detail pages: header strip skeleton + 2-column section skeletons
|
||||
- Dashboard: KPI tile skeletons + chart skeletons
|
||||
- Replaces today's mix of "Loading..." text and spinners
|
||||
|
||||
### Mobile responsive (full sweep)
|
||||
|
||||
Breakpoints:
|
||||
|
||||
- < 640px (phone): single column, sticky bottom action bar, sheet overlays for filters
|
||||
- 640-1024px (tablet): single column with wider gutters, side column under main
|
||||
- ≥ 1024px (desktop): full two-column
|
||||
|
||||
Per-page rules:
|
||||
|
||||
- List tables → card stack < 768px
|
||||
- Detail page header collapses subtitle to "Show more"
|
||||
- Tabs collapse to `<select>` < 640px
|
||||
- Sidebar slides over content < 1024px
|
||||
- Primary "+ New" actions float as FAB bottom-right < 640px
|
||||
|
||||
## Test plan
|
||||
|
||||
### Unit (`tests/unit/`)
|
||||
|
||||
- `document-reminders-cadence.test.ts` — `isReminderDue` math; manual-vs-auto window/cooldown bypass
|
||||
- `documenso-place-fields.test.ts` — v1/v2 dispatch (mocked HTTP); coord normalization; default field staggering for 1/2/3/5 recipients
|
||||
- `email-attachments-resolver.test.ts` — fileId → MinIO buffer; cross-port 403; 10 MB cap warning
|
||||
|
||||
### Integration (`tests/integration/`)
|
||||
|
||||
- Extend `document-templates-generate-and-sign.test.ts` — new template formats (`pdf_form`, `pdf_overlay`, `documenso_render`); upload-path test
|
||||
- New `document-watchers.test.ts` — add/remove endpoints; notification fan-out; port isolation
|
||||
- New `document-cancel.test.ts` — user-initiated cancel; mocked Documenso void; status + event log; reject 409 if completed
|
||||
- New `reservation-agreement-contract-mirror.test.ts` — `handleDocumentCompleted` mirrors `signedFileId` to `berth_reservations.contractFileId` only for `reservation_agreement` type
|
||||
- New `reminder-cron-cadence.test.ts` — seed varied templates; simulated time advance; assert correct docs reminded
|
||||
|
||||
### E2E smoke (`tests/e2e/smoke/`)
|
||||
|
||||
- Extend `04-documents.spec.ts` — hub tabs, expand row, per-signer remind with cooldown, type/status filters, saved-view round-trip, bulk-remind with per-row toast reasons
|
||||
- Extend `05-eoi-generate.spec.ts` — wizard invocation prefills (template, interest); existing flow regression
|
||||
- New `27-document-create-wizard.spec.ts` — template path full flow; upload path full flow; watcher addition; reminder-override radios produce correct DB state
|
||||
- New `28-reservation-agreements.spec.ts` — reservation detail → Generate agreement → wizard prefilled → Send → agreement section state transitions; post-completion contract attached + email button visible
|
||||
- New `29-email-attachments.spec.ts` — system path send (documentEvents row, no email_messages); user path send when toggle on (email_messages with attachment_file_ids); cross-port 403
|
||||
|
||||
### E2E exhaustive (`tests/e2e/exhaustive/`) — click-everything sweep
|
||||
|
||||
- New `10-documents-hub.spec.ts` — crawl each tab, filter dropdowns, saved-view, expand row, signer-row buttons, bulk-action bar
|
||||
- New `11-document-detail.spec.ts` — crawl in three states (draft/sent/completed); watcher add/remove; notes auto-save; preview download; "Email signed PDF" launch
|
||||
- New `12-document-create-wizard.spec.ts` — crawl each wizard step under both template and upload paths; picker dropdowns, signer add/remove, drag-handle, reminder-cadence radios
|
||||
- New `13-reservation-detail.spec.ts` — crawl in three states (pending no agreement / agreement-in-flight / agreement-completed); Activate/Cancel/Generate buttons; inline notes
|
||||
- New `14-email-composer.spec.ts` — crawl composer drawer with attachments; From dropdown; attach button; recipient chips
|
||||
- Extend exhaustive `05-eoi-generate.spec.ts` — parallel-mode + signing-order edge cases (greyed-out reminder buttons; out-of-order remind rejection)
|
||||
|
||||
### E2E real-API (`tests/e2e/realapi/`)
|
||||
|
||||
Each spec gates on env vars; clean skip if missing.
|
||||
|
||||
- Extend `documenso-real-api.spec.ts`:
|
||||
- Generate from Documenso template (real send) and assert in real Documenso
|
||||
- Generate from in-app PDF AcroForm fill, upload to real Documenso, assert
|
||||
- Generate from upload path with auto-placed signature fields, assert fields visible in Documenso
|
||||
- v1 and v2 explicit version-flag tests (via `DOCUMENSO_API_VERSION`)
|
||||
- Manually sign in real Documenso (or simulate webhook) and assert local DB updates
|
||||
- Cancel real in-flight doc, assert local + remote state
|
||||
- Send reminder via real Documenso, assert HTTP + documentEvents row
|
||||
|
||||
- New `smtp-system-send.spec.ts` — system-path send → IMAP fetch → assert subject + attachment; verify port-config from-identity; cleanup via IMAP delete
|
||||
- New `smtp-user-send.spec.ts` — user-path send (requires connected account, allowPersonalAccountSends=true) → IMAP fetch → email_messages row with attachment_file_ids
|
||||
- New `minio-file-lifecycle.spec.ts` — upload, list, preview, download (byte-equal), delete; port isolation; mime-type validation
|
||||
- New `documenso-webhook-ingress.spec.ts` — requires cloudflared tunnel; configure tunnel URL as Documenso webhook target; trigger doc completion; assert webhook fires + handler updates DB; verify timing-safe secret check rejects wrong secret with 401; verify event normalisation (uppercase enum + lowercase-dotted both accepted)
|
||||
- New `email-attachments-roundtrip.spec.ts` — compose with fileId attachment; SMTP send; IMAP fetch; assert attachment bytes match; reject cross-port fileId with 403 before SMTP touched
|
||||
|
||||
### Visual baselines (`tests/e2e/visual/`)
|
||||
|
||||
`snapshots.spec.ts-snapshots/` regenerated as polish ships per page; one PR per surface group, baselines reviewed in PR diff. New baselines added: documents hub, doc detail, create-document wizard (each step), reservation detail, email composer with attachments.
|
||||
|
||||
### Test data fixtures
|
||||
|
||||
`global-setup.ts` extended with:
|
||||
|
||||
- Seed default `reservation_agreement` template (HTML format)
|
||||
- Seed default `signed_doc_completion` template
|
||||
- Seed one in-flight EOI doc with two pending signers (for hub-tab tests)
|
||||
- Seed one `berth_reservation` with `status='active'` and no agreement (for lifecycle alert query)
|
||||
|
||||
### CI vs local runs
|
||||
|
||||
| Project | When |
|
||||
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| `setup` + `smoke` (~14 min) | Every PR via CI |
|
||||
| `exhaustive` (with new click-everything specs) | Every PR via CI; ~25 min budget |
|
||||
| `visual` | Every PR; baselines reviewed in PR diffs |
|
||||
| `realapi` | Locally before merging touch-points; pre-release; not on CI (avoids burning Documenso quota and SMTP costs) |
|
||||
|
||||
## Build sequence
|
||||
|
||||
| # | Title | Effort | Depends on |
|
||||
| ----- | ------------------------------------------------- | ------ | -------------- |
|
||||
| 1 | Data model + service skeletons | 1d | — |
|
||||
| 2 | Documenso v1/v2 abstraction layer | 1d | — |
|
||||
| 3 | Visual primitives + token additions | 1.5d | — |
|
||||
| 4 | Documents hub page | 2d | 1, 3 |
|
||||
| 5 | Document detail page | 2d | 1, 3 |
|
||||
| 6 | Create-document wizard + new template formats | 2.5d | 1, 2, 3 |
|
||||
| 7 | Reservation detail + agreement flow | 1.5d | 1, 6 |
|
||||
| 8 | Email composer attachments + From selector | 1d | 1, 3 |
|
||||
| 9 | Reminder framework polish | 1d | 1 |
|
||||
| 10a-e | Visual polish sweep (5 PRs across surface groups) | 3-4d | 3 |
|
||||
| 11 | Real-API integration tests | 1.5d | 2, 4-9 shipped |
|
||||
|
||||
### Critical path
|
||||
|
||||
```
|
||||
1 → 2 → 6 → 7 (data model → Documenso → wizard → reservation)
|
||||
1 → 3 → 4 → 5 → 9 (data model → primitives → hub → detail → reminders)
|
||||
1 → 8 (composer)
|
||||
3 → 10a-e (sweep)
|
||||
all → 11 (realapi)
|
||||
```
|
||||
|
||||
Wall-clock minimum ~9 days; realistic with overhead ~17 days; calendar ~3.5-5 weeks.
|
||||
|
||||
### Acceptance gates per PR
|
||||
|
||||
- `pnpm tsc --noEmit` and `pnpm lint` clean
|
||||
- Vitest unit + integration green
|
||||
- Playwright smoke green for surface touched
|
||||
- Visual baselines regenerated and reviewed in PR diff
|
||||
- For PRs touching external integrations (2, 6 upload, 7 contract mirror, 8 SMTP, 11): relevant `realapi` spec verified locally before merge
|
||||
|
||||
### Risk register
|
||||
|
||||
| Risk | Mitigation |
|
||||
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| Documenso v2 endpoint shape drifts from docs | PR2 validates against real v2 instance during dev; realapi spec re-runs nightly post-ship |
|
||||
| Visual polish scope creeps | One PR per surface group (10a-e), each independently shippable |
|
||||
| Cron migration changes effective behaviour | Backfill sets EOI cadence to 1 day matching today's effective; run on staging first |
|
||||
| Mobile responsive regressions | Visual baselines include phone-viewport snapshots; PR10e is the responsive sweep |
|
||||
| EOI dialog → wizard migration breaks "Generate EOI" button | Wizard launched with prefills from interest detail; PR6 includes regression spec |
|
||||
| AcroForm template format confuses non-technical admins | HTML default; inline help; default templates seeded |
|
||||
| Phase A wall-clock past 5 weeks | Tier-2 sweep items + optional realapi specs deferrable to follow-up release |
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Documenso** — open-source document signing service, self-hosted instance at `signatures.portnimara.dev`
|
||||
- **EOI** — Expression of Interest, a pre-reservation signed document
|
||||
- **Reservation Agreement** — contract signed when a berth reservation is committed
|
||||
- **Hub** — the new `/[port]/documents` page
|
||||
- **Watcher** — a CRM user added to a doc to receive notifications on signature events without being a signer themselves
|
||||
- **Signing order** — sequential index across signers; sequential mode requires lower order to sign first; parallel mode lets all sign concurrently
|
||||
- **Cadence** — interval in days between auto-reminders to unsigned signers
|
||||
- **System send / User send** — email dispatch identity: System uses port-config noreply SMTP; User uses connected personal email account (gated by admin toggle)
|
||||
- **Render location** — where the PDF is generated (CRM-local via HTML/AcroForm/overlay, or in Documenso). Signing is always Documenso; render location is independent.
|
||||
Reference in New Issue
Block a user