diff --git a/docs/tasks/T-004.md b/docs/tasks/T-004.md new file mode 100644 index 0000000..32bf39b --- /dev/null +++ b/docs/tasks/T-004.md @@ -0,0 +1,67 @@ +--- +id: T-004 +title: 建立核心数据模型与状态机 +phase: 0 +deps: [T-001] +status: DOING +created: 2026-08-03 +vikunja_task_id: 19 +context_ref: c72371c +work_branch: task/t-004-core-data-state +needs_device: false +needs_human_review: false +write_paths: + - docs/tasks/T-004.md + - admin/go.mod + - admin/go.sum + - admin/cmd/migrate/** + - admin/internal/domain/** + - admin/internal/migrations/** + - admin/internal/storage/sqlite/** + - admin/migrations/** + - docs/04-architecture.md + - docs/api.md +--- + + +## 问题 / 背景 + +T-001 已建立可运行的采购服务骨架,但尚无业务实体、数据库 schema 或可验证的状态机。后续登录、建单、领取、授权和提交围栏都依赖一致的数据模型;若先写 HTTP 页面再补状态约束,会把资金安全边界分散到处理器中。 + +## 关联需求与交互 + +- 功能:Phase 0 核心数据模型地基。 +- 用户故事 / 交互:不适用,不实现生产页面。 +- 架构 / API:以 docs/04-architecture.md 第四、第五节和 docs/api.md 为权威;schema 变化必须同步两者。 + +## 方案 + +1. 从现有架构/API逐字段提取 tasks、order_authorizations、order_submissions,不臆造接口字段。 +2. 使用 goose 与 SQLite 建立可重复迁移及约束;金额只存十进制字符串,禁止 float。 +3. 在 admin/internal/domain 建立显式状态与合法转换,非法转换 fail closed,并用表驱动测试覆盖。 +4. 对一次性授权、提交围栏和不可重试结果只建立数据约束与纯状态规则,不实现 HTTP、真机点击或下单函数。 +5. T-002 为 DOING 时不修改 docs/current-state.md;代码与架构/API完成后先记录验证,待 T-002 关闭再扩展 write_paths 并收口状态快照。 + +## 验收要点 + +- tasks、order_authorizations、order_submissions 表和约束与架构文档一致,迁移可重复向上/向下验证。 +- 核心状态合法/非法流转有单元测试;第一趟状态路径不引用任何下单函数。 +- 金额字段是十进制字符串,代码和 schema 不使用浮点数。 +- go test ./...、go vet ./...、go build ./... 通过。 +- 不实现 HTTP 业务端点、页面、真机判据、提交订单点击或付款。 + +## 执行记录 + +(暂无) + + +## 边界 + +- 不实现 HTTP 业务端点、管理页面、设备领取、真机自动化或 Phase 2+ 服务。 +- 不编写或引用任何真机下单函数,不点击提交订单,不涉及付款。 +- 不放宽 `docs/04-architecture.md` 第四节任何边界;代码与文档不一致时先停止并由主 agent + 复核,不以“跑通”为理由改弱约束。 +- 不修改 `client/`、需求、交互原型、启动入口或 T-002 当前占用的 `docs/current-state.md`。 +- 如完成代码后仍需更新 `docs/current-state.md`,必须等待 T-002 关闭并先提交 `write_paths` + 扩展;不得在两个 `DOING` 任务间制造共享路径冲突。 +- 不使用前序项目 schema 作为事实来源;所有字段和状态只取自本仓库架构/API。