Files

T

weichenandCursor 511864bad0 docs(ops): scaffold doc taxonomy and relocate audit/remediation

Establish .doc/{status,audit,remediation,archive} structure with README
maps, migrate 15 root audit/remediation docs, and add redirect stubs.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-13 02:50:23 +00:00

41 KiB

Raw Permalink Blame History

三工作流严格治理与现有系统融合整改方案

日期：2026-09-12
状态：核心业务决策已确认 / 可进入实施拆分
范围：工作流定义、项目实例、阶段门禁、文档三权、通知与对话推进、运行时授权、数据迁移和验收
本文性质：当前代码与开发数据库的只读核验结论及整改设计；本轮未修改业务代码

1. 结论先行

系统面向项目创建者和项目成员时，只应存在以下 3 个可选择工作流：

商务对接流程：7 个文档，3 个阶段；
智能产品经理流程：1 个输出文档，1 个阶段；
智能测试工程师流程：1 个输出文档，1 个阶段。

商务对接流程的文档数量可以定案为 7 个，不是 6 个。前端模板工厂和测试固定断言了 7 个任务键，后端标准任务目录也包含同一组 7 个商务文档，历史专项测试报告同样把它们定义为标准全生命周期交付物。¹²³

当前系统尚未满足这一目标，且不是简单改几个显示名称即可解决：

启动代码实际发布 5 个默认工作流，除目标三项外还包含“医疗器械研发”和“非医疗纯软件”；⁴
当前开发库已有 92 个工作流定义，其中大量为测试定义；三个目标工作流仍都是单阶段的 schema v1；
仓库虽然有三个 schema v2 清单，但商务清单只有 5 个文档，漏了 feasibility_dev 和 user_requirements；⁵
三个 v2 清单仅被嵌入和登记，没有进入启动发布链；已有发布版又会让 seed 逻辑直接退出，因此现有库不会自动升级；⁶⁷
旧运行入口会把多阶段版本压成“第一个阶段的第一个任务”，与项目实例运行时并存，形成双轨权威；⁸
配置页面允许勾选关闭文档，但后端校验禁止关闭所有 required/blocking 文档；当前清单又把所有文档都标成这两类，因此界面能力实际上不可用；⁹
智能测试工程师当前被 manifest、执行服务和前端提示硬绑定到产品经理/SRS，与已确认的两个智能工作流独立运行原则冲突；¹⁰¹¹
阶段推进虽然先检查批准状态，但事务内会把所有启用任务强制写成 approved，并且最后阶段完成后没有把项目恢复到可选择下一工作流的状态；¹²¹³
对话中的“推进阶段”仍调用旧商务成熟度执行器，并没有调用项目工作流实例的阶段推进服务；¹⁴

因此本次整改的核心是：以已激活项目工作流实例的冻结快照作为唯一运行时权威。工作流目录、项目配置、文档三权、任务启动、审批、阶段门禁、通知和对话都必须围绕同一个实例标识运行，旧的直接切换和扁平执行入口退出生产路径。

2. 已确认的业务基线

2.1 唯一允许对项目展示和选择的工作流

稳定内部 key	对外名称	阶段数	输出文档数	说明
`main`	商务对接流程	3	7	保留现有 key 以避免破坏历史数据，只改正式名称
`product_manager`	智能产品经理流程	1	1	输出《系统需求规格书》
`test_manager`	智能测试工程师流程	1	1	保留现有 key，只把“测试经理”统一更名为“测试工程师”

“系统只需要三个流程”的含义应同时落实到三个层面：

项目设置 API 只返回这 3 个可选项；
前端任何入口只展示这 3 个可选项；
服务端只允许为这 3 个正式、已发布版本创建项目工作流实例。

后台可以保留历史定义和草稿以满足审计，但必须标记为 retired 或 project_selectable=false，不能继续出现在项目目录中。不能仅靠前端白名单隐藏，因为当前设置服务会枚举数据库里全部有发布版本的定义。¹⁵

2.2 商务对接流程：7 个文档，3 个阶段

沿用系统已经形成的 V0.1 / V0.5 / V1.0 业务阶段和模板归属，目标定义如下。当前模板工厂已按 1 + 5 + 1 归档这 7 个文档。¹⁶

阶段	顺序	task key	正式文档名	默认状态	阶段门禁
V0.1 需求摸底	10	`intake`	用户初始需求收集表	启用	启用时必须批准
V0.5 方案与可行性	20	`research`	调研报告	启用	启用时必须批准
V0.5 方案与可行性	21	`feasibility_dev`	设计开发可行性评估报告	启用	启用时必须批准
V0.5 方案与可行性	22	`feasibility_reg`	注册路径可行性评估报告	启用	启用时必须批准
V0.5 方案与可行性	23	`user_requirements`	用户需求表	启用	启用时必须批准
V0.5 方案与可行性	24	`prelim_design`	系统初步设计方案	启用	启用时必须批准
V1.0 商务报价	30	`cdo_quote`	CDO 报价单	启用	启用时必须批准

