pn-new-crm/docs/superpowers/plans/2026-04-23-data-model-refactor.md

# Data-Model Refactor Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Refactor the core client/yacht/company data model into first-class entities so the system can represent real-world multi-cardinality relationships (one person with many yachts, one yacht owned by a company, one berth with one active reservation). Ships with rich dummy data for dev; real data arrives in Spec 2. Hand-off ready: dual-path EOI generation, exhaustive click-through test suite, golden-image template regression.

**Architecture:** New tables `yachts`, `yacht_ownership_history`, `companies`, `company_memberships`, `berth_reservations` (plus notes/tags/addresses mirrors). Removes yacht/company/proxy columns from `clients`. Adds `yachtId` and `companyId` FKs to `interests`, `berth_waiting_list`, `invoices`, `files`, `documents`. Polymorphic owner columns (`currentOwnerType` + `currentOwnerId`) validated in the service layer; partial unique indexes enforce exclusivity at the DB level. EOI generation routes through a shared `buildEoiContext()` that feeds either Documenso or in-app pdfme.

**Tech Stack:** Drizzle ORM (Postgres), Zod (validation), better-auth, BullMQ, Redis, MinIO, Socket.IO, Next.js 15 App Router, React 19, TanStack Table/Query, react-hook-form, shadcn/ui, pdfme, Documenso API, Vitest, Playwright.

**Spec:** `docs/superpowers/specs/2026-04-23-data-model-refactor-design.md` — refer to it for WHY decisions were made. This plan focuses on HOW to execute them.

---

## Plan conventions

- **Branch:** All work on `refactor/data-model` (long-lived feature branch). Rebase onto `main` daily; merge to `main` in one final PR after Task 15.5.
- **Commits:** After each task, commit with `feat(scope): description` or `refactor(scope): description` or `test(scope): description`. Example: `feat(yachts): add yachts schema`.
- **Tests before code (TDD):** For every service function and every route handler, write the failing test first, verify it fails, then implement.
- **Running tests:** `pnpm vitest run path/to/test.test.ts` for unit/integration; `pnpm playwright test tests/e2e/...` for E2E.
- **Schema changes:** After any `src/lib/db/schema/*.ts` change, run `pnpm db:generate` to produce a migration file, then `pnpm db:push` to apply locally.
- **Linting:** `pnpm lint` and `pnpm format` before every commit (or rely on Husky pre-commit hook).
- **Permission checks:** Every new route MUST call `requirePermission(context, '<key>')` before service calls. Cross-tenant guards are handled inside services via `portId` scoping.

## File structure

New files (created during this plan):

```
src/lib/db/schema/
  yachts.ts                          — yachts + yacht_ownership_history + yacht_notes + yacht_tags
  companies.ts                       — companies + company_memberships + company_addresses + company_notes + company_tags
  reservations.ts                    — berth_reservations

src/lib/validators/
  yachts.ts                          — zod schemas for yacht CRUD + transfer
  companies.ts                       — zod for company CRUD
  company-memberships.ts             — zod for membership CRUD
  reservations.ts                    — zod for reservation CRUD + state transitions

src/lib/services/
  yachts.service.ts
  companies.service.ts
  company-memberships.service.ts
  berth-reservations.service.ts
  eoi-context.ts                     — shared EOI payload builder

src/app/api/v1/yachts/
  route.ts                           — GET list, POST create
  autocomplete/route.ts
  [id]/route.ts                      — GET, PATCH, DELETE
  [id]/transfer/route.ts             — POST transfer
  [id]/ownership-history/route.ts    — GET history

src/app/api/v1/companies/
  route.ts
  autocomplete/route.ts
  [id]/route.ts
  [id]/members/route.ts              — GET list, POST add
  [id]/members/[mid]/route.ts        — PATCH, DELETE

src/app/api/v1/berths/[id]/reservations/
  route.ts                           — GET, POST

src/app/api/v1/berth-reservations/[id]/route.ts  — PATCH state transitions

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

src/components/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

src/components/reservations/
  reservation-form.tsx
  reservation-list.tsx
  berth-reserve-dialog.tsx

src/components/shared/
  owner-picker.tsx                   — polymorphic client|company combobox
  billing-entity-picker.tsx

src/app/(dashboard)/[portSlug]/yachts/
  page.tsx                           — list
  [yachtId]/page.tsx                 — detail

src/app/(dashboard)/[portSlug]/companies/
  page.tsx
  [companyId]/page.tsx

tests/helpers/factories.ts           — EXTEND with yacht/company/membership/reservation factories
tests/helpers/click-everything.ts    — NEW utility for Tier 3.5 exhaustive suite

tests/unit/services/yachts.test.ts
tests/unit/services/companies.test.ts
tests/unit/services/company-memberships.test.ts
tests/unit/services/berth-reservations.test.ts
tests/unit/services/eoi-context.test.ts
tests/unit/validators/yachts.test.ts
tests/unit/validators/companies.test.ts
tests/integration/schema-constraints.test.ts
tests/integration/ownership-transfer.test.ts
tests/integration/reservation-exclusivity.test.ts

tests/e2e/scenarios/yacht-lifecycle.spec.ts
tests/e2e/scenarios/company-lifecycle.spec.ts
tests/e2e/scenarios/multi-cardinality.spec.ts
tests/e2e/scenarios/eoi-documenso-path.spec.ts
tests/e2e/scenarios/eoi-inapp-path.spec.ts
tests/e2e/scenarios/portal.spec.ts

tests/e2e/exhaustive/yachts.spec.ts
tests/e2e/exhaustive/companies.spec.ts
tests/e2e/exhaustive/reservations.spec.ts
tests/e2e/exhaustive/client-detail-refactored.spec.ts
tests/e2e/exhaustive/eoi-generate.spec.ts
tests/e2e/exhaustive/invoice-form.spec.ts
tests/e2e/exhaustive/berths-with-reservations.spec.ts
tests/e2e/exhaustive/portal.spec.ts
tests/e2e/exhaustive/navigation.spec.ts

tests/e2e/templates/eoi-golden-image.spec.ts
tests/e2e/fixtures/eoi-golden/*.pdf  — committed reference PDFs

src/lib/pdf/templates/eoi-standard-inapp.ts  — new in-app EOI template
```

Modified files (major ones):

```
src/lib/db/schema/clients.ts          — drop yacht/company/proxy columns
src/lib/db/schema/interests.ts        — add yachtId
src/lib/db/schema/berths.ts           — add yachtId to waiting list
src/lib/db/schema/financial.ts        — add billingEntityType + billingEntityId to invoices
src/lib/db/schema/documents.ts        — add yachtId + companyId to files + documents
src/lib/db/schema/relations.ts        — wire all new tables
src/lib/db/schema/index.ts            — re-export new tables
src/lib/db/seed.ts                    — rewrite for new model
src/lib/services/clients.service.ts   — strip yacht/company/proxy handling
src/lib/services/interests.service.ts — accept yachtId
src/lib/services/berths.service.ts    — integrate berth_reservations
src/lib/services/invoices.service.ts  — billingEntityType + billingEntityId
src/lib/services/search.service.ts    — extend to yachts + companies
src/lib/services/recommendations.ts   — read yacht dims from yachts table
src/lib/services/document-templates.ts — update MERGE_FIELDS + resolveTemplate
src/lib/services/portal.service.ts    — portal: my-yachts, my-memberships, my-reservations
src/lib/validators/clients.ts         — drop yacht/company/proxy fields
src/lib/validators/interests.ts       — add yachtId
src/lib/validators/invoices.ts        — add billingEntityType + billingEntityId
src/components/clients/client-form.tsx
src/components/clients/client-detail.tsx
src/components/clients/client-tabs.tsx
src/components/clients/client-columns.tsx
src/components/interests/interest-form.tsx
src/components/invoices/invoice-form.tsx
src/components/berths/berth-detail-*.tsx
src/app/api/public/interests/route.ts
src/app/(portal)/portal/**/*.tsx
```

---

# PR 1 — Schema Migration

**Goal:** Add every new table. Leave old client columns in place. Old code still works; new tables exist and are ready for the service layer in PR 2.

**Branch off:** `main`. Merge to: `refactor/data-model`.

### Task 1.1: Create `yachts.ts` schema file

**Files:**

- Create: `src/lib/db/schema/yachts.ts`

- [ ] **Step 1: Write the schema file**

```typescript
import {
  pgTable,
  text,
  integer,
  numeric,
  timestamp,
  boolean,
  index,
  uniqueIndex,
  primaryKey,
} from 'drizzle-orm/pg-core';
import { sql } from 'drizzle-orm';
import { ports } from './ports';

export const yachts = pgTable(
  'yachts',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    portId: text('port_id')
      .notNull()
      .references(() => ports.id),
    name: text('name').notNull(),
    hullNumber: text('hull_number'),
    registration: text('registration'),
    flag: text('flag'),
    yearBuilt: integer('year_built'),
    builder: text('builder'),
    model: text('model'),
    hullMaterial: text('hull_material'),
    lengthFt: numeric('length_ft'),
    widthFt: numeric('width_ft'),
    draftFt: numeric('draft_ft'),
    lengthM: numeric('length_m'),
    widthM: numeric('width_m'),
    draftM: numeric('draft_m'),
    currentOwnerType: text('current_owner_type').notNull(), // 'client' | 'company'
    currentOwnerId: text('current_owner_id').notNull(),
    status: text('status').notNull().default('active'), // 'active' | 'retired' | 'sold_away'
    notes: text('notes'),
    archivedAt: timestamp('archived_at', { withTimezone: true }),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_yachts_port').on(table.portId),
    index('idx_yachts_current_owner').on(
      table.portId,
      table.currentOwnerType,
      table.currentOwnerId,
    ),
    index('idx_yachts_name').on(table.portId, table.name),
    index('idx_yachts_archived').on(table.portId, table.archivedAt),
  ],
);

export const yachtOwnershipHistory = pgTable(
  'yacht_ownership_history',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    yachtId: text('yacht_id')
      .notNull()
      .references(() => yachts.id, { onDelete: 'cascade' }),
    ownerType: text('owner_type').notNull(),
    ownerId: text('owner_id').notNull(),
    startDate: timestamp('start_date', { withTimezone: true, mode: 'date' }).notNull(),
    endDate: timestamp('end_date', { withTimezone: true, mode: 'date' }),
    transferReason: text('transfer_reason'),
    transferNotes: text('transfer_notes'),
    createdBy: text('created_by').notNull(),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_yoh_yacht').on(table.yachtId),
    uniqueIndex('idx_yoh_active')
      .on(table.yachtId)
      .where(sql`${table.endDate} IS NULL`),
  ],
);

export const yachtNotes = pgTable(
  'yacht_notes',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    yachtId: text('yacht_id')
      .notNull()
      .references(() => yachts.id, { onDelete: 'cascade' }),
    authorId: text('author_id').notNull(),
    content: text('content').notNull(),
    mentions: text('mentions').array(),
    isLocked: boolean('is_locked').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [index('idx_yn_yacht').on(table.yachtId)],
);

export const yachtTags = pgTable(
  'yacht_tags',
  {
    yachtId: text('yacht_id')
      .notNull()
      .references(() => yachts.id, { onDelete: 'cascade' }),
    tagId: text('tag_id').notNull(),
  },
  (table) => [primaryKey({ columns: [table.yachtId, table.tagId] })],
);

export type Yacht = typeof yachts.$inferSelect;
export type NewYacht = typeof yachts.$inferInsert;
export type YachtOwnershipHistoryRow = typeof yachtOwnershipHistory.$inferSelect;
export type NewYachtOwnershipHistoryRow = typeof yachtOwnershipHistory.$inferInsert;
export type YachtNote = typeof yachtNotes.$inferSelect;
export type NewYachtNote = typeof yachtNotes.$inferInsert;
```

- [ ] **Step 2: Re-export from schema index**

