8.3 KiB
geMoldInsight 架构与边界（ARCHITECTURE）
文档定位：当前架构、模块边界与结构原则的权威文档。 本文描述“现在的系统结构是什么、边界如何划分、目标形态是什么”；不负责维护当前实现进度，当前状态见 STATUS.md，部署见 DEPLOYMENT.md，演进路线见 ROADMAP.md。 如需追溯模块化设计蓝图与扩展讨论，见 archive/BACKEND_MODULARIZATION_BLUEPRINT.md。
1. 架构目标
geMoldInsight 的目标架构不是微服务，也不是继续维持历史单体，而是：
单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith
这意味着：
- 保持同一 Git 仓库
- 保持同一 PostgreSQL 数据库
- 按模块组织业务代码与部署入口
- 在不拆库、不拆仓的前提下，明确业务边界与部署边界
2. 当前模块划分
2.1 moldinsight
目录：
职责：
- STEP/STP 上传与任务管理
- 几何分析与特征识别
- 模具方案生成
- 批量分析
- 成本估算
- 导出与结果查询
- 结合 Celery 执行异步分析链路
2.2 inventory
目录：
职责：
- 成品/物料管理
- BOM 管理
- 库存与库存流水
- 采购订单 / 销售订单
- 财务与对账
- 采购建议推导
2.3 frontend
目录：
职责：
- 模具分析页面
- 进销存页面
- 登录/用户管理
- 统一路由与状态管理
- 基于 OpenAPI 类型生成的前端调用
2.4 shared（当前平台层）
目录：
职责：
- 配置
- 数据库连接与 session
- 认证与权限
- 日志与 request_id
- 应用工厂与共用中间件
说明：
shared的定位已明确为平台层（跨模块基础能力）；模块专属接线（RustFS 启动 / HTML 报告挂载 / 路由聚合）已收敛回模块层（见 §6.2），当前仓库结构仍以shared为事实名称- 剩余语义收敛（identity 平台表 vs 模块表的命名与注释口径）随实际重构继续推进
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
只部署模具分析后端。
适合：
- 单独开放分析能力
- 异步任务与文件处理独立扩容
入口：
4.3 inventory-only
只部署进销存后端。
适合：
- 独立使用 ERP / 库存能力
- 与 moldinsight 分开部署节奏
入口：
部署操作与当前推荐方案见 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 组合职责 —— 已收敛（2026-09-18，D3 剩余）
平台层与模块专属接线的边界已明确（shared = 跨模块基础能力，模块专属接线归属模块层）：
- 平台工厂 src/shared/app_factory.py 只做纯平台引导：CORS / 请求日志 / 目录准备 / 静态托管 / 数据库与 Redis 启动 / auth 路由 / /health / SPA fallback。
startup_hooks参数承载模块专属启动接线——原connect_rustfs参数（平台工厂持有 moldinsight 依赖）已移除。 - moldinsight 专属接线收敛回 moldinsight 层：
- RustFS 启动 → init_storage.py 的
rustfs_startup_hook（moldinsight/unified 入口经startup_hooks注入） - /api 路由聚合 + HTML 报告根路径挂载 → moldinsight/api/__init__.py 的
register_moldinsight_routers（入口只做单点调用，不再重复 include html_report）
- RustFS 启动 → init_storage.py 的
- 入口 src/entrypoints/ 退化为纯组装：sys.path 修正 + 调 create_app + 传 startup_hooks / register_routers。
6.3 文档与结构尚未完全同步
代码结构已明显模块化，但历史文档中仍保留不少阶段性叙述、旧部署语义与重复说明，这也是本轮文档整理要解决的问题之一。
7. 专题文档与主骨架的关系
以下文档仍可作为专题补充参考，但不再承担默认入口职责：
- 存储方向：
- 性能方向：
- 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