docs(workflow): Phase 0 基线确认、架构决策记录(ADR)与契约冻结

.doc/system-design/project-workflow/04-项目多工作流与智能产品经理-测试经理工作流-实施计划.md

@@ -0,0 +1,798 @@
+# 项目多工作流与智能产品经理、智能测试经理工作流实施计划
+
+> 文档性质：分阶段实施计划
+>
+> 依赖方案：`03-项目多工作流与智能产品经理-测试经理工作流-设计方案.md`
+>
+> 编制日期：2026-09-10
+>
+> 本文范围：计划、任务拆分、测试与上线策略，不直接实施代码改造
+
+## 1. 实施目标
+
+在不替换现有 Go/SSE、Coordinator、Context、Squad、DocGov 运行时的前提下，实现：
+
+1. 服务端权威的项目创建人与项目工作流模型；
+2. 一个项目拥有多个工作流、至多一个当前激活工作流；
+3. 仅项目创建人可以原子切换当前激活工作流；
+4. 智能产品经理工作流生成系统需求规格书；
+5. 智能测试经理工作流基于项目上下文和产品经理输出生成系统验证方案及计划；
+6. 上下游文档版本化追溯和 stale 传播；
+7. 完整的权限、并发、失败恢复、质量门禁、前端交互和审计测试。
+
+## 2. 实施原则
+
+- **先控制面，后执行面**：先建立项目—工作流—激活权限，再增加两个工作流；
+- **先产品经理，后测试经理**：测试经理依赖产品经理输出，不能并行盲目接入；
+- **保持领域边界**：项目工作流控制进入新领域模块，不污染 Squad 内部步骤状态；
+- **服务端权威**：创建人、工作流归属、激活状态和上游版本均不信任前端；
+- **兼容迁移**：老任务入口可过渡，但所有新增写操作经过新服务；
+- **可回滚**：数据库变更向前兼容，功能通过开关逐级启用；
+- **测试先行**：每阶段先补契约/失败用例，再实现；
+- **不触碰历史用户改动**：实施时先记录干净基线，逐模块提交，避免混入当前工作区未提交内容。
+
+## 3. 阶段总览
+
+建议分为八个阶段：
+
+1. Phase 0：基线确认与契约冻结；
+2. Phase 1：数据库和项目身份权威化；
+3. Phase 2：项目多工作流控制面；
+4. Phase 3：Coordinator、上下文与 API 集成；
+5. Phase 4：智能产品经理工作流；
+6. Phase 5：智能测试经理工作流与文档血缘；
+7. Phase 6：前端项目工作流体验；
+8. Phase 7：端到端验证、迁移、灰度和上线。
+
+建议不要把八个阶段压成一个大提交。至少拆为数据库/领域服务、产品经理、测试经理、前端四组可独立审阅的变更。
+
+## 4. Phase 0：基线确认与契约冻结
+
+### 4.1 目标
+
+消除当前项目模型、认证模型、文档模型和命名上的歧义，形成后续改造的稳定契约。
+
+### 4.2 任务
+
+1. 确认生产环境权威项目表来自哪个迁移链，统一 `deploy/postgres/system_init.sql` 与 `context_init.sql` 的结构演进方式；
+2. 确认前端“新建项目”是否正式迁移为服务端创建；本方案要求答案为是；
+3. 冻结工作流键：
+   - `product_manager`；
+   - `test_manager`；
+4. 冻结阶段/任务键：
+   - 产品经理：`stage_key=system_reqs`、`task_key=system_reqs`；
+   - 测试经理：`stage_key=system_test_plan`、`task_key=test_manager`；
+5. 明确正式文档名称：
+   - 《系统需求规格书》；
+   - 《系统验证方案及计划》，UI 别名《系统测试方案》；
+6. 明确测试经理正式模式默认要求产品经理文档处于 `approved`；
+7. 明确项目创建人不可通过普通项目编辑 API变更；
+8. 明确激活工作流只改变路由焦点，不取消任务；
+9. 盘点当前未提交改动，建立本功能的独立分支或独立提交边界；
+10. 建立 API 错误码清单与 JSON 契约快照。
+
+### 4.3 输出
+
+- 架构决策记录（ADR）；
+- API 契约草案；
+- 数据迁移说明；
+- 工作流键与文档名称表；
+- 测试矩阵初稿。
+
+### 4.4 完成条件
+
+- 所有关键命名不再冲突；
+- 创建人、激活、运行、文档状态四者语义得到确认；
+- 生产数据库迁移入口明确；
+- 旧接口兼容期限明确。
+
+## 5. Phase 1：数据库和项目身份权威化
+
+### 5.1 数据库迁移
+
+新增迁移文件，完成：
+
+- `projects.creator_user_id`；
+- `projects.active_workflow_key`；
+- `projects.workflow_selection_version`；
+- `projects.active_workflow_changed_at/by`；
+- `project_workflows`；
+- `workflow_runs`；
+- `workflow_activation_audits`；
+- `document_lineage` 或文档表的等价血缘字段；
+- 必要索引、唯一约束和状态 CHECK；
+- 历史项目回填脚本和不可推断项目报告。
+
+迁移必须先允许 `creator_user_id` 为空，在完成历史数据回填后再决定是否增加非空约束。
+
+### 5.2 项目 Store 与 Service
+
+新增或完善：
+
+- `CreateProject(ctx, authenticatedUser, input)`；
+- `GetProjectForUser(ctx, projectID, userID)`；
+- `ListProjectsForUser(ctx, userID)`；
+- `IsProjectCreator(ctx, projectID, userID)`；
+- 项目成员可见性检查；
+- 项目创建事务内初始化工作流实例。
+
+### 5.3 项目 API
+
+实现：
+
+- `POST /api/v1/projects`；
+- `GET /api/v1/projects`；
+- `GET /api/v1/projects/{id}`。
+
+认证要求：
+
+- 从 Bearer token 获取用户；
+- 忽略或拒绝请求体中的创建人 ID；
+- 无权项目不泄露元数据；
+- 日志记录请求 ID与用户 ID，但不记录令牌。
+
+### 5.4 测试
+
+- 创建项目自动记录登录用户为创建人；
+- 客户端伪造创建人无效；
+- 未登录不能创建；
+- 无权用户不能查询项目；
+- 项目创建和工作流初始化事务一致；
+- 初始化中途失败时项目与工作流均回滚；
+- 历史项目回填可重复运行且幂等；
+- PostgreSQL 集成测试验证外键与并发。
+
+### 5.5 完成条件
+
+- 服务端可权威回答“谁创建了项目”；
+- 新项目不再只存在于前端 `localStorage`；
+- 所有新增项目自动得到项目工作流实例。
+
+## 6. Phase 2：项目多工作流控制面
+
+### 6.1 工作流目录
+
+实现统一 `Catalog` 接口：
+
+```go
+type Catalog interface {
+    Get(workflowKey string) (Definition, bool)
+    List() []Definition
+    Validate() error
+}
+```
+
+首期注册现有主线、`product_manager`、`test_manager`。每个定义包含版本、阶段、模板、步骤提供器、输入契约和质量配置。
+
+如果采用 YAML：
+
+- 新增 `configs/workflows/product_manager.yaml`；
+- 新增 `configs/workflows/test_manager.yaml`；
+- 新增加载、schema 校验、重复键、依赖环和模板存在性测试。
+
+如果首期采用 Go 注册表，也必须实现同样抽象，避免继续让 `SupportedTasks` 承担工作流目录职责。
+
+### 6.2 ProjectWorkflowService
+
+实现：
+
+- `InitializeProjectWorkflows`；
+- `ListProjectWorkflows`；
+- `GetProjectWorkflow`；
+- `ActivateWorkflow`；
+- `GetActiveWorkflow`；
+- `ValidateRunTarget`；
+- `RecordRunStarted/Completed/Failed`。
+
+激活必须使用事务与项目行锁，并支持 `expected_version`。
+
+### 6.3 API
+
+实现：
+
+- `GET /api/v1/projects/{id}/workflows`；
+- `PUT /api/v1/projects/{id}/active-workflow`；
+- 可选 `GET /api/v1/projects/{id}/workflow-activation-audits`（创建人或管理员）。
+
+### 6.4 事件
+
+定义内部事件：
+
+- `project.workflow.activated`；
+- `project.workflow.run_started`；
+- `project.workflow.run_completed`；
+- `project.workflow.run_failed`；
+- `project.document.stale`。
+
+事件先可同步写活动流，后续再迁移到 Outbox。不得因为通知失败回滚已经成功的激活事务；审计写入必须与激活同事务。
+
+### 6.5 测试
+
+- 一个项目存在多个工作流；
+- 不同项目同名工作流隔离；
+- 创建人切换成功；
+- 非创建人切换返回 403；
+- 切换到不存在/禁用工作流失败；
+- 重复激活同一工作流幂等；
+- 两个并发切换请求最多一个基于旧版本成功；
+- 审计记录 from/to/actor/version 正确；
+- 切换不修改运行状态与文档状态；
+- 缓存失效后上下文读取到最新激活工作流。
+
+### 6.6 完成条件
+
+- 项目工作流清单和激活状态以数据库为权威；
+- 权限、并发和审计闭环；
+- 尚未接入专项执行时也可独立验收控制面。
+
+## 7. Phase 3：Coordinator、上下文与运行 API 集成
+
+### 7.1 上下文改造
+
+- `ProjectInfo` 增加创建人、激活键和选择版本；
+- `CurrentWorkflow` 兼容字段改为读取激活键，不再由最近工作区覆盖；
+- 新增 `LastRun`/`ActiveRun` 描述运行态；
+- `GetProjectContext` 联查项目工作流摘要；
+- 缓存键包含项目与工作流选择版本；
+- 工作流切换后使 C4 项目上下文与相关会话缓存失效。
+
+### 7.2 动作与路由
+
+- 重构 `ComputeAvailableActions`，组合成熟度、激活工作流和权限；
+- 新增激活工作流意图/槽位或复用现有交互卡机制；
+- 明确“当前工作流”“产品经理”“测试经理”的别名映射；
+- 非创建人请求切换时返回稳定说明；
+- 创建人跨工作流操作时先确认切换；
+- 所有写动作再次经过 `ProjectWorkflowService`，不能只依靠 L1 意图结果。
+
+### 7.3 运行 API
+
+新增项目工作流运行接口，或在现有任务接口前增加适配层：
+
+- 认证用户解析；
+- 项目可见性与运行权限；
+- 工作流归属与激活状态；
+- 输入前置条件；
+- 运行幂等；
+- `workflow_runs` 状态；
+- SSE 事件携带 `project_id/workflow_key/run_id`；
+- 完成事件包含输出文档与质量摘要。
+
+### 7.4 测试
+
+- 未激活时“当前工作流”需要用户选择；
+- 激活后省略表达路由正确；
+- 显式提及非当前工作流不会静默切换；
+- 创建人确认卡可完成切换后继续；
+- 非创建人确认卡无法绕过服务端；
+- 会话重启后仍读取项目激活状态；
+- 两个会话共享同项目时状态一致；
+- SSE 断线重连不重复创建运行。
+
+### 7.5 完成条件
+
+- 对话、REST 和 SSE 使用同一工作流控制服务；
+- `CurrentWorkflow` 不再被最近工作区错误覆盖；
+- 运行记录与项目工作流状态可观察。
+
+## 8. Phase 4：智能产品经理工作流
+
+### 8.1 模板与定义
+
+1. 将 `.refs/weichen-agent-system/templates/docs/system_reqs.md` 复制到 `templates/docs/system_reqs.md`；
+2. 核对模板变量与当前渲染器：`project_name`、`generated_at`、`snapshot_id`、`applicability`、`na_rationale`、`materials`；
+3. 统一 UR/UN 命名；
+4. 注册 `product_manager` 工作流和 `system_reqs` 任务；
+5. 为模板生成 SHA-256 并写入输入快照/manifest。
+
+### 8.2 输入装配
+
+实现 `ProductManagerInputAssembler`：
+
+- 接收显式材料引用；
+- 未提供材料时读取项目上下文；
+- 读取项目黑板、里程碑决策和基础字段；
+- 固定材料哈希与上下文版本；
+- 冲突不自动解决；
+- 生成 `MaterialItem`、`Fields` 和 `UserContext`；
+- 缺失非阻塞字段进入待确认清单。
+
+### 8.3 小队步骤
+
+新增专用基线步骤：
+
+- 整理产品介绍、需求输入和 UR 池；
+- 工程需求分解与验证方式；
+- 条件法规核查；
+- 高复杂度写作计划与计划审核；
+- 模板成文；
+- 追溯与粒度终审。
+
+尽量复用 `organizer/engineer/regulatory/writer/leader`，不需要新增角色类型。
+
+### 8.4 领域质量门禁
+
+实现结构化 Markdown 表格解析或中间 JSON 产物，检查：
+
+- 系统需求表非空；
+- ID 唯一连续；
+- 上游追溯非空；
+- 验证方式非空；
+- 原子需求规则；
+- 待确认项；
+- 模板章节；
+- 无占位符、无敷衍短语。
+
+推荐让工程步骤同时输出 `requirements.json`，writer 根据它写 Markdown，质量门禁校验 JSON 与 Markdown 一致。不要只靠正则解析复杂表格。
+
+### 8.5 DocGov 集成
+
+- 稳定文档 ID：`doc_proj{projectID}_product_manager_system_reqs`；
+- `workflow_key=product_manager`；
+- `stage_key=system_reqs`；
+- 生成完成后标记非模板；
+- 保存输入快照和血缘；
+- 继续使用作者、审核人、批准人和编辑租约；
+- 已认领文档的重生成走变更提案，不直接覆盖。
+
+### 8.6 测试
+
+单元测试：
+
+- 有需求文档的输入装配；
+- 仅项目上下文的输入装配；
+- 冲突来源保留；
+- 缺字段待确认；
+- 模板渲染；
+- UR/需求映射门禁；
+- 未渲染占位符失败。
+
+集成测试：
+
+- Stub backend 生成完整工作区；
+- 材料进入 `context/materials_text`；
+- manifest 含输入和模板哈希；
+- 文档记录进入 drafting；
+- 重复运行遵守租约与提案规则；
+- SSE 阶段事件顺序正确。
+
+端到端测试：
+
+- 创建项目→激活产品经理→上传用户需求→生成→审核→批准；
+- 创建项目→激活产品经理→无上传材料→使用项目上下文生成。
+
+### 8.7 完成条件
+
+- 两种输入路径均可完成；
+- 输出满足模板和领域门禁；
+- 文档版本和输入可追溯；
+- 产品经理输出可被下游服务稳定查询。
+
+## 9. Phase 5：智能测试经理工作流与文档血缘
+
+### 9.1 模板与定义
+
+1. 将 `.refs/weichen-agent-system/templates/docs/test_manager.md` 复制到 `templates/docs/test_manager.md`；
+2. 核对模板变量；
+3. 注册 `test_manager` 工作流和 `system_test_plan` 阶段；
+4. 配置法规库依赖和降级策略；
+5. 注册系统测试质量配置。
+
+### 9.2 前置条件解析
+
+实现 `TestManagerPrerequisiteResolver`：
+
+- 查询同项目产品经理文档；
+- 过滤空模板；
+- 正式模式只选择 `approved`；
+- 默认最新已批准版本，但允许显式固定历史版本；
+- 校验调用者可访问；
+- 读取内容和哈希；
+- 生成 `PriorDocItem` 和 `document_lineage`；
+- 找不到时返回结构化错误与下一步建议。
+
+### 9.3 输入装配与执行
+
+- 合并项目上下文与上游系统需求；
+- 法规检索扩大检索数量并保留候选判定；
+- 组织步骤输出需求清单；
+- 法规步骤输出适用性矩阵；
+- 工程步骤输出 `test_cases.json`；
+- writer 生成模板正文；
+- leader 检查覆盖与可操作性；
+- 质量门禁失败进入定向修复。
+
+### 9.4 领域质量门禁
+
+建议结构化中间产物：
+
+```json
+{
+  "upstream_requirements": ["RS-001", "RF-002"],
+  "test_cases": [
+    {
+      "requirement_id": "RS-001",
+      "test_case_id": "TSYS-0001",
+      "method": "...",
+      "acceptance": "...",
+      "disposition": "tested"
+    }
+  ],
+  "exclusions": [],
+  "regulatory_coverage": []
+}
+```
+
+校验：
+
+- 上游需求全集等于 tested + excluded + unclear 的集合；
+- 禁止静默遗漏；
+- 测试用例 ID 唯一连续；
+- 每个 tested 需求至少一个用例；
+- 方法与接受准则非空；
+- 主表行数与 4.1 的 N 一致；
+- 资源和法规附录完整；
+- JSON 与 Markdown 一致。
+
+### 9.5 stale 传播
+
+在产品经理文档新版本保存/批准后：
+
+1. 查询 `document_lineage` 中引用旧版本的下游文档；
+2. 比较新旧内容哈希；
+3. 内容变化则标记测试方案 stale；
+4. 写入 `stale_reason` 和活动审计；
+5. UI 展示影响；
+6. 不自动覆盖测试方案。
+
+项目关键事实更新也触发影响评估。首期可先对固定敏感键做规则判断，后续再增加语义差异评估。
+
+### 9.6 测试
+
+前置条件：
+
+- 无产品经理文档时正式运行失败；
+- 只有模板时失败；
+- 草稿在正式模式下失败；
+- 已批准版本成功；
+- 跨项目文档被拒绝；
+- 无权文档被拒绝；
+- 显式历史版本被正确固定。
+
+质量：
+
+- 上游需求全部覆盖；
+- 遗漏任一需求失败；
+- 方法只有标准号时失败；
+- 排除没有依据时失败；
+- 用例数与主表不一致时失败；
+- 法规库不可用时严格模式失败、降级模式受限。
+
+血缘：
+
+- 输出记录上游版本和哈希；
+- 上游无内容变化不标 stale；
+- 上游内容变化标 stale；
+- stale 不解锁或删除下游文档；
+- 重新生成新版本后血缘指向新上游版本。
+
+端到端：
+
+- 创建项目→产品经理生成并批准→切换测试经理→生成测试方案；
+- 上游需求更新→测试方案 stale→重新生成/变更提案。
+
+### 9.7 完成条件
+
+- 下游运行前置条件可靠；
+- 上游覆盖无静默遗漏；
+- 文档血缘可查询、可复现；
+- stale 传播不破坏 DocGov 状态机。
+
+## 10. Phase 6：前端项目工作流体验
+
+### 10.1 类型与 API Client
+
+新增类型：
+
+- `ProjectSummary`；
+- `ProjectWorkflowSummary`；
+- `WorkflowPrerequisiteStatus`；
+- `WorkflowSelectionState`；
+- `WorkflowRunSummary`；
+- `DocumentLineageSummary`。
+
+新增 API：
+
+- `projectApi.create/list/get`；
+- `workflowApi.list/activate/run/getRun`；
+- 激活错误码映射；
+- SSE 运行上下文增加 `workflowKey/runId`。
+
+### 10.2 状态模型
+
+- 项目实体与会话实体分离；
+- 多个会话引用同一个 `projectId`；
+- 激活工作流来自服务端，不放在单个会话中独立保存；
+- `localStorage` 只缓存项目最近访问和 UI筛选；
+- 登录用户变化时清理不再有权访问的缓存；
+- 激活成功后更新所有同项目视图。
+
+### 10.3 组件
+
+建议新增：
+
+- `ProjectWorkflowSwitcher`；
+- `WorkflowOverviewPanel`；
+- `WorkflowPrerequisiteBanner`；
+- `WorkflowRunActionBar`；
+- `UpstreamDocumentPicker`；
+- `StaleDocumentNotice`；
+- `WorkflowActivationConfirmDialog`。
+
+### 10.4 交互测试
+
+- 创建人可打开并切换；
+- 非创建人只读；
+- 切换确认文案说明不会取消任务；
+- 409 后刷新状态并提示重新选择；
+- 测试经理缺上游时显示可行动提示；
+- 可选择最新已批准或历史版本；
+- stale 提示展示原因与新旧版本；
+- 两个浏览器标签状态最终一致；
+- 键盘访问、焦点、禁用态、错误提示满足可访问性。
+
+### 10.5 完成条件
+
+- 项目级选择体验清晰，不与文档分类筛选混淆；
+- 权限反馈与服务端一致；
+- 用户能完整完成两个工作流的串联路径。
+
+## 11. Phase 7：端到端验证、迁移与上线
+
+### 11.1 自动化测试门禁
+
+后端：
+
+- `go test ./...`；
+- PostgreSQL 迁移与集成测试；
+- 并发激活 race 测试；
+- 工作流配置启动校验；
+- Stub backend 端到端；
+- 真实 backend 的受控 smoke test；
+- 鉴权和跨项目越权测试；
+- DocGov 状态与 stale 组合测试。
+
+前端：
+
+- 类型检查；
+- 单元测试；
+- 构建；
+- 关键组件交互测试；
+- 项目创建、切换、运行、断线恢复路径测试。
+
+### 11.2 数据验证
+
+- 每个项目的 `creator_user_id` 回填报告；
+- 每个项目的工作流实例数量；
+- `active_workflow_key` 必须属于 `project_workflows`；
+- 同项目工作流键唯一；
+- 运行记录项目 ID 与工作流实例项目 ID一致；
+- 文档血缘上下游同项目；
+- stale 文档具备原因和时间；
+- 无孤立审计或运行记录。
+
+### 11.3 灰度顺序
+
+建议功能开关顺序：
+
+1. 仅开启数据库双写与只读工作流清单；
+2. 对内部测试项目开启创建人切换；
+3. 开启智能产品经理；
+4. 验证产品经理文档质量和 DocGov；
+5. 开启智能测试经理草案模式；
+6. 验证法规库、覆盖门禁与血缘；
+7. 开启正式测试经理模式；
+8. 全量启用新项目；
+9. 历史项目分批迁移。
+
+### 11.4 监控与回滚阈值
+
+重点观察：
+
+- 激活 403/409 比例异常；
+- 项目创建后工作流初始化失败；
+- 工作流运行失败率或时长显著增加；
+- 产品经理质量门禁失败率；
+- 测试经理上游缺失/覆盖失败率；
+- stale 数量异常激增；
+- SSE 断线和重复运行；
+- 文档租约冲突。
+
+出现数据完整性、越权或跨项目引用问题时立即关闭写功能开关；保留新表数据，不执行破坏性回滚。
+
+## 12. 推荐代码变更清单
+
+以下为实施时的建议文件范围，最终以当前分支源码复核为准。
+
+### 12.1 新增
+
+- `internal/projectworkflow/types.go`
+- `internal/projectworkflow/catalog.go`
+- `internal/projectworkflow/store.go`
+- `internal/projectworkflow/service.go`
+- `internal/projectworkflow/policy.go`
+- `internal/projectworkflow/dependency.go`
+- `internal/projectworkflow/errors.go`
+- `internal/projectworkflow/*_test.go`
+- `configs/workflows/product_manager.yaml`（若采用 YAML）
+- `configs/workflows/test_manager.yaml`（若采用 YAML）
+- `templates/docs/system_reqs.md`
+- `templates/docs/test_manager.md`
+- 新数据库迁移文件
+- `internal/server/project_workflow_api.go`
+- `internal/server/project_workflow_api_test.go`
+- `web/src/api/projectWorkflow.ts`
+- `web/src/components/project/ProjectWorkflowSwitcher.tsx`
+- `web/src/components/project/WorkflowOverviewPanel.tsx`
+- `web/src/components/project/WorkflowPrerequisiteBanner.tsx`
+- 对应前端测试。
+
+### 12.2 修改
+
+- `internal/squad/service.go`：注册或适配两个新任务；
+- `internal/squad/workspace.go`：专项步骤与输入快照；
+- `internal/squad/quality_gate.go`：接入可插拔领域规则；
+- `internal/bizdev/service.go`：在保留执行能力的同时接受权威工作流输入；
+- `internal/coordinator/context.go`：项目工作流上下文；
+- `internal/coordinator/engine.go`：激活确认与路由；
+- `internal/ctxmgr/manager.go`：读取权威激活状态与缓存失效；
+- `internal/docgov/types.go` / `engine.go`：工作流血缘和 stale；
+- `internal/server/server.go`：路由注册；
+- `internal/server/handlers.go` / `sse.go`：认证身份和兼容层；
+- `web/src/types/workbench.ts`：项目工作流类型；
+- `web/src/App.tsx`：服务端项目与工作流状态集成；
+- 项目/数据库初始化脚本和测试夹具。
+
+### 12.3 不应修改的边界
+
+- 不以参考系统替换当前 Agent backend；
+- 不删除现有商务研发任务；
+- 不绕过 DocGov 直接覆盖受控文档；
+- 不把创建人权限写死到前端角色；
+- 不让激活切换直接操作 `workflow.json`；
+- 不把项目工作流实例存放在临时工作区文件中作为权威状态。
+
+## 13. 测试矩阵
+
+### 13.1 权限
+
+- 创建人激活：允许；
+- 项目成员激活：拒绝；
+- 非成员激活：不可见/拒绝；
+- 请求体伪造用户：拒绝；
+- 管理员普通接口代切换：拒绝；
+- 管理员专用 override：仅在明确实现且审计时允许。
+
+### 13.2 状态
+
+- ready→active focus；
+- active A→active B；
+- active B→B 幂等；
+- 切换到 disabled 拒绝；
+- 工作流 running 时切换焦点，运行继续；
+- 文档 reviewing/approved 时切换，不改变文档状态；
+- 运行失败，激活状态保持。
+
+### 13.3 输入
+
+- 产品经理：需求文档；
+- 产品经理：项目上下文；
+- 产品经理：两者都有且冲突；
+- 测试经理：项目上下文 + approved 上游；
+- 测试经理：无上游；
+- 测试经理：跨项目上游；
+- 测试经理：草稿上游；
+- 测试经理：历史批准版本；
+- KB 正常、不可用、部分命中。
+
+### 13.4 并发与恢复
+
+- 同项目并发激活；
+- 不同项目并发激活；
+- 同工作流重复启动；
+- SSE 中断后续跑；
+- 同文档人工编辑与 Squad 竞争租约；
+- 上游在下游运行期间更新；
+- 服务重启后恢复项目激活和运行状态。
+
+### 13.5 质量与追溯
+
+- 产品经理缺章节、重复 ID、空追溯、空验证方式；
+- 测试经理遗漏需求、重复用例、无接受判据、排除无依据；
+- 模板变量泄漏；
+- manifest 哈希；
+- 血缘版本；
+- stale 传播与影响确认。
+
+## 14. 建议提交/PR 拆分
+
+为便于审查与回滚，建议拆分：
+
+1. PR-1：项目创建人、项目 API、数据库迁移；
+2. PR-2：项目工作流目录、实例、激活、审计与并发测试；
+3. PR-3：Coordinator/Context/运行接口适配；
+4. PR-4：智能产品经理模板、步骤、输入与质量门禁；
+5. PR-5：智能测试经理、法规模式、血缘与 stale；
+6. PR-6：前端项目工作流选择器和专项页面；
+7. PR-7：历史迁移、E2E、监控与运维文档。
+
+每个 PR 都应包含测试和迁移/回滚说明，不要先合入无校验的模板或无权限的切换接口。
+
+## 15. 工作量与优先级建议
+
+### P0：必须完成
+
+- 项目创建人服务端权威化；
+- 项目工作流实例与唯一激活状态；
+- 创建人权限与原子切换；
+- 产品经理两种输入路径；
+- 测试经理同项目上游版本依赖；
+- 两个模板与专用质量门禁；
+- 文档血缘和上游更新 stale；
+- 关键 API、数据库和 E2E 测试。
+
+### P1：上线质量
+
+- 高复杂度 plan/review_plan；
+- 多标签实时状态同步；
+- 法规库严格/降级模式 UI；
+- 领域指标与告警；
+- 历史项目迁移工具；
+- 上游差异影响摘要。
+
+### P2：后续增强
+
+- 创建人转让流程；
+- 非创建人申请切换；
+- 工作流自定义启用/禁用；
+- 可视化工作流图；
+- 多版本工作流定义迁移；
+- 需求与测试用例的结构化编辑器；
+- 基于差异的增量测试方案更新。
+
+## 16. Definition of Done
+
+只有同时满足以下条件，功能才算完成：
+
+1. 数据库迁移在空库和历史库均验证成功；
+2. 项目创建人来自认证会话且不可伪造；
+3. 同项目多个工作流可查询、状态隔离；
+4. 单一激活约束在并发测试中成立；
+5. 非创建人无法通过 UI、REST、SSE 或对话绕过切换权限；
+6. 产品经理能从两类输入生成符合模板和门禁的文档；
+7. 测试经理只能使用同项目合格的产品经理输出版本；
+8. 上游需求覆盖完整，测试方法可执行；
+9. 文档血缘、输入快照、模板哈希和 manifest 可复现；
+10. 上游更新正确标记下游 stale；
+11. 激活、运行和文档生命周期互不混淆；
+12. `go test ./...`、前端测试、类型检查和构建通过；
+13. 关键真实 backend smoke test 通过；
+14. 监控、审计、功能开关和回滚说明齐全；
+15. 代码变更未混入无关用户改动。
+
+## 17. 首个可交付里程碑
+
+建议第一个可演示里程碑只包含完整但较窄的闭环：
+
+1. 登录用户创建项目；
+2. 项目自动拥有智能产品经理和智能测试经理；
+3. 创建人激活智能产品经理；
+4. 上传用户需求文档或使用项目上下文；
+5. 生成并批准系统需求规格书；
+6. 创建人切换到智能测试经理；
+7. 选择已批准的系统需求规格书版本；
+8. 生成系统验证方案及计划；
+9. 修改上游需求并形成新版本；
+10. 系统将测试方案标记为 stale，并提供重新生成入口。
+
+这个里程碑同时证明：多工作流、创建人权限、激活路由、两个专项工作流、DocGov、输入快照、文档血缘和 stale 传播已经形成真正闭环。

