docs(aps): B0.2 APS 边界清单与对平台的契约草案（含客户硬编码处置）

aps/README.md

@@ -48,6 +48,13 @@ uv run pytest -q
 | `server/importers` | Excel / SQL / MOM 导入与 profile | B1 |
 | `aps-frontend` 页面清单 | 界面外壳的范围参照（代码不搬） | B6 |
 
+## 文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [docs/boundary.md](./docs/boundary.md) | 边界清单（B0.2）：带走 / 留下 / 丢弃、反向依赖清单、客户硬编码处置 |
+| [docs/contract-draft.md](./docs/contract-draft.md) | 对平台的契约草案（B0.2 → B5 输入）：传输形状、只读能力清单、错误映射 |
+
 ## 迁出条件（ADR-0010）
 
 满足任一条即迁出独立仓库：APS 需要独立发版节奏、APS 由独立团队维护、平台包发布流程需要隔离权限。

aps/docs/boundary.md

@@ -0,0 +1,108 @@
+# APS 边界清单（B0.2）
+
+> 判据来自 `docs/spec/platform-vs-business.md`（三个问题：与具体业务系统无关吗 / 它是业务事实的承载者吗 / 它是与第三个系统的对接吗）。本文是拆分时的实际处置表，有争议先改 `platform-vs-business.md` 再改这里。
+
+## 0 结论摘要
+
+| 类别 | 规模 | 去向 |
+| --- | --- | --- |
+| 带走 | 83 文件 / 51,073 行 | 迁进 `aps/src/aps/`，成为独立系统 |
+| 留下 | 跨系统流程、对话、导入骨架、报告导出机制 | 平台已有或平台重写（不搬代码，只搬语义） |
+| 丢弃 | 客户专用入口、与平台重复的调度/工具运行时、早期前端原型 | 不迁移，旧分支归档 |
+
+## 1 实测口径（2026-09-30，`main` 分支）
+
+| 来源目录 | 文件 | 行数 | 去向 |
+| --- | --- | --- | --- |
+| `server/aps_domain` | 59 | 39,270 | `aps/src/aps/domain`（主体） |
+| `server/engines` | 11 | 7,562 | `aps/src/aps/engines` |
+| `server/state` | 8 | 2,714 | `aps/src/aps/state` |
+| `server/importers` | 5 | 1,527 | `aps/src/aps/importers` |
+| **合计** | **83** | **51,073** | — |
+
+行数为文件内换行符计数（`git show main:<file>` 逐文件统计），与 `wc -l` 同口径。
+
+## 2 三类清单
+
+### 2.1 带走（进 `aps/`）
+
+| 子包 | 主要来源 | 说明 |
+| --- | --- | --- |
+| `domain` | `scheduling_problem_v2` / `scheduling_validator` / `planning` / `mps_planning` / `mrp` / `orders` / `masterdata` / `master_query` / `inventory` / `changeover` / `sop_rules` / `flex` / `rush` / `forecast` / `scenario*` / `robustness` / `sensitivity` / `shadow_price` / `cp_*` / `supply_netting` / `sourcing` / `attribution` / `analytics` / `readiness` / `reports` / `views` / `scheduling_dto` / `trace` / `params` / `guidance` / `intake` / `importers`(APS 侧) | 排产、主数据、订单、交期、运行与结果——业务事实的承载者 |
+| `domain.closed_loop` | `closed_loop_runtime` / `closed_loop_problem` / `saga` / `adjust` / `conflicts` / `constraints` / `lns` / `explore_boundary` / `scene*` | 闭环与冲突消解；`saga` 去掉对平台运行时的引用后归 APS |
+| `domain.drawing` | `drawing_ai` / `drawing_dxf` / `drawing_pdf` / `drawing_process` / `drawing_understanding` / `dxf_drawing` / `multimodal` | 图纸解析成工艺信息归 APS；展示与上传归平台 |
+| `engines` | CP-SAT / GA / NSGA2 / 池 / 规则 / `external_engine` | 求解引擎与求解进程隔离；`external_engine` 去掉平台依赖 |
+| `state` | 世界状态、检查点、分支、数据包 | 排产过程的中间状态 |
+| `importers` | `excel_importer` / `sql_pack` / `profiles/*` / `mps_import` | 导入实现；profile 机制本身归平台 |
+| `governance`（新写） | 借鉴 `governance_rules` 的动作分级 + 平台审计的链式哈希 | B4 自己实现，不搬旧代码 |
+| `api`（新写） | 无 | B5 的契约化接口层 |
+
+### 2.2 留下（平台侧）
+
+| 项 | 为什么留 | 现状 |
+| --- | --- | --- |
+| 跨系统顺序流程（`workflow.py` 里的编排骨架） | 它同时碰 APS 与 ERP/MES，属跨系统流程，归平台 `server/workflows` | 平台侧已有目录与任务；APS 只保留业务步骤 |
+| 对话与意图（`kangni_intake.py` 的对话部分） | D12：APS 不内置对话智能体 | 平台已有 A3/A4；APS 只留「智能体接入点」契约 |
+| 导入骨架与 profile 机制 | 任何业务系统都要有导入入口，属平台基础能力 | 平台侧 `server` 已有导入骨架任务；APS 保留 profile 文件 |
+| 报告导出机制 | 导出成 PDF/Excel 的机制与业务无关 | 平台侧；APS 只产出报告内容 |
+| 项目/会话/权限/审计的通用模型 | 平台基础能力，见 `platform-vs-business.md` 三分类 | 平台已实现（A3/A4） |
+
+### 2.3 丢弃
+
+| 项 | 理由 |
+| --- | --- |
+| `kangni_intake.py` 的客户专用入口 | 客户专用入口被「平台对话 + 能力调用」取代；通用部分（主数据核对）归 `domain.masterdata` |
+| `folder_pack.py` 的目录打包/交付介质逻辑 | 是当时的交付手段，不是业务能力；其中与排产相关的部分已迁 `domain` |
+| 平台侧 `agent_core` 的重复实现（意图、工具运行时、调度） | 平台 TS 版从零重写（D8），旧 Python 实现只作借鉴 |
+| `aps-frontend/`（33 个页面的早期原型） | localStorage 原型，只作 B6 的页面范围参照，代码不搬 |
+
+### 2.4 待定（需要拍板）
+
+| 项 | 分歧点 | 建议 |
+| --- | --- | --- |
+| `mesh.py`（网格面板相关计算） | 是开发调试用还是业务视图 | 先留在 `main`，B6 做界面时按是否出现在业务页面决定 |
+| `external_engine.py` | 外部求解器是 APS 能力还是平台能力 | 归 APS：求解器是排产的核心手段，换业务系统就不成立（判据 1） |
+
+## 3 反向依赖处置（B3 输入）
+
+今日实测：APS 侧有 **17 个文件**引用平台 `agent_core`。
+
+| 目录 | 文件数 | 文件 |
+| --- | --- | --- |
+| `aps_domain` | 14 | `adjust` / `conflicts` / `constraints` / `flex` / `folder_pack` / `governance_rules` / `mes` / `mps_planning` / `multimodal` / `project_analyze` / `saga` / `sap_sync` / `wms_events` / `workflow`（`workflow` 命中 31 行，最重） |
+| `engines` | 2 | `external_engine` / `nsga2_engine` |
+| `importers` | 1 | `sql_pack` |
+
+处置分三类：
+
+| 用途 | 处置 |
+| --- | --- |
+| 审计与治理调用 | 换成 APS 自己的 `governance`（B4） |
+| 工具/能力注册 | 换成 `api` 层的能力声明（B5） |
+| 事件发布与运行时调度 | 换成 APS 自己的事件出口；跨系统的部分留给平台 |
+
+## 4 客户硬编码处置
+
+命中行数（`git grep -c`，2026-09-30 实测）：
+
+| 位置 | 命中行数 | 处置 |
+| --- | --- | --- |
+| `aps_domain/workflow.py` | 32 | 编排部分迁平台 `workflows`；业务步骤里的客户分支改成参数（工艺/日历/策略从项目设置读） |
+| `aps_domain/kangni_intake.py` | 33 | 整个文件丢弃（客户专用入口），通用逻辑并入 `domain.masterdata` |
+| `aps_domain/folder_pack.py` | 29 | 文件丢弃；相关排产逻辑已并入 `domain` |
+| `importers/excel_importer.py` | 4 | 改成读 profile，不判断客户 |
+| `importers/profiles/kangni.json` | 3 | 保留为 profile 示例，改名 `example.json` 并去掉客户字段 |
+| **合计** | **101** | 迁完后 `grep -i kangni` 在 `aps/` 里应为 0，由 CI 卡住 |
+
+> 与 A0 盘点时的 116 处（folder_pack 46 / kangni_intake 36 / workflow 36）差异来自统计口径：当时的数字是「出现次数」，本表是「命中行数」。
+
+## 5 与任务的对应
+
+| 任务 | 本清单的作用 |
+| --- | --- |
+| B1 网关分流 | 按 2.1/2.2 决定每段代码落哪一侧 |
+| B2 数据库拆分 | 见 ADR-0008 补记的 8 张平台表；APS 侧 6 张表随之进 `aps/` |
+| B3 解除双向引用 | 直接使用第 3 节的 17 个文件清单 |
+| B4 APS 治理 | 借鉴 `governance_rules` 的分级 + 链式哈希，代码新写 |
+| B5 契约化接口层 | 见 `contract-draft.md` |
+| B6 APS 界面 | 页面范围参照 `aps-frontend/` 的 33 个页面（代码不搬） |

