From 0a6152e419acdd6292086889c9a7c65488ad1685 Mon Sep 17 00:00:00 2001 From: zh Date: Thu, 24 Sep 2026 15:36:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20ADR-0010=EF=BC=88APS=20=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=9C=9F=E5=90=8C=E4=BB=93=E4=B8=8D=E5=90=8C=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=EF=BC=89+=20aps/=20=E9=AA=A8=E6=9E=B6=20+=20A1?= =?UTF-8?q?=E2=80=93A2=20=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0010：开发期 APS 放 aps/，独立工具链、独立 CI、独立库，唯一界面是 Provider 契约；写清迁出独立仓库的三个触发条件。架构设计第 2 节补开发期例外说明。新增 docs/plan/a1-a2-plan.md：A1.6 → A1.4 → A1.5 → A2.1 → A2.2 的串行计划与每步验收证据。 --- aps/README.md | 32 ++++++++++++++++++ docs/adr/0010-aps-dev-shape-in-repo.md | 47 ++++++++++++++++++++++++++ docs/adr/README.md | 1 + docs/architecture.md | 2 +- docs/plan/a1-a2-plan.md | 39 +++++++++++++++++++++ 5 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 aps/README.md create mode 100644 docs/adr/0010-aps-dev-shape-in-repo.md create mode 100644 docs/plan/a1-a2-plan.md diff --git a/aps/README.md b/aps/README.md new file mode 100644 index 0000000..51b8442 --- /dev/null +++ b/aps/README.md @@ -0,0 +1,32 @@ +# APS（独立业务系统 · 开发期同仓形态） + +> 本目录是 APS 的开发期落点，形态由 ADR-0010 规定：**同仓库、不同目录、独立系统**。 + +## 现状 + +APS 现在还在 `main` 分支里与平台混装（`server/aps_domain` 39,212 行、`server/engines` 7,551 行、`server/state`、`server/importers`，以及早期原型 `aps-frontend/`）。B0–B7 负责把它拆到这里并补齐独立运行所需的能力。 + +## 边界规则 + +| 规则 | 说明 | +| --- | --- | +| 工具链独立 | Python；不共享平台的 Node 依赖 | +| 不互相引用 | 平台代码不得引用 `aps/`；APS 不得引用平台 TS 代码 | +| 唯一界面 | Provider 契约（HTTP）；平台通过 `providers/aps` 的适配器调用 APS | +| 数据库独立 | APS 库归 APS（ADR-0008）：独立账号、独立 database | +| 交付独立 | APS 单独部署与升级（ADR-0009） | +| CI 分流 | 平台 job 与 APS job 互不阻塞 | + +## 要搬进来的东西 + +| 来源（`main`） | 内容 | 对应任务 | +| --- | --- | --- | +| `server/aps_domain` | 业务主体：排产、主数据、订单、柔性、闭环运行时、报告 | B1–B4 | +| `server/engines` | 求解引擎：CP-SAT / GA / NSGA2 / 池 / 规则 + 求解进程隔离 | B1 | +| `server/state` | 世界状态、检查点、分支、数据包 | B1 | +| `server/importers` | Excel / SQL / MOM 导入与 profile | B1 | +| `aps-frontend` 页面清单 | 界面外壳的范围参照（代码不搬） | B6 | + +## 迁出条件（ADR-0010） + +满足任一条即迁出独立仓库：APS 需要独立发版节奏、APS 由独立团队维护、平台包发布流程需要隔离权限。 \ No newline at end of file diff --git a/docs/adr/0010-aps-dev-shape-in-repo.md b/docs/adr/0010-aps-dev-shape-in-repo.md new file mode 100644 index 0000000..f63616c --- /dev/null +++ b/docs/adr/0010-aps-dev-shape-in-repo.md @@ -0,0 +1,47 @@ +# ADR-0010：APS 开发期与本仓库同仓不同目录 + +- **状态**：已接受 +- **日期**：2026-09-24 +- **决策人**：技术负责人 +- **相关**：任务表 B0；ADR-0008、ADR-0009；《架构设计》第 2 节 + +## 背景 + +《架构设计》第 2 节写的是「业务系统的代码不在这个仓库里」，ADR-0008/0009 也把 APS 当独立系统。但 APS 目前还在 `main` 分支里与平台混装，B0–B7 是把它拆出来的全过程。拆的过程中需要两个问题先有答案： + +1. 开发期 APS 放哪？立刻新建独立仓库，还是先在本仓库里隔离出一个目录？ +2. 这段过渡形态要不要写进 ADR，免得以后有人拿《架构设计》第 2 节说事？ + +## 选项 + +| 选项 | 做法 | 代价 | 不选的理由 | +| --- | --- | --- | --- | +| A 开发期同仓库 `aps/` 目录 | APS 代码放本仓库 `aps/`，独立工具链、独立 CI、独立库；迁出条件写进 ADR | 仓库体积与 clone 成本上升；边界靠规则而非物理隔离 | 选定 | +| B 立刻新建独立仓库 | B0 之前先建仓库、配权限、配 CI | 边界最干净 | APS 还有 39k 行在 `main` 里，没拆完就分仓会让搬迁与查证两头跑 | +| C 继续混装 | 不动结构 | 零成本 | 与 D8、ADR-0008/0009 全部冲突 | + +## 结论 + +选 A：**开发期 APS 放本仓库 `aps/` 目录**，按独立系统对待。 + +| 项 | 结论 | +| --- | --- | +| 目录 | `aps/`；工具链 Python，与平台（TS）不共享依赖 | +| 依赖规则 | 平台代码不得引用 `aps/`；APS 不得引用平台的 TS 代码。两侧唯一的界面是 Provider 契约（HTTP） | +| CI | 独立 job；平台的 lint / typecheck / test 不因 APS 失败而阻塞，反之亦然 | +| 数据库 | APS 库归 APS（ADR-0008），仍要求独立账号、独立 database | +| 交付 | 仍按 ADR-0009：首版只交付纯平台包，APS 单独部署 | +| 与架构设计的关系 | 《架构设计》第 2 节描述的是最终形态；本文定的是**开发期过渡形态** | +| 迁出条件 | 满足任一条即迁出独立仓库：① APS 需要独立发版节奏；② APS 由独立团队维护；③ 平台包发布流程需要隔离权限 | + +## 影响 + +- **对代码**：新增 `aps/` 目录；平台侧只在 `providers/aps` 里写适配器，不直接引用 `aps/` +- **对任务**：B0 的第一个产出物从「定仓库位置」改为「定 `aps/` 目录结构与迁出条件」；B1–B7 在 `aps/` 里做 +- **对文档**：《架构设计》第 2 节补一句开发期说明；术语表「业务系统」条目无需改 +- **不这么做的后果**：B0 卡在仓库创建上无法启动；或者继续混装，拆到一半两套工具链互相牵制 + +## 遗留 + +- 迁出时机的判断人：技术负责人；触发时按本 ADR 的迁出条件走 +- `aps/` 与 `platform` 的 CI 分流细节：A1.6 落地时一并写进工作流 \ No newline at end of file diff --git a/docs/adr/README.md b/docs/adr/README.md index 60818ea..7de96fe 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -47,5 +47,6 @@ ADR 写完不再修改。要改结论就**新写一份**，并在两份里互相 | [0007](./0007-storage-and-consistency.md) | 数据存储选型与双形态一致规则 | 已接受 | 任务表 A0（决策 D11） | | [0008](./0008-database-ownership-and-topology.md) | 数据库归属与实例拓扑 | 已接受 | 任务表 A0（决策 D13） | | [0009](./0009-delivery-shape.md) | 交付形态：纯平台包 + APS 单独部署 | 已接受 | 任务表 A0（决策 D14） | +| [0010](./0010-aps-dev-shape-in-repo.md) | APS 开发期与本仓库同仓不同目录 | 已接受 | 任务表 B0 | 编号在写之前先在本表登记，避免多人并行时撞号。 diff --git a/docs/architecture.md b/docs/architecture.md index 4661c77..28754f2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -88,7 +88,7 @@ flowchart TB # 2 项目结构 -一个 monorepo，按客户端与服务端两段组织。服务端是引擎中立的平台服务：应用服务、引擎适配、控制面、Provider 接口各归其位，引擎在适配层内部选定；客户端只通过一套接口与其通信。业务系统的代码不在这个仓库里。 +一个 monorepo，按客户端与服务端两段组织。服务端是引擎中立的平台服务：应用服务、引擎适配、控制面、Provider 接口各归其位，引擎在适配层内部选定；客户端只通过一套接口与其通信。业务系统的代码不在这个仓库里。（开发期例外：APS 暂放本仓库 `aps/` 目录，形态见 ADR-0010；迁出条件也写在里面。） ```text agent-platform/ diff --git a/docs/plan/a1-a2-plan.md b/docs/plan/a1-a2-plan.md new file mode 100644 index 0000000..d276ee6 --- /dev/null +++ b/docs/plan/a1-a2-plan.md @@ -0,0 +1,39 @@ +# A1–A2 串行实施计划（全自动执行） + +> 由技术负责人指定：串行推进、自动完成。每步都必须带可验证证据，做完即提交。 + +## 前置状态 + +| 项 | 状态 | +| --- | --- | +| A0 | 已完成：7 份 ADR（含 0008/0009/0010）、术语表、资产盘点 26 条、评审结论、两份设计文档入库 | +| A1 | 5/8：A1.1 骨架、A1.2 依赖方向检查、A1.3 server 最小闭环、A1.7 协议、A1.8 HTTP 契约 | +| 测试 | 21 条：契约 7 + 依赖方向 8 + 服务端冒烟 6（`pnpm test`） | + +## 步骤 + +| # | 任务 | 做什么 | 验收证据 | +| --- | --- | --- | --- | +| 1 | B0 前置 | `aps/` 目录 + ADR-0010（开发期同仓形态）+ 边界规则 | ADR 提交、目录说明 | +| 2 | A1.6 CI 基线 | eslint + prettier 基线、跨库访问检查、能力描述检查、APS/平台 CI 分流 | 本地 `pnpm lint` 通过；CI 工作流含全部检查 | +| 3 | A1.4 client 最小界面 | Vite + React 三栏骨架：左会话列表、中对话流（SSE）、右工作区占位；连接状态；用协议 v1 类型 | `pnpm --filter @aps/client-app build` 通过；服务端托管构建产物后能打开 | +| 4 | A1.5 一键启动 | `pnpm dev` 同时起服务端与前端；`pnpm start` 构建后单端口托管 | 实测两条命令可用；文档写清前置条件 | +| 5 | A2.1 Provider SDK | manifest / execute / status 接口 + 能力分级 + 错误分类 | 类型编译 + 契约测试 | +| 6 | A2.2 Core.invoke | 最小执行入口：幂等键、超时、执行记录、回执 | 单测：幂等重放、超时未知、错误分类 | +| 7 | A2.3/A2.4 | 内存假 Provider + 契约测试套件 | 契约套件对假 Provider 全绿 | +| 8 | A2.7 | 问法评测集跑通（假引擎） | 六项指标输出并记录 | + +## 纪律 + +1. 每步一个提交，提交信息写清任务号与证据 +2. `contracts/` 单点负责：本计划期间由主线改 +3. 每个新规则都要有会真失败的用例（依赖方向、契约漂移都已是这个标准） +4. 做完一步就更新任务表，不攒到最后 + +## 风险 + +| 风险 | 应对 | +| --- | --- | +| 前端引入 React/Vite 后 CI 变慢 | 只在 client 相关 job 跑构建；其余 job 不受影响 | +| eslint 首次接入报大量历史问题 | 当前代码是新的，问题量小；真有问题分文件修，不整体关闭规则 | +| A2.2 与 A3.1 的接口边界重叠 | A2.2 只做 `Core.invoke` 与执行记录；引擎接口归 A3.1，二者不互相引用 | \ No newline at end of file