当前后端商务阶段只执行 intake、research、feasibility_reg、prelim_design、cdo_quote 五项，正好缺少另外两项，必须同步补齐阶段执行映射和 executor 注册。¹⁷¹⁸

2.3 智能产品经理流程

阶段	task key	唯一输出文档	默认状态	门禁
系统需求基线	`system_reqs`	系统需求规格书	启用	文档批准后，创建者确认完成工作流

2.4 智能测试工程师流程

阶段	task key	唯一输出文档	默认状态	门禁
系统验证策划	`test_manager`	系统验证方案及计划	启用	文档批准后，创建者确认完成工作流

智能产品经理流程和智能测试工程师流程相互解耦。 智能测试工程师流程不再要求项目曾运行智能产品经理流程，也不再要求必须存在该流程输出的《系统需求规格书》。它直接从当前项目可用于工作流的对话、文档、上传材料、项目事实和决策记录中提取需求及验证依据，独立生成《系统验证方案及计划》。

如果项目中恰好存在已批准的《系统需求规格书》，它只是项目输入集合中的一项高权威来源，不是启动前置条件，也不产生流程级耦合。当前 manifest、执行服务、血缘逻辑和前端提示仍硬编码了这一依赖，整改时必须一起删除。¹⁰¹¹

2.5 两个智能工作流的统一项目上下文输入

智能产品经理和智能测试工程师使用同一个“项目上下文快照服务”，但采用不同的分析目标和输出模板：

输入类别	纳入内容	建议权威等级
项目事实	项目名称、客户、产品类型、预期用途、目标市场、结构化事实黑板	已确认事实
项目决策	创建者确认事项、里程碑决策、已关闭的待确认项	已确认决策
项目文档	当前有效版本的受控文档、项目共享文档、上传材料	按批准状态和来源分级
项目对话	所有已进入项目共享知识边界的成员对话及其附件	原始沟通证据
历史输出	商务、产品、测试或自由任务形成的项目交付物	按状态和版本分级
知识依据	系统检索到的法规、标准和内部知识库命中	外部参考依据

这里的“所有”是指 当前项目知识边界内全部有资格被工作流使用的内容，不是把数据库中所有原文无差别拼接到一次模型调用中。建议遵循以下规则：

只纳入当前项目，绝不跨项目召回；
私人草稿、个人私聊只有在明确“共享到项目”后才进入项目级工作流输入，避免流程执行扩大原有可见范围；
任务启动时生成不可变 project_context_snapshot，记录截止时间、来源 ID、版本、内容 hash、权限判定和引用位置；
全量来源先建立清单，再按任务目标检索相关片段；已确认事实和已批准文档必须进入固定核心上下文，普通对话按相关性分批读取；
冲突时不静默覆盖，优先级建议为：创建者确认事实/决策 > 当前已批准文档 > 用户上传原始材料 > 里程碑记录 > 普通项目对话 > 智能体历史总结；
输出必须带 source manifest。智能测试工程师需在唯一输出文档内部生成“需求/风险—测试项—来源”追溯表，不额外创建第二个受控输出文档；
任务运行后项目来源发生变化时，依据被引用来源的 hash 判断 input_changed/stale，而不是只监听《系统需求规格书》。未被本次输出引用的无关对话变化不应把文档误标为 stale。

现有 Squad 工作区已经支持 project context、materials、prior docs、knowledge hits 等输入槽位，也会建立带权威等级的 context 索引；产品经理还已有从项目事实和里程碑生成输入材料的局部实现。因此应把这些能力上移为通用项目上下文快照服务，而不是为测试流程继续维护单一 SRS 特例。¹⁹

3. 不可违反的业务规则

3.1 选择、启动和切换

只有项目创建者可以选择、配置、激活、推进或受控终止项目工作流。
一个项目同一时刻最多只能有一个 live 实例。
在 active、awaiting_stage_confirmation 或 termination_requested 状态下，不允许选择或切换工作流。
“切换工作流”不是修改当前实例的 workflow_key，而是当前实例 completed 或 terminated 后创建一个新的 planning 实例。
激活时冻结工作流版本、阶段、文档开关、模板版本、执行器、质量门禁和三权责任人。运行中不可静默修改。
管理员不因系统身份自动替代项目创建者执行推进；如以后引入 break-glass，必须单独设计理由、再认证和审计，且不能代替文档签署人。

目标状态机：

stateDiagram-v2
    [*] --> planning: 创建者选择并配置
    planning --> active: 预览后确认激活
    active --> awaiting_stage_confirmation: 当前阶段所有启用文档已批准
    awaiting_stage_confirmation --> active: 创建者确认进入下一阶段
    awaiting_stage_confirmation --> completed: 创建者确认完成最后阶段
    active --> termination_requested: 创建者申请终止
    termination_requested --> terminated: 二次确认并记录原因
    completed --> planning: 创建下一工作流实例
    terminated --> planning: 创建下一工作流实例

