From 2d0fdd2c503a457ba71b01a47ddaf936ebca6282 Mon Sep 17 00:00:00 2001 From: zh Date: Thu, 24 Sep 2026 13:51:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20ADR-0008=20=E6=95=B0=E6=8D=AE=E5=BA=93?= =?UTF-8?q?=E5=BD=92=E5=B1=9E=E4=B8=8E=E5=AE=9E=E4=BE=8B=E6=8B=93=E6=89=91?= =?UTF-8?q?=E3=80=81=E5=B9=B3=E5=8F=B0=E4=B8=8E=E4=B8=9A=E5=8A=A1=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=E8=BE=B9=E7=95=8C=E3=80=81=E5=8D=95=E6=9C=BA=E7=89=88?= =?UTF-8?q?=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0008：库各自私有、允许共用实例、平台禁止直连 APS 库，并纠正「单机版」口径（客户端与平台服务同机，不含 APS）。新增 docs/spec/platform-vs-business.md 作为拆分判据（三分类 + 三个判据 + 四项已确认边界）。术语表修正 Pi 的描述（长驻子进程 + 扩展桥），补单机版/服务端版。实施设计 9.5 补进程创建时机：首次发消息时懒启动。 --- .../0008-database-ownership-and-topology.md | 46 +++++++++++++++++++ docs/adr/README.md | 1 + docs/glossary.md | 4 +- docs/implementation.md | 1 + docs/spec/platform-vs-business.md | 35 ++++++++++++++ 5 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0008-database-ownership-and-topology.md create mode 100644 docs/spec/platform-vs-business.md diff --git a/docs/adr/0008-database-ownership-and-topology.md b/docs/adr/0008-database-ownership-and-topology.md new file mode 100644 index 0000000..3a14bf1 --- /dev/null +++ b/docs/adr/0008-database-ownership-and-topology.md @@ -0,0 +1,46 @@ +# ADR-0008：数据库归属与实例拓扑 + +- **状态**：已接受 +- **日期**：2026-09-24 +- **决策人**：技术负责人 +- **相关**：任务表 A0（决策 D13）；设计文档《实施设计》1.5；ADR-0007 + +## 背景 + +ADR-0007 定了单机版用 SQLite、服务端版用 PostgreSQL，并留了一句「APS 侧数据库选型由 APS 自己定」。但它没回答三个问题：**库归谁、能不能共用一个 PostgreSQL 实例、怎么保证平台不越过 APS 直连它的库**。项目下一步既要拆数据库（B2）又要实现平台持久层（A3.7），不分清这三件事就会各写一半。 + +另有一处口径需要纠正：**「单机版」指客户端与平台服务在同一台机器上，不包含 APS。** APS 始终是独立系统——即使部署在同一台机器，也是独立进程、独立库、独立界面。 + +## 选项 + +| 选项 | 做法 | 代价 | 不选的理由 | +| --- | --- | --- | --- | +| A 各自私有库，可共用实例 | 平台库与 APS 库各自归属；开发期共用一个 PostgreSQL 实例的两个 database | 要账号与权限隔离，并加检查 | 选定 | +| B 单一共享库 | 两边的表放同一个库 | 运维最省事 | 破坏权威数据源边界：平台能读到甚至改到业务数据，门禁形同虚设 | +| C 强制不同实例 | 两边各起一个 PostgreSQL | 边界最清晰 | 单机与小型部署要维护两个数据库实例，成本不必要 | + +## 结论 + +选 A。 + +| 项 | 结论 | +| --- | --- | +| 库归属 | 平台库归平台，APS 库归 APS：各自迁移、各自备份、各自账号 | +| 库内容 | 平台 7 张（项目、会话、消息、文件、审计、待确认动作、桌面授权）；APS 6 张（主数据宽表、项目字典、工艺模板两表、排产执行与结果） | +| 实例拓扑 | 允许共用实例：开发期一个 PostgreSQL 跑两个 database；生产按部署拓扑定，不强制分离 | +| 访问规则 | **平台代码禁止直连 APS 库**，只能经 Provider 契约；反向同理，APS 不读平台库 | +| 隔离方式 | 不同 database + 不同账号；平台账号对 APS 库不授予任何权限 | +| 单机版 | 客户端 + 平台服务同机，平台库用 SQLite（ADR-0007）；APS 仍以独立系统部署，用自己的库 | +| 检查方式 | CI 扫描连接串、表名与跨库查询；出现平台侧访问 APS 表的代码即失败 | + +## 影响 + +- **对代码**：平台持久层只碰平台库；Provider 不接数据库，只调 APS 的接口 +- **对任务**：B2 按「平台 7 / APS 6」执行；A3.7 会话落库只建平台侧表；A1.6 增加跨库访问检查 +- **对文档**：术语表补「单机版 / 服务端版」定义；《实施设计》1.5 的权威数据源表以此为准 +- **不这么做的后果**：共用一张表会让平台绕过门禁读到业务数据，等 B2 之后想再拆就更贵 + +## 遗留 + +- CI 跨库检查的具体实现（正则扫连接串，还是 AST 级检查）在 A1.6 定 +- 生产是否分离实例：随部署拓扑在 A10 前后定，不影响代码 \ No newline at end of file diff --git a/docs/adr/README.md b/docs/adr/README.md index 7c4d4d0..3dc86a5 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -45,5 +45,6 @@ ADR 写完不再修改。要改结论就**新写一份**，并在两份里互相 | [0005](./0005-cutover-strategy.md) | 直接切换，不并行、不迁移 | 已接受 | 任务表 A0.9（决策 D7） | | [0006](./0006-engine-as-subprocess.md) | 引擎以长驻子进程运行 | 已接受 | 任务表 A3（决策 D10） | | [0007](./0007-storage-and-consistency.md) | 数据存储选型与双形态一致规则 | 已接受 | 任务表 A0（决策 D11） | +| [0008](./0008-database-ownership-and-topology.md) | 数据库归属与实例拓扑 | 已接受 | 任务表 A0（决策 D13） | 编号在写之前先在本表登记，避免多人并行时撞号。 diff --git a/docs/glossary.md b/docs/glossary.md index a92af10..8ca195d 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -11,8 +11,10 @@ | **平台服务** | 服务端进程：入口、应用服务、引擎适配、Core、Provider 接入 | 引擎在开发或部署期选定，服务端本身引擎中立 | | **应用服务** | 会话与任务编排、能力查询、确认流转、事件推送 | 不做业务规则，不替引擎判断 | | **Agent 引擎** | 驱动一轮智能体循环的实现，Pi 或 Codex 二选一 | 不等于平台，也不等于 Core | -| **Pi** | 进程内嵌入的 Node 库，工具由应用注册 | 核心不带工具，不带权限模型 | +| **Pi** | 以长驻子进程运行的引擎，平台用官方 RpcClient 驱动；工具由 Pi 侧扩展桥回调平台 | 不是进程内库；核心不带工具，不带权限模型 | | **Codex** | 以子进程驱动的引擎实现 | 自带 shell 与文件类工具，接入时必须关闭 | +| **单机版** | 客户端与平台服务在同一台机器上运行的部署形态（平台库用 SQLite） | **不包含 APS**：APS 始终是独立系统，即使同机部署也是独立进程、独立库、独立界面 | +| **服务端版** | 客户端连远端平台服务的部署形态（平台库用 PostgreSQL） | 与单机版共用同一套代码，只换存储实现与部署拓扑 | | **Core** | 平台控制面：身份、策略、确认、执行、审计五个模块 | 不是第二个智能体；不放业务规则与业务数据 | | **身份** | 平台用户到各业务系统账号的映射 | 不复制业务系统的角色与权限 | | **策略** | 用代码判断允许、拒绝或需确认 | 默认拒绝；每次执行前都查，不能只在展示工具列表时过滤 | diff --git a/docs/implementation.md b/docs/implementation.md index f1a8368..3ccee5b 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -494,6 +494,7 @@ Provider 先写适配器，再以包的形式安装和管理。开发步骤与 | 项 | 首版做法 | 原因 | | --- | --- | --- | +| 创建时机 | **首次发消息时懒启动**，不随平台启动预创建 | 建会话不需要引擎；懒启动让进程数跟着真实使用量走，避免为闲置会话养进程 | | 进程粒度 | **一个会话一个引擎进程** | 会话间不串状态，崩溃互不影响 | | 空闲回收 | A3.10 定：空闲时长与进程数上限 | 平台持有历史，进程随时可杀，下次按历史重建 | | 进程复用 | 首版不做 | Pi 支持会话切换、Codex 支持多线程；进程数成为负担时再评估 | diff --git a/docs/spec/platform-vs-business.md b/docs/spec/platform-vs-business.md new file mode 100644 index 0000000..805d872 --- /dev/null +++ b/docs/spec/platform-vs-business.md @@ -0,0 +1,35 @@ +# 平台基础能力与 APS 业务能力边界 + +> 用途：拆分判据。判断一段代码该放平台、放 APS，还是单独做成 Provider，看它落进哪一类；有争议时先改本文，再动代码。 + +## 判据（三个问题） + +1. **与具体业务系统无关吗？** 换掉 APS 换成别的业务系统，这段逻辑还要不要？要 → 平台基础。 +2. **它是业务事实的承载者吗？** 是不是「这家工厂的订单、工艺、排产结果」这类事实？是 → 业务系统。 +3. **它是与第三个系统的对接吗？** 是不是在跟 ERP / EMS / MES 打交道？是 → 独立 Provider。 + +## 三分类 + +| 分类 | 内容 | +| --- | --- | +| **平台基础** | 会话、消息、工作区、项目、附件与产物（数据管理）；能力目录与 Provider 契约；策略、确认卡、执行授权；审计；身份与租户映射；凭据代理；引擎适配与进程管理；协议 v1（HTTP / SSE）；客户端壳与桌面壳；Provider 套件管理与可视化宿主；跨系统顺序流程；文件导入骨架（profile 机制） | +| **APS 业务** | 求解引擎（CP-SAT / GA / NSGA2 / 池 / 规则）与求解进程隔离；柔性排产、能力池、交期承诺；订单、主数据、MRP；工厂日历与换型字典；工艺路线模板；排产执行与结果；世界状态、检查点、分支、数据包；排产校验器；SAGA 与闭环运行时；APS 自己的治理与审计；排产类报告内容 | +| **独立 Provider** | 与 ERP / EMS / MES / WMS / SAP 的对接。现在这些代码混在 `aps_domain` 里（`mes.py`、`sap_sync.py`、`wms_events.py`），B 线拆分时搬成各自的 Provider | + +## 已确认的边界项 + +| 项 | 归属 | 说明 | +| --- | --- | --- | +| 图纸与多模态 | 展示、上传、预览 → 平台基础；图纸解析成工艺信息 → APS | 2026-09-24 确认 | +| 知识库与 RAG | 检索能力 → 平台基础；工艺模板库 → APS | 工艺模板归 APS 见 D8 相关结论 | +| 报告 | 导出机制 → 平台基础；排产报告内容 → APS | 2026-09-24 确认 | +| 网格面板（`MeshPanel`） | 待查 | 需确认是开发调试用还是业务视图 | + +## 与决策的对应 + +| 决策 | 对本文的影响 | +| --- | --- | +| D8 | 平台 TS 从零重写；APS 保持 Python 搬迁适配 | +| D9 | 权限与协作归业务系统；平台不做转派、委托、多人计数、角色策略 | +| D12 | **APS 不内置对话智能体**：只保留「智能体接入点」契约，需要对话时由平台驱动 | +| D13 / ADR-0008 | 库各自私有：平台库归平台，APS 库归 APS，平台禁止直连 APS 库 | \ No newline at end of file