geMoldInsight/README.md

geMoldInsight

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

当前实现状态：见 docs/STATUS.md 当前架构与边界：见 docs/ARCHITECTURE.md 本文是唯一文档导航入口：请按角色或主题跳转到对应主文档

---

项目概览

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

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

项目当前采用：

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

更详细的结构说明见 docs/ARCHITECTURE.md。

---

快速开始（三步）

1. 安装依赖

pip install -r requirements.txt

前端开发需要：

cd frontend
npm install

2. 配置环境变量

复制并编辑：

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

3. 启动

推荐先查看部署入口：

• docs/DEPLOYMENT.md

本地常见方式（按模式对应不同 compose 文件）：

# 默认：unified（前端 + 后端 + Celery）
docker compose up -d

# 仅模具分析
docker compose -f docker-compose.moldinsight.yml up -d

# 仅进销存
docker compose -f docker-compose.inventory.yml up -d

镜像首次构建：bash deploy/build.sh（build base → backend → celery → frontend 4 个 tag）。

如需直接运行：

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 安装。

---

目录概览

geMoldInsight/
├── src/
│   ├── entrypoints/               # 独立部署入口
│   ├── shared/                    # 当前共享平台层
│   ├── moldinsight/               # 模具分析模块
│   ├── inventory/                 # 进销存模块
│   ├── celery_app.py              # Celery app
│   └── celery_tasks.py            # moldinsight 异步任务
├── frontend/                      # 独立前端工程
├── migrations/                    # 数据库迁移
├── deploy/                        # 镜像、Nginx、部署辅助文件
├── docs/
├── tests/
├── requirements.txt
└── .env.example

---

文档导航（唯一入口）

按主题阅读

文档	解决什么问题
AGENTS.md	项目开发规范、硬约束、代码地图、文档同步要求
docs/STATUS.md	当前实现状态（日志体，唯一归属）
docs/ARCHITECTURE.md	当前架构、模块边界、结构原则
docs/OPERATIONS.md	配置 / 启动 / 环境 / 运维硬性要求
docs/API_CONTRACT.md	前后端契约：端点总览、约定、OpenAPI 类型生成
docs/ROADMAP.md	后续演进路线与阶段计划
docs/TECH_DEBT.md	当前活跃技术债与治理计划
docs/DEPLOYMENT.md	部署主题入口与部署文档分工
docs/deployment/LINUX_SETUP.md	Linux 环境下的详细部署步骤
docs/archive/BACKEND_MODULARIZATION_BLUEPRINT.md	模块化蓝图档案与补充设计讨论

按角色阅读

你是	建议阅读顺序
第一次了解项目	本文 → docs/STATUS.md → docs/ARCHITECTURE.md
开发者 / 改代码	AGENTS.md → docs/ARCHITECTURE.md → docs/API_CONTRACT.md → docs/TECH_DEBT.md
运维 / 部署	本文 → docs/OPERATIONS.md → docs/DEPLOYMENT.md → docs/deployment/LINUX_SETUP.md
规划 / 重构	本文 → docs/ROADMAP.md → docs/TECH_DEBT.md

---

核心能力

模块	能力
moldinsight	STEP/STP 上传、几何分析、特征识别、模具方案、批量分析、成本估算、结果导出
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 类型生成

---

当前代码入口

• unified： src/entrypoints/unified.py
• moldinsight-only： src/entrypoints/moldinsight.py
• inventory-only： src/entrypoints/inventory.py

当前 Compose 入口（一键命令对应文件名）：

• unified： docker-compose.yml → docker compose up -d
• moldinsight-only： docker-compose.moldinsight.yml → docker compose -f docker-compose.moldinsight.yml up -d
• inventory-only： docker-compose.inventory.yml → docker compose -f docker-compose.inventory.yml up -d

---

开发建议

• 新增业务逻辑优先放入对应业务模块，不要继续堆进 shared
• 新增 API 时优先考虑模块归属，而不是“能放就放”
• 文档状态统一维护在 docs/STATUS.md
• 部署方式变化统一更新 docs/DEPLOYMENT.md

---

许可证

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