PMFlow/docs/architecture/ARCHITECTURE_INVENTORY.md

# ARCHITECTURE INVENTORY

## 1. 目的
- 本文档承接 PMFlow 的架构库存与关键入口索引。
- `CLAUDE.md` 保留当前架构说明、运行边界和参考模式。
- 本文档记录当前模块分布、重要子包、关键脚本与前端页面分组，后续架构变更统一在此同步。

## 2. 同步规则
- 任何影响目录结构、主入口、模块归属、前后端页面/API 分组、脚本布局的架构变更，都必须同步更新：
  - `CLAUDE.md`
  - `docs/architecture/ARCHITECTURE_INVENTORY.md`
- API/Schema 契约变更仍需同步：
  - `docs/architecture/API_CONTRACTS.md`
  - 对应前端 `types/api` 封装
- 路由/函数名/运行时流向变更仍需同步：
  - `docs/architecture/DATAFLOW.md`
  - `backend/.openclaw/pmflow-routing-rules.json`

## 3. 顶层库存
- `docs/INBOX_INLINE_OPS_3_PHASE_CHECKLIST.md`：消息台内联操作执行清单
- `docs/architecture/MASTER_CONTRACT.md`：跨栈主契约
- `docs/architecture/CODE_REFERENCE_INDEX.md`：新增代码参考入口与高频代码索引
- `docs/architecture/RUNTIME_GUARDRAILS.md`：运行边界、守门规则与已知运行假设
- `docs/architecture/API_CONTRACTS.md`：接口/Schema 契约
- `docs/architecture/DATAFLOW.md`：主链与数据流说明
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`：任务包模板
- `docs/superpowers/plans/`：实现计划
- `docs/task_briefs/`：任务包产物与验收截图

## 4. 后端库存

### 4.1 API 路由分组
- `backend/app/api/ai_steward_api/`
- `backend/app/api/ai_pmo_api/`
- `backend/app/api/feishu_api/`
- `backend/app/api/rag_api/`
- `backend/app/api/sstc_api/`
- `backend/app/api/signals_api/`
- `backend/app/api/signal_sources_api/`
- `backend/app/api/skill_tags_api/`
- `backend/app/api/ai_logs_api/`

### 4.2 AI PMO 与语义主链
- `backend/app/services/ai_pmo/ai_pmo_kernel/`
- `backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/`
- `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/`
- `backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/`
- `backend/app/services/ai_pmo/semantic_context/`
- `backend/app/services/ai_pmo/workflow_semantic_planner/`
- `backend/app/services/ai_pmo/draft_confirm_handler.py`

### 4.3 问答、模型与生成
- `backend/app/services/adaptive_rag_service/`
- `backend/app/services/llm_service/`
- `backend/app/services/ai_steward_service/`
- `backend/app/services/feedback_center/`
- `backend/app/services/task_brief_service.py`
- `backend/app/config/ai_prompts.py`
- `backend/app/config/ai_prompts_catalog/`
- `backend/app/config/ai_prompt_registry.py`
- `backend/app/services/model/model_routing/service.py`
- `backend/app/services/model/model_config.py`

### 4.4 集成、信号与运行时
- `backend/app/services/integrations/feishu_integration_service/`
- `backend/app/services/integrations/feishu_outbox/service.py`
- `backend/app/services/integrations/feishu_signal_pipeline/`
- `backend/app/services/signal/signal_capture_service/`
- `backend/app/services/signal/signal_source_orchestration/`
- `backend/app/services/signal/signal_source_repair/`
- `backend/app/services/signal/signal_planner/`
- `backend/app/services/signal/draft_generator_service.py`
- `backend/app/core/startup/`
- `backend/app/utils/thread_context.py`
- `backend/app/utils/timezone.py`
- `backend/app/utils/audited_write.py`
- `backend/alembic/versions/`

### 4.5 Mounted Runtime / 训练相关
- `backend/app/models/reply_iteration.py`
- `backend/app/models/training_pipeline.py`
- `backend/app/models/mounted_ai_runtime.py`
- `backend/app/api/ai_steward_api/routes_reply_iteration.py`
- `backend/app/api/ai_steward_api/routes_training_pipeline.py`
- `backend/app/api/ai_steward_api/routes_mounted_ai.py`

### 4.6 结构归并结果
- `backend/app/services/` 根目录已目录化收敛，新增服务优先进入对应子包。
- API canonical 入口优先使用 `*_api/` 子包，不再优先引用顶层兼容壳。
- 运行时业务动作归因优先走“对象/上下文绑定 -> `SemanticContextPacket` -> `SemanticDecision` -> gatekeeper”。
- `backend/tests/test_runtime_structured_semantics_contract.py` 与 `backend/tests/test_feishu_pipeline_queue_contract.py` 共同守门 runtime 结构化语义收口，锁定飞书入口、signal capture、reply/runtime routing 不得回流旧词法拍板 helper。

## 5. 前端库存

### 5.1 页面分组
- `frontend/src/pages/inbox/`
- `frontend/src/pages/ai-steward/`
- `frontend/src/pages/scheduler-center/`
- `frontend/src/pages/project-board/`
- `frontend/src/pages/projects/`
- `frontend/src/pages/users/`
- `frontend/src/pages/recipes/`
- `frontend/src/pages/feishu-config/`
- `frontend/src/pages/ai-config/`
- `frontend/src/pages/model-routing-config/`
- `frontend/src/pages/task-brief-center/`
- `frontend/src/pages/task-brief-runs/`
- `frontend/src/pages/task-brief-template/`
- `frontend/src/pages/charter-detail/`
- `frontend/src/pages/contract-sync-board/`
- `frontend/src/pages/dashboard/`
- `frontend/src/pages/knowledge-graph-context-board/`
- `frontend/src/pages/login/`
- `frontend/src/pages/skill-tasks/`
- `frontend/src/pages/skills/`
- `frontend/src/pages/user-profile/`
- `frontend/src/pages/user-skills/`
- `frontend/src/pages/workload-detail/`
- `frontend/src/pages/workloads/`

### 5.2 API 与共享模块
- `frontend/src/api/aiPmo.ts`
- `frontend/src/api/aiSteward.ts`
- `frontend/src/api/taskBriefs.ts`
- `frontend/src/api/modelRouting.ts`
- `frontend/src/api/knowledgeGraph.ts`
- `frontend/src/api/mountedAi.ts`
- `frontend/src/api/feedbackCenter.ts`
- `frontend/src/api/sstc.ts`
- `frontend/src/components/inbox/`
- `frontend/src/components/sstc/`
- `frontend/src/pages/scheduler-center/components/`
- `frontend/src/pages/ai-steward/components/`
- `frontend/src/lib/`

### 5.3 前端结构边界
- 页面级编排逻辑优先收敛到 `pages/*/` 子目录。
- API 调用统一走 `frontend/src/api/`，不在页面或组件内直接 `fetch`。
- `frontend/src/components/sstc/` 继续作为 SSTC 共享组件目录维护。

## 6. 工具与运行库存
- `backend/scripts/repair_requirement_plan_history.py`
- `scripts/start_model_probe.sh`
- `scripts/model_probe.py`
- `scripts/gen_task_brief.sh`
- `scripts/check_contract_sync.sh`
- `frontend/playwright.config.ts`
- `frontend/e2e/feishu-project-full-flow.spec.ts`

## 7. 维护建议
- 想看“现在怎么跑、边界怎么定”：先看 `AGENTS.md`，再看 `CLAUDE.md`
- 想看“模块都搬到哪里了、目录怎么分组”：看本文档
- 想看“接口/数据流契约”：看 `docs/architecture/API_CONTRACTS.md` 与 `docs/architecture/DATAFLOW.md`