69 lines
4.6 KiB
Markdown
69 lines
4.6 KiB
Markdown
# CLAUDE.md — Claude Code Implementation Guide
|
||
## SOP Governance Tool (Stage 1, single-tenant)
|
||
|
||
You are pair-programming with a **coding beginner**, solo founder, 3PL logistics domain expert. Optimize for his learning and maintainability, never cleverness.
|
||
|
||
## Project description
|
||
Web app for ONE company (founder's own warehouse) replacing manual SOP governance: Editors draft SOPs (AI-assisted), Approvers approve/reject, Admin publishes versioned snapshots, Staff view on phone in EN/BM/ZH and tap-acknowledge with a typed-name signature. Dashboard tracks acknowledgement %. Staff also report floor incidents (photo + severity) feeding SOP revisions. Every governance action is audit-logged.
|
||
|
||
## Fixed stack (never substitute)
|
||
Next.js 14+ App Router + TypeScript · Supabase (Postgres + Auth + Storage + RLS) · Vercel · Anthropic API (server-side only) · Tailwind + shadcn/ui. No other DB, ORM (use supabase-js directly), state library, or i18n framework. Ask before adding ANY dependency not already in this list.
|
||
|
||
## Hard rules
|
||
1. `org_id` on every table, RLS enabled on every table — non-negotiable even with 1 org.
|
||
2. State machine (`canTransition()`, `nextVersion()`) lives ONLY in `lib/workflow.ts`. No status transition logic duplicated elsewhere.
|
||
3. AI calls are server-side only (`/api/ai/*` routes), never from the client. `ANTHROPIC_API_KEY` and `SUPABASE_SERVICE_ROLE_KEY` only in server files / Vercel env vars.
|
||
4. Every mutation writes an `audit_log` row in the same transaction (route handler using service-role client).
|
||
5. Published SOP content is a frozen snapshot in `sop_versions` — never edit it; edits happen on the draft row only.
|
||
6. No secrets client-side, never disable RLS "temporarily", never mock away auth to make something work.
|
||
|
||
## Spec-review decisions (apply when the relevant milestone is built)
|
||
- **Storage:** `sop-photos` bucket, path-scoped policy — Editor+ write to SOP step paths; Staff insert-own under `incidents/{user_id}/*` (needed for FR-7.1 staff photo upload). Apply at M6.5/S19.
|
||
- **Approver scope:** Approver acts org-wide, not department-scoped — PRD "in their scope" language is dropped, matches existing RLS/schema. No dept filter needed on approvals.
|
||
- **FR-3.2 notification:** "Editor notified in-app" = visible via SOP status change + History (audit) tab. No separate notifications table/UI.
|
||
- **`sop_status` enum:** drop `archived` — unused in Stage 1, remove from `create type sop_status` in `db/schema.sql` at S2.
|
||
|
||
## Directory layout (from 03-architecture §4)
|
||
```
|
||
/app
|
||
/(auth)/login
|
||
/(admin)/dashboard /sops /sops/[id]/edit /approvals /users /audit
|
||
/(staff)/my-sops /my-sops/[id]
|
||
/api/sops/... /api/ai/... /api/ack ...
|
||
/components (ui/ = shadcn, sop/ = editor pieces, staff/ = mobile viewer)
|
||
/lib
|
||
supabase/ (browser client, server client, service client)
|
||
ai/ (anthropic client, prompts, parsers)
|
||
workflow.ts (status machine)
|
||
audit.ts (writeAudit())
|
||
/db
|
||
schema.sql policies.sql seed.sql
|
||
/docs (spec pack)
|
||
CLAUDE.md
|
||
```
|
||
|
||
## How we work together
|
||
1. **One milestone at a time**, per `docs/07-development-plan.md` session plan (S1...S22). Don't build ahead.
|
||
2. Before writing code for a step: explain the plan in plain English first, wait if it's non-trivial.
|
||
3. After writing code: 3–5 line plain-English summary of what it does and why. If asked "explain", go line-by-line.
|
||
4. **Ask before:** adding a dependency, changing the schema, deviating from a spec, deleting more than ~30 lines.
|
||
5. When something fails: show the error, plain-English diagnosis, then the fix.
|
||
6. Test in the browser after each small step before moving to the next.
|
||
|
||
## Conventions
|
||
- TypeScript strict; server components by default, `"use client"` only when needed.
|
||
- Reads use the user-scoped client under RLS; writes/workflow mutations go through `/app/api/*` with the service-role client.
|
||
- Errors: `{ error: { code, message } }` with correct HTTP status (05-api-spec §6).
|
||
- Commits: imperative plain English, after each working step ("Add SOP publish route with version snapshot").
|
||
- Files: kebab-case; components PascalCase; one component per file.
|
||
|
||
## Current milestone
|
||
**M0 — Setup (S1).** Scaffold Next.js + TypeScript + Tailwind + shadcn/ui; create Supabase project (Singapore region); Supabase clients in `lib/supabase/`; env wiring; deploy hello world to Vercel.
|
||
|
||
## Definition of done (any task)
|
||
Works in the browser · matches its FRD acceptance criteria · no TypeScript errors · explained in plain English · committed · deployed preview checked.
|
||
|
||
## Scratch — next session goal
|
||
(Write 1–2 lines here before each session.)
|
||
|
||
Ignore the add-module skill — it targets a different stack. |