cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e728dcd226c640fe2dee56cd967fb1d0c909d5a5
geMoldInsight/docs/ARCHITECTURE.md
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

229 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# geMoldInsight 架构与边界（ARCHITECTURE）
> 文档定位：**当前架构、模块边界与结构原则的权威文档**。
> 本文描述“现在的系统结构是什么、边界如何划分、目标形态是什么”；不负责维护当前实现进度，当前状态见 [STATUS.md](STATUS.md)，部署见 [DEPLOYMENT.md](DEPLOYMENT.md)，演进路线见 [ROADMAP.md](ROADMAP.md)。
> 如需追溯模块化设计蓝图与扩展讨论，见 [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](archive/BACKEND_MODULARIZATION_BLUEPRINT.md)。
---
## 1. 架构目标
geMoldInsight 的目标架构不是微服务，也不是继续维持历史单体，而是：
> **单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith**
这意味着：
- 保持同一 Git 仓库
- 保持同一 PostgreSQL 数据库
- 按模块组织业务代码与部署入口
- 在不拆库、不拆仓的前提下，明确业务边界与部署边界
---
## 2. 当前模块划分
### 2.1 moldinsight
目录：
- [src/moldinsight/](../src/moldinsight/)
职责：
- STEP/STP 上传与任务管理
- 几何分析与特征识别
- 模具方案生成
- 批量分析
- 成本估算
- 导出与结果查询
- 结合 Celery 执行异步分析链路
### 2.2 inventory
目录：
- [src/inventory/](../src/inventory/)
职责：
- 成品/物料管理
- BOM 管理
- 库存与库存流水
- 采购订单 / 销售订单
- 财务与对账
- 采购建议推导
### 2.3 frontend
目录：
- [frontend/](../frontend/)
职责：
- 模具分析页面
- 进销存页面
- 登录/用户管理
- 统一路由与状态管理
- 基于 OpenAPI 类型生成的前端调用
### 2.4 shared（当前平台层）
目录：
- [src/shared/](../src/shared/)
职责：
- 配置
- 数据库连接与 session
- 认证与权限
- 日志与 request_id
- 应用工厂与共用中间件
说明：
- `shared` 当前仍是“共享平台层 + 历史耦合区”的混合体
- 后续会继续向更清晰的 platform 语义收敛，但当前仓库结构仍以 `shared` 为事实名称
---
## 3. 当前代码结构
当前核心结构如下：
```text
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](../src/entrypoints/moldinsight.py)
### 4.3 inventory-only
只部署进销存后端。
适合：
- 独立使用 ERP / 库存能力
- 与 moldinsight 分开部署节奏
入口：
- [src/entrypoints/inventory.py](../src/entrypoints/inventory.py)
部署操作与当前推荐方案见 [DEPLOYMENT.md](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](../src/shared/models/base.py)：唯一 `Base` + 归属约定与全量注册点说明
- [src/shared/models/identity.py](../src/shared/models/identity.py)：用户/角色/权限/审计（平台层，所有部署形态共用）
- [src/moldinsight/models/](../src/moldinsight/models/)：STEP 分析域 9 表（stp_files 及各阶段产物、processing_tasks）
- [src/inventory/models/](../src/inventory/models/)：进销存 15 表（catalog / warehouse / trading / finance 四域文件）
跨模块只允许裸 FK（规则见 §5.1）；全量模型注册点收敛为 `migrations/env.py` 与 `tests/conftest.py`；归属边界由 [tests/test_model_ownership.py](../tests/test_model_ownership.py) 锁定（含单模块独立 mapper 配置与旧模块无 facade 断言）。
### 6.2 app factory 组合职责偏重
当前 [src/shared/app_factory.py](../src/shared/app_factory.py) 仍承担较多平台与模块组合职责，是后续平台层收敛的重点。
### 6.3 文档与结构尚未完全同步
代码结构已明显模块化，但历史文档中仍保留不少阶段性叙述、旧部署语义与重复说明，这也是本轮文档整理要解决的问题之一。
---
## 7. 专题文档与主骨架的关系
以下文档仍可作为专题补充参考，但不再承担默认入口职责：
- 存储方向：
- [topics/storage/RUSTFS_STORAGE.md](topics/storage/RUSTFS_STORAGE.md)
- [topics/storage/STORAGE_SETUP.md](topics/storage/STORAGE_SETUP.md)
- 性能方向：
- [topics/performance/OCC_THROUGHPUT.md](topics/performance/OCC_THROUGHPUT.md)（OCC 吞吐与隔离方案设计，TECH_DEBT D10 归属）
AI、铝泡沫等更偏历史设计/规划性质的专题材料已迁入 [archive/README.md](archive/README.md)。
阶段性任务清单、迁移计划、历史总结等文档会逐步迁入 [archive/README.md](archive/README.md)。
---
## 8. 与相关文档的边界
- 想看“当前做到哪一步”：看 [STATUS.md](STATUS.md)
- 想看“后面还要往哪演进”：看 [ROADMAP.md](ROADMAP.md)
- 想看“当前有哪些活跃技术债”：看 [TECH_DEBT.md](TECH_DEBT.md)
- 想看“配置怎么给、服务怎么起”：看 [OPERATIONS.md](OPERATIONS.md)
- 想看“前后端接口契约”：看 [API_CONTRACT.md](API_CONTRACT.md)
- 想看“怎么部署”：看 [DEPLOYMENT.md](DEPLOYMENT.md)
- 想看“模块化蓝图与更完整设计讨论”：看 [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
Reference in New Issue View Git Blame Copy Permalink