63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# 数据库层（SQLite 主数据 + world 投影）
|
||
|
||
> M-A 落地：主数据不再写死在代码里，康尼只是数据库里的一个「项目」。
|
||
> 代码：`server/db/`（models / database / sync）、`server/state/packs.py`、`server/importers/`。
|
||
|
||
## 定位
|
||
|
||
- **SQLite（`server/data/master.db`，`APS_DB_PATH` 可覆盖）**：主数据的持久源——项目、
|
||
主数据宽表（资源/物料/BOM/工序/路线/订单/柔性表）、行业工艺路线模板。
|
||
- **world.json**：排产运行态（版本/工单/冲突/检查点/审计）仍留在 `WorldStore`；
|
||
引擎零改动，读的还是 world dict。
|
||
- **knowledge.json + embeddings.json**：RAG 知识库（见 [rag.md](./rag.md)）。
|
||
|
||
## 表结构（`server/db/models.py`，SQLAlchemy 2.0）
|
||
|
||
| 表 | 作用 |
|
||
| --- | --- |
|
||
| `projects` | 项目/租户（demo、kangni…），`is_active` 标记当前投影项目 |
|
||
| `master_records` | 通用宽表：`(project_id, table_key, seq)` + `code/name` 索引列 + `payload` JSON 全量；`table_key` 覆盖 `factories/materials/flexOrders/routingSteps/...`（清单见 `sync.MASTER_LIST_KEYS`） |
|
||
| `project_settings` | dict 型主数据（`factoryCalendar/changeoverMatrix/...`，见 `MASTER_DICT_KEYS`） |
|
||
| `routing_templates` / `routing_template_steps` | 行业工艺路线模板库（M-E，含推荐工时区间/设备类型/知识资产关联） |
|
||
|
||
宽表设计的取舍：world 的主数据形态仍在快速演进，`payload` 存整行 JSON、
|
||
`code/name/seq` 提列做索引，避免每加一个字段就迁 schema；引擎兼容性优先。
|
||
|
||
## 投影与同步（`server/db/sync.py` + `state/store.py`）
|
||
|
||
```
|
||
启动: WorldStore.__init__ → _sync_with_db()
|
||
DB 有主数据 → db_to_world() 覆盖 world 主数据键（DB 为准）
|
||
DB 空 world 有 → world_to_db() 一次性迁移（保留现场已导入数据）
|
||
写入: store.save() → _sync_master_to_db()（master_fingerprint 脏检查，变了才写）
|
||
```
|
||
|
||
- `set_active_project(code)` 切换活跃项目；`db_to_world` 只投影该项目数据。
|
||
- `APS_DB_DISABLED=1` 完全绕过 DB（测试/降级）；DB 异常不阻断 world 主流程。
|
||
|
||
## 数据包（`server/state/packs.py`）
|
||
|
||
- `export_pack(world, name)` → `server/data/packs/<name>.json`（记录 `baseDate`）。
|
||
- `load_pack(name)` 重放时把所有日期按 `baseDate→今天` 平移（演示数据永不过期）。
|
||
- `seed_world()`：`APS_SEED_PACK` 指定则重放数据包，否则 `build_demo_world()` 程序化种子。
|
||
- `scripts/generate_demo_pack.py` 重新生成 `demo.json`。
|
||
|
||
## 导入器配置化（`server/importers/`）
|
||
|
||
- `excel_importer.import_site_excel(profile_name, path)`：按 profile 解析现场 Excel → 入库 → 投影。
|
||
- `profiles/kangni.json`：工厂名、区域、工时推断规则（部装 45/装配 30…）、换型/接刀默认、
|
||
班组、日历——原 `kangni_intake.py` 的硬编码全部搬进配置；解析函数吃 profile 参数。
|
||
- 新客户 = 新增一个 profile JSON，不改代码。
|
||
|
||
## API
|
||
|
||
| 端点 | 用途 |
|
||
| --- | --- |
|
||
| `GET /api/projects` | 项目清单 + 活跃项目（P0） |
|
||
| `GET /api/packs` | 可重放数据包清单（P0） |
|
||
|
||
## 测试
|
||
|
||
`tests/golden/test_db_projection.py`（入库→投影→PoolEngine 可排、多项目隔离、数据包日期平移）、
|
||
`test_excel_importer.py`（profile 等价性 + 覆写生效 + stdTimeSource 标记）。
|