# CPS 架构与设计文档

> 版本：2026-11-18（对应 53 份契约；最新功能与门禁见 CHANGELOG / BACKLOG）
> 读者：开发/运维/二次开发者。背景与决策过程见 [CPS_FEASIBILITY.md](./CPS_FEASIBILITY.md)（为什么）与 [CPS_ARCHITECTURE_ROADMAP.md](./CPS_ARCHITECTURE_ROADMAP.md)（演进路线）；本文只写"现在是什么、怎么设计的"。
> 上手操作见 [GETTING_STARTED.md](./GETTING_STARTED.md)；演示脚本见 [DEMO_SCRIPT.md](./DEMO_SCRIPT.md)。

---

## 1. 系统总览

CPS 是**通用数字孪生基础设施**：生产车间/产线第一优先，仓储同等支持。四部分完整系统，全部自有代码：

```
┌────────────────────────────────────────────────────────────────────┐
│ ① 设计器前端  apps/studio :5174（React 18 + R3F + Zustand + Vite）    │
│    双域编辑（2D 画布 + 3D 预览）· 校验面板 · 模板 · 布局库 · 运行视图    │
├────────────────────────────────────────────────────────────────────┤
│ ② 设计器后端  apps/design_server :8100（FastAPI）                    │
│    权威校验代理 · 试跑编排（进程树管理）· 服务器布局库 · demo fixture   │
├────────────────────────────────────────────────────────────────────┤
│ ③ 运行时引擎（后端权威，确定性）                                      │
│    apps/server :8000          ← warehouse_twin（仓储域，M1）         │
│    apps/factory_backend :8010 ← domain_factory（产线域，M3）         │
│    RunManager 会话化 · REST+WS · guard 防护                          │
├────────────────────────────────────────────────────────────────────┤
│ ④ 运行时渲染  studio 运行视图（M2/M4）                                │
│    仓储：FULL/PATCH(base_tick 链) + 六态连接 + LOCAL_DEMO 回放        │
│    产线：1Hz 快照 + 10Hz amr_patch + REST 控制                       │
├────────────────────────────────────────────────────────────────────┤
│ 横向件                                                              │
│  contracts/  Pydantic → JSON Schema(53) → TS 生成（--check 防漂移）   │
│  packages/twin_validator   布局权威校验（navgrid/A*/重叠/连通性）      │
│  services/data_gateway     数据接入/点表标定/前向推演（P3）            │
│  services/compute          推演进程隔离（spawn 池 + 线程回退）          │
│  services/observability    /metrics + 实时链路 SLO（事件循环/WS/网关） │
│  packages/domain_*         域引擎包（原样迁自上游，对拍护航）           │
└────────────────────────────────────────────────────────────────────┘
```

**持久化分层（2026-11-17 定位）**：运行时按环境选用两套后端，**SQLite 不移除**。

- **demo / 开发 / CI / 单租户试点**：SQLite 默认——`packages/auth/core.py`（`auth.db`）、`packages/auth/tenancy.py`（归属）、`services/data_gateway/calibration.py`（`calibration.db`）、`services/history/store.py`（`history-*.db`）、`warehouse_twin/db.py`（`twin-live.db`）。单文件、零依赖，是确定性对拍与"60 秒上手"的基础。
- **生产 / 多租户**：PostgreSQL 16——`CPS_AUTH_DSN` 使 `get_store()` 切到 `packages/auth/pg_store.py`（`PgAuthStore`），身份走 `cps_identity`（BYPASSRLS，主键点查）、审计走 `cps_tenant`（受 RLS + `set_config(app.tenant_id,…)`）；`CPS_HISTORY_DSN` 独立切时序后端。`packages/auth/pg_rls.py` 对 `users`/`control_audit`/`run_owners`/`calibrations` 四表 `ENABLE+FORCE RLS` + fail closed 谓词。
- **边界**：隔离第一道门始终是应用层 `tenant_id` 过滤（`tenancy.py`），RLS 是第二道；权威 run 在内存、`kpi_history` 无 tenant 列，不受 RLS。归属/校准/事件的运行时写入当前仍落 SQLite 卷，完整切库属触发式（见 DEPLOYMENT §0.6）。