数据库已经为一个 planning 实例和一个 live 实例设置了部分唯一索引，也预留了 awaiting_stage_confirmation、terminated 等状态，适合沿此模型完善，不必另造一套表。²⁰

3.2 文档启用与禁用

项目创建者可以在 planning 状态逐文档启用或禁用。严格语义如下：

文档状态	三权配置	可创建/启动编制	可提交审核	可审核	可批准	是否计入阶段门禁
enabled	作者、审核人、批准人均必填且互斥	是，仅作者或明确执行人	是，仅作者	是，仅审核人	是，仅批准人	是
disabled	必须为空	否	否	否	否	否

关键约束：

default_enabled 只表示默认值，不表示不可关闭；
blocking_when_enabled=true 表示文档一旦启用，未批准就阻断阶段；
新增明确字段 creator_configurable=true/false，不要继续混用现有 required、blocking、default_enabled 三个布尔值表达四种含义；
禁用后实例状态写为 skipped_disabled，不创建 DocGov 文档、不生成三权行，也不允许通过 task key、对话、SSE、Agent tool 或旧 API 旁路启动；
对禁用文档发起动作时统一返回 409 DOC_TASK_DISABLED；对启用文档但责任人不匹配返回 403 DOC_DUTY_FORBIDDEN；
激活计划必须至少包含一个启用文档。这样一文档流程仍可在配置时关闭唯一文档，但关闭后不能激活一个没有产出的空工作流。

现有数据结构已经能表达 enabled 和三权，且持久化时会跳过禁用文档的职责写入；可复用这部分。问题在于定义校验把 required/blocking 文档一律视为不可关闭，需要先修正语义。²¹²²

3.3 阶段完成和推进

阶段就绪的唯一业务判定应为：

stage_ready = 当前阶段处于 active
           AND 当前阶段至少有一个 enabled 文档
           AND 每个 enabled 文档的当前受控版本都为 approved
           AND 没有正在执行、待审核、待批准或 stale 的同任务实例

推进动作必须满足：

服务端在同一数据库事务中锁定 workflow instance 和 stage instance；
重新计算门禁，不能只信几秒前的 readiness 响应；
校验操作者仍是项目创建者；
校验 expected_config_revision 和幂等键；
只改变阶段和实例状态，绝不把文档“补写”为 approved；
进入下一启用阶段；若没有下一阶段，则把实例标为 completed，并把项目切回“可配置下一个工作流”的状态；
同事务关闭对应 stage_advance_request，写审计和 outbox 事件。

当前 readiness 已经忽略禁用任务、检查启用必需文档是否批准，并限制创建者推进，这一骨架可以保留；但它按 project_id + task_key 汇总文档状态，仍需升级到 doc_task_instance_id + document_version_id，避免跨阶段或重复实例串线。²³²⁴

3.4 主动提醒和对话推进

系统在 readiness 从 false 变为 true 时生成一次 stage.ready_to_advance 事件，并只通知项目创建者。已有 outbox、站内通知、去重键以及 24 小时再次提醒机制可以复用。²⁵²⁶

建议闭环：

最后一份启用文档批准；
事务后事件处理器重新计算 readiness；
实例进入 awaiting_stage_confirmation；
创建者收到站内消息和可操作确认卡：阶段名、启用/已批准文档清单、下一阶段或“完成工作流”；
创建者点击按钮，或在项目对话中说“推进到下一阶段 / 确认推进”；
两种入口都调用同一个 AdvanceStage 应用服务；
成功后通知状态改为 acted，推进请求改为 confirmed；若条件在确认前失效，则返回最新阻断项并把旧请求标为 superseded。

当前前端已经每 15 秒拉取通知并显示“确认推进”按钮，但对话入口仍走旧的 bizdev.ExecuteStage，所以需要把自然语言意图解析与执行彻底分开：识别器只产生命令，实例服务才拥有推进权。²⁷¹⁴

4. 当前系统与目标的差距

4.1 定义和目录

编号	当前事实	风险	整改
WF-CAT-01	Bootstrap 发布 5 个工作流	项目会看到目标外流程	只发布三项；其余退役且不可选
WF-CAT-02	设置服务返回所有有发布版的定义	测试/历史流程进入项目	增加 `project_selectable`，查询端白名单 + 状态双重校验
WF-CAT-03	开发库有 92 个定义，88 个 key 为 `pg_` 或 `test_`	测试污染业务目录	测试强制独立数据库/schema，fixture 必须清理
WF-DEF-01	三个正式 key 当前均为 schema v1 单阶段	实际运行不是目标结构	以新版本发布 schema v2/v3，禁止覆盖旧版本
WF-DEF-02	`main.v2.json` 只有 5 个文档	商务流程缺 2 个输出	补齐 7 个并增加 executor、模板和质量门禁校验
WF-DEF-03	v2 manifest 未进入 bootstrap	仓库文件与运行数据库不一致	建立 manifest 迁移器，按 hash 创建并发布新版本
WF-DEF-04	seed 发现任何 published 就跳过	永远停留旧版本	按内容 hash 和目标版本升级，写版本迁移审计
WF-DEF-05	DBCatalog 压扁完整定义	多阶段配置不能驱动运行	删除生产 flatten 路径，运行只读取冻结实例
WF-DEF-06	测试流程声明 product_manager 上游，执行服务又硬查 approved SRS	两个智能工作流不能独立运行	删除流程级依赖；改用统一项目上下文快照和多来源血缘