Add to `src/lib/db/schema/index.ts`:

```typescript
export * from './yachts';
```

- [ ] **Step 3: Generate migration**

Run: `pnpm db:generate`
Expected: new file in `src/lib/db/migrations/` containing the four table creations.

- [ ] **Step 4: Apply migration**

Run: `pnpm db:push`
Expected: no errors; tables created in local Postgres.

- [ ] **Step 5: Commit**

```bash
git add src/lib/db/schema/yachts.ts src/lib/db/schema/index.ts src/lib/db/migrations/
git commit -m "feat(yachts): add yachts, ownership history, notes, tags schema"
```

### Task 1.2: Create `companies.ts` schema file

**Files:**

- Create: `src/lib/db/schema/companies.ts`

- [ ] **Step 1: Write the schema file**

```typescript
import {
  pgTable,
  text,
  timestamp,
  boolean,
  index,
  uniqueIndex,
  primaryKey,
} from 'drizzle-orm/pg-core';
import { sql } from 'drizzle-orm';
import { ports } from './ports';
import { clients } from './clients';

export const companies = pgTable(
  'companies',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    portId: text('port_id')
      .notNull()
      .references(() => ports.id),
    name: text('name').notNull(),
    legalName: text('legal_name'),
    taxId: text('tax_id'),
    registrationNumber: text('registration_number'),
    incorporationCountry: text('incorporation_country'),
    incorporationDate: timestamp('incorporation_date', { withTimezone: true, mode: 'date' }),
    status: text('status').notNull().default('active'), // 'active' | 'dissolved'
    billingEmail: text('billing_email'),
    notes: text('notes'),
    archivedAt: timestamp('archived_at', { withTimezone: true }),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_companies_port').on(table.portId),
    uniqueIndex('idx_companies_name_unique').on(table.portId, sql`lower(${table.name})`),
    index('idx_companies_taxid')
      .on(table.portId, table.taxId)
      .where(sql`${table.taxId} IS NOT NULL`),
  ],
);

export const companyMemberships = pgTable(
  'company_memberships',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    companyId: text('company_id')
      .notNull()
      .references(() => companies.id, { onDelete: 'cascade' }),
    clientId: text('client_id')
      .notNull()
      .references(() => clients.id, { onDelete: 'cascade' }),
    role: text('role').notNull(), // director | officer | broker | representative | legal_counsel | employee | shareholder | other
    roleDetail: text('role_detail'),
    startDate: timestamp('start_date', { withTimezone: true, mode: 'date' }).notNull(),
    endDate: timestamp('end_date', { withTimezone: true, mode: 'date' }),
    isPrimary: boolean('is_primary').notNull().default(false),
    notes: text('notes'),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_cm_company').on(table.companyId),
    index('idx_cm_client').on(table.clientId),
    index('idx_cm_active')
      .on(table.companyId, table.clientId)
      .where(sql`${table.endDate} IS NULL`),
    uniqueIndex('unique_cm_exact').on(table.companyId, table.clientId, table.role, table.startDate),
  ],
);

export const companyAddresses = pgTable(
  'company_addresses',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    companyId: text('company_id')
      .notNull()
      .references(() => companies.id, { onDelete: 'cascade' }),
    portId: text('port_id')
      .notNull()
      .references(() => ports.id, { onDelete: 'cascade' }),
    label: text('label').notNull().default('Primary'),
    streetAddress: text('street_address'),
    city: text('city'),
    stateProvince: text('state_province'),
    postalCode: text('postal_code'),
    country: text('country'),
    isPrimary: boolean('is_primary').notNull().default(true),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_compa_company').on(table.companyId),
    index('idx_compa_port').on(table.portId),
    uniqueIndex('idx_compa_primary')
      .on(table.companyId)
      .where(sql`${table.isPrimary} = true`),
  ],
);

export const companyNotes = pgTable(
  'company_notes',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    companyId: text('company_id')
      .notNull()
      .references(() => companies.id, { onDelete: 'cascade' }),
    authorId: text('author_id').notNull(),
    content: text('content').notNull(),
    mentions: text('mentions').array(),
    isLocked: boolean('is_locked').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [index('idx_compn_company').on(table.companyId)],
);

export const companyTags = pgTable(
  'company_tags',
  {
    companyId: text('company_id')
      .notNull()
      .references(() => companies.id, { onDelete: 'cascade' }),
    tagId: text('tag_id').notNull(),
  },
  (table) => [primaryKey({ columns: [table.companyId, table.tagId] })],
);

export type Company = typeof companies.$inferSelect;
export type NewCompany = typeof companies.$inferInsert;
export type CompanyMembership = typeof companyMemberships.$inferSelect;
export type NewCompanyMembership = typeof companyMemberships.$inferInsert;
export type CompanyAddress = typeof companyAddresses.$inferSelect;
export type NewCompanyAddress = typeof companyAddresses.$inferInsert;
export type CompanyNote = typeof companyNotes.$inferSelect;
export type NewCompanyNote = typeof companyNotes.$inferInsert;
```

- [ ] **Step 2: Re-export from schema index**

Add to `src/lib/db/schema/index.ts`:

```typescript
export * from './companies';
```

- [ ] **Step 3: Generate + apply migration**

```bash
pnpm db:generate
pnpm db:push
```

- [ ] **Step 4: Commit**

```bash
git add src/lib/db/schema/companies.ts src/lib/db/schema/index.ts src/lib/db/migrations/
git commit -m "feat(companies): add companies, memberships, addresses, notes, tags schema"
```

### Task 1.3: Create `reservations.ts` schema file

**Files:**

- Create: `src/lib/db/schema/reservations.ts`

- [ ] **Step 1: Write the schema**

```typescript
import { pgTable, text, timestamp, index, uniqueIndex } from 'drizzle-orm/pg-core';
import { sql } from 'drizzle-orm';
import { ports } from './ports';
import { berths } from './berths';
import { clients } from './clients';
import { yachts } from './yachts';
import { interests } from './interests';
import { files } from './documents';

export const berthReservations = pgTable(
  'berth_reservations',
  {
    id: text('id')
      .primaryKey()
      .$defaultFn(() => crypto.randomUUID()),
    berthId: text('berth_id')
      .notNull()
      .references(() => berths.id),
    portId: text('port_id')
      .notNull()
      .references(() => ports.id),
    clientId: text('client_id')
      .notNull()
      .references(() => clients.id),
    yachtId: text('yacht_id')
      .notNull()
      .references(() => yachts.id),
    interestId: text('interest_id').references(() => interests.id),
    status: text('status').notNull(), // 'pending' | 'active' | 'ended' | 'cancelled'
    startDate: timestamp('start_date', { withTimezone: true, mode: 'date' }).notNull(),
    endDate: timestamp('end_date', { withTimezone: true, mode: 'date' }),
    tenureType: text('tenure_type').notNull().default('permanent'),
    contractFileId: text('contract_file_id').references(() => files.id),
    notes: text('notes'),
    createdBy: text('created_by').notNull(),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_br_berth').on(table.berthId),
    index('idx_br_client').on(table.clientId),
    index('idx_br_yacht').on(table.yachtId),
    index('idx_br_port').on(table.portId),
    uniqueIndex('idx_br_active')
      .on(table.berthId)
      .where(sql`${table.status} = 'active'`),
  ],
);

export type BerthReservation = typeof berthReservations.$inferSelect;
export type NewBerthReservation = typeof berthReservations.$inferInsert;
```

- [ ] **Step 2: Re-export from schema index**

- [ ] **Step 3: Generate + apply migration, commit**

```bash
pnpm db:generate && pnpm db:push
git add src/lib/db/schema/reservations.ts src/lib/db/schema/index.ts src/lib/db/migrations/
git commit -m "feat(reservations): add berth_reservations schema with partial unique exclusivity"
```

### Task 1.4: Add `yachtId` to `interests`, `berth_waiting_list`

**Files:**

- Modify: `src/lib/db/schema/interests.ts`
- Modify: `src/lib/db/schema/berths.ts`

- [ ] **Step 1: Add `yachtId` to `interests` schema**

In `src/lib/db/schema/interests.ts`, add a `yachtId` column after `berthId`:

```typescript
yachtId: text('yacht_id'), // FK added via relation; nullable until pipeline leaves 'open'
```

Add an index:

```typescript
index('idx_interests_yacht').on(table.yachtId),
```

- [ ] **Step 2: Add `yachtId` to `berth_waiting_list`**

In `src/lib/db/schema/berths.ts`, find `berthWaitingList` and add:

```typescript
yachtId: text('yacht_id'), // FK added via relation; nullable
```

- [ ] **Step 3: Generate + apply migration, commit**

```bash
pnpm db:generate && pnpm db:push
git add src/lib/db/schema/interests.ts src/lib/db/schema/berths.ts src/lib/db/migrations/
git commit -m "feat(schema): add yachtId to interests and berth_waiting_list"
```

### Task 1.5: Modify `invoices` — add billing entity

**Files:**

- Modify: `src/lib/db/schema/financial.ts`

- [ ] **Step 1: Add billing entity columns**

After `clientName` in the `invoices` table, add:

```typescript
billingEntityType: text('billing_entity_type').notNull().default('client'), // 'client' | 'company' — default needed for backfill-less green-field
billingEntityId: text('billing_entity_id').notNull().default(''),
```

Add an index:

```typescript
index('idx_invoices_billing_entity').on(table.portId, table.billingEntityType, table.billingEntityId),
```

- [ ] **Step 2: Generate + apply migration, commit**

```bash
pnpm db:generate && pnpm db:push
git add src/lib/db/schema/financial.ts src/lib/db/migrations/
git commit -m "feat(invoices): add billingEntityType/Id for polymorphic billing"
```

### Task 1.6: Modify `files` and `documents` — add yachtId/companyId FKs

**Files:**

- Modify: `src/lib/db/schema/documents.ts`

- [ ] **Step 1: Add FKs to `files` table**

```typescript
yachtId: text('yacht_id'), // FK wired in relations.ts
companyId: text('company_id'), // FK wired in relations.ts
```

Also add indexes.

- [ ] **Step 2: Add same FKs to `documents` table**

Same two columns + indexes.

- [ ] **Step 3: Generate + apply migration, commit**

```bash
pnpm db:generate && pnpm db:push
git add src/lib/db/schema/documents.ts src/lib/db/migrations/
git commit -m "feat(documents): add yachtId/companyId to files and documents"
```

### Task 1.7: Wire new tables into `relations.ts`

**Files:**

- Modify: `src/lib/db/schema/relations.ts`

- [ ] **Step 1: Import new tables**

At the top of `relations.ts`, add imports:

```typescript
import { yachts, yachtOwnershipHistory, yachtNotes, yachtTags } from './yachts';
import {
  companies,
  companyMemberships,
  companyAddresses,
  companyNotes,
  companyTags,
} from './companies';
import { berthReservations } from './reservations';
```

- [ ] **Step 2: Add relations for `yachts`**

```typescript
export const yachtsRelations = relations(yachts, ({ one, many }) => ({
  port: one(ports, { fields: [yachts.portId], references: [ports.id] }),
  ownershipHistory: many(yachtOwnershipHistory),
  notes: many(yachtNotes),
  tags: many(yachtTags),
  interests: many(interests),
  reservations: many(berthReservations),
  documents: many(documents),
}));

export const yachtOwnershipHistoryRelations = relations(yachtOwnershipHistory, ({ one }) => ({
  yacht: one(yachts, { fields: [yachtOwnershipHistory.yachtId], references: [yachts.id] }),
}));

export const yachtNotesRelations = relations(yachtNotes, ({ one }) => ({
  yacht: one(yachts, { fields: [yachtNotes.yachtId], references: [yachts.id] }),
}));

export const yachtTagsRelations = relations(yachtTags, ({ one }) => ({
  yacht: one(yachts, { fields: [yachtTags.yachtId], references: [yachts.id] }),
  tag: one(tags, { fields: [yachtTags.tagId], references: [tags.id] }),
}));
```