**目录结构**（关键部分）：

```
CPS/
├── apps/
│   ├── studio/               # 设计器前端（src/ 下：doc/ state/ profiles/ components/ services/ factory3d/ templates/ validation/ util/ layout/）
│   ├── design_server/        # 设计器后端（main.py + tests/）
│   ├── server/               # 运行时入口（仓储域薄封装）
│   └── factory_backend/      # 产线运行时（main.py + guard.py）
├── packages/
│   ├── domain_warehouse/     # 仓储域引擎包（warehouse_twin/：sim/schema/ai/db/server/app）
│   ├── domain_factory/       # 产线域引擎包（engine/models/serialize/whatif/copilot/vision…）
│   ├── twin_runtime_core/    # 确定性内核（时钟/命名流 RNG/事件总线/审计）
│   └── twin_validator/       # 布局权威校验器（CLI：check / navgrid）
├── contracts/schemas/        # [生成] 53 份 JSON Schema
├── services/data_gateway/    # 数据网关（adapters/calibrate/forecast）
├── services/compute.py       # 推演进程隔离（spawn 池；失败显式回退线程）
├── services/observability/   # Prometheus 指标 + 实时 SLO 滚动窗口
├── scripts/                  # export_schemas.py / generate_types.mjs / github_push_api.py
├── config/                   # 产线运行参数（factory_layout.json + simulation_parameters.yaml）
├── docs/                     # 本文档体系
└── runtime/                  # 运行时产物（布局库/校验临时件/demo fixture；git 忽略）
```

---

## 2. 核心设计原则（六条，全部有测试/机制兜底）

| # | 原则 | 兜底机制 |
|---|---|---|
| P1 | **后端权威单引擎**：前端只渲染/编辑，永不仿真；断线 STALE 诚实降级 | 仓储/产线引擎只在 apps/server|factory_backend 进程；LOCAL_DEMO 回放=放数据帧（不含仿真规则） |
| P2 | **布局即唯一真相源**：layout JSON 同时驱动 2D/3D/导航/校验/引擎 | twin-validator 单一权威 + TS 预览件 golden 对拍（逐格一致专测） |
| P3 | **契约单向管道**：Pydantic → JSON Schema → TS；任何漂移 CI 失败 | `npm run contracts:check`；生成物手改即拦截 |
| P4 | **确定性可复现**：固定 tick + seeded PRNG + state 可序列化 | 双域对拍测试（同 seed → state_hash/state 逐字节一致） |
| P5 | **域 = profile 插件**：骨架（画布/命令栈/属性面板/运行视图框架）零域知识 | `profiles/registry`；新增域 = 新增 profiles/<domain> 包 |
| P6 | **编辑即命令**：一切修改产生可逆命令，undo 后 canonical 等价 | 54 项测试含命令可逆性断言（canonical JSON 相等） |

---

## 3. 设计器前端（apps/studio）设计

### 3.1 编辑文档模型（doc/）

**layout JSON 即文档**。`state/store.ts` 持模块级 `layout` 绑定（可整体替换）+ 两个版本号：

- `layoutVersion`：文档身份（打开/新建/模板生成时 +1）→ 3D 场景以 key 重挂（相机复位）
- `editVersion`：内容变化（每次命令落档 +1）→ 场景/面板据此重建 memo

**命令栈（doc/commands.ts）**：四类命令工厂——

| 命令 | 语义 | undo 实现 |
|---|---|---|
| placeCommand | 新放对象 | 删除该对象 |
| removeCommand | 批量删除 | 按原索引插回（保序） |
| mutateCommand | 字段级修改（before/after 快照） | 按 id 原位替换（数组顺序也还原） |
| rootMutateCommand | 布局根字段/参数对象（点路径） | 整对象快照恢复 |
| composite | 组合（复制/阵列/参数导入） | 逆序 undo |

栈深 200；`apply()`（执行+入栈）与 `pushApplied()`（拖拽等已执行动作只入栈）分离。

