geMoldInsight/AGENTS.md

AGENTS.md - geMoldInsight 开发规范

本文件是给开发 agent（Claude / Codex / …）和协作开发者的入口文档。开始任何实现前先读这个，避免重复输入背景。 人类入口见 README.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。

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

• 文档先行：非微小改动，先把实施方案写入对应文档，再按文档执行；方案变了先改文档再改代码。不能先改代码后补文档。
• 完成需求后必须同步文档：按 §4.1 的映射表逐项检查，防实现与文档漂移。
• 每类信息只有一个归属文档：状态只在 docs/STATUS.md；架构边界只在 docs/ARCHITECTURE.md；规划只在 docs/ROADMAP.md；技术债只在 docs/TECH_DEBT.md；配置与运行只在 docs/OPERATIONS.md；部署入口只在 docs/DEPLOYMENT.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/，不与当前权威文档混放。
• 配置只走 .env（参照 .env.example 全键说明）：DB_*、SECRET_KEY 等关键项不设代码兜底（惰性校验，缺失即报），不在代码里给 localhost/弱口令默认值。

3. 代码地图

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 聚合：ROUTE_MODULES 清单 + _safe_include 挂载，失败登记 route_registry（/api/health 呈现 degraded，DEBUG 下 fail fast）；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           # 存储初始化
  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
    models/                     # inventory 域 ORM（catalog / warehouse / trading / finance 四文件，共 15 表）
    utils.py
  shared/                       # 【共享平台层：只放真正跨模块复用的基础能力，勿堆业务】
    app_factory.py              # create_app：request_id 日志中间件 / auth_router / /health / SPA fallback / connect_rustfs 开关（D11 后 /html 由 moldinsight 代理路由提供，不再挂本地 StaticFiles）
    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 脚本
docs/                           # 权威文档（本文件 §5 导航）

4. 开发约定

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

变化	必须同步
实现状态（完成了什么 / 测试基线变化）	docs/STATUS.md（顶部加日志条目）
模块边界 / 目录结构 / 架构原则	docs/ARCHITECTURE.md
接口路径 / 请求响应模型 / 鉴权	docs/API_CONTRACT.md + 重新导出 openapi.json + npm run gen:api
配置项增删 / 启动方式 / 运维要求	docs/OPERATIONS.md + .env.example
部署方式 / Compose / Nginx	docs/DEPLOYMENT.md（操作细节进 docs/deployment/LINUX_SETUP.md）
计划 / 优先级变化	docs/ROADMAP.md
技术债新增 / 清偿	docs/TECH_DEBT.md
阶段性结论 / 旧方案	迁入 docs/archive/，不留在权威文档

4.2 测试

• 命令：pytest tests/ -q（pytest.ini 已定 testpaths=tests，asyncio auto 模式）。
• 测试用 sqlite+aiosqlite 临时库（tests/conftest.py 自建 fixture），不依赖真实 PostgreSQL/Redis。
• 依赖 pythonocc 的契约测试在无 OCC 环境自动 skip；OCC 全量验证用 conda 环境（参考项目实践：本地 pip 环境 + moldinsight conda/OCC 环境各跑一遍，基线数见 docs/STATUS.md）。
• 新增接口/服务逻辑应配套测试；改 mold_generator 公共接口必须保持契约测试通过。

4.3 API 与契约

• 新增 API 优先考虑模块归属（moldinsight / inventory / shared auth），路由文件过大按职责拆分。
• 请求体用 Pydantic 模型定义，减少 await request.json() 手写解析（存量债务见 docs/TECH_DEBT.md D1）。
• 接口变更后重导出 openapi.json 并在前端重新生成类型，步骤见 docs/API_CONTRACT.md §4。

4.4 配置

• 配置只走 .env（.env.example 为全键说明）；compose 从同目录 .env 注入 ${VAR}。
• 关键项（DB_* / SECRET_KEY / ADMIN_PASSWORD）无代码兜底；新增硬依赖配置缺失要 fail-fast，不给 localhost 默认。
• 配置项语义与加载优先级详见 docs/OPERATIONS.md §1。

5. 文档导航

文档	管什么
AGENTS.md（本文件）	agent briefing + 硬约束 + 代码地图 + 开发约定
README.md	人类入口：是什么 + 快速启动 + 文档导航
docs/STATUS.md	当前实现状态（唯一归属，常改，日志体）
docs/ARCHITECTURE.md	架构 + 模块边界 + 结构原则
docs/OPERATIONS.md	配置 / 启动 / 环境 / 运维硬性要求
docs/API_CONTRACT.md	前后端契约权威：端点 / 约定 / OpenAPI 类型生成
docs/DEPLOYMENT.md	部署入口与部署文档分工
docs/deployment/LINUX_SETUP.md	Linux 详细部署步骤
docs/ROADMAP.md	演进路线与阶段计划
docs/TECH_DEBT.md	活跃技术债与治理顺序
docs/topics/	专题补充（存储等）
docs/archive/README.md	历史文档归档入口