55 lines
4.9 KiB
Markdown
55 lines
4.9 KiB
Markdown
# CLAUDE.md — Claude Code Implementation Guide
|
||
## SOP Governance Tool (Stage 1, single-tenant)
|
||
|
||
You are pair-programming with a **coding beginner** who is the product owner and domain expert (3PL logistics). Optimize for his learning and for maintainability, not for cleverness.
|
||
|
||
## Project context
|
||
- Full specs live in `/docs` — READ THE RELEVANT SPEC before implementing anything:
|
||
`01-PRD` (scope/roles) · `02-FRD` (requirements + acceptance criteria) · `03-architecture` (stack & decisions AD-1…AD-6) · `04-database-schema` (DDL + RLS) · `05-api-spec` (routes & payloads) · `06-ui-ux` (screens & tokens) · `07-development-plan` (milestones M0–M7, incl. M6.5 incident log).
|
||
- Stack is FIXED: Next.js App Router + TypeScript + Tailwind + shadcn/ui + Supabase + Vercel + Anthropic API. Do not introduce other databases, ORMs (use supabase-js), state libraries, or i18n frameworks.
|
||
- Single org today, but `org_id` + RLS on every table is non-negotiable (AD-1).
|
||
|
||
## How to work with me (the human)
|
||
1. **Explain as you go.** After writing code, give a 3–5 line plain-English summary of what it does and why. If I ask "explain", teach me line-by-line.
|
||
2. **Small steps.** Implement ONE checklist item at a time, then tell me exactly how to test it in the browser before moving on.
|
||
3. **Ask before:** adding any dependency, changing the schema, deviating from a spec, or deleting more than ~30 lines.
|
||
4. **Never** put secrets in client code, disable RLS "temporarily", or mock away auth to make something work.
|
||
5. When something fails, show me the error, your diagnosis in plain English, then the fix.
|
||
|
||
## Conventions
|
||
- TypeScript strict; server components by default, `"use client"` only when needed.
|
||
- All workflow mutations go through `/app/api/*` route handlers using the service-role client; state transitions ONLY via `lib/workflow.ts`; every mutation writes `audit_log` in the same transaction (AD-3).
|
||
- Reads use the user-scoped client under RLS.
|
||
- Errors: return `{ error: { code, message } }` with correct HTTP status (see 05-api-spec §5).
|
||
- Commits: after each working step, imperative plain English ("Add SOP publish route with version snapshot").
|
||
- Files: kebab-case; components PascalCase; one component per file.
|
||
|
||
## Session plan (follow in order; ~2 hours each)
|
||
Before each session: read the matching milestone in `docs/07-development-plan.md` and the FRD items it cites. After each: run the ✅ checklist with me, commit, push (Vercel auto-deploys).
|
||
|
||
- **S1 (M0):** Scaffold app, Tailwind, shadcn init; Supabase clients in `lib/supabase/`; env wiring; deploy hello world.
|
||
- **S2 (M0):** Apply `db/schema.sql` + `db/policies.sql` + `db/seed.sql`; verify tables + RLS deny-by-default with an anon query test.
|
||
- **S3–4 (M1):** Login page + session; profiles + JWT claims hook; role-redirect middleware; route guards.
|
||
- **S5 (M1):** Users & Departments admin pages (invite, role change, deactivate).
|
||
- **S6–7 (M2):** SOP list (filters/search) + create dialog; SOP detail shell with status badge.
|
||
- **S8–9 (M2):** Structured editor: sections nav, step cards (add/reorder/delete), photo upload to Storage, autosave.
|
||
- **S10 (M3):** `lib/workflow.ts` (canTransition, nextVersion) with unit tests; submit route + validation.
|
||
- **S11 (M3):** decide (approve/reject) + approvals queue page; publish route with version snapshot transaction; versions tab.
|
||
- **S12 (M3):** `lib/audit.ts`; wire audit into all mutations; audit page + per-SOP history tab.
|
||
- **S13 (M4):** Assign-departments dialog + route; staff `/my-sops` list (mobile shell, needs-ack vs acked).
|
||
- **S14 (M4):** Staff SOP viewer (mobile, language switcher) + acknowledge flow (typed-name sheet, immutability, re-ack on new version) + share link.
|
||
- **S15 (M5):** Dashboard cards + per-SOP acknowledgement table + department table + overdue badges.
|
||
- **S16 (M5):** Ack report endpoint + CSV export; audit CSV.
|
||
- **S17 (M6):** `lib/ai/` (client, prompts, JSON parser with one retry); `/api/ai/draft` + editor modal; ai_log + daily rate limit.
|
||
- **S18 (M6):** `/api/ai/translate` + translations tab + reviewed flag + staff-viewer fallback rule (safety → English until reviewed).
|
||
- **S19 (M6.5):** Incidents table + policies; POST /api/incidents; staff report flow (viewer "Report a problem" + My SOPs button, severity buttons, photo upload).
|
||
- **S20 (M6.5):** Admin incident list with filters + detail; review/close route with resolution note + "requires SOP revision" jump; SOP detail Incidents tab; dashboard open-incidents card.
|
||
- **S21 (M7):** Security checklist from `docs/03-architecture.md §6` — verify each item with me and show the evidence.
|
||
- **S22 (M7):** Real data seed for the company; fix onboarding frictions; final walkthrough of `docs/02-FRD.md` acceptance criteria.
|
||
|
||
## Definition of done (any task)
|
||
Works in the browser · matches its FRD acceptance criteria · no TypeScript errors · explained to me in plain English · committed · deployed preview checked.
|
||
|
||
## Scratch — next session goal
|
||
(Human writes 1–2 lines here before each session.)
|