Files

T

cjw 0e6b3b1811 后端设计治理：批次 0-4 全部完成（安全/部署/一致性/结构/架构）

按 ROADMAP §3.1 治理批次推进的后端设计审查整改：

- 批次 0（安全）：/api/status/{task_id} 补 JWT 鉴权与任务归属校验；
  pythonocc_available 真实探测；bcrypt 超 72 字节显式拒绝；
  SECRET_KEY/RUSTFS_* 惰性校验，代码侧弱默认移除
- 批次 1（部署正确性）：主处理链路改走 RustFS（分派入参 stp_file_id 化，
  worker 按 object_key 下载）；AUTO_MIGRATE 开关 + 迁移目录 alembic/→migrations/
  修复包遮蔽（自动迁移此前从未真正生效）；OCC 镜像改 conda 原生执行 +
  基础镜像 tag 锁定；compose 关键项改 ${VAR:?} 强制显式配置
- 批次 2（任务一致性）：删除 Redis 进程内存回退，PG 为任务状态单一事实源；
  批量元数据入库（processing_tasks.batch_id，迁移 a3f8c2d91e47）；
  型腔失败任务标 failed 不再静默 completed；事务边界收口
  （数据本体写 flush-only、失败先回滚再置 failed、进度更新保留即时 commit）
- 批次 3（API 与代码结构）：592 行 advanced_router 拆为 design/cost/machining/
  export 四子路由，请求体全量 Pydantic 化；ROUTE_MODULES + route_registry
  （/api/health 呈现 degraded，DEBUG fail fast）；纯计算端点统一 to_thread；
  StorageIntegrationService 按职责三拆；MAX_FILE_SIZE 接线生效、
  celery 复用 Settings.redis_url；管理员重置密码改 JSON body（端到端断裂修复）；
  openapi.json 重导出（76 paths）+ 前端 gen:api
- 批次 4（架构演进）：共享 ORM 按模块拆分（shared/models/base.py + identity.py、
  moldinsight/models/、inventory/models/，删除三条无使用方的跨模块
  relationship，跨模块桥接收敛为裸 FK 硬规则，无兼容 facade）；
  OCC executor 重建补 cancel_futures=True（消除旧队列被慢恢复线程
  并行消化的数据竞争）；OCC 吞吐方案设计先行
  （docs/topics/performance/OCC_THROUGHPUT.md）；顺手清偿 D15
  （vite.config.ts 未用参数致 npm run build 失败）

测试基线：125 passed, 2 skipped（pytest + sqlite+aiosqlite；归属边界、
路由契约、配置治理、鉴权回归等随批新增）
文档同步：STATUS / TECH_DEBT / ROADMAP / ARCHITECTURE / API_CONTRACT /
OPERATIONS / AGENTS

Co-Authored-By: Claude Code <noreply@anthropic.com>

2026-09-17 16:15:49 +08:00

7.2 KiB

Raw Blame History

geMoldInsight 架构与边界（ARCHITECTURE）

文档定位：当前架构、模块边界与结构原则的权威文档。本文描述“现在的系统结构是什么、边界如何划分、目标形态是什么”；不负责维护当前实现进度，当前状态见 STATUS.md，部署见 DEPLOYMENT.md，演进路线见 ROADMAP.md。如需追溯模块化设计蓝图与扩展讨论，见 archive/BACKEND_MODULARIZATION_BLUEPRINT.md。

1. 架构目标

geMoldInsight 的目标架构不是微服务，也不是继续维持历史单体，而是：

单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith

这意味着：

保持同一 Git 仓库
保持同一 PostgreSQL 数据库
按模块组织业务代码与部署入口
在不拆库、不拆仓的前提下，明确业务边界与部署边界

2. 当前模块划分

2.1 moldinsight

src/moldinsight/

职责：

STEP/STP 上传与任务管理
几何分析与特征识别
模具方案生成
批量分析
成本估算
导出与结果查询
结合 Celery 执行异步分析链路

2.2 inventory

src/inventory/

职责：

成品/物料管理
BOM 管理
库存与库存流水
采购订单 / 销售订单
财务与对账
采购建议推导

2.3 frontend

frontend/

职责：

模具分析页面
进销存页面
登录/用户管理
统一路由与状态管理
基于 OpenAPI 类型生成的前端调用

2.4 shared（当前平台层）

src/shared/

职责：

配置
数据库连接与 session
认证与权限
日志与 request_id
应用工厂与共用中间件

说明：

shared 当前仍是“共享平台层 + 历史耦合区”的混合体
后续会继续向更清晰的 platform 语义收敛，但当前仓库结构仍以 shared 为事实名称

3. 当前代码结构

当前核心结构如下：

