feat(documents): Phase A schema + service skeletons

Adds Phase A data model deltas to documents/templates and the new
document_watchers table. Introduces createFromWizard/createFromUpload
stubs, getDocumentDetail aggregator, cancelDocument flow, signed-doc
email composer, reservation agreement context, and notifyDocumentEvent
fan-out. Validator update accepts new template formats with html-only
bodyHtml requirement. EOI cadence backfilled to 1 day to preserve
current effective behaviour.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/db/migrations/0013_abnormal_thundra.sql

@@ -0,0 +1,25 @@
+CREATE TABLE "document_watchers" (
+	"document_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"added_by" text NOT NULL,
+	"added_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "document_watchers_document_id_user_id_pk" PRIMARY KEY("document_id","user_id")
+);
+--> statement-breakpoint
+ALTER TABLE "document_templates" ALTER COLUMN "body_html" DROP NOT NULL;--> statement-breakpoint
+ALTER TABLE "document_templates" ADD COLUMN "template_format" text DEFAULT 'html' NOT NULL;--> statement-breakpoint
+ALTER TABLE "document_templates" ADD COLUMN "source_file_id" text;--> statement-breakpoint
+ALTER TABLE "document_templates" ADD COLUMN "documenso_template_id" text;--> statement-breakpoint
+ALTER TABLE "document_templates" ADD COLUMN "field_mapping" jsonb DEFAULT '{}'::jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "document_templates" ADD COLUMN "overlay_positions" jsonb DEFAULT '[]'::jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "document_templates" ADD COLUMN "reminder_cadence_days" integer;--> statement-breakpoint
+ALTER TABLE "documents" ADD COLUMN "reservation_id" text;--> statement-breakpoint
+ALTER TABLE "documents" ADD COLUMN "reminders_disabled" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "documents" ADD COLUMN "reminder_cadence_override" integer;--> statement-breakpoint
+ALTER TABLE "document_watchers" ADD CONSTRAINT "document_watchers_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_doc_watchers_doc" ON "document_watchers" USING btree ("document_id");--> statement-breakpoint
+CREATE INDEX "idx_doc_watchers_user" ON "document_watchers" USING btree ("user_id");--> statement-breakpoint
+ALTER TABLE "document_templates" ADD CONSTRAINT "document_templates_source_file_id_files_id_fk" FOREIGN KEY ("source_file_id") REFERENCES "public"."files"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_docs_reservation" ON "documents" USING btree ("reservation_id");--> statement-breakpoint
+CREATE INDEX "idx_docs_status_port" ON "documents" USING btree ("port_id","status");--> statement-breakpoint
+UPDATE "document_templates" SET "reminder_cadence_days" = 1 WHERE "template_type" = 'eoi';

src/lib/db/migrations/meta/_journal.json

@@ -92,6 +92,13 @@
       "when": 1777308900666,
       "tag": "0012_large_zarda",
       "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1777334766194,
+      "tag": "0013_abnormal_thundra",
+      "breakpoints": true
     }
   ]
 }

src/lib/db/schema/documents.ts

