PMFlow/docs/architecture/CODE_REFERENCE_INDEX.md

# CODE REFERENCE INDEX

## 1. 目的
- 本文档承接 PMFlow 的“新增代码参考模式”与高频代码入口索引。
- `CLAUDE.md` 只保留摘要与跳转入口；详细的接口、页面、服务参考清单统一维护在这里。
- 当新增 API、关键页面入口、工作流入口或参考样式发生变化时，应同步更新本文档。

## 2. 后端接口参考

### 2.1 通用与基础
- 新增后端接口：参考 `backend/app/api/sstc_api/` 的结构
- 新增数据库表：参考 `alembic/versions/` 最新 migration
- 新增飞书事件处理：参考 `backend/app/services/integrations/feishu_integration_service/`
- 飞书卡片动作回调：参考 `backend/app/api/feishu_api/card_action_routes.py` 与 `backend/app/services/integrations/feishu_integration_service/mixin_card_action.py`
- 用户管理接口：参考 `backend/app/api/users_api/`（统一前缀 `GET /users/`、`GET /users/me`、`GET /users/available`、`GET /users/{user_id}`）
- 审计查询接口：参考 `backend/app/api/audit.py`（`GET /audit/operations`）
- 配置读取类接口：参考 `backend/app/api/llm_providers.py`（`GET /ai-steward/llm/providers`）
- LLM 引擎设置接口：参考 `backend/app/api/llm_engines.py`（`PUT /ai-steward/llm-engines/settings`）

### 2.2 AI Steward / Training / Mounted Runtime
- 项目创建接口：参考 `backend/app/api/ai_steward_api/routes_capture.py`
- 模型路由配置接口：参考 `backend/app/api/model_routing.py`
- 回复质量闭环接口：参考 `backend/app/api/ai_steward_api/routes_reply_iteration.py`
- 训练/微调管线接口：参考 `backend/app/api/ai_steward_api/routes_training_pipeline.py`
- Mounted Runtime 控制台接口：参考 `backend/app/api/ai_steward_api/routes_mounted_ai.py`
- 老板晨报接口：参考 `backend/app/api/ai_steward_api/routes_executive_briefing.py`
- 每日简报 v2 接口：参考 `backend/app/api/ai_steward_api/routes_brief_blockers.py`
- 脏数据修复接口：参考 `backend/app/api/ai_steward.py`（`POST /ai-steward/signal-sources/repair-dirty`）
- AI Steward 指挥规划接口已移除：`POST /ai-steward/command/dispatch`