4.2 项目实例和生命周期

编号	当前事实	风险	整改
WF-INS-01	planning / active 和唯一 live 骨架已存在	可复用但未闭环	扩展 awaiting/completed/terminated 完整转换
WF-INS-02	完成最后阶段只更新实例	项目仍为 active，无法配置下一流程	同事务更新项目可选择状态并清空 current live 指针
WF-INS-03	无受控终止 API	异常流程永久锁死或只能改库	增加申请、影响预览、创建者二次确认和终止原因
WF-INS-04	激活 token 明文保存，消费与激活分事务	失败后 token 已失效或可泄露	只存 hash，并在激活事务内锁定、消费
WF-INS-05	冻结子任务只写 key/enabled/status	executor、模板、质量门禁仍依赖可变定义	激活时把完整运行元数据写入实例表并以实例表为权威

数据库已添加 executor/template/quality gate 列，但当前实例写入 SQL 仍只插入 task key、enabled 和 status，证明冻结快照尚未真正成为执行权威。²⁸

4.3 文档、三权和运行时授权

编号	当前事实	风险	整改
WF-DOC-01	启用文档要求三权且互斥	基础规则正确	再校验三人均为 active 项目成员且账户有效
WF-DOC-02	禁用文档不会写三权	基础持久化正确	增加 `skipped_disabled` 和全入口拒绝
WF-DOC-03	访问过滤按 task key 判断	同 key 重复实例可能串权	所有动作使用 `doc_task_instance_id`
WF-DOC-04	无 live 实例时访问过滤默认不限制	完成后旧任务入口可能恢复可用	正式项目按治理模式 fail closed；legacy 仅限显式迁移标记
WF-DOC-05	运行入口仍接受 task key 并查扁平目录	可能绕过阶段和冻结绑定	请求只传 doc task instance id，服务端解析 executor/template/duty
WF-DOC-06	DocGov 状态机可验证具体审核/批准人	可复用	文档必须外键绑定 doc task instance 和版本

现有阶段访问代码确实会从 live 快照中排除禁用任务，这是可保留的基础；但当没有 live 实例或实例 completed 时会返回 unrestricted，因此不能把它视为禁用文档全生命周期的完整保障。²⁹

4.4 前端、通知和对话

编号	当前事实	风险	整改
WF-UI-01	旧切换器硬编码三项，但名称不一致	用户认知混乱	统一为三个正式名称，数据来自服务端目录
WF-UI-02	新治理 API 失败时回退旧直接切换 UI	可重新打开不合规路径	删除回退；治理不可用时只读并明确报错
WF-UI-03	旧切换在版本冲突后自动重试	可能覆盖用户最新选择	展示冲突并要求重新确认，不自动提交高风险操作
WF-UI-04	项目设置只显示 stage/task key	不利于业务确认	显示正式阶段名、文档名、启用状态、三权和影响摘要
WF-UI-05	live 配置缺少完整只读审计视图	创建者不清楚冻结内容	展示版本、hash、激活人/时间、所有 enabled/disabled 和职责
WF-NOTIFY-01	readiness 通知和 24h 提醒已存在	基础可复用	增加状态转换、已读/已处理、失效和重算
WF-DLG-01	对话推进旧商务阶段	可越过新实例门禁	对话调用同一实例 AdvanceStage command
WF-CTX-01	产品经理仅在无材料时拼装部分项目事实；测试工程师只注入 SRS	“全部项目内容”没有统一、可复现的输入语义	建立项目上下文快照、来源清单、权限过滤、冲突优先级和 hash 血缘

旧前端切换器在治理不可用时仍调用 /active-workflow，并在冲突后自动取新版本再次切换；这两个行为都应删除。³⁰ 旧服务端路由在迁移完成后应返回 410 WORKFLOW_SWITCH_API_RETIRED，而不是继续作为备用入口。³¹

4.5 开发数据库现场快照

2026-09-12 对当前 shuimu-context-pg-dev / agent_system_dev 做只读查询得到：

workflow_definitions = 92
published workflow versions = 92
main            = version 1, schema 1, 1 stage
product_manager = version 1, schema 1, 1 stage
test_manager    = version 1, schema 1, 1 stage
project_workflow_instances: active 32, completed 47
projects.lifecycle_status: active 97, planning 51
completed 实例已存在、无 live 实例但项目仍为 active：47 个
测试命名定义（pg_* / test_*）：88 个