- [ ] **Step 3: Add relations for companies + memberships + addresses + notes + tags**

Mirror the pattern from Step 2. Include `companyMembershipsRelations` wiring both `company: one(companies, ...)` and `client: one(clients, ...)`.

- [ ] **Step 4: Add relations for `berthReservations`**

```typescript
export const berthReservationsRelations = relations(berthReservations, ({ one }) => ({
  berth: one(berths, { fields: [berthReservations.berthId], references: [berths.id] }),
  port: one(ports, { fields: [berthReservations.portId], references: [ports.id] }),
  client: one(clients, { fields: [berthReservations.clientId], references: [clients.id] }),
  yacht: one(yachts, { fields: [berthReservations.yachtId], references: [yachts.id] }),
  interest: one(interests, {
    fields: [berthReservations.interestId],
    references: [interests.id],
  }),
  contractFile: one(files, {
    fields: [berthReservations.contractFileId],
    references: [files.id],
  }),
}));
```

- [ ] **Step 5: Extend `clientsRelations`**

Add to the `clients` relations `many()` block:

```typescript
companyMemberships: many(companyMemberships),
berthReservations: many(berthReservations),
```

Note: owned yachts (where client is the current owner) is a polymorphic lookup; query via `yachts` where `currentOwnerType='client' AND currentOwnerId=...`. Don't attempt a Drizzle relation for this — service layer handles it.

- [ ] **Step 6: Extend `interestsRelations`**

Add: `yacht: one(yachts, { fields: [interests.yachtId], references: [yachts.id] })`.

- [ ] **Step 7: Extend `filesRelations`, `documentsRelations`**

Add `yacht` and `company` one-to-one relations on each.

- [ ] **Step 8: Commit**

```bash
git add src/lib/db/schema/relations.ts
git commit -m "feat(schema): wire yacht, company, reservation relations in Drizzle"
```

### Task 1.8: Integration test for partial unique indexes

**Files:**

- Create: `tests/integration/schema-constraints.test.ts`

- [ ] **Step 1: Write failing test**

```typescript
import { describe, it, expect, beforeEach } from 'vitest';
import { db } from '@/lib/db';
import { yachts, yachtOwnershipHistory } from '@/lib/db/schema';
import { berthReservations } from '@/lib/db/schema/reservations';
import { makeClient, makePort, makeYacht, makeBerth } from 'tests/helpers/factories';

describe('schema constraints', () => {
  it('partial unique: rejects a second active ownership row per yacht', async () => {
    const port = await makePort();
    const client1 = await makeClient({ portId: port.id });
    const client2 = await makeClient({ portId: port.id });
    const yacht = await makeYacht({ portId: port.id, ownerType: 'client', ownerId: client1.id });
    // ownership row #1 already created by makeYacht

    await expect(
      db.insert(yachtOwnershipHistory).values({
        yachtId: yacht.id,
        ownerType: 'client',
        ownerId: client2.id,
        startDate: new Date(),
        endDate: null, // another "active" row — should fail
        createdBy: 'test',
      }),
    ).rejects.toThrow(/duplicate key/i);
  });

  it('partial unique: rejects a second active reservation per berth', async () => {
    const port = await makePort();
    const client1 = await makeClient({ portId: port.id });
    const client2 = await makeClient({ portId: port.id });
    const yacht1 = await makeYacht({ portId: port.id, ownerType: 'client', ownerId: client1.id });
    const yacht2 = await makeYacht({ portId: port.id, ownerType: 'client', ownerId: client2.id });
    const berth = await makeBerth({ portId: port.id });

    await db.insert(berthReservations).values({
      berthId: berth.id,
      portId: port.id,
      clientId: client1.id,
      yachtId: yacht1.id,
      status: 'active',
      startDate: new Date(),
      createdBy: 'test',
    });

    await expect(
      db.insert(berthReservations).values({
        berthId: berth.id,
        portId: port.id,
        clientId: client2.id,
        yachtId: yacht2.id,
        status: 'active',
        startDate: new Date(),
        createdBy: 'test',
      }),
    ).rejects.toThrow(/duplicate key/i);
  });

  it('case-insensitive company name uniqueness per port', async () => {
    const port = await makePort();
    await db.insert(companies).values({ portId: port.id, name: 'Aegean Holdings' });
    await expect(
      db.insert(companies).values({ portId: port.id, name: 'AEGEAN HOLDINGS' }),
    ).rejects.toThrow(/duplicate key/i);
  });
});
```

- [ ] **Step 2: Add `makeYacht`, `makeBerth` factories to `tests/helpers/factories.ts`**

```typescript
export async function makeYacht(args: {
  portId: string;
  ownerType: 'client' | 'company';
  ownerId: string;
  overrides?: Partial<NewYacht>;
}) {
  const [yacht] = await db
    .insert(yachts)
    .values({
      portId: args.portId,
      name: faker.word.noun() + ' ' + faker.word.adjective(),
      currentOwnerType: args.ownerType,
      currentOwnerId: args.ownerId,
      ...args.overrides,
    })
    .returning();
  await db.insert(yachtOwnershipHistory).values({
    yachtId: yacht!.id,
    ownerType: args.ownerType,
    ownerId: args.ownerId,
    startDate: new Date(),
    endDate: null,
    createdBy: 'test',
  });
  return yacht!;
}

export async function makeBerth(args: { portId: string; overrides?: Partial<NewBerth> }) {
  const [berth] = await db
    .insert(berths)
    .values({
      portId: args.portId,
      mooringNumber: faker.string.alphanumeric(6),
      ...args.overrides,
    })
    .returning();
  return berth!;
}
```

- [ ] **Step 3: Run the test — verify all three cases pass**

```bash
pnpm vitest run tests/integration/schema-constraints.test.ts
```

Expected: 3 passed.

- [ ] **Step 4: Commit**

```bash
git add tests/integration/schema-constraints.test.ts tests/helpers/factories.ts
git commit -m "test(schema): verify partial unique indexes and case-insensitive company uniqueness"
```

### Task 1.9: Create PR 1

- [ ] Open PR from `refactor/data-model` (or push changes if working directly on it).
- [ ] PR title: `feat(schema): foundation tables for yacht/company refactor (PR 1 of 15)`
- [ ] Body: summary of tables created + link to spec.

---

# PR 2 — New Services

**Goal:** Build the four new services (yachts, companies, memberships, berth-reservations) + shared EOI context builder. Unit tests for every function. Integration tests for atomic operations.

### Task 2.1: Validators — `yachts.ts`

**Files:**

- Create: `src/lib/validators/yachts.ts`

- [ ] **Step 1: Write zod schemas**

```typescript
import { z } from 'zod';
import { baseListQuerySchema } from '@/lib/api/route-helpers';

export const ownerRefSchema = z.object({
  type: z.enum(['client', 'company']),
  id: z.string().min(1),
});

export const createYachtSchema = z.object({
  name: z.string().min(1).max(200),
  hullNumber: z.string().optional(),
  registration: z.string().optional(),
  flag: z.string().optional(),
  yearBuilt: z.number().int().min(1800).max(2100).optional(),
  builder: z.string().optional(),
  model: z.string().optional(),
  hullMaterial: z.string().optional(),
  lengthFt: z.string().optional(),
  widthFt: z.string().optional(),
  draftFt: z.string().optional(),
  lengthM: z.string().optional(),
  widthM: z.string().optional(),
  draftM: z.string().optional(),
  owner: ownerRefSchema, // required; yacht must have an owner
  status: z.enum(['active', 'retired', 'sold_away']).optional().default('active'),
  notes: z.string().optional(),
  tagIds: z.array(z.string()).optional().default([]),
});

export const updateYachtSchema = createYachtSchema.partial().omit({ owner: true });
// Owner changes go through /transfer, not PATCH.

export const transferOwnershipSchema = z.object({
  newOwner: ownerRefSchema,
  effectiveDate: z.coerce.date(),
  transferReason: z
    .enum(['sale', 'inheritance', 'gift', 'company_restructure', 'other'])
    .optional(),
  transferNotes: z.string().optional(),
});

export const listYachtsQuery = baseListQuerySchema.extend({
  ownerType: z.enum(['client', 'company']).optional(),
  ownerId: z.string().optional(),
  status: z.enum(['active', 'retired', 'sold_away']).optional(),
  search: z.string().optional(),
});

export type CreateYachtInput = z.infer<typeof createYachtSchema>;
export type UpdateYachtInput = z.infer<typeof updateYachtSchema>;
export type TransferOwnershipInput = z.infer<typeof transferOwnershipSchema>;
export type ListYachtsInput = z.infer<typeof listYachtsQuery>;
```

- [ ] **Step 2: Write unit tests for validators**

```typescript
// tests/unit/validators/yachts.test.ts
import { describe, it, expect } from 'vitest';
import { createYachtSchema, transferOwnershipSchema } from '@/lib/validators/yachts';

describe('createYachtSchema', () => {
  it('rejects empty name', () => {
    const result = createYachtSchema.safeParse({
      name: '',
      owner: { type: 'client', id: 'c1' },
    });
    expect(result.success).toBe(false);
  });

  it('requires owner', () => {
    const result = createYachtSchema.safeParse({ name: 'Sea Breeze' });
    expect(result.success).toBe(false);
  });

  it('rejects invalid yearBuilt', () => {
    const result = createYachtSchema.safeParse({
      name: 'Sea Breeze',
      owner: { type: 'client', id: 'c1' },
      yearBuilt: 1700,
    });
    expect(result.success).toBe(false);
  });

  it('accepts minimal valid input', () => {
    const result = createYachtSchema.safeParse({
      name: 'Sea Breeze',
      owner: { type: 'client', id: 'c1' },
    });
    expect(result.success).toBe(true);
  });
});

describe('transferOwnershipSchema', () => {
  it('requires newOwner + effectiveDate', () => {
    expect(transferOwnershipSchema.safeParse({}).success).toBe(false);
  });

  it('accepts valid input', () => {
    const result = transferOwnershipSchema.safeParse({
      newOwner: { type: 'company', id: 'co1' },
      effectiveDate: new Date(),
      transferReason: 'sale',
    });
    expect(result.success).toBe(true);
  });
});
```

- [ ] **Step 3: Run tests, commit**

```bash
pnpm vitest run tests/unit/validators/yachts.test.ts
git add src/lib/validators/yachts.ts tests/unit/validators/yachts.test.ts
git commit -m "feat(yachts): add zod validators + tests"
```

### Task 2.2: Service — `yachts.service.ts` (create + list + get)

**Files:**

- Create: `src/lib/services/yachts.service.ts`
- Create: `tests/unit/services/yachts.test.ts`

- [ ] **Step 1: Write failing test for `createYacht`**

```typescript
// tests/unit/services/yachts.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createYacht, getYachtById } from '@/lib/services/yachts.service';
import { makeClient, makeCompany, makePort, makeAuditMeta } from 'tests/helpers/factories';
import { db } from '@/lib/db';
import { yachts, yachtOwnershipHistory } from '@/lib/db/schema';
import { eq } from 'drizzle-orm';

describe('yachts.service — createYacht', () => {
  it('creates a yacht with a client owner and opens an ownership history row', async () => {
    const port = await makePort();
    const client = await makeClient({ portId: port.id });

    const yacht = await createYacht(
      port.id,
      {
        name: 'Sea Breeze',
        owner: { type: 'client', id: client.id },
      },
      makeAuditMeta(),
    );

    expect(yacht.currentOwnerType).toBe('client');
    expect(yacht.currentOwnerId).toBe(client.id);

    const history = await db
      .select()
      .from(yachtOwnershipHistory)
      .where(eq(yachtOwnershipHistory.yachtId, yacht.id));
    expect(history).toHaveLength(1);
    expect(history[0]!.endDate).toBeNull();
  });

  it('rejects when ownerType=client but ownerId does not exist', async () => {
    const port = await makePort();
    await expect(
      createYacht(
        port.id,
        { name: 'Phantom', owner: { type: 'client', id: 'nonexistent' } },
        makeAuditMeta(),
      ),
    ).rejects.toThrow(/owner not found/i);
  });

  it('rejects when ownerType=company but ownerId does not exist', async () => {
    const port = await makePort();
    await expect(
      createYacht(
        port.id,
        { name: 'Phantom', owner: { type: 'company', id: 'nonexistent' } },
        makeAuditMeta(),
      ),
    ).rejects.toThrow(/owner not found/i);
  });

  it('rejects owner from a different tenant (cross-tenant guard)', async () => {
    const portA = await makePort();
    const portB = await makePort();
    const clientInB = await makeClient({ portId: portB.id });
    await expect(
      createYacht(
        portA.id,
        { name: 'Wrong Port', owner: { type: 'client', id: clientInB.id } },
        makeAuditMeta(),
      ),
    ).rejects.toThrow(/owner not found/i);
  });
});
```

