geMoldInsight/AGENTS.md

AGENTS.md - geMoldInsight 开发规范

本文件是给开发 agent（Claude / Codex / …）和协作开发者的项目入口约定。开始任何实现前先读本文件。 人类入口见 README.md；当前实现状态见 docs/STATUS.md；当前架构与边界见 docs/ARCHITECTURE.md。

1. 项目定位

geMoldInsight 是一个面向模具制造场景的综合系统，围绕：

• STEP / STP 模型分析
• 模具方案生成
• 分析结果沉淀与导出
• 成品创建
• BOM / 库存 / 采购 / 销售闭环

当前整体形态为：

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

核心模块：

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

2. 硬约束速览（违反即返工）

• 执行前必须先同步方案到文档：开始实施前，必须先把方案写入对应文档，再按照文档中的步骤逐项执行，不能先改代码后补文档。
• 每次完成需求都必须更新文档：每完成一个需求，都必须同步更新相关文档，保持文档为最新状态，避免实现与文档漂移。
• README 只做导航入口：不在 README 重复维护状态、架构、规划、部署细节。
• 当前实现状态只在 docs/STATUS.md 维护。
• 架构边界只在 docs/ARCHITECTURE.md 维护。
• 规划路线只在 docs/ROADMAP.md 维护。
• 技术债只在 docs/TECH_DEBT.md 维护。
• 部署入口只在 docs/DEPLOYMENT.md 与 docs/deployment/LINUX_SETUP.md 维护。
• 历史材料统一进入 docs/archive/，不与当前权威文档混放。
• 新增业务逻辑优先进入对应模块，不要继续把业务逻辑堆进 shared。
• 接口变更优先补契约与请求模型，减少手写 request.json() 风格解析。

3. 代码地图

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/ARCHITECTURE.md
• 规划变化：更新 docs/ROADMAP.md
• 技术债状态变化：更新 docs/TECH_DEBT.md
• 部署方式变化：更新 docs/DEPLOYMENT.md 与 docs/deployment/LINUX_SETUP.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/ARCHITECTURE.md
• 当前规划只在 docs/ROADMAP.md
• 当前技术债只在 docs/TECH_DEBT.md
• 当前部署入口只在 docs/DEPLOYMENT.md
• 历史材料统一进入 docs/archive/

5. 开发完成后的最小检查清单

每次完成需求后，至少确认：

• 代码已按模块边界落位
• 相关测试已执行或说明未执行原因
• 相关文档已同步更新
• STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT 没有与实现冲突的地方
• 新增历史性说明没有误放进当前权威文档

6. 文档导航

文档	用途
AGENTS.md	项目开发规范、开发约束、文档同步要求
README.md	人类入口、最短启动说明、文档导航
docs/STATUS.md	当前实现状态与当前推荐方案
docs/ARCHITECTURE.md	当前架构、模块边界、结构原则
docs/ROADMAP.md	后续演进路线与阶段计划
docs/TECH_DEBT.md	当前活跃技术债与治理顺序
docs/DEPLOYMENT.md	部署主题入口
docs/deployment/LINUX_SETUP.md	Linux 详细部署步骤
docs/archive/README.md	历史文档与阶段性材料归档入口