这些数字主要反映当前开发环境和集成测试污染，不能直接当成生产数据；但它们证明目录查询没有隔离正式定义与测试定义，也直接复现了“实例已完成而项目仍 active”的生命周期断点。PG 测试在未设置 TEST_DATABASE_URL 时默认连接开发库，部分定义发布测试又没有清理工作流定义，因此必须纳入整改。³²³³

5. 目标技术模型

5.1 单一运行权威

Published Workflow Version
        │  创建 planning plan
        ▼
Project Workflow Instance + immutable config snapshot
        │  激活时物化
        ├── Stage Instances
        │      └── Doc Task Instances
        │              ├── frozen executor/template/quality gate
        │              ├── duty assignments
        │              ├── controlled document versions
        │              └── task runs
        ├── Stage Advance Requests / Notifications
        └── Audit / Outbox Events

激活后，任何运行请求不得再从“最新发布定义”、前端 task key 或 legacy catalog 推导行为。最新定义只用于创建未来实例；已运行实例永远引用自己的冻结数据。

5.2 定义 schema 建议

文档任务应至少明确以下字段：

{
  "key": "research",
  "title": "调研报告",
  "default_enabled": true,
  "creator_configurable": true,
  "blocking_when_enabled": true,
  "executor_key": "bizdev.research.v1",
  "quality_gate_key": "quality.generic.v1",
  "template": {"asset_key": "research", "version": 1},
  "output_doc_type": "research",
  "output_doc_title": "调研报告"
}

发布校验必须增加：

workflow key 属于三个正式 key 之一，且对外名称准确；
阶段 key、position、任务 key 均唯一且非空；
每个阶段至少一个文档任务；
executor、quality gate 和 ready 模板版本全部存在；
三个正式流程精确满足 7 / 1 / 1 文档清单；
三个正式工作流均不声明流程级 required_upstream_workflow；
项目上下文输入策略、来源权限和冲突优先级完整；
禁用策略、完成策略和参与策略完整；
发布后版本不可原地修改。

当前 v2 校验只检查 schema 版本、阶段位置、executor/quality gate 注册和输出类型，尚不足以守住上述业务契约。³⁴

5.3 数据结构增量

优先扩展现有表，不重复建模：

workflow_definitions：增加 project_selectable、catalog_order、official_code；
workflow_versions.definition_json：采用新禁用语义并保留版本 hash；
project_workflow_instances：增加 completed_at/by、terminated_at/by/reason、previous_instance_id；
project_stage_instances：增加 ready_at、completed_at/by；
project_doc_task_instances：持久化 executor_key、quality_gate_key、模板 asset/version、output type/title；禁用任务状态为 skipped_disabled；
documents：增加 doc_task_instance_id，受控文档版本唯一绑定；
project_context_snapshots：记录项目、任务、截止时间、汇总 hash、创建人和冻结状态；
project_context_snapshot_sources：逐项记录 source type/id/version/hash、权限范围、权威等级、是否实际引用；
task_runs：增加 workflow_instance_id、stage_instance_id、doc_task_instance_id、context_snapshot_id；
document_lineages：从单一“上游 SRS”扩展为多来源 lineage，允许对话、材料、事实、决策和文档版本作为来源；
stage_advance_requests：保留 readiness revision，补 idempotency_key、superseded_at；
审计事件：至少记录 plan saved、activated、document disabled/enabled、duty assigned、stage ready、stage advanced、workflow completed/terminated。

5.4 API 收敛

建议正式接口：

方法与路径	用途	关键约束
`GET /api/v1/workflows/catalog`	返回严格三项正式目录	只含 project_selectable + published
`GET /api/v1/projects/{id}/settings`	规划或冻结配置视图	项目访问控制
`PUT /api/v1/projects/{id}/workflow-plan`	选择流程、开关文档、设置三权	仅创建者、仅 planning、乐观锁
`POST /api/v1/projects/{id}/activation-preview`	完整影响与校验	无空流程、三权和上下文策略通过
`POST /api/v1/projects/{id}/workflow-instances/activate`	冻结并激活	创建者二次确认、原子 token
`GET /api/v1/workflow-instances/{id}`	运行和历史详情	项目 + 阶段可见性
`GET /api/v1/workflow-instances/{id}/stages/{key}/readiness`	门禁详情	返回所有启用文档状态
`POST /api/v1/workflow-instances/{id}/stages/{key}/advance`	创建者推进或完成	事务内重算、幂等
`POST /api/v1/workflow-instances/{id}/termination-preview`	终止影响	未决任务、文档和通知清单
`POST /api/v1/workflow-instances/{id}/terminate`	受控终止	创建者、原因、二次确认
`POST /api/v1/doc-task-instances/{id}/runs`	启动编制	enabled + active stage + duty

旧 /projects/{id}/active-workflow 和依赖扁平 workflow key 的 run 接口先记录迁移告警，完成客户端切换后返回 410。

