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-15 18:02:25 +08:00
parent 4fbff0761a
commit 6464e89942
6 changed files with 353 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+144 -118
View File
@@ -1,137 +1,163 @@
# AGENTS.md - geMoldInsight 开发规范
> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的项目入口约定。**开始任何实现前先读本文件**。
> 人类入口见 [README.md](README.md)；当前实现状态见 [docs/STATUS.md](docs/STATUS.md)；当前架构与边界见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的入口文档。**开始任何实现前先读这个**，避免重复输入背景。
> 人类入口见 [README.md](README.md)；**当前实现状态见 [docs/STATUS.md](docs/STATUS.md)**（本文件不复制状态内容）。
## 1. 项目定位
## 1. 项目是什么
**geMoldInsight** 是一个面向模具制造场景的综合系统，围绕：
**geMoldInsight**：面向模具制造场景的综合系统，围绕 STEP/STP 模型分析、模具方案生成、分析结果沉淀与导出、成品创建、BOM / 库存 / 采购 / 销售闭环展开。
- STEP / STP 模型分析
- 模具方案生成
- 分析结果沉淀与导出
- 成品创建
- BOM / 库存 / 采购 / 销售闭环
形态：**单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith**。
当前整体形态为：
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
核心模块：
- `moldinsight`：模具分析、几何处理、批量分析、成本估算、结果导出
- `inventory`：产品、BOM、库存、采购、销售、财务
- `frontend`：Vue 3 前端工程
- `moldinsight`：模具分析、几何处理、批量分析、成本估算、CAM、结果导出（Celery 异步链路）
- `inventory`：成品 / 物料 / BOM / 库存 / 采购 / 销售 / 财务
- `frontend`：Vue 3 独立前端工程（与后端同仓不同目录）
- `shared`：配置、数据库、认证、日志、应用工厂等共享平台层
技术栈一句话：FastAPI + SQLAlchemy 2.0 + PostgreSQL + Alembic + Redis + Celery + PythonOCC/trimesh/pyvista + RustFS（MinIO 兼容）；前端 Vue 3 + Vite + TypeScript + Pinia + TDesign；OpenAPI → TypeScript 类型生成。
架构与模块边界的详细说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 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()` 风格解析。
- **文档先行**：非微小改动，先把实施方案写入对应文档，再按文档执行；方案变了先改文档再改代码。不能先改代码后补文档。
- **完成需求后必须同步文档**：按 §4.1 的映射表逐项检查，防实现与文档漂移。
- **每类信息只有一个归属文档**：状态只在 [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/OPERATIONS.md](docs/OPERATIONS.md)；部署入口只在 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)；前后端契约只在 [docs/API_CONTRACT.md](docs/API_CONTRACT.md)。其他文档只链接，不复制。
- **README 只做导航与最短入门**，不维护状态 / 架构 / 规划 / 部署细节。
- **业务代码归属模块**：moldinsight 业务进 `src/moldinsight/`，inventory 业务进 `src/inventory/`；只有真正跨模块复用的基础能力才进 `src/shared/`。不继续把业务逻辑堆进 `shared`。
- **单数据库是刻意设计**：moldinsight 与 inventory 共享同一 PostgreSQL（如 `STPFile.product_id -> Product.id` 桥接），不拆库。
- **接口变更三件套**：优先用 Pydantic 请求模型（少用手写 `request.json()` 解析）→ 重新导出根目录 `openapi.json` → 前端 `npm run gen:api` 重新生成类型。三步缺一即契约漂移。
- **历史材料统一进 [docs/archive/](docs/archive/README.md)**，不与当前权威文档混放。
- **配置只走 `.env`**（参照 [.env.example](.env.example) 全键说明）：`DB_*`、`SECRET_KEY` 等关键项不设代码兜底（惰性校验，缺失即报），不在代码里给 localhost/弱口令默认值。
## 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 # 人类入口与最短启动说明
```
src/
entrypoints/ # 独立部署入口（均为 create_app 组装，含 sys.path 修正）
moldinsight.py # moldinsight-only 入口：/api 前缀挂 moldinsight router，端口 8000
inventory.py # inventory-only 入口：inventory_router，端口 8001
unified.py # 双模块统一入口：/api 挂 moldinsight + inventory，当前推荐后端
moldinsight/ # 【模具分析模块】
api/
__init__.py # router 聚合：_safe_include 按序挂子 router，失败仅 WARNING 跳过；debug_router 仅 settings.DEBUG 挂载
health_router.py # /api/health 模块健康检查
upload_router.py # /api/upload STEP/STP 上传
batch_router.py # /api/batch-upload 批量上传与分析
task_router.py # /api/status/{task_id} 任务状态查询
history_router.py # /api/history 分析历史与结果文件
cam_router.py # /api/cam/plan CAM 加工方案
aluminum_price_routes.py # /api/aluminum-price/* 铝价（当前为模拟/参考数据，见 TECH_DEBT D2）
advanced_router.py # 导出 / 成本估算 / 设计分析等高级接口（技术债 D1：待拆分 + 请求模型化）
debug_router.py # /api/debug/tasks 全量任务 dump（仅 DEBUG 模式注册，仍需登录）
core/ # 几何与方案核心算法（OCC 重依赖区）
stp_parser.py # STEP/STP 解析
geometry_analyzer.py # 几何分析
mesh_generator.py # 网格生成
base_mold_generator.py # Generator 公共接口（契约测试覆盖）
mold_generator.py # 模具生成
mold_generator_registry.py # 生成器注册表
aluminum_foam_mold.py # 铝泡沫模具方案
feature_detector_registry.py # 特征识别注册表
parting_candidate_generator.py / parting_scheme_scorer.py # 分模候选与评分
multi_scheme_planner.py # 多方案规划
mold_system_designer.py # 模架/浇注等系统设计
side_action_designer.py # 侧向抽芯设计
cavity_layout_optimizer.py # 型腔布局优化
mold_machining.py / mold_cam.py # 加工与 CAM
mold_quality_inspector.py # 质量检查
cad_exporter.py # CAD 导出
services/ # 业务服务层
task_dispatcher.py # 后台任务统一分派（勿绕过它 fire-and-forget）
task_query_service.py # 任务状态查询聚合
processing_service.py # 分析处理编排
calculation_service.py # 计算服务
cost_estimate_service.py # 成本估算
cam_bundle_service.py # CAM 结果打包
verification_service.py # FreeCAD 验证（可选）
shape_loader.py # shape 加载（含 OCC 超时后 executor 重建逻辑）
material_service.py # 物料价格服务
aluminum_price_service.py # 铝价服务（模拟数据）
llm_service.py # LLM 增强分析（可选，OpenAI 兼容）
storage_integration_rustfs.py # RustFS 存储集成
storage/
rustfs_storage.py # RustFS/MinIO 客户端封装
init_storage.py # 存储初始化
inventory/ # 【进销存模块】
api/ # 每域一个 routes 文件：product / supplier / customer / warehouse / inventory / stock_movement / purchase_order / sales_order / purchase_demand / finance / dashboard / material
schemas/ # 每域一个 Pydantic schema 文件（与 api 一一对应）
services/ # 领域服务：inventory / purchase_order / sales_order / finance / purchase_demand / stock_movement
utils.py
shared/ # 【共享平台层：只放真正跨模块复用的基础能力，勿堆业务】
app_factory.py # create_app：request_id 日志中间件 / auth_router / /health / SPA fallback / /html mount
config/settings.py # Settings 单例：dotenv + os.getenv；DB_*/SECRET_KEY 惰性校验无默认
database/database.py # async engine / session / get_db_session
database/init_db.py # 建表与管理员种子
models/database.py # 全量 ORM（identity + moldinsight + inventory 三类同居一处——当前最强耦合点，见 ARCHITECTURE §6）
models/schemas.py # 共享 Pydantic 模型
services/auth_routes.py # /api/auth/* 认证用户角色权限路由
services/auth_service.py # JWT 签发校验 + get_current_active_user 依赖
services/redis_task_manager.py # Redis 任务状态（Hash 字段级原子更新，兼容旧 string）
utils/logger.py # 结构化日志（json/text）+ request_id
utils/file_handler.py # 上传文件处理
utils/html_generator.py # /html 静态分析报告生成
celery_app.py # Celery app（Redis broker，task_acks_late）
celery_tasks.py # moldinsight 异步分析任务
frontend/ # Vue 3 独立工程：src/modules 按域组织（moldinsight/inventory/users/login/home）；src/types/api.ts 为 openapi 生成物，勿手改
alembic/ # 数据库迁移
scripts/ # 一次性迁移与工具脚本（migrations/ 数据迁移、db/ 索引与审计 SQL、tools/ 检查工具），非运行时代码
tests/ # pytest：sqlite+aiosqlite 临时库；pythonocc 缺失时 OCC 契约测试自动 skip
deploy/ # Dockerfile.* / nginx / build 脚本
docs/ # 权威文档（本文件 §5 导航）
```
## 4. 开发规范
## 4. 开发约定
### 4.1 文档先行
### 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/STATUS.md](docs/STATUS.md)（顶部加日志条目） |
| 模块边界 / 目录结构 / 架构原则 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| 接口路径 / 请求响应模型 / 鉴权 | [docs/API_CONTRACT.md](docs/API_CONTRACT.md) + 重新导出 `openapi.json` + `npm run gen:api` |
| 配置项增删 / 启动方式 / 运维要求 | [docs/OPERATIONS.md](docs/OPERATIONS.md) + [.env.example](.env.example) |
| 部署方式 / Compose / Nginx | [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) |
| 阶段性结论 / 旧方案 | 迁入 [docs/archive/](docs/archive/README.md)，不留在权威文档 |
### 4.2 测试
- 命令：`pytest tests/ -q`（pytest.ini 已定 `testpaths=tests`，asyncio auto 模式）。
- 测试用 sqlite+aiosqlite 临时库（[tests/conftest.py](tests/conftest.py) 自建 fixture），不依赖真实 PostgreSQL/Redis。
- 依赖 pythonocc 的契约测试在无 OCC 环境自动 skip；OCC 全量验证用 conda 环境（参考项目实践：本地 pip 环境 + moldinsight conda/OCC 环境各跑一遍，基线数见 [docs/STATUS.md](docs/STATUS.md)）。
- 新增接口/服务逻辑应配套测试；改 `mold_generator` 公共接口必须保持契约测试通过。
### 4.3 API 与契约
- 新增 API 优先考虑模块归属（moldinsight / inventory / shared auth），路由文件过大按职责拆分。
- 请求体用 Pydantic 模型定义，减少 `await request.json()` 手写解析（存量债务见 [docs/TECH_DEBT.md](docs/TECH_DEBT.md) D1）。
- 接口变更后重导出 `openapi.json` 并在前端重新生成类型，步骤见 [docs/API_CONTRACT.md](docs/API_CONTRACT.md) §4。
### 4.4 配置
- 配置只走 `.env`（[.env.example](.env.example) 为全键说明）；compose 从同目录 `.env` 注入 `${VAR}`。
- 关键项（`DB_*` / `SECRET_KEY` / `ADMIN_PASSWORD`）无代码兜底；新增硬依赖配置缺失要 fail-fast，不给 localhost 默认。
- 配置项语义与加载优先级详见 [docs/OPERATIONS.md](docs/OPERATIONS.md) §1。
## 5. 文档导航
| 文档 | 管什么 |
|---|---|
| AGENTS.md（本文件） | agent briefing + 硬约束 + 代码地图 + 开发约定 |
| [README.md](README.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/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 部署入口与部署文档分工 |
| [docs/deployment/LINUX_SETUP.md](docs/deployment/LINUX_SETUP.md) | Linux 详细部署步骤 |
| [docs/archive/README.md](docs/archive/README.md) | 历史文档与阶段性材料归档入口 |
| [docs/ROADMAP.md](docs/ROADMAP.md) | 演进路线与阶段计划 |
| [docs/TECH_DEBT.md](docs/TECH_DEBT.md) | 活跃技术债与治理顺序 |
| [docs/topics/](docs/topics/) | 专题补充（存储等） |
| [docs/archive/README.md](docs/archive/README.md) | 历史文档归档入口 |