@@ -1,5 +1,6 @@
 import {
   pgTable,
+  primaryKey,
   text,
   boolean,
   integer,
@@ -55,6 +56,7 @@ export const documents = pgTable(
     clientId: text('client_id').references(() => clients.id),
     yachtId: text('yacht_id'), // FK wired in relations.ts
     companyId: text('company_id'), // FK wired in relations.ts
+    reservationId: text('reservation_id'), // FK wired in relations.ts
     documentType: text('document_type').notNull(), // eoi, contract, nda, reservation_agreement, other
     title: text('title').notNull(),
     status: text('status').notNull().default('draft'), // draft, sent, partially_signed, completed, expired, cancelled
@@ -63,6 +65,8 @@ export const documents = pgTable(
     signedFileId: text('signed_file_id').references(() => files.id),
     isManualUpload: boolean('is_manual_upload').notNull().default(false),
     notes: text('notes'),
+    remindersDisabled: boolean('reminders_disabled').notNull().default(false),
+    reminderCadenceOverride: integer('reminder_cadence_override'),
     createdBy: text('created_by').notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
@@ -73,7 +77,9 @@ export const documents = pgTable(
     index('idx_docs_client').on(table.clientId),
     index('idx_documents_yacht').on(table.yachtId),
     index('idx_documents_company').on(table.companyId),
+    index('idx_docs_reservation').on(table.reservationId),
     index('idx_docs_type').on(table.portId, table.documentType),
+    index('idx_docs_status_port').on(table.portId, table.status),
   ],
 );
 
@@ -134,8 +140,19 @@ export const documentTemplates = pgTable(
     name: text('name').notNull(),
     description: text('description'),
     templateType: text('template_type').notNull(), // welcome_letter, handover_checklist, acknowledgment, correspondence, custom
-    bodyHtml: text('body_html').notNull(),
+    // Nullable: only required when template_format='html'.
+    bodyHtml: text('body_html'),
     mergeFields: jsonb('merge_fields').notNull().default([]),
+    // 'html' | 'pdf_form' | 'pdf_overlay' | 'documenso_render'
+    templateFormat: text('template_format').notNull().default('html'),
+    sourceFileId: text('source_file_id').references(() => files.id),
+    documensoTemplateId: text('documenso_template_id'),
+    // pdf_form: { acroFieldName: mergeToken }
+    fieldMapping: jsonb('field_mapping').notNull().default({}),
+    // pdf_overlay: [{ token, page, x, y, fontSize }]
+    overlayPositions: jsonb('overlay_positions').notNull().default([]),
+    // null = no auto-reminders
+    reminderCadenceDays: integer('reminder_cadence_days'),
     isActive: boolean('is_active').notNull().default(true),
     createdBy: text('created_by').notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
@@ -147,6 +164,23 @@ export const documentTemplates = pgTable(
   ],
 );
 
+export const documentWatchers = pgTable(
+  'document_watchers',
+  {
+    documentId: text('document_id')
+      .notNull()
+      .references(() => documents.id, { onDelete: 'cascade' }),
+    userId: text('user_id').notNull(),
+    addedBy: text('added_by').notNull(),
+    addedAt: timestamp('added_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.documentId, table.userId] }),
+    index('idx_doc_watchers_doc').on(table.documentId),
+    index('idx_doc_watchers_user').on(table.userId),
+  ],
+);
+
 export const formTemplates = pgTable(
   'form_templates',
   {
@@ -200,6 +234,8 @@ export type DocumentEvent = typeof documentEvents.$inferSelect;
 export type NewDocumentEvent = typeof documentEvents.$inferInsert;
 export type DocumentTemplate = typeof documentTemplates.$inferSelect;
 export type NewDocumentTemplate = typeof documentTemplates.$inferInsert;
+export type DocumentWatcher = typeof documentWatchers.$inferSelect;
+export type NewDocumentWatcher = typeof documentWatchers.$inferInsert;
 export type FormTemplate = typeof formTemplates.$inferSelect;
 export type NewFormTemplate = typeof formTemplates.$inferInsert;
 export type FormSubmission = typeof formSubmissions.$inferSelect;

src/lib/db/schema/relations.ts

@@ -52,6 +52,7 @@ import {
   documentSigners,
   documentEvents,
   documentTemplates,
+  documentWatchers,
   formTemplates,
   formSubmissions,
 } from './documents';
@@ -457,7 +458,7 @@ export const berthTagsRelations = relations(berthTags, ({ one }) => ({
 
 // ─── Berth Reservations ───────────────────────────────────────────────────────
 
-export const berthReservationsRelations = relations(berthReservations, ({ one }) => ({
+export const berthReservationsRelations = relations(berthReservations, ({ one, many }) => ({
   berth: one(berths, {
     fields: [berthReservations.berthId],
     references: [berths.id],
@@ -482,6 +483,7 @@ export const berthReservationsRelations = relations(berthReservations, ({ one })
     fields: [berthReservations.contractFileId],
     references: [files.id],
   }),
+  documents: many(documents),
 }));
 
 // ─── Documents ────────────────────────────────────────────────────────────────
@@ -538,8 +540,13 @@ export const documentsRelations = relations(documents, ({ one, many }) => ({
     fields: [documents.companyId],
     references: [companies.id],
   }),
+  reservation: one(berthReservations, {
+    fields: [documents.reservationId],
+    references: [berthReservations.id],
+  }),
   signers: many(documentSigners),
   events: many(documentEvents),
+  watchers: many(documentWatchers),
 }));
 
 export const documentSignersRelations = relations(documentSigners, ({ one, many }) => ({
@@ -566,6 +573,17 @@ export const documentTemplatesRelations = relations(documentTemplates, ({ one })
     fields: [documentTemplates.portId],
     references: [ports.id],
   }),
+  sourceFile: one(files, {
+    fields: [documentTemplates.sourceFileId],
+    references: [files.id],
+  }),
+}));
+
+export const documentWatchersRelations = relations(documentWatchers, ({ one }) => ({
+  document: one(documents, {
+    fields: [documentWatchers.documentId],
+    references: [documents.id],
+  }),
 }));
 
 export const formTemplatesRelations = relations(formTemplates, ({ one, many }) => ({