**布局工具（doc/edit.ts，域无关）**：集合读写（缺集合安全）、鸭子类型 aabbOf（rect/polygon/path/position+size/{x,z,width,depth}/cell/{x,z}）、hitTest（profile.hitPriority 优先序）、translateObject（同步 access_point/door 从属点）、rotateRack90（绕中心换边）、`alignmentAdjust`（边缘/中线对齐吸附，纯函数）、`assignIds`（`${prefix}-${n}` 全局唯一，跨集合查重）。

**canonicalize（doc/doc.ts）**：递归键排序序列化，**路径栈循环检测**（DAG 共享引用合法——与 JSON.stringify 同语义；生成器共享 access_point 数组的真实案例）。用途：`layout_hash`（WebCrypto SHA-256）、语义等价断言、存回自检。

### 3.2 Profile 体系（profiles/）——域插件接缝

```
DomainProfile {
  id, label
  kinds: ObjectKindDef[]        # 对象目录：type/label/color/gesture(point|rect|path)/
                                #   collection/idPrefix/create/fields/render2D/layer/visibility
  treeOrder, collectionLabels   # 对象树
  hitPriority                   # 2D 命中序（小对象在前）
  solidCollections              # 参与重叠校验的实体集合
  boundsOf                      # 画布坐标范围（仓储 0,0 起；产线负坐标）
  counts / createEmpty / sceneFields / underlay2D / renderFlows / hasNavGrid
}
```

- `profiles/warehouse`：13 类对象 + 字段表（含 glTF 绑定编辑）+ navgrid 预览
- `profiles/factory`：工艺单元/AMR 停靠点/家位与充电位/障碍点/工艺流向 + 场景设置（corridorZ/walkwayZ/floor 边界，rootMutateCommand）+ 参数编辑器 schema（paramsSchema.ts 动态展开 cells/buffers）
- `registry.ts`：`useProfile()` + `inferProfileId(layout)`（载入自动判域）
- **骨架无域知识**：MapView2D/ObjectsPanel/PropertiesPanel/App 只消费 ProfileDef

### 3.3 2D 编辑画布（components/views/MapView2D）

- 渲染分层：域 underlay2D → under 层 kind → navgrid 障碍格（preview-only，仅 warehouse）→ main 层 kind → 拓扑（renderFlows 箭头）→ 选中高亮 → 违例红框 → 框选 → 对齐辅助线 → 幽灵预览
- 手势：point（点击+十字吸附）/rect（拖拽+尺寸标注）/path（折线）；connect 工具（工艺流向，链式：上一步终点=下一步起点）
- 拖动：主锚点 0.5m 吸附 + alignmentAdjust 对齐修正（多选保相对偏移不做对齐）
- 坐标变换：`svg.getScreenCTM().inverse()`（负坐标域安全）；`window.cps.svgCtm()` dev 钩子供 e2e 换算

### 3.4 即时校验（validation/advisory.ts）与权威校验（twin_validator）

| 层 | 内容 | 时机 |
|---|---|---|
| 前端 advisory | 同集合实体重叠（**按楼层分组**）/越出画布（贴墙 0.5m 容差）/接入点被封（复用 navgrid 预览） | 每次编辑后即时 |
| Python 权威 | 越界/重叠（按楼层）/接入点按楼层可走/首台 spawn 全量 A* 连通性（仓储）；单元键唯一/坐标边界/走廊（产线） | 导出门禁 + `npm run validate` |

**产品规则：advisory 仅供参考，导出/试跑必过 Python 权威**（`/api/validate`，本地桥回退）。golden 对拍测试锁定 TS 与 Python 网格逐格一致（F1/F2）。

### 3.5 3D 渲染（components/scene/）