geMoldInsight/
├── src/
│   ├── entrypoints/
│   │   ├── moldinsight.py
│   │   └── inventory.py
│   ├── shared/
│   ├── moldinsight/
│   ├── inventory/
│   ├── celery_app.py
│   └── celery_tasks.py
├── frontend/
├── migrations/
├── deploy/
├── docs/
└── tests/

这反映的是当前实际代码组织，不是历史单体结构。

4. 部署边界

当前设计上支持三种部署模式：

4.1 unified

一个统一后端同时承载 moldinsight + inventory，并作为前端默认反代目标。

适合：

本地开发
集成环境
小团队统一部署

4.2 moldinsight-only

只部署模具分析后端。

适合：

单独开放分析能力
异步任务与文件处理独立扩容

入口：

src/entrypoints/moldinsight.py

4.3 inventory-only

只部署进销存后端。

适合：

独立使用 ERP / 库存能力
与 moldinsight 分开部署节奏

入口：

src/entrypoints/inventory.py

部署操作与当前推荐方案见 DEPLOYMENT.md。

5. 关键架构原则

5.1 单数据库是刻意设计

项目不是把 moldinsight 与 inventory 强拆成两个数据库，而是保留共享数据库，以支撑完整业务闭环：

分析结果
创建成品
成品 BOM
销售 / 采购 / 库存

典型桥接关系示例：

STPFile.product_id -> Product.id

桥接只允许裸 FK 列（字符串表名），不允许跨模块 ORM relationship——单模块部署下另一模块的模型类可能未注册，跨模块 relationship 会让 mapper 配置直接失败（2026-09-17 批次 4 起为硬规则，原三条跨模块 relationship 均无使用方，已删除；对象化查询由使用方显式 select）。

5.2 模块边界优先于“临时方便”

新增逻辑时，应优先放入对应业务模块，而不是继续堆进 shared。

原则上：

moldinsight 业务进入 src/moldinsight/
inventory 业务进入 src/inventory/
只有真正跨模块复用的基础能力才进入 src/shared/

5.3 前端是独立工程，不是后端静态附属

前端已是独立 Vite/Vue 工程，部署上可与后端组合，但在代码组织上应视为独立模块，而不是后端 static/ 的扩展。

6. 当前主要耦合点

虽然模块化已经成型，但仍有几个关键耦合点需要持续关注：

6.1 共享 ORM 模型 —— 已按模块拆分（2026-09-17，批次 4）

历史上的 shared/models/database.py（31 个模型类三类同居）已拆除，现为按归属分置：

src/shared/models/base.py：唯一 Base + 归属约定与全量注册点说明
src/shared/models/identity.py：用户/角色/权限/审计（平台层，所有部署形态共用）
src/moldinsight/models/：STEP 分析域 9 表（stp_files 及各阶段产物、processing_tasks）
src/inventory/models/：进销存 15 表（catalog / warehouse / trading / finance 四域文件）

跨模块只允许裸 FK（规则见 §5.1）；全量模型注册点收敛为 migrations/env.py 与 tests/conftest.py；归属边界由 tests/test_model_ownership.py 锁定（含单模块独立 mapper 配置与旧模块无 facade 断言）。

6.2 app factory 组合职责偏重

当前 src/shared/app_factory.py 仍承担较多平台与模块组合职责，是后续平台层收敛的重点。

6.3 文档与结构尚未完全同步

代码结构已明显模块化，但历史文档中仍保留不少阶段性叙述、旧部署语义与重复说明，这也是本轮文档整理要解决的问题之一。

7. 专题文档与主骨架的关系

以下文档仍可作为专题补充参考，但不再承担默认入口职责：

存储方向：
- topics/storage/RUSTFS_STORAGE.md
- topics/storage/STORAGE_SETUP.md
性能方向：
- topics/performance/OCC_THROUGHPUT.md（OCC 吞吐与隔离方案设计，TECH_DEBT D10 归属）

AI、铝泡沫等更偏历史设计/规划性质的专题材料已迁入 archive/README.md。

阶段性任务清单、迁移计划、历史总结等文档会逐步迁入 archive/README.md。

8. 与相关文档的边界

想看“当前做到哪一步”：看 STATUS.md
想看“后面还要往哪演进”：看 ROADMAP.md
想看“当前有哪些活跃技术债”：看 TECH_DEBT.md
想看“配置怎么给、服务怎么起”：看 OPERATIONS.md
想看“前后端接口契约”：看 API_CONTRACT.md
想看“怎么部署”：看 DEPLOYMENT.md
想看“模块化蓝图与更完整设计讨论”：看 archive/BACKEND_MODULARIZATION_BLUEPRINT.md

7.2 KiB Raw Blame History Unescape Escape