- [ ] **Step 2: Run test — verify 4 failures**

```bash
pnpm vitest run tests/unit/services/yachts.test.ts
```

- [ ] **Step 3: Implement `createYacht`**

```typescript
// src/lib/services/yachts.service.ts
import { and, eq, sql } from 'drizzle-orm';
import { db } from '@/lib/db';
import { yachts, yachtOwnershipHistory, clients } from '@/lib/db/schema';
import { companies } from '@/lib/db/schema/companies';
import { createAuditLog } from '@/lib/audit';
import { NotFoundError, ValidationError } from '@/lib/errors';
import { emitToRoom } from '@/lib/socket/server';
import type { CreateYachtInput } from '@/lib/validators/yachts';

interface AuditMeta {
  userId: string;
  portId: string;
  ipAddress: string;
  userAgent: string;
}

async function assertOwnerExists(
  portId: string,
  owner: { type: 'client' | 'company'; id: string },
): Promise<void> {
  if (owner.type === 'client') {
    const client = await db.query.clients.findFirst({
      where: and(eq(clients.id, owner.id), eq(clients.portId, portId)),
    });
    if (!client) throw new ValidationError('owner not found');
  } else {
    const company = await db.query.companies.findFirst({
      where: and(eq(companies.id, owner.id), eq(companies.portId, portId)),
    });
    if (!company) throw new ValidationError('owner not found');
  }
}

export async function createYacht(portId: string, data: CreateYachtInput, meta: AuditMeta) {
  return await db.transaction(async (tx) => {
    await assertOwnerExists(portId, data.owner);

    const [yacht] = await tx
      .insert(yachts)
      .values({
        portId,
        name: data.name,
        hullNumber: data.hullNumber ?? null,
        registration: data.registration ?? null,
        flag: data.flag ?? null,
        yearBuilt: data.yearBuilt ?? null,
        builder: data.builder ?? null,
        model: data.model ?? null,
        hullMaterial: data.hullMaterial ?? null,
        lengthFt: data.lengthFt ?? null,
        widthFt: data.widthFt ?? null,
        draftFt: data.draftFt ?? null,
        lengthM: data.lengthM ?? null,
        widthM: data.widthM ?? null,
        draftM: data.draftM ?? null,
        currentOwnerType: data.owner.type,
        currentOwnerId: data.owner.id,
        status: data.status ?? 'active',
        notes: data.notes ?? null,
      })
      .returning();

    await tx.insert(yachtOwnershipHistory).values({
      yachtId: yacht!.id,
      ownerType: data.owner.type,
      ownerId: data.owner.id,
      startDate: new Date(),
      endDate: null,
      createdBy: meta.userId,
    });

    void createAuditLog({
      userId: meta.userId,
      portId,
      action: 'create',
      entityType: 'yacht',
      entityId: yacht!.id,
      newValue: { name: yacht!.name, owner: data.owner },
      ipAddress: meta.ipAddress,
      userAgent: meta.userAgent,
    });

    emitToRoom(`port:${portId}`, 'yacht:created', { yachtId: yacht!.id });

    return yacht!;
  });
}

export async function getYachtById(id: string, portId: string) {
  const yacht = await db.query.yachts.findFirst({
    where: and(eq(yachts.id, id), eq(yachts.portId, portId)),
  });
  if (!yacht) throw new NotFoundError('Yacht');
  return yacht;
}
```

- [ ] **Step 4: Run test — verify all 4 pass**

- [ ] **Step 5: Commit**

```bash
git add src/lib/services/yachts.service.ts tests/unit/services/yachts.test.ts
git commit -m "feat(yachts): createYacht + getYachtById services with tests"
```

### Task 2.3: Service — `yachts.service.ts` (update + archive)

**Files:**

- Modify: `src/lib/services/yachts.service.ts`
- Modify: `tests/unit/services/yachts.test.ts`

- [ ] **Step 1: Add failing tests for `updateYacht`, `archiveYacht`**

Tests: update fields succeeds; owner fields cannot be changed via PATCH (must use transfer); archive sets `archivedAt`.

- [ ] **Step 2: Implement `updateYacht` and `archiveYacht`**

Pattern mirrors other services (`diffEntity`, audit log, socket emit). Reject any attempt to mutate `currentOwnerType` or `currentOwnerId` via update (throw `ValidationError('use /transfer to change ownership')`).

- [ ] **Step 3: Run tests, commit**

```bash
git commit -am "feat(yachts): updateYacht + archiveYacht"
```

### Task 2.4: Service — `yachts.service.ts` (transferOwnership — atomic)

**Files:**

- Modify: `src/lib/services/yachts.service.ts`
- Create: `tests/integration/ownership-transfer.test.ts`

- [ ] **Step 1: Write integration test for atomicity**

```typescript
// tests/integration/ownership-transfer.test.ts
import { describe, it, expect } from 'vitest';
import { transferOwnership } from '@/lib/services/yachts.service';
import {
  makeClient,
  makeCompany,
  makePort,
  makeYacht,
  makeAuditMeta,
} from 'tests/helpers/factories';
import { db } from '@/lib/db';
import { yachtOwnershipHistory, yachts } from '@/lib/db/schema';
import { eq } from 'drizzle-orm';

describe('transferOwnership', () => {
  it('closes prior history row and opens a new one atomically', async () => {
    const port = await makePort();
    const clientA = await makeClient({ portId: port.id });
    const clientB = await makeClient({ portId: port.id });
    const yacht = await makeYacht({ portId: port.id, ownerType: 'client', ownerId: clientA.id });

    await transferOwnership(
      yacht.id,
      port.id,
      {
        newOwner: { type: 'client', id: clientB.id },
        effectiveDate: new Date(),
        transferReason: 'sale',
      },
      makeAuditMeta(),
    );

    const history = await db
      .select()
      .from(yachtOwnershipHistory)
      .where(eq(yachtOwnershipHistory.yachtId, yacht.id));
    expect(history).toHaveLength(2);
    const [prior, current] = history.sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
    expect(prior!.endDate).not.toBeNull();
    expect(current!.endDate).toBeNull();
    expect(current!.ownerId).toBe(clientB.id);

    const updatedYacht = await db.query.yachts.findFirst({ where: eq(yachts.id, yacht.id) });
    expect(updatedYacht!.currentOwnerId).toBe(clientB.id);
  });

  it('rejects when newOwner = currentOwner (no-op)', async () => {
    const port = await makePort();
    const client = await makeClient({ portId: port.id });
    const yacht = await makeYacht({ portId: port.id, ownerType: 'client', ownerId: client.id });

    await expect(
      transferOwnership(
        yacht.id,
        port.id,
        { newOwner: { type: 'client', id: client.id }, effectiveDate: new Date() },
        makeAuditMeta(),
      ),
    ).rejects.toThrow(/same owner/i);
  });

  it('partial unique index prevents concurrent double-open ownership rows', async () => {
    // Prior to the atomic close-then-open, a naive impl would insert a new open row
    // without closing the old one. Verify this would be blocked at the DB level.
    const port = await makePort();
    const clientA = await makeClient({ portId: port.id });
    const clientB = await makeClient({ portId: port.id });
    const yacht = await makeYacht({ portId: port.id, ownerType: 'client', ownerId: clientA.id });

    await expect(
      db.insert(yachtOwnershipHistory).values({
        yachtId: yacht.id,
        ownerType: 'client',
        ownerId: clientB.id,
        startDate: new Date(),
        endDate: null,
        createdBy: 'test',
      }),
    ).rejects.toThrow(/duplicate key/i);
  });
});
```

- [ ] **Step 2: Implement `transferOwnership`**

```typescript
export async function transferOwnership(
  yachtId: string,
  portId: string,
  data: TransferOwnershipInput,
  meta: AuditMeta,
) {
  return await db.transaction(async (tx) => {
    const yacht = await tx.query.yachts.findFirst({
      where: and(eq(yachts.id, yachtId), eq(yachts.portId, portId)),
    });
    if (!yacht) throw new NotFoundError('Yacht');

    if (
      yacht.currentOwnerType === data.newOwner.type &&
      yacht.currentOwnerId === data.newOwner.id
    ) {
      throw new ValidationError('same owner — nothing to transfer');
    }

    await assertOwnerExists(portId, data.newOwner);

    // Close the currently-active history row
    await tx
      .update(yachtOwnershipHistory)
      .set({ endDate: data.effectiveDate })
      .where(
        and(
          eq(yachtOwnershipHistory.yachtId, yachtId),
          sql`${yachtOwnershipHistory.endDate} IS NULL`,
        ),
      );

    // Open new row
    await tx.insert(yachtOwnershipHistory).values({
      yachtId,
      ownerType: data.newOwner.type,
      ownerId: data.newOwner.id,
      startDate: data.effectiveDate,
      endDate: null,
      transferReason: data.transferReason ?? null,
      transferNotes: data.transferNotes ?? null,
      createdBy: meta.userId,
    });

    // Update denormalized current-owner columns
    const [updated] = await tx
      .update(yachts)
      .set({
        currentOwnerType: data.newOwner.type,
        currentOwnerId: data.newOwner.id,
        updatedAt: new Date(),
      })
      .where(eq(yachts.id, yachtId))
      .returning();

    void createAuditLog({
      userId: meta.userId,
      portId,
      action: 'update',
      entityType: 'yacht',
      entityId: yachtId,
      newValue: { ownerTransferTo: data.newOwner, reason: data.transferReason },
      ipAddress: meta.ipAddress,
      userAgent: meta.userAgent,
    });

    emitToRoom(`port:${portId}`, 'yacht:ownership_transferred', {
      yachtId,
      newOwner: data.newOwner,
    });

    return updated!;
  });
}
```

- [ ] **Step 3: Run tests, commit**

```bash
pnpm vitest run tests/integration/ownership-transfer.test.ts
git commit -am "feat(yachts): atomic transferOwnership with partial-unique guard"
```

### Task 2.5: Service — `yachts.service.ts` (list + search + owner lookups)

**Files:**

- Modify: `src/lib/services/yachts.service.ts`

- [ ] **Step 1: Write failing tests for `listYachts`**

Tests: filters by ownerType+ownerId; filters by status; filters by search; respects pagination; tenant-scoped.

- [ ] **Step 2: Implement `listYachts`**

Uses `buildListQuery` helper. Filter predicates: ownerType, ownerId, status, name ILIKE.

- [ ] **Step 3: Implement `listYachtsForOwner(ownerType, ownerId)`** — queries by polymorphic current owner, used by client detail page.

- [ ] **Step 4: Implement `autocomplete(portId, q)`** — ILIKE match on name + hullNumber + registration, returns top 10.

- [ ] **Step 5: Commit**

```bash
git commit -am "feat(yachts): list + owner-scoped list + autocomplete"
```

### Task 2.6: Service — `companies.service.ts`

**Files:**