aps/docs/contract-draft.md

@@ -0,0 +1,73 @@
+# APS 对平台的契约草案（B0.2 → B5 输入）
+
+> 两侧唯一的界面就是这份契约：平台通过 `providers/aps` 的适配器调它，APS 不 import 平台代码。首版**只读优先**——写能力先列出来定形状，实现放在 A6/B6 之后。
+>
+> 能力描述七要素见 `docs/spec/capability-description.md`（平台侧同一份规范）。
+
+## 1 传输形状
+
+| 项 | 约定 |
+| --- | --- |
+| 端点 | `POST /api/capabilities/{capabilityId}` |
+| 请求体 | `{ "params": {}, "executionId": "...", "idempotencyKey": "...", "deadlineAt": 0, "identity": { "accountId": "..." } }` |
+| 响应体 | 与平台 `contracts/schemas/receipt.schema.json` 的 `ExecutionReceipt` 同形：`{ executionId, status, result?, errorKind?, approvalId? }` |
+| 健康 | `GET /api/health` → `{ status: "ok"|"degraded"|"down", detail?, checkedAt }` |
+| 清单 | `GET /api/manifest` → `ProviderManifest`（id / displayName / version / platformVersion / requiresIdentity / auth / capabilities） |
+| 鉴权 | 服务间令牌 + 身份透传（`identity.accountId`）。**权限由 APS 自己校验**（D9：权限归业务系统），平台放行不代表 APS 放行 |
+| 超时 | `deadlineAt` 由平台给，APS 尽力遵守；超时不等于失败，平台按「结果未知」处理 |
+| 版本 | `platformVersion: 1`；能力 schema 只加不改，改语义换 capabilityId |
+
+## 2 只读能力（B5 首批实现）
+
+| capabilityId | 一句话用途（≤40 字） | effect | mode | 幂等 | 何时不用 | 同义词 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `aps.master.query` | 查物料、工序、设备等主数据 | read | sync | none | 要改主数据请用主数据维护流程 | 主数据、基础资料、物料表 |
+| `aps.orders.query` | 查订单与交期承诺状态 | read | sync | none | 要看排产结果用 `aps.schedule.query` | 订单、交期、承诺日期 |
+| `aps.capacity.query` | 查产能池与负荷分布 | read | sync | none | 要看某版方案的负荷用 `aps.schedule.query` | 产能、负荷、能力池 |
+| `aps.calendar.query` | 查工厂日历、班次与换型字典 | read | sync | none | 不用于查排产结果 | 日历、班次、换型、setup |
+| `aps.routing.query` | 查工艺路线模板与工序顺序 | read | sync | none | 图纸解析在 `aps.drawing.parse` | 工艺路线、工序、路线模板 |
+| `aps.schedule.query` | 查现有排产方案与执行结果 | read | sync | none | 要新算一版用 `aps.schedule.preview` | 排产结果、计划、方案 |
+| `aps.exceptions.query` | 查缺料、冲突与超期等异常 | read | sync | none | 要看某个订单细节用 `aps.orders.query` | 异常、冲突、缺料、超期 |
+
+参数 schema 一律：`{ "project": string(必填，默认当前项目), "filters": object(可选) }`，把枚举与单位写进描述；返回 `{ items: [], total: number, asOf: string }`（`asOf` 是数据时点，供界面显示"数据截至"）。
+
+## 3 草稿与写能力（形状先定，实现后置）
+
+| capabilityId | 用途 | effect | mode | 幂等 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `aps.schedule.preview` | 按当前数据试排一版，只出结果不发布 | draft | async | natural | 返回 `jobId`；结果进隔离草稿，不碰 APS 生产数据 |
+| `aps.schedule.publish` | 把指定版本方案发布到 APS | write | async | key | 必须带 `revision`（目标数据版本）；平台侧先出确认卡（A4.4） |
+| `aps.orders.upsert` | 新增或修改订单 | write | sync | key | 需要业务系统的写权限；平台不代替它判断 |
+| `aps.drawing.parse` | 把图纸解析成工艺信息 | draft | async | natural | 入参是平台上传后的文件引用，APS 不接收文件本身 |
+
+`draft` 与 `write` 的关键区别：`draft` 只写隔离草稿、不碰生产数据，因此不走确认卡；`write` 一律走确认卡（平台策略层已实现）。
+
+## 4 错误映射
+
+| APS 侧情况 | errorKind |
+| --- | --- |
+| 参数缺失、类型错、枚举越界 | `invalid_argument` |
+| 当前账号在该 APS 里没有这个权限 | `forbidden` |
+| 版本冲突、并发修改 | `conflict` |
+| 求解器等资源排队 | `rate_limited` |
+| APS 不可用、依赖系统不可用 | `unavailable` |
+| 超时、部分完成、无法判断 | `unknown_result` |
+
+只有 `rate_limited` 与 `unavailable` 允许平台自动重试；其余一律不重试（平台 Core 已按此实现）。
+
+## 5 与平台侧的对齐检查
+
+| 检查 | 方式 |
+| --- | --- |
+| 清单形状 | `GET /api/manifest` 的返回能通过平台 `ProviderManifest` 类型校验 |
+| 能力描述七要素 | 跑平台 `pnpm check:capabilities` 同一套规则（B5 时把规则提到契约里，两侧共用） |
+| 契约测试 | 平台 `runProviderContract` 对 APS 适配器跑一遍（A2.4 已实现） |
+| 只读验收 | A5.6 在真实 APS 上完成一次查询并留证 |
+
+## 6 待定
+
+| 项 | 说明 | 定的时机 |
+| --- | --- | --- |
+| 契约用 HTTP 还是进程内 | 首版 Provider 可跑在平台信任域内（实施设计 5），跨进程是外部团队接入的形态 | B5 实现时按部署形态定 |
+| `aps.schedule.preview` 的结果存放 | 方案结果落 APS 库还是平台产物区 | B5 |
+| 图纸文件引用形式 | 平台产物 id 还是 URL | 与 `drawing.parse` 一起定 |