docs(14): create phase plan
This commit is contained in:
Chandler Copeland
252
.planning/phases/14-multi-signer-schema/14-01-PLAN.md
Normal file
252
.planning/phases/14-multi-signer-schema/14-01-PLAN.md
Normal file
@@ -0,0 +1,252 @@
|
||||
---
|
||||
phase: 14-multi-signer-schema
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- teressa-copeland-homes/src/lib/db/schema.ts
|
||||
- teressa-copeland-homes/drizzle/0010_*.sql
|
||||
autonomous: true
|
||||
requirements:
|
||||
- MSIGN-08
|
||||
must_haves:
|
||||
truths:
|
||||
- "Existing single-signer documents continue to prepare, send, and sign with zero code changes"
|
||||
- "SignatureFieldData has an optional signerEmail field for field ownership routing"
|
||||
- "signingTokens has a nullable signerEmail column for per-signer token identity"
|
||||
- "documents has a signers JSONB column typed as { email: string; color: string }[]"
|
||||
- "documents has a nullable completionTriggeredAt timestamp column for race-safe completion"
|
||||
- "Drizzle migration 0010 applies cleanly with no data loss"
|
||||
artifacts:
|
||||
- path: "teressa-copeland-homes/src/lib/db/schema.ts"
|
||||
provides: "Multi-signer schema additions"
|
||||
contains: "signerEmail"
|
||||
- path: "teressa-copeland-homes/drizzle/0010_*.sql"
|
||||
provides: "Drizzle-generated migration SQL"
|
||||
contains: "signer_email"
|
||||
key_links:
|
||||
- from: "teressa-copeland-homes/src/lib/db/schema.ts"
|
||||
to: "teressa-copeland-homes/drizzle/0010_*.sql"
|
||||
via: "drizzle-kit generate"
|
||||
pattern: "ALTER TABLE"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Add multi-signer schema columns to the database — signerEmail on SignatureFieldData interface, signerEmail column on signingTokens, signers JSONB and completionTriggeredAt columns on documents — via a single additive Drizzle migration. All new columns are nullable; all existing single-signer behavior is unchanged.
|
||||
|
||||
Purpose: Establishes the data foundation that Phases 15 (backend) and 16 (UI) build on. Without these columns, field ownership routing, per-signer tokens, and race-safe completion detection cannot be implemented.
|
||||
|
||||
Output: Updated schema.ts with new types/columns + generated migration 0010_*.sql applied to the database.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@$HOME/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/14-multi-signer-schema/14-CONTEXT.md
|
||||
@teressa-copeland-homes/src/lib/db/schema.ts
|
||||
|
||||
<interfaces>
|
||||
<!-- Current schema.ts types and table definitions the executor needs -->
|
||||
|
||||
From teressa-copeland-homes/src/lib/db/schema.ts:
|
||||
|
||||
```typescript
|
||||
// Current SignatureFieldData — signerEmail will be added here
|
||||
export interface SignatureFieldData {
|
||||
id: string;
|
||||
page: number;
|
||||
x: number;
|
||||
y: number;
|
||||
width: number;
|
||||
height: number;
|
||||
type?: SignatureFieldType;
|
||||
}
|
||||
|
||||
// Current getFieldType pattern — signerEmail helper will follow this pattern
|
||||
export function getFieldType(field: SignatureFieldData): SignatureFieldType {
|
||||
return field.type ?? 'client-signature';
|
||||
}
|
||||
|
||||
// Current signingTokens — signerEmail column will be added
|
||||
export const signingTokens = pgTable('signing_tokens', {
|
||||
jti: text('jti').primaryKey(),
|
||||
documentId: text('document_id').notNull()
|
||||
.references(() => documents.id, { onDelete: 'cascade' }),
|
||||
createdAt: timestamp('created_at').defaultNow().notNull(),
|
||||
expiresAt: timestamp('expires_at').notNull(),
|
||||
usedAt: timestamp('used_at'),
|
||||
});
|
||||
|
||||
// Current documents — signers JSONB and completionTriggeredAt will be added
|
||||
export const documents = pgTable("documents", {
|
||||
id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
|
||||
name: text("name").notNull(),
|
||||
// ... existing columns ...
|
||||
signedAt: timestamp("signed_at"),
|
||||
});
|
||||
|
||||
// JSONB typed column pattern (already established):
|
||||
signatureFields: jsonb("signature_fields").$type<SignatureFieldData[]>(),
|
||||
textFillData: jsonb("text_fill_data").$type<Record<string, string>>(),
|
||||
emailAddresses: jsonb("email_addresses").$type<string[]>(),
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Add multi-signer types and columns to schema.ts</name>
|
||||
<files>teressa-copeland-homes/src/lib/db/schema.ts</files>
|
||||
<read_first>
|
||||
- teressa-copeland-homes/src/lib/db/schema.ts (current schema — must see exact structure before editing)
|
||||
- .planning/phases/14-multi-signer-schema/14-CONTEXT.md (locked decisions D-01 through D-07)
|
||||
</read_first>
|
||||
<action>
|
||||
Edit `teressa-copeland-homes/src/lib/db/schema.ts` to add the following, in order:
|
||||
|
||||
**1. Add `signerEmail?: string` to `SignatureFieldData` interface (per D-04):**
|
||||
After the existing `type?: SignatureFieldType;` line, add:
|
||||
```typescript
|
||||
signerEmail?: string; // Optional — absent = legacy single-signer or agent-owned field
|
||||
```
|
||||
|
||||
**2. Add `getSignerEmail` helper function** immediately after the existing `isClientVisibleField` function:
|
||||
```typescript
|
||||
/**
|
||||
* Safe signer email reader — returns the field's signerEmail or a fallback.
|
||||
* Legacy single-signer documents have no signerEmail on their fields;
|
||||
* this coalesces to the fallback (typically the document's single recipient email).
|
||||
* ALWAYS use this instead of reading field.signerEmail directly.
|
||||
*/
|
||||
export function getSignerEmail(field: SignatureFieldData, fallbackEmail: string): string {
|
||||
return field.signerEmail ?? fallbackEmail;
|
||||
}
|
||||
```
|
||||
|
||||
**3. Add `DocumentSigner` interface** immediately before the `documents` table definition (per D-01):
|
||||
```typescript
|
||||
/** Shape of each entry in documents.signers JSONB array. */
|
||||
export interface DocumentSigner {
|
||||
email: string;
|
||||
color: string;
|
||||
}
|
||||
```
|
||||
Note: Per user decision D-01, this is `{ email: string; color: string }` only — NOT the expanded shape from ARCHITECTURE.md that included name/tokenJti/signedAt. Those fields are NOT part of Phase 14.
|
||||
|
||||
**4. Add two columns to the `documents` table definition:**
|
||||
After the existing `signedAt: timestamp("signed_at"),` line, add:
|
||||
```typescript
|
||||
/** Per-signer list with assigned colors. NULL = legacy single-signer document. */
|
||||
signers: jsonb("signers").$type<DocumentSigner[]>(),
|
||||
/** Atomic completion guard — set once by the last signer's handler. NULL = not yet completed. */
|
||||
completionTriggeredAt: timestamp("completion_triggered_at"),
|
||||
```
|
||||
|
||||
**5. Add `signerEmail` column to the `signingTokens` table definition (per D-02):**
|
||||
After the existing `documentId` line and before `createdAt`, add:
|
||||
```typescript
|
||||
/** Signer this token belongs to. NULL = legacy single-signer token. */
|
||||
signerEmail: text('signer_email'),
|
||||
```
|
||||
|
||||
**Do NOT:**
|
||||
- Add any new values to `auditEventTypeEnum` — those are Phase 15 scope (D-06 says Phase 14 is schema-only, no sign handler changes; new audit events belong with the handlers that fire them)
|
||||
- Add `Partially Signed` to `documentStatusEnum` (per D-05)
|
||||
- Change any existing function signatures or column definitions
|
||||
- Touch any file other than schema.ts
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx tsc --noEmit 2>&1 | head -20</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- grep "signerEmail?: string" src/lib/db/schema.ts returns a match inside SignatureFieldData
|
||||
- grep "export function getSignerEmail" src/lib/db/schema.ts returns a match
|
||||
- grep "export interface DocumentSigner" src/lib/db/schema.ts returns a match
|
||||
- grep 'signers: jsonb("signers")' src/lib/db/schema.ts returns a match
|
||||
- grep 'completionTriggeredAt: timestamp("completion_triggered_at")' src/lib/db/schema.ts returns a match
|
||||
- grep "signerEmail: text('signer_email')" src/lib/db/schema.ts returns a match inside signingTokens
|
||||
- grep "Partially" src/lib/db/schema.ts returns NO match (D-05)
|
||||
- npx tsc --noEmit exits 0 (no type errors)
|
||||
</acceptance_criteria>
|
||||
<done>schema.ts has all 4 additions (interface field, helper function, 2 document columns, 1 signingTokens column) with zero changes to existing definitions; TypeScript compiles cleanly</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Generate Drizzle migration and apply it</name>
|
||||
<files>teressa-copeland-homes/drizzle/0010_*.sql</files>
|
||||
<read_first>
|
||||
- teressa-copeland-homes/src/lib/db/schema.ts (just-modified schema — confirm changes are present)
|
||||
- teressa-copeland-homes/drizzle.config.ts (migration output dir and DB config)
|
||||
- teressa-copeland-homes/drizzle/0009_luxuriant_catseye.sql (latest migration — confirm 0010 is next)
|
||||
</read_first>
|
||||
<action>
|
||||
**1. Generate the migration (per D-07):**
|
||||
```bash
|
||||
cd teressa-copeland-homes && npx drizzle-kit generate
|
||||
```
|
||||
This will produce `drizzle/0010_*.sql` containing ALTER TABLE statements for the 3 new columns (signer_email on signing_tokens, signers and completion_triggered_at on documents). The SignatureFieldData interface change does NOT produce SQL — it is a TypeScript-only change (the JSONB column is schema-less at the DB level).
|
||||
|
||||
**2. Inspect the generated SQL** to verify it contains exactly:
|
||||
- `ALTER TABLE "signing_tokens" ADD COLUMN "signer_email" text;`
|
||||
- `ALTER TABLE "documents" ADD COLUMN "signers" jsonb;`
|
||||
- `ALTER TABLE "documents" ADD COLUMN "completion_triggered_at" timestamp;`
|
||||
- NO DROP COLUMN statements
|
||||
- NO ALTER TYPE statements
|
||||
- NO backfill UPDATE statements
|
||||
|
||||
**3. Apply the migration:**
|
||||
```bash
|
||||
cd teressa-copeland-homes && npx drizzle-kit migrate
|
||||
```
|
||||
|
||||
**4. Verify migration applied** by checking drizzle-kit output shows success.
|
||||
|
||||
**Do NOT:**
|
||||
- Hand-edit the generated SQL file — Drizzle generates it; we commit it as-is
|
||||
- Run any backfill queries
|
||||
- Add ALTER TYPE statements for audit events (Phase 15 scope)
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /Users/ccopeland/temp/red/teressa-copeland-homes && ls drizzle/0010_*.sql && grep -l "signer_email" drizzle/0010_*.sql && grep -l "completion_triggered_at" drizzle/0010_*.sql</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- A file matching drizzle/0010_*.sql exists
|
||||
- grep "signer_email" drizzle/0010_*.sql returns a match
|
||||
- grep "signers" drizzle/0010_*.sql returns a match for the JSONB column
|
||||
- grep "completion_triggered_at" drizzle/0010_*.sql returns a match
|
||||
- grep -i "DROP" drizzle/0010_*.sql returns NO match (additive only)
|
||||
- grep "audit_event_type" drizzle/0010_*.sql returns NO match (no enum changes in Phase 14)
|
||||
- drizzle/meta/_journal.json contains an entry for migration 0010
|
||||
</acceptance_criteria>
|
||||
<done>Migration 0010 generated with 3 additive ALTER TABLE statements (no drops, no type changes, no backfills), applied successfully to the database, and committed alongside schema.ts</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
After both tasks complete:
|
||||
1. `npx tsc --noEmit` exits 0 — TypeScript compiles with new types
|
||||
2. `drizzle/0010_*.sql` exists and contains only additive ALTER TABLE statements
|
||||
3. `grep -c "signerEmail" teressa-copeland-homes/src/lib/db/schema.ts` returns 3+ (interface field, helper function param, signingTokens column)
|
||||
4. No files outside schema.ts and drizzle/ were modified
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Drizzle migration 0010 applies cleanly (no errors)
|
||||
- schema.ts has SignatureFieldData.signerEmail?, DocumentSigner interface, documents.signers JSONB, documents.completionTriggeredAt TIMESTAMP, signingTokens.signerEmail TEXT
|
||||
- Existing single-signer code paths unaffected (all additions are nullable/optional)
|
||||
- No audit event enum changes, no status enum changes, no sign handler changes
|
||||
- TypeScript compiles cleanly
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/14-multi-signer-schema/14-01-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user