6. 实施顺序

Phase 0：冻结错误扩散和数据盘点

给项目目录增加服务端正式白名单，立即只暴露三个目标 key。
禁止测试默认连接开发库；CI 必须显式提供隔离的 TEST_DATABASE_URL。
备份并分类 92 个定义及其引用：正式、历史、测试、被实例引用。
未被任何实例引用的测试定义在开发环境清理；被引用定义只退役，不物理删除。
修复开发环境中 completed instance 与 project lifecycle 不一致的数据，但先输出 dry-run 清单。

Phase 1：发布三个唯一正式定义

修订三个 manifest 的正式名称与 schema；商务流程补齐 7 个文档。
为 feasibility_dev 和 user_requirements 注册专用 executor，或明确映射到通用任务 executor；禁止使用含混的法规 executor 代替。
从 test_manager manifest、默认目录和校验模型中删除 required_upstream_workflow=product_manager，使三个流程在流程级完全独立。
增加严格发布校验和 7 / 1 / 1 契约测试。
实现 hash 驱动的版本升级：已有 v1 时创建 v2/v3，而不是退出或覆盖。
medical_device_development、non_medical_software 及其他定义全部 project_selectable=false 并退役。

Phase 2：补齐实例状态机和禁用语义

重构 plan validator：creator-configurable 文档可关闭；启用文档三权必填；空工作流不可激活。
校验三权人员为有效项目成员、账户有效且三权互斥。
激活时完整物化运行元数据，以实例为唯一权威。
阶段推进事务内重算门禁，删除“推进时强制批准文档”的 SQL。
完成最后阶段时同步更新项目状态，使其可创建下一 planning 实例。
实现受控终止，保证 live 实例不会永久锁住项目。

Phase 3：运行、文档治理和权限合流

建立通用项目上下文快照服务，覆盖项目事实、项目级对话、文档、材料、决策、历史输出和知识命中。
产品经理和测试工程师分别从同一快照服务取数；删除测试任务中“查找已批准 system_reqs，否则拒绝”的特例。
所有任务启动改用 doc_task_instance_id；服务端解析 task/executor/template/stage/duty/context snapshot。
文档创建、查看、编辑、提交、审核、批准均校验同一 doc task instance。
disabled、非当前阶段、非责任人、实例非 live 均 fail closed。
SSE、异步 task run、恢复/取消、RAG 检索、Agent tools 使用同一策略决策。
审批回调按具体文档版本更新具体 doc task instance，不再按项目 + task key 批量更新。
把 SRS 单来源 lineage 改成 source manifest 多来源血缘；只在实际引用来源变化时标记输出待复核。

Phase 4：通知、对话和前端闭环

readiness 边沿触发状态和通知，补 read/acted/dismissed API。
把对话“推进/完成工作流”绑定到项目实例 command；保留明确确认卡。
项目设置只显示三项，按正式名称显示阶段和文档。
active/awaiting 时显示冻结只读视图，隐藏所有切换动作。
completed/terminated 后显示“配置下一个工作流”，而不是修改旧实例。
删除旧切换回退、冲突自动重试和 WorkflowPrerequisiteBanner 的产品经理前置提示。
在运行预览中展示项目上下文截止时间、来源数量、被排除的私有/无权内容和冲突项。

Phase 5：迁移和发布

新项目只允许使用新的三个正式版本。
尚未激活的 planning v1 计划自动重建为新版本草稿，并要求创建者重新确认三权。
已激活 v1 实例不静默改写：真实业务实例由创建者选择继续兼容完成或受控终止后重建；开发/测试垃圾实例按确认后的清理脚本处理。
先 shadow 计算新旧 readiness 差异，再开启新推进服务。
通过全套验收后关闭 legacy route 和 flatten catalog。

7. 验收标准

7.1 目录和定义

任意项目、任意普通用户或管理员在项目选择页都只能看到 3 个工作流。
正式名称精确为“商务对接流程 / 智能产品经理流程 / 智能测试工程师流程”。
定义快照精确为 7 / 1 / 1；缺一、多一、重复 key、模板未 ready 或 executor 未注册均无法发布。
三个正式定义均没有流程级上游依赖；产品经理和测试工程师可被分别独立选择和运行。
服务重启、数据库迁移和旧数据存在时，目录结果仍稳定为三项。

7.2 选择和冻结

只有项目创建者可保存、激活和推进；普通成员、系统管理员默认均被拒绝。
live 实例存在时，UI、API 和对话三个入口均不能切换。
工作流完成或受控终止后，创建者可以配置下一实例；旧实例保持只读可追溯。
两个浏览器同时配置或推进时只有一个成功，另一个收到版本冲突并重新确认。

7.3 文档开关和三权

启用文档缺任一职责、职责重复、责任人非 active 项目成员时不能激活。
禁用文档没有职责行、没有受控文档、没有运行按钮，也不能通过手工 API、SSE 或对话启动。
对禁用文档的编制、提交、审核、批准请求全部稳定返回 DOC_TASK_DISABLED。
再启用只允许发生在 planning；激活后不能原地改变。

