geMoldInsight/README.md

# geMoldInsight

<div align="center">

![Version](https://img.shields.io/badge/version-v4.0.0-blue)
![Python](https://img.shields.io/badge/python-3.12-blue)
![FastAPI](https://img.shields.io/badge/fastapi-0.100.0-green)
![Vue.js](https://img.shields.io/badge/vue.js-3-green)
![PostgreSQL](https://img.shields.io/badge/postgresql-15-blue)
![License](https://img.shields.io/badge/license-MIT-green)

</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/                        # 镜像构建、Nginx 配置与部署辅助文件
│   ├── Dockerfile.base
│   ├── Dockerfile.moldinsight
│   ├── Dockerfile.inventory
│   ├── Dockerfile.celery
│   ├── Dockerfile.frontend
│   └── nginx/
│
├── 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，并作为前端同域反代的默认 backend。

适合：
- 本地开发
- 集成环境
- 小团队统一部署
- 前端独立部署 + 单 upstream 反代

### 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 文件会启动：
- `frontend`（独立前端 Nginx 静态站点）
- `backend`（unified backend，当前推荐）
- `moldinsight-celery`
- 可选保留：`moldinsight` / `inventory`（模块独立部署 profile）

其中：
- 前端通过同域反代把 `/api`、`/health`、`/html` 转发给 unified backend
- PostgreSQL / Redis / RustFS / MinIO 兼容对象存储仍由服务器现有服务提供

示例：

```bash
docker compose --profile full up -d
```

可选 profile：
- `full`
- `frontend`
- `unified`
- `moldinsight`
- `inventory`

> 说明：根目录 `docker-compose.yml` 是当前唯一 Compose 入口；前端已独立部署，并默认反代到 unified backend。

### 方式 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)。