Adopt agents-settings kit, ship Product/SKU scan models, harden auth, verify OCR accuracy

Backend (app-pfm-ocr-v2/backend): - Product/SKU scan feature complete: trained DINOv2 index (118 reference photos, 16 SKU classes) and YOLO classifier (83.3% top-1 val accuracy), fixed scripts/install-pipeline.sh (was missing ultralytics/torch), fully browser-verified end-to-end on /scan-pfm. Mobile m-scan-pfm page cancelled (Flutter app handles mobile; web UI is desktop-only for pipeline testing). - Fixed a real data-loss bug: Save Ground Truth (scan-pfm and the DO-flow's manual-label) was silently writing into the pfm-web-app container's ephemeral filesystem instead of the host, because /sources wasn't bind-mounted in docker-compose.yml. Added the mount, recovered an orphaned entry. - accounts.password is now bcrypt-hashed (bcryptjs, idempotent migration in db/init.ts) instead of plaintext; login route compares hashes. - /api/v1/documents/* (list, PUT, upload) now enforces real 401 auth, matching what the Flutter client already sends. The "classic" routes deliberately stay open — they're dev-only web UI with no login flow and won't exist in production. - OCR accuracy investigated end-to-end: real baseline is 95.10% overall (target met; accuracy_report.md was stale at 75.04%, now flagged). Fixed one genuine parser.ts bug (SO/DO field duplication in the global fallback regex); remaining gaps are OCR/layout-model limitations, not parser bugs. - Adopted a standalone copy of the fhanyuh/agents-settings e/n workflow scoped to backend/ (AGENTS.md Part A/B split, SKILLS.md, plans/, docs/), independent of the root copy which now covers Flutter only. - next-implementation.md deleted; content folded into backend/plans/next-enhancements.md for traceability. Root: - Adopted fhanyuh/agents-settings kit (AGENTS.md, SKILLS.md, plans/, docs/feature-list.md), scoped to the Flutter app only. - Pending documents queue now persists to Hive (lib/core/storage) instead of memory-only, surviving an app kill mid-upload. Removed backend_backup/ (stale Express/Prisma prototype, superseded by pfm-web-app) and the completed plans/next-enhancement-plan.md checklist. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-08 11:56:32 +07:00
1 parent 3df9f6ec5d
commit e60ab63154
@@ -0,0 +1,212 @@
+# Agent Instructions
+
+This is the authoritative rules file for any AI coding agent (Claude Code, Cursor,
+GitHub Copilot, Aider, etc.) working in a project that uses this starter kit. Agents
+that don't read AGENTS.md natively should be pointed at it via their own config file
+— see `docs/vibe-coding/` for per-tool instructions. `CLAUDE.md` imports this file.
+
+## Scope: excludes `backend/`
+
+This kit's automated behaviors — the `e`/`enhance` and `n`/`next` triggers, the §3
+file-size threshold as an *enforcement action* (splitting a file because this kit
+says so), and the §5 Demo/Live and §6 Cloud/Local switches — govern the **Flutter
+app at the repo root** (`lib/`, `test/`, root-level config/docs) only.
+
+**`backend/` is out of scope for this kit.** It is a separately governed subtree
+with its own pre-existing rules files — `backend/CLAUDE.md` (project-specific
+architecture/history/confidentiality notes) and `backend/AGENTS.md` (carried over
+near-unchanged from `ai-ocr-pfm-2026`: uv conventions, issue-recording workflow,
+karpathy coding guidelines) — that predate this kit's adoption and are tuned to
+that codebase's own conventions. Do not let this kit's generic rules override or
+be conflated with them:
+- Don't run `e`/`enhance` against `backend/` modules, and don't let `n`/`next`
+  auto-seed or pick up backend-section tasks, unless the user explicitly asks for
+  a backend-scoped run for that specific invocation.
+- Don't apply §3's 256-line split as a repo-wide mandate inside `backend/` — that
+  subtree already documents its own pre-existing large files as accepted debt (see
+  `backend/CLAUDE.md`) and has its own change conventions.
+- §5 (Demo/Live) and §6 (Cloud/Local) describe app-level UX switches for the
+  Flutter client; they are not a mandate to add mock-data layers or deployment
+  switches inside the Next.js backend.
+- If asked to work inside `backend/`, defer entirely to `backend/CLAUDE.md` and
+  `backend/AGENTS.md` (and `backend/plans/next-enhancements.md` for feature-level
+  status — `backend/next-implementation.md` was deleted 2026-07-08, its content
+  folded into that plan) instead of this file.
+
+See **Adaptation Notes** at the end of this file for how `plans/next-enhancements.md`
+reconciles this after an earlier adoption pass mistakenly seeded backend sections.
+
+## 0. Adopting Into an Existing Project
+
+This kit auto-detects whether it's landing in a new or existing codebase — no
+separate trigger is required. You can also type "i" / "init" at any time to force a
+re-audit (e.g. after a large refactor or reorg).
+
+**Auto-detection**: the first time "e"/"enhance" or "n"/"next" runs, if
+`plans/next-enhancements.md` is still the empty seed template (or missing) AND the
+repo already contains files/history beyond this kit's own files, treat it as an
+existing project and run the audit below first. Skip it on a genuinely empty/new
+project — there's nothing to audit.
+
+**The audit** (owned by the Software Architect role, see `SKILLS.md`):
+- **Don't overwrite silently.** If the repo already has its own README.md/AGENTS.md/
+  CLAUDE.md, merge additively — append a clearly-marked section pointing at this
+  kit's files rather than deleting existing project-specific instructions.
+- **Discover reality before writing anything**:
+  - Detect the tech stack and real build/test/lint commands (package.json, Makefile,
+    pyproject.toml, etc.).
+  - Map the actual existing folder/module structure — this becomes the section list
+    `e`/`enhance` uses, replacing invented sections.
+  - Scan for files already over the 256-line threshold (§3) and list them as
+    **pre-existing debt**, not a blocker — the rule binds new/touched files going
+    forward, it does not retroactively force-refactor untouched legacy code.
+  - Check for existing equivalents of Demo/Live (§5) or Cloud/Local (§6) patterns;
+    adapt to what's already there instead of introducing a redundant second switch.
+- Seed `plans/next-enhancements.md` sections from the real discovered modules (not
+  blank placeholders); optionally backfill `docs/feature-list.md` with a short
+  "Existing Features (pre-kit)" summary so the log doesn't start misleadingly empty.
+- Record any deviation from this kit's defaults (because the project already does it
+  differently) as a short **Adaptation Notes** subsection appended to the end of this
+  file — so future `e`/`n` runs see local reality, not just the template's
+  assumptions.
+- Once the audit (and any merge/adaptation) is done, `e`/`enhance` and `n`/`next`
+  behave exactly as described below.
+
+## 1. Trigger "e" or "enhance"
+
+If the user types "e", "enhance", or requests an enhancement plan:
+- Read `/plans/next-enhancements.md` to understand the current platform structure, history, and active tasks.
+- Overwrite or update the active tasks list inside `/plans/next-enhancements.md`.
+- The plan must cover each main section/module of the application.
+- Inside the tasks list, define **exactly 3 new enhancements per section** with:
+  1. A unique number (e.g., `1.1`, `1.2`, `1.3`).
+  2. A clear, specific description of the functional change.
+  3. A status (initially set to `[TODO]`).
+- Present this plan to the user in your final summary response.
+
+## 2. Trigger "n", "next", or "n{x}"
+
+If the user types "n", "next", "n{x}" (where `{x}` is a positive integer), or requests execution of the next enhancement task(s):
+- Read `/plans/next-enhancements.md` to check the status of tasks.
+- If all tasks are `[DONE]` (or none are `[TODO]`), automatically run the **"e" / "enhance"** workflow first.
+- Otherwise, select the most impactful `[TODO]` task(s) by strategic value, functional impact, or UX contribution — not just the first in order. If `{x}` is given, select the top `{x}` tasks and execute them sequentially.
+
+### 2a. Clarify before building ("Grill Me" step)
+
+Before implementing a task, check whether its scope or acceptance criteria are
+genuinely ambiguous (multiple valid interpretations, unspecified UI/data behavior,
+no clear "done" condition). If so:
+- Ask clarifying questions **one at a time** until the task is unambiguous — use
+  your tool's native mechanism (e.g. Claude Code's `AskUserQuestion`) where available,
+  otherwise ask inline and wait for the answer before continuing.
+- Record the resolved acceptance criteria as a short 1-3 line note next to the task
+  entry in `/plans/next-enhancements.md` before writing any code.
+- Skip this step entirely when the task is already unambiguous — don't grill the
+  user on obvious work.
+
+- Implement the selected task(s) fully in the codebase, applying the relevant role(s)
+  from `SKILLS.md` (Architect, Backend, Frontend, QA, Hardware/Compatibility).
+- Once complete:
+  1. Update the task's status in `/plans/next-enhancements.md` to `[DONE]`.
+  2. Document the new/updated feature in `/docs/feature-list.md` under the right section heading.
+- **Verify build integrity** — this is not just "it compiles and runs":
+  - QA pass: exercise the golden path and edge cases; run/extend automated tests.
+  - Hardware/Compatibility pass: check cross-platform, cross-browser, and resource
+    (memory/CPU) assumptions per `SKILLS.md`.
+- In your final response, state which task(s) were completed and the exact menu/navigation path to see the new feature.
+
+## 3. File Size & Refactoring Rules
+
+- **256-line threshold**: any code/script file — new, modified, or pre-existing —
+  that exceeds 256 lines of code must be split into smaller, modular, logical files.
+  This is a repo-wide rule, not just for new work; if you touch a file over the
+  threshold, split it as part of that change.
+- **Why**: an agent reading a file spends its context budget parsing it before it can
+  reason about the task. Small, single-purpose files keep that cost low and keep the
+  agent's understanding accurate (see the "smart zone / dumb zone" problem — models
+  reason worse as context fills up).
+- This applies to AGENTS.md, CLAUDE.md, and SKILLS.md too: keep each under ~250 lines.
+  Push detail into linked docs (`docs/`) rather than growing the root files.
+
+## 4. Roles
+
+Every implementation task should be viewed through the lens of the relevant role(s)
+defined in `SKILLS.md`: Software Architect, Backend Engineer, Frontend Engineer,
+QA/Test Engineer, and Hardware & Performance Compatibility Reviewer. A single agent
+plays all roles in sequence unless the harness supports spawning role-specific
+subagents (see `CLAUDE.md`).
+
+## 5. Mockup Data & Demo/Live Mode
+
+- Store all mock/sample data in `/data/mockup/` — keep it separate from UI components and styling.
+- Provide a mock API layer that reads from `/data/mockup/` and mirrors the real backend contract.
+- Add a switcher control (icon) in the UI to toggle **Demo** (mock API + mock data) and **Live** (real API + real data).
+
+## 6. Cloud vs Local (On-Premise)
+
+- Provide a setting to choose **Cloud** or **Local (on-premise)** deployment.
+- **Cloud**: use remote/cloud-hosted API endpoints and services.
+- **Local**: use on-premise/self-hosted API endpoints and services.
+- Persist the selection and route all backend/service calls to the chosen environment.
+
+## 7. Ad-hoc Feature Requests
+
+For direct feature requests not using "e"/"n", implement the feature and document it in `/docs/feature-list.md`.
+
+## Adaptation Notes (this project)
+
+Recorded 2026-07-08, from adopting this kit into the existing `app-pfm-ocr-v2` repo.
+
+- **Tech stack**: Flutter mobile app at the repo root (`lib/`) is the field client;
+  `backend/` runs a Next.js API gateway + Python PaddleOCR/vLLM OCR pipeline +
+  Postgres. See root `CLAUDE.md` and `backend/CLAUDE.md` for full architecture.
+- **Real commands**: `flutter test`, `flutter analyze lib`, `flutter build apk --release`
+  (Flutter, repo root); `npm run dev`/`build`/`lint` inside `backend/pfm-web-app`
+  (Next.js) — see `backend/CLAUDE.md` for the OCR accuracy regression harness and the
+  uv/vLLM Python service commands. There is no single unified test runner across both
+  halves; Flutter and backend are tested independently.
+- **Real module boundaries** (seeded into `plans/next-enhancements.md`): Flutter —
+  Auth & Splash, Camera Capture & Geotagging, Pending Documents Queue, Document
+  Editor & PDF Receipt; Backend — Next.js API Gateway, OCR Pipeline & Accuracy,
+  Postgres Data Layer, DevOps/Docker & Dev Tunnel.
+- **Scope correction (2026-07-08, later same day)**: an early `e`/`enhance` run
+  seeded and executed against the four Backend sections above (5-8) before the
+  **Scope: excludes `backend/`** rule at the top of this file was written. Those
+  sections were first frozen as archival, then removed outright from
+  `plans/next-enhancements.md` (2026-07-08) once `backend/` got its own independent
+  kit copy — the already-shipped 7.1 DB-transaction fix stays recorded in
+  `docs/feature-list.md`, but the task itself no longer has an entry in this file's
+  plan. `plans/next-enhancements.md` now tracks only the Flutter sections (1-4).
+  Backend enhancement tracking lives entirely in `backend/`'s own copy of this kit
+  (`backend/plans/next-enhancements.md`, driven by `backend/AGENTS.md` Part B).
+- **Pre-existing files over the 256-line threshold** (§3 debt, not a blocker — split
+  only if/when touched going forward), **Flutter only** now that `backend/` is out of
+  scope for this kit (see §Scope above; backend's own debt list, re-verified
+  2026-07-08, lives in `backend/AGENTS.md`'s Adaptation Notes instead):
+  `lib/features/editor/editor_screen.dart` (682), `lib/features/documents/documents_screen.dart`
+  (442), `lib/features/camera/image_preview_screen.dart` (380), `lib/features/camera/camera_screen.dart`
+  (376), `lib/features/documents/pending_documents_provider.dart` (271).
+- **No Demo/Live or Cloud/Local switch exists yet** (§5, §6). The closest existing
+  analogue is `AppConfig.initializeApiBaseUrl()` in `lib/config/app_config.dart`,
+  which dynamically resolves a *real* backend endpoint (ngrok tunnel, falling back to
+  a LAN IP) — it always talks to the live backend with real data, never mock data, so
+  it is not a Demo/Live switch. Building an actual mock-data Demo mode and a
+  Cloud/Local deployment switch remain open `n`/`next` work, not something this
+  adoption pass implemented.
+- **Naming collision to watch for**: `docker-compose.demo.yml` at the repo root
+  already uses "demo" for an unrelated concept — a **production-mode** Compose
+  override (`npm start` instead of `npm run dev`), not a mock-data mode. Don't
+  conflate it with §5's Demo/Live data switch when that feature is eventually built.
+- **Pre-existing, unrelated governance files left as-is** (not part of this kit, not
+  touched by this adoption):
+  - `.agents/AGENTS.md` — a short set of OCR post-processing/parsing rules (table
+    column-shift correction, date normalization). Different purpose and path from
+    this kit's root `AGENTS.md`; both coexist.
+  - `plans/next-enhancement-plan.md` (singular) — a pre-existing, fully `[DONE]` QA
+    verification checklist auto-managed by "QE guidelines," unrelated to the `e`/`n`
+    workflow's `plans/next-enhancements.md` (plural, added by this kit). Kept side by
+    side, not merged or migrated.
+- **CLAUDE.md**: the repo already had a substantial project-specific root
+  `CLAUDE.md`. Per this section's "merge additively" rule, this kit's import and
+  Claude-specific notes were appended as a new, clearly-marked section rather than
+  replacing the file.