- **仓储**：前身仓储引擎 全套程序化资产（WarehouseShell 外壳/RackInstances InstancedMesh/Fixtures/Mezzanine 货梯/Robots 运行层）
- **产线**：CPS 全套道具（factory3d/ ~50 组件：Fence/CellSign/StackLight/Cnc/Booth/ConveyorStruct/DockBay/ChargingPad/ControlSpine/TruckTail/BufferSlots…）+ **真六轴 RobotArm**（J1~J6 关节、角速度限幅姿势逼近、焊枪/夹爪工具差、快照节拍外插）
- **glTF 资产管道（util/gltf.tsx）**：对象可选 `model: {gltf, scale, offset, rotateY}`；GLTFLoader 单例 + 模板缓存 clone 实例化（同资产多实例共享几何材质）；加载失败静默降级；属性面板可编辑路径/scale/rotateY。资产放 `public/assets/models/`
- 场景重建：`key={layoutVersion}-{editVersion}`（FactoryScene）/ `SceneContent` 订阅 editVersion（Scene3D）

---

## 4. 运行时引擎（packages/domain_* + apps/server|factory_backend）

### 4.1 仓储域（warehouse_twin）

- `sim/engine.py`：100ms 固定 tick；20 AMR（15 态 FSM）、2 货梯（联锁+OBB 避碰）、任务生成/可解释派工（5 权重）、LiDAR 感知、8 种故障注入、KPI；Mulberry32 位级 PRNG
- `server.py`：TwinServer（模拟循环/broadcast/patch diff/handle）+ GuardMiddleware（限流/Origin/body 上限）
- `app.py`：**RunManager 会话化**（多 run 并存、缺省 LIVE 兼容上游协议、REST/WS 可选 run 参数、`/api/runs`）
- wire 协议：FULL → PATCH（base_tick 链式，sim/robots 字段级/集合按 id diff/事件 prepend）+ RESYNC + HEATMAP
- 标定入口：引擎 state 即真源（gateway setPath 直写）；clone() 隔离副本供 what-if/forecast

### 4.2 产线域（domain_factory）

- `engine.py`：4 工艺单元（相位状态机）/守恒式断言/能耗账（per-asset 积分）/AMR 交通（让行/改道）/10 种故障
- `models.py` + `serialize.py`：WIRE_MODELS 6 个 → snapshot(1Hz 含 control.seq)/event(seq)/amr_patch(10Hz 变动字段)
- `apps/factory_backend`：ticker 推进 + 慢消费者踢除 + Reset 冻结旧 run（410 SUPERSEDED）
- 参数单一来源：`config/simulation_parameters.yaml`（parameter_hash 引擎自动算）

### 4.3 RunManager（apps/server，AD5）

多 run 并存（每 run 独立引擎/SQLite/连接组）；缺省 LIVE 保证协议兼容；`POST /api/runs` 显式建会话；gateway/forecast 端点同进程直连真 LIVE（`S(run).engine`）。

### 4.4 实时链路 SLO（services/observability）

引擎指标（tick 数、耗时）只回答“跑了多少拍”，不回答“主循环是否被卡住 /
WS 是否及时送达 / 数据源是否已经过期”。2026-10-21 补齐端到端观测：

- `realtime.py` 维护**无界样本数上限的滚动窗口**（事件循环延迟、WS 发送/广播、
  网关点延迟、推演耗时），`/api/slo` 用 p95/最坏值 + 阈值给出
  `ok|degraded|unknown`；无样本项是 `unknown`，不伪装成通过。
- 事件循环监控用 `loop.call_at()` 绝对时刻排下一拍：**卡顿本身会表现为采样晚到**，
  而不是“监控任务也被卡住 → 永远没有坏样本”。
- 指标走 `services/observability/__init__.py` 的集中声明；domain 包不直接 import
  services（AGENTS.md 分层纪律），由 app 层钩子注入（`TwinServer.on_ticks` /
  `on_ws_*` / `compute_runner`）。
- 网关在 `calibrate.poll_values/apply_values` 记录轮询耗时、质量码、点延迟与陈旧数；
  链路 DOWN 但保留上一批点时，陈旧本身可见（R5）。

### 4.5 推演进程隔离（services/compute.py）

