aps-agent/docs/architecture/modules.md

# 可重生模块登记（REGEN）

> 与 `server/agent_core/registry.py` 的 `scan_modules()` 对齐（文件头 `moduleId: xxx, 可重生`）。  
> 增删改名带 `moduleId` 的模块 → **同轮**更新本表 + [`../CHANGELOG.md`](../CHANGELOG.md)。  
> UI 实时扫描来自 `/api/gov/modules`；本表补充「黄金测试 + 重生提示词要点」。

## 登记表（按层）

### agent-core

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| core-audit | server/agent_core/audit.py | test_m2_state | 链式哈希 prev+body → sha256；GENESIS |
| core-harness | server/agent_core/harness.py | test_gov_api | 封闭 _POWER_MAP；未登记默认 P3；一次性令牌 |
| core-intent | server/agent_core/intent.py | 间接 e2e | 正则快路 → LLM JSON 强校验降级 |
| core-providers | server/agent_core/providers.py | — | OpenAI 兼容；超时/非法降级 |
| core-registry | server/agent_core/registry.py | test_gov_api | 扫描 moduleId；剪枝 node_modules/dist 等 |
| server-agent-core | server/agent_core/__init__.py | — | 包声明 |

### domain

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| domain-orders | server/aps_domain/orders.py | test_order_management | 订单投影与 P2 写入纯领域逻辑；页面/对话共用 |
| domain-masterdata | server/aps_domain/masterdata.py | test_master_data | 资源树/物料BOM/日历维保投影 + 五个 master.* P2 写动作（产线/物料/维保/BOM明细/工艺步骤）；停用资源只标 INACTIVE 不物理删除 |
| domain-mrp | server/aps_domain/mrp.py | test_mrp | 订单分解：BOM 净需求→采购建议（前置期倒排）；外协步骤→委外建议；DRAFT 幂等替换 |
| domain-flex | server/aps_domain/flex.py | test_pool_engine | 柔性排产领域服务：能力池投影 + PoolEngine 触发（P1）+ 交期承诺模拟（沙盒）；只读/沙盒不碰主干 |
| domain-reports | server/aps_domain/reports.py | test_m3_knowledge | 冻结快照→模板；数字只取快照 |
| domain-scenario | server/aps_domain/scenario.py | test_m2_state | 深拷贝沙盒；永不碰主干 |
| domain-views | server/aps_domain/views.py | test_rule_engine | 甘特/负荷/交期/KPI 投影 |
| domain-workflow | server/aps_domain/workflow.py | test_m2_state | 意图→动作；P2 出卡；写前建档 |
| server-aps-domain | server/aps_domain/__init__.py | — | 包声明 |

### knowledge

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| server-knowledge | server/knowledge/__init__.py | — | 包导出 |
| knowledge-assets | server/knowledge/assets.py | test_m3_knowledge | JSON 资产库；同名版本递增 |
| knowledge-retrieval | server/knowledge/retrieval.py | test_m3_knowledge | bigram Dice+idf；命中必带出处 |
| knowledge-preferences | server/knowledge/preferences.py | test_m3_knowledge | 采用2分/试排1分；窗口200 |

### engine

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| engines-base | server/engines/base.py | test_rule_engine | ISchedulingEngine + EngineParams |
| engines-queries | server/engines/queries.py | test_rule_engine | 主数据只读查询 |
| engines-rule | server/engines/rule_engine.py | test_rule_engine | 策略排序→占槽；跨天；冲突只扫本版 |
| engines-pool | server/engines/pool_engine.py | test_pool_engine | 柔性：能力池选设备+虚拟产线组装+瓶颈锚；设备级占槽；模具换型/移动耗时 |
| server-engines | server/engines/__init__.py | test_rule_engine | CP/GA/HYBRID 占位走 RULE 留痕；导出 PoolEngine |

### state

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| server-state | server/state/__init__.py | — | 导出 |
| state-checkpoints | server/state/checkpoints.py | test_m2_state | 成对快照；容量淘汰；原子写 |
| state-seed | server/state/seed.py | test_rule_engine | 演示工厂；固定 Random(42) |
| state-store | server/state/store.py | test_m2_state | 单文件 JSON 原子写 |

