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

x

Browse Source
This commit is contained in:
chenjw28
2026-09-02 18:18:42 +08:00
parent 5e531ffe1e
commit 4fbff0761a
18 changed files with 239 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+137
View File
@@ -0,0 +1,137 @@
# AGENTS.md - geMoldInsight 开发规范
> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的项目入口约定。**开始任何实现前先读本文件**。
> 人类入口见 [README.md](README.md)；当前实现状态见 [docs/STATUS.md](docs/STATUS.md)；当前架构与边界见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 1. 项目定位
**geMoldInsight** 是一个面向模具制造场景的综合系统，围绕：
- STEP / STP 模型分析
- 模具方案生成
- 分析结果沉淀与导出
- 成品创建
- BOM / 库存 / 采购 / 销售闭环
当前整体形态为：
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
核心模块：
- `moldinsight`：模具分析、几何处理、批量分析、成本估算、结果导出
- `inventory`：产品、BOM、库存、采购、销售、财务
- `frontend`：Vue 3 前端工程
- `shared`：配置、数据库、认证、日志、应用工厂等共享平台层
## 2. 硬约束速览（违反即返工）
- **执行前必须先同步方案到文档**：开始实施前，必须先把方案写入对应文档，再按照文档中的步骤逐项执行，不能先改代码后补文档。
- **每次完成需求都必须更新文档**：每完成一个需求，都必须同步更新相关文档，保持文档为最新状态，避免实现与文档漂移。
- **README 只做导航入口**：不在 README 重复维护状态、架构、规划、部署细节。
- **当前实现状态只在 [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) 维护**。
- **历史材料统一进入 [docs/archive/](docs/archive/)**，不与当前权威文档混放。
- **新增业务逻辑优先进入对应模块**，不要继续把业务逻辑堆进 `shared`。
- **接口变更优先补契约与请求模型**，减少手写 `request.json()` 风格解析。
## 3. 代码地图
```text
geMoldInsight/
├── src/
│ ├── entrypoints/ # 独立部署入口（moldinsight / inventory / unified）
│ ├── moldinsight/ # 模具分析模块
│ │ ├── api/ # 模具分析 API
│ │ ├── services/ # 业务服务层
│ │ ├── core/ # 几何 / 算法 / OCC 核心能力
│ │ └── ...
│ ├── inventory/ # 进销存模块
│ │ ├── api/ # 进销存 API
│ │ ├── services/ # 业务服务层
│ │ └── ...
│ ├── shared/ # 当前共享平台层（配置 / DB / 认证 / 日志 / app factory）
│ ├── celery_app.py # Celery app
│ └── celery_tasks.py # moldinsight 异步任务
├── frontend/ # Vue 3 独立前端工程
├── alembic/ # 数据库迁移
├── deploy/ # Docker / Nginx / 部署辅助文件
├── docs/ # 当前权威文档与主题文档
├── tests/ # 测试
└── README.md # 人类入口与最短启动说明
```
## 4. 开发规范
### 4.1 文档先行
所有非微小改动都遵循：
1. 先明确改动范围与目标
2. 先把实施方案同步到文档
3. 再按文档步骤执行实现
4. 完成后回填结果、状态、约束变化
如果方案变化，必须先更新文档，再继续实现。
### 4.2 文档更新规则
完成需求后，至少检查并更新这些文档中的相关项：
- 实现状态变化：更新 [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)
- 历史/阶段性材料：必要时迁入 [docs/archive/README.md](docs/archive/README.md) 所索引的位置
### 4.3 代码组织规则
- `moldinsight` 业务代码进入 `src/moldinsight/`
- `inventory` 业务代码进入 `src/inventory/`
- 真正跨模块复用的基础能力才进入 `src/shared/`
- 尽量避免继续扩大 `shared` 的业务组合职责
- 新增 API 时优先考虑模块归属、service 复用与请求模型规范化
### 4.4 API 与契约规则
- 优先使用明确的请求模型和参数校验
- 尽量减少手写 `await request.json()` / `request.json()` 解析
- 路由文件过大时按职责拆分，避免单 router 混合过多领域能力
- 返回结构、接口路径、前后端契约发生变化时，要同步更新相关文档
### 4.5 文档体系规则
- README 只做导航与最短入门
- 当前状态只在 [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/archive/](docs/archive/)
## 5. 开发完成后的最小检查清单
每次完成需求后，至少确认：
- 代码已按模块边界落位
- 相关测试已执行或说明未执行原因
- 相关文档已同步更新
- `STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT` 没有与实现冲突的地方
- 新增历史性说明没有误放进当前权威文档
## 6. 文档导航
| 文档 | 用途 |
|---|---|
| [AGENTS.md](AGENTS.md) | 项目开发规范、开发约束、文档同步要求 |
| [README.md](README.md) | 人类入口、最短启动说明、文档导航 |
| [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/README.md](docs/archive/README.md) | 历史文档与阶段性材料归档入口 |
README.md
+1
View File
@@ -108,6 +108,7 @@ geMoldInsight/
| 文档 | 解决什么问题 |
|---|---|
| [AGENTS.md](AGENTS.md) | 项目开发规范、开发约束、文档同步要求 |
| [docs/STATUS.md](docs/STATUS.md) | 当前实现状态、当前推荐方案、近期完成项 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 当前架构、模块边界、结构原则 |
| [docs/ROADMAP.md](docs/ROADMAP.md) | 后续演进路线与阶段计划 |
docs/ARCHITECTURE.md
+2 -8
View File
@@ -196,17 +196,11 @@ geMoldInsight/
以下文档仍可作为专题补充参考，但不再承担默认入口职责：
- AI / FreeCAD 方向：
- [topics/ai/AI_ENGINE_DESIGN.md](topics/ai/AI_ENGINE_DESIGN.md)
- [topics/ai/AI_FREECAD_INTEGRATION.md](topics/ai/AI_FREECAD_INTEGRATION.md)
- 存储方向：
- [topics/storage/RUSTFS_STORAGE.md](topics/storage/RUSTFS_STORAGE.md)
- [topics/storage/STORAGE_SETUP.md](topics/storage/STORAGE_SETUP.md)
- 铝泡沫模具专题：
- [topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md](topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md)
- 性能专题：
- [topics/performance/PERFORMANCE_SCALABILITY_PLAN.md](topics/performance/PERFORMANCE_SCALABILITY_PLAN.md)
- [topics/performance/PERFORMANCE_BENCHMARKS.md](topics/performance/PERFORMANCE_BENCHMARKS.md)
AI、性能、铝泡沫等更偏历史设计/规划性质的专题材料已迁入 [archive/README.md](archive/README.md)。
阶段性任务清单、迁移计划、历史总结等文档会逐步迁入 [archive/README.md](archive/README.md)。
docs/DEPLOYMENT.md
+8 -4
View File
@@ -9,7 +9,7 @@
当前推荐模式为：
- **unified**：frontend + unified backend + moldinsight celery
- **unified**：frontend + unified backend + moldinsight Celery worker
原因：
- 适合本地开发与集成环境
@@ -66,11 +66,15 @@
### 3.2 端口与配置说明
以下文档当前仍保留，但后续会继续收敛：
以下文档作为当前部署补充说明保留：
- [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)
- [deployment/PORT_CONFIG.md](deployment/PORT_CONFIG.md)
它们描述的是端口与环境配置细节，不应替代部署入口文档。
它们的职责分别是：
- `DEPLOY_PORT.md`：端口暴露、端口规划与 Nginx / 防火墙层面的说明
- `PORT_CONFIG.md`：环境变量、端口配置项与 direct run / compose 映射补充
它们是部署入口文档的补充参考，不替代本文或 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)。
### 3.3 历史/阶段性部署材料
@@ -78,7 +82,7 @@
- [archive/PORT_REFACTOR_SUMMARY.md](archive/PORT_REFACTOR_SUMMARY.md)
- [archive/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md](archive/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md)
这些材料已迁入 `docs/archive/`。
这些材料已迁入 `docs/archive/`，仅用于历史追溯，不替代当前的 [DEPLOYMENT.md](DEPLOYMENT.md) 、 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md) 与 [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)。
---
docs/STATUS.md
+1 -1
View File
@@ -94,7 +94,7 @@ geMoldInsight 当前已从早期单体演进为：
当前已验证：
- 本地 pip 环境：**47 passed, 1 skipped**
- gemold conda + OCC 环境：**88 passed**
- moldinsight conda + OCC 环境：**88 passed**
说明：
- 无 OCC 环境下，依赖 pythonocc 的契约测试会自动 skip
docs/archive/README.md
+15 -1
View File
@@ -1,7 +1,7 @@
# 文档归档说明（archive）
> 文档定位：**历史文档与阶段性材料归档目录**。
> 当前权威文档请优先查看：
> archive 仅保存历史迁移说明、阶段性计划与已不再作为默认入口的旧文档；当前权威内容请优先查看 `docs/` 主骨架：
> - [../STATUS.md](../STATUS.md)
> - [../ARCHITECTURE.md](../ARCHITECTURE.md)
> - [../ROADMAP.md](../ROADMAP.md)
@@ -19,3 +19,17 @@
- [TASKS_ALUMINUM_FOAM_MOLD.md](TASKS_ALUMINUM_FOAM_MOLD.md)
- [CHECKLIST_ALUMINUM_FOAM_MOLD.md](CHECKLIST_ALUMINUM_FOAM_MOLD.md)
- [DELIVERABLES.md](DELIVERABLES.md)
- [EVOLUTION_ROADMAP.md](EVOLUTION_ROADMAP.md)
- [MOLDINSIGHT_TECH_DEBT_PLAN.md](MOLDINSIGHT_TECH_DEBT_PLAN.md)
- [BACKEND_MODULARIZATION_BLUEPRINT.md](BACKEND_MODULARIZATION_BLUEPRINT.md)
- [MOLD_ERP_ANALYSIS_REPORT.md](MOLD_ERP_ANALYSIS_REPORT.md)
- [ZERO_FINISHED_INVENTORY_CERTIFICATE.md](ZERO_FINISHED_INVENTORY_CERTIFICATE.md)
- [CONFLUENCE_ARCHIVE_STRUCTURE.md](CONFLUENCE_ARCHIVE_STRUCTURE.md)
- [topics/ai/](topics/ai/)：已迁移的 AI 相关专题历史材料
- [topics/performance/](topics/performance/)：已迁移的性能专题历史材料
- [topics/aluminum-foam/](topics/aluminum-foam/)：已迁移的铝泡沫专题历史材料
部署相关的归档文档仅用于历史追溯；当前对应入口请查看：
- [../DEPLOYMENT.md](../DEPLOYMENT.md)
- [../deployment/LINUX_SETUP.md](../deployment/LINUX_SETUP.md)
- [../deployment/DEPLOY_PORT.md](../deployment/DEPLOY_PORT.md)
docs/topics/ai/AI_ENGINE_DESIGN.md → docs/archive/topics/ai/AI_ENGINE_DESIGN.md
+1 -1
View File
@@ -1,7 +1,7 @@
# AI 智能引擎设计文档
> 文档定位：**AI 能力方向的设计性/专题性文档**。
> 本文描述的是 AI 引擎的设计设想与能力规划，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，当前架构边界见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
> 本文描述的是 AI 引擎的设计设想与能力规划，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，当前架构边界见 [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
## 一、AI 引擎架构
### 1.1 整体架构
docs/topics/ai/AI_FREECAD_INTEGRATION.md → docs/archive/topics/ai/AI_FREECAD_INTEGRATION.md
+1 -1
View File
@@ -1,7 +1,7 @@
# AI + FreeCAD 集成方案
> 文档定位：**AI / FreeCAD 集成方向的专题设计文档**。
> 本文描述的是集成设想、能力规划与差距分析，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，当前架构边界见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
> 本文描述的是集成设想、能力规划与差距分析，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，当前架构边界见 [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
## 一、项目概述
本文档描述 geMoldInsight 项目集成 AI 智能引擎和 FreeCAD 的完整方案，实现真实的模具型腔生成和 G 代码输出功能。
docs/topics/ai/FREECAD_SETUP.md → docs/archive/topics/ai/FREECAD_SETUP.md
View File
docs/topics/ai/GCODE_GENERATION.md → docs/archive/topics/ai/GCODE_GENERATION.md
View File
docs/topics/aluminum-foam/MOLD_SPLITTING_IMPROVEMENTS.md → docs/archive/topics/aluminum-foam/MOLD_SPLITTING_IMPROVEMENTS.md
View File
docs/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md → docs/archive/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md
+1 -1
View File
@@ -1,7 +1,7 @@
# 铝制家电包装泡沫模具分模功能技术规格说明书
> 文档定位：**铝泡沫模具分模方向的专题规格文档**。
> 本文保留该方向的需求背景、规格设想与能力边界，不作为当前项目整体状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，总体架构见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)，活跃技术债见 [../../TECH_DEBT.md](../../TECH_DEBT.md)。
> 本文保留该方向的需求背景、规格设想与能力边界，不作为当前项目整体状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，总体架构见 [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)，活跃技术债见 [../../../TECH_DEBT.md](../../../TECH_DEBT.md)。
## 文档信息
docs/topics/performance/PERFORMANCE_BENCHMARKS.md → docs/archive/topics/performance/PERFORMANCE_BENCHMARKS.md
+1 -1
View File
@@ -1,7 +1,7 @@
# 性能基准定义（建议）
> 文档定位：**性能基准与压测口径的专题参考文档**。
> 本文给出建议性性能指标与测试数据口径，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
> 本文给出建议性性能指标与测试数据口径，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
## 1. 核心接口基准
| 场景 | 接口 | 指标 |
docs/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md → docs/archive/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md
+1 -1
View File
@@ -1,7 +1,7 @@
# 性能与扩展性评估补充（模具订单/采购主线）
> 文档定位：**性能与扩展性方向的专题规划文档**。
> 本文描述的是性能评估、慢 SQL 发现、扩展路线等补充规划，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
> 本文描述的是性能评估、慢 SQL 发现、扩展路线等补充规划，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
## 1. 高并发冲突面与加固点
### 1.1 新增/修改模具订单的锁冲突来源
docs/deployment/DEPLOY_PORT.md
+21 -24
View File
@@ -2,19 +2,19 @@
> 文档定位：**当前部署下的端口规划补充说明**。
> 部署入口与当前推荐方案见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
> 本文档描述的是 **当前模块化部署模式** 下的端口规划，不再以历史单体 `src.main:app` 作为默认前提。
> 本文档负责 **当前模块化部署模式** 下的端口暴露、端口规划与 Nginx / 防火墙层面的补充说明，不再以历史单体 `src.main:app` 作为默认前提。
当前推荐部署对象：
- frontend（Nginx，同域入口）
- unified backend
- gemold Celery worker（无 HTTP 端口）
- moldinsight Celery worker（无 HTTP 端口）
以下基础设施默认由服务器现有服务提供，不在本项目 compose 中重复部署：
- PostgreSQL
- Redis
- MinIO / RustFS（gemold 需要）
- MinIO / RustFS（moldinsight 需要）
---
@@ -24,7 +24,7 @@
|---|---:|---|
| frontend | 80 | 前端 Nginx，同域入口 |
| unified backend | 8000 | 当前推荐统一后端 |
| gemold API | 8000 | 模具分析独立部署时使用 |
| moldinsight API | 8000 | 模具分析独立部署时使用 |
| inventory API | 8001 | 进销存独立部署时使用 |
| PostgreSQL | 5432 | 共享数据库 |
| Redis | 6379 | 共享队列/缓存 |
@@ -37,7 +37,7 @@
## 2. 三种部署模式下的端口
### 2.1 gemold-only
### 2.1 moldinsight-only
- 对外开放：`8000`
- 依赖：PostgreSQL、Redis、MinIO/RustFS
@@ -51,16 +51,13 @@
### 2.3 unified
两种常见实现：
当前推荐由 unified backend 提供单一后端入口：
1. **统一网关模式**
- 外部只开放 80/443
- 网关转发到 gemold / inventory
2. **统一应用组合模式**
- 统一后端监听单一端口
- 后续组合层重构完成后更适合采用
- 对外开放：`8000`（或由前置 Nginx / 网关统一暴露 80/443）
- 依赖：PostgreSQL、Redis、MinIO / RustFS
- 配套：moldinsight Celery worker 不直接暴露 HTTP 端口
当前阶段，如果需要统一对外，更推荐**网关统一**而不是继续依赖历史单体入口。
在生产环境中，仍推荐通过同域 Nginx / 网关统一对外暴露 80/443，再反代到 unified backend。
---
@@ -73,7 +70,7 @@
- `FRONTEND_PORT` → frontend Nginx 外部端口
- `BACKEND_PORT` → unified backend 外部端口
- `MOLDINSIGHT_PORT` → gemold-only 独立部署端口
- `MOLDINSIGHT_PORT` → moldinsight-only 独立部署端口
- `INVENTORY_PORT` → inventory-only 独立部署端口
示例：
@@ -85,14 +82,14 @@ INVENTORY_PORT=8001
对应 compose 行为：
- gemold：`${MOLDINSIGHT_PORT:-8000}:8000`
- moldinsight：`${MOLDINSIGHT_PORT:-8000}:8000`
- inventory：`${INVENTORY_PORT:-8001}:8001`
---
## 4. 直接运行时的端口约定
### gemold-only
### moldinsight-only
```bash
uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
@@ -105,7 +102,7 @@ uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
```
如果改端口：
- gemold 改 `--port`
- moldinsight 改 `--port`
- inventory 改 `--port`
- 同步更新 Nginx / 防火墙 / 前端 base URL
@@ -125,7 +122,7 @@ VITE_API_BASE_URL=https://api.example.com
### split 模式
```env
VITE_AUTH_API_BASE_URL=https://auth.example.com
VITE_MOLDINSIGHT_API_BASE_URL=https://gemold.example.com
VITE_MOLDINSIGHT_API_BASE_URL=https://moldinsight.example.com
VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
```
@@ -136,12 +133,12 @@ VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
## 6. Nginx 示例
### gemold-only
### moldinsight-only
```nginx
server {
listen 80;
server_name gemold.example.com;
server_name moldinsight.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
@@ -177,7 +174,7 @@ server {
如果不通过 Nginx 统一入口而是直接暴露服务端口，则应显式开放：
```bash
# gemold
# moldinsight
sudo ufw allow 8000/tcp
# inventory
@@ -205,6 +202,6 @@ curl http://127.0.0.1:8001/health
在当前模块化架构下：
- gemold 与 inventory 应视为**两个独立后端模块**
- 端口应按模块分配，而不是继续沿用单体“一个后端一个端口”的思路
- unified 更适合通过**组合层或网关**实现，而不是继续让历史单体入口承载全部语义
- moldinsight 与 inventory 应视为两个独立后端模块
- `unified` 是当前推荐部署模式，由 unified backend 提供单一后端入口
- 端口应按模块与部署模式清晰分配；生产环境通常通过同域 Nginx / 网关统一对外暴露 80/443
docs/deployment/LINUX_SETUP.md
+30 -29
View File
@@ -6,8 +6,8 @@
当前项目支持三种部署模式：
- **unified**：frontend + unified backend + celery，统一对外部署（当前推荐）
- **gemold-only**：仅部署模具分析后端
- **unified**：frontend + unified backend + moldinsight Celery worker，统一对外部署（当前推荐）
- **moldinsight-only**：仅部署模具分析后端
- **inventory-only**：仅部署进销存后端
项目保持：
@@ -34,10 +34,10 @@
### 按模块附加要求
#### gemold / unified 需要
#### moldinsight / unified 需要
- 服务器上已可访问的 MinIO 或 RustFS 兼容对象存储
- PythonOCC 运行环境
- Celery worker（推荐与 gemold 一起部署）
- Celery worker（推荐与 moldinsight 一起部署）
#### inventory-only 需要
- PostgreSQL
@@ -73,7 +73,7 @@ pip install --upgrade pip
pip install -r requirements.txt
```
> 如果需要 gemold 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
> 如果需要 moldinsight 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
---
@@ -117,7 +117,7 @@ RUSTFS_SECRET_KEY=minioadmin
```
说明：
- `RUSTFS_*` 仅 **gemold / unified** 模式需要
- `RUSTFS_*` 仅 **moldinsight / unified** 模式需要
- `inventory-only` 可不使用对象存储
- 当前配置读取实现见 [settings.py](../../src/shared/config/settings.py)
@@ -136,7 +136,7 @@ RUSTFS_SECRET_KEY=minioadmin
相关实现参考：
- [init_db.py](../../src/shared/database/init_db.py)
> 当前项目是 **单数据库** 设计，因此 unified / gemold-only / inventory-only 都连接到同一个数据库与同一 migration head。
> 当前项目是 **单数据库** 设计，因此 unified / moldinsight-only / inventory-only 都连接到同一个数据库与同一 migration head。
---
@@ -149,7 +149,7 @@ RUSTFS_SECRET_KEY=minioadmin
- `/` → 前端静态资源与 SPA 路由
- `/api` → unified backend
- `/health` → unified backend
- `/html` → unified backend（内部再提供 gemold 分析产物）
- `/html` → unified backend（内部再提供 moldinsight 分析产物）
如果使用根目录 [docker-compose.yml](../../docker-compose.yml) 的 `frontend` 服务，则该入口已经内置在前端 Nginx 镜像中。
@@ -168,7 +168,7 @@ uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
---
## 6.2 gemold-only
## 6.2 moldinsight-only
```bash
source .venv/bin/activate
@@ -179,7 +179,7 @@ uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
- 单独部署模具分析能力
- 文件上传 / 分析 / 导出 / 批量分析
### gemold Celery worker
### moldinsight Celery worker
建议同时启动 worker：
@@ -188,18 +188,19 @@ source .venv/bin/activate
celery -A src.celery_app.celery_app worker --loglevel=info
```
> gemold 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
> moldinsight 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
---
## 6.3 unified
当前仓库历史上存在过统一入口，但它更适合作为**过渡参考**，不建议再作为长期标准入口。
`unified` 是当前推荐的默认部署方式，适合 frontend 同域反代到单一 backend 的本地开发、集成环境与统一部署场景。
在正式完成组合层重构前，如需统一部署，可优先使用反向代理或部署编排层统一暴露 gemold 与 inventory；后续会演进为显式 `unified_app.py`。
如需按模块独立部署，则使用 `moldinsight-only` 或 `inventory-only` 入口；它们仍共享同一个仓库、同一个数据库与同一套基础设施。
蓝图参考：
- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
当前入口与部署编排见：
- [../../docker-compose.yml](../../docker-compose.yml)
- [../../src/entrypoints/unified.py](../../src/entrypoints/unified.py)
---
@@ -210,7 +211,7 @@ celery -A src.celery_app.celery_app worker --loglevel=info
创建：
```bash
sudo nano /etc/systemd/system/gemold-inventory.service
sudo nano /etc/systemd/system/moldinsight-inventory.service
```
```ini
@@ -236,18 +237,18 @@ WantedBy=multi-user.target
```bash
sudo systemctl daemon-reload
sudo systemctl enable gemold-inventory
sudo systemctl start gemold-inventory
sudo systemctl enable moldinsight-inventory
sudo systemctl start moldinsight-inventory
```
---
## 7.2 gemold-only API 服务
## 7.2 moldinsight-only API 服务
创建：
```bash
sudo nano /etc/systemd/system/gemold-moldinsight.service
sudo nano /etc/systemd/system/moldinsight-moldinsight.service
```
```ini
@@ -271,12 +272,12 @@ WantedBy=multi-user.target
---
## 7.3 gemold Celery worker 服务
## 7.3 moldinsight Celery worker 服务
创建：
```bash
sudo nano /etc/systemd/system/gemold-celery.service
sudo nano /etc/systemd/system/moldinsight-celery.service
```
```ini
@@ -309,7 +310,7 @@ WantedBy=multi-user.target
- `/` 提供前端静态资源与 SPA fallback
- `/api/` 反代后端
- `/health` 反代后端
- `/html/` 反代 gemold
- `/html/` 反代 moldinsight
### 8.1 inventory-only
@@ -328,12 +329,12 @@ server {
}
```
### 8.2 gemold-only
### 8.2 moldinsight-only
```nginx
server {
listen 80;
server_name gemold.example.com;
server_name moldinsight.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
@@ -361,7 +362,7 @@ inventory-only：
curl http://127.0.0.1:8001/health
```
gemold-only：
moldinsight-only：
```bash
curl http://127.0.0.1:8000/health
@@ -374,7 +375,7 @@ curl http://127.0.0.1:8000/health
- `/api/products` 返回数据
- `/api/inventory` 返回数据
#### gemold-only
#### moldinsight-only
- 登录接口可用
- `/api/upload` 可访问
- 上传后 worker 能正常消费任务
@@ -388,9 +389,9 @@ curl http://127.0.0.1:8000/health
因为当前项目已演进为模块化结构，`src.main:app` 更适合作为过渡兼容入口，而不是长期部署标准。应优先围绕 [entrypoints/](../../src/entrypoints/) 部署。
### 2. inventory-only 为什么不需要对象存储？
因为对象存储主要服务于 gemold 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
因为对象存储主要服务于 moldinsight 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
### 3. gemold-only 为什么建议同时部署 Celery？
### 3. moldinsight-only 为什么建议同时部署 Celery？
因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。
---
docs/deployment/PORT_CONFIG.md
+17 -37
View File
@@ -2,17 +2,15 @@
> 文档定位：**模块化部署下的端口与环境变量配置补充说明**。
> 当前部署主题入口见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，详细 Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
> 本文档说明当前 geMoldInsight 在**模块化部署**下的端口配置方式。
> 本文只补充环境变量、端口配置项与 direct run / compose 的映射；端口规划与对外暴露方式以 [DEPLOY_PORT.md](./DEPLOY_PORT.md) 为准。
当前架构中应区分：
当前配置中主要需要区分：
- **gemold API 端口**
- **moldinsight API 端口**
- **inventory API 端口**
- **数据库/Redis/对象存储端口**
- **数据库 / Redis / 对象存储端口**
- **前端访问地址**
不再推荐把所有部署场景都抽象成“单应用单端口”。
---
## 1. 当前主配置位置
@@ -54,7 +52,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
|---|---|
| `FRONTEND_PORT` | 前端 Nginx 宿主机暴露端口 |
| `BACKEND_PORT` | unified backend 宿主机暴露端口 |
| `MOLDINSIGHT_PORT` | gemold-only 独立部署端口 |
| `MOLDINSIGHT_PORT` | moldinsight-only 独立部署端口 |
| `INVENTORY_PORT` | inventory-only 独立部署端口 |
| `DB_PORT` | PostgreSQL 端口 |
| `REDIS_PORT` | Redis 端口 |
@@ -65,7 +63,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
## 3. 推荐配置方式
### 3.1 gemold-only
### 3.1 moldinsight-only
```env
MOLDINSIGHT_PORT=8000
@@ -92,30 +90,13 @@ REDIS_PORT=6379
---
## 4. 为什么不再强调单一 `PORT` 变量
## 4. direct run 与 Compose 的映射
历史单体部署通常只有一个后端入口，因此 `PORT=8000` 足够。
通过直接运行或 Docker Compose 部署时，端口含义保持一致，但映射方式不同。
当前项目已经是：
- gemold 独立入口
- inventory 独立入口
- unified 作为组合模式而非默认单体入口
### direct run
因此端口配置必须模块化：
- gemold 一个端口
- inventory 一个端口
- 如果 unified 对外存在，可以由网关统一暴露 80/443
这比继续强行把所有模式压成一个 `PORT` 更清晰，也更符合真实部署方式。
---
## 5. 直接运行与 Compose 的区别
### 直接运行
gemold：
moldinsight：
```bash
uvicorn src.entrypoints.moldinsight:app --port 8000
@@ -131,7 +112,7 @@ uvicorn src.entrypoints.inventory:app --port 8001
Compose 通过端口映射暴露服务：
- gemold → `${MOLDINSIGHT_PORT}:8000`
- moldinsight → `${MOLDINSIGHT_PORT}:8000`
- inventory → `${INVENTORY_PORT}:8001`
当前实际定义见：
@@ -139,7 +120,7 @@ Compose 通过端口映射暴露服务：
---
## 6. 与前端配置的关系
## 5. 与前端配置的关系
前端是否使用 unified / split deployment，会影响前端 API 地址配置。
@@ -147,7 +128,7 @@ Compose 通过端口映射暴露服务：
- 一个 API 基地址
### split
- gemold 与 inventory 各自基地址
- moldinsight 与 inventory 各自基地址
因此，修改后端端口后，可能还需要同步：
@@ -157,22 +138,21 @@ Compose 通过端口映射暴露服务：
---
## 7. 推荐实践
## 6. 推荐实践
1. **本地开发**
- gemold：8000
- moldinsight：8000
- inventory：8001
2. **服务器部署**
- 外网只暴露 80/443
- Nginx 反代到 8000 / 8001
3. **不要继续把所有部署模式都写成 `src.main:app + PORT=8000`**
- 这已不符合当前架构
3. 修改端口后，同步检查 `.env`、Compose 端口映射、前端环境变量与反向代理配置
---
## 8. 关联文档
## 7. 关联文档
- [LINUX_SETUP.md](./LINUX_SETUP.md)
- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
docs/topics/storage/STORAGE_SETUP.md
+2 -2
View File
@@ -25,7 +25,7 @@
```text
┌─────────────────────────────────────────────────────────────┐
│ 应用层 (gemold / inventory) │
│ 应用层 (moldinsight / inventory) │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────┴──────────────┐
@@ -50,7 +50,7 @@
- `users` - 用户信息
- `roles` / `permissions` - 权限体系
### gemold 相关
### moldinsight 相关
- `stp_files` - STP 文件元数据
- `html_files` - HTML 报告元数据
- `geometry_data` - 几何分析数据