7.4 阶段门禁和提醒

当前阶段 N 个启用文档中任一未批准，创建者按钮和对话推进均被阻断并返回清单。
全部批准后只产生一次首提醒；24 小时未处理才产生一次升级提醒。
readiness 后文档被驳回或标 stale 时，旧推进请求失效，确认动作不能成功。
推进事务不会修改任何文档审批状态。
最后一阶段确认后实例为 completed，项目立即可配置下一流程。

7.5 安全、恢复和真实链路

跨项目、非成员、非职责人、未来阶段成员、已退出成员全部有服务端负例。
API、SSE、异步任务、断线恢复、搜索、导出、RAG 和 Agent tool 的判定一致。
服务重启后能恢复 live 实例、当前阶段、禁用状态、职责和 pending 推进请求。
使用真实 PostgreSQL 和真实 PI Agent 分别跑完商务 7 文档、产品 1 文档、测试 1 文档链路。
项目从未运行产品经理流程且不存在 SRS 时，测试工程师仍可依据项目对话、文档和材料成功生成唯一测试方案；输出包含逐项来源追溯和待确认清单。
项目已有 SRS 时，该文档被当作高权威来源纳入，但移除它不会导致工作流定义级依赖错误；是否需要重新生成由本次 source manifest 判断。
项目私聊/个人草稿未共享时不进入上下文；共享后可被新快照发现。跨项目内容在检索和快照层都有负例。
同一组项目输入分别启动产品经理和测试工程师时，两者快照可复现、来源清单一致，输出目标和模板不同。
测试结束后业务数据库中不残留 pg_*、test_* 定义或测试项目。

8. 已确认的业务决策及实施解释

2026-09-12 已确认以下决策，后续实现和验收以此为准：

允许关闭单文档流程的唯一文档，但空工作流不能激活。 配置可以保存，激活预览必须明确阻断并提示重新启用文档或选择其他工作流。
智能产品经理和智能测试工程师解耦。 两者都直接使用当前项目知识边界内的对话、文档、材料、事实和决策。任何一方的产出都不是另一方的启动前置；已有 SRS 仅作为高权威输入来源。
开放项目创建者受控终止工作流。 必须二次确认、填写原因、处理或取消在途任务并形成审计；completed 和 terminated 都允许创建下一工作流实例，但历史含义必须区分。

这些决策合理且彼此一致。第 2 项的实施建议是“流程解耦、数据可组合、来源可追溯”，而不是取消质量控制：测试工程师必须自己从项目上下文抽取需求和风险，生成文档内追溯矩阵，并将缺少判据的内容列为待确认，不能因为没有 SRS 就编造需求。

商务流程按 7 个文档落地、系统只暴露三个正式流程、运行中不可切换、阶段推进必须由创建者确认、禁用文档不得参与任何编审批动作，也均为已确认要求。

9. 建议的实施交付拆分

建议按以下 8 个可独立评审的变更集提交，避免一次大改难以回滚：

正式目录隔离与测试数据库隔离；
三个正式 manifest、严格 validator 和版本升级器；
planning 配置、文档开关和成员/三权校验；
激活冻结与完整实例物化；
doc task instance 驱动的执行、DocGov 和统一授权；
原子 readiness / advance / complete / terminate 状态机；
通知、对话命令与前端只读/下一流程体验；
数据迁移、兼容退出、真实 PG/PI Agent E2E 和发布门禁。

每个变更集都应包含正向测试、越权负例、并发负例和重启恢复验证。只有第 8 项完成后，才应删除旧兼容路径并宣布三工作流治理正式生效。

10. 来源与证据

开发数据库数字来源：2026-09-12 在本机容器内对 workflow_definitions、workflow_versions、project_workflow_instances 和 projects 执行只读聚合查询。该快照仅用于诊断当前开发环境，不代表生产环境。

