geMoldInsight

geMoldInsight 是一个面向模具制造场景的综合系统，围绕 STP/STEP 模型分析、模具方案生成、分析结果沉淀、成品创建、BOM/库存/采购/销售闭环 展开。

当前项目已经从早期单体演进为：

• gemold（moldinsight）模块：模具分析、几何处理、批量分析、成本估算、结果导出
• inventory 模块：产品、BOM、库存、采购、销售、财务
• frontend 模块：Vue 3 前端工程
• shared 平台层：配置、数据库、认证、日志、应用工厂

项目当前采用：

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

详细重构方向见：BACKEND_MODULARIZATION_BLUEPRINT.md

---

核心能力

模块	能力
gemold	STP/STEP 上传、几何分析、特征识别、模具方案、批量分析、成本估算、结果导出
inventory	成品/物料、BOM、库存、库存流水、采购订单、销售订单、财务、采购建议
integration	分析结果一键创建成品，打通“模具分析 → 成品 → BOM → 销售/采购/库存”
platform	用户、角色、权限、JWT 鉴权、数据库连接、日志、健康检查

---

技术栈

后端

• FastAPI
• SQLAlchemy 2.0
• PostgreSQL
• Alembic
• Redis
• Celery
• PythonOCC / trimesh / pyvista
• RustFS / MinIO 兼容对象存储

前端

• Vue 3
• Vite
• TypeScript
• Pinia
• Vue Router
• TDesign Vue Next

基础设施

• Docker / Docker Compose
• 结构化日志 / request_id
• OpenAPI → TypeScript 类型生成

---

当前项目结构

下述结构反映的是当前代码现状，不是历史单体结构。

geMoldInsight/
├── src/
│   ├── entrypoints/               # 独立部署入口
│   │   ├── moldinsight.py         # gemold-only 入口
│   │   └── inventory.py           # inventory-only 入口
│   │
│   ├── shared/                    # 共享平台层（当前形态）
│   │   ├── app_factory.py         # FastAPI 应用工厂
│   │   ├── config/                # 配置
│   │   ├── database/              # DB engine / session / init
│   │   ├── models/                # 共享 ORM 模型（当前最大耦合点）
│   │   ├── services/              # 认证、Redis 等共享服务
│   │   └── utils/                 # 日志、文件、HTML 工具
│   │
│   ├── moldinsight/               # gemold 模块
│   │   ├── api/
│   │   ├── core/
│   │   ├── services/
│   │   └── storage/
│   │
│   ├── inventory/                 # inventory 模块
│   │   ├── api/
│   │   ├── schemas/
│   │   └── services/
│   │
│   ├── celery_app.py              # Celery app
│   ├── celery_tasks.py            # gemold 异步任务
│   └── main.py                    # 旧统一入口（兼容/过渡）
│
├── frontend/                      # 独立前端工程
│   ├── src/
│   │   ├── modules/
│   │   │   ├── moldinsight/
│   │   │   ├── inventory/
│   │   │   ├── login/
│   │   │   ├── users/
│   │   │   └── home/
│   │   ├── router/
│   │   ├── shared/
│   │   ├── stores/
│   │   └── types/
│   └── package.json
│
├── alembic/                       # Alembic migrations
├── deploy/                        # 镜像构建与部署辅助文件
│   ├── Dockerfile.base
│   ├── Dockerfile.moldinsight
│   ├── Dockerfile.inventory
│   └── Dockerfile.celery
│
├── docs/
├── tests/
├── requirements.txt
└── .env.example

---

模块说明

1. gemold（moldinsight）

主要负责：

• STP/STEP 上传与任务管理
• 几何分析与特征识别
• 模具方案、型腔/型芯/工艺建议
• 批量分析
• 成本估算
• 导出与结果查询
• Celery 异步处理

关键目录：

• src/moldinsight/
• src/celery_app.py
• src/celery_tasks.py

2. inventory

主要负责：

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

关键目录：

• src/inventory/

3. frontend

主要负责：

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

关键目录：

• frontend/

4. shared（当前平台层）

主要负责：

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

关键目录：

• src/shared/

说明：后续会逐步将 shared 收敛为更清晰的 platform 语义，见 BACKEND_MODULARIZATION_BLUEPRINT.md。

---

部署模式

当前项目设计上支持三种模式：

1. unified

一个统一后端同时挂载 gemold + inventory。

适合：

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

2. gemold-only

只部署模具分析后端。

适合：

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

入口参考：

• src/entrypoints/moldinsight.py

3. inventory-only

