geMoldInsight/AGENTS.md

# AGENTS.md - geMoldInsight 开发规范

> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的入口文档。**开始任何实现前先读这个**，避免重复输入背景。
> 人类入口见 [README.md](README.md)；**当前实现状态见 [docs/STATUS.md](docs/STATUS.md)**（本文件不复制状态内容）。

## 1. 项目是什么

**geMoldInsight**：面向模具制造场景的综合系统，围绕 STEP/STP 模型分析、模具方案生成、分析结果沉淀与导出、成品创建、BOM / 库存 / 采购 / 销售闭环展开。

形态：**单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith**。

- `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. 硬约束速览（违反即返工）

- **文档先行**：非微小改动，先把实施方案写入对应文档，再按文档执行；方案变了先改文档再改代码。不能先改代码后补文档。
- **完成需求后必须同步文档**：按 §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)**，不与当前权威文档混放。
- **历史批次详细流水账 / 早段 STATUS**：见 [docs/archive/2026-09_governance_batches.md](docs/archive/2026-09_governance_batches.md) 与 [docs/archive/2026-09_status_history.md](docs/archive/2026-09_status_history.md)；主骨架权威文档（TECH_DEBT §2 / STATUS 顶部）只保留摘要。
- **配置只走 `.env`**（参照 [.env.example](.env.example) 全键说明）：`DB_*`、`SECRET_KEY` 等关键项不设代码兜底（惰性校验，缺失即报），不在代码里给 localhost/弱口令默认值。

## 3. 代码地图

```
src/
  entrypoints/                  # 独立部署入口（纯组装：sys.path 修正 + create_app + startup_hooks/register_routers）
    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 聚合：ROUTE_MODULES 清单 + _safe_include 挂载，失败登记 route_registry（/api/health 呈现 degraded，DEBUG 下 fail fast）；register_moldinsight_routers 入口单点调用（/api 聚合 + HTML 报告根路径挂载）；debug_router 仅 settings.DEBUG 挂载
      route_registry.py         # 路由装载注册表（loaded / failed / disabled，health_router 引用）
      health_router.py          # /api/health 模块健康检查（含真实 pythonocc 探测与路由装载状态）
      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 加工方案（Pydantic 请求模型 + to_thread）
      design_router.py          # 设计类接口：/optimize-layout /design-* /detect-undercuts（原 advanced_router，D1 拆分）
      cost_router.py            # /cost-estimate 成本估算（原 advanced_router）
      machining_router.py       # 加工类接口：/design-cam /check-collision /optimize-toolpath /design-electrodes /simulate-machining
      export_router.py          # 导出类接口：/export-mold /export-download /export-recommendations
      core_modules.py           # 核心计算模块惰性装载器（设计/加工路由共用，装载失败 503）
      aluminum_price_routes.py  # /api/aluminum-price/* 铝价（模拟数据，响应带 source: "simulated"，见 TECH_DEBT D2）
      html_report_router.py     # GET /html/{filename} 报告代理（根路径挂载：RustFS 报告键 → 遗留 JSON 包装 → 本地卷兜底；include_into 由入口调用）
      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 导出（export_mold_results 随方案 B 已删；export_step 等供 OCC 子进程持久化/转换）
      occ_worker.py             # OCC 常驻工作进程入口：操作注册表（parse_stp/generate_mesh/generate_cavity/analyze_mold_design/detect_undercuts/convert_component_step/ping/sleep/warmup）+ worker_main 消息循环
    services/                   # 业务服务层
      task_dispatcher.py        # 后台任务统一分派（勿绕过它 fire-and-forget）
      task_query_service.py     # 任务状态查询聚合
      processing_service.py     # 分析处理编排（run_occ 经常驻 OCC 进程池调度，见 occ_process_pool.py / OCC_THROUGHPUT.md）
      occ_process_pool.py       # OCC 常驻工作进程池（方案 B）：超时/崩溃 terminate 换新补位；任务级超时 recover 整体重建
      calculation_service.py    # 计算服务
      cost_estimate_service.py  # 成本估算
      cam_bundle_service.py     # CAM 结果打包
      verification_service.py   # FreeCAD 验证（可选）
      stp_materializer.py       # 按 task_id 把 STP 原件落盘临时文件（OCC 解析在子进程内，形状不跨进程）
      material_service.py       # 物料价格服务
      aluminum_price_service.py # 铝价服务（模拟数据）
      llm_service.py            # LLM 增强分析（可选，OpenAI 兼容）
      task_storage_service.py   # STP 文件与处理任务生命周期存储（D9：数据写 flush-only，状态更新即时 commit）
      analysis_storage_service.py # 分析结果数据存储（几何/网格/型腔/HTML/特征）与任务数据视图组装
      file_history_service.py   # 按文件名聚合的上传历史查询视图
    models/                     # moldinsight 域 ORM（stp_analysis.py：stp_files 及各阶段产物 + processing_tasks，共 9 表）
    storage/
      rustfs_storage.py         # RustFS/MinIO 客户端封装
      init_storage.py           # RustFS 连接初始化 + rustfs_startup_hook（入口经 startup_hooks 注入）
  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 / master_data / material / product / purchase_order / sales_order / finance / purchase_demand / stock_movement / dashboard
    models/                     # inventory 域 ORM（catalog / warehouse / trading / finance 四文件，共 15 表）
    utils.py
  shared/                       # 【共享平台层：只放真正跨模块复用的基础能力，勿堆业务】
    app_factory.py              # create_app：纯平台引导（CORS / 请求日志 / /health / SPA fallback / db+Redis 启动）；模块专属接线经 startup_hooks 注入（D3 收敛，原 connect_rustfs 已移除）
    config/settings.py          # Settings 单例：dotenv + os.getenv；DB_*/SECRET_KEY 惰性校验无默认
    database/database.py        # async engine / session / get_db_session
    database/init_db.py         # 建表与管理员种子
    models/base.py              # 唯一 ORM Base + 模型归属约定（跨模块只许裸 FK，禁跨模块 relationship）
    models/identity.py          # 身份与权限 ORM：User/Role/Permission/UserRole/RolePermission/UserActivity/SystemLog
    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/摘要/数据 JSON；产物写任务临时目录，由 moldinsight 上传 RustFS 报告键）
  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 生成物，勿手改
migrations/                     # 数据库迁移
scripts/                        # 一次性迁移与工具脚本（migrations/ 数据迁移、db/ 索引与审计 SQL、tools/ 检查工具），非运行时代码
tests/                          # pytest：sqlite+aiosqlite 临时库；pythonocc 缺失时 OCC 契约测试自动 skip
deploy/                         # Dockerfile.* / nginx / build 脚本 / generate_lockfiles.{sh,bat}（D13 锁文件生成入口）
docs/                           # 权威文档（本文件 §5 导航）
```

## 4. 开发约定

### 4.1 完成需求后的文档映射（改什么 → 同步什么）

| 变化 | 必须同步 |
|---|---|
| 实现状态（完成了什么 / 测试基线变化） | [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/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) | 历史文档归档入口 |