# 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) | 历史文档与阶段性材料归档入口 |