.doc/system-design/project-workflow/05-Phase0-基线确认与契约冻结.md

@@ -0,0 +1,51 @@
+# Phase 0 基线确认与契约冻结
+
+> 编制日期：2026-09-10  
+> 归属项目：Chat-Agent-System 项目多工作流与专项工作流体系
+
+---
+
+## 1. 架构决策记录 (ADR)
+
+### ADR-001：三层模型与服务端项目身份权威化
+- **决策**：废除将 Squad 底层任务标识当作项目工作流的做法，确立“工作流定义（Workflow Definition）→ 项目工作流实例（Project Workflow Instance）→ 运行实例（Workflow Run）”三层领域模型。
+- **创建人权威**：项目创建人必须从认证 Token (`auth.UserAccount.ID`) 提取并写入 `projects.creator_user_id`，禁止客户端在 Request Body 中传入或伪造；普通项目更新接口不可修改 `creator_user_id`。
+
+### ADR-002：单一激活焦点与并发版本控制
+- **决策**：每个项目可挂载多个工作流实例，但全局有且仅有一个当前激活焦点 `projects.active_workflow_key`。
+- **并发与审计**：激活切换仅限项目创建人执行，采用数据库行级锁 (`FOR UPDATE`) 与 `workflow_selection_version` 乐观锁防重放/冲突；每次切换均生成只追加记录到 `workflow_activation_audits`。
+- **运行时无损**：激活切换仅更改对话/前端的路由焦点，绝不取消后台进行中的任务运行，也不更改受控文档生命周期状态。
+
+### ADR-003：上下游依赖契约与 Stale 传播
+- **决策**：智能测试经理工作流强依赖同项目下智能产品经理的输出成果，正式模式必须要求产品经理文档处于 `approved` 状态；支持显式锚定历史已批准版本。
+- **血缘与 Stale**：执行时在 `document_lineage` 中记录上游文档 ID、版本与 SHA256；上游产生新版本时，下游自动打上 `stale` 标记并记录原因，绝不盲目覆写已有下游受控文档。
+
+---
+
+## 2. 标识与命名冻结表
+
+| 领域对象 | 标准标识 / Key | 阶段 / 任务 Key | 产出受控文档正式名称 | UI 显示别名 |
+| :--- | :--- | :--- | :--- | :--- |
+| **智能产品经理** | `product_manager` | `stage_key=system_reqs`<br>`task_key=system_reqs` | 《系统需求规格书》 | 系统需求规格书 / 产品需求 |
+| **智能测试经理** | `test_manager` | `stage_key=system_test_plan`<br>`task_key=test_manager` | 《系统验证方案及计划》 | 系统测试方案 / 测试验证方案 |
+
+---
+
+## 3. 标准 API 错误码清单
+
+| HTTP 状态码 | 错误码 (Code) | 说明 | 处理指引 |
+| :--- | :--- | :--- | :--- |
+| `401 Unauthorized` | `ERR_UNAUTHENTICATED` | 会话已过期或未提供 Token | 重新登录并刷新 Token |
+| `403 Forbidden` | `ERR_NOT_PROJECT_CREATOR` | 非项目创建人无权切换工作流 | 提示联系项目创建人进行配置 |
+| `404 Not Found` | `ERR_PROJECT_NOT_FOUND` | 指定项目不存在或无权限查看 | 检查项目 ID 或核查数据权限 |
+| `404 Not Found` | `ERR_WORKFLOW_NOT_FOUND` | 工作流定义不存在或项目未开通 | 校验工作流 Key 是否有效 |
+| `409 Conflict` | `ERR_CONCURRENT_SWITCH` | 乐观版本冲突 (selection_version mismatch) | 前端刷新当前工作流状态后重试 |
+| `412 Precondition Failed`| `ERR_PREREQUISITE_NOT_MET` | 测试经理缺少已批准的产品需求文档 | 引导前往产品经理工作流完成编制与审批 |
+
+---
+
+## 4. 数据库演进与迁移策略
+
+- **权威主库**：以 `context_init.sql` 体系中的 `projects` 为基础基线。
+- **迁移脚本**：在 `deploy/postgres/migrations/2026-09-11-project-workflows-and-lineage.sql` 中统一执行 ALTER 与 CREATE。
+- **历史兼容**：`creator_user_id` 初始设置为允许 NULL，回填脚本优先以项目首个会话创建者或默认管理员 (ID: 1) 回填，确保零破坏。