diff --git a/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md b/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md index f20bd773..f7f2d7ab 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md +++ b/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md @@ -116,6 +116,7 @@ | PJ2026-01040407 | 观测与验收 | 本规格 6.7 | web-probe observe/analyze、DOM 脱敏、YAML-first 阈值和 issue-ready evidence | 平台运维、公开入口、Cloud Web | D601/v03 原入口验收 | | PJ2026-01040408 | YAML-first 运行配置 | 本规格 6.8 | 独立服务部署、Secret sourceRef、DB/OTel/health/public route 配置 | YAML运维、平台发布 | D601/v03 rollout | | PJ2026-01040409 | MDTODO前端重写 | [PJ2026-01040409 MDTODO前端重写](PJ2026-01040409-mdtodo-web-rewrite.md) | 清除旧 MDTODO Web 前端并按有界三栏、Rxx 树、报告预览和主动编辑重新实现 | Project Management API、Web工作台、web-probe | D601/v03 MDTODO 原入口可用性 | +| PJ2026-01040410 | TaskTree PostgreSQL持久化 | 本规格 6.9 | TaskTree 在线事务、schema migration、CLI/API repository 一致性和灾备边界 | PostgreSQL、Temporal、API契约 | TaskTree CLI、API、worker 和 Web | ### 5.1 目标架构图 @@ -440,6 +441,33 @@ D601/v03 的 HWPOD-bound MDTODO 验收应允许把 Source 配置到 `hwpodId=d60 Secret、DB DSN、provider token、session token、API key、host path 和 raw Markdown 内容不得出现在默认 CLI 输出、probe 报告、日志或错误 envelope 中。输出只披露对象名、key 名、sourceRef、presence、fingerprint、hash、字节数和 `valuesRedacted=true` 摘要。 +### 6.9 CLIENT-PM-REQ-009 TaskTree PostgreSQL持久化与schema migration + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-009 | TaskTree持久化 | PJ2026-01040410 TaskTree PostgreSQL持久化 | [API契约](PJ2026-010403-api-contract.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +- TaskTree 的在线事务权威固定为 PostgreSQL: + - 本地 dispatcher、API 和 Temporal worker 必须共享同一 repository 合同; + - GitHub 快照只承担版本化灾备,不成为在线读写 authority; + - CLI transport 切换不得改变命令、DTO、状态流转和错误语义。 +- Schema migration 必须采用版本化单写语义: + - 每个 migration 使用稳定且单调的版本标识,并在数据库 ledger 中记录完成状态; + - 多进程同时初始化时,使用 PostgreSQL transaction advisory lock 或等价数据库级事务锁串行化 migration 临界区; + - 等待者取得锁后必须重新读取 ledger,只执行尚未完成的版本; + - 已完成全部 migration 的普通读命令不得再次执行 `ALTER TABLE`、constraint 重建或其他 DDL; + - constraint 调整必须属于一次性版本 migration,禁止在每次 store 初始化时重复 drop/add。 +- Migration 失败必须保持可恢复和可观察: + - migration DDL 与 ledger 更新必须在同一事务内提交或回滚; + - 失败时保留 PostgreSQL SQLSTATE、migration 版本和稳定错误上下文; + - 禁止用静默重试、忽略 DDL 错误或返回空数据掩盖 migration 缺陷; + - CLI 成功或失败都必须返回一次完整 JSON envelope,不能以数据库已写入替代调用端输出。 +- 验收必须覆盖可变化的并发场景: + - fresh database 中多个 store 并发初始化后,只完成一次 schema migration,所有调用返回正常 envelope; + - existing database 中并发执行 group、task 和 report 只读命令时,不出现 `40P01` 或重复 DDL; + - migration 中途失败后事务完整回滚,后续初始化可从 ledger 状态继续; + - 并发客户端数量和重复轮次由测试参数控制,不写入生产配置或规格固定值。 + ## 7. 过程控制 本规格的阶段活动由架构治理 issue [#2123](https://github.com/pikasTech/HWLAB/issues/2123) 拆分跟踪: