137 lines
6.2 KiB
Markdown
137 lines
6.2 KiB
Markdown
# Round 70 工作计划：审批数据库权威 Clock / TTL / CAS
|
||
|
||
> 日期：2026-08-04
|
||
> 来源：`plan.md` R67-B2、`docs/product/plan-completion-matrix.md` P0 可信试点基线
|
||
> 当前状态：计划完成，待进入实现
|
||
> 外部边界：当前机器 Docker daemon 不可用、无 mysql client、无真实 MySQL 8 测试实例。
|
||
|
||
## 1. 背景与问题
|
||
|
||
`DatabaseApprovalStore` 已具备共享 DB、revision CAS、一次性 grant、同事务 grant/event 和 InnoDB/Alembic 门禁，但审批和 grant 的有效期仍由 Gateway 进程传入 `now_epoch` 或 `time.time()`裁决。两个节点存在正负时钟偏移时，可能对同一请求得出不同 TTL 结论；请求状态转换 CAS 也未把 expiry 条件放入 SQL UPDATE，存在跨过到期边界后的 TOCTOU。
|
||
|
||
## 2. 本轮目标
|
||
|
||
1. MySQL 的审批、转派、过期、grant 创建/消费、事件时间全部使用同一写事务连接取得的数据库权威时间。
|
||
2. MySQL 安全判断忽略调用方绝对 `now_epoch`；SQLite 继续保留 test-only 注入时间以保证确定性测试。
|
||
3. 所有 request CAS 增加 `expires_at_epoch > db_now`，过期 CAS 使用 `<= db_now`。
|
||
4. grant consume/expire 使用同事务 `db_now`，状态和 event 不得部分提交。
|
||
5. 请求 TTL 仅继承调用方给出的持续时间 `expiresAtEpoch-createdAtEpoch`，起点重锚到 MySQL `db_now`；拒绝非有限、非正 TTL。
|
||
6. MySQL epoch 列由 `FLOAT` 升级为 `DOUBLE`，避免 2026 年 epoch 精度损失。
|
||
7. 保持文件审批 backend、Harness/API 合同和 SQLite test-only 边界不变。
|
||
|
||
## 3. 已确认设计决策
|
||
|
||
### 3.1 权威时钟
|
||
|
||
- MySQL：在实际写事务 session 上执行 `SELECT UNIX_TIMESTAMP(CURRENT_TIMESTAMP(6))`。
|
||
- SQLite：使用测试传入 `now_epoch`；未传时只为测试/维护兼容使用 `time.time()`。
|
||
- 其他数据库：继续失败关闭。
|
||
- DB 时钟查询失败：禁止回退应用时钟，操作失败关闭。
|
||
|
||
### 3.2 TTL 与边界
|
||
|
||
- `now < expires`：有效。
|
||
- `now == expires`：已过期。
|
||
- `now > expires`：已过期。
|
||
- request TTL = payload 的 `expiresAtEpoch-createdAtEpoch`，验证为有限且大于 0，再以 `db_now` 重建绝对时间。
|
||
- grant TTL 继续使用 `grant_ttl_seconds`，但起点改为 `db_now`。
|
||
|
||
### 3.3 CAS 与事务
|
||
|
||
每次尝试采用新 session：
|
||
|
||
```text
|
||
BEGIN
|
||
→ 获取 db_now
|
||
→ 读取当前 row/revision
|
||
→ 权限、SOD、payload 校验
|
||
→ status + revision + expiry 条件 UPDATE
|
||
→ 插入 grant（如有）
|
||
→ 插入 event
|
||
→ COMMIT
|
||
```
|
||
|
||
`rowcount=0` 视为 CAS/TTL 未命中并有限重试；数据库断连、权限、schema 或 DB clock 错误不得伪装为普通冲突。
|
||
|
||
### 3.4 Schema
|
||
|
||
当前 SQLAlchemy MySQL DDL 实测生成 `FLOAT`。本轮：
|
||
|
||
- request：`created_at_epoch / expires_at_epoch`
|
||
- grant：`created_at_epoch / expires_at_epoch / consumed_at_epoch`
|
||
- event：`decided_at_epoch`
|
||
|
||
升级为 MySQL `DOUBLE(asdecimal=False)`，SQLite 继续保持现有浮点合同；新增 Alembic revision `20260804_01`，并更新数据库后端启动门禁要求。
|
||
|
||
## 4. 写边界
|
||
|
||
### 允许修改
|
||
|
||
- `server/agent_core/approval_db_store.py`
|
||
- `server/db/models.py`
|
||
- `server/db/migrations/versions/20260804_01_approval_database_clock.py`
|
||
- `tests/golden/test_approval_database_clock.py`
|
||
- 必要时最小更新 `tests/golden/test_approval_database_store.py`
|
||
- Round 70 文档、`plan.md`、完成矩阵和 CHANGELOG
|
||
|
||
### 禁止修改
|
||
|
||
- 文件审批 backend `approval_store.py`
|
||
- Harness、Gateway API、前端
|
||
- approval migration 的 B1 业务逻辑
|
||
- SAP/MES/WMS 集成
|
||
- Round 69 数据生成器和 canonical 数据包
|
||
- 受保护 `server/data` 文件
|
||
|
||
## 5. 验收矩阵
|
||
|
||
### 5.1 本地必须通过
|
||
|
||
- SQLite 边界：到期前/等于/到期后审批、转派和 grant 消费。
|
||
- SQLite 并发：final approve、approve/reject、approve/expire、consume/expire、consume-once。
|
||
- DB clock 查询失败 fail-closed，不回退应用时间。
|
||
- grant/event/commit 故障注入整体回滚。
|
||
- MySQL mock/编译：权威时间 SQL、CAS expiry 条件、六个 epoch 列为 DOUBLE。
|
||
- Alembic upgrade/downgrade 与 ORM 一致。
|
||
- 原有 approval database/migration/store/harness 回归。
|
||
- 全量 golden、Ruff、compileall、8003/5173 健康和受保护数据哈希。
|
||
|
||
### 5.2 外部阻断，不冒充完成
|
||
|
||
当前无 Docker daemon、mysql client 和真实 MySQL 实例，因此本地不能证明：
|
||
|
||
- 两个独立 Gateway 节点正负时钟偏移；
|
||
- MySQL REPEATABLE READ 下的真实多连接并发；
|
||
- deadlock/lock wait timeout、commit 前后断连；
|
||
- session timezone、主从/HA 切换；
|
||
- 生产账号、代理、连接池和真实部署拓扑。
|
||
|
||
本轮完成后矩阵可标记 **Done (local contract) / Partial (external MySQL)**，不得标记生产完成。
|
||
|
||
## 6. 验证命令
|
||
|
||
```powershell
|
||
.venv\Scripts\python.exe -m ruff check server/agent_core/approval_db_store.py server/db/models.py server/db/migrations/versions/20260804_01_approval_database_clock.py tests/golden/test_approval_database_clock.py tests/golden/test_approval_database_store.py
|
||
.venv\Scripts\python.exe -m compileall -q server/agent_core/approval_db_store.py server/db/models.py server/db/migrations/versions/20260804_01_approval_database_clock.py
|
||
.venv\Scripts\python.exe -m pytest -q tests/golden/test_approval_database_clock.py tests/golden/test_approval_database_store.py tests/golden/test_approval_migration.py tests/golden/test_approval_store.py tests/golden/test_harness_p3.py
|
||
.venv\Scripts\python.exe -m pytest tests/golden -q
|
||
npm run test:node
|
||
npm run build:web
|
||
```
|
||
|
||
完成代码后刷新 GitNexus 并执行 `detect_changes(compare main)`；未经用户授权不 commit/push/merge/publish。
|
||
|
||
## 7. 风险门禁
|
||
|
||
- `DatabaseApprovalStore` upstream impact：LOW，7 个受影响符号。
|
||
- `ApprovalRequestRecord` upstream impact：HIGH，127 个受影响符号；修改模型前必须向用户明确预警，并用迁移、DDL 编译和全量回归保护。
|
||
- 若 implementation 发现需修改 Harness/API 或文件审批 backend，立即停止扩界并重新做 impact/计划审计。
|
||
|
||
## 8. Plan Audit
|
||
|
||
`PLAN AUDIT: PASS`
|
||
|
||
Blocking issues：无。
|
||
Clarification needed：无；MySQL 真实环境已明确列为外部验收门禁。
|
||
Non-blocking improvements：未来取得 MySQL 8 实例后补双节点时钟偏移和故障注入，不影响本地合同实现。
|