### gateway / contract

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| gateway-app | server/gateway/app.py | test_gov_api | HTTP/SSE；P2 确认通道 |
| gateway-golden | server/gateway/golden.py | test_gov_api | pytest 子进程；run 须 to_thread |
| server-gateway | server/gateway/__init__.py | — | 包声明 |
| server-main | server/main.py | — | uvicorn 入口 |
| server-contracts | server/contracts.py | test_gov_api | 意图/UIBlock 封闭枚举 |
| server-root | server/__init__.py | — | 包声明 |
| server-timeutil | server/timeutil.py | test_rule_engine | 与 legacy 时间语义对齐 |

### ui（React）

| moduleId | 文件 | 黄金测试 | 重生提示词要点 |
| --- | --- | --- | --- |
| web-app | apps/web/src/App.tsx | 构建 | Shell；executeCommand 汇聚 |
| web-api-client | apps/web/src/api/client.ts | 构建 | REST + SSE |
| web-types | apps/web/src/api/types.ts | 构建 | 与 contracts 镜像 |
| web-chat | apps/web/src/chat/ChatPanel.tsx | 构建 | 确认卡/方案卡 |
| web-project-panel | apps/web/src/projects/ProjectPanel.tsx | 构建 | 项目树 |
| web-project-store | apps/web/src/projects/store.ts | 构建 | localStorage |
| web-project-types | apps/web/src/projects/types.ts | 构建 | 类型 |
| web-timeline | apps/web/src/timeline/TimelineRail.tsx | 构建 | 回滚口令合成 |
| web-viewport | apps/web/src/viewport/ViewportPanel.tsx | 构建 | 模式+KPI |
| web-gantt | apps/web/src/viewport/GanttView.tsx | 构建 | 甘特 |
| web-load | apps/web/src/viewport/LoadView.tsx | 构建 | 负荷 |
| web-due | apps/web/src/viewport/DueView.tsx | 构建 | 交期 |
| web-splitter | apps/web/src/shell/VSplitter.tsx | 构建 | 分隔条 |
| web-kebab | apps/web/src/shell/KebabMenu.tsx | 构建 | ⋯ 菜单 |
| web-dialog | apps/web/src/shell/AppDialog.tsx | 构建 | 应用内对话框 |
| web-gov-console | apps/web/src/gov/GovConsole.tsx | 构建 | 治理覆盖层 |
| web-orders | apps/web/src/orders/OrderPanel.tsx | 构建 + test_order_management | 订单列表/编辑器；写入动作只暂存确认卡 |
| web-master | apps/web/src/master/MasterPanel.tsx | 构建 + test_master_data | 主数据三页签（资源/物料BOM/日历维保）；复用订单面板骨架；写入只暂存确认卡 |
| web-cmd-palette | apps/web/src/shell/CommandPalette.tsx | 构建 | Ctrl+K |
| web-main | apps/web/src/main.tsx | 构建 | 入口 |
| web-styles | apps/web/src/styles.css | 构建 | 设计令牌 |

> `shared/schemas/*.json` 无 moduleId，由 contracts / web-types 双侧约束。

## 变更记录

| 日期 | 变更 |
| --- | --- |
| 2026-07-16 | 初版；M3 扩至 knowledge/reports |
| 2026-07-16 | 迁入 `architecture/modules.md` |
| 2026-07-16 | OR-01：登记 `domain-orders` / `web-orders`，黄金测试扩至订单管理 |
| 2026-07-16 | MD-01/02/03：登记 `domain-masterdata` / `web-master`，黄金测试扩至主数据 |
| 2026-07-16 | MRP：登记 `domain-mrp`；`web-orders` 扩分解建议视图；`web-master` 扩 BOM/路线编辑 |
| 2026-07-22 | 柔性排产：登记 `engines-pool` / `domain-flex`，黄金测试新增 `test_pool_engine`（9 项） |