---
phase: "02-admin-area-interactive-features"
plan: 04
subsystem: "client-interactions"
tags: [api-routes, client-components, approvals, comments, immutability]
dependency_graph:
  requires: ["02-03"]
  provides: ["client-approval-flow", "client-comment-flow"]
  affects: ["src/app/c/[token]/page.tsx", "src/components/phase-timeline.tsx"]
tech_stack:
  added: []
  patterns: ["token-in-body auth", "router.refresh() for Server Component revalidation", "polymorphic entity comments"]
key_files:
  created:
    - src/app/api/client/approve/route.ts
    - src/app/api/client/comment/route.ts
    - src/components/client/ApproveButton.tsx
    - src/components/client/CommentForm.tsx
    - src/components/client/CommentList.tsx
  modified:
    - src/app/c/[token]/page.tsx
    - src/components/client-dashboard.tsx
    - src/components/phase-timeline.tsx
decisions:
  - "approved_at immutability enforced at API layer: route checks approved_at !== null before UPDATE; no-op 200 response if already approved"
  - "Client components use router.refresh() (not full page reload) to re-fetch Server Component data after mutations"
  - "Comments fetched server-side in page.tsx as a single DB query across all entity IDs, passed down as prop — avoids N+1 per entity"
  - "revalidate set to 0 on client page — approvals and comments must always be fresh, ISR would serve stale state"
  - "PhaseTimeline extended (not replaced) to accept token + comments props — Phase 1 UI preserved, interactive elements additive"
  - "ApproveButton renders on all deliverables regardless of status — shows date badge if approved_at set, Approva button otherwise"
metrics:
  duration_minutes: 17
  completed_date: "2026-05-15"
  tasks_completed: 2
  tasks_total: 2
  files_created: 5
  files_modified: 3
---

# Phase 02 Plan 04: Client Interactions — Approvals + Comments Summary

**One-liner:** Client-facing approval and comment API routes with token validation, ownership verification, approved_at immutability enforcement, and inline ApproveButton/CommentForm/CommentList wired into the Phase 1 dashboard via PhaseTimeline.

## Tasks Completed

