86 lines
4.3 KiB
Markdown
86 lines
4.3 KiB
Markdown
|
---
|
||
|
|
phase: 14-multi-signer-schema
|
||
|
|
plan: "01"
|
||
|
|
subsystem: database-schema
|
||
|
|
tags: [schema, drizzle, multi-signer, migration]
|
||
|
|
dependency_graph:
|
||
|
|
requires: []
|
||
|
|
provides: [multi-signer-schema-columns, DocumentSigner-interface, getSignerEmail-helper]
|
||
|
|
affects: [phase-15-backend, phase-16-ui]
|
||
|
|
tech_stack:
|
||
|
|
added: []
|
||
|
|
patterns: [additive-nullable-columns, jsonb-typed-columns, safe-reader-helper]
|
||
|
|
key_files:
|
||
|
|
created:
|
||
|
|
- teressa-copeland-homes/drizzle/0010_sharp_archangel.sql
|
||
|
|
- teressa-copeland-homes/drizzle/meta/0010_snapshot.json
|
||
|
|
modified:
|
||
|
|
- teressa-copeland-homes/src/lib/db/schema.ts
|
||
|
|
decisions:
|
||
|
|
- "documents.signers JSONB shape is { email, color }[] — not string[] — so Phase 16 can retrieve consistent per-signer colors from DB without recalculating"
|
||
|
|
- "signingTokens.signerEmail is nullable TEXT — NULL = legacy single-signer token, no existing token creation code requires changes"
|
||
|
|
- "documents.completionTriggeredAt is nullable TIMESTAMP used as atomic completion guard in Phase 15 UPDATE...WHERE completionTriggeredAt IS NULL"
|
||
|
|
- "SignatureFieldData.signerEmail? follows exact same additive-nullable pattern as type? — zero breakage to existing JSONB field rows"
|
||
|
|
- "No Partially Signed status added to documentStatusEnum — partial state computed dynamically in Phase 16 by counting used tokens"
|
||
|
|
metrics:
|
||
|
|
duration: "5 min"
|
||
|
|
completed_date: "2026-04-03"
|
||
|
|
tasks_completed: 2
|
||
|
|
files_modified: 3
|
||
|
|
---
|
||
|
|
|
||
|
|
# Phase 14 Plan 01: Multi-Signer Schema Summary
|
||
|
|
|
||
|
|
Additive Drizzle migration 0010 adding signerEmail to SignatureFieldData and signingTokens, plus signers JSONB and completionTriggeredAt to documents — all nullable, zero backfills, TypeScript compiles cleanly.
|
||
|
|
|
||
|
|
## What Was Built
|
||
|
|
|
||
|
|
Three new nullable database columns and one TypeScript interface extension, establishing the data foundation for Phases 15 (sign handler rewrite) and 16 (multi-signer UI):
|
||
|
|
|
||
|
|
1. `SignatureFieldData.signerEmail?: string` — optional field ownership routing (absent = legacy single-signer)
|
||
|
|
2. `getSignerEmail(field, fallbackEmail)` helper — safe reader following the same pattern as `getFieldType()`
|
||
|
|
3. `DocumentSigner` interface — `{ email: string; color: string }[]` shape for the signers JSONB array
|
||
|
|
4. `documents.signers JSONB` — per-signer list with assigned colors; NULL = legacy single-signer document
|
||
|
|
5. `documents.completionTriggeredAt TIMESTAMP` — atomic completion guard for Phase 15's race-safe handler
|
||
|
|
6. `signingTokens.signerEmail TEXT` — per-token signer identity; NULL = legacy single-signer token
|
||
|
|
|
||
|
|
Migration `0010_sharp_archangel.sql` contains exactly 3 `ALTER TABLE...ADD COLUMN` statements — no DROPs, no ALTER TYPEs, no backfills.
|
||
|
|
|
||
|
|
## Tasks
|
||
|
|
|
||
|
|
| Task | Name | Commit | Files |
|
||
|
|
|------|------|--------|-------|
|
||
|
|
| 1 | Add multi-signer types and columns to schema.ts | c658f13 | src/lib/db/schema.ts |
|
||
|
|
| 2 | Generate Drizzle migration and apply it | 3639491 | drizzle/0010_sharp_archangel.sql, drizzle/meta/_journal.json, drizzle/meta/0010_snapshot.json |
|
||
|
|
|
||
|
|
## Decisions Made
|
||
|
|
|
||
|
|
- `documents.signers` uses `{ email, color }[]` JSONB shape so Phase 16 PreparePanel can render consistent signer-assigned colors without recalculating by index position
|
||
|
|
- `signerEmail` on `SignatureFieldData` is optional (not required) so every existing JSONB field row stored in the DB remains valid with no migration needed
|
||
|
|
- `completionTriggeredAt` is Phase 14 schema-only; write logic (UPDATE...WHERE...IS NULL RETURNING) is Phase 15 scope
|
||
|
|
- No `Partially Signed` enum value added — computed dynamically by counting `usedAt IS NOT NULL` tokens in Phase 16
|
||
|
|
|
||
|
|
## Verification Results
|
||
|
|
|
||
|
|
- `npx tsc --noEmit` exits 0 — no TypeScript errors
|
||
|
|
- `grep -c signerEmail src/lib/db/schema.ts` returns 6 (>= 3 required)
|
||
|
|
- Migration SQL contains only `ALTER TABLE...ADD COLUMN` — no DROPs
|
||
|
|
- Migration applied successfully to local Postgres instance
|
||
|
|
- No files outside schema.ts and drizzle/ were modified
|
||
|
|
|
||
|
|
## Deviations from Plan
|
||
|
|
|
||
|
|
None — plan executed exactly as written.
|
||
|
|
|
||
|
|
## Known Stubs
|
||
|
|
|
||
|
|
None — this plan is schema-only with no UI or data-rendering code paths.
|
||
|
|
|
||
|
|
## Self-Check: PASSED
|
||
|
|
|
||
|
|
- `teressa-copeland-homes/src/lib/db/schema.ts` — FOUND (modified)
|
||
|
|
- `teressa-copeland-homes/drizzle/0010_sharp_archangel.sql` — FOUND (created)
|
||
|
|
- `teressa-copeland-homes/drizzle/meta/0010_snapshot.json` — FOUND (created)
|
||
|
|
- Commit c658f13 — FOUND
|
||
|
|
- Commit 3639491 — FOUND
|