# PMFlow OS Product Contract 版本日期：2026-04-26 本文档是 PMFlow OS 从本地高保真主链走向真实数据闭环的产品级合同。它锁定对象真源、读写边界、状态流转和后续开发接口，避免 `frontend/src/features/pmflow-os/` 继续围绕 mock store 扩散。A3 已完成真实只读 projection，Phase B 已完成 Project Launch 创建链，Phase C1 已完成 Change Review 数据底座与审查状态机；Phase C2 backend 已按 atomic commit 合同实现，后续前端接入不得再自行改变 API shape。 产品方向真源仍以 `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 为准；UI 行为与状态标签以 `docs/PMFLOW_UI_CONTRACT.md` 为准；推进节奏以 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 为准。 ## 1. 合同结论 PMFlow OS V1 的主链是： ```text Project Thread -> Structured Extraction -> ChangeSet Review -> Project Memory / Work Graph commit -> Execution Bridge -> Release / Growth feedback ``` 当前复用边界： - `Requirement / Decision / Risk / Release` 优先从 `truth_nodes` 投影，不新建另一套正式业务对象表。 - `Task` 复用 `tasks`，并通过 `truth_node_id` 绑定需求/宪章/项目真相节点。 - `Project Memory` 由 `truth_nodes + semantic_facts` 聚合投影；`semantic_facts` 是 read model，不是人工确认记录本身。 - `ModelDecision / PromptPackage / ReleaseValidation / Feedback / Revenue / ROI / Compliance` 复用 `ai_project_control` 模型与 `sstc_api/model_control.py` 现有接口。 - `ExecutionContext` 复用 `prompt_packages + repo_bindings + task_code_links + progress_events + dev_sync summary`。 - `Thread / ThreadMessage` 已由 Phase B 落到 `pmflow_threads / pmflow_thread_messages`。 - `ChangeSet / ChangeItem / Approval / EvidenceLink` 已由 Phase C1 落到 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。 PMFlow OS 专属表： ```text pmflow_threads pmflow_thread_messages pmflow_change_sets pmflow_change_items pmflow_approvals pmflow_evidence_links ``` `/commit` 后端代码与前端真实模式接入已实现；真实模式下 `promoteAcceptedToGraph` 必须调用后端 `POST /pmflow-os/change-sets/{change_set_id}/commit`，不得用本地 mutation 冒充正式 Project Memory 写入。 ## 2. 对象映射表 | 前端对象 | 后端来源 | 是否新增表 | 读 API | 写 API | 状态流转 | 证据/审计 | 风险点 | | --- | --- | --- | --- | --- | --- | --- | --- | | `ProjectTruthState` | 聚合投影：`projects`、`truth_nodes`、`tasks`、`semantic_facts`、PMFlow OS 专属 review 表、`ai_project_control`、`dev_sync` | 不直接建总表 | `GET /pmflow-os/projects/{project_id}/truth-state` | 由各子对象 API 写入 | `loopStage` 由最近线程、提取和审查状态计算 | 返回 customer-safe 状态，不暴露内部 raw label | 需要 projection service，不能由前端拼多个旧接口冒充 | | `Thread` | `pmflow_threads`；绑定 `project_id`、默认目标、当前阶段 | 是，Phase B 已建 | `truth-state` 内返回 | 创建项目时初始化，或 C1 `messages` 首次写入时懒创建 | `idle -> loading -> ready` 仅表示提取状态 | 线程本身是后续 ChangeSet 证据源 | 不能复用飞书 thread/session 作为唯一项目线程 | | `Message` | `pmflow_thread_messages`；可引用 Feishu/QA/message 来源 | 是，Phase B 已建 | `truth-state` 内返回 | `POST /pmflow-os/projects/{project_id}/threads/{thread_id}/messages` | C1 先写 `sent`，后续可扩 `analyzing/resolved/failed` | message id 可被 `EvidenceLink` 引用 | 写 message 不等于写项目真相层 | | `ChangeSet` | `pmflow_change_sets` | 是，Phase C1 已建 | `GET /pmflow-os/projects/{project_id}/change-sets/{change_set_id}` | `POST /pmflow-os/projects/{project_id}/extractions` 生成；C2 才实现 `commit` | C1：`open -> reviewed`；C2：`committed / partially_committed` | 记录生成来源、routing_meta、LLM call id、actor | 不能用 `truth_nodes` 直接模拟 ChangeSet；ChangeSet 是待确认变更包 | | `ChangeItem` | `pmflow_change_items` | 是，Phase C1 已建 | ChangeSet detail | C1：`accept / edit / defer`；C2：`commit` 后写正式对象 | C1：`pending_review -> accepted / edited / deferred`；C2：`committed / skipped` | 每项必须绑定 evidence ids 与 risk level | `accept` 只改审查状态，不得静默落库 | | `Evidence` | `pmflow_evidence_links` 投影，来源可为 message、truth_node、task、progress_event、release_validation、feedback、metric | 是，Phase C1 已建 link 表 | `truth-state`、ChangeSet detail | C1 随 extraction 创建 thread message evidence；C2 随 commit、execution/growth 回写扩展 | 证据不走业务状态，只可 active/archived | 必须记录 `source_type/source_id/excerpt/display_label` | `ai_project_control.EvidencePack` 只适合发布/合规证据包，不能替代通用证据链 | | `Approval` | `pmflow_approvals` | 是，Phase C1 已建 | `truth-state`、ChangeSet detail | C1：`accept / edit / defer` 写入；C2：commit gate 扩展 | `approved / edited / deferred / rejected` | 记录 actor、role、decision、before/after | 高风险变更必须有 approval 记录；C1 只记录，C2 才强制 gate | | `Requirement` | `truth_nodes.node_type in ('charter','requirement')` 投影；V1 可从 charter content 中拆分 requirement block | 否 | `truth-state` | `commit` accepted ChangeItem 后创建/更新 `truth_nodes` | `draft/proposed -> confirmed -> archived`，前端映射到 `draft/confirmed/done` | commit 时绑定 ChangeItem/EvidenceLink；semantic facts hook 后台抽取 | 当前 `TruthNode.node_type` 历史值不统一，需在 projection 层做白名单映射 | | `Decision` | `truth_nodes.node_type='decision'` 或 charter/review content 决策块投影 | 否 | `truth-state` | `commit` 写 `truth_nodes` | `draft/proposed -> confirmed` | 必须保留来源 ChangeItem 和 owner | 若历史没有 decision node，先从 charter content 投影，不新增前端-only 决策 | | `Task` | `tasks` + `truth_nodes` | 否 | `truth-state`；后续可复用 SSTC task board | `commit` 创建/更新 `tasks`；执行进度走 dev-sync | `draft -> in_progress -> blocked/done` | 任务来源 ChangeItem、验收标准、assignee 建议进入审计 | `tasks.status` 与前端状态枚举需 projection 映射 | | `Risk` | `truth_nodes.node_type='risk'` 或 charter/release/check content 风险块投影 | 否 | `truth-state` | `commit` 写 `truth_nodes` | `draft/proposed -> confirmed -> archived` | 高风险必须绑定 approval 与 mitigation | `ReleaseValidationRun.risk_items` 是发布检查结果，不等于正式风险对象 | | `ModelDecision` | `project_model_bindings`、`model_recommendation_snapshots`、`model_eval_runs` 投影 | 否 | `truth-state` 可聚合；细节复用 `/projects/{project_id}/model-recommendations`、`/model-usage` | `/model-binding` | `recommended -> active -> archived` 映射到前端 `confirmed/released` | selection_reason、snapshot_input、eval summary 作为证据 | 不做独立模型市场页，必须嵌入项目主链 | | `TestRun` | `model_eval_runs`、`release_validation_runs`、`progress_events(event_type=test*)` 投影 | 否 | `truth-state`、`execution-summary` | dev-sync progress event 或 release validation | `pending/running -> passed/failed/blocked` | 测试日志和 PR/commit 可作为 evidence | 当前没有通用 test_runs 表，V1 先按投影聚合 | | `Release` | `truth_nodes.node_type='release'` + `release_validation_runs` | 否 | `truth-state`；SSTC release APIs | SSTC release 创建；`run_release_validation` | `check_pending -> ready -> shipping -> live/watch` | release gate、rollback_plan、validation_summary | 发布对象和发布验证结果需要在 projection 中分清 | | `MetricSignal` | `feedback_ingests.metrics`、`revenue_events`、`roi_snapshots`、增长埋点结果投影 | 否 | `truth-state`；`/roi-snapshots` | `feedback-ingest`、`revenue-events` | `draft/proposed -> confirmed` | 指标来源和采样窗口必须展示 | 只做轻量反馈，不引入完整财务系统 | | `ExecutionContext` | `prompt_packages`、`repo_bindings`、`task_code_links`、`progress_events`、`dev_sessions` | 否 | `GET /pmflow-os/projects/{project_id}/execution-summary` 聚合 `GET /projects/{project_id}/dev-sync/summary` | `createPromptPackage`、`bindGithubRepo`、`createProgressEvent` | `queued -> pushed -> coding -> pr_open -> testing -> synced/failed` | progress events、deliveries、repo/PR/commit 是执行证据 | 不得重造 dev-sync；PMFlow OS 只做项目内执行投影 | | `TeamFeed / TeamInbox` | `pmflow_change_sets`、`pmflow_approvals`、`progress_events`、release/feedback 事件聚合 | 暂不新增专表，先 projection | `truth-state` | 由各业务动作写入源表 | feed item 不承载主状态 | 必须能追溯到源对象 | Phase F 才补 Role Inbox/Decision Desk 的真实模型 | ## 3. ProjectTruthState 后端投影 `GET /pmflow-os/projects/{project_id}/truth-state` 返回前端兼容结构，但数据必须由后端 projection service 组装： ```text project: projects + latest confirmed truth_nodes thread/messages: pmflow_threads + pmflow_thread_messages changeSets/changeItems/evidence/approvals: PMFlow OS 专属 review 表 requirements/decisions/risks/releases: truth_nodes 投影 tasks: tasks + related truth_nodes modelDecisions: model_recommendation_snapshots + project_model_bindings + model_eval_runs testRuns: release_validation_runs + model_eval_runs + progress_events(test) metricSignals: feedback_ingests + revenue_events + roi_snapshots feed/teamInbox: review/actions/progress/release/growth 事件聚合 execution: dev-sync summary + prompt_packages + recent progress_events ``` 投影规则： - `AI 已生成` 对应 `ChangeSet.open` 和 `ChangeItem.pending_review`，不得进入正式对象列表。 - `待你确认` 对应 `ChangeItem.pending_review` 或高风险 `Approval.requested`。 - `已确认` 对应 `ChangeItem.accepted/edited`，但尚未必然写入 Project Memory。 - `已写入项目记忆` 只能在 `ChangeSet.commit` 成功写入 `truth_nodes / tasks / semantic_facts` 后出现。 - `semantic_facts` 只用于 read-side facts-first 查询与 Project Memory projection，不作为人工确认动作记录。 ## 4. API 合同草案 所有接口统一返回： ```json { "code": 0, "message": "success", "data": {} } ``` 错误仍走项目现有失败包络与 HTTP 状态；客户可见错误必须明确失败原因，不得用 mock 或默认句冒充成功。 ### 4.1 获取项目真相投影 ```text GET /pmflow-os/projects/{project_id}/truth-state ``` Response `data`： ```json { "loopStage": "extraction_ready", "lastWritebackAt": "2026-04-25T10:00:00+08:00", "project": {}, "thread": {}, "messages": [], "changeSets": [], "changeItems": [], "evidence": [], "requirements": [], "decisions": [], "tasks": [], "risks": [], "modelDecisions": [], "testRuns": [], "releases": [], "metricSignals": [], "approvals": [], "feed": [], "teamInbox": {}, "activeChangeSetId": null, "selectedTaskId": null, "execution": {} } ``` 失败语义： - `404 project_not_found`：项目不存在或不属于当前租户。 - `403 forbidden`：当前用户不是项目成员或管理角色。 - `409 projection_incomplete`：核心合同对象缺失，不能拼装可信 ProjectTruthState。 ### 4.2 写入线程消息 ```text POST /pmflow-os/projects/{project_id}/threads/{thread_id}/messages ``` Request： ```json { "content": "用户输入", "source": "web", "attachments": [] } ``` 行为： - 只写 `pmflow_thread_messages`。 - 可触发异步 extraction job，但不能直接写 `truth_nodes / tasks`。 - 返回 message 和可选 `extraction_job_id`。 ### 4.3 创建结构化提取 ```text POST /pmflow-os/projects/{project_id}/extractions ``` Request： ```json { "thread_id": "thread_123", "message_id": "msg_123", "scope": "latest_message", "proposed_items": [ { "group": "new_object", "object_type": "Requirement", "title": "待审变更标题", "summary": "待审变更摘要", "payload": {}, "confidence": 0.82, "risk_level": "medium" } ] } ``` 行为： - C1 采用 `proposed_items` 最小闭环，不默认调用 LLM；后续 AI 结构化提取应在上游生成 proposed items 后调用该接口。 - 生成 `pmflow_change_sets` 与 `pmflow_change_items`。 - ChangeSet 默认 `open`，ChangeItem 默认 `pending_review`。 - 生成 `pmflow_evidence_links`，至少绑定触发消息。 - 不写 `truth_nodes / tasks / semantic_facts`。 失败语义： - `422 invalid_proposed_items`：未提供可审查 proposed items，不生成 ChangeSet。 - `404 message_not_found`：message 不属于当前 tenant/project/thread。 ### 4.4 获取 ChangeSet ```text GET /pmflow-os/projects/{project_id}/change-sets/{change_set_id} ``` Response `data`： ```json { "changeSet": {}, "items": [], "evidence": [], "approvals": [] } ``` ### 4.5 审查 ChangeItem ```text POST /pmflow-os/change-items/{change_item_id}/accept POST /pmflow-os/change-items/{change_item_id}/edit POST /pmflow-os/change-items/{change_item_id}/defer ``` `edit` Request： ```json { "summary": "修改后的摘要", "diff": "修改后的业务 diff", "payload_patch": {} } ``` 行为： - `accept`：仅将 ChangeItem 置为 `accepted`，写 `pmflow_approvals`，不写正式对象。 - `edit`：保存人工修改后的 payload，状态为 `edited`，写 `pmflow_approvals`。 - `defer`：状态为 `deferred`，不进入项目真相层，但保留审计。 失败语义： - `409 changeset_not_open`：ChangeSet 非 open，不能继续审查。 - `409 item_already_reviewed`：ChangeItem 已被接受、编辑、暂缓、提交或跳过，不重复写 approval。 - `422 invalid_change_payload`：修改后的 payload 不满足对象合同。 ### 4.6 提交 ChangeSet Phase C2 必须按此合同实现，后端与前端不得自行发明其它请求或响应形状。 ```text POST /pmflow-os/change-sets/{change_set_id}/commit ``` Auth： - 当前用户必须是项目成员、`OWNER` 或 `REVIEWER`。 - `tenant_id` 必须来自当前 JWT，不得从请求体传入。 Request： ```json { "item_ids": ["12", "13"], "mode": "atomic", "note": "确认写入项目记忆" } ``` 字段规则： - `item_ids` 可选；为空时提交该 ChangeSet 下全部 `accepted / edited` 项。 - `mode` C2 V1 只允许 `atomic`；未来若支持部分提交，必须先更新本文档。 - `note` 可选，仅进入审计，不参与业务字段生成。 行为： - 只处理 `accepted / edited` 的 ChangeItem。 - `pending_review / deferred / committed / skipped` 不写正式对象，只进入 `skippedItems` 明细。 - C2 V1 使用单事务原子提交：任一 eligible item 写入失败时，整个 commit 回滚，不允许出现半写入 Project Memory。 - 按 `objectType` 写入正式对象： - `Requirement / Decision / Risk / Release` -> `truth_nodes` - `Task` -> `truth_nodes(node_type='task')` + `tasks.truth_node_id` - `ModelDecision` -> `project_model_bindings` 或绑定选择记录 - `MetricSignal` -> 反馈/收入/ROI 相关记录，或生成下一轮 recommendation 草案 - 创建或更新 `pmflow_evidence_links`。 - 提交成功后触发 semantic facts 抽取/刷新。 - 全部 eligible item 成功后 ChangeSet 进入 `committed`。 - `partially_committed` 是未来扩展状态，C2 V1 不应写出该状态。 Response `data`： ```json { "changeSet": { "id": "10", "status": "committed", "rawStatus": "committed", "committedAt": "2026-04-26T10:00:00+08:00", "committedItemIds": ["12"], "skippedItemIds": ["14"], "failedItemIds": [] }, "committedItems": [ { "changeItemId": "12", "objectType": "Requirement", "targetType": "truth_node", "targetId": "301", "status": "committed", "evidenceIds": ["44"], "semanticFactStatus": "queued" } ], "skippedItems": [ { "changeItemId": "14", "objectType": "Task", "status": "deferred", "reason": "item_not_accepted_or_edited" } ], "failedItems": [], "projectTruthState": {} } ``` 响应规则： - `projectTruthState` 可选；若返回，必须是 commit 后的后端真实 projection，不得由前端本地拼装。 - `committedItems[].targetId` 必须是正式对象 id，如 `truth_nodes.id`、`tasks.id`、`project_model_bindings.id`。 - `semanticFactStatus` 取值：`queued / seeded / skipped / failed`；失败不能影响已完成的正式对象写入，但必须进入审计或 failed detail。 失败语义： - `404 changeset_not_found`：ChangeSet 不存在或不属于当前 tenant/project。 - `409 changeset_not_reviewed`：仍存在 `pending_review` 项且请求未显式只提交 `item_ids`。 - `409 changeset_already_committed`：ChangeSet 已经提交，不能重复提交。 - `409 no_accepted_items`：没有 `accepted / edited` 可提交项。 - `409 high_risk_approval_required`：高风险项缺少 required approval。 - `422 invalid_commit_item_ids`：`item_ids` 不属于该 ChangeSet 或包含不可提交状态。 - `422 unsupported_object_type`：`objectType` 不在 C2 白名单。 - `422 invalid_change_payload`：有效 payload 不满足正式对象必填字段。 - `500 commit_failed`：写入正式对象失败；C2 V1 必须回滚整个事务，并返回 `failedItems` 明细，不得冒充部分成功。 ### 4.7 获取执行桥摘要 ```text GET /pmflow-os/projects/{project_id}/execution-summary ``` 行为： - 优先调用或复用 `GET /projects/{project_id}/dev-sync/summary`。 - 额外补齐最近 Prompt Package、活动 repo、PR/commit/test progress event。 - 返回前端 `ExecutionContext` 兼容结构与详细 dev task 列表。 ## 5. ChangeSet 写入正式对象规则 `ChangeItem.objectType` 的提交规则： 有效 payload 生成规则： - `edited` 项优先使用 `edited_payload`，否则使用 `payload`。 - `PMFlowChangeItem.title / summary / diff` 是展示与审计主字段；payload 中同名字段只能补充，不能覆盖人工 edit 后的主字段。 - 每个正式对象 content/payload 必须写入：`source=pmflow_change_set_commit`、`change_set_id`、`change_item_id`、`evidence_ids`、`confidence`、`risk_level`、`committed_by`、`committed_at`。 - 所有正式写入必须带 `tenant_id` 查询边界；`truth_nodes` 历史模型若无显式 `tenant_id` 字段，必须通过所属 `project_id` 的 tenant 校验间接保证租户边界。 | objectType | 正式写入目标 | 必填字段 | 写入后前端状态 | | --- | --- | --- | --- | | `Requirement` | `truth_nodes(node_type='requirement')` | `title`、`summary`、`stage`、证据 | `confirmed` | | `Decision` | `truth_nodes(node_type='decision')` | `title`、`summary`、`owner`、证据 | `confirmed` | | `Task` | `truth_nodes(node_type='task')` + `tasks` | `title`、`description/summary`、`priority`、`acceptanceCriteria` | `draft` | | `Risk` | `truth_nodes(node_type='risk')` | `title`、`summary`、`riskLevel`、`mitigation`、证据 | `confirmed` | | `ModelDecision` | `project_model_bindings` 或 `model_recommendation_snapshots` 引用 | `catalog_item_id` 或推荐快照引用 | `confirmed` | | `Release` | `truth_nodes(node_type='release')` + release validation 引用 | `title`、`summary`、gate items | `check_pending/ready` | | `MetricSignal` | `feedback_ingests`、`revenue_events`、`roi_snapshots` 投影或 recommendation 草案 | source、value、window | `confirmed` | C2 V1 白名单： - 必须实现：`Requirement / Decision / Task / Risk`。 - 可实现但不阻塞 C2：`Release`。 - 暂缓实现：`ModelDecision / MetricSignal`，若收到这两类 item，必须返回 `422 unsupported_object_type`，不得假成功。 禁止规则： - 禁止 `accept` 时直接写正式对象。 - 禁止没有 evidence 的高风险项进入 `commit`。 - 禁止把 AI 生成内容直接投影为 `Project Memory` confirmed facts。 - 禁止让前端用本地 `promoteAcceptedToGraph` 代替后端 commit。 - 禁止 commit 后仍让 `activeChangeSetId` 指向已 committed 的 ChangeSet；projection 应选择最近 open/reviewed ChangeSet，或返回 `null`。 高风险 approval gate： - `risk_level=high` 的 item 必须存在同 item 的 `pmflow_approvals` 记录，且 `decision in ('approved','edited')`、`after_status in ('accepted','edited')`。 - 高风险 item 必须能解析到至少一个 evidence link；ChangeSet 级 evidence 可以继承给 item，但 response 里必须显式返回 `evidenceIds`。 - gate 失败时整个 commit 不写入正式对象。 ## 6. Execution Bridge 复用合同 PMFlow OS 不重造开发执行系统。执行桥复用： - `PromptPackage`：开发上下文包，创建接口为 `POST /projects/{project_id}/charters/{charter_id}/prompt-packages`。 - `RepoBinding / GitHubAppInstallation / GitHubAppRepository`：仓库与 GitHub App 授权状态。 - `TaskCodeLink`：任务与 branch/PR/commit 绑定。 - `ProgressEvent`：commit、PR、test、manual progress 的统一回写事件。 - `DevSession`：开发活跃会话。 - `GET /projects/{project_id}/dev-sync/summary`：当前执行桥最小真实读路径。 `ExecutionContext` 字段映射： | 前端字段 | 后端来源 | | --- | --- | | `taskId` | active dev task id | | `status` | `ProgressEvent.derived_task_status` + `Task.status` projection | | `prompt` | latest `PromptPackage.package_text` | | `commitLog` | recent `ProgressEvent.summary` / payload commit fields | | `prStatus` | `TaskCodeLink.pr_number` + progress event | | `testSummary` | test progress event / release validation summary | | `writebackStatus` | latest progress event workflow state | ## 7. 后续实施顺序 1. A3 最小真实读路径：已实现 `pmflow_os_api` read-only projection，提供 `truth-state` 与 `execution-summary`。 2. Phase B：已把 `/project-launch` 的草案确认接入真实项目创建和初始 Project Memory 写入。 3. Phase C1：已实现 ChangeSet/ChangeItem/Approval/EvidenceLink 表与 `accept / edit / defer` 审查 API。 4. Phase C2 backend：已实现 ChangeSet atomic commit，把 `accepted / edited` 写入 `truth_nodes / tasks / semantic_facts` 并补齐高风险 approval gate。 5. Phase C2 frontend：已把真实模式下的 `promoteAcceptedToGraph` 接到 `POST /pmflow-os/change-sets/{change_set_id}/commit`，commit 后 refetch truth-state。 6. Phase D：把 `ExecutionBridgePage` 切到 `execution-summary` 和 dev-sync 真实数据。 7. Phase E：把 Release/Growth 投影接入 release validation、feedback、revenue、ROI、compliance。 本文档若与后续实现不一致，必须先更新合同再改代码。