### 2.3 RAG / AI PMO / Knowledge Graph
- RAG 问答主入口：参考 `backend/app/api/rag_api/` 与 `backend/app/api/rag_ask_contract.py`
- `/rag/ask` richer response contract、QA session detail 与 state replay：参考 `backend/app/api/rag_ask_contract.py`、`backend/app/services/adaptive_rag_service/mixin_qa_session_list_ops_p1.py`
- Unified Project Operating Context 合同与 builder：参考 `backend/app/schemas/project_operating_context.py`、`backend/app/services/ai_pmo/project_operating_context_builder.py`
- Four-level interaction boundary 合同与冷启动 answer control：参考 `backend/app/services/ai_pmo/semantic_context/decision_schema.py`、`backend/app/services/ai_pmo/workflow_semantic_planner/service.py`、`backend/tests/test_semantic_decision_service.py`、`backend/tests/test_workflow_semantic_planner.py`；`interaction_boundary` 负责表达本轮允许做到 `status / recommendation / draft / execute` 哪一挡以及禁止升级到哪一挡，`answer_control` 负责把识别出的 workflow 真正过滤成最终可执行 bundle，并把 `requested_level / forbidden_levels / effective_level / blocked_workflows` 挂进 diagnostics
- Analysis packet family 合同与 builder：参考 `backend/app/schemas/analysis_packets.py`、`backend/app/services/analysis_packet_builder.py`、`backend/app/services/analysis_project_snapshot_loader.py`；当前 `project_fit_analysis / external_impact_analysis / internal_explain_analysis` 已显式带 `current_subject / candidate_position / rejected_position / reason_chain`，共享 richer project snapshot 由 loader 统一补 `tasks/signals + description/summary + analysis_object_refs`；但 loader 现已 fail-closed，没有真实结构锚点时不再从 task/signal 标题描述推导 object refs。builder 只消费显式 object ref、精确文本绑定和唯一候选这三类非语义结构证据；`direct_match` 若缺 dependent task ref，就只保留 anchor signal，不再硬挂任务；`internal_explain` 若缺 `target_resolution`，也只允许精确文本绑定，不再做 partial-name/overlap 反绑。
- sparse project-fit 降级规则也在 `backend/app/services/analysis_packet_builder.py`：当前若 `preferred/rejected` 结构对象缺失，会直接按“结构对象缺失”降级，不再靠“解释层/当前主链”占位词表、token-overlap 或 partial-name match 决定 fallback 分支。
- Query 路由网关与显式来源回复合同：参考 `backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py`
- query semantics 真源与 business-frame 输出：参考 `backend/app/config/ai_prompts.py`、`backend/app/services/adaptive_rag_service/mixin_core_intent.py`、`backend/app/services/ai_pmo/semantic_context/business_frame_schema.py`；当前 query semantics 上游只保留 `query_profile(needs_private_context, needs_freshness, confidence)` 与 `business_frame` 这组运行时真源，不再输出/持久化 `subject_focus / query_profile.referenced_objects`
- `ProjectFitBrief` 构建与 external handoff 接缝：参考 `backend/app/services/adaptive_rag_service/mixin_project_fit_brief.py`、`backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py`；formal `signal_source_anchors` 与当前项目任务目标 `signal_source_objectives` 都在这里生成
- `execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step / handoff_mode` 回答接缝：参考 `backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py`、`mixin_answer_mainline.py`、`mixin_answer_payload.py`
- follow-up session rewrite gate 与“新项目/新业务 scope reset”判定：参考 `backend/app/services/adaptive_rag_service/mixin_session_state.py` 与 `mixin_answer_mainline.py`；当前实现会先比对上一轮 `QARecord.routing_snapshot` 的 `project_id / target_resolution / business_frame binding` 与当前原始问句解析出的同组结构，再决定是否允许 `state_subject/state_entities` 重写，避免在 `session_state` 里靠项目名/正则延续旧主题
- follow-up anchor / pending clarification 结构化恢复：参考 `backend/app/services/adaptive_rag_service/mixin_followup_anchor.py` 与 `mixin_answer_mainline.py`；当前 `query_route_selection / followup_anchor_selection` 都先经过统一结构化澄清解析，再把选中的 `source_policy_hint / query_semantics_overrides / selected_qa_id` 透回主链。`selected_qa_id` 会继续传给 follow-up anchor resolver，避免“第二条/那条”澄清后又回到最近回复词面重猜
- Internal Query `Operation Contract / Target Resolver` 的 business-frame-first 入口：参考 `backend/app/services/adaptive_rag_service/mixin_target_resolution.py`；当前 `goal_kind / target_scope / resource_role / project_binding / object_binding / expected_answer_shape` 会先被收进 operation contract，再由 target resolution 直接据此判定 `project / task / signal / config / feature / doc / user` 绑定，不再靠 `subject_focus / referenced_objects` 这类 coarse 字段补拍对象
- `AdaptiveRAG` read-side business-frame-first 归一化入口：参考 `backend/app/services/adaptive_rag_service/shared_utils.py`；`_structured_runtime_entity_type / _structured_project_requested` 会把 `business_frame + target_resolution + query_plan` 合成统一 entity/project binding，供 `mixin_deterministic_query_core.py`、`mixin_fast_answer_project_main.py`、`mixin_fast_answer_semantic_p1.py`、`mixin_deterministic_query_count.py`、`mixin_deterministic_query_list.py`、`mixin_retrieval_router_db.py`、`mixin_deep_guard_answer.py`、`mixin_answer_mainline.py`、`mixin_manifest_feature_p2.py` 复用；这些 read-side consumer 现已不再读取 `subject_focus / referenced_objects` 做 `project / task / signal / config / feature / doc / user` 的快答、检索和 deep guard 分流
- unified handoff rollback guard：参考 `backend/app/services/adaptive_rag_service/shared_utils.py`（env flags）、`mixin_query_route_gateway.py`、`mixin_answer_retrieval.py`、`mixin_answer_payload.py`
- QA session detail 对 handoff 元数据的持久化/回放：参考 `backend/app/services/adaptive_rag_service/mixin_core_intent.py`、`mixin_qa_session_list_ops_p1.py`
- Feishu QA 文本呈现与 action card 分流：参考 `backend/app/services/integrations/feishu_integration_service/mixin_receive_routing.py`、`mixin_card_action.py`、`backend/tests/test_feishu_card_action_contract.py`；当前实现为“共享 analysis_packet -> 受控改写 -> blocked-entity 校验 -> deterministic fallback”的两段式 presenter，相关 prompt 在 `backend/app/config/ai_prompts_catalog/part_01.py`。`qa_direct` 还额外承担中文化 presentation policy：原始 answer 若泄出 `Project database / signal_total / 当前盘面 / 建议动作 / External Freshness Guard` 等英文或内部术语，或自然化结果直接复述 `分析包 / analysis_packet / missing_mapping / next_step / focus_objects / reason_chain` 这类内部 packet jargon，会优先压回 packet 文本，并最多只补一行中文来源说明；命中外部信号源 recommendation 呈现时，现在优先吃 `rag_result.external_query_plan/query_semantics` 里的结构化 `interaction_level=recommendation`，不再靠 Feishu 本地问句 cue list 决定是否直出推荐正文。对 sparse project-fit fallback，当前 deterministic reply 也会被重写成业务中文，不再原样暴露 packet 缺口字段
- Query route governance 只读审计接口：参考 `backend/app/api/rag_api/routes_route_governance.py` 与 `backend/app/services/adaptive_rag_service/mixin_query_route_governance.py`
- External Query Service 主链：参考 `backend/app/services/external_query_service/`（`planner.py`、`gateway.py`、`registry.py`、`schemas.py`、`presenter.py`、`adapters/`）；`planner.py` 当前会对“推荐外部信号源”问法优先补 `signal_source_objectives / signal_source_anchors` 驱动的项目锚点查询，并在 structured plan 返回过泛 query 时仍把这些项目锚点 seed queries 保留在前面；同时 `ExternalQueryPlan.interaction_level` 会承接统一语义规划层透传下来的 `recommendation` 层级，供后续 presenter 分支消费。`schemas.py` 现在还定义了 recommendation 内容层的 `SignalSourceRecommendationPacket / SignalSourceRecommendationCandidate`，`presenter.py` 会先生成这层结构化候选，再渲染成业务中文的 `top-N candidate + why`；recommendation 分支现在优先看 `plan.interaction_level` 与结构化 recommendation goal/anchors，不再靠 presenter 本地问题 cue list 拍板。当前 presenter 仍保留 overclaim guard：若候选里出现百分比、已确认、无需验证或内部术语，会 fail-closed 回退到 customer-safe fallback candidate，而不是继续把高确定性或架构腔文本吐给用户
- non-plan 外部推荐 -> signal source 直写链：参考 `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_signal_source.py`、`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/ingress/ai_pmo_kernel_mixins_ingress_storage.py`、`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_project_signal_resume.py`、`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_verification.py`、`backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_reply_renderer.py`；这条链当前会把 recommendation candidate set 经 `reply_anchor_qa_context + action_contract` 沉到执行结果，再在后续 `把推荐的写进系统 / 确认入库` 时复用 `candidate_set_binding + candidate_refs + project_binding` 继续 `prepare_write -> confirm_write -> execute_write`，非 `plan mode` 不再默认 requirement draft，且一旦 signal 已 materialize 并写入项目，用户可见结果视为成功，后续 onboarding/manual 状态只通过 `post_process_status` 暴露
- requirement-plan / draft confirm 协议优先级与碎片化收敛主链：参考 `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py`、`backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_entry.py`、`backend/tests/test_ai_pmo_ingress_mainline.py`；当前实现明确把 raw `A/B/C/确认/取消/重出/修改` 协议放在 semantic backfill 之前，active requirement 的碎片化短回复优先留在 collect / contextual promotion 主链，且 `ready / draft_pending_confirm` 状态下无锚点单句不再劫持旧草稿确认链
- 去 lexical fallback 的运行时入口：`backend/app/services/adaptive_rag_service/mixin_fast_answer_project_main.py` 里的 project progress fast answer bypass 现在只吃结构化 `interaction_level / goal_kind / resource_role / expected_answer_shape`；`backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py` 的 casual chat 直答只吃 `message_intent=casual_chat`，`project_lookup` shortcut 只吃结构化 `message_intent=project_lookup(_question) + query_semantics`，不再靠问句词面、`项目列表/项目清单` 正则或 `extract_project_lookup_keyword` 提前抢答；`backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor_mixins_parse.py` 与 `backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/mixin_analysis.py` 的 signal 数量/strict analysis 也只消费结构化 `requested_count / analysis_mode / operation_intent_contract`，不再从自由文本里解析“3个信号”“先分析后入库”
- internal config/domain clarify 与 fast answer 真源：`backend/app/services/adaptive_rag_service/internal_domain_catalog.py`、`mixin_target_resolution.py`、`mixin_followup_anchor.py`、`mixin_answer_precheck.py`、`mixin_answer_payload.py`、`mixin_deep_guard_answer.py`。当前 internal domain catalog 已覆盖 `project / task / signal / config / feature / doc / user`；其中 config 主链只认 `business_frame.object_binding`（如 `config:model_routing`、`config:mcp_template_center`）做直答，task/signal/feature/doc/user 则优先走 domain-first target resolution 与受控 retrieval。若只确认了大域但还没唯一落到子对象，则先从 internal domain catalog 产出 `internal_target_selection` 澄清协议，pending clarification follow-up 会把选中的 `query_semantics_overrides` 回填主链后再继续往里查，而不是重复旧答案。
- 项目化 `impact_judgment` 快答主链：`backend/app/services/adaptive_rag_service/mixin_fast_answer_project_main.py`。当 `business_frame.goal_kind=impact_judgment` 或 `expected_answer_shape=impact_chain` 时，会把项目影响判断接到 project progress fast answer 主链，并在没有外部实时条目时仍保留结构化 `external_impact` 结论
- Feishu signal pipeline 的结构化 intake 主链：参考 `backend/app/services/integrations/feishu_signal_pipeline/mixin_process_message_core.py`、`mixin_process_message_default.py`、`mixin_item_processing.py`、`mixin_extraction.py`、`mixin_item_finalize_routing.py`、`mixin_core_base.py`；当前 default capture 会把 `intent_gate` 透给后续 `signal_intake_hint`，extraction 失败时统一回落到低置信 degraded payload（不再使用 `_is_simple_signal_source_request / _heuristic_*_fallback / regex 项目命名猜测`），core dedupe intent fragment 也只保留标准化片段，不再本地推导 `external_integration / project_setup / feature_change`
- Feishu `project.create` 的结构化预填链：参考 `backend/app/services/integrations/feishu_signal_pipeline/mixin_intent_gate_core.py`、`mixin_context_prefill_a.py`、`mixin_context_prefill_b.py`、`mixin_serialization.py`、`mixin_extraction.py`；当前项目字段预填统一依赖 `_extract_project_prefill()` 产出的 `suggested_name / suggested_description / suggested_scope`，不再使用 `_extract_project_scope / _extract_project_intent_fields / _is_contextual_project_request / heuristic_*` 这类词面推断。
- external route 回答接缝与回归：参考 `backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py`、`mixin_deep_guard_answer.py`、`backend/tests/test_mcp_external_query_bridge.py`、`backend/tests/test_adaptive_rag_mainline_contract.py`
- 运行时语义守门与回归：参考 `scripts/semantic_lint.py`、`backend/tests/test_semantic_lint.py`、`backend/tests/test_external_query_planner.py`
- MCP backend-direct runtime / Microsoft Learn bridge：参考 `backend/app/services/mcp_config/runtime.py` 与 `backend/app/services/mcp_config/service.py`
- 路由记忆样本模型：参考 `backend/app/models/query_route_memory.py`
- Internal Query `Operation Contract / Target Resolver / DSL / InternalContextPacket / verifier` 主链：参考 `backend/app/services/adaptive_rag_service/internal_query_context.py`、`mixin_target_resolution.py`、`mixin_answer_mainline.py`、`mixin_deterministic_query_core.py`、`mixin_answer_payload.py`
- Semantic facts 读模型与抽取服务：参考 `backend/app/models/semantic_fact.py`、`backend/app/models/semantic_fact_extraction_run.py`、`backend/app/services/semantic_fact_service/`
- Semantic facts 自动入队钩子：参考 `backend/app/services/semantic_fact_service/hooks.py`
- Semantic facts 异步事件消费：参考 `backend/app/services/project_knowledge_graph_service/mixin_event_queue.py`
- Semantic facts 治理后台接口：参考 `backend/app/api/semantic_facts_api/routes.py`
- KG 上下文闭环接口：参考 `backend/app/api/knowledge_graph.py`
- 任务包中心接口：参考 `backend/app/api/task_briefs.py`
- MCP 模板接入中心接口：参考 `backend/app/api/mcp_api/routes.py`
- AI PMO 恢复接口：参考 `POST /ai-pmo/work-items/{work_item_id}/resume`
- AI PMO 草稿决策接口：参考 `POST /ai-pmo/work-items/{work_item_id}/draft-decision`
- AI PMO 审批接口：参考 `POST /ai-pmo/work-items/{work_item_id}/decision`
- AI PMO 消息台列表接口：参考 `GET /ai-pmo/work-items`
- AI PMO `process-text/work-item` 的 `plan_mode / plan_status / requirement_plan_context_summary` 投影：参考 `backend/app/api/ai_pmo_api/helpers_inbox_payload.py` 与 `backend/app/api/ai_pmo_api/routes_core.py`
- `/rag/ask` 与 `/ai-pmo/process-text` 注入 `project_operating_context`：参考 `backend/app/api/rag_ask_contract.py` 与 `backend/app/api/ai_pmo_api/routes_core.py`

