docs(spec): add data-model refactor design (Spec 1 of 3)
Introduces yachts and companies as first-class entities with memberships, ownership history, berth reservations, and dual-path EOI templates. Explicit non-goals (importer, merge endpoint) carved out as Specs 2 and 3. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Ciaccio
663
docs/superpowers/specs/2026-04-23-data-model-refactor-design.md
Normal file
663
docs/superpowers/specs/2026-04-23-data-model-refactor-design.md
Normal file
@@ -0,0 +1,663 @@
|
||||
# Data-Model Refactor: Yachts and Companies as First-Class Entities
|
||||
|
||||
**Status:** Draft — awaiting final review
|
||||
**Date:** 2026-04-23
|
||||
**Spec position:** 1 of 3 (Spec 2 = NocoDB+MinIO importer; Spec 3 = client merge endpoint)
|
||||
|
||||
## Overview
|
||||
|
||||
This spec delivers a refactor of the core client / yacht / company data model to support real-world ownership relationships that the current schema cannot express.
|
||||
|
||||
The current `clients` table holds yacht dimensions and company name as columns directly on the person row. This enforces a one-person = one-yacht = one-company assumption that breaks the moment:
|
||||
|
||||
- A client owns multiple yachts (a common marina scenario)
|
||||
- A person is a broker or director of multiple companies
|
||||
- A yacht is legally owned by a shell company (common for tax / liability reasons) rather than by the human on the dock
|
||||
- A yacht changes hands between owners and the marina needs chain-of-title
|
||||
|
||||
The refactor pulls yacht and company data into their own first-class tables, adds join tables for person↔company memberships, and introduces a proper `berth_reservations` table for exclusive-reservation lifecycle tracking.
|
||||
|
||||
This spec also fixes two existing schema gaps that surface during the refactor:
|
||||
|
||||
- `berths.status` tracks the state of a berth but there is no table recording which client/yacht exclusively reserves a berth
|
||||
- `invoices.clientName` is a text field with no FK — there's no first-class link between invoices and billing entities
|
||||
|
||||
## Scope boundaries
|
||||
|
||||
### In scope (this spec)
|
||||
|
||||
- New `yachts`, `yacht_ownership_history`, `yacht_notes`, `yacht_tags` tables
|
||||
- New `companies`, `company_memberships`, `company_addresses`, `company_notes`, `company_tags` tables
|
||||
- New `berth_reservations` table with partial-unique-index exclusivity enforcement
|
||||
- Updates to `interests`, `berth_waiting_list`, `invoices`, `files`, `documents` to add FKs to the new entities
|
||||
- Removal of yacht, company, and proxy columns from `clients`
|
||||
- New services, API routes, permissions, and socket/webhook events
|
||||
- New UI pages for yachts, companies, and berth reservations; modifications to client, interest, berth, invoice forms
|
||||
- Dual-path EOI generation (Documenso + in-app PDF template) with a shared payload builder
|
||||
- Comprehensive test coverage: unit, integration, E2E, exhaustive click-through, template regression
|
||||
- Seeder with realistic multi-cardinality dummy data
|
||||
|
||||
### Explicitly out of scope
|
||||
|
||||
- **Importing NocoDB records and MinIO documents** → Spec 2
|
||||
- **Client merge endpoint** → Spec 3
|
||||
- Yacht survey / class-cert document categorization
|
||||
- Company hierarchy (holding → subsidiary)
|
||||
- Line-item-level yacht references on invoices
|
||||
- Auto-renewal flow for berth reservations
|
||||
- Per-yacht row-level permissions
|
||||
- Portal branding per company
|
||||
|
||||
## Decisions and rationale
|
||||
|
||||
| Topic | Decision | Why |
|
||||
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Yacht scope | Full entity: own page, documents, ownership history, yacht-keyed interests / reservations / invoices | Marina domain cares about yachts as first-class objects (dimensions for berth fit, registration for port entry, ownership for liability) |
|
||||
| Company scope | Full entity: memberships join, company-owned yachts, company billing | Yachts are frequently owned by shell companies for tax/liability reasons — the human on the dock is a director or broker. Lightweight/medium models can't route invoices to the correct legal entity |
|
||||
| Ownership history | Dedicated `yacht_ownership_history` table + denormalized current-owner columns on `yachts` | Ownership change is exactly the kind of event that needs queryable history (chain of title, insurance, broker commission attribution). Denormalized current-owner keeps common reads fast |
|
||||
| Proxy fields on clients (`isProxy`, `proxyType`, `actualOwnerName`, `relationshipNotes`) | Drop all four | Every real proxy scenario is expressible through `company_memberships` roles or `client_relationships`. Keeping the old fields creates two sources of truth and drift risk |
|
||||
| Berth exclusive reservation | New `berth_reservations` table with partial unique index `WHERE status = 'active'` | Current schema tracks berth state via `berths.status` but does not record which client/yacht holds the reservation. Partial unique index enforces exclusivity at the DB level |
|
||||
| Invoice billing entity | `billingEntityType` (`'client' \| 'company'`) + `billingEntityId`; `clientName` retained as an immutable snapshot | Companies become first-class payers. `clientName` as text is preserved on the invoice as a snapshot so invoices never retroactively rename themselves |
|
||||
| Data state | Green-field with dummy seeder; real data arrives via Spec 2 | No production data lives in this Postgres DB yet. NocoDB holds the real records until Spec 2 imports them |
|
||||
| Delivery | One cohesive spec covering both yacht + company refactor | Splitting doubles the migration/UI/test churn for no architectural gain; both sets of changes overlap heavily |
|
||||
| EOI template strategy | Support both Documenso-template path and in-app PDF template path, both fully functional from day one | Handoff risk: client must not come back claiming "EOIs don't work." If Documenso breaks or is replaced, in-app path is the fallback. Both consume the same payload builder for data consistency |
|
||||
| EOI UI picker | Dropdown at generation time (user picks Documenso or in-app explicitly) | Explicit beats automatic fallback for handoff — misconfiguration is visible, not silently masked |
|
||||
| Testing | Unit, integration, full E2E scenarios, exhaustive Playwright click-through, template regression (including visual diff) | Explicit "test thoroughly" direction plus the handoff concern justify going heavier than normal on integration + E2E tiers |
|
||||
|
||||
## Schema design
|
||||
|
||||
### New tables
|
||||
|
||||
```
|
||||
yachts
|
||||
id text PK
|
||||
portId text NOT NULL FK → ports.id
|
||||
name text NOT NULL
|
||||
hullNumber text
|
||||
registration text
|
||||
flag text
|
||||
yearBuilt integer
|
||||
builder text
|
||||
model text
|
||||
hullMaterial text
|
||||
lengthFt numeric
|
||||
widthFt numeric
|
||||
draftFt numeric
|
||||
lengthM numeric
|
||||
widthM numeric
|
||||
draftM numeric
|
||||
currentOwnerType text NOT NULL -- 'client' | 'company'
|
||||
currentOwnerId text NOT NULL
|
||||
status text NOT NULL DEFAULT 'active' -- 'active' | 'retired' | 'sold_away'
|
||||
notes text
|
||||
archivedAt timestamptz
|
||||
createdAt timestamptz NOT NULL DEFAULT now()
|
||||
updatedAt timestamptz NOT NULL DEFAULT now()
|
||||
Indexes:
|
||||
idx_yachts_port on (portId)
|
||||
idx_yachts_current_owner on (portId, currentOwnerType, currentOwnerId)
|
||||
idx_yachts_name on (portId, name)
|
||||
|
||||
yacht_ownership_history
|
||||
id text PK
|
||||
yachtId text NOT NULL FK → yachts.id ON DELETE CASCADE
|
||||
ownerType text NOT NULL -- 'client' | 'company'
|
||||
ownerId text NOT NULL
|
||||
startDate date NOT NULL
|
||||
endDate date -- NULL = currently active
|
||||
transferReason text -- 'sale' | 'inheritance' | 'gift' | 'company_restructure' | 'other'
|
||||
transferNotes text
|
||||
createdBy text NOT NULL
|
||||
createdAt timestamptz NOT NULL DEFAULT now()
|
||||
Indexes:
|
||||
idx_yoh_yacht on (yachtId)
|
||||
idx_yoh_active (partial) on (yachtId) WHERE endDate IS NULL
|
||||
|
||||
yacht_notes -- mirrors client_notes shape
|
||||
id, yachtId (FK CASCADE), authorId, content, mentions text[], isLocked, createdAt, updatedAt
|
||||
|
||||
yacht_tags
|
||||
yachtId, tagId composite PK; tagId references system.tags.id
|
||||
|
||||
companies
|
||||
id text PK
|
||||
portId text NOT NULL FK → ports.id
|
||||
name text NOT NULL
|
||||
legalName text
|
||||
taxId text
|
||||
registrationNumber text
|
||||
incorporationCountry text
|
||||
incorporationDate date
|
||||
status text NOT NULL DEFAULT 'active' -- 'active' | 'dissolved'
|
||||
billingEmail text
|
||||
notes text
|
||||
archivedAt timestamptz
|
||||
createdAt timestamptz NOT NULL DEFAULT now()
|
||||
updatedAt timestamptz NOT NULL DEFAULT now()
|
||||
Indexes:
|
||||
idx_companies_port on (portId)
|
||||
idx_companies_name_unique UNIQUE on (portId, lower(name)) -- case-insensitive
|
||||
idx_companies_taxid on (portId, taxId) WHERE taxId IS NOT NULL
|
||||
|
||||
company_memberships
|
||||
id text PK
|
||||
companyId text NOT NULL FK → companies.id ON DELETE CASCADE
|
||||
clientId text NOT NULL FK → clients.id ON DELETE CASCADE
|
||||
role text NOT NULL -- 'director' | 'officer' | 'broker' | 'representative' | 'legal_counsel' | 'employee' | 'shareholder' | 'other'
|
||||
roleDetail text -- free-text qualifier: "Managing Director", "Exclusive Broker"
|
||||
startDate date NOT NULL
|
||||
endDate date -- NULL = active
|
||||
isPrimary boolean NOT NULL DEFAULT false
|
||||
notes text
|
||||
createdAt timestamptz NOT NULL DEFAULT now()
|
||||
updatedAt timestamptz NOT NULL DEFAULT now()
|
||||
Indexes:
|
||||
idx_cm_company on (companyId)
|
||||
idx_cm_client on (clientId)
|
||||
idx_cm_active (partial) on (companyId, clientId) WHERE endDate IS NULL
|
||||
unique_cm_exact UNIQUE on (companyId, clientId, role, startDate)
|
||||
|
||||
company_addresses -- mirrors client_addresses shape with companyId FK
|
||||
company_notes -- mirrors client_notes shape with companyId FK
|
||||
company_tags
|
||||
companyId, tagId composite PK
|
||||
|
||||
berth_reservations
|
||||
id text PK
|
||||
berthId text NOT NULL FK → berths.id
|
||||
portId text NOT NULL FK → ports.id
|
||||
clientId text NOT NULL FK → clients.id -- contract holder
|
||||
yachtId text NOT NULL FK → yachts.id -- which yacht occupies the slip
|
||||
interestId text FK → interests.id -- nullable link back to originating interest
|
||||
status text NOT NULL -- 'pending' | 'active' | 'ended' | 'cancelled'
|
||||
startDate date NOT NULL
|
||||
endDate date -- NULL = open-ended
|
||||
tenureType text NOT NULL DEFAULT 'permanent' -- 'permanent' | 'fixed_term' | 'seasonal'
|
||||
contractFileId text FK → files.id
|
||||
createdBy text NOT NULL
|
||||
createdAt timestamptz NOT NULL DEFAULT now()
|
||||
updatedAt timestamptz NOT NULL DEFAULT now()
|
||||
Indexes:
|
||||
idx_br_berth on (berthId)
|
||||
idx_br_client on (clientId)
|
||||
idx_br_yacht on (yachtId)
|
||||
idx_br_active (partial) UNIQUE on (berthId) WHERE status = 'active'
|
||||
```
|
||||
|
||||
### Modified tables
|
||||
|
||||
```
|
||||
clients
|
||||
DROP COLUMN yachtName, yachtLengthFt, yachtWidthFt, yachtDraftFt,
|
||||
yachtLengthM, yachtWidthM, yachtDraftM, berthSizeDesired
|
||||
DROP COLUMN companyName
|
||||
DROP COLUMN isProxy, proxyType, actualOwnerName, relationshipNotes
|
||||
(retains: fullName, nationality, preferredContactMethod, preferredLanguage,
|
||||
timezone, source, sourceDetails, archivedAt, createdAt, updatedAt)
|
||||
|
||||
interests
|
||||
ADD COLUMN yachtId text FK → yachts.id -- nullable initially; enforced non-null before pipeline_stage leaves 'open'
|
||||
ADD INDEX idx_interests_yacht on (yachtId)
|
||||
|
||||
berth_waiting_list
|
||||
ADD COLUMN yachtId text FK → yachts.id
|
||||
|
||||
invoices
|
||||
ADD COLUMN billingEntityType text NOT NULL -- 'client' | 'company'
|
||||
ADD COLUMN billingEntityId text NOT NULL
|
||||
(clientName column kept as immutable snapshot — must never auto-update)
|
||||
ADD INDEX idx_invoices_billing_entity on (portId, billingEntityType, billingEntityId)
|
||||
|
||||
files
|
||||
ADD COLUMN yachtId text FK → yachts.id -- nullable
|
||||
ADD COLUMN companyId text FK → companies.id -- nullable
|
||||
(existing clientId stays nullable; a file links to one of: client, yacht, or company)
|
||||
|
||||
documents
|
||||
ADD COLUMN yachtId text FK → yachts.id -- nullable
|
||||
ADD COLUMN companyId text FK → companies.id -- nullable
|
||||
```
|
||||
|
||||
### DB-level invariants
|
||||
|
||||
| # | Invariant | Enforced by |
|
||||
| --- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1 | One active ownership row per yacht | Partial unique index on `yacht_ownership_history(yachtId) WHERE endDate IS NULL` |
|
||||
| 2 | One active reservation per berth | Partial unique index on `berth_reservations(berthId) WHERE status = 'active'` |
|
||||
| 3 | Yacht always has a current owner | Both `currentOwnerType` and `currentOwnerId` NOT NULL; ownership row inserted atomically with yacht creation inside service transaction |
|
||||
| 4 | Company names unique per port (case-insensitive) | Unique index on `(portId, lower(name))` |
|
||||
| 5 | Exact-duplicate memberships blocked | Unique index on `(companyId, clientId, role, startDate)` |
|
||||
|
||||
### Service-layer invariants (not DB-enforceable due to polymorphic columns)
|
||||
|
||||
| # | Invariant | Enforced by |
|
||||
| --- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| 6 | `yacht.currentOwnerType='client'` ↔ `currentOwnerId` references an existing row in `clients`; same for `'company'` ↔ `companies` | Zod validator + service-layer lookup before insert/update |
|
||||
| 7 | `yacht_ownership_history.ownerType/ownerId` consistent with the corresponding entity table | Same as #6 |
|
||||
| 8 | `invoices.billingEntityType` + `billingEntityId` consistent with entity table | Same as #6 |
|
||||
| 9 | `files.clientId`, `files.yachtId`, `files.companyId` — exactly one of the three must be non-null if the file is entity-scoped | Service-layer validation on insert/update |
|
||||
|
||||
### Drizzle relations (`relations.ts`)
|
||||
|
||||
All new tables wire into the relations map. Notable additions:
|
||||
|
||||
- `clientsRelations`: `companyMemberships` (many), `ownedYachts` (many, via polymorphic query), `berthReservations` (many)
|
||||
- `yachtsRelations`: `port` (one), `ownershipHistory` (many), `notes` (many), `tags` (many), `interests` (many), `reservations` (many), `documents` (many)
|
||||
- `companiesRelations`: `port` (one), `memberships` (many), `addresses` (many), `notes` (many), `tags` (many), `documents` (many)
|
||||
- `berthReservationsRelations`: `berth`, `port`, `client`, `yacht`, `interest`, `contractFile`
|
||||
|
||||
## Service layer and API
|
||||
|
||||
### New services (`src/lib/services/`)
|
||||
|
||||
| File | Key functions |
|
||||
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `yachts.service.ts` | `list`, `getById`, `create`, `update`, `archive`, `transferOwnership(yachtId, newOwnerType, newOwnerId, effectiveDate, reason, notes)` — atomic: closes current history row, opens new row, updates denormalized `currentOwner*` columns |
|
||||
| `companies.service.ts` | `list`, `getById`, `create`, `update`, `archive`, `upsertByName(portId, name)` (case-insensitive, for autocomplete) |
|
||||
| `company-memberships.service.ts` | `addMembership`, `endMembership(id, endDate)`, `updateMembership`, `listByCompany`, `listByClient`, `setPrimary` |
|
||||
| `berth-reservations.service.ts` | `createPending`, `activate(id)` (gates on partial unique index), `end(id, endDate)`, `cancel(id)`, `listByBerth`, `listByClient`, `listByYacht` |
|
||||
|
||||
### Modified services
|
||||
|
||||
| File | Change |
|
||||
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `clients.service.ts` | Strip yacht/company/proxy field handling from create/update paths |
|
||||
| `interests.service.ts` | Accept `yachtId`; validate yacht is owned by the interest's client OR by a company the client actively represents. Promote-to-stage helpers require `yachtId` non-null before leaving `'open'` |
|
||||
| `berths.service.ts` | Read reservation state via `berth_reservations` instead of deriving from `berths.status`. Reservation state changes also update `berths.status` via trigger-in-service-layer |
|
||||
| `invoices.service.ts` | Accept `billingEntityType` + `billingEntityId`; snapshot the entity's current display name into `clientName` at creation (immutable afterward) |
|
||||
| `search.service.ts` | Extend to yachts and companies; include yacht name, hull number, registration in search index; include company name, legal name, taxId |
|
||||
| `recommendations.ts` (berth matcher) | Pull yacht dimensions from `yachts` table via `interest.yachtId` instead of from `clients.yacht*` |
|
||||
| `document-templates.ts` | Update `MERGE_FIELDS` catalog: deprecate `{{client.yachtName}}`, `{{client.companyName}}` and old yacht dimension tokens; add `{{yacht.*}}`, `{{company.*}}`, `{{owner.*}}` scopes. Update `resolveTemplate()` to resolve new scopes |
|
||||
| `portal.service.ts` | Portal user dashboards surface their yachts (owned + represented via memberships), their active memberships, and their active berth reservations |
|
||||
|
||||
### New REST endpoints
|
||||
|
||||
```
|
||||
# Yachts
|
||||
GET /api/v1/yachts
|
||||
POST /api/v1/yachts
|
||||
GET /api/v1/yachts/:id
|
||||
PATCH /api/v1/yachts/:id
|
||||
DELETE /api/v1/yachts/:id — archive (soft delete)
|
||||
POST /api/v1/yachts/:id/transfer — ownership transfer
|
||||
GET /api/v1/yachts/:id/ownership-history
|
||||
GET /api/v1/yachts/autocomplete?q=…
|
||||
|
||||
# Companies
|
||||
GET /api/v1/companies
|
||||
POST /api/v1/companies
|
||||
GET /api/v1/companies/:id
|
||||
PATCH /api/v1/companies/:id
|
||||
DELETE /api/v1/companies/:id — archive
|
||||
GET /api/v1/companies/autocomplete?q=…
|
||||
|
||||
# Company memberships
|
||||
GET /api/v1/companies/:id/members
|
||||
POST /api/v1/companies/:id/members
|
||||
PATCH /api/v1/companies/:id/members/:mid
|
||||
DELETE /api/v1/companies/:id/members/:mid — sets endDate
|
||||
|
||||
# Berth reservations
|
||||
GET /api/v1/berths/:id/reservations
|
||||
POST /api/v1/berths/:id/reservations — create pending
|
||||
PATCH /api/v1/berth-reservations/:id — state transitions
|
||||
```
|
||||
|
||||
### Modified endpoints
|
||||
|
||||
- `GET /api/v1/clients/:id` — response now includes nested `yachts` (owned + represented), `companies` (via active memberships), `activeReservations`
|
||||
- `POST /api/v1/clients` — no longer accepts yacht/company/proxy fields
|
||||
- `POST /api/v1/interests` — requires `yachtId`
|
||||
- `POST /api/v1/invoices` — requires `billingEntityType` + `billingEntityId`
|
||||
- `POST /api/public/interests` — creates new `client` + `yacht` + optional `company` + `membership` + `interest` in one transaction, all marked `source: 'public_submission'`. No dedup against existing records (anonymous trust boundary).
|
||||
|
||||
### Permissions (new keys)
|
||||
|
||||
```
|
||||
yachts:view
|
||||
yachts:write
|
||||
yachts:transfer — higher-stakes operation, separate from :write
|
||||
yachts:delete — archive permission
|
||||
|
||||
companies:view
|
||||
companies:write
|
||||
companies:delete
|
||||
|
||||
memberships:write — covers both directions of company_memberships
|
||||
|
||||
reservations:view
|
||||
reservations:write
|
||||
```
|
||||
|
||||
Existing role updates:
|
||||
|
||||
- `admin` — all new keys
|
||||
- `team_lead` — `yachts:view`, `yachts:write`, `companies:view`, `companies:write`, `memberships:write`, `reservations:view`; NOT `yachts:transfer` or `reservations:write`
|
||||
- `front_desk` — all `:view` keys
|
||||
|
||||
### Socket / webhook events (new)
|
||||
|
||||
```
|
||||
yacht.created
|
||||
yacht.updated
|
||||
yacht.ownership_transferred
|
||||
yacht.archived
|
||||
company.created
|
||||
company.updated
|
||||
company.archived
|
||||
company_membership.added
|
||||
company_membership.ended
|
||||
berth_reservation.created
|
||||
berth_reservation.activated
|
||||
berth_reservation.ended
|
||||
berth_reservation.cancelled
|
||||
```
|
||||
|
||||
Webhook event map in `src/lib/services/webhooks.ts` gains the same list.
|
||||
|
||||
## EOI template strategy (dual-path)
|
||||
|
||||
Both paths fully supported from day one. Required to mitigate handoff risk — if Documenso breaks or is replaced, the in-app path is the fallback.
|
||||
|
||||
### Shared payload builder
|
||||
|
||||
```ts
|
||||
// src/lib/services/eoi-context.ts
|
||||
export async function buildEoiContext(interestId: string): Promise<EoiContext>
|
||||
|
||||
type EoiContext = {
|
||||
client: { fullName; nationality; primaryEmail; primaryPhone; address; … }
|
||||
yacht: { name; lengthFt; widthFt; draftFt; hullNumber; flag; yearBuilt; … } // via interest.yachtId
|
||||
company: { name; legalName; taxId; billingAddress } | null // if yacht owner is a company
|
||||
owner: { type: 'client' | 'company'; name; … } // polymorphic current owner
|
||||
berth: { mooringNumber; area; lengthFt; price; priceCurrency; tenureType; … }
|
||||
interest: { stage; leadCategory; dateFirstContact; notes; … }
|
||||
port: { name; defaultCurrency; legalEntity; … }
|
||||
date: { today; year }
|
||||
}
|
||||
```
|
||||
|
||||
Both paths consume this. Guarantees the two rendering engines see the same data and stay in sync as schema evolves.
|
||||
|
||||
### Path A — Documenso template
|
||||
|
||||
- Documenso hosts the template, referenced by ID via env var `DOCUMENSO_TEMPLATE_ID` (matches the old system's `NUXT_DOCUMENSO_TEMPLATE_ID` pattern — a single global template ID; per-port templates are a future extension if needed)
|
||||
- Payload builder flattens `EoiContext` into Documenso's field-name format, POSTs to `/api/v1/templates/{id}/generate-document`
|
||||
- Signing flow unchanged: Documenso emails signers, webhook updates status in our DB
|
||||
- Mitigation for "Documenso's template expects specific field names": one-time audit mapping every field name expected by `templateId=8` (from the old system) to a source in the new schema
|
||||
|
||||
### Path B — In-app PDF template
|
||||
|
||||
- Seed a "Standard EOI" HTML template into `document_templates` table on first boot. Template references tokens: `{{client.fullName}}`, `{{yacht.name}}`, `{{yacht.lengthFt}}`, `{{company.name}}`, `{{berth.mooringNumber}}`, `{{interest.dateFirstContact}}`, etc.
|
||||
- `resolveTemplate()` substitutes tokens from `EoiContext`
|
||||
- `pdfme` renders the resolved HTML to PDF
|
||||
- **Signing**: generated PDF is uploaded to Documenso via existing `documensoCreate` + `documensoSend` — Documenso supports signing ad-hoc PDFs (not just its own templates). Signing experience identical to Path A from the signer's perspective.
|
||||
- **Fallback**: if Documenso is unavailable, the PDF can be emailed to the signer via `nodemailer` as a manual fallback (flag in UI, not auto-fallback)
|
||||
|
||||
### UI picker
|
||||
|
||||
Generate-EOI dialog adds a Template dropdown:
|
||||
|
||||
```
|
||||
Template: [ Documenso — Standard EOI v ]
|
||||
[ Documenso — Standard EOI ]
|
||||
[ In-app — Standard EOI ]
|
||||
[ In-app — (any custom template user authored) ]
|
||||
```
|
||||
|
||||
Explicit picker chosen over automatic fallback: misconfiguration is visible, not silently masked — important for handoff.
|
||||
|
||||
## UI impact
|
||||
|
||||
### New pages
|
||||
|
||||
| Route | Purpose |
|
||||
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `/[portSlug]/yachts` | List view: name, dimensions, current owner, status. Filters by owner type, size, status |
|
||||
| `/[portSlug]/yachts/[yachtId]` | Detail — Tabs: Overview, Ownership History, Interests, Reservations, Documents, Notes, Tags |
|
||||
| `/[portSlug]/companies` | List view: name, legal name, # members, # owned yachts |
|
||||
| `/[portSlug]/companies/[companyId]` | Detail — Tabs: Overview, Members, Owned Yachts, Addresses, Documents, Notes, Tags |
|
||||
|
||||
### Modified pages
|
||||
|
||||
| Page | Change |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `client-form` | Remove yacht / companyName / proxy fields. Becomes a clean "person" form. Yacht and company associations managed from detail page, not here |
|
||||
| `client-detail` | Add tabs: Yachts (owned + represented), Companies (active memberships), Reservations |
|
||||
| `client-columns` | Replace yacht/company text columns with "# yachts" and "Primary company" (from active memberships marked `isPrimary`) |
|
||||
| `interest-form` | New required field: yacht picker, constrained to client's yachts (with inline "Add new yacht" option) |
|
||||
| `interest-detail` | Display yacht prominently; berth recommendations match against yacht dimensions |
|
||||
| `berth-detail` | New tab: Reservations. Shows active reservation + history. "Reserve this berth" button opens reservation dialog |
|
||||
| `invoice-form` | New billing-entity picker (client or company toggle + autocomplete); `clientName` snapshot populates automatically |
|
||||
| `eoi-generate-dialog` | New template-picker dropdown (per dual-path strategy) |
|
||||
| Global search | Extended to yachts and companies |
|
||||
| Sidebar | Adds "Yachts" and "Companies" entries. Reservations lives inside the Berths page |
|
||||
| `/api/public/interest` form (new interest submission) | Captures yacht + company sub-forms; creates new trio on submission |
|
||||
|
||||
### Portal pages
|
||||
|
||||
- Dashboard: shows owned + represented yachts, active memberships, active reservations
|
||||
- New "My Yachts" tab — read-only yacht detail scoped to ones user owns or represents
|
||||
- New "My Reservations" tab
|
||||
- Authenticated interest submissions create yacht row linked to the portal user (not anonymous)
|
||||
|
||||
### New components (`src/components/`)
|
||||
|
||||
```
|
||||
yachts/
|
||||
yacht-form.tsx
|
||||
yacht-detail.tsx
|
||||
yacht-detail-header.tsx
|
||||
yacht-tabs.tsx
|
||||
yacht-columns.tsx
|
||||
yacht-picker.tsx
|
||||
yacht-ownership-history.tsx
|
||||
yacht-transfer-dialog.tsx
|
||||
companies/
|
||||
company-form.tsx
|
||||
company-detail.tsx
|
||||
company-detail-header.tsx
|
||||
company-tabs.tsx
|
||||
company-columns.tsx
|
||||
company-picker.tsx
|
||||
company-members-tab.tsx
|
||||
company-owned-yachts-tab.tsx
|
||||
add-membership-dialog.tsx
|
||||
reservations/
|
||||
reservation-form.tsx
|
||||
reservation-list.tsx
|
||||
berth-reserve-dialog.tsx
|
||||
shared/
|
||||
owner-picker.tsx — polymorphic client|company autocomplete
|
||||
billing-entity-picker.tsx
|
||||
```
|
||||
|
||||
All follow existing `shadcn/ui` + CVA + react-hook-form + zod pattern.
|
||||
|
||||
### Seeder (`src/lib/db/seed.ts`) — rewrite
|
||||
|
||||
Produces realistic multi-cardinality fixtures:
|
||||
|
||||
- 3 companies (two with multiple members, one dissolved with an `endDate` on all memberships)
|
||||
- 8 clients (some personal-only, some with company memberships, at least one representing multiple companies)
|
||||
- 12 yachts (mix of client-owned and company-owned; 2-3 with ownership-transfer history)
|
||||
- Interests linking clients ↔ yachts ↔ berths with realistic pipeline-stage distribution
|
||||
- A handful of active berth reservations + a few ended/cancelled ones
|
||||
- Rich contact / address / membership / ownership-history data covering every test scenario
|
||||
|
||||
Seeder shares factory helpers with tests (`tests/helpers/factories.ts`).
|
||||
|
||||
## Testing strategy
|
||||
|
||||
### Coverage targets (CI-enforced)
|
||||
|
||||
| Tier | Target |
|
||||
| ------------- | ------------------- |
|
||||
| Service layer | ≥ 90% line coverage |
|
||||
| Validators | 100% line coverage |
|
||||
| API routes | ≥ 85% line coverage |
|
||||
| Overall | ≥ 85% line coverage |
|
||||
|
||||
Hard rules: no skipped tests on `main`; no PR merge without green CI on all tiers.
|
||||
|
||||
### Tier 1 — Unit tests (Vitest)
|
||||
|
||||
- Every new service function: happy path, each validation failure, each precondition failure, tenant-scoping
|
||||
- Merge-field resolver: every new token resolves correctly across each context shape
|
||||
- Validators: every zod schema tested for pass + fail on each field
|
||||
|
||||
### Tier 2 — Integration tests (Vitest + Postgres via docker-compose test DB)
|
||||
|
||||
- Migration up/down correctness
|
||||
- Partial unique indexes (`berth_reservations(berthId) WHERE status='active'`, `yacht_ownership_history(yachtId) WHERE endDate IS NULL`) reject duplicate inserts
|
||||
- FK cascades: deleting a client cascades contacts/addresses; yacht-with-this-owner is BLOCKED from being lost
|
||||
- Atomic `transferOwnership`: concurrent retries result in consistent state
|
||||
- Polymorphic integrity checks: `yacht.currentOwnerType='client'` with a companyId is rejected by service-layer validation
|
||||
- Company name case-insensitive uniqueness
|
||||
- Every new API route: auth → permission → service → DB → response shape
|
||||
|
||||
### Tier 3 — E2E scenario tests (Playwright)
|
||||
|
||||
Full-lifecycle flows:
|
||||
|
||||
1. Create client → add yacht → create interest → generate EOI (Documenso path) → PDF in MinIO
|
||||
2. Same, in-app template path → verify PDF content contains expected yacht name
|
||||
3. Create company → add two clients as members → create yacht owned by company → generate invoice billed to company
|
||||
4. Yacht transfer: client-owned → company-owned; verify history + denormalized column + UI
|
||||
5. Reserve berth: create → verify visible → attempt duplicate reservation → blocked
|
||||
6. Public interest form → admin sees new client+yacht+company+interest trio
|
||||
7. (Spec 3 stub): merge flow tested end-to-end in Spec 3
|
||||
|
||||
Multi-cardinality flows (the core justification for this refactor):
|
||||
|
||||
8. One client with 3 yachts, 3 interests, 3 different berths — all representable
|
||||
9. One person as broker for 2 companies, each owning 1 yacht — memberships + owned yachts visible from client detail
|
||||
|
||||
Portal flows:
|
||||
|
||||
10. Portal user views "my yachts" — sees only owned/represented
|
||||
11. Portal user submits interest — new yacht linked to their identity
|
||||
|
||||
### Tier 3.5 — Exhaustive Playwright click-through suite
|
||||
|
||||
Location: `tests/e2e/exhaustive/`. Separate CI job (15-20 min, runs in parallel with other tiers, blocks merge if failing).
|
||||
|
||||
Spec files: `yachts`, `companies`, `reservations`, `client-detail-refactored`, `eoi-generate`, `invoice-form`, `berths-with-reservations`, `portal`, `navigation`.
|
||||
|
||||
Per-page logic:
|
||||
|
||||
1. Navigate to page
|
||||
2. Enumerate every interactive element (`button`, `a`, `[role="button"]`, `[data-testid]`, form inputs)
|
||||
3. Click/fill each; post-click: assert no console errors, no 4xx/5xx network responses, UI returns to stable state
|
||||
4. Coverage assertion: elements clicked ≥ total elements on page (minus declared destructive-action allowlist)
|
||||
|
||||
Helper: `tests/helpers/click-everything.ts` exports `clickEverythingOnPage(page, opts)`.
|
||||
|
||||
Destructive actions allowlist (tested separately with create-then-destroy isolation):
|
||||
|
||||
```
|
||||
yachts.delete, yachts.archive, yachts.transferOwnership
|
||||
companies.delete, companies.archive
|
||||
companyMemberships.end
|
||||
berthReservations.cancel, berthReservations.end
|
||||
invoices.delete
|
||||
```
|
||||
|
||||
Acceptance criteria for Spec 1 completion:
|
||||
|
||||
- Every new or changed page has 100% coverage in the exhaustive suite (minus allowlist)
|
||||
- Every allowlist entry has its own narrow destructive test
|
||||
- Zero console errors across the full suite
|
||||
- Zero unexpected 4xx/5xx responses
|
||||
|
||||
### Tier 4 — EOI template regression
|
||||
|
||||
- **Documenso payload snapshot test**: mock Documenso API; assert POST body contains every expected field name with correct value sourced from new schema
|
||||
- **In-app template rendering test**: render seeded template against each scenario's context; assert resolved HTML contains expected substrings; assert `pdfme` produces a non-empty PDF
|
||||
- **Visual diff**: render in-app EOI to PDF, compare against committed golden-image PDFs per scenario; regressions surface as image diffs in PR
|
||||
- **Error paths**: missing yacht, missing company with company-owned yacht reference, missing config (Documenso API key missing) — all produce explicit errors, not silent blanks
|
||||
|
||||
### Tier 5 — Security tests
|
||||
|
||||
- Cross-tenant isolation: yacht/company/reservation in port A invisible/unmodifiable from port B
|
||||
- Permission enforcement: user without `yachts:write` cannot `POST /yachts`; `yachts:transfer` required for transfer endpoint
|
||||
- Portal authorization: portal user cannot see yachts they don't own/represent
|
||||
- Public interest endpoint: anonymous submitter cannot read existing records
|
||||
|
||||
### Test infrastructure
|
||||
|
||||
Fixture factories in `tests/helpers/factories.ts`:
|
||||
|
||||
```
|
||||
makeYacht({ owner: client|company, ...overrides })
|
||||
makeCompany({ overrides })
|
||||
makeMembership({ client, company, role, ...overrides })
|
||||
makeOwnershipHistoryRow({ yacht, owner, startDate, endDate })
|
||||
makeReservation({ berth, client, yacht, status })
|
||||
```
|
||||
|
||||
Scenario builders produce Tier 3 multi-cardinality setups in a single call.
|
||||
|
||||
Integration tests run against a fresh migrated DB; each test file wraps in a transaction that rolls back OR uses per-file schema isolation.
|
||||
|
||||
## Rollout plan
|
||||
|
||||
Green-field Postgres DB — no dual-write, no phased migration needed. Concern is only sequencing so the working tree never enters a broken half-migrated state.
|
||||
|
||||
### PR sequence (≈ 15 PRs, feature branch `refactor/data-model`)
|
||||
|
||||
| # | PR | Depends on |
|
||||
| --- | --------------------------------------------------------------------------------------------------- | ------------ |
|
||||
| 1 | Schema migration: add all new tables, leave old client columns in place | — |
|
||||
| 2 | Service layer: new services (yachts, companies, memberships, reservations) | 1 |
|
||||
| 3 | API routes for new services + new permissions | 2 |
|
||||
| 4 | Seeder rewrite with multi-cardinality fixtures | 2 |
|
||||
| 5 | UI: yacht list + detail + form + picker + ownership-history + transfer-dialog | 3 |
|
||||
| 6 | UI: company list + detail + form + picker + memberships tab + add-membership dialog | 3 |
|
||||
| 7 | UI: berth reservations tab + reserve dialog + ownership-transfer wiring | 3 |
|
||||
| 8 | Client form refactor: strip yacht/company/proxy fields, add nav links to yachts/companies | 5, 6 |
|
||||
| 9 | Interest form: require `yachtId` + public interest form creates trio | 5 |
|
||||
| 10 | Invoice billing-entity support (client or company) | 6 |
|
||||
| 11 | EOI shared payload builder + seed in-app Standard EOI template + dual-path dialog | 5, 6 |
|
||||
| 12 | Merge-field catalog update + resolver extension for `{{yacht.*}}` / `{{company.*}}` / `{{owner.*}}` | 11 |
|
||||
| 13 | Drop old columns from `clients` (`yacht*`, `companyName`, proxy fields) | 8, 9, 10, 11 |
|
||||
| 14 | Exhaustive Playwright click-through suite (Tier 3.5) | 13 |
|
||||
| 15 | Documentation updates (CLAUDE.md, numbered spec files 01-15, API catalog) | 13 |
|
||||
|
||||
After PR 15, merge the feature branch into `main` as one final PR.
|
||||
|
||||
## Risks and mitigations
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
| -------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Spec 2 (importer) depends on final schema; mid-development schema churn → rework | High | Schema freeze after PR 1 lands; amendments require deliberate spec update |
|
||||
| Polymorphic owner columns have no DB-level FK — service-layer bug could insert inconsistent owner | Medium | Service-layer validation + integration test for every create/update path; runtime assertion in `buildEoiContext` |
|
||||
| EOI dual-template drift (two engines produce subtly different output) | Medium | Golden-image visual-diff tests in Tier 4, CI-gated |
|
||||
| Documenso template at `templateId=8` expects specific field names — new payload builder must match | Medium | One-time audit: document every field the existing template expects; map each to a source in new schema; Spec 2's importer uses same mapping |
|
||||
| Old `client-portal/` sub-repo coordination during Spec 2 cutover | Low | Confirm old client-portal is decommissioned at Spec 2 cutover (not running concurrently against shared data) |
|
||||
| Seeder becomes dev-onboarding bottleneck | Low | Seeder uses same factory helpers as tests — code path shared + tested |
|
||||
| Documentation rot in numbered spec files | Low | PR 15 updates them before the feature branch merges to `main` |
|
||||
| Exhaustive-click-suite runtime (15-20 min per PR) | Low | Separate CI job, runs in parallel with other tiers |
|
||||
| Handoff quality — "EOIs don't work" / "I can't see my yachts" | Addressed | Dual template paths + exhaustive click coverage + golden-image diff + template regression tests collectively mitigate |
|
||||
|
||||
## Open questions / deferred items
|
||||
|
||||
Explicitly out of scope for this spec:
|
||||
|
||||
- Yacht survey / class-cert document categorization (requires taxonomy work)
|
||||
- Multi-level company hierarchy (holding → subsidiary) — additive later
|
||||
- Invoice line items referencing specific yacht
|
||||
- Berth reservation auto-renewal flow
|
||||
- Per-yacht row-level permissions (e.g., "broker can only see yachts they represent")
|
||||
- Portal branding per company
|
||||
|
||||
## Success criteria
|
||||
|
||||
Spec 1 is complete when:
|
||||
|
||||
1. All PRs in the sequence are merged to `main`
|
||||
2. CI is green: all coverage gates met, zero skipped tests, exhaustive click-through suite passes
|
||||
3. Manual verification: developer walks through every multi-cardinality scenario in Tier 3 E2E list against a dev build
|
||||
4. Both EOI paths produce documents that match the current system's outputs (visual verification + golden images committed)
|
||||
5. Documentation (CLAUDE.md + numbered spec files) updated
|
||||
6. Spec 2 (NocoDB+MinIO importer) can begin against a frozen schema
|
||||
Reference in New Issue
Block a user