cmbuyer/docs/tasks/T-004.md

id, title, phase, deps, status, created, vikunja_task_id, context_ref, work_branch, needs_device, needs_human_review, write_paths

id	title	phase	deps	status	created	vikunja_task_id	context_ref	work_branch	needs_device	needs_human_review	write_paths
T-004	建立核心数据模型与状态机	0	T-001	DONE	2026-08-03	19	c72371c	task/t-004-core-data-state	false	false	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 业务端点、页面、真机判据、提交订单点击或付款。

执行记录

2026-08-03T10:37:05Z · ila

主 agent 二次终审通过：完成 tasks、spec_trials、order_authorizations、order_submissions 的 Goose/SQLite 迁移、纯状态机与迁移 CLI；金额字段均为 TEXT 十进制字符串，无 HTTP、真机、下单点击或付款代码。 返修后迁移 CLI 仅允许 up/down/status；复合外键禁止授权引用其他任务试选记录、提交记录引用其他任务授权；围栏后状态不可回退，第一趟 RUNNING 不可进入 ORDERING。 独立验证：gofmt 无差异，go mod tidy 后干净；go test ./...、go test -race ./...、go vet ./...、go build ./... 通过；真实临时库迁移 up/status 通过；agent-context、diff check 和越界扫描通过。

边界

• 不实现 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。