只部署进销存后端。

适合：

• 仅使用 ERP / 库存能力
• 与 gemold 分开部署节奏

入口参考：

• src/entrypoints/inventory.py

---

快速开始

1. 环境要求

• Python 3.12
• PostgreSQL 15+（服务器已部署或自行提供）
• Redis（服务器已部署或自行提供）
• 对象存储（MinIO / RustFS 兼容；gemold 模块需要，服务器已部署或自行提供）
• Node.js 20+（前端开发需要）
• 推荐使用 docker-compose.yml 仅启动项目自身服务，复用服务器已有 PostgreSQL / Redis / 对象存储

---

2. 安装后端依赖

pip install -r requirements.txt

如果需要几何分析能力，还需确保 PythonOCC 运行环境可用。项目中已说明其通常通过 conda 提供，而不是直接由 pip 安装。

---

3. 配置环境变量

复制并编辑：

• .env.example
• 部署场景也可参考 deploy/.env.example

最少需要关注：

HOST=0.0.0.0
PORT=8000

DB_HOST=localhost
DB_PORT=5432
DB_NAME=moldinsight
DB_USER=moldinsight_user
DB_PASSWORD=moldinsight_password

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

SECRET_KEY=change-me
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me

RUSTFS_ENDPOINT=http://localhost:9000
RUSTFS_ACCESS_KEY=your-access-key
RUSTFS_SECRET_KEY=your-secret-key

更多配置项见：

• settings.py
• .env.example

---

4. 初始化数据库

项目当前使用 Alembic 管理迁移。应用启动时也会执行初始化逻辑，但首次部署建议显式执行迁移流程。

如需查看初始化实现，可参考：

• init_db.py

---

5. 启动方式

方式 A：使用根目录 Compose（推荐）

当前唯一 Compose 入口：

• docker-compose.yml

该 compose 文件只启动项目自身容器：

• moldinsight
• moldinsight-celery
• inventory

并通过 .env 连接服务器上已经存在的：

• PostgreSQL
• Redis
• RustFS / MinIO 兼容对象存储

示例：

docker compose --profile full up -d

可选 profile：

• full
• moldinsight
• inventory

说明：docker-compose.yml 不再重复部署 postgres / redis / minio，而是复用服务器现有基础设施。

方式 B：直接启动后端入口

gemold-only：

uvicorn src.entrypoints.moldinsight:app --reload --host 0.0.0.0 --port 8000

inventory-only：

uvicorn src.entrypoints.inventory:app --reload --host 0.0.0.0 --port 8001

方式 C：启动前端

cd frontend
npm install
npm run dev

生产构建：

cd frontend
npm run build

---

健康检查与接口

健康检查

两类后端都通过共享 app factory 暴露健康检查：

• GET /health
• POST /health

参考实现：

• app_factory.py

认证接口

• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me

gemold 典型接口

• POST /api/upload
• POST /api/batch-upload
• GET /api/status/{task_id}
• GET /api/history
• POST /api/cost-estimate

inventory 典型接口

• GET /api/products
• GET /api/inventory
• GET /api/purchase-orders
• GET /api/sales-orders
• GET /api/finance/*

统一契约输出可参考：

• openapi.json
• frontend/src/types/api.ts

---

当前架构重点说明

1. gemold 与 inventory 已基本模块化

当前代码层面，src/moldinsight/ 与 src/inventory/ 已基本无直接互相依赖，说明业务边界已经初步成型。

2. 当前最大耦合点在 shared + 共享 ORM

需要特别注意：

• src/shared/models/database.py 同时定义了 identity、gemold、inventory 的 ORM 模型
• src/shared/app_factory.py 仍承担较多平台与模块组合职责

这也是下一阶段重构的重点。

3. 单数据库是刻意选择

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

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

典型桥接点：

• STPFile.product_id -> Product.id

---

开发与演进文档

推荐先阅读：

• BACKEND_MODULARIZATION_BLUEPRINT.md — 当前模块化重构蓝图
• EVOLUTION_ROADMAP.md — 历史演进与阶段任务
• docs/deployment/ — 现有部署文档（部分仍在对齐中）

---

开发建议

• 新增业务逻辑优先放入对应业务模块，不要继续堆进 shared
• 新增 API 时优先考虑模块归属，而不是“能放就放”
• 前端优先通过域 API client 调用接口，而不是散落裸 /api/... 路径
• 数据模型改动要同时考虑表归属与 Alembic 迁移影响

---

许可证

本项目采用 MIT 许可证，详见 LICENSE。