cjw
79441a8a87
D4 文档/规划/历史混放收口：
- docs/TECH_DEBT.md §2 由'按批次回顾'精简为'按主题摘要'，
与§3重复内容（批次0-4详细展开）整体迁入
docs/archive/2026-09_governance_batches.md
- docs/STATUS.md 顶部 2026-09-17 之前条目迁入
docs/archive/2026-09_status_history.md，仅保留指针
- D2 历史口径补齐为 2026-09-18 批次4后续专项清偿
- D4 标已清偿
- AGENTS.md / docs/archive/README.md 同步导航
D13 锁文件流程固化（镜像引入主体已清偿，仅剩锁文件落盘）：
- 新增 deploy/generate_lockfiles.{sh,bat}：在 moldinsight conda
环境（仅项目依赖）执行 pip freeze --exclude pythonocc-core，
产出 deploy/requirements-{base,moldinsight}.lock.txt
- deploy/Dockerfile.moldinsight 注释改为指向生成脚本
- docs/OPERATIONS.md §2.1 增加完整流程说明
- tests/test_lockfile_generation.py 加锁文件存在性+体积契约；
tests/conftest.py 注册 --run-lockfile-check 选项，
默认 skip（仓库单测不阻塞），CI 镜像构建 job 显式启用 fail-fast
遗留：锁文件本身尚未落盘（本机Miniforge跨项目开发栈混装，
污染严重不能直接 pip freeze）；待 CI / 生产首次构建时按流程落锁。
测试基线：126 passed, 9 skipped（默认4原有skip + D13新增5skip；
启用 --run-lockfile-check 时严格断言2项锁文件契约）
Co-Authored-By: Claude Code <noreply@anthropic.com>
178 lines
15 KiB
Markdown
178 lines
15 KiB
Markdown
# 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) | 历史文档归档入口 |
|