PMFlow/docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md

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 的主链是：

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 专属表：

pmflow_threads
pmflow_thread_messages
pmflow_change_sets
pmflow_change_items
pmflow_approvals
pmflow_evidence_links

/commit 后端代码已实现；前端真实模式接入完成前，仍不得用本地 promoteAcceptedToGraph 冒充正式 Project Memory 写入。C2 后续前端实现必须遵守本文 4.6 和第 5 节合同。

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 组装：

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 合同草案

所有接口统一返回：

{ "code": 0, "message": "success", "data": {} }

错误仍走项目现有失败包络与 HTTP 状态；客户可见错误必须明确失败原因，不得用 mock 或默认句冒充成功。

4.1 获取项目真相投影

GET /pmflow-os/projects/{project_id}/truth-state

Response data：

{
  "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 写入线程消息

POST /pmflow-os/projects/{project_id}/threads/{thread_id}/messages

Request：

{
  "content": "用户输入",
  "source": "web",
  "attachments": []
}

行为：

• 只写 pmflow_thread_messages。
• 可触发异步 extraction job，但不能直接写 truth_nodes / tasks。
• 返回 message 和可选 extraction_job_id。

4.3 创建结构化提取

POST /pmflow-os/projects/{project_id}/extractions

Request：

{
  "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

GET /pmflow-os/projects/{project_id}/change-sets/{change_set_id}

Response data：

{
  "changeSet": {},
  "items": [],
  "evidence": [],
  "approvals": []
}

4.5 审查 ChangeItem

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：

{
  "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 必须按此合同实现，后端与前端不得自行发明其它请求或响应形状。

POST /pmflow-os/change-sets/{change_set_id}/commit

Auth：

• 当前用户必须是项目成员、OWNER 或 REVIEWER。
• tenant_id 必须来自当前 JWT，不得从请求体传入。

Request：

{
  "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：

{
  "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 获取执行桥摘要

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。
6. Phase D：把 ExecutionBridgePage 切到 execution-summary 和 dev-sync 真实数据。
7. Phase E：把 Release/Growth 投影接入 release validation、feedback、revenue、ROI、compliance。

本文档若与后续实现不一致，必须先更新合同再改代码。