### 2.4 Signal / Project / SSTC
- 需求点落信号源：参考 `backend/app/services/signal/signal_source_orchestration/mixin_registry_execute.py`
- 飞书捕获模拟接口：`POST /ai-steward/signal/capture-feishu`
- 项目删除接口：参考 `backend/app/api/projects.py`
- 项目成员分配接口：参考 `backend/app/api/projects.py` + `backend/app/services/project_member/service.py`
- 通用任务拆解接口：参考 `POST /tasks/breakdown`
- SSTC 总览接口：参考 `GET /projects/{project_id}/sstc/overview`
- SSTC 信号列表接口：参考 `GET /projects/{project_id}/signals`
- SSTC 宪章详情接口：参考 `GET /projects/{project_id}/charters/{charter_id}`
- SSTC 宪章 AI 预填充接口：参考 `POST /projects/{project_id}/charters/{charter_id}/ai-prefill`
- SSTC AI 拆解接口：参考 `POST /projects/{project_id}/charters/{charter_id}/tasks/ai-breakdown`
- SSTC 发布验证生成接口：参考 `POST /projects/{project_id}/releases/{release_node_id}/verification/generate`
- SSTC 负责人推荐接口：参考 `POST /projects/{project_id}/tasks/{task_id}/recommend-assignee`
- SSTC 任务更新接口：参考 `PATCH /projects/{project_id}/tasks/{task_id}`
- SSTC 发布创建接口：参考 `POST /projects/{project_id}/releases`
- PMFlow OS 真实读路径、C1 Change Review API、C2 backend commit、Execution Handoff、Release Evidence Gate、Release Validation Run、Release Feedback Signal 与 Iteration Loop draft：参考 `backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_os_projection_service.py`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`；只读提供 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync`，并读取 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；C1 写 API 包括 thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`；C2 backend 已实现 `POST /pmflow-os/change-sets/{change_set_id}/commit`，默认 `mode=atomic`，将 `Requirement / Decision / Risk` 写入 `truth_nodes`，将 `Task` 写入 `truth_nodes(node_type='task') + tasks`，高风险项强制 approval gate；D.2 已实现 `POST /pmflow-os/projects/{project_id}/execution-handoffs`，对已确认任务生成/复用 `PromptPackage` 并创建 `ProgressEvent(event_type='handoff_created')` 起点；P1 已实现 `POST /pmflow-os/projects/{project_id}/execution-handoffs/{prompt_package_id}/consume`，记录运行端领取、更新 `PromptPackage.package_payload.latest_handoff.handoff_state=consumed` 并创建 `ProgressEvent(event_type='handoff_consumed', derived_task_status='coding')`；Release Growth P1 已在 `execution-summary.releaseGate` 中从 branch / commit / PR / test_passed / checks_passed / failed / blocked 等 `ProgressEvent` 推导 `ready / blocked / needs_confirmation / empty`；Release Validation P1 新增 `POST /pmflow-os/projects/{project_id}/release-validation-runs`，从当前 `releaseGate` 固化 `ReleaseValidationRun` 快照并在 `releaseGate.latestValidationRun` 返回最新记录，无 evidence 时返回 `release_validation_evidence_empty`；Release Feedback P1 新增 `POST /pmflow-os/projects/{project_id}/release-feedback-ingests`，复用 `FeedbackIngest / IterationRecommendation` 写入真实发布后反馈，并在 `execution-summary.releaseSignals` 投影真实 `feedback / revenueEvents / recommendations` 与 release gate / validation run 关系；Iteration Loop P1 新增 `POST /pmflow-os/projects/{project_id}/iteration-recommendations/{recommendation_id}/change-set-drafts`，把真实 `IterationRecommendation` 转为 open ChangeSet、pending_review Requirement/Task/Risk/Decision items 与 iteration evidence，重复调用复用既有 draft；Iteration Loop P2 新增 `POST /pmflow-os/projects/{project_id}/iteration-recommendation-groups/{group_key}/change-set-drafts`，并在 `execution-summary.releaseSignals.recommendations` 补 `groupKey / duplicateOf / mergedCount / impactLevel / riskLevel / suggestedChangeTypes / reviewPriority`，在 `recommendationGroups` 聚合同组建议，支持同组 recommendation 批量生成一个可复用 ChangeSet draft 与 `iteration_recommendation_group` evidence；这些步骤均不执行发布命令、外部支付、真实推送、自动 Project Memory commit 或正式 Task 创建
- Project Launch 真实创建链：参考 `backend/app/api/pmflow_launch_api/`、`backend/app/services/pmflow_launch_service.py`、`backend/app/schemas/pmflow_launch.py` 与模型 `backend/app/models/pmflow_launch.py`；接口为 `POST /pmflow-launch/drafts` 与 `POST /pmflow-launch/drafts/{draft_id}/confirm`，draft 只写 `pmflow_launch_drafts`，confirm 在同一事务内创建 `projects / user_projects / pmflow_threads / pmflow_thread_messages / truth_nodes / tasks / semantic_facts seed / operation_logs`
- PMFlow Change Review 模型与 migration：参考 `backend/app/models/pmflow_change_review.py` 与 `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`；只包含 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`，本阶段不得新增或依赖 `/commit`

## 3. 前端参考
- PMFlow UI 契约真源：先读 `docs/PMFLOW_UI_CONTRACT.md`，再修改 `project-launch`、`personal-space`、`pmflow-os` 相关页面；该文档锁定 Logo、色彩、移动端底部导航、状态标签、AI 操作/用户动作/待确认视觉语法和核心功能 canonical 契约
- PMFlow 大模块并行公共壳：参考 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 的 `4.4.1-4.4.3` 与 `frontend/src/router/index.tsx`、`frontend/src/main.tsx`、`frontend/src/features/pmflow-os/components/MobileBottomNav.tsx`、`frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`；`/space` 归 Space lane，`/pmflow-os / /command-center / /change-review / /execution-bridge / /release-growth` 归 Main Flow lane，`/me` 归 Account Settings lane，`/settings` 当前仅为 reserved route，新增或改动必须由 Shell / Integration owner 串行处理
- PMFlow OS 产品合同真源：先读 `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`，再实现 `pmflow-os` 真实后端接入；该文档锁定 `ProjectTruthState / Thread / ChangeSet / ChangeItem / Evidence / Approval / Project Memory / ExecutionContext` 与 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 的复用边界和后续 API 草案
- 新增前端 API 调用：参考 `frontend/src/api/sstc.ts`；Space 工作面只读聚合参考 `frontend/src/api/space.ts`，只消费项目摘要与 PMFlow OS `truth-state / execution-summary`，不写 Project Memory、ChangeSet 状态、ProgressEvent 或 ReleaseValidationRun；Space P3 的 `releaseAttention` 优先从 `truth-state.releases` 的 release validation 投影生成“发布验证阻塞 / 发布验证待确认”，没有验证投影时才回落到 `PMFlowExecutionSummary.releaseGate` 的“发布候选 / 发布门禁阻塞”，所有动作只跳转 `/release-growth?projectId=<id>`；PMFlow OS 真实接入参考 `frontend/src/api/pmflowOs.ts` 的 `getPMFlowTruthState(projectId)`、`getPMFlowExecutionSummary(projectId)`、`createPMFlowExecutionHandoff`、`consumePMFlowExecutionHandoff`、`createPMFlowExecutionProgressEvent`、`createPMFlowReleaseValidationRun`、`createPMFlowReleaseFeedbackIngest`、`createPMFlowIterationRecommendationChangeSetDraft`、`createPMFlowIterationRecommendationGroupChangeSetDraft`、`createPMFlowThreadMessage`、`createPMFlowExtraction`、`getPMFlowChangeSet`、`acceptPMFlowChangeItem`、`editPMFlowChangeItem`、`deferPMFlowChangeItem`、`commitPMFlowChangeSet`；`PMFlowExecutionSummary.releaseGate` 是 ReleaseGrowth 真实发布门禁前端合同，`releaseGate.latestValidationRun` 是最新发布验证记录前端合同，`execution-summary.releaseSignals` 是 Release/Growth 发布后 feedback/revenue/recommendation 信号、recommendation quality grouping 与下一轮 ChangeSet draft 状态前端合同；Project Launch 创建链参考 `frontend/src/api/pmflowLaunch.ts` 的 `createPMFlowLaunchDraft` 与 `confirmPMFlowLaunchDraft`
- AI Steward 页面入口：参考 `frontend/src/pages/ai-steward/`
- AI Steward 问答浮窗与上下文显性化组件：参考 `frontend/src/components/ai-steward/FloatingQAChat.tsx`、`frontend/src/components/ai-steward/QAConversationStatusBar.tsx`、`frontend/src/components/ai-steward/QAResponseMetaCard.tsx`
- AI Steward QA contract 前端类型（含 `analysis_packet`）：参考 `frontend/src/api/aiSteward.ts`
- AI Steward handoff 元卡片回归：参考 `frontend/src/components/ai-steward/FloatingQAChat.test.tsx`、`frontend/src/components/ai-steward/QAResponseMetaCard.test.tsx`
- AI Steward / QA session 前端 contract：参考 `frontend/src/api/aiSteward.ts`
- PMFlow OS 前端 MVP 产品域：参考 `frontend/src/features/pmflow-os/`
- 个人空间首页 / 空间层入口前端产品域：参考 `frontend/src/features/personal-space/`、`frontend/src/api/space.ts` 与薄入口 `frontend/src/pages/PersonalSpacePage.tsx`；本地预览路由入口为 `/space`，覆盖继续推进、待我确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱与最近项目，点击项目主动作进入 `/pmflow-os?projectId=<id>`，待确认项进入 `/change-review?projectId=<id>&changeSetId=<id>`，执行中项进入 `/execution-bridge?projectId=<id>`，发布关注和发布后反馈关注项进入 `/release-growth?projectId=<id>`，已生成 ChangeSet draft 的下一轮建议进入 `/change-review?projectId=<id>&changeSetId=<id>`；Space 只读聚合项目摘要、PMFlow OS `truth-state.releases / execution-summary.releaseGate / execution-summary.releaseSignals`，发布验证、发布后信号或 iteration draft 缺失时显示明确空态，不虚构验证、反馈、收入、ROI、合规、iteration recommendation 或 ChangeSet draft，不直接写 Project Memory、ChangeSet 状态、execution event、ReleaseValidationRun、FeedbackIngest、RevenueEvent 或 ComplianceCheckRun；暂存想法后端只读聚合尚未接入时必须显示 empty/warning，不得用 mock 数据冒充真实内容；空间层共享左侧栏、顶部条与空间用量组件在 `frontend/src/features/personal-space/components/SpaceChrome.tsx`，`/project-launch` 桌面首次新建壳也复用该组件
- 新项目启动台 / 首次进入页前端产品域：参考 `frontend/src/features/project-launch/` 与薄入口 `frontend/src/pages/ProjectLaunchPage.tsx`；真实模式默认通过 `frontend/src/api/pmflowLaunch.ts` 调用后端 draft/confirm API，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用 `mockData.ts` 本地演示状态机；本地预览路由入口为 `/project-launch`
- Account Settings / `/me` 前端产品域与 P1/P2/P3/P5/P6 偏好合同：参考 `frontend/src/features/account-settings/AccountSettingsPanel.tsx`、`frontend/src/features/pmflow-os/pages/AccountPage.tsx`、`frontend/src/api/accountSettings.ts`、`backend/app/api/account_settings_api/`、`backend/app/schemas/account_settings.py` 与 `backend/app/services/account_settings_service.py`；当前覆盖个人资料、默认语言、AI 回答深度、证据展示偏好、待确认、执行回写、发布门禁和失败提醒通知偏好，移动端使用分组列表与 bottom sheet，账户退出仍复用 `AccountControls.tsx`，不改 OAuth/JWT/auth core；P1 后端合同提供 `GET /account-settings/me` 与 `PUT /account-settings/me`，已由 `backend/app/api/router.py` 挂入核心路由组，按当前 `tenant_id + user_id` 保存账号偏好，前端有 token 时优先账号同步，后端不可用时明确回落 `仅本机暂存 / 保存失败`；P2 在 `frontend/src/api/accountSettings.ts` 提供 `shouldShowAccountNotification` 与 `getAccountNotificationConsumption`，把通知偏好映射为页面内提醒消费模型；P3 新增 `getReleaseGateNotificationPreference(settings, event)` 供 Release/Growth 后续消费：`release_gate_*` 与 `release_validation_*` 使用 `releaseGate` 偏好，`failed_event` 使用 `failureAlert` 偏好；P5/P6 的 `getPostReleaseNotificationPreference(settings, event)` 供发布后反馈与下一轮待确认消费：`feedback_received / revenue_signal / compliance_blocked` 使用 `releaseGate` 偏好，`iteration_recommendation / next_change_review` 使用 `pendingConfirmation` 偏好并落到 `change_review` surface，返回 `spaceReadable / showInAppReminder / evidencePolicy / reminderPolicy`；ReleaseGrowthPage 当前消费 `releaseGate` 与 `failureAlert` 两个偏好，只静默强调型提醒，不隐藏 release evidence、阻塞原因、审计状态、validation run、releaseSignals 或下一轮 ChangeSet draft；这些 helper 只控制本地 UI 提醒消费合同，不代表真实邮件、桌面推送或系统通知中心已接入
- PMFlow OS 共享 truth store 与主链状态动作：参考 `frontend/src/features/pmflow-os/store.tsx`；当前支持 `?projectId=<id>` 走 React Query 读取真实 `truth-state` 与 `execution-summary`，真实模式下 thread message、`proposed_items` extraction、ChangeItem `accept/edit/defer`、ChangeSet commit、Execution Handoff create/consume、execution progress writeback、release validation run create、release feedback ingest、单条 iteration recommendation -> ChangeSet draft 与同组 iteration recommendation 批量 -> ChangeSet draft 均调后端并 refetch，不本地 promote 入 Project Memory、不伪造 execution event、发布验证记录、发布后信号或下一轮 draft；`?demo=1` 才启用本地 mock 演示状态机和本地动作；项目内 AI 结构化闭环状态机为 `command_idle / ai_extracting / extraction_ready / review_open / writeback_success`
- PMFlow OS 产品页入口：参考 `frontend/src/features/pmflow-os/pages/CommandCenterPage.tsx`、`StructuredExtractionPage.tsx`、`ChangeReviewPage.tsx`、`MemoryWritebackResultPage.tsx`、`WorkGraphPage.tsx`、`ExecutionBridgePage.tsx`、`ReleaseGrowthPage.tsx`、`TeamLayerPage.tsx`、`ProjectMemoryPage.tsx`、`AccountPage.tsx`；`ReleaseGrowthPage.tsx` 真实模式展示 `execution-summary.releaseGate`、execution evidence、阻塞原因、下一步动作、`latestValidationRun` 和 `releaseSignals`，缺证据或缺发布后信号时显示 empty/warning，不展示 mock 发布结果；页面可调用真实 API 创建 release validation run、摄取 release feedback，从真实 recommendation 生成下一轮待确认 ChangeSet draft，并按 `recommendationGroups` 批量生成同组下一轮 ChangeSet draft；`ChangeReviewPage.tsx` 会解释来自 `iteration_recommendation_group` evidence 的组、反馈、风险、影响和审查优先级；生成后仍进入 Change Review accept/edit/defer，不自动 commit、不写 Project Memory、不执行部署命令、不接外部支付；同时消费 Account notification preference helper，`releaseGate` 关闭时静默发布门禁强调提醒，`failureAlert` 关闭时静默失败强调提醒，所有真实证据和审计状态仍可见；静态高保真发布/增长数据仅保留在显式 demo 模式
- PMFlow OS 行为组件：参考 `frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx`、`ProjectStageRail.tsx`、`ThreadComposer.tsx`、`ExtractionRail.tsx`、`ChangeGroupPanel.tsx`、`ObjectGraphSection.tsx`、`ContextPacketPanel.tsx`、`ExecutionTimeline.tsx`、`ReleaseGatePanel.tsx`、`TeamFeedPanel.tsx`、`ChangeReviewGroup.tsx`、`WorkbenchPanel.tsx`、`ExecutionBridgeCards.tsx`、`PMFlowOsFrame.tsx`、`AccountControls.tsx`、`FeedbackPrimitives.tsx`、`MobileBottomNav.tsx`；其中 `ProjectStructuredLoop.tsx` 承接 `StatusLabel / EvidenceSnippet / ObjectChangeCard / ProjectConversationPanel / StructuredExtractionPanel / ProjectAICopilotPanel`，`PMFlowOsFrame.tsx` 承接项目内面包屑和项目切换器，`AccountControls.tsx` 承接桌面头像菜单、退出登录确认与移动端 bottom sheet，`FeedbackPrimitives.tsx` 承接 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet`，`MobileBottomNav.tsx` 承接正式应用壳移动端固定底部导航
- PMFlow OS 原型状态回归测试：参考 `frontend/src/features/pmflow-os/store.test.ts`；真实 API 动作回归参考 `frontend/src/features/pmflow-os/store.api.test.tsx`
- Project Launch 真实/演示分支回归测试：参考 `frontend/src/features/project-launch/useProjectLaunchState.test.ts`
- Account Settings 前端合同回归测试：参考 `frontend/src/features/account-settings/accountSettings.test.ts`，覆盖默认偏好、账号同步 fallback、通知偏好消费模型、Release/Growth 通知消费合同、失败事件映射和缺字段 fallback。
- 网页问答显式锚点与 AI Steward URL 构造：参考 `frontend/src/components/ai-steward/qaPageAnchor.ts`
- Inbox 页面入口：参考 `frontend/src/pages/inbox/`
- Inbox `plan_mode` 展开卡片与映射：参考 `frontend/src/components/inbox/InboxListItem.tsx`、`frontend/src/lib/inbox.ts`、`frontend/src/api/aiPmo.ts`
- 登录页/营销页的共享视觉基线：参考 `frontend/src/components/marketing/MarketingFrame.tsx` 与 `frontend/src/components/marketing/MarketingVisuals.tsx`
- 公开登录页入口：参考 `frontend/src/pages/login/LoginPage.tsx`、`frontend/src/components/login/LoginExperience.tsx`、`frontend/src/components/login/LoginWorkflowVisual.tsx`、`frontend/src/components/login/loginScene.ts`、`frontend/src/components/login/loginMath.ts` 与 `frontend/src/router/index.tsx`
- 登录页分级验证：参考 `frontend/package.json` 中的 `verify:login-fast / verify:login-responsive / verify:login-full`、`capture:login:matrix`、`frontend/scripts/login-live-check.mjs` 与 `frontend/src/pages/login/LoginPage.test.tsx`
- 顶层路由懒加载与统一 fallback：参考 `frontend/src/router/index.tsx` 与 `frontend/src/components/layout/LazyBoundary.tsx`
- 顶层前端 Provider 入口：参考 `frontend/src/main.tsx`（`PMFlowOsProvider` + `RouterProvider`）
- AI Steward tab 级懒加载入口：参考 `frontend/src/pages/ai-steward/AIStewardPage.tsx`
- AI Config section 级懒加载入口：参考 `frontend/src/pages/ai-config/AIConfigPage.tsx`
- 项目看板控制面/对话框懒加载入口：参考 `frontend/src/pages/project-board/ProjectBoardPage.tsx`
- 用户页对话框懒加载入口：参考 `frontend/src/pages/users/UsersPage.tsx`
- 图表二级 chunk 入口：参考 `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`
- Vite chunk 分组与 watch 忽略策略：参考 `frontend/vite.config.ts`
- Scheduler Center / Mounted AI Console：参考 `frontend/src/pages/scheduler-center/`
- SSTC 工作流组件：参考 `frontend/src/components/sstc/`
- Model Routing 页面：参考 `frontend/src/pages/model-routing-config/`
- MCP 模板接入页：参考 `frontend/src/pages/ai-config/mcp-config/`
- Route / Context 治理页：参考 `frontend/src/pages/query-route-governance/`
- Semantic facts 治理页：参考 `frontend/src/pages/semantic-facts-board/`
- MCP 前端 API：参考 `frontend/src/api/mcp.ts`
- Route / Context 治理前端 API：参考 `frontend/src/api/queryRouteGovernance.ts`
- Semantic facts 前端 API：参考 `frontend/src/api/semanticFacts.ts`
- AI Config 治理工具入口：参考 `frontend/src/pages/ai-config/constants.ts` 与 `frontend/src/router/index.tsx`

## 4. 模型与配置真源
- 模型配置唯一来源：参考 `backend/app/services/model/model_config.py`
- 路由规则真源：`backend/.control_plane/pmflow-routing-rules.json`
- Prompt 聚合：`backend/app/config/ai_prompts.py`
- Prompt 场景化分片：`backend/app/config/ai_prompts_catalog/`
- Prompt registry：`backend/app/config/ai_prompt_registry.py`
- External Query Planner Prompt：`backend/app/config/ai_prompts.py` 中的 `PROMPT_EXTERNAL_QUERY_PLAN`
- External Answer Presenter Prompts：`backend/app/config/ai_prompts.py` 中的 `PROMPT_EXTERNAL_DIRECT_FACT_QA`、`PROMPT_EXTERNAL_SUMMARY_WITH_SOURCES_QA`、`PROMPT_EXTERNAL_COMPARE_WITH_SOURCES_QA`
- 开发轻启动配置：参考 `backend/app/core/config.py`、`backend/app/main.py`、`backend/app/api/router.py` 与 `docker-compose.dev.yml`

## 5. 维护建议
- 新增接口时：先更新本文档，再同步 `API_CONTRACTS.md`
- 新增页面/关键入口时：同步本文档与 `ARCHITECTURE_INVENTORY.md`
- 若某条参考入口已经下线，应直接从本文档移除，不保留历史死链