aps-agent/docs/round-85-optimize-integration-shape-plan.md

# Round 85: optimize 集成形态计划

更新时间：2026-09-03

## 1. 本轮目标

将当前 `optimize` 的集成形态落定为 `aps-agent` 内部的 V2 原生排产求解器，并为下一轮实现定义清晰、可验证的边界。

本轮只完成架构和实施计划，不修改生产代码。下一轮实现应能让真实 MOM 数据经过 APS 既有闭环，由 optimize 求解，再通过 V2 校验并写回 APS 版本和审计记录。

## 2. 背景与当前状态

### aps-agent 现有主链

```text
/api/flex/schedule
  -> Harness P1 门禁
  -> workflow / run_flex_schedule
  -> MOM/world 同步、MRP 分解、来源标注
  -> closed_loop_problem
  -> SchedulingProblemV2
  -> solver
  -> SchedulingValidator
  -> 候选结果原子化物化
  -> WorldStore + audit
```

关键现有模块：

- `server/agent_core/harness.py`：权限等级和写入门禁
- `server/aps_domain/flex.py`：柔性排产入口和审计闭环
- `server/aps_domain/closed_loop_problem.py`：需求、BOM、供应和阻断建模
- `server/aps_domain/closed_loop_runtime.py`：V2 问题、求解、校验和物化
- `server/aps_domain/scheduling_problem_v2.py`：生产排产问题/结果契约
- `server/aps_domain/scheduling_validator.py`：独立 fail-closed 校验
- `server/engines/`：RULE、CP、HYBRID、GA、NSGA2、EXTERNAL 等引擎
- `server/importers/mom_pack.py`、`excel_importer.py`、`profiles/kangni.json`：现有 MOM/Kangni 导入
- `server/state/store.py`：WorldStore 唯一状态源

### optimize 现有能力

- Node 调度规则：EDD、SPT、PRIORITY、FIFO、LPT、CR、ATC
- Node CP-SAT 适配和独立结果认证
- Kangni/MOM 输入准入、manifest/hash、数据等级和阻断报告
- source-aware RAG、文档抽取、检索和 Python 数据流
- 既有 Node/Python 测试和 fixture

### 预检记录

- 目标仓库：`C:\Users\ssk\workspaces\aps-agent`
- 目标分支：`main`
- 轮次分支：`round/85-optimize-integration-shape`
- 轮次工作树：`C:\Users\ssk\worktrees\aps-agent-round-85-optimize-integration-shape`
- 基线 commit：`7f171f328d99974ff83eba1754b2fe669c7f9d15`
- 原始 `optimize` 工作树存在既有未提交/未跟踪改动，受保护，不自动带入本轮工作树
- `aps-agent` 轮次工作树当前干净

## 3. 已确认决策

任务重量：轻量。当前只有一个主集成方向，后续实现可由单 agent 在轮次工作树完成，不预先创建 worker worktree。

P0/P1 决策：

1. `optimize` 的最终身份是 V2 原生求解器。
2. 第一阶段直接进入生产 `closed-loop V2`，不建立 legacy 主链。
3. 第一轮纳入排产核心、APS 适配和 provenance；复用 aps-agent 已有 MOM/Kangni 导入；RAG 不在本轮重做。
4. APS WorldStore 是唯一权威状态源；optimize 不拥有订单、物料、资源或排产版本状态。
5. 成功标准包含真实 MOM 数据端到端验收；数据被 admission 阻断时必须准确报告阻断原因。
6. 排产核心迁移为 Python；Node 版本仅作为迁移期间的差分基线。
7. APS 与 optimize 直接使用完整 V2 问题/结果格式，不保留简化格式作为生产接口。
8. 七种规则和 CP-SAT 一起迁移；规则作为稳定基线，CP-SAT 处理复杂约束。

## 4. 集成形态

```text
APS WorldStore / MOM importer
  -> closed_loop_problem
  -> SchedulingProblemV2
  -> OptimizeEngine (Python)
      - dispatch rules: EDD/SPT/PRIORITY/FIFO/LPT/CR/ATC
      - CP-SAT adapter/certification
  -> SchedulingValidator
  -> closed_loop_runtime materialization
  -> APS schedule version / audit / evidence
```

optimize 只能产生候选排产解。Harness、Workflow、WorldStore、版本发布、确认卡、MES 写入和审计仍由 aps-agent 负责。

