# Project Handover — Validation Checklist

Run this before declaring the handover manual complete. Every box must be checked or explicitly waived with a reason recorded in section 10 (Open Questions).

## Coverage of the four required pillars

### Business data-flow main chains (section 3)

- [ ] At least the 3 most important business main chains are documented (not just one)
- [ ] Each chain names its trigger (HTTP / MQ / scheduled job / callback) with `file:line`
- [ ] Each chain has a Mermaid sequence diagram covering entry → service → rules → persistence → external/writeback
- [ ] Each chain has a stage table (stage / entry / key class·method / input / processing / output·state-change / persistence / failure handling)
- [ ] Sync vs async hops (MQ / thread pool) are distinguished
- [ ] Transaction boundaries, idempotency keys, and compensation/rollback are noted where they exist
- [ ] State machines / status enums are documented where present

### Third-party integration inventory (section 4)

- [ ] Dependency manifests were scanned (package.json / pom.xml / build.gradle / go.mod / requirements.txt / Gemfile, etc.)
- [ ] HTTP/RPC clients and middleware (DB, cache, MQ, object storage, config/registry center, search, monitoring) are all included
- [ ] For EVERY integration: name, purpose, call style, key client class, config location (file:key), auth, and **failure-degradation behavior** are filled — no blanks
- [ ] Failure handling explicitly states retry / circuit-breaker / fallback / degrade / none for each integration
- [ ] An "environment & secrets" note tells a new dev what is needed to run locally and where secrets live

### Design highlights & trade-offs (section 5)

- [ ] Key design decisions / patterns / extension points are listed (not just "uses Spring")
- [ ] Each entry explains the problem it solves AND why it was chosen AND what was traded off
- [ ] Each entry is marked as verified (doc/comment/ADR/commit) vs inferred (needs author confirmation)

### Known pitfalls & legacy debt (section 6)

- [ ] Marker scan was run (TODO / FIXME / HACK / XXX / @Deprecated / workaround / 临时 / 兼容 / 历史 / 慎改 / 坑)
- [ ] At least the categories present in the code are covered: traps, implicit dependencies, temporary hacks, perf/concurrency, weird naming, legacy
- [ ] Each pitfall has location, symptom/risk, trigger condition, how-to-avoid, and severity

## Newcomer usability

- [ ] Section 1 (Orientation) lets a stranger build a mental model and run the project
- [ ] Section 2 (Module map) answers "to change feature X, which module do I touch?"
- [ ] Section 7 (Glossary) defines the non-obvious terms / abbreviations / status codes / table names used in the doc
- [ ] Section 8 (Onboarding checklist) gives concrete first steps including a starter task
- [ ] Section 9 (Troubleshooting pointers) maps common symptoms to where to look first

## Evidence & honesty

- [ ] Concrete claims cite `file:line` (or `file`) — not vague generalities
- [ ] Inferences are clearly flagged with the ⚠️ marker and collected in section 10 (Open Questions)
- [ ] No fabricated APIs, tables, or integrations — only what exists in the code

## Output hygiene

- [ ] HANDOVER.md written to `{project_knowledge}/`
- [ ] No leftover `<!-- FILL` markers remain in the final document
- [ ] No template comment blocks (the single-chain template, etc.) remain
- [ ] Mermaid diagrams are syntactically valid (render-checkable) — no raw `<` `>` `{` `}` in diagram message text (they break the parser; use plain words like `applyNo`)
- [ ] Document is written in `{document_output_language}`
- [ ] Markdown renders cleanly (tables aligned, code fences closed)

## Completion criteria

The handover manual is complete when:

1. All four required pillars (sections 3–6) are concrete and non-empty
2. Every integration row has a failure-degradation value
3. No `<!-- FILL` markers or template scaffolding remain
4. Inferences are flagged and gathered in Open Questions
5. The user has reviewed and confirmed the manual is usable for onboarding