# geMoldInsight 后端模块化重构蓝图

> 目标：在**同一 Git 仓库**、**同一数据库**前提下，将当前代码结构整理为**可独立部署的多模块架构**，明确 gemold、inventory、frontend 的边界与演进路径。本文档是后续实施的权威蓝图，不是历史记录。

---

## 1. 背景与目标

当前项目已经从早期单体演进为“双应用 + 共享层”的形态：

- 业务模块：`src/moldinsight/`、`src/inventory/`
- 共享层：`src/shared/`
- 部署入口：`src/entrypoints/moldinsight.py`、`src/entrypoints/inventory.py`
- 前端工程：`frontend/`

从代码现状看，`moldinsight` 与 `inventory` 已基本无直接互引，说明模块边界已经初步形成；但同时，数据库模型、认证、配置、应用工厂等仍集中在 `shared/`，导致当前更接近“**模块化中的单体**”，而不是“**可独立部署的模块化单体**”。

本次蓝图的目标不是拆库、拆仓、微服务化，而是：

1. 保持**单仓库（monorepo）**
2. 保持**单数据库**
3. 将后端正式整理为多个模块：
   - **gemold**（模具分析 / moldinsight）
   - **inventory**（进销存）
   - **identity / platform**（共享基础设施与认证）
4. 保持前端为**独立模块工程**，并增强其对多部署模式的兼容
5. 支持三种部署模式：
   - **unified**：gemold + inventory 同时部署
   - **gemold-only**：仅部署 gemold
   - **inventory-only**：仅部署 inventory

---

## 2. 范围与非目标

### 2.1 本次蓝图覆盖范围

- 后端模块边界
- 共享层职责重新定义
- 单数据库下的模型归属与表所有权
- 独立部署模式设计
- 前端 API 边界强化策略
- 分阶段迁移路径
- 风险与验证方法

### 2.2 非目标

本蓝图**不包含**以下方向：

- 多 Git 仓库拆分
- 多数据库拆分
- 分布式微服务重构
- 全量 DDD 重写
- 全量前端重构
- 事件驱动或消息总线主导的跨服务通信改造

换句话说，目标架构是：

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

而不是微服务系统。

---

## 3. 当前架构快照

### 3.1 后端现状

当前核心目录结构如下：

```text
src/
  entrypoints/
    moldinsight.py
    inventory.py
  shared/
    app_factory.py
    config/
    database/
    models/
    services/
    utils/
  moldinsight/
    api/
    core/
    services/
    storage/
  inventory/
    api/
    schemas/
    services/
```

其中：

- [app_factory.py](../src/shared/app_factory.py) 已统一 CORS、日志中间件、startup/shutdown、认证路由、健康检查与 SPA fallback。
- [moldinsight.py](../src/entrypoints/moldinsight.py) 与 [inventory.py](../src/entrypoints/inventory.py) 已提供独立入口。
- [database.py](../src/shared/models/database.py) 同时包含 identity、moldinsight、inventory 三类模型，是当前最强耦合点。

### 3.2 前端现状

前端已是独立 Vite/Vue 工程：

```text
frontend/
  src/
    modules/
      moldinsight/
      inventory/
      login/
      users/
      home/
    router/
    shared/
    stores/
    types/
```

特点：

- 已按页面/业务模块组织
- 已有共享 API 层雏形：[api-client.ts](../frontend/src/shared/api-client.ts)
- 已接入 OpenAPI 生成类型：[api.ts](../frontend/src/types/api.ts)
- 当前仍有大量相对路径 `/api/...` 与 raw `fetch()` 的同源假设

### 3.3 现状判断

当前架构可概括为：

> **HTTP 入口已分离，业务代码已分组，但平台层与数据层仍共享。**

因此，它适合继续朝“可独立部署的模块化单体”演进，而不适合直接跳到微服务。

---

## 4. 目标架构：可独立部署的模块化单体

### 4.1 架构原则

目标态采用以下原则：

1. **组合优先于复制**：不同部署模式通过组合不同模块得到，而不是复制多套代码。
2. **平台与业务分离**：`platform` 只承载技术性共享能力，不继续承载业务逻辑。
3. **模块所有权清晰**：每张表、每条 API、每个服务类都应有明确归属。
4. **单数据库但显式边界**：允许共享 DB，但不允许“共享数据库 = 没有边界”。
5. **统一前端，兼容多后端部署形态**：前端继续是一套工程，通过 API client 适配 unified / split deployment。