what-if / forecast 默认在 `spawn` 进程池执行（`CPS_COMPUTE_ISOLATION=process`）。
**状态复制语义不变**：工厂 `dump_state()` + params，仓储 `clone()`；worker 不持有
LIVE 引擎引用。`thread` 是显式降级路径；进程基础设施失败自动回退线程，并通过
`compute.degraded_reason` / `cps_compute_fallbacks_total` 留痕。工厂场景编号在
**父进程**分配（`scenario_number`），避免 worker 各自从 1 开始导致 `SC-001` 重复；
仓储 what-if 的 progress 经 `multiprocessing.Manager` 队列回到主进程。
地点：`services/compute.py`、`packages/domain_factory/whatif.py::_next_number`、
`TwinServer.compute_runner`、`apps/factory_backend/aethon_bridge.py`。

---

## 5. 设计器后端（apps/design_server :8100）

| 端点 | 功能 |
|---|---|
| POST /api/validate | twin_validator 权威校验（双域自动识别；临时文件→CLI→报告） |
| POST /api/trial | 试跑编排：写契约文件（warehouse→domain_warehouse 包内布局；factory→CPS/config 双文件）→ spawn uvicorn（进程树登记）→ poll /api/health（60s）|
| POST /api/trial/stop | taskkill 进程树回收 |
| GET/POST/DELETE /api/layouts | 服务器布局库（runtime/layouts/ 文件持久化；localStorage 双写） |
| GET /api/demo/fixture | LOCAL_DEMO 回放（引擎预生成 3 分钟 1Hz 采样 ndjson；确定性专测） |
| GET /api/health | 自身健康 + 进程登记 |

