112 lines
11 KiB
Markdown
112 lines
11 KiB
Markdown
# 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`
|
||
- 若某条参考入口已经下线，应直接从本文档移除，不保留历史死链
|