### 4.2 架构定位

目标架构不是“多个服务各自拥有数据库”的微服务，而是：

- 同一个仓库
- 同一个数据库
- 多个模块
- 多个部署入口
- 同一套迁移历史
- 同一套共享基础设施能力

这是一种适合当前项目阶段的**治理性重构**，而不是组织级拆分。

---

## 5. 目标目录结构

以下结构是**目标态**，不要求一次性到位：

```text
src/
  platform/
    app/
      app_factory.py
      lifecycle.py
      middleware/
    config/
    auth/
    database/
      engine.py
      session.py
      migrations/
    observability/
    contracts/
      api/
      events/
    shared_kernel/
      types/
      exceptions/
      utils/

  modules/
    moldinsight/
      application/
        services/
        use_cases/
      domain/
        models/
        policies/
        repositories/
      infrastructure/
        persistence/
        storage/
        adapters/
      interfaces/
        api/
        schemas/
      module.py

    inventory/
      application/
        services/
        use_cases/
      domain/
        models/
        policies/
        repositories/
      infrastructure/
        persistence/
        adapters/
      interfaces/
        api/
        schemas/
      module.py

    identity/
      application/
      domain/
      infrastructure/
      interfaces/
      module.py

  compositions/
    unified_app.py
    gemold_app.py
    inventory_app.py

  legacy/
    main.py
```

### 5.1 当前目录到目标目录的映射

| 当前路径 | 目标路径 | 说明 |
|---|---|---|
| `src/shared/*` | `src/platform/*` | 共享基础设施重新命名与归位 |
| `src/moldinsight/*` | `src/modules/moldinsight/*` | gemold 业务模块 |
| `src/inventory/*` | `src/modules/inventory/*` | inventory 业务模块 |
| `src/entrypoints/*` | `src/compositions/*` | 部署组合层 |
| `src/main.py` | `src/legacy/main.py` | 过渡期兼容入口 |

### 5.2 为什么要引入 `compositions/`

当前 [entrypoints/](../src/entrypoints/) 已经承担“部署入口”角色，但语义更偏“启动文件”。

引入 `compositions/` 的意义是明确：

- 它不是业务模块
- 它不是平台能力
- 它是“**按部署模式装配模块**”的组合层

例如：

- `gemold_app.py`：平台 + identity + moldinsight
- `inventory_app.py`：平台 + identity + inventory
- `unified_app.py`：平台 + identity + moldinsight + inventory

---

## 6. 模块职责边界

### 6.1 platform

`platform` 是技术共享层，只承载**跨模块公共基础设施能力**。

#### 归属范围
- app factory / middleware / 生命周期
- config
- 数据库 engine / session / Alembic 接线
- auth / JWT / 权限
- 日志 / request_id / observability
- 通用 contracts / utilities

#### 可复用现有实现
- [app_factory.py](../src/shared/app_factory.py)
- [settings.py](../src/shared/config/settings.py)
- [database.py](../src/shared/database/database.py)
- [auth_service.py](../src/shared/services/auth_service.py)
- [auth_routes.py](../src/shared/services/auth_routes.py)

#### 规则
`platform` 不得继续吸收业务规则代码，否则新的 `platform` 会变成旧的 `shared`。

---

### 6.2 moldinsight（gemold）

`moldinsight` 模块负责模具分析、几何处理和分析结果生命周期。

#### 归属范围
- 上传、任务、历史、批量分析、成本估算、CAM、分析结果
- 几何分析、特征检测、模具方案、报告
- RustFS / 对象存储接入
- Celery 异步处理链路

#### 可复用现有实现
- [moldinsight/api/__init__.py](../src/moldinsight/api/__init__.py)
- [processing_service.py](../src/moldinsight/services/processing_service.py)
- [task_query_service.py](../src/moldinsight/services/task_query_service.py)
- [moldinsight/core/](../src/moldinsight/core/)
- [celery_app.py](../src/celery_app.py)
- [celery_tasks.py](../src/celery_tasks.py)

---

### 6.3 inventory