前端 `services/designApi.ts` **双路径**：design-server 8100 优先 → Vite dev 桥（/__cps/*，同逻辑 dev-only）回退 → none 提示。

---

## 6. 运行视图（components/panels/RunView | FactoryRunView）

| | 仓储 RunView | 产线 FactoryRunView |
|---|---|---|
| 协议 | WS：FULL/PATCH(base_tick)/RESYNC | WS：1Hz snapshot + 10Hz amr_patch + event(seq)；REST 控制 |
| 连接态 | off/connecting/live/reconnecting/stale/demo（诚实六态；STALE 15s） | off/connecting/live/reconnecting/stale |
| 控制条 | ⏸▶ / 1~10× / ↺ RESET（WS SIM_CONTROL） | ⏸▶ / 0.5~5× / ↺（REST） |
| 视图 | KPI 六格 + 事件日志 + Scene3D+Robots（关节/感知/路径） | OEE/吞吐/能耗 KPI + 四单元卡（瓶颈标记）+ FactoryScene（CPS 道具 + RobotArm）+ 事件 |
| 场景几何 | 试跑后从引擎 `/api/layout` 拉取 loadDoc（**域不匹配自愈**） | 同左 |
| 本地演示 | ◐ 回放（fixture 数据帧循环，零仿真规则） | —（后置） |

数据绑定（GatewayPanel，顶栏入口）：数据源（simulated/file/rest）+ 点表 → **poll 标定**（字段级白名单 `robots.<ID>.battery|stats.*`、`sensors.*`——position/fsm/path 不开放）+ **影子偏差**（标定前引擎值 vs 外部值，dev_avg/dev_max）+ **前向推演曲线**（clone LIVE → horizon → KPI 采样 SVG）。

---

## 7. 契约与数据流

```
设计文档（studio doc）
  = layout JSON（warehouse 契约形 / factory 规范形）
  → 导出：warehouse 原样（即运行契约）/ factory 经 adapters.exportFactoryLayout
    （→ CPS factory_layout.json + simulation_parameters.yaml 双文件，往返不变量专测）
  → twin_validator check（导出门禁）
  → 试跑写入引擎目录 → 引擎加载（CPS 引擎按 key 取值，忽略未知字段 →
    model.gltf 等设计器扩展字段向后兼容）

运行数据流（仓储）：engine.step() → make_patch（字段级 diff）→ WS PATCH →
  run.ts applyPatch（robots {...prev,...patch}；集合按 id；null=删）→ store.twin →
  Scene3D/Robots 10Hz→60Hz 指数平滑
运行数据流（产线）：ticker(0.1s×speed) → event/amr_patch/1Hz snapshot →
  factoryStore（control.seq 单调）→ rftwinStore 同步 → RobotArm 姿态/CellSign 状态
```

`layout_hash`：canonical JSON SHA-256（前端 WebCrypto；文档切换/编辑防抖后重算，状态栏显示前 12 位）。

---

## 8. 确定性与对拍体系

| 对拍 | 断言 |
|---|---|
| M1 仓储 | 同 seed 同布局 600 tick（每 150 分段）state **逐字节一致**；RunManager 同步/会话语义 |
| M3 产线 | 源文件 sha256 与上游一致；同 config 同 seed 3600 tick **state_hash 一致**；异 seed 分岔 |
| golden | TS buildNavGrid vs Python navgrid F1/F2 **逐格一致**；双域样例权威校验通过 |
| 模板 | 4 形态 advisory 零违例 + **Python 权威校验含全量连通性** |
| LOCAL_DEMO | fixture 删缓存再生成**逐字节一致** |

`npm run ci` = contracts:check → validate（双域）→ test:parity（双域引擎）→ test:studio（54）。design-server 6 项（TestClient）与 twin_validator CLI 另行运行。

---

## 9. 扩展指南

**新增对象类型**（某域内）：profiles/<domain>/objects 里加 ObjectKindDef（create/fields/render2D/手势）→ 自动进对象库/属性面板/对象树；需要批量渲染性能时在对应 3D 场景加 InstancedMesh 分支。

**新增域**：新建 `profiles/<domain>/`（对象目录+字段表+boundsOf+counts+createEmpty[+render2D 资产]）→ registry 注册 → 推断函数加分支。骨架零改动（参照 factory 从零接入的完整先例）。

**新增数据源类型**：services/data_gateway/adapters.py 实现 DataAdapter（poll/close）→ create_adapter 注册。

**glTF 非标资产**：public/assets/models/ 放 `.glb` → 选中对象属性面板填路径（详见 assets/models/README.md）。约定：米制、Y 向上、原点底面中心。

**引擎行为修改**：domain_* 包内改 → 必须同步更新对拍基线（M1/M3 测试）或说明为何 hash 变化——对拍是行为偏移的唯一闸门。

---

## 10. 已知边界（诚实清单）

- 引擎内部 state 仍为裸 dict；产线 dump/load 已由 `domain_factory/state_registry.py` 声明式 table 驱动（AD6 完成，黄金零差异），仓储侧仍为手工枚举
- 产线下钻视图有限：Flow/Energy 高级视图未内化（后端 API 可用）；LOCAL_DEMO 确定性回放已做（`studio/src/services/factoryRun.ts`）
- 仿真假设为演示级（非真实工业标准值）；视觉为程序化示意级（glTF 可补非标设备）
- ~~TimescaleDB 历史层、OPC UA/Modbus/MQTT 适配器、影子并行引擎~~：**已完成**
  （P3.5~P3.7：`services/history/`、`services/data_gateway/adapters.py`、`shadow.py`；
  见 `docs/PRD.md` RF03/RF06 状态与 `docs/BACKLOG.md` 执行日志）；**BIM/IFC 仍未做**（接口已留）
- 实时性边界：仿真时钟固定 tick 驱动，默认 `shift` 锚（确定性对拍），`wall` 锚
  （`CPS_CLOCK_ANCHOR=wall`）把当前 tick 贴到墙钟现在；「倍速/追赶/实时因子/丢拍计数」
  已实现（2026-10-19，见 `docs/audit/CPS_REALTIME_DT_GAPS_2026-10-19.md`）。
  **北向接口（OPC UA Server）已实现**（R6，默认关、只读、端点默认只绑本机）；
  已知边界是 asyncua 1.1.8 与 Python 3.14 不兼容，服务端按 fail-closed 拒绝建树
  （`/api/northbound/status` 报告原因）。**BIM/IFC、多副本实时 SLO 仍未做**
- git 直连（SSH）在本环境可用；早期网络受限时曾用 `scripts/github_push_api.py`（REST Git 数据端点）替代
