cjw
b03431b511
- DEPLOYMENT §1.2 / LINUX_SETUP §11 / README / OPERATIONS 补充： docker compose up -d 对本地已有同名镜像不会自动重建，更新代码后 需 up -d --build 或先 build（部署机实测复用旧镜像后澄清） - build.sh 描述由四步修正为 base → backend → frontend 三步（celery 复用 backend 镜像，随 Dockerfile.celery 移除的文档收尾） Co-Authored-By: Claude Code <noreply@anthropic.com>
206 lines
6.9 KiB
Markdown
206 lines
6.9 KiB
Markdown
# geMoldInsight
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</div>
|
||
|
||
geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STEP/STP 模型分析、模具方案生成、分析结果沉淀、成品创建、BOM/库存/采购/销售闭环** 展开。
|
||
|
||
> **当前实现状态**：见 [docs/STATUS.md](docs/STATUS.md)
|
||
> **当前架构与边界**：见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
|
||
> **本文是唯一文档导航入口**：请按角色或主题跳转到对应主文档
|
||
|
||
---
|
||
|
||
## 项目概览
|
||
|
||
当前项目已经从早期单体演进为：
|
||
|
||
- **moldinsight 模块**：模具分析、几何处理、批量分析、成本估算、结果导出
|
||
- **inventory 模块**：产品、BOM、库存、采购、销售、财务
|
||
- **frontend 模块**：Vue 3 前端工程
|
||
- **shared 平台层**：配置、数据库、认证、日志、应用工厂
|
||
|
||
项目当前采用：
|
||
|
||
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
|
||
|
||
更详细的结构说明见 [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)
|
||
|
||
本地常见方式（按模式对应不同 compose 文件）：
|
||
|
||
```bash
|
||
# 默认：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 → frontend 3 个 tag，celery 复用 backend）；更新代码后用 `docker compose up -d --build` 重建（裸 `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/ # 独立前端工程
|
||
├── migrations/ # 数据库迁移
|
||
├── deploy/ # 镜像、Nginx、部署辅助文件
|
||
├── docs/
|
||
├── tests/
|
||
├── requirements.txt
|
||
└── .env.example
|
||
```
|
||
|
||
---
|
||
|
||
## 文档导航（唯一入口）
|
||
|
||
### 按主题阅读
|
||
|
||
| 文档 | 解决什么问题 |
|
||
|---|---|
|
||
| [AGENTS.md](AGENTS.md) | 项目开发规范、硬约束、代码地图、文档同步要求 |
|
||
| [docs/STATUS.md](docs/STATUS.md) | 当前实现状态（日志体，唯一归属） |
|
||
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 当前架构、模块边界、结构原则 |
|
||
| [docs/OPERATIONS.md](docs/OPERATIONS.md) | 配置 / 启动 / 环境 / 运维硬性要求 |
|
||
| [docs/API_CONTRACT.md](docs/API_CONTRACT.md) | 前后端契约：端点总览、约定、OpenAPI 类型生成 |
|
||
| [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) |
|
||
| 开发者 / 改代码 | [AGENTS.md](AGENTS.md) → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) → [docs/API_CONTRACT.md](docs/API_CONTRACT.md) → [docs/TECH_DEBT.md](docs/TECH_DEBT.md) |
|
||
| 运维 / 部署 | 本文 → [docs/OPERATIONS.md](docs/OPERATIONS.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) |
|
||
|
||
---
|
||
|
||
## 核心能力
|
||
|
||
| 模块 | 能力 |
|
||
|---|---|
|
||
| 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](src/entrypoints/unified.py)
|
||
- moldinsight-only： [src/entrypoints/moldinsight.py](src/entrypoints/moldinsight.py)
|
||
- inventory-only： [src/entrypoints/inventory.py](src/entrypoints/inventory.py)
|
||
|
||
当前 Compose 入口（一键命令对应文件名）：
|
||
|
||
- unified： [docker-compose.yml](docker-compose.yml) → `docker compose up -d`
|
||
- moldinsight-only： [docker-compose.moldinsight.yml](docker-compose.moldinsight.yml) → `docker compose -f docker-compose.moldinsight.yml up -d`
|
||
- inventory-only： [docker-compose.inventory.yml](docker-compose.inventory.yml) → `docker compose -f docker-compose.inventory.yml up -d`
|
||
|
||
---
|
||
|
||
## 开发建议
|
||
|
||
- 新增业务逻辑优先放入对应业务模块，不要继续堆进 `shared`
|
||
- 新增 API 时优先考虑模块归属，而不是“能放就放”
|
||
- 文档状态统一维护在 [docs/STATUS.md](docs/STATUS.md)
|
||
- 部署方式变化统一更新 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。
|