| Task | Name | Commit | Key Files |
|------|------|--------|-----------|
| 1 | POST /api/client/approve + POST /api/client/comment | c24bdde | src/app/api/client/approve/route.ts, src/app/api/client/comment/route.ts |
| 2 | ApproveButton, CommentForm, CommentList + dashboard wiring | dc512ec | src/components/client/*, src/app/c/[token]/page.tsx, src/components/phase-timeline.tsx |

## What Was Built

### API Routes

**POST /api/client/approve** (`src/app/api/client/approve/route.ts`):
- Reads `{ token, deliverableId }` from request body
- Validates token → finds clientId via `clients` table
- Verifies deliverable ownership: `deliverables → tasks → phases.client_id = clientId` (innerJoin chain prevents cross-client approval — T-02-16)
- Checks `approved_at !== null` — if already set, returns 200 no-op (T-02-17 immutability)
- Sets `status = 'approved'` and `approved_at = new Date()` atomically
- Returns 404 on invalid token or missing deliverable; 500 on unexpected error

**POST /api/client/comment** (`src/app/api/client/comment/route.ts`):
- Reads `{ token, entity_type, entity_id, body }` from request body
- Zod schema validates: entity_type enum, body min 1 / max 2000 chars (T-02-20 DoS mitigation)
- Validates token → finds clientId
- For tasks: verifies task belongs to a phase owned by clientId
- For deliverables: verifies deliverable belongs to a task in a phase owned by clientId (T-02-18)
- Inserts comment with `author: 'client'`
- Returns 201 on success; 400 on validation failure; 404 on invalid token/entity

### Client Components

**ApproveButton** (`src/components/client/ApproveButton.tsx`):
- `'use client'` directive
- If `approvedAt !== null`: renders immutable green badge "Approvato il [localeDateString it-IT]"
- Otherwise: renders "Approva" button; on click POSTs to `/api/client/approve`, calls `router.refresh()` on success
- Loading state disables button; error message shown below on failure

**CommentForm** (`src/components/client/CommentForm.tsx`):
- `'use client'` directive
- Textarea + submit button; disabled when body is empty or loading
- POSTs to `/api/client/comment` with `{ token, entity_type, entity_id, body }`
- On success: clears textarea, calls `router.refresh()` to reload comments from server

**CommentList** (`src/components/client/CommentList.tsx`):
- Pure presentational Server Component (no `'use client'`)
- Renders nothing when empty
- Admin comments: right-aligned, dark bubble, labelled "iamcavalli"
- Client comments: left-aligned, gray bubble, labelled "Tu"

### Dashboard Wiring

**page.tsx** — extended to:
- Collect all task IDs and deliverable IDs from the ClientView
- Run single `db.select().from(comments).where(inArray(comments.entity_id, allEntityIds))` query
- Pass `token` and `allComments` to `<ClientDashboard>`
- Changed `revalidate` from 60 (ISR) to 0 (always fresh)

**client-dashboard.tsx** — updated `ClientDashboardProps` to include `token: string` and `comments: Comment[]`; passes both to `<PhaseTimeline>`

**phase-timeline.tsx** — extended `PhaseTimelineProps` with `token` and `comments`; added `commentsFor()` helper; renders within each task: ApproveButton on each deliverable, CommentList + CommentForm below each deliverable and below each task

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Missing @radix-ui/react-tabs dependency caused build failure**
- **Found during:** Task 1 build verification
- **Issue:** `tabs.tsx` component (from Plan 02-03) imported `@radix-ui/react-tabs` which was listed in `package.json` but not installed in the worktree's node_modules
- **Fix:** Ran `npm install` in the main repo directory to install all declared dependencies
- **Files modified:** None (package install only)
- **Commit:** Resolved before Task 1 commit; no separate commit needed

**2. [Rule 3 - Blocking] Missing .env.local in worktree caused build page-data collection error**
- **Found during:** Task 1 build verification (second attempt)
- **Issue:** `DATABASE_URL env var is required` error during page data collection; .env.local exists in main repo but not copied to worktree
- **Fix:** Copied `.env.local` from main repo to worktree root (file is gitignored)
- **Files modified:** `.env.local` (worktree only, not committed)
- **Commit:** Not committed (gitignored)

**3. [Rule 2 - Missing prop type] ClientDashboard and PhaseTimeline needed prop signature updates**
- **Found during:** Task 2 — IDE diagnostic after updating page.tsx
- **Issue:** `ClientDashboard` and `PhaseTimeline` had no `token` or `comments` props in their interfaces — TypeScript error TS2322
- **Fix:** Updated `ClientDashboardProps` and `PhaseTimelineProps` to include `token: string` and `comments: Comment[]`; updated function signatures and render logic accordingly
- **Files modified:** `src/components/client-dashboard.tsx`, `src/components/phase-timeline.tsx`
- **Commit:** dc512ec (included in Task 2 commit)

## Known Stubs

None — all components are fully wired to live API routes and server-fetched data.

## Threat Surface Scan

All threat mitigations from the plan's `<threat_model>` are implemented:

| Threat ID | Status | Implementation |
|-----------|--------|---------------|
| T-02-15 | Mitigated | Token validated via DB lookup before any mutation in both routes |
| T-02-16 | Mitigated | innerJoin chain (deliverable → task → phase → client_id) prevents cross-client approval |
| T-02-17 | Mitigated | `approved_at !== null` check before UPDATE; no-op 200 if already approved |
| T-02-18 | Mitigated | Entity ownership verified via phase → client_id chain before comment insert |
| T-02-19 | Accepted | Comments scoped to entity_ids from validated client's view; server-side filtered |
| T-02-20 | Mitigated | Zod schema enforces `max(2000)` on comment body; returns 400 if exceeded |

No new threat surface introduced beyond what is documented in the plan.

## Self-Check: PASSED

Files exist:
- src/app/api/client/approve/route.ts: FOUND
- src/app/api/client/comment/route.ts: FOUND
- src/components/client/ApproveButton.tsx: FOUND
- src/components/client/CommentForm.tsx: FOUND
- src/components/client/CommentList.tsx: FOUND

Commits exist:
- c24bdde: FOUND (Task 1)
- dc512ec: FOUND (Task 2)

Build: PASSED (npm run build — no TypeScript errors, all routes listed in output)