- Create: `src/lib/validators/companies.ts`
- Create: `src/lib/services/companies.service.ts`
- Create: `tests/unit/services/companies.test.ts`

- [ ] **Step 1: Validators** — `createCompanySchema`, `updateCompanySchema`, `listCompaniesQuery`. Required: `name`. Optional: `legalName`, `taxId`, `registrationNumber`, `incorporationCountry`, `incorporationDate`, `status`, `billingEmail`, `notes`, `tagIds`.

- [ ] **Step 2: Tests (TDD)** — `createCompany` happy path; case-insensitive name uniqueness (create "Aegean Holdings", then "AEGEAN HOLDINGS" → throws); `upsertByName` returns existing row on case-insensitive match; `archiveCompany` sets archivedAt; all tenant-scoped.

- [ ] **Step 3: Implementation** mirrors yachts.service pattern. Notable: `upsertByName(portId, name)` uses `INSERT ... ON CONFLICT (portId, lower(name)) DO UPDATE SET updatedAt = NOW() RETURNING *` or a SELECT-then-INSERT transaction. Socket: emit `company:created`, `company:updated`, `company:archived`.

- [ ] **Step 4: Run tests, commit**

```bash
git commit -am "feat(companies): service + validators + unit tests"
```

### Task 2.7: Service — `company-memberships.service.ts`

**Files:**

- Create: `src/lib/validators/company-memberships.ts`
- Create: `src/lib/services/company-memberships.service.ts`
- Create: `tests/unit/services/company-memberships.test.ts`

- [ ] **Step 1: Validators** — `addMembershipSchema` (companyId via path, body: clientId, role, roleDetail?, startDate, isPrimary?, notes?). `updateMembershipSchema`. `endMembershipSchema` (endDate).

- [ ] **Step 2: Tests** — `addMembership` creates row; rejects duplicate exact (companyId+clientId+role+startDate via unique constraint); `setPrimary` ensures only one membership-per-company has `isPrimary=true` (enforce in service; unique partial index is `isPrimary=true` per company could also work). `endMembership` sets endDate. `listByCompany` and `listByClient` return active-only by default.

- [ ] **Step 3: Implementation.** `setPrimary` runs in a transaction: un-primary all others for this company, set this one primary. Emit socket events: `company_membership:added`, `company_membership:ended`.

- [ ] **Step 4: Commit**

```bash
git commit -am "feat(company-memberships): service + validators + tests"
```

### Task 2.8: Service — `berth-reservations.service.ts`

**Files:**

- Create: `src/lib/validators/reservations.ts`
- Create: `src/lib/services/berth-reservations.service.ts`
- Create: `tests/unit/services/berth-reservations.test.ts`
- Create: `tests/integration/reservation-exclusivity.test.ts`

- [ ] **Step 1: Validators** — `createPendingSchema`, `activateSchema`, `endReservationSchema`, `cancelSchema`.

- [ ] **Step 2: Unit tests** — lifecycle transitions: pending → active; active → ended; pending → cancelled; active → cancelled; invalid transitions (e.g., ended → active) throw `ValidationError`. Cross-validation: yacht belongs to a client who matches the reservation's clientId (or represents a company that owns the yacht).

- [ ] **Step 3: Integration test** — partial unique `idx_br_active`: two concurrent `activate` attempts on same berth → one succeeds, one throws with distinct error we catch and surface as `ConflictError`.

- [ ] **Step 4: Implementation.** `activate(id)` reads current row, verifies status=pending, updates to active. If DB rejects with unique violation, re-query for the conflicting active row and throw `ConflictError` with that info. Emit `berth_reservation:created|activated|ended|cancelled`.

- [ ] **Step 5: Commit**

```bash
git commit -am "feat(reservations): service + validators + exclusivity tests"
```

### Task 2.9: Service — `eoi-context.ts` (shared EOI payload builder)

**Files:**

- Create: `src/lib/services/eoi-context.ts`
- Create: `tests/unit/services/eoi-context.test.ts`

- [ ] **Step 1: Define the `EoiContext` type**

```typescript
export type EoiContext = {
  client: {
    fullName: string;
    nationality: string | null;
    primaryEmail: string | null;
    primaryPhone: string | null;
    address: { street: string; city: string; country: string } | null;
  };
  yacht: {
    name: string;
    lengthFt: string | null;
    widthFt: string | null;
    draftFt: string | null;
    lengthM: string | null;
    widthM: string | null;
    draftM: string | null;
    hullNumber: string | null;
    flag: string | null;
    yearBuilt: number | null;
  };
  company: {
    name: string;
    legalName: string | null;
    taxId: string | null;
    billingAddress: string | null;
  } | null;
  owner: {
    type: 'client' | 'company';
    name: string;
    legalName?: string;
  };
  berth: {
    mooringNumber: string;
    area: string | null;
    lengthFt: string | null;
    price: string | null;
    priceCurrency: string;
    tenureType: string;
  };
  interest: {
    stage: string;
    leadCategory: string | null;
    dateFirstContact: Date | null;
    notes: string | null;
  };
  port: {
    name: string;
    defaultCurrency: string;
  };
  date: {
    today: string;
    year: string;
  };
};
```

- [ ] **Step 2: Failing tests for `buildEoiContext`**

Scenarios (each should return a correctly-populated context):

- Client-owned yacht
- Company-owned yacht
- Company-owned yacht where interest's client is a company member (verify `client` is the interest's client, `company` is the yacht's owner, `owner.type === 'company'`)
- Missing berth (interest has no berth yet) — context.berth is still populated if linked; otherwise `throw ValidationError('interest has no berth')` (we need berth for EOI)
- Missing yacht (interest has no yacht) — throws

- [ ] **Step 3: Implementation**

Fetches interest + client + primary contact + primary address + yacht + yacht's current owner (polymorphic resolution) + berth + port. Returns fully-populated `EoiContext`.

- [ ] **Step 4: Run tests, commit**

```bash
git commit -am "feat(eoi): shared context builder + tests"
```

### Task 2.10: Create PR 2

- [ ] Push `refactor/data-model`. PR title: `feat(services): yachts, companies, memberships, reservations, EOI context (PR 2 of 15)`.

---

# PR 3 — API Routes and Permissions

**Goal:** Wire every new service to REST endpoints with proper permission gates. Add new permission keys. Every route has an integration test.

### Task 3.1: Add new permission keys

**Files:**

- Modify: `src/lib/auth/permissions.ts` (or wherever permission keys are declared)
- Modify: seed for default roles (`src/lib/db/seed.ts`) or role-update migration

- [ ] **Step 1: Add the following keys to the permissions enum/list:**

```
yachts:view
yachts:write
yachts:transfer
yachts:delete
companies:view
companies:write
companies:delete
memberships:write
reservations:view
reservations:write
```

- [ ] **Step 2: Update default role assignments**

In whichever migration/seed owns the default role configuration:

- `admin`: add all new keys
- `team_lead`: `yachts:view`, `yachts:write`, `companies:view`, `companies:write`, `memberships:write`, `reservations:view`
- `front_desk`: all `:view` keys

- [ ] **Step 3: Test** — verify `requirePermission(context, 'yachts:transfer')` succeeds for admin, throws for team_lead.

- [ ] **Step 4: Commit**

```bash
git commit -am "feat(permissions): add yacht, company, membership, reservation keys"
```

### Task 3.2: Yacht API routes — list + create

**Files:**

- Create: `src/app/api/v1/yachts/route.ts`
- Create: tests alongside

- [ ] **Step 1: Write route integration test**

```typescript
// tests/integration/api/yachts.test.ts
import { describe, it, expect } from 'vitest';
import { testFetch, makeTestSession } from 'tests/helpers/api';
import { makeClient, makePort } from 'tests/helpers/factories';

describe('POST /api/v1/yachts', () => {
  it('creates a yacht when user has yachts:write', async () => {
    const { port, session } = await makeTestSession({ permissions: ['yachts:write'] });
    const client = await makeClient({ portId: port.id });

    const res = await testFetch('POST', '/api/v1/yachts', {
      session,
      body: { name: 'Sea Breeze', owner: { type: 'client', id: client.id } },
    });
    expect(res.status).toBe(201);
    const body = await res.json();
    expect(body.name).toBe('Sea Breeze');
  });

  it('rejects when user lacks yachts:write', async () => {
    const { port, session } = await makeTestSession({ permissions: ['yachts:view'] });
    const client = await makeClient({ portId: port.id });

    const res = await testFetch('POST', '/api/v1/yachts', {
      session,
      body: { name: 'Sea Breeze', owner: { type: 'client', id: client.id } },
    });
    expect(res.status).toBe(403);
  });

  it('returns 400 on invalid body', async () => {
    const { session } = await makeTestSession({ permissions: ['yachts:write'] });
    const res = await testFetch('POST', '/api/v1/yachts', { session, body: { name: '' } });
    expect(res.status).toBe(400);
  });
});
```

- [ ] **Step 2: Implement route**

```typescript
// src/app/api/v1/yachts/route.ts
import { NextRequest } from 'next/server';
import { withContext } from '@/lib/api/route-helpers';
import { requirePermission } from '@/lib/auth/permissions';
import { createYachtSchema, listYachtsQuery } from '@/lib/validators/yachts';
import { createYacht, listYachts } from '@/lib/services/yachts.service';

export async function GET(req: NextRequest) {
  return withContext(req, async (ctx) => {
    requirePermission(ctx, 'yachts:view');
    const query = listYachtsQuery.parse(Object.fromEntries(req.nextUrl.searchParams));
    const result = await listYachts(ctx.portId, query);
    return Response.json(result);
  });
}

export async function POST(req: NextRequest) {
  return withContext(req, async (ctx) => {
    requirePermission(ctx, 'yachts:write');
    const body = createYachtSchema.parse(await req.json());
    const yacht = await createYacht(ctx.portId, body, ctx.auditMeta);
    return Response.json(yacht, { status: 201 });
  });
}
```

- [ ] **Step 3: Run tests, commit**

```bash
git commit -am "feat(api): GET/POST /api/v1/yachts"
```

### Task 3.3: Yacht API routes — detail, update, archive, transfer, history

**Files:**

- Create: `src/app/api/v1/yachts/[id]/route.ts` — GET, PATCH, DELETE
- Create: `src/app/api/v1/yachts/[id]/transfer/route.ts` — POST
- Create: `src/app/api/v1/yachts/[id]/ownership-history/route.ts` — GET
- Create: `src/app/api/v1/yachts/autocomplete/route.ts` — GET

- [ ] **Step 1: Tests for each — mirror Task 3.2's pattern.** Specifically test that `PATCH` rejects owner-mutation (`use /transfer to change ownership`), that `POST /transfer` requires `yachts:transfer` (not just `:write`).

- [ ] **Step 2: Implementations.**

- [ ] **Step 3: Commit**

```bash
git commit -am "feat(api): yacht detail, patch, archive, transfer, history, autocomplete"
```

### Task 3.4: Company API routes

**Files:**

- Create: `src/app/api/v1/companies/route.ts`
- Create: `src/app/api/v1/companies/autocomplete/route.ts`
- Create: `src/app/api/v1/companies/[id]/route.ts`

- [ ] **Steps:** Follow Task 3.2-3.3 pattern for GET list/create, detail/patch/archive, autocomplete.

- [ ] **Commit** after full file set works.

### Task 3.5: Company memberships API

**Files:**

- Create: `src/app/api/v1/companies/[id]/members/route.ts` — GET list, POST add
- Create: `src/app/api/v1/companies/[id]/members/[mid]/route.ts` — PATCH, DELETE

- [ ] **Steps:** `POST` requires `memberships:write`. `DELETE` sets endDate (soft). Test that a non-existent companyId returns 404 before permission check (avoid info leak? Actually 403 vs 404 is fine here; 404 after scoping).

- [ ] **Commit.**

### Task 3.6: Berth reservations API