现有 MOM 导入直接复用，不创建第二套 `records` 主模型。optimize 当前 manifest/hash 能力只在必要处转换成 APS 的 source revision、problem hash、solverMeta 和 evidenceRefs。

## 5. 下一轮实现范围

### In scope

- 在 `server/engines/` 增加 Python `OptimizeEngine`，接入 `get_engine("OPTIMIZE")`。
- 将七种 dispatch 规则迁移到统一的 V2 求解输入和结果结构。
- 将当前 CP-SAT 认证规则迁移或接入 APS 现有 solver isolation/validator 边界。
- 将 `SchedulingProblemV2` 转成算法内部只读视图，并将结果转换成 `SchedulingSolutionV2`。
- 接入算法版本、随机种子、输入 hash、运行 ID、solverMeta 和 evidenceRefs。
- 复用现有 `server/importers/mom_pack.py` 和 Kangni world fixture，完成真实 MOM 闭环测试。
- 保留 Node 结果对照脚本或 fixture，验证迁移前后的算法关键指标一致性。

### Out of scope

- 不复制或重写 aps-agent 的 MOM/Kangni importer。
- 不创建第二套 WorldStore、订单模型、排产版本或冲突模型。
- 不迁移 optimize 的前端、独立 Gateway 或独立审批流程。
- 不在本轮重做 APS 已有 `server/knowledge/` 的知识资产、检索和权限平台。
- 不把 Node 运行时作为 APS 生产容器的必要依赖。
- 不在本轮扩展新的 GA、NSGA-II 或其他算法；先完成已确认的七种规则和 CP-SAT。

## 6. 实施任务与写入边界

本轮后续采用单 agent 轻量实现，所有写入只发生在轮次工作树。任务顺序如下：

1. **契约与引擎骨架**
   - 写入范围：`server/engines/`、必要的 `server/aps_domain/` 适配文件
   - 结果：`OptimizeEngine` 可被工厂选择，并明确 V2 输入/输出边界
   - 停止条件：发现 V2 字段不足以表达当前算法所需约束时，先回报，不绕过契约

2. **规则算法迁移**
   - 写入范围：`server/engines/` 下 optimize 专属实现和算法目录注册
   - 结果：七种规则在同一 V2 只读问题上运行，返回可校验的候选解
   - 停止条件：规则语义无法在 V2 中保持，或必须修改 WorldStore 才能运行

3. **CP-SAT 认证接入**
   - 写入范围：`server/engines/`、必要的 solver isolation 适配和测试
   - 结果：CP-SAT 结果带独立目标/完成时间检查，不声称未经证明的 optimal
   - 停止条件：需要改变现有 solver 子进程安全边界，或出现无法解释的目标不一致

4. **真实 MOM 闭环与差分验证**
   - 写入范围：`tests/golden/`、`tests/e2e/` 或明确的 round fixture；不修改原始 MOM 数据
   - 结果：真实 MOM world 能完成 admission、求解、V2 校验和版本物化；被阻断时有稳定 blocker
   - 停止条件：真实数据缺少业务前置条件，必须记录为数据阻断，不通过放宽校验解决

## 7. 成功标准

- `get_engine("OPTIMIZE")` 能稳定选择 Python OptimizeEngine。
- 七种规则和 CP-SAT 均使用 `SchedulingProblemV2`，不依赖旧简化生产接口。
- 结果必须通过 `SchedulingValidator`；非法结果不得写入 APS 生产版本。
- 真实 MOM 数据从 APS 现有 importer/world 进入闭环，产生以下之一：
  - 合法、可追溯的排产版本；或
  - 明确、可复现的 admission blocker。
- 版本中包含算法 ID/版本、problem hash、run ID、solverMeta 和 evidenceRefs。
- Node 对照结果用于发现迁移差异，但不参与生产写回。

## 8. 验证方式

下一轮至少执行：

- `pytest tests/golden/test_rule_engine.py tests/golden/test_cp_engine.py -q`
- 相关 `SchedulingProblemV2` / `scheduling_validator` golden tests
- 新增 `test_optimize_engine.py`：工厂选择、V2 字段、规则结果和非法结果拒绝
- 新增真实 MOM 闭环测试：导入或加载现有 MOM world -> `flex.schedule` -> blocker 或合法版本
- Node/Python 差分检查：同一固定输入的订单完成时间、总延迟、资源分配和状态语义
- 运行 `git diff --check`，确认没有无关文件和临时数据