web/src/engine/templateFactory.test.ts:8-33，测试精确断言 7 个任务键；读取于 2026-09-12。 ↩︎
internal/squad/service.go:128-138，后端标准任务目录包含 7 个商务任务及产品、测试任务；读取于 2026-09-12。 ↩︎
.doc/test-reports/2026-09-08-project-init-template-cloning-test-report.md:12-25,51-60，历史专项测试把商务全生命周期固定为 7 个受控交付物；读取于 2026-09-12。 ↩︎
internal/workflowdef/bootstrap.go:63-74,78-115，启动种子包含三个旧流程及两个额外行业流程；读取于 2026-09-12。 ↩︎
internal/workflowdef/manifests/main.v2.json:1-50，清单只定义 intake、research、feasibility_reg、prelim_design、cdo_quote；读取于 2026-09-12。 ↩︎
internal/workflowdef/manifest_loader.go:9-32 仅提供嵌入读取和文件名映射；仓库检索未发现 V2ManifestFiles 的运行时调用；读取于 2026-09-12。 ↩︎
internal/workflowdef/store.go:364-372，已有任意 latest published version 时直接返回；读取于 2026-09-12。 ↩︎
internal/workflowdef/catalog.go:27-41,50-82，数据库目录将版本压为首阶段首任务；读取于 2026-09-12。 ↩︎
internal/projectinstance/validator.go:37-90,105-139，required 或 blocking 任务关闭时校验失败；读取于 2026-09-12。 ↩︎
internal/workflowdef/manifests/test_manager.v2.json:1-23，测试流程声明 product_manager 前置依赖；读取于 2026-09-12。 ↩︎
internal/bizdev/service.go:349-380,673-687，测试任务硬查同项目 approved SRS、自动注入并记录单一 SRS 血缘；读取于 2026-09-12。 ↩︎
internal/projectinstance/stage_store.go:71-158，推进事务把启用任务状态强制更新为 approved；读取于 2026-09-12。 ↩︎
internal/projectinstance/stage_store.go:128-158 只完成实例，internal/projectinstance/service.go:119-135 又只允许 planning 项目保存下一计划；读取于 2026-09-12。 ↩︎
internal/coordinator/engine.go:672-811，对话推进调用 bizdevSvc.ExecuteStage 并直接改变旧成熟度上下文；读取于 2026-09-12。 ↩︎
internal/projectinstance/service.go:94-113，项目设置枚举全部有 latest published version 的定义；读取于 2026-09-12。 ↩︎
web/src/engine/templateFactory.ts:37-39,87-89,158-160,228-230,286-288,331-333,392-394，7 个商务模板当前归属为 V0.1 一项、V0.5 五项、V1.0 一项；读取于 2026-09-12。 ↩︎
internal/bizdev/service.go:204-223，旧商务阶段仅映射 1 + 3 + 1 个任务；读取于 2026-09-12。 ↩︎
internal/workflow/registry.go:5-15，商务 executor 缺少 feasibility_dev 和 user_requirements；读取于 2026-09-12。 ↩︎
internal/squad/service.go:35-55、internal/squad/workspace.go:262-408 和 internal/bizdev/service.go:250-294，现有运行参数及工作区已支持项目、材料、前序文档、知识和部分项目事实输入；读取于 2026-09-12。 ↩︎
deploy/postgres/goose/00017_2026-09-12-project-workflow-instances.sql:13-52，实例状态和 one planning/one live 唯一索引；读取于 2026-09-12。 ↩︎
internal/projectinstance/types.go:21-48，计划已包含文档 enabled 和三权；读取于 2026-09-12。 ↩︎
internal/projectinstance/store.go:244-280，禁用文档不会写职责行；读取于 2026-09-12。 ↩︎
internal/projectinstance/gate.go:5-53 和 internal/projectinstance/stage_service.go:15-63，现有门禁忽略禁用任务并限制创建者；读取于 2026-09-12。 ↩︎
internal/projectinstance/stage_store.go:176-191，批准同步按 project_id + task_key 更新；读取于 2026-09-12。 ↩︎
internal/server/workflow_approval_hook.go:17-44 和 internal/notification/service.go:38-107，批准回调、推进请求、outbox 与创建者通知；读取于 2026-09-12。 ↩︎
internal/notification/reminder.go:35-91,94-171，24 小时提醒和 confirmed 状态；读取于 2026-09-12。 ↩︎
web/src/components/workflow/StageAdvanceBanner.tsx:29-95,111-151，前端轮询 readiness/通知并提供确认按钮；读取于 2026-09-12。 ↩︎
deploy/postgres/goose/00023_2026-09-12-instance-integrity.sql:8-11 已添加运行元数据列，而 internal/projectinstance/store.go:254-259 插入时未写这些列；读取于 2026-09-12。 ↩︎
internal/projectinstance/stage_access.go:15-71,90-104，live 实例中排除禁用任务，但无 live/completed 时不限制；读取于 2026-09-12。 ↩︎
web/src/components/workflow/ProjectWorkflowSwitcher.tsx:16-23,38-76,173-236，旧名称、旧直切换和冲突自动重试仍存在；读取于 2026-09-12。 ↩︎
internal/server/server.go:157-169，新项目实例 API 与旧 active-workflow/run API 同时暴露；读取于 2026-09-12。 ↩︎
internal/projectinstance/pg_integration_test.go:19-49 和 internal/server/workflow_governance_pg_test.go:26-61，未设置 TEST_DATABASE_URL 时连接本地开发库；读取于 2026-09-12。 ↩︎
internal/workflowdef/publish_test.go:37-72，发布测试创建带时间戳定义但未注册清理；读取于 2026-09-12。 ↩︎
internal/workflowdef/validator_v2.go:9-47，现有 v2 校验范围有限；读取于 2026-09-12。 ↩︎

41 KiB Raw Permalink Blame History Unescape Escape