`inventory` 模块负责 ERP / 进销存类业务流程。

#### 归属范围
- 产品、物料、供应商、客户、仓库
- 库存、库存流水
- 销售订单、采购订单、财务、采购建议
- BOM / 采购需求推导

#### 可复用现有实现
- [inventory/api/__init__.py](../src/inventory/api/__init__.py)
- [inventory_service.py](../src/inventory/services/inventory_service.py)
- [sales_order_service.py](../src/inventory/services/sales_order_service.py)
- [purchase_order_service.py](../src/inventory/services/purchase_order_service.py)
- [finance_service.py](../src/inventory/services/finance_service.py)

---

### 6.4 identity

`identity` 负责用户、角色、权限与认证授权。

#### 归属范围
- User / Role / Permission
- 登录、鉴权、管理员接口
- 统一授权能力

在物理目录上，identity 可以先靠近 platform；但逻辑上应从一开始就被视为独立边界，而不是“moldinsight 的一部分”或“inventory 的一部分”。

---

## 7. 允许的依赖方向

这是本蓝图最重要的治理规则之一。

### 7.1 依赖规则

```text
compositions -> platform
compositions -> modules/*

platform -> 不依赖业务模块

modules/*/interfaces -> modules/*/application
modules/*/application -> modules/*/domain
modules/*/infrastructure -> modules/*/domain

modules/*/interfaces -> platform
modules/*/infrastructure -> platform
```

### 7.2 跨模块约束

- `inventory` 不能直接 import `moldinsight.api` / `moldinsight.services`
- `moldinsight` 不能直接 import `inventory.api` / `inventory.services`
- `platform` 不得依赖任一业务模块
- 跨模块协作只能通过：
  - 显式 contract / query service
  - composition wiring
  - 受控的共享数据库引用

### 7.3 当前代码与规则的差距

从代码检查看，当前 `moldinsight` 与 `inventory` 基本没有直接互引，这说明上述规则在业务代码层**已经接近成立**。

当前主要问题集中在：

- [database.py](../src/shared/models/database.py) 集中承载所有 ORM 模型
- [app_factory.py](../src/shared/app_factory.py) 同时知道通用平台逻辑与 moldinsight 专属 startup 行为

因此，后续实施的重点不是“切断业务模块互引”，而是“**把共享层与数据层的边界拉直**”。

---

## 8. 单数据库下的模型与表归属策略

### 8.1 核心原则

数据库继续保持为**一个 PostgreSQL 数据库**，但代码中的模型归属必须显式化。

也就是说：

> **数据库不拆，模型归属要拆。**

### 8.2 当前最强耦合点

当前 [database.py](../src/shared/models/database.py) 同时包含：

- identity / 平台相关模型
- moldinsight 业务模型
- inventory 业务模型

这会带来两个问题：

1. 代码层看不出模型所有权
2. 开发者更容易跨模块直接访问整套 ORM 图谱

因此，后续实施应优先将这个文件按归属拆分。

### 8.3 推荐表归属矩阵

#### platform / identity-owned
- users
- roles
- permissions
- user_roles
- role_permissions
- （可选）system_logs

#### moldinsight-owned
- stp_files
- geometry_data
- mesh_data
- html_files
- processing_tasks
- mold_cavity_data
- feature_detections
- design_recommendations
- analysis_metrics

#### inventory-owned
- products
- product_materials
- material_price_history
- material_suppliers
- suppliers
- customers
- warehouses
- inventory
- stock_movements
- purchase_orders
- purchase_order_items
- sales_orders
- sales_order_items
- finance_transactions
- finance_allocations

### 8.4 目标代码形态

推荐逐步演进到：

```text
platform/database/base.py
modules/identity/infrastructure/persistence/models.py
modules/moldinsight/infrastructure/persistence/models.py
modules/inventory/infrastructure/persistence/models.py
```

同时保持：

- 同一个 SQLAlchemy `Base`
- 同一个 metadata
- 同一条 Alembic 历史链
- 同一个数据库连接

### 8.5 跨模块 FK 的处理策略

当前存在真实跨模块业务桥：

- `STPFile.product_id -> Product.id`

这是合理的，因为它反映了真实业务关系：模具分析结果可以创建成品，并与 inventory 中的产品建立连接。

