cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档目录结构简洁化

Browse Source
This commit is contained in:
chenjw28
2026-09-01 18:05:18 +08:00
parent bee439cf34
commit 5e531ffe1e
47 changed files with 1334 additions and 3380 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+126 -391
View File
@@ -11,11 +11,19 @@
</div>
geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STP/STEP 模型分析、模具方案生成、分析结果沉淀、成品创建、BOM/库存/采购/销售闭环** 展开。
geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STEP/STP 模型分析、模具方案生成、分析结果沉淀、成品创建、BOM/库存/采购/销售闭环** 展开。
> **当前实现状态**：见 [docs/STATUS.md](docs/STATUS.md)
> **当前架构与边界**：见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
> **本文是唯一文档导航入口**：请按角色或主题跳转到对应主文档
---
## 项目概览
当前项目已经从早期单体演进为：
- **gemold（moldinsight）模块**：模具分析、几何处理、批量分析、成本估算、结果导出
- **moldinsight 模块**：模具分析、几何处理、批量分析、成本估算、结果导出
- **inventory 模块**：产品、BOM、库存、采购、销售、财务
- **frontend 模块**：Vue 3 前端工程
- **shared 平台层**：配置、数据库、认证、日志、应用工厂
@@ -24,7 +32,98 @@ geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STP/ST
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
详细重构方向见：[BACKEND_MODULARIZATION_BLUEPRINT.md](docs/BACKEND_MODULARIZATION_BLUEPRINT.md)
更详细的结构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
---
## 快速开始（三步）
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
前端开发需要：
```bash
cd frontend
npm install
```
### 2. 配置环境变量
复制并编辑：
- [`.env.example`](.env.example)
- 部署场景可参考 [deploy/.env.example](deploy/.env.example)
### 3. 启动
推荐先查看部署入口：
- [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
本地常见方式：
```bash
docker compose --profile full up -d
```
如需直接运行：
```bash
uvicorn src.entrypoints.moldinsight:app --reload --host 0.0.0.0 --port 8000
uvicorn src.entrypoints.inventory:app --reload --host 0.0.0.0 --port 8001
```
> 如需 OCC 几何分析能力，请准备 PythonOCC 运行环境。项目中通常通过 conda 提供，而不是仅靠 pip 安装。
---
## 目录概览
```text
geMoldInsight/
├── src/
│ ├── entrypoints/ # 独立部署入口
│ ├── shared/ # 当前共享平台层
│ ├── moldinsight/ # 模具分析模块
│ ├── inventory/ # 进销存模块
│ ├── celery_app.py # Celery app
│ └── celery_tasks.py # moldinsight 异步任务
├── frontend/ # 独立前端工程
├── alembic/ # 数据库迁移
├── deploy/ # 镜像、Nginx、部署辅助文件
├── docs/
├── tests/
├── requirements.txt
└── .env.example
```
---
## 文档导航（唯一入口）
### 按主题阅读
| 文档 | 解决什么问题 |
|---|---|
| [docs/STATUS.md](docs/STATUS.md) | 当前实现状态、当前推荐方案、近期完成项 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 当前架构、模块边界、结构原则 |
| [docs/ROADMAP.md](docs/ROADMAP.md) | 后续演进路线与阶段计划 |
| [docs/TECH_DEBT.md](docs/TECH_DEBT.md) | 当前活跃技术债与治理计划 |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 部署主题入口与部署文档分工 |
| [docs/deployment/LINUX_SETUP.md](docs/deployment/LINUX_SETUP.md) | Linux 环境下的详细部署步骤 |
| [docs/archive/BACKEND_MODULARIZATION_BLUEPRINT.md](docs/archive/BACKEND_MODULARIZATION_BLUEPRINT.md) | 模块化蓝图档案与补充设计讨论 |
### 按角色阅读
| 你是 | 建议阅读顺序 |
|---|---|
| 第一次了解项目 | 本文 → [docs/STATUS.md](docs/STATUS.md) → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| 开发者 / 改代码 | 本文 → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) → [docs/TECH_DEBT.md](docs/TECH_DEBT.md) → 相关专题文档 |
| 运维 / 部署 | 本文 → [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) → [docs/deployment/LINUX_SETUP.md](docs/deployment/LINUX_SETUP.md) |
| 规划 / 重构 | 本文 → [docs/ROADMAP.md](docs/ROADMAP.md) → [docs/TECH_DEBT.md](docs/TECH_DEBT.md) |
---
@@ -32,7 +131,7 @@ geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STP/ST
| 模块 | 能力 |
|---|---|
| gemold | STP/STEP 上传、几何分析、特征识别、模具方案、批量分析、成本估算、结果导出 |
| moldinsight | STEP/STP 上传、几何分析、特征识别、模具方案、批量分析、成本估算、结果导出 |
| inventory | 成品/物料、BOM、库存、库存流水、采购订单、销售订单、财务、采购建议 |
| integration | 分析结果一键创建成品，打通“模具分析 → 成品 → BOM → 销售/采购/库存” |
| platform | 用户、角色、权限、JWT 鉴权、数据库连接、日志、健康检查 |
@@ -42,399 +141,35 @@ geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STP/ST
## 技术栈
### 后端
- **FastAPI**
- **SQLAlchemy 2.0**
- **PostgreSQL**
- **Alembic**
- **Redis**
- **Celery**
- **PythonOCC / trimesh / pyvista**
- **RustFS / MinIO 兼容对象存储**
- FastAPI
- SQLAlchemy 2.0
- PostgreSQL
- Alembic
- Redis
- Celery
- PythonOCC / trimesh / pyvista
- RustFS / MinIO 兼容对象存储
### 前端
- **Vue 3**
- **Vite**
- **TypeScript**
- **Pinia**
- **Vue Router**
- **TDesign Vue Next**
- Vue 3
- Vite
- TypeScript
- Pinia
- Vue Router
- TDesign Vue Next
### 基础设施
- **Docker / Docker Compose**
- **结构化日志 / request_id**
- **OpenAPI → TypeScript 类型生成**
- 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/) — 现有部署文档（部分仍在对齐中）
- moldinsight-only： [src/entrypoints/moldinsight.py](src/entrypoints/moldinsight.py)
- inventory-only： [src/entrypoints/inventory.py](src/entrypoints/inventory.py)
- 当前 Compose 入口： [docker-compose.yml](docker-compose.yml)
---
@@ -442,8 +177,8 @@ npm run build
- 新增业务逻辑优先放入对应业务模块，不要继续堆进 `shared`
- 新增 API 时优先考虑模块归属，而不是“能放就放”
- 前端优先通过域 API client 调用接口，而不是散落裸 `/api/...` 路径
- 数据模型改动要同时考虑表归属与 Alembic 迁移影响
- 文档状态统一维护在 [docs/STATUS.md](docs/STATUS.md)
- 部署方式变化统一更新 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
---