**Files:**

- Create: `src/app/api/v1/berths/[id]/reservations/route.ts`
- Create: `src/app/api/v1/berth-reservations/[id]/route.ts`

- [ ] **Steps:** `POST /berths/:id/reservations` creates pending. `PATCH /berth-reservations/:id` with body `{ action: 'activate' | 'end' | 'cancel', ...details }` performs state transition. Test every transition + invalid transitions → 400.

- [ ] **Commit.**

### Task 3.7: Socket + webhook event wiring

**Files:**

- Modify: `src/lib/services/webhooks.ts` (or wherever the event map lives)
- Modify: any socket event declaration file

- [ ] **Step 1: Add new event names to the webhook event map**

Events: 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.

- [ ] **Step 2: Update `tests/unit/webhook-event-map.test.ts`** to assert every new event is in the catalog.

- [ ] **Step 3: Verify socket events are emitted by services** (already implemented in PR 2; spot-check).

- [ ] **Step 4: Commit**

```bash
git commit -am "feat(events): register yacht, company, membership, reservation events"
```

### Task 3.8: Create PR 3

- [ ] Push + PR title: `feat(api): new endpoints for yachts, companies, memberships, reservations (PR 3 of 15)`.

---

# PR 4 — Seeder Rewrite

**Goal:** `pnpm db:seed` produces realistic multi-cardinality fixtures that exercise every relationship the refactor introduces.

### Task 4.1: Extend factory helpers

**Files:**

- Modify: `tests/helpers/factories.ts`

- [ ] **Step 1: Add factories (if not already added in PR 1-2):**

```typescript
export async function makeCompany(args: { portId: string; overrides?: Partial<NewCompany> }) { ... }

export async function makeMembership(args: {
  companyId: string;
  clientId: string;
  role?: string;
  startDate?: Date;
  endDate?: Date | null;
  isPrimary?: boolean;
}) { ... }

export async function makeReservation(args: {
  berthId: string;
  clientId: string;
  yachtId: string;
  status: 'pending' | 'active' | 'ended' | 'cancelled';
  startDate?: Date;
  endDate?: Date | null;
}) { ... }

export async function makeOwnershipTransfer(args: {
  yachtId: string;
  fromOwner: { type; id };
  toOwner: { type; id };
  date: Date;
}) { ... }  // closes existing, opens new
```

- [ ] **Step 2: Commit**

### Task 4.2: Rewrite `src/lib/db/seed.ts`

**Files:**

- Modify: `src/lib/db/seed.ts`

- [ ] **Step 1: Replace the seed with the scenarios defined in the spec**

Creates (per port):

- 3 companies: Aegean Holdings (active, 3 members), Blue Seas Marine (active, 1 member), Phantom SA (dissolved, all memberships ended)
- 8 clients: 3 personal-only, 2 members of one company, 2 members of two companies, 1 who's a member of the dissolved company
- 12 yachts: 7 client-owned (across the 8 clients), 5 company-owned (across 2 active companies). 3 yachts have a completed ownership transfer in history (e.g., from a client to a company).
- ~15 interests distributed across clients/yachts/berths with pipeline-stage variety
- 5 active berth reservations (one per owning client); 2 ended reservations with realistic historical dates; 1 cancelled
- Rich contact data: every client has 1-3 contacts (email + optional phone); every yacht has registration data; every company has a billing address

- [ ] **Step 2: Seed uses the factory helpers** — no bespoke DB calls in `seed.ts`.

- [ ] **Step 3: Run seed + verify**

```bash
pnpm db:push && pnpm db:seed
pnpm db:studio
# Eyeball: yachts table has 12 rows across the 3 seeded ports; company_memberships shows realistic distribution
```

- [ ] **Step 4: Commit**

```bash
git commit -am "feat(seed): rewrite seed for multi-cardinality refactor"
```

### Task 4.3: Create PR 4

- [ ] Push, title: `feat(seed): multi-cardinality dummy data (PR 4 of 15)`.

---

# PR 5 — Yacht UI

**Goal:** List, detail, create, edit, transfer, archive — all from the UI. Every button has a Playwright test in PR 14.

### Task 5.1: Base components — `yacht-picker`, `owner-picker`

**Files:**

- Create: `src/components/shared/owner-picker.tsx`
- Create: `src/components/yachts/yacht-picker.tsx`

- [ ] **Step 1: `owner-picker.tsx`**

Polymorphic combobox. Props: `value: { type: 'client' | 'company'; id: string } | null`, `onChange`, `portId`. Toggle at top: `[Client] [Company]`. Below: autocomplete backed by `/api/v1/clients/autocomplete` or `/api/v1/companies/autocomplete` depending on toggle.

- [ ] **Step 2: `yacht-picker.tsx`**

Autocomplete combobox wrapping `/api/v1/yachts/autocomplete`. Props: `value: string | null`, `onChange`, `portId`, `ownerFilter?: { type; id }` (for interest form — filter to the interest's client's yachts).

- [ ] **Step 3: Simple unit-level sanity: render with empty state, render with a value, change event fires.**

- [ ] **Step 4: Commit.**

### Task 5.2: Yacht form + validator wiring

**Files:**

- Create: `src/components/yachts/yacht-form.tsx`

- [ ] **Step 1: Implement form** using `react-hook-form` + `@hookform/resolvers/zod` with `createYachtSchema`. Fields: name (required), dimensions (ft + m), hull/registration/flag/yearBuilt/builder/model/material, owner (via `owner-picker`), status, notes.

- [ ] **Step 2: Submit handler** POSTs to `/api/v1/yachts`; on success, close dialog / navigate to detail. On 400, show field errors.

- [ ] **Step 3: Commit.**

### Task 5.3: Yacht detail page + tabs + ownership history

**Files:**

- Create: `src/components/yachts/yacht-detail.tsx`
- Create: `src/components/yachts/yacht-detail-header.tsx`
- Create: `src/components/yachts/yacht-tabs.tsx`
- Create: `src/components/yachts/yacht-ownership-history.tsx`
- Create: `src/app/(dashboard)/[portSlug]/yachts/[yachtId]/page.tsx`

- [ ] **Step 1: Page** — server component that fetches yacht detail (plus eager loads: ownershipHistory, reservations, notes, tags, documents, interests). Passes to `<YachtDetail />`.

- [ ] **Step 2: `yacht-detail-header`** — name + dimensions + current-owner link + status badge + Edit / Archive / Transfer buttons.

- [ ] **Step 3: `yacht-tabs`** — tabs: Overview, Ownership History, Interests, Reservations, Documents, Notes, Tags. Uses existing shadcn tabs component.

- [ ] **Step 4: `yacht-ownership-history`** — table: start date, end date (or "Current"), owner (with link), reason, notes.

- [ ] **Step 5: Commit.**

### Task 5.4: Yacht list page + columns

**Files:**

- Create: `src/components/yachts/yacht-columns.tsx`
- Create: `src/app/(dashboard)/[portSlug]/yachts/page.tsx`

- [ ] **Step 1: Columns** — name, current owner (link, polymorphic), dimensions (LxW ft), status badge, actions (view, archive).

- [ ] **Step 2: Page** — uses TanStack Table + existing list patterns. Filter UI: owner type select, status select, free-text search.

- [ ] **Step 3: Commit.**

### Task 5.5: Yacht transfer dialog

**Files:**

- Create: `src/components/yachts/yacht-transfer-dialog.tsx`

- [ ] **Step 1: Dialog** with form: `owner-picker`, effective date, reason (select), notes (textarea), optional deed/sale-doc upload (file input → MinIO via existing upload flow).

- [ ] **Step 2: Submit** calls `POST /api/v1/yachts/:id/transfer`. On success, emits local event to refetch ownership history; toast "Transferred successfully"; closes dialog.

- [ ] **Step 3: Commit.**

### Task 5.6: Nav entry + create-yacht flow

**Files:**

- Modify: `src/components/layout/sidebar.tsx` (or wherever nav is defined)

- [ ] **Step 1: Add `Yachts` sidebar entry** with icon (lucide: `Anchor`) linked to `/[portSlug]/yachts`.

- [ ] **Step 2: On the list page, "Create yacht" button** opens a dialog with `<YachtForm />`.

- [ ] **Step 3: Commit.**

### Task 5.7: Create PR 5

---

# PR 6 — Company UI

**Goal:** List, detail (with members + owned yachts), create, edit, archive. Add membership dialog. Uses existing shadcn patterns.

### Task 6.1: Base — `company-picker`

**Files:**

- Create: `src/components/companies/company-picker.tsx`

- [ ] **Step 1:** Autocomplete wrapping `/api/v1/companies/autocomplete`.
- [ ] **Step 2: Commit.**

### Task 6.2: Company form

**Files:**

- Create: `src/components/companies/company-form.tsx`

- [ ] **Step 1:** Form fields: name, legalName, taxId, registrationNumber, incorporationCountry, incorporationDate, status, billingEmail, notes, tagIds. Case-insensitive uniqueness is enforced server-side — show the 409 error as a form-level error.
- [ ] **Step 2: Commit.**

### Task 6.3: Company detail + tabs

**Files:**

- Create: `src/components/companies/company-detail.tsx`
- Create: `src/components/companies/company-detail-header.tsx`
- Create: `src/components/companies/company-tabs.tsx`
- Create: `src/components/companies/company-members-tab.tsx`
- Create: `src/components/companies/company-owned-yachts-tab.tsx`
- Create: `src/app/(dashboard)/[portSlug]/companies/[companyId]/page.tsx`

- [ ] **Step 1: Page + detail shell + header.**
- [ ] **Step 2: Tabs:** Overview, Members (active + past toggle), Owned Yachts, Addresses, Documents, Notes, Tags.
- [ ] **Step 3: Members tab:** list with client link + role + dates. "Add member" button opens `add-membership-dialog`. "End membership" button on active rows.
- [ ] **Step 4: Owned yachts tab:** server-queries yachts where `currentOwnerType='company'` AND `currentOwnerId=<this>`. Table: yacht name, dimensions, status, link to yacht detail.
- [ ] **Step 5: Commit.**

### Task 6.4: Add-membership dialog

**Files:**

- Create: `src/components/companies/add-membership-dialog.tsx`

- [ ] **Step 1:** Form: client combobox (existing `ClientPicker` if present, else implement), role select, roleDetail, startDate, isPrimary toggle, notes.
- [ ] **Step 2:** Submit → `POST /api/v1/companies/:id/members`. On 409 (duplicate exact), show "This membership already exists".
- [ ] **Step 3: Commit.**

### Task 6.5: Company list page + columns + nav

**Files:**

- Create: `src/components/companies/company-columns.tsx`
- Create: `src/app/(dashboard)/[portSlug]/companies/page.tsx`
- Modify: sidebar config

- [ ] **Step 1: Columns:** name, legalName, # active members, # owned yachts, status.
- [ ] **Step 2: Page + sidebar entry** (`Building2` lucide icon).
- [ ] **Step 3: Commit.**

### Task 6.6: Create PR 6

---

# PR 7 — Berth Reservations UI + Ownership Wiring

**Goal:** Berth detail surfaces reservations; reserve and ownership-transfer dialogs are end-to-end wired.

### Task 7.1: `reservation-list` component

**Files:**

- Create: `src/components/reservations/reservation-list.tsx`

- [ ] **Step 1:** Table: client link, yacht link, date range, status badge, tenure type, contract file link. Props: `reservations: BerthReservation[]`, `showBerth?: boolean`.
- [ ] **Step 2: Commit.**

### Task 7.2: `berth-reserve-dialog`

**Files:**

- Create: `src/components/reservations/berth-reserve-dialog.tsx`

