100 lines
4.9 KiB
Markdown
100 lines
4.9 KiB
Markdown
|
---
|
||
|
|
phase: 08-schema-foundation-and-signing-page-safety
|
||
|
|
plan: "01"
|
||
|
|
subsystem: schema
|
||
|
|
tags: [schema, typescript, drizzle, field-types, backward-compat]
|
||
|
|
dependency_graph:
|
||
|
|
requires: []
|
||
|
|
provides:
|
||
|
|
- SignatureFieldType union type
|
||
|
|
- getFieldType() helper function
|
||
|
|
- isClientVisibleField() predicate function
|
||
|
|
- Drizzle migration snapshot 0006
|
||
|
|
affects:
|
||
|
|
- teressa-copeland-homes/src/lib/db/schema.ts
|
||
|
|
- teressa-copeland-homes/drizzle/meta/_journal.json
|
||
|
|
tech_stack:
|
||
|
|
added: []
|
||
|
|
patterns:
|
||
|
|
- TypeScript union type discriminant for JSONB field data
|
||
|
|
- Backward-compatible optional field with coalescing helper
|
||
|
|
key_files:
|
||
|
|
created:
|
||
|
|
- teressa-copeland-homes/drizzle/0006_type_discriminant.sql
|
||
|
|
- teressa-copeland-homes/drizzle/meta/0006_snapshot.json
|
||
|
|
modified:
|
||
|
|
- teressa-copeland-homes/src/lib/db/schema.ts
|
||
|
|
- teressa-copeland-homes/drizzle/meta/_journal.json
|
||
|
|
decisions:
|
||
|
|
- "SignatureFieldType field on SignatureFieldData is optional to preserve backward-compat with v1.0 documents that have no type in their JSONB data"
|
||
|
|
- "getFieldType() coalesces field.type ?? 'client-signature' so all v1.0 documents resolve as client-signature without any data migration"
|
||
|
|
- "isClientVisibleField() returns false only for agent-signature — all other types (including undefined/legacy) are visible to client"
|
||
|
|
- "Migration 0006 has no DDL — .$type<T>() is TypeScript-only; snapshot and journal updated manually since Drizzle declined to generate (no DDL changes)"
|
||
|
|
- "db:migrate skipped — database unavailable in dev environment; migration is a no-op and presents no risk"
|
||
|
|
metrics:
|
||
|
|
duration: "2 min"
|
||
|
|
completed: "2026-03-21"
|
||
|
|
tasks_completed: 2
|
||
|
|
files_modified: 4
|
||
|
|
---
|
||
|
|
|
||
|
|
# Phase 8 Plan 01: Schema Foundation — SignatureFieldType Discriminant Summary
|
||
|
|
|
||
|
|
**One-liner:** TypeScript-only schema discriminant adding SignatureFieldType union, optional type field on SignatureFieldData, and two backward-compatible helper exports (getFieldType, isClientVisibleField).
|
||
|
|
|
||
|
|
## What Was Built
|
||
|
|
|
||
|
|
Extended `teressa-copeland-homes/src/lib/db/schema.ts` with three additions required by all Phase 9-13 field-type features:
|
||
|
|
|
||
|
|
1. **`SignatureFieldType` union type** — six literals: `'client-signature' | 'initials' | 'text' | 'checkbox' | 'date' | 'agent-signature'`
|
||
|
|
|
||
|
|
2. **`SignatureFieldData.type?` field** — optional field on the existing interface; v1.0 documents with no type continue to work without data migration
|
||
|
|
|
||
|
|
3. **`getFieldType(field)` helper** — always returns a `SignatureFieldType`, coalescing `field.type ?? 'client-signature'`; prevents scattered `field.type ?? 'client-signature'` patterns across call sites
|
||
|
|
|
||
|
|
4. **`isClientVisibleField(field)` predicate** — returns `false` for `agent-signature` only, used by the signing page filter added in Plan 08-02
|
||
|
|
|
||
|
|
Created `drizzle/0006_type_discriminant.sql` (empty SQL — no DDL) and updated `drizzle/meta/_journal.json` and `drizzle/meta/0006_snapshot.json` to keep the Drizzle migration chain in sync.
|
||
|
|
|
||
|
|
## Commits
|
||
|
|
|
||
|
|
| Task | Commit | Files |
|
||
|
|
|------|--------|-------|
|
||
|
|
| 1: Extend schema.ts | `2dd1b61` | `src/lib/db/schema.ts` |
|
||
|
|
| 2: Migration snapshot | `b5f8b62` | `drizzle/0006_type_discriminant.sql`, `drizzle/meta/0006_snapshot.json`, `drizzle/meta/_journal.json` |
|
||
|
|
|
||
|
|
## Deviations from Plan
|
||
|
|
|
||
|
|
### Manual migration file creation
|
||
|
|
|
||
|
|
**Found during:** Task 2
|
||
|
|
|
||
|
|
**Issue:** `npm run db:generate` reported "No schema changes, nothing to migrate" because `SignatureFieldType` is a TypeScript-only change (`.$type<T>()` annotation) with no DDL. Drizzle does not create a migration file when there are no DDL changes.
|
||
|
|
|
||
|
|
**Fix:** Created `drizzle/0006_type_discriminant.sql` (comment-only, no SQL), `drizzle/meta/0006_snapshot.json` (DDL state identical to 0005), and updated `_journal.json` manually. This matches the plan's stated intent: "The SQL content will be empty or contain only a comment — that is CORRECT and expected."
|
||
|
|
|
||
|
|
**Files modified:** `drizzle/0006_type_discriminant.sql` (created), `drizzle/meta/0006_snapshot.json` (created), `drizzle/meta/_journal.json` (updated)
|
||
|
|
|
||
|
|
**Rule:** Rule 3 — Auto-fix blocking issue (Drizzle would not auto-generate the required file)
|
||
|
|
|
||
|
|
### db:migrate not applied
|
||
|
|
|
||
|
|
**Found during:** Task 2
|
||
|
|
|
||
|
|
**Issue:** `npm run db:migrate` failed with "url: undefined" — no database connection string configured in environment.
|
||
|
|
|
||
|
|
**Resolution:** Noted in summary as planned. The plan explicitly states this is acceptable: "DO NOT block plan completion — the TypeScript changes are the deliverable." Migration is a no-op (empty SQL) and presents no risk.
|
||
|
|
|
||
|
|
## Self-Check: PASSED
|
||
|
|
|
||
|
|
Files exist:
|
||
|
|
- FOUND: `teressa-copeland-homes/src/lib/db/schema.ts`
|
||
|
|
- FOUND: `teressa-copeland-homes/drizzle/0006_type_discriminant.sql`
|
||
|
|
- FOUND: `teressa-copeland-homes/drizzle/meta/0006_snapshot.json`
|
||
|
|
|
||
|
|
Commits exist:
|
||
|
|
- FOUND: `2dd1b61` feat(08-01): extend SignatureFieldData with type discriminant and helper exports
|
||
|
|
- FOUND: `b5f8b62` chore(08-01): add Drizzle migration snapshot for TypeScript-only schema change
|
||
|
|
|
||
|
|
TypeScript compilation: PASS (npx tsc --noEmit exits 0)
|