真实数据门禁必须在集成点之前安排：先确认 MOM world 的 admission 状态，再判断求解器和物化结果。不能只在最终测试阶段才发现数据本身不可排。

## 9. 关键风险与控制

| 风险 | 影响 | 控制方式 |
|---|---|---|
| V2 与 optimize 旧模型字段不一致 | 迁移时丢失资源/物料/来源信息 | 先做只读 V2 adapter；缺字段时停下扩展契约，不静默丢弃 |
| 重复维护 MOM 输入模型 | 数据含义和 hash 漂移 | 复用 aps-agent importer/world，optimize 不写业务输入 |
| Node/Python 结果差异 | 迁移后业务行为变化 | 固定 fixture 做差分；记录算法版本、种子和时间语义 |
| 外部/不完整 MOM 数据被误判为算法失败 | 错误业务结论 | 保留 admission blocker，阻断时不物化版本 |
| CP-SAT 认证被绕过 | 产生虚假的 optimal/feasible 声明 | 统一经过现有 solver isolation 和独立 Validator |
| 迁移范围扩展到 RAG/UI/MES | 本轮失控 | 明确排除；通过现有接口接入，不改主流程 |

## 10. 停止条件

遇到以下情况暂停并回报，不继续扩大改动：

- 必须修改 WorldStore 的权威语义或审批/审计门禁才能接入。
- 需要引入第二套生产订单、物料、资源或版本数据源。
- V2 契约无法表达真实 MOM 约束，且无法通过局部兼容字段解决。
- 真实 MOM 数据的阻断原因尚未明确，却要求通过放宽校验让测试通过。
- Node/Python 差分出现未解释的完成时间、资源分配或可行性变化。
- 需要新增生产依赖、许可证或外部服务而没有明确运行环境。

## 11. 计划可行性检查

PLAN AUDIT: PASS

## 14. 本轮实施结果

- 已新增 `server/engines/optimize_engine.py`，并通过 `get_engine("OPTIMIZE")` 接入 APS。
- 七种派工规则（EDD/SPT/PRIORITY/FIFO/LPT/CR/ATC）共用 APS 的能力池、日历、班组、工装和物化逻辑；结果统一进入 `SchedulingSolutionV2` 校验。
- `/api/flex/schedule` 增加 `engine=OPTIMIZE`；Optimize 版本记录 `solverId`、`solverVersion`、`algorithmId`、`algorithmVersion`，并保留 V2 provenance 和 adapter assumption。
- 准入阻断时仍由 APS 记录零工单 DRAFT 版本，同时保留请求的引擎身份和 blocker，不绕过 admission。
- 新增 `tests/golden/test_optimize_engine.py`；Optimize/V2/算法注册表相关定向测试共 20 项通过，相关 APS 回归共 34 项通过。
- 当前 APS 轮次工作树未包含 `server/data/world-proj_712276ba.json`，因此真实 MOM world 用例只能按既有测试策略跳过；全量 CP/Excel 测试还受到当前环境 NumPy（X86_V2）二进制不兼容影响。CP-SAT 的 V2 原生求解器仍应作为后续轮次接入，本轮不把 PoolEngine 适配器冒充为 CP-SAT 最优证明。

阻塞问题：无。

检查结论：目标、写入范围、验收标准、验证命令、真实 MOM 门禁和停止条件均已明确；单 agent 任务没有并行写入冲突，也没有依赖未讨论的产品决策。

## 12. 目标分支合并前确认

本轮计划分支为 `round/85-optimize-integration-shape`，基于 `main`。后续实现、验证和自检通过后，主 agent 必须先报告：主要结论、关键洞察、仍需特别留意的风险和未覆盖环境，再请求用户确认是否合并到 `main`。未获得确认前，不合并目标分支。

## 13. 当前轮次完成定义

- 本计划文件已提交到轮次分支。
- 用户确认后才能进入目标模式实现；当前不修改生产代码。
- 实现完成后必须通过自身检查；如形成集成结果，补充统一集成审计和真实 MOM 验证。
- 轮次结束时保留计划、验证证据和未合并分支，直到用户明确决定是否合并。