- [ ] **Step 1:** Form: client combobox, yacht combobox (filtered to client's yachts; includes "Add new yacht" inline shortcut), startDate, endDate, tenureType, contract file upload.
- [ ] **Step 2:** Submit → `POST /api/v1/berths/:id/reservations` (creates pending). Second button "Create and activate" → creates pending then immediately PATCHes to active; on 409 (duplicate active), surface the existing active reservation as an error.
- [ ] **Step 3: Commit.**

### Task 7.3: Berth detail — add reservations tab

**Files:**

- Modify: `src/components/berths/berth-detail.tsx` (or equivalent)
- Modify: `src/components/berths/berth-tabs.tsx`

- [ ] **Step 1:** Add "Reservations" tab. Content: active reservation card (or "No active reservation") + "Reserve this berth" button + history table below.
- [ ] **Step 2: Commit.**

### Task 7.4: Create PR 7

---

# PR 8 — Client Form Refactor

**Goal:** Strip yacht/company/proxy fields from the client form. Clean person-only form. Yacht + company management moves to detail page tabs.

### Task 8.1: Update validator

**Files:**

- Modify: `src/lib/validators/clients.ts`

- [ ] **Step 1: Remove fields** from `createClientSchema`:
  - `companyName`, `isProxy`, `proxyType`, `actualOwnerName`, `relationshipNotes`
  - `yachtName`, `yachtLengthFt/WidthFt/DraftFt`, `yachtLengthM/WidthM/DraftM`, `berthSizeDesired`

- [ ] **Step 2: Update tests** in `tests/unit/validators.test.ts`. Add assertions that deprecated fields are rejected (or just ignored — depends on your preference; `z.object.strict()` would reject; default `z.object` ignores unknown). Prefer `.strict()` for safety.

- [ ] **Step 3: Commit.**

### Task 8.2: Update `clients.service.ts`

**Files:**

- Modify: `src/lib/services/clients.service.ts`

- [ ] **Step 1: Remove all references** to the deleted fields in create/update/diff/response shaping.

- [ ] **Step 2: Extend `getClientById`** to return `yachts` (via polymorphic query), `companies` (via active memberships), `activeReservations`.

- [ ] **Step 3: Update service unit tests** to reflect new shape.

- [ ] **Step 4: Commit.**

### Task 8.3: Refactor client form UI

**Files:**

- Modify: `src/components/clients/client-form.tsx`

- [ ] **Step 1: Remove fields** yacht/company/proxy; keep: name, contacts, nationality, preferred contact method/language, timezone, source, sourceDetails, tagIds.

- [ ] **Step 2: Commit.**

### Task 8.4: Refactor client detail — add new tabs

**Files:**

- Modify: `src/components/clients/client-detail.tsx`
- Modify: `src/components/clients/client-tabs.tsx`

- [ ] **Step 1:** New tabs:
  - **Yachts** — list of client-owned yachts + "Add yacht" button (opens `YachtForm` pre-filled owner=this client). Also shows yachts represented via company memberships (read-only link).
  - **Companies** — list of active memberships: company link, role, since date, "Set primary", "End membership" buttons. "Add membership" opens dialog.
  - **Reservations** — list of active + historical reservations via `reservation-list`.

- [ ] **Step 2: Remove** the old "Yacht details" and "Proxy" sections from Overview tab.

- [ ] **Step 3: Update `client-columns.tsx`:** replace yacht/company text columns with "# yachts" and "Primary company" (from active memberships with `isPrimary=true`).

- [ ] **Step 4: Commit.**

### Task 8.5: Update `portal.service.ts` + portal UI

**Files:**

- Modify: `src/lib/services/portal.service.ts`
- Modify: `src/app/(portal)/portal/dashboard/page.tsx`
- Create: `src/app/(portal)/portal/my-yachts/page.tsx`
- Create: `src/app/(portal)/portal/my-reservations/page.tsx`

- [ ] **Step 1: `portal.service.ts`** — add these functions:
  - `getPortalUserYachts(clientId, portId)` — returns yachts where `currentOwnerType='client' AND currentOwnerId=clientId`, PLUS yachts owned by any company where the client has an active `company_membership`. De-duped.
  - `getPortalUserMemberships(clientId, portId)` — active memberships for the portal client.
  - `getPortalUserReservations(clientId, portId)` — active + upcoming reservations.

- [ ] **Step 2: Unit tests** for each — cover client-owned, company-represented, and dedup cases.

- [ ] **Step 3: Dashboard update** — add three new cards: "My Yachts", "My Memberships", "My Active Reservations".

- [ ] **Step 4: New pages** — `my-yachts` lists yachts with read-only detail; `my-reservations` lists reservations.

- [ ] **Step 5: E2E test** — portal user with one client-owned + one company-owned yacht sees exactly two yachts in "My Yachts", not four.

- [ ] **Step 6: Commit.**

```bash
git commit -am "feat(portal): surface yachts, memberships, reservations for portal users"
```

### Task 8.6: Create PR 8

---

# PR 9 — Interest Form + Public Interest Form + Search + Recommendations

**Goal:** Interest form requires `yachtId`. Public interest form creates client + yacht + optional company + membership + interest as a trio.

### Task 9.1: Update interest validator + service

**Files:**

- Modify: `src/lib/validators/interests.ts`
- Modify: `src/lib/services/interests.service.ts`

- [ ] **Step 1:** Validator: `yachtId` — nullable on create (for stage=open), required before leaving stage=open. Service enforces: reject promote-to-next-stage if `yachtId` is null.

- [ ] **Step 2:** Service validates yacht belongs to the interest's client OR is owned by a company that the client actively represents. `ValidationError` otherwise.

- [ ] **Step 3: Tests + commit.**

### Task 9.2: Update interest form UI

**Files:**

- Modify: `src/components/interests/interest-form.tsx`

- [ ] **Step 1: Add `yacht-picker`** — filtered to the interest's client (plus company-owned yachts for companies the client represents). Inline "Add new yacht" shortcut opens yacht-form dialog.

- [ ] **Step 2: Commit.**

### Task 9.3: Update public interest form

**Files:**

- Modify: `src/app/api/public/interests/route.ts`

- [ ] **Step 1:** Extend request body to include yacht fields and optional company fields (separated from client fields).

- [ ] **Step 2: Service changes** (can live in a helper): in one transaction, `createClient` + `createYacht` (owner = the new client) + optional `upsertCompany` + `addMembership` + `createInterest` (with yachtId, berthId if provided). All marked `source: 'public_submission'`.

- [ ] **Step 3: Update public interest form UI** to match new body shape.

- [ ] **Step 4: E2E test** — submit the public form; admin sees four new rows (client + yacht + optional company + interest) in the appropriate lists.

- [ ] **Step 5: Commit.**

### Task 9.4: Update `search.service.ts` — index yachts and companies

**Files:**

- Modify: `src/lib/services/search.service.ts`
- Modify: `src/hooks/use-search.ts`
- Modify: `src/components/search/search-result-item.tsx`
- Modify: `src/components/search/command-search.tsx`

- [ ] **Step 1: Extend search** to query yachts (name, hullNumber, registration) and companies (name, legalName, taxId) alongside clients. Each result carries a `type: 'client' | 'yacht' | 'company' | 'interest' | 'berth'` tag.

- [ ] **Step 2: Update UI** — result-item variants per type (distinct icon per entity); clicking routes to the correct detail page.

- [ ] **Step 3: Unit test `search.service.ts`** — search term matching against seeded yachts and companies returns correct results with type tags.

- [ ] **Step 4: E2E test** — global search for a yacht name returns yacht result; clicking navigates to yacht detail.

- [ ] **Step 5: Commit.**

```bash
git commit -am "feat(search): index yachts and companies alongside clients"
```

### Task 9.5: Update `recommendations.ts` — yacht dims from yachts table

**Files:**

- Modify: `src/lib/services/recommendations.ts`

- [ ] **Step 1: Update berth-fit logic** — currently reads yacht dimensions from `clients.yacht*` fields. Switch to reading from `yachts` table via `interest.yachtId`.

- [ ] **Step 2: Unit test** — generate berth recommendations for an interest whose yacht has known dimensions; verify the matcher respects them.

- [ ] **Step 3: Commit.**

```bash
git commit -am "feat(recommendations): read yacht dimensions from yachts table"
```

### Task 9.6: Create PR 9

---

# PR 10 — Invoice Billing Entity

**Goal:** Invoices reference a polymorphic billing entity (client or company). `clientName` remains as a snapshot.

### Task 10.1: Update validators + service

**Files:**

- Modify: `src/lib/validators/invoices.ts`
- Modify: `src/lib/services/invoices.service.ts`

- [ ] **Step 1: Validator:** add `billingEntityType`, `billingEntityId`. Remove reliance on `clientName` for creation (it becomes a snapshot derived from the entity at create time).

- [ ] **Step 2: Service:** on create, look up entity (client or company), copy its display name into `clientName`. Validate cross-tenant.

- [ ] **Step 3: Tests + commit.**

### Task 10.2: Update invoice form UI

**Files:**

- Modify: `src/components/invoices/invoice-form.tsx`

- [ ] **Step 1: Add `billing-entity-picker`** at the top of the form. Selecting an entity populates `clientName` + `billingEmail` + `billingAddress` from the entity.
- [ ] **Step 2: Commit.**

### Task 10.3: Create PR 10

---

# PR 11 — EOI Dual-Path + Shared Payload Builder

**Goal:** Both Documenso and in-app paths wired end-to-end; UI picker chooses. Standard EOI template seeded for in-app.

### Task 11.1: Audit Documenso template field names

**Files:**

- Create: `docs/eoi-documenso-field-mapping.md`

- [ ] **Step 1: Read the old system's `client-portal/server/api/eoi/generate-quick-eoi.ts`** and enumerate every field name the Documenso template expects (look at the POST body of `/api/v1/templates/{id}/generate-document`).

- [ ] **Step 2: Document each field in the new doc:** field name → schema source (e.g., `clientFullName → client.fullName`, `yachtLength → yacht.lengthFt`).

- [ ] **Step 3: Commit this doc** — it's the reference for Spec 2's importer too.

```bash
git add docs/eoi-documenso-field-mapping.md
git commit -m "docs(eoi): document Documenso template field name mapping"
```

### Task 11.2: Documenso payload builder

**Files:**

- Modify: `src/lib/services/documenso-client.ts` (or create `src/lib/services/documenso-payload.ts`)

- [ ] **Step 1: Write test:** given an `EoiContext`, `buildDocumensoPayload(context)` returns the flat payload Documenso expects.

- [ ] **Step 2: Implement** using the field mapping from Task 11.1.

- [ ] **Step 3: Integration test** (with mocked Documenso API): generate an EOI through the service, assert the POST body contains every mapped field.

- [ ] **Step 4: Commit.**

### Task 11.3: Seed in-app Standard EOI template

**Files:**

- Create: `src/lib/pdf/templates/eoi-standard-inapp.ts` — exports `getStandardEoiTemplateHtml()`
- Modify: `src/lib/db/seed.ts` — also insert a `document_templates` row per port with this HTML

- [ ] **Step 1: Write the HTML template** using the token namespace defined in spec: `{{client.fullName}}`, `{{yacht.name}}`, `{{yacht.lengthFt}}`, `{{company.name}}`, `{{company.legalName}}`, `{{berth.mooringNumber}}`, `{{interest.dateFirstContact}}`, `{{port.name}}`, `{{date.today}}`, etc. Mirror the structure of the Documenso EOI (a developer should review it side-by-side with the old EOI).

- [ ] **Step 2: Seeder inserts one row per port** referencing this template. Template type: `'eoi'`. `isActive: true`. Name: "Standard EOI (in-app)".

- [ ] **Step 3: Commit.**

### Task 11.4: Extend `resolveTemplate` to new scopes

**Files:**

- Modify: `src/lib/services/document-templates.ts`

- [ ] **Step 1: Update `MERGE_FIELDS`** — remove old `{{client.yachtName}}`, `{{client.companyName}}`, and yacht dimension tokens; add new `yacht`, `company`, `owner` sections.

- [ ] **Step 2: Extend `resolveTemplate()`** — when context includes `interestId`, resolve via `buildEoiContext` and substitute `{{yacht.*}}` / `{{company.*}}` / `{{owner.*}}` tokens.

- [ ] **Step 3: Unit tests** for every new token resolving correctly.

- [ ] **Step 4: Commit.**

### Task 11.5: EOI generation — dual-path service

**Files:**

- Modify: `src/lib/services/document-templates.ts` — `generateAndSign` gains a `pathway: 'documenso-template' | 'inapp'` parameter

- [ ] **Step 1: Test** — for each pathway, generate an EOI for a seeded interest, verify the resulting file exists in MinIO and the `documents` row is created with correct metadata.

- [ ] **Step 2: Implement** — if `pathway === 'documenso-template'`, call Documenso template-generate. Else, resolve in-app template → pdfme → upload PDF → optionally pass to Documenso for signing via existing `documensoCreate` + `documensoSend`.

- [ ] **Step 3: Commit.**

### Task 11.6: EOI-generate dialog UI

**Files:**

- Modify: (wherever the existing EOI-generate UI lives in `src/components/interests/` or `src/app/(dashboard)/[portSlug]/interests/`)

- [ ] **Step 1: Add template dropdown** — list: Documenso Standard EOI + seeded in-app templates. Preview shows which context fields will be filled.

- [ ] **Step 2: Submit** calls the dual-path service with the chosen pathway.

- [ ] **Step 3: Commit.**

### Task 11.7: Create PR 11

---

# PR 12 — Merge-Field Catalog Cleanup

**Goal:** Any stale references to old tokens (`{{client.yachtName}}`, etc.) are removed from the codebase, seeded templates, and validator allow-lists. All remaining tokens route through the new schema.

### Task 12.1: Remove stale tokens

**Files:**

- Modify: anywhere `{{client.yachtName|yachtLength|companyName}}` appears in code or seed data

- [ ] **Step 1: `rg -n '{{client\\.(yacht|companyName)'` across the repo** — verify only historical seed data / test fixtures remain (code paths should be updated).

- [ ] **Step 2: Update or remove all matches.** Any remaining template in the seeder should use new tokens.

- [ ] **Step 3: Commit.**

### Task 12.2: Validator tightening

**Files:**

- Modify: `src/lib/validators/document-templates.ts`

- [ ] **Step 1:** If there's a token allow-list, update it to match the new `MERGE_FIELDS` structure. Unknown tokens rejected at creation time.

- [ ] **Step 2: Commit.**

### Task 12.3: Create PR 12

---

# PR 13 — Drop Old Columns from `clients`

**Goal:** With all reads migrated, drop the deprecated columns.

### Task 13.1: Drop columns

**Files:**

- Modify: `src/lib/db/schema/clients.ts`

- [ ] **Step 1: Remove column definitions:** `yachtName`, `yachtLengthFt`, `yachtWidthFt`, `yachtDraftFt`, `yachtLengthM`, `yachtWidthM`, `yachtDraftM`, `berthSizeDesired`, `companyName`, `isProxy`, `proxyType`, `actualOwnerName`, `relationshipNotes`.

- [ ] **Step 2: `pnpm db:generate && pnpm db:push`** — generates a destructive migration (column drops).

- [ ] **Step 3: Run full test suite** — verify no silent breakage.

```bash
pnpm vitest run
pnpm playwright test tests/e2e/scenarios
```

- [ ] **Step 4: Commit.**

```bash
git commit -am "refactor(clients): drop deprecated yacht/company/proxy columns"
```

### Task 13.2: Verify no callers remain

**Files:**

- N/A (exploration)

- [ ] **Step 1: `rg -n 'yachtName|companyName|isProxy|proxyType|actualOwnerName|relationshipNotes|berthSizeDesired' src/`** — should return zero matches in code (tests may reference old column names in assertions that should also have been removed).

- [ ] **Step 2: If matches remain, clean them up in this PR.**

- [ ] **Step 3: Commit.**

### Task 13.3: Create PR 13

---

# PR 14 — Exhaustive Click-Through Suite (Tier 3.5)

**Goal:** Every interactive element on every new or changed page has been clicked and verified to not throw.

### Task 14.1: `click-everything` helper

**Files:**

- Create: `tests/helpers/click-everything.ts`

- [ ] **Step 1: Implement helper**

```typescript
import { Page } from '@playwright/test';

export async function clickEverythingOnPage(
  page: Page,
  opts?: {
    skip?: string[]; // CSS selectors to skip (destructive actions)
    cleanupBetween?: () => Promise<void>;
  },
): Promise<{ clicked: number; skipped: number; errors: string[] }> {
  // Record starting URL so we can return after click-caused navigation
  const startingUrl = page.url();
  const errors: string[] = [];
  let clicked = 0;
  let skipped = 0;

  // Attach console error listener
  page.on('console', (msg) => {
    if (msg.type() === 'error') errors.push(`[console] ${msg.text()}`);
  });
  page.on('response', async (resp) => {
    if (resp.status() >= 400) errors.push(`[network] ${resp.status()} ${resp.url()}`);
  });

  const elements = await page.locator(':is(button, a, [role="button"])').all();
  for (const el of elements) {
    const selector = (await el.evaluate((n) => (n as HTMLElement).outerHTML)).slice(0, 120);
    if (opts?.skip?.some((s) => selector.includes(s))) {
      skipped++;
      continue;
    }
    try {
      if (await el.isVisible()) {
        await el.click({ timeout: 2000 });
        clicked++;
        await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {});
        // Close any opened dialog
        const closeBtn = page.locator('[role="dialog"] [aria-label="Close"]').first();
        if (await closeBtn.isVisible()) await closeBtn.click();
        // If navigation happened, return to starting URL
        if (page.url() !== startingUrl) await page.goto(startingUrl);
        if (opts?.cleanupBetween) await opts.cleanupBetween();
      }
    } catch (err) {
      errors.push(`[click] ${selector} → ${(err as Error).message}`);
    }
  }

  return { clicked, skipped, errors };
}
```

- [ ] **Step 2: Commit.**

### Task 14.2-14.10: Per-domain exhaustive spec files

For each of: `yachts`, `companies`, `reservations`, `client-detail-refactored`, `eoi-generate`, `invoice-form`, `berths-with-reservations`, `portal`, `navigation`:

- [ ] **Step 1: Create `tests/e2e/exhaustive/<domain>.spec.ts`**

Template (instantiate per domain):

```typescript
import { test, expect } from '@playwright/test';
import { clickEverythingOnPage } from '../../helpers/click-everything';
import { loginAs, seedScenario } from '../../helpers/e2e';

test.describe('exhaustive: yachts', () => {
  test('list page', async ({ page }) => {
    await loginAs(page, 'admin');
    await seedScenario(page, 'multi-yacht-client');
    await page.goto('/port-1/yachts');

    const result = await clickEverythingOnPage(page, {
      skip: ['data-testid="archive"', 'data-testid="delete"'], // destructive
    });

    expect(result.errors).toEqual([]);
    expect(result.clicked).toBeGreaterThanOrEqual(
      (await page.locator(':is(button, a, [role="button"])').count()) - result.skipped,
    );
  });

  test('detail page — every tab and every button', async ({ page }) => {
    /* similar shape, navigate to /yachts/<id>, clickEverything, assert */
  });
});
```

- [ ] **Step 2: Per domain:** instantiate for list + detail + every sub-page, including the ownership-transfer dialog (open + fill + cancel — actual transfer happens in a separate destructive test).

- [ ] **Step 3: Run all exhaustive specs, confirm zero errors.**

- [ ] **Step 4: Commit after each domain** (not all at once — keep PR digestible).

### Task 14.11: Destructive-action narrow tests

**Files:**

- Create: `tests/e2e/destructive/<several>.spec.ts`

- [ ] For each action in the allowlist (yachts.delete, yachts.transfer, companies.delete, memberships.end, reservations.cancel, reservations.end, invoices.delete), write a narrow test that:
  - Creates a throwaway entity via API
  - Performs the destructive action via UI
  - Verifies the effect (archived, status changed, etc.)

- [ ] **Commit.**

### Task 14.12: CI config update

**Files:**

- Modify: `.github/workflows/*` (or whichever CI file runs Playwright)

- [ ] **Step 1: Add a separate CI job** that runs `pnpm playwright test tests/e2e/exhaustive`. Sequential with the other Playwright job (shared test DB), but its own pass/fail summary.

- [ ] **Step 2: Commit.**

### Task 14.13: Create PR 14

---

# PR 15 — Documentation + Final Merge

**Goal:** Update spec files, CLAUDE.md, and open the final merge to `main`.

### Task 15.1: Update numbered spec files

**Files:**

- Modify: `01-CONSOLIDATED-SYSTEM-SPEC.md`, `02-*.md`, … (in repo root)

- [ ] **Step 1:** Spot-check each numbered spec file for references to the old data model (yacht fields on client, `companyName`, proxy fields). Update any mentions.

- [ ] **Step 2: Add a reference** in the system spec to the new yacht/company/reservation tables and their roles.

- [ ] **Step 3: Commit.**

### Task 15.2: Update CLAUDE.md

**Files:**

- Modify: `CLAUDE.md`

- [ ] **Step 1:** Update the "Conventions" and "Project structure" sections to mention the new schema files (`yachts.ts`, `companies.ts`, `reservations.ts`) and component directories.

- [ ] **Step 2: Commit.**

### Task 15.3: Tier 4 golden-image template regression

**Files:**

- Create: `tests/e2e/templates/eoi-golden-image.spec.ts`
- Create: `tests/e2e/fixtures/eoi-golden/*.pdf`

- [ ] **Step 1:** For each Tier 3 E2E scenario that generates an EOI, render the in-app PDF, compare against a committed reference PDF using a visual-diff library (e.g., `pixelmatch` or `playwright`'s built-in screenshot comparison). First time through, the PDFs are generated manually and committed as the golden set.

- [ ] **Step 2: Commit.**

### Task 15.4: Merge the feature branch to `main`

- [ ] **Step 1:** All PRs 1-14 have been merged into `refactor/data-model`. CI green.
- [ ] **Step 2:** Open final PR `refactor/data-model` → `main`, title `refactor(data-model): yacht + company + reservation refactor (final merge)`.
- [ ] **Step 3:** After approval, squash-merge (or merge-commit, per repo convention).

### Task 15.5: Close out

- [ ] **Step 1:** Delete the feature branch.
- [ ] **Step 2:** Announce Spec 1 complete. Spec 2 (NocoDB + MinIO importer) can begin — schema is frozen.
- [ ] **Step 3:** File any follow-ups flagged in the spec's "Open questions" section as issues in the backlog.

---

## Acceptance checklist (must all be true before Spec 1 marked complete)

- [ ] All 15 PRs merged to `main`
- [ ] CI green on `main`: unit ≥ 90% on services, validators 100%, API routes ≥ 85%, overall ≥ 85%
- [ ] Exhaustive click-through suite: zero console errors, zero unexpected 4xx/5xx, 100% coverage (minus declared destructive-action allowlist)
- [ ] Tier 4 golden-image PDFs committed; visual-diff tests passing
- [ ] Tier 3 E2E scenarios 1-11 all pass against a freshly seeded dev instance
- [ ] Documenso path and in-app path both produce functional EOIs (manual verification required; visual comparison against old system output)
- [ ] `docs/eoi-documenso-field-mapping.md` exists and is accurate
- [ ] Numbered spec files (01-15) + CLAUDE.md reflect the new data model
- [ ] No grep hits for `yachtName`, `companyName`, `isProxy`, `proxyType`, `actualOwnerName`, `relationshipNotes`, `berthSizeDesired` in `src/`
- [ ] Seeder produces realistic multi-cardinality fixtures; developer can manually walk through every scenario
- [ ] Spec 2 (NocoDB importer) can begin against a frozen schema