docs(06-03): complete signing page plan — SUMMARY, STATE, ROADMAP updated
- 06-03-SUMMARY.md created with decisions, deviations, file list - STATE.md advanced to Plan 3 complete; two new decisions recorded - ROADMAP.md phase 6 updated to 3/6 summaries complete
This commit is contained in:
Chandler Copeland
142
.planning/phases/06-signing-flow/06-03-SUMMARY.md
Normal file
142
.planning/phases/06-signing-flow/06-03-SUMMARY.md
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
phase: 06-signing-flow
|
||||
plan: "03"
|
||||
subsystem: ui
|
||||
tags: [react-pdf, pdfjs, signing, jwt, audit, overlay, animation, next-app-router]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 06-signing-flow/06-01
|
||||
provides: verifySigningToken(), logAuditEvent(), signingTokens table, SignatureFieldData schema
|
||||
|
||||
provides:
|
||||
- /sign/[token] public route with three states (expired/used/pending)
|
||||
- Server component token validation before any UI renders
|
||||
- SigningPageClient: full-scroll react-pdf viewer + pulsing blue field overlays + sticky progress bar
|
||||
- SigningProgressBar: sticky bottom bar with X/Y count + jump-to-next + submit button
|
||||
- GET /api/sign/[token]: token validation data route + audit event logging
|
||||
- GET /api/sign/[token]/pdf: token-authenticated PDF streaming route
|
||||
|
||||
affects: [06-04, 06-05]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- react-pdf used with dynamic import (ssr:false) via SigningPageClientWrapper — prevents SSR crashes from browser-only canvas/worker APIs
|
||||
- PDF coordinate conversion: screenTop = renderedH - (field.y * scaleY) - (field.height * scaleY); origin flip from PDF bottom-left to screen top-left
|
||||
- CSS keyframes injected via <style> tag inside client component for pulse-border animation
|
||||
- Token-authenticated PDF serving via /api/sign/[token]/pdf — no agent auth, signed token grants file access
|
||||
- Path traversal guard on PDF file serving (checks for .. in stored relative path)
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- teressa-copeland-homes/src/app/api/sign/[token]/route.ts
|
||||
- teressa-copeland-homes/src/app/api/sign/[token]/pdf/route.ts
|
||||
- teressa-copeland-homes/src/app/sign/[token]/page.tsx
|
||||
- teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClient.tsx
|
||||
- teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClientWrapper.tsx
|
||||
- teressa-copeland-homes/src/app/sign/[token]/_components/SigningProgressBar.tsx
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "SigningPageClientWrapper uses dynamic import (ssr:false) — react-pdf uses browser APIs (canvas, pdfjs worker) that cannot run server-side"
|
||||
- "PDF served via /api/sign/[token]/pdf (token-authenticated) not /api/documents/[id]/file (agent-authenticated) — signing page is public, agent route requires session"
|
||||
- "ErrorPage function defined in page.tsx for inline use — no separate file needed, three small JSX blocks"
|
||||
- "onFieldClick prop is a no-op stub in this plan — modal capture wired in Plan 04"
|
||||
|
||||
patterns-established:
|
||||
- "Signing page validates token at server component level before rendering any client component — no canvas flash on expired/used/invalid tokens"
|
||||
- "PDF coordinate conversion: pdfY (bottom-left origin) -> screenTop = renderedH - pdfY*scaleY - fieldH*scaleY"
|
||||
- "Token-authenticated file routes use verifySigningToken() with no usedAt check — viewing is idempotent, submission check is separate"
|
||||
|
||||
requirements-completed: [SIGN-02, SIGN-03, LEGAL-01]
|
||||
|
||||
# Metrics
|
||||
duration: 3min
|
||||
completed: 2026-03-20
|
||||
---
|
||||
|
||||
# Phase 6 Plan 03: Signing Page Summary
|
||||
|
||||
**Public /sign/[token] route with server-side token enforcement (expired/used/pending states), react-pdf full-scroll viewer, pulsing blue signature field overlays, and sticky progress bar**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 3 min
|
||||
- **Started:** 2026-03-20T17:28:18Z
|
||||
- **Completed:** 2026-03-20T17:30:54Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 6
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Server component validates JWT + one-time-use before rendering any signing UI — no canvas flash on invalid tokens
|
||||
- GET /api/sign/[token] returns expired/used/pending JSON with link_opened + document_viewed audit events logged
|
||||
- Full-scroll react-pdf viewer with absolutely-positioned pulsing blue overlay divs on each signature field
|
||||
- Sticky progress bar shows "X of Y signatures complete" with jump-to-next scroll and submit button
|
||||
- GET /api/sign/[token]/pdf streams prepared PDF authenticated by signing token (no agent session required)
|
||||
- npm run build passes cleanly with /sign/[token], /api/sign/[token], /api/sign/[token]/pdf all visible as dynamic routes
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: GET /api/sign/[token] route — token validation + audit logging** - `e1306da` (feat)
|
||||
2. **Task 2: Signing page server component + client PDF viewer + progress bar** - `dcf503d` (feat)
|
||||
|
||||
**Plan metadata:** (docs commit — see below)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `teressa-copeland-homes/src/app/api/sign/[token]/route.ts` - Public GET route: validates JWT, checks one-time-use, logs audit events, returns expired/used/pending JSON
|
||||
- `teressa-copeland-homes/src/app/api/sign/[token]/pdf/route.ts` - Token-authenticated PDF streaming route; path traversal guard on stored relative path
|
||||
- `teressa-copeland-homes/src/app/sign/[token]/page.tsx` - Server component: validates token + DB lookups before rendering any client UI; inline ErrorPage for three error states
|
||||
- `teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClient.tsx` - Client PDF viewer: react-pdf Document+Page all pages, pulsing overlay divs, coordinate conversion, signaturesRef for Plan 04
|
||||
- `teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClientWrapper.tsx` - Dynamic import wrapper (ssr:false) for react-pdf browser requirement
|
||||
- `teressa-copeland-homes/src/app/sign/[token]/_components/SigningProgressBar.tsx` - Sticky progress bar with jump-to-next and submit button
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- `SigningPageClientWrapper` created with `dynamic(..., { ssr: false })` — react-pdf requires browser APIs (HTMLCanvasElement, pdfjs worker). Direct import from server component would crash at SSR time.
|
||||
- PDF file served via `/api/sign/[token]/pdf` rather than the existing `/api/documents/[id]/file` — the existing file route requires an authenticated agent session; the signing page is intentionally public and authenticates via the signing token.
|
||||
- `onFieldClick` is a no-op stub in this plan. Plan 04 will wire up the signature modal and populate `signaturesRef`.
|
||||
- `ErrorPage` inlined in `page.tsx` — three simple JSX blocks, not worth a separate file.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing Critical] Added SigningPageClientWrapper for SSR-safe dynamic import**
|
||||
- **Found during:** Task 2 (server component + PDF viewer)
|
||||
- **Issue:** `SigningPageClient` uses `pdfjs.GlobalWorkerOptions.workerSrc = new URL(import.meta.url)` and react-pdf canvas APIs — these cannot run in Next.js SSR. Directly importing the client component from the server page.tsx would throw at build/render time.
|
||||
- **Fix:** Created `SigningPageClientWrapper.tsx` as a `'use client'` component that wraps `SigningPageClient` in `next/dynamic(..., { ssr: false })`. `page.tsx` imports the wrapper instead.
|
||||
- **Files modified:** `SigningPageClientWrapper.tsx` (new), `page.tsx` (imports wrapper not client directly)
|
||||
- **Verification:** `npm run build` passes, no SSR errors
|
||||
- **Committed in:** `dcf503d` (Task 2 commit)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (Rule 2 — missing critical SSR guard)
|
||||
**Impact on plan:** Necessary for correctness — react-pdf cannot render server-side. The wrapper is a thin file with no behavior change. No scope creep.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None — no external service configuration required for this plan.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Phase 6 signing page is visually complete and compiles cleanly:
|
||||
- /sign/[token] renders correct error states (expired/used/invalid) server-side before any JS runs
|
||||
- Valid tokens render the branded header, full-scroll PDF viewer, pulsing field overlays, and sticky progress bar
|
||||
- GET /api/sign/[token] logs audit events; GET /api/sign/[token]/pdf streams the prepared PDF
|
||||
- Plan 04 can import `SigningPageClient` and wire up `onFieldClick` + the signature modal + submission POST
|
||||
- Plan 04 can populate `signaturesRef.current` with captured signatures and call `setSignedFields`
|
||||
|
||||
---
|
||||
*Phase: 06-signing-flow*
|
||||
*Completed: 2026-03-20*
|
||||
Reference in New Issue
Block a user