80835138e9
- README: orientation, doc map, target package layout (pointers only, no duplicated architecture content) - CLAUDE.md: agent operating manual — invariants as code-review rules, conventions, do-not list, task reading order - ROADMAP: M1-M5 with verifiable acceptance criteria, phase-2 fence - GLOSSARY: canonical Chinese-term → code-name mapping - docs/adr/: eight ADRs recording settled decisions and rejected alternatives - docs/open-questions.md: consolidated TODO(业务) tracker by owner and blocking milestone - .gitignore; untrack .DS_Store Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr 🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh
21 lines
996 B
Markdown
21 lines
996 B
Markdown
# ADR-0002: zod as schema source of truth
|
|
|
|
**Status**: accepted · 2026-09
|
|
|
|
**Context**: Business objects cross TS runtime ↔ Python skills; schema drift
|
|
between languages is the classic failure. Someone must own the truth.
|
|
|
|
**Decision**: Hand-written zod schemas in `packages/domain` are the only
|
|
source. Build exports JSON Schema to `contracts/` (committed, versioned);
|
|
pydantic models are generated from those (never hand-edited). Golden fixtures
|
|
validated by both CIs. Data representation rules in docs/11 §3.3 are part of
|
|
the contract (decimal strings for money, units in field names, etc.).
|
|
|
|
**Alternatives**: Hand-written JSON Schema as neutral source (revisit if
|
|
Python-side partners need co-ownership — the contracts/ layer stays identical);
|
|
protobuf/gRPC (rejected: call volume doesn't need it, lineage snapshots should
|
|
be human-readable, partner onboarding cost).
|
|
|
|
**Consequences**: Python teams depend only on `contracts/`, never on TS
|
|
internals — org boundary = code boundary.
|