448 lines
11 KiB
Markdown
448 lines
11 KiB
Markdown
# geMoldInsight
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</div>
|
||
|
||
geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STP/STEP 模型分析、模具方案生成、分析结果沉淀、成品创建、BOM/库存/采购/销售闭环** 展开。
|
||
|
||
当前项目已经从早期单体演进为：
|
||
|
||
- **gemold（moldinsight）模块**：模具分析、几何处理、批量分析、成本估算、结果导出
|
||
- **inventory 模块**：产品、BOM、库存、采购、销售、财务
|
||
- **frontend 模块**：Vue 3 前端工程
|
||
- **shared 平台层**：配置、数据库、认证、日志、应用工厂
|
||
|
||
项目当前采用：
|
||
|
||
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
|
||
|
||
详细重构方向见：[BACKEND_MODULARIZATION_BLUEPRINT.md](docs/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 类型生成**
|
||
|
||
---
|
||
|
||
## 当前项目结构
|
||
|
||
> 下述结构反映的是**当前代码现状**，不是历史单体结构。
|
||
|
||
```text
|
||
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/moldinsight/)
|
||
- [src/celery_app.py](src/celery_app.py)
|
||
- [src/celery_tasks.py](src/celery_tasks.py)
|
||
|
||
### 2. inventory
|
||
|
||
主要负责：
|
||
- 成品/物料管理
|
||
- BOM
|
||
- 库存与库存流水
|
||
- 采购订单 / 销售订单
|
||
- 财务与对账
|
||
- 采购建议推导
|
||
|
||
关键目录：
|
||
- [src/inventory/](src/inventory/)
|
||
|
||
### 3. frontend
|
||
|
||
主要负责：
|
||
- 模具分析页面
|
||
- 进销存页面
|
||
- 登录/用户管理
|
||
- 统一路由与状态管理
|
||
- 基于 OpenAPI 生成类型的前端 API 调用
|
||
|
||
关键目录：
|
||
- [frontend/](frontend/)
|
||
|
||
### 4. shared（当前平台层）
|
||
|
||
主要负责：
|
||
- 配置
|
||
- 数据库连接与 session
|
||
- 认证与权限
|
||
- 日志与 request_id
|
||
- 应用工厂与通用中间件
|
||
|
||
关键目录：
|
||
- [src/shared/](src/shared/)
|
||
|
||
> 说明：后续会逐步将 `shared` 收敛为更清晰的 `platform` 语义，见 [BACKEND_MODULARIZATION_BLUEPRINT.md](docs/BACKEND_MODULARIZATION_BLUEPRINT.md)。
|
||
|
||
---
|
||
|
||
## 部署模式
|
||
|
||
当前项目设计上支持三种模式：
|
||
|
||
### 1. unified
|
||
一个统一后端同时挂载 gemold + inventory。
|
||
|
||
适合：
|
||
- 本地开发
|
||
- 集成环境
|
||
- 小团队统一部署
|
||
|
||
### 2. gemold-only
|
||
只部署模具分析后端。
|
||
|
||
适合：
|
||
- 单独开放分析能力
|
||
- 分析任务独立扩容
|
||
- 文件处理与异步任务独立部署
|
||
|
||
入口参考：
|
||
- [src/entrypoints/moldinsight.py](src/entrypoints/moldinsight.py)
|
||
|
||
### 3. inventory-only
|
||
只部署进销存后端。
|
||
|
||
适合：
|
||
- 仅使用 ERP / 库存能力
|
||
- 与 gemold 分开部署节奏
|
||
|
||
入口参考：
|
||
- [src/entrypoints/inventory.py](src/entrypoints/inventory.py)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
## 1. 环境要求
|
||
|
||
- Python 3.12
|
||
- PostgreSQL 15+（服务器已部署或自行提供）
|
||
- Redis（服务器已部署或自行提供）
|
||
- 对象存储（MinIO / RustFS 兼容；gemold 模块需要，服务器已部署或自行提供）
|
||
- Node.js 20+（前端开发需要）
|
||
- 推荐使用 `docker-compose.yml` 仅启动项目自身服务，复用服务器已有 PostgreSQL / Redis / 对象存储
|
||
|
||
---
|
||
|
||
## 2. 安装后端依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
如果需要几何分析能力，还需确保 PythonOCC 运行环境可用。项目中已说明其通常通过 conda 提供，而不是直接由 pip 安装。
|
||
|
||
---
|
||
|
||
## 3. 配置环境变量
|
||
|
||
复制并编辑：
|
||
|
||
- [`.env.example`](.env.example)
|
||
- 部署场景也可参考 [deploy/.env.example](deploy/.env.example)
|
||
|
||
最少需要关注：
|
||
|
||
```env
|
||
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](src/shared/config/settings.py)
|
||
- [.env.example](.env.example)
|
||
|
||
---
|
||
|
||
## 4. 初始化数据库
|
||
|
||
项目当前使用 Alembic 管理迁移。应用启动时也会执行初始化逻辑，但首次部署建议显式执行迁移流程。
|
||
|
||
如需查看初始化实现，可参考：
|
||
- [init_db.py](src/shared/database/init_db.py)
|
||
|
||
---
|
||
|
||
## 5. 启动方式
|
||
|
||
### 方式 A：使用根目录 Compose（推荐）
|
||
|
||
当前唯一 Compose 入口：
|
||
- [docker-compose.yml](docker-compose.yml)
|
||
|
||
该 compose 文件**只启动项目自身容器**：
|
||
- `moldinsight`
|
||
- `moldinsight-celery`
|
||
- `inventory`
|
||
|
||
并通过 `.env` 连接服务器上**已经存在**的：
|
||
- PostgreSQL
|
||
- Redis
|
||
- RustFS / MinIO 兼容对象存储
|
||
|
||
示例：
|
||
|
||
```bash
|
||
docker compose --profile full up -d
|
||
```
|
||
|
||
可选 profile：
|
||
- `full`
|
||
- `moldinsight`
|
||
- `inventory`
|
||
|
||
> 说明：`docker-compose.yml` 不再重复部署 postgres / redis / minio，而是复用服务器现有基础设施。
|
||
|
||
### 方式 B：直接启动后端入口
|
||
|
||
gemold-only：
|
||
|
||
```bash
|
||
uvicorn src.entrypoints.moldinsight:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
inventory-only：
|
||
|
||
```bash
|
||
uvicorn src.entrypoints.inventory:app --reload --host 0.0.0.0 --port 8001
|
||
```
|
||
|
||
### 方式 C：启动前端
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
生产构建：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 健康检查与接口
|
||
|
||
### 健康检查
|
||
|
||
两类后端都通过共享 app factory 暴露健康检查：
|
||
|
||
- `GET /health`
|
||
- `POST /health`
|
||
|
||
参考实现：
|
||
- [app_factory.py](src/shared/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](openapi.json)
|
||
- [frontend/src/types/api.ts](frontend/src/types/api.ts)
|
||
|
||
---
|
||
|
||
## 当前架构重点说明
|
||
|
||
### 1. gemold 与 inventory 已基本模块化
|
||
|
||
当前代码层面，`src/moldinsight/` 与 `src/inventory/` 已基本无直接互相依赖，说明业务边界已经初步成型。
|
||
|
||
### 2. 当前最大耦合点在 shared + 共享 ORM
|
||
|
||
需要特别注意：
|
||
|
||
- [src/shared/models/database.py](src/shared/models/database.py) 同时定义了 identity、gemold、inventory 的 ORM 模型
|
||
- [src/shared/app_factory.py](src/shared/app_factory.py) 仍承担较多平台与模块组合职责
|
||
|
||
这也是下一阶段重构的重点。
|
||
|
||
### 3. 单数据库是刻意选择
|
||
|
||
项目不是把 gemold 与 inventory 拆成两个数据库，而是保留一个共享数据库，用于支撑完整业务闭环：
|
||
|
||
- 分析结果
|
||
- 创建成品
|
||
- 成品 BOM
|
||
- 销售 / 采购 / 库存
|
||
|
||
典型桥接点：
|
||
- `STPFile.product_id -> Product.id`
|
||
|
||
---
|
||
|
||
## 开发与演进文档
|
||
|
||
推荐先阅读：
|
||
|
||
- [BACKEND_MODULARIZATION_BLUEPRINT.md](docs/BACKEND_MODULARIZATION_BLUEPRINT.md) — 当前模块化重构蓝图
|
||
- [EVOLUTION_ROADMAP.md](docs/EVOLUTION_ROADMAP.md) — 历史演进与阶段任务
|
||
- [docs/deployment/](docs/deployment/) — 现有部署文档（部分仍在对齐中）
|
||
|
||
---
|
||
|
||
## 开发建议
|
||
|
||
- 新增业务逻辑优先放入对应业务模块，不要继续堆进 `shared`
|
||
- 新增 API 时优先考虑模块归属，而不是“能放就放”
|
||
- 前端优先通过域 API client 调用接口，而不是散落裸 `/api/...` 路径
|
||
- 数据模型改动要同时考虑表归属与 Alembic 迁移影响
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。
|