原则上允许保留这类稳定 FK，但应遵守：

1. 跨模块 FK 是**业务桥**，不是“任意跨模块查询”的许可
2. 模块之间应逐步通过 query service / repository contract 暴露需要的读取能力
3. 避免一个模块直接依赖另一个模块的整套 ORM 图谱

---

## 9. 部署模式设计

本项目必须支持三种部署模式。

### 9.1 unified

#### 组成
- platform + identity + moldinsight + inventory

#### 适用场景
- 本地开发
- 小团队部署
- 集成环境
- 一体化业务场景

#### 说明
新的 unified 组合层应接替旧 [main.py](../src/main.py) 的语义，但应通过 `compositions/unified_app.py` 的方式实现，而不是继续维持旧单体式入口。

---

### 9.2 gemold-only

#### 组成
- platform + identity + moldinsight

#### 适用场景
- 仅开放模具分析能力
- 分析服务独立扩容
- 单独部署算法/文件处理能力

#### 说明
- 只暴露 gemold 路由
- 可保留对共享数据库中 `products` 的受控引用
- RustFS / Celery 等专属基础设施只在该模式启用

当前入口基线：
- [moldinsight.py](../src/entrypoints/moldinsight.py)

---

### 9.3 inventory-only

#### 组成
- platform + identity + inventory

#### 适用场景
- 仅提供 ERP / 进销存能力
- 不需要模具分析链路的后台场景

#### 说明
- 只暴露 inventory 路由
- 不要求启动 RustFS 等 moldinsight 专属基础设施

当前入口基线：
- [inventory.py](../src/entrypoints/inventory.py)

---

### 9.4 当前共享工厂的边界问题

需要特别指出：当前 [app_factory.py](../src/shared/app_factory.py) 通过 `mount_html=True` 分支初始化 RustFS，这说明共享工厂仍然知道 moldinsight 模块专属基础设施。

这意味着：

- `shared` / `platform` 还不够纯
- 模块专属 startup hook 还没有完全从平台层剥离

后续实施时，这应是**优先解决的问题之一**：

> app factory 只负责通用平台装配；模块专属生命周期应由 module hook 或 composition layer 决定。

---

## 10. 前端 API 边界策略

### 10.1 设计原则

前端已经是独立工程，不需要再拆目录或拆仓。后续重点应放在：

- 强化域 API 边界
- 消除对单一同源 `/api/...` 的强依赖
- 兼容 unified / split deployment

### 10.2 当前可复用基础

当前前端已经具备良好基础：

- 域客户端入口：[api-client.ts](../frontend/src/shared/api-client.ts)
- 生成类型：[api.ts](../frontend/src/types/api.ts)
- 模块目录：[frontend/src/modules/moldinsight/](../frontend/src/modules/moldinsight/) 与 [frontend/src/modules/inventory/](../frontend/src/modules/inventory/)

因此，后续策略应是“**边界强化**”，不是“前端重写”。

### 10.3 建议的客户端边界

应继续收敛为：

- `authApi`
- `moldinsightApi`
- `inventoryApi`

并要求：

- 页面/组件尽量不直接写裸 `/api/...` 字符串
- multipart upload / download / export 也尽量通过域客户端封装
- 统一利用 OpenAPI 生成类型，而不是额外维护平行手写类型

### 10.4 支持两类部署配置

#### unified 模式
- `VITE_API_BASE_URL`

#### split 模式
- `VITE_AUTH_API_BASE_URL`
- `VITE_MOLDINSIGHT_API_BASE_URL`
- `VITE_INVENTORY_API_BASE_URL`

客户端实现上应支持：

- unified 下三个 client 指向同一个 base URL
- split 下各 client 指向不同服务

### 10.5 capability-aware UI

在 gemold-only 或 inventory-only 部署模式下，前端不应假设所有模块总是存在。

因此建议：

- 后端通过 `/health` 或单独 capability endpoint 暴露已启用模块信息
- 前端根据 capability 隐藏未部署模块入口或禁用对应页面

这样可避免“前端路由还在，但后端根本没部署”的硬失败场景。

---

## 11. 分阶段迁移计划

### Phase 0：蓝图冻结

目标：冻结目标结构与边界规则，防止迁移过程中继续长出新的耦合。

动作：
- 确认模块边界
- 确认依赖规则
- 确认三种部署模式
- 确认 shared/platform 的使用边界

---

### Phase 1：组合层标准化

目标：将部署模式从“若干入口脚本”升级为“正式的 composition layer”。

动作：
- 将 `entrypoints/*` 升级为 `compositions/*`
- 定义 `unified_app.py` / `gemold_app.py` / `inventory_app.py`
- 将 module-specific startup hooks 从通用 app factory 中迁出

重点问题：
- 当前 `mount_html -> RustFS connect` 属于模块专属逻辑，必须从 shared factory 中剥离

---

### Phase 2：platform 与业务代码分治

目标：把“共享基础设施”从“共享杂项”中真正分离出来。

动作：
- 从 `shared` 语义切换到更清晰的 `platform`
- 归位 config / auth / db / observability / utils
- 禁止新业务逻辑继续沉积到 `shared`

---

### Phase 3：ORM 按归属拆分

目标：解决当前最大的代码耦合源。

动作：
- 拆分 [database.py](../src/shared/models/database.py)
- 保持单 Base / 单 Alembic / 单 DB
- 先完成代码层归属拆分，再处理更深层的业务隔离

这是整个重构中最关键的一步。

---

### Phase 4：模块内部继续分层

目标：让每个模块内部的“路由 / 服务 / 领域 / 基础设施”边界更清晰。

动作：
- inventory：从现有 service 层继续向 `application / domain / infrastructure / interfaces` 拉开
- moldinsight：逐步理顺 `api / services / core / storage` 的边界

原则：
- 不要求一步完成 DDD 化
- 先把层次职责清楚，再考虑更纯粹的领域对象抽象

---

### Phase 5：建立跨模块集成规则

目标：把当前 ad hoc 跨表访问逐步收敛成显式桥接能力。

动作：
- 定义跨模块 query services / repository contracts
- 明确“从分析创建成品”等桥接能力的正式入口
- 收敛直接穿透跨模块 ORM 图谱的做法

重点桥接场景：
- `STPFile.product_id`
- [product_routes.py](../src/inventory/api/product_routes.py) 中的“按 task 创建产品”逻辑

---

### Phase 6：前端边界加固

目标：让前端真正适配 unified / split deployment。

动作：
- 强制域 API client 收口
- 支持 per-module base URL
- 支持 capability-aware UI
- 减少页面中裸 `fetch('/api/...')`

---

### Phase 7：部署与文档收尾

目标：使架构蓝图与部署事实一致。

动作：
- 固化 unified / gemold-only / inventory-only 部署说明
- 更新 README / deployment docs / frontend docs
- 明确旧入口、旧 Dockerfile、旧部署说明的地位（兼容 / 历史 / 废弃）

---

## 12. 风险与缓解措施

### 风险 1：共享模型文件继续隐藏领域归属

**现象**：所有模型集中在 [database.py](../src/shared/models/database.py)

**风险**：边界无法落实，任何模块都能自然跨领域访问

**缓解**：
- 先产出表归属矩阵
- 再拆 ORM 文件
- 拆归属优先于改业务逻辑

---

### 风险 2：`shared` 继续变成杂物间

**风险**：shared/platform 成为“不知道放哪就放这里”的位置

**缓解**：
- 以 `platform` 重新定义共享层
- 明确只有技术性共享能力可进入 platform
- 代码 review 中禁止新增业务逻辑进入 platform

---

### 风险 3：模块专属启动逻辑继续留在 app factory

**现象**：当前 `mount_html` 分支控制 RustFS 连接

**风险**：平台层继续了解业务模块内部基础设施

**缓解**：
- module lifecycle hook
- composition 层控制模块 startup/shutdown
- 通用 app factory 保持纯平台化

---

### 风险 4：独立部署后，前端仍假设所有模块存在

**风险**：前端路由可见，但后端未部署，造成运行时错误

**缓解**：
- capability metadata
- feature gating
- 前端按模块部署形态动态隐藏入口

---

### 风险 5：单数据库导致开发者随意跨模块查表

**风险**：虽然数据库未拆，但代码边界被绕开

**缓解**：
- 表归属规则文档化
- code review 要求说明跨模块访问理由
- 逐步通过 query services 收口

---

### 风险 6：大爆炸式目录迁移导致 import churn

**风险**：一次性移动所有目录，修改面过大，回归成本高

**缓解**：
- 分阶段迁移
- 保留兼容 import 过渡层
- 先稳定组合层与模型层，再做深层目录调整

---

## 13. 验证清单

### 13.1 结构验证

- `platform` 不 import 业务模块
- `moldinsight` / `inventory` 无直接 api/services 互引
- ORM 文件已按归属拆分，或至少表归属矩阵已文档化并被遵守

### 13.2 运行验证

#### unified
- 两类路由都能正常挂载
- 统一 health / auth / request-id 机制生效

#### gemold-only
- inventory 路由未挂载
- gemold 路由可用
- RustFS / Celery 等专属依赖正常初始化

#### inventory-only
- moldinsight 路由未挂载
- inventory 路由可用
- 不依赖 moldinsight 专属基础设施即可启动

### 13.3 数据验证

- 三种部署模式使用同一 migration head
- 单数据库中的跨模块 FK 保持有效
- Alembic 无分叉历史

### 13.4 前端验证

- unified 模式下，一个 base URL 即可跑通
- split 模式下，各模块 base URL 可独立配置
- 未部署模块能被隐藏或优雅失败

---

## 14. 文档联动更新计划

本蓝图批准后，以下文档应逐步对齐：

- [EVOLUTION_ROADMAP.md](./EVOLUTION_ROADMAP.md)
- [LINUX_SETUP.md](./deployment/LINUX_SETUP.md)
- [DEPLOY_PORT.md](./deployment/DEPLOY_PORT.md)
- [PORT_CONFIG.md](./deployment/PORT_CONFIG.md)
- [PORT_REFACTOR_SUMMARY.md](./deployment/PORT_REFACTOR_SUMMARY.md)
- `README.md`
- `frontend/README.md`

其中需要特别注意：

- `README.md` 当前仍主要描述旧单体结构，与当前实际代码已有明显漂移。
- 本文档应作为“当前目标架构”的权威蓝图，路线图与部署文档随后对齐。

---

## 15. 附录：实施热点文件

以下文件是后续实际重构时最关键的热点：

### 平台与组合层
- [app_factory.py](../src/shared/app_factory.py)
- [settings.py](../src/shared/config/settings.py)
- [database.py](../src/shared/database/database.py)
- [init_db.py](../src/shared/database/init_db.py)
- [moldinsight.py](../src/entrypoints/moldinsight.py)
- [inventory.py](../src/entrypoints/inventory.py)
- [main.py](../src/main.py)

### 模型与边界
- [database.py](../src/shared/models/database.py)
- [product_routes.py](../src/inventory/api/product_routes.py)

### gemold 模块
- [moldinsight/api/__init__.py](../src/moldinsight/api/__init__.py)
- [processing_service.py](../src/moldinsight/services/processing_service.py)
- [task_query_service.py](../src/moldinsight/services/task_query_service.py)

### inventory 模块
- [inventory/api/__init__.py](../src/inventory/api/__init__.py)
- [inventory_service.py](../src/inventory/services/inventory_service.py)
- [sales_order_service.py](../src/inventory/services/sales_order_service.py)
- [purchase_order_service.py](../src/inventory/services/purchase_order_service.py)
- [finance_service.py](../src/inventory/services/finance_service.py)

### 前端边界
- [api-client.ts](../frontend/src/shared/api-client.ts)
- [api.ts](../frontend/src/types/api.ts)

### 演进与部署参考
- [EVOLUTION_ROADMAP.md](./EVOLUTION_ROADMAP.md)
- [docker-compose.yml](../docker-compose.yml)

---

## 16. 最终结论

本项目当前最适合的演进路径不是微服务，而是：

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

它既能保留当前业务闭环（模具分析 → 成品 → BOM → 销售/采购/库存），又能逐步降低共享层和模型层的结构耦合。

后续实施时，应优先按以下顺序推进：

1. 固化组合层（deployment composition）
2. 纯化 platform/shared 边界
3. 拆分共享 ORM 文件
4. 再继续模块内部细分层次
5. 最后收口前端 API 与部署文档

这条路径风险最低、收益最大，也最符合当前代码现状与团队演进成本。