cmbuyer/docs/tasks/T-004.md

---
id: T-004
title: 建立核心数据模型与状态机
phase: 0
deps: [T-001]
status: DONE
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
---

<!-- BEGIN VIKUNJA EXPORT id=19 synced=2026-08-03T10:37:34Z sha256=a848b2881154932ac8dd7ac46abbbd8a58da1664c50a0901dccd905eb00db5c2 -->
## 问题 / 背景

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 和越界扫描通过。
<!-- END VIKUNJA EXPORT -->

## 边界

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