diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 238e83f..37e43ef 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -111,7 +111,7 @@ - [ ] **MSIGN-05**: Document recipients list is built automatically from unique signer emails on placed fields (no separate manual entry) - [ ] **MSIGN-06**: All signers receive their unique signing links simultaneously when agent sends - [ ] **MSIGN-07**: Each signer's signing page shows only their own assigned fields — other signers' fields are not visible -- [ ] **MSIGN-08**: Server enforces field ownership — a signer can only submit fields assigned to them +- [x] **MSIGN-08**: Server enforces field ownership — a signer can only submit fields assigned to them - [ ] **MSIGN-09**: Dashboard shows per-signer completion status (who has signed, who hasn't) - [ ] **MSIGN-10**: When all signers complete, agent receives a notification email - [ ] **MSIGN-11**: When all signers complete, all parties (each signer + agent) receive the final merged PDF via email link @@ -224,7 +224,7 @@ Which phases cover which requirements. Updated during roadmap creation. | TXTF-03 | Phase 12.1 | Complete | | AI-01 | Phase 13 | In Progress | | AI-02 | Phase 13 | In Progress | -| MSIGN-08 | Phase 14 | Pending | +| MSIGN-08 | Phase 14 | Complete | | MSIGN-05 | Phase 15 | Pending | | MSIGN-06 | Phase 15 | Pending | | MSIGN-07 | Phase 15 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index f9ee32b..695eac8 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -174,7 +174,7 @@ Plans: **Milestone Goal:** A single document can be sent to multiple signers in parallel, each receiving their own link and seeing only their own fields, with automatic completion notifications — plus a production-ready Docker Compose setup that correctly passes secrets so email works reliably. -- [ ] **Phase 14: Multi-Signer Schema** - Additive DB migration enabling multi-signer field routing, per-signer token identity, and race-safe completion detection +- [x] **Phase 14: Multi-Signer Schema** - Additive DB migration enabling multi-signer field routing, per-signer token identity, and race-safe completion detection (completed 2026-04-03) - [ ] **Phase 15: Multi-Signer Backend** - Token creation loop, signer-aware signing flow, atomic completion detection, parallel email dispatch and final PDF delivery - [ ] **Phase 16: Multi-Signer UI** - PreparePanel signer list, FieldPlacer signer assignment and color-coding, send-block validation, per-signer dashboard status - [ ] **Phase 17: Docker Deployment** - Three-stage Dockerfile, docker-compose.yml with named uploads volume and env_file secrets, health endpoint, SMTP fix @@ -319,7 +319,7 @@ Plans: **Plans**: 1 plan Plans: -- [ ] 14-01-PLAN.md — schema.ts multi-signer additions (SignatureFieldData.signerEmail, DocumentSigner interface, documents.signers JSONB, documents.completionTriggeredAt, signingTokens.signerEmail) + Drizzle migration 0010 +- [x] 14-01-PLAN.md — schema.ts multi-signer additions (SignatureFieldData.signerEmail, DocumentSigner interface, documents.signers JSONB, documents.completionTriggeredAt, signingTokens.signerEmail) + Drizzle migration 0010 **UI hint**: no @@ -383,7 +383,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → | 12. Filled Document Preview | v1.1 | 2/2 | Complete | 2026-03-21 | | 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | v1.1 | 2/2 | Complete | 2026-03-21 | | 13. AI Field Placement and Pre-fill | v1.1 | 3/4 | In Progress | - | -| 14. Multi-Signer Schema | v1.2 | 0/1 | Not started | - | +| 14. Multi-Signer Schema | v1.2 | 1/1 | Complete | 2026-04-03 | | 15. Multi-Signer Backend | v1.2 | 0/TBD | Not started | - | | 16. Multi-Signer UI | v1.2 | 0/TBD | Not started | - | | 17. Docker Deployment | v1.2 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 4701539..e7ddc8d 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,15 +2,15 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: Smart Document Preparation -status: executing -stopped_at: Completed 13-ai-field-placement-and-pre-fill/13-03-PLAN.md — AI Auto-place button wired; Plan 03 of 4 done; ready for Plan 04 (E2E verification) -last_updated: "2026-04-03T20:30:14.113Z" -last_activity: 2026-04-03 -- v1.2 roadmap created (Phases 14-17 planned) +status: verifying +stopped_at: "Completed 14-01-PLAN.md — Multi-signer schema: signerEmail on SignatureFieldData/signingTokens, signers JSONB + completionTriggeredAt on documents, migration 0010" +last_updated: "2026-04-03T21:17:15.201Z" +last_activity: 2026-04-03 progress: - total_phases: 8 - completed_phases: 7 - total_plans: 20 - completed_plans: 19 + total_phases: 16 + completed_phases: 15 + total_plans: 49 + completed_plans: 48 percent: 100 --- @@ -24,10 +24,10 @@ See: .planning/PROJECT.md (updated 2026-04-03) ## Current Position -Phase: 13 (ai-field-placement-and-pre-fill) — EXECUTING -Plan: 1 of 4 -Status: Executing Phase 13 (v1.1 final phase); v1.2 roadmap created and ready -Last activity: 2026-04-03 -- v1.2 roadmap created (Phases 14-17 planned) +Phase: 14 (multi-signer-schema) — EXECUTING +Plan: 1 of 1 +Status: Phase complete — ready for verification +Last activity: 2026-04-03 ## Note on v1.1 @@ -36,6 +36,7 @@ v1.1 (Smart Document Preparation) is complete except Phase 13 Plan 04 (E2E verif ## Note on v1.2 v1.2 (Multi-Signer and Deployment Hardening) roadmap is defined. Four phases planned: + - Phase 14: Multi-Signer Schema — additive DB migration, enables Phases 15+16 - Phase 15: Multi-Signer Backend — token loop, signer-aware signing flow, atomic completion - Phase 16: Multi-Signer UI — PreparePanel signer list, FieldPlacer color-coding, send validation @@ -84,6 +85,7 @@ Progress: [█████████████] 100% (13/13 phases complete | Phase 12.1-per-field-text-editing-and-quick-fill P02 | 5 | 2 auto tasks + 1 human-verify checkpoint | 2 files modified + 1 deleted | | Phase 13-ai-field-placement-and-pre-fill P01 | 2 | 2 tasks | 5 files | | Phase 13-ai-field-placement-and-pre-fill P03 | 2 | 2 tasks | 5 files | +| Phase 14-multi-signer-schema P01 | 5 | 2 tasks | 3 files | ## Accumulated Context @@ -151,6 +153,9 @@ Recent decisions affecting v1.1 work: - [Phase 13-03]: aiPlacementKey integer incremented via setAiPlacementKey(k => k + 1) — functional update prevents stale closure issues - [Phase 13-03]: textFillData is MERGED not replaced — preserves manually typed values while AI values take precedence - [Phase 13-03]: AI button uses violet bg-violet-600 to visually distinguish from gray Preview and blue Prepare-and-Send +- [Phase 14-multi-signer-schema]: documents.signers JSONB shape is { email, color }[] so Phase 16 can retrieve consistent per-signer colors from DB without recalculating +- [Phase 14-multi-signer-schema]: completionTriggeredAt nullable TIMESTAMP used as atomic completion guard — Phase 14 adds column; Phase 15 owns write logic +- [Phase 14-multi-signer-schema]: No Partially Signed enum added — partial state computed dynamically by counting usedAt IS NOT NULL tokens in Phase 16 ### v1.2 Pre-decisions (from research) @@ -174,6 +179,6 @@ None yet. ## Session Continuity -Last session: 2026-04-03 -Stopped at: v1.2 roadmap created — Phases 14-17 defined; ready to complete Phase 13 Plan 04 then begin Phase 14 +Last session: 2026-04-03T21:17:15.198Z +Stopped at: Completed 14-01-PLAN.md — Multi-signer schema: signerEmail on SignatureFieldData/signingTokens, signers JSONB + completionTriggeredAt on documents, migration 0010 Resume file: None diff --git a/.planning/phases/14-multi-signer-schema/14-01-SUMMARY.md b/.planning/phases/14-multi-signer-schema/14-01-SUMMARY.md new file mode 100644 index 0000000..03da839 --- /dev/null +++ b/.planning/phases/14-multi-signer-schema/14-01-SUMMARY.md @@ -0,0 +1,85 @@ +--- +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