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
• Query 路由网关与显式来源回复合同：参考 backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py
• 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 也在这里生成
• execution_recipe / fit_brief / external_recommendation / recommended_next_step / handoff_mode 回答接缝：参考 backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py、mixin_answer_mainline.py、mixin_answer_payload.py
• 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；当前实现为“结构化分析包 -> 受控改写 -> blocked-entity 校验”的两段式 presenter，相关 prompt 在 backend/app/config/ai_prompts_catalog/part_01.py
• 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/）
• 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

3. 前端参考

• 新增前端 API 调用：参考 frontend/src/api/sstc.ts
• 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 前端类型：参考 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
• 网页问答显式锚点与 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
• 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

5. 维护建议

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