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