cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档

Browse Source
This commit is contained in:
chenjw28
2026-09-15 18:02:25 +08:00
parent 4fbff0761a
commit 6464e89942
6 changed files with 353 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+144 -118
View File
@@ -1,137 +1,163 @@
# AGENTS.md - geMoldInsight 开发规范
> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的项目入口约定。**开始任何实现前先读本文件**。
> 人类入口见 [README.md](README.md)；当前实现状态见 [docs/STATUS.md](docs/STATUS.md)；当前架构与边界见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的入口文档。**开始任何实现前先读这个**，避免重复输入背景。
> 人类入口见 [README.md](README.md)；**当前实现状态见 [docs/STATUS.md](docs/STATUS.md)**（本文件不复制状态内容）。
## 1. 项目定位
## 1. 项目是什么
**geMoldInsight** 是一个面向模具制造场景的综合系统，围绕：
**geMoldInsight**：面向模具制造场景的综合系统，围绕 STEP/STP 模型分析、模具方案生成、分析结果沉淀与导出、成品创建、BOM / 库存 / 采购 / 销售闭环展开。
- STEP / STP 模型分析
- 模具方案生成
- 分析结果沉淀与导出
- 成品创建
- BOM / 库存 / 采购 / 销售闭环
形态：**单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith**。
当前整体形态为：
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
核心模块：
- `moldinsight`：模具分析、几何处理、批量分析、成本估算、结果导出
- `inventory`：产品、BOM、库存、采购、销售、财务
- `frontend`：Vue 3 前端工程
- `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. 硬约束速览（违反即返工）
- **执行前必须先同步方案到文档**：开始实施前，必须先把方案写入对应文档，再按照文档中的步骤逐项执行，不能先改代码后补文档。
- **每次完成需求都必须更新文档**：每完成一个需求，都必须同步更新相关文档，保持文档为最新状态，避免实现与文档漂移。
- **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()` 风格解析。
- **文档先行**：非微小改动，先把实施方案写入对应文档，再按文档执行；方案变了先改文档再改代码。不能先改代码后补文档。
- **完成需求后必须同步文档**：按 §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)**，不与当前权威文档混放。
- **配置只走 `.env`**（参照 [.env.example](.env.example) 全键说明）：`DB_*`、`SECRET_KEY` 等关键项不设代码兜底（惰性校验，缺失即报），不在代码里给 localhost/弱口令默认值。
## 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 # 人类入口与最短启动说明
```
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 聚合：_safe_include 按序挂子 router，失败仅 WARNING 跳过；debug_router 仅 settings.DEBUG 挂载
health_router.py # /api/health 模块健康检查
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 加工方案
aluminum_price_routes.py # /api/aluminum-price/* 铝价（当前为模拟/参考数据，见 TECH_DEBT D2）
advanced_router.py # 导出 / 成本估算 / 设计分析等高级接口（技术债 D1：待拆分 + 请求模型化）
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 导出
services/ # 业务服务层
task_dispatcher.py # 后台任务统一分派（勿绕过它 fire-and-forget）
task_query_service.py # 任务状态查询聚合
processing_service.py # 分析处理编排
calculation_service.py # 计算服务
cost_estimate_service.py # 成本估算
cam_bundle_service.py # CAM 结果打包
verification_service.py # FreeCAD 验证（可选）
shape_loader.py # shape 加载（含 OCC 超时后 executor 重建逻辑）
material_service.py # 物料价格服务
aluminum_price_service.py # 铝价服务（模拟数据）
llm_service.py # LLM 增强分析（可选，OpenAI 兼容）
storage_integration_rustfs.py # RustFS 存储集成
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
utils.py
shared/ # 【共享平台层：只放真正跨模块复用的基础能力，勿堆业务】
app_factory.py # create_app：request_id 日志中间件 / auth_router / /health / SPA fallback / /html mount
config/settings.py # Settings 单例：dotenv + os.getenv；DB_*/SECRET_KEY 惰性校验无默认
database/database.py # async engine / session / get_db_session
database/init_db.py # 建表与管理员种子
models/database.py # 全量 ORM（identity + moldinsight + inventory 三类同居一处——当前最强耦合点，见 ARCHITECTURE §6）
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 静态分析报告生成
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 生成物，勿手改
alembic/ # 数据库迁移
scripts/ # 一次性迁移与工具脚本（migrations/ 数据迁移、db/ 索引与审计 SQL、tools/ 检查工具），非运行时代码
tests/ # pytest：sqlite+aiosqlite 临时库；pythonocc 缺失时 OCC 契约测试自动 skip
deploy/ # Dockerfile.* / nginx / build 脚本
docs/ # 权威文档（本文件 §5 导航）
```
## 4. 开发规范
## 4. 开发约定
### 4.1 文档先行
### 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/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/archive/README.md](docs/archive/README.md) | 历史文档与阶段性材料归档入口 |
| [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) | 历史文档归档入口 |
README.md
+6 -4
View File
@@ -108,9 +108,11 @@ geMoldInsight/
| 文档 | 解决什么问题 |
|---|---|
| [AGENTS.md](AGENTS.md) | 项目开发规范、开发约束、文档同步要求 |
| [docs/STATUS.md](docs/STATUS.md) | 当前实现状态、当前推荐方案、近期完成项 |
| [AGENTS.md](AGENTS.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/ROADMAP.md](docs/ROADMAP.md) | 后续演进路线与阶段计划 |
| [docs/TECH_DEBT.md](docs/TECH_DEBT.md) | 当前活跃技术债与治理计划 |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 部署主题入口与部署文档分工 |
@@ -122,8 +124,8 @@ geMoldInsight/
| 你是 | 建议阅读顺序 |
|---|---|
| 第一次了解项目 | 本文 → [docs/STATUS.md](docs/STATUS.md) → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| 开发者 / 改代码 | 本文 → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.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) |
| 开发者 / 改代码 | [AGENTS.md](AGENTS.md) → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) → [docs/API_CONTRACT.md](docs/API_CONTRACT.md) → [docs/TECH_DEBT.md](docs/TECH_DEBT.md) |
| 运维 / 部署 | 本文 → [docs/OPERATIONS.md](docs/OPERATIONS.md) → [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/API_CONTRACT.md
+108
View File
@@ -0,0 +1,108 @@
# geMoldInsight 前后端契约（API_CONTRACT）
> 文档定位：**前后端契约的唯一归属**——端点总览、统一约定、OpenAPI 类型生成流程。
> 端点定义、路径、请求/响应 schema 的**最终真相源是根目录 `openapi.json`**（由 FastAPI 自动生成）；本文维护人可读的总览与变更规则。当前状态见 [STATUS.md](STATUS.md)，架构见 [ARCHITECTURE.md](ARCHITECTURE.md)，接口类技术债见 [TECH_DEBT.md](TECH_DEBT.md) D1。
---
## 1. 总览
三种部署形态暴露的 API 面（入口见 [src/entrypoints/](../src/entrypoints/)）：
| 形态 | API 面 |
|---|---|
| unified（推荐） | `/api/*`（moldinsight + inventory）+ `/api/auth/*` + 顶层 `/health` |
| moldinsight-only | `/api/*`（moldinsight）+ `/api/auth/*` + `/health` |
| inventory-only | `/api/*`（inventory）+ `/api/auth/*` + `/health` |
- moldinsight 路由在 [moldinsight/api/\_\_init\_\_.py](../src/moldinsight/api/__init__.py) 经 `_safe_include` 聚合（子 router 加载失败仅 WARNING 跳过；`debug_router` 仅 `DEBUG=true` 注册）。
- inventory 路由在 [inventory/api/\_\_init\_\_.py](../src/inventory/api/__init__.py) 按域静态聚合。
- 认证路由来自 [shared/services/auth_routes.py](../src/shared/services/auth_routes.py)，由 [app_factory](../src/shared/app_factory.py) 挂载，三种形态共用。
## 2. 统一约定
- **鉴权**：JWT Bearer（`Authorization: Bearer <token>`）。登录：`POST /api/auth/login`（表单）/ `POST /api/auth/login/json`（JSON）；受保护路由通过 FastAPI 依赖 `get_current_active_user` 注入当前用户（[shared/services/auth_service.py](../src/shared/services/auth_service.py)）。`SECRET_KEY` 跨进程必须一致。
- **响应形态**：现状**无统一信封包装**——各端点直接返回业务 JSON；schema 以 `openapi.json` 的 components 为准。新增接口不建议另起信封风格，保持与所在模块一致。
- **错误**：FastAPI 标准 `HTTPException` 状态码语义；业务校验优先 Pydantic 请求模型自动 422。
- **业务路由前缀**：全部业务端点在 `/api` 下；顶层仅 `/health`（探活）、`/login`、`/users`（历史遗留入口，前端主链路用 `/api/auth/*`）。
## 3. 端点总览（按域分组）
> 下表为导航用速览；路径参数、请求/响应字段以 `openapi.json` 为准。
### 3.1 认证与用户（shared）
| 域 | 端点 | 文件 |
|---|---|---|
| 登录 | `/api/auth/login`、`/api/auth/login/json`、`/api/auth/logout` | auth_routes.py |
| 当前用户 | `/api/auth/me` | auth_routes.py |
| 用户管理 | `/api/auth/users`、`/api/auth/users/{user_id}`、`/api/auth/users/{user_id}/reset-password` | auth_routes.py |
| 角色权限 | `/api/auth/roles`、`/api/auth/roles/{role_id}`、`/api/auth/roles/{role_id}/permissions`、`/api/auth/permissions`、`/api/auth/permissions/{permission_id}` | auth_routes.py |
### 3.2 moldinsight（模具分析）
| 域 | 端点 | 文件 |
|---|---|---|
| 上传 | `/api/upload` | upload_router.py |
| 批量分析 | `/api/batch-upload`、`/api/batch/{batch_id}` | batch_router.py |
| 任务状态 | `/api/status/{task_id}` | task_router.py |
| 历史结果 | `/api/history`、`/api/history/{filename}` | history_router.py |
| CAM | `/api/cam/plan` | cam_router.py |
| 铝价（模拟数据） | `/api/aluminum-price/current`、`/api/aluminum-price/history` | aluminum_price_routes.py |
| 健康检查 | `/api/health` | health_router.py |
| 调试（仅 DEBUG） | `/api/debug/tasks` | debug_router.py |
| 导出/估算/设计等高级接口 | 见 `openapi.json` 对应路径 | advanced_router.py（技术债 D1：待拆分） |
### 3.3 inventory（进销存）
| 域 | 端点 | 文件 |
|---|---|---|
| 成品 | `/api/products`、`/api/products/{product_id}`、`/api/products/{product_id}/materials`、`/api/products/from-task/{task_id}` | product_routes.py |
| 物料价格/供应商 | `/api/materials/*` | material_routes.py |
| 供应商 | `/api/suppliers`、`/api/suppliers/{supplier_id}` | supplier_routes.py |
| 客户 | `/api/customers`、`/api/customers/{customer_id}` | customer_routes.py |
| 仓库 | `/api/warehouses` | warehouse_routes.py |
| 库存 | `/api/inventory`、`/api/inventory/{inventory_id}` | inventory_routes.py |
| 库存流水 | `/api/stock-movements` | stock_movement_routes.py |
| 采购订单 | `/api/purchase-orders`、`/api/purchase-orders/{order_id}`、`.../receive`、`.../status` | purchase_order_routes.py |
| 采购建议 | `/api/purchase-demands/calculate` | purchase_demand_routes.py |
| 销售订单 | `/api/sales-orders`、`/api/sales-orders/{order_id}`、`.../status`、`.../issue-materials`、`.../consume-materials`、`.../production-plan` | sales_order_routes.py |
| 财务 | `/api/finance/summary`、`/api/finance/receivables|payables|receipts|payments|transactions`、`/api/finance/partner-statement/{partner_type}` 等 | finance_routes.py |
| 看板 | `/api/dashboard` | dashboard_routes.py |
**moldinsight → inventory 桥接**：`/api/products/from-task/{task_id}` 由分析任务一键创建成品（对应 `STPFile.product_id -> Product.id` 单库桥接，见 [ARCHITECTURE.md](ARCHITECTURE.md) §5.1）。
## 4. OpenAPI 与前端类型生成（接口变更三件套）
接口变更后**必须依次完成**：
1. **改代码**：路由 + Pydantic 请求/响应模型（优先模型，少写 `request.json()` 解析）。
2. **重导出 `openapi.json`**（在可 import 项目的环境执行，如 conda `gemold`）：
```bash
python -c "import sys; sys.path.insert(0, 'src'); from entrypoints.unified import app; import json; print(json.dumps(app.openapi(), ensure_ascii=False, indent=2))" > openapi.json
```
（moldinsight-only 契约视角可把 `entrypoints.unified` 换成 `entrypoints.moldinsight`；对外主契约以 unified 为准。）
3. **重新生成前端类型**：
```bash
cd frontend && npm run gen:api # openapi-typescript：../openapi.json -> src/types/api.ts
```
- `frontend/src/types/api.ts` 是**生成物，禁止手改**；前端代码类型引用它。
- 三步缺一即前后端契约漂移（硬约束，见 [AGENTS.md](../AGENTS.md) §2）。
- **当前已知滞后**：checked-in `openapi.json`（2026-07-27）落后当前代码（实际 76 paths vs 文件内 70），下次接口变更时按上述流程重导出。
## 5. 契约变更规则
- 新增接口先定模块归属（moldinsight / inventory / shared auth），再写路由；返回结构、路径、鉴权发生变化时，同步更新本文相应表格。
- 路由文件过大按职责拆分（现状债务：`advanced_router` 待拆分，见 [TECH_DEBT.md](TECH_DEBT.md) D1）。
- 破坏性变更（删字段 / 改语义）需在 [STATUS.md](STATUS.md) 日志条目中记录，并确认前端同仓同步修改。
## 6. 前端消费约定
- 前端为独立工程 [frontend/](../frontend/)（Vue 3 + Vite + TS + Pinia + TDesign），按域组织在 `src/modules/`（moldinsight / inventory / users / login / home）。
- API 类型唯一来源 `src/types/api.ts`（生成物）；组件不手写与后端重复的响应类型。
- 跨域：开发期走 Vite；部署期为同域反代（见 [DEPLOYMENT.md](DEPLOYMENT.md)），`CORS_ORIGINS` 仅服务于非同域场景。
docs/ARCHITECTURE.md
+2
View File
@@ -211,5 +211,7 @@ AI、性能、铝泡沫等更偏历史设计/规划性质的专题材料已迁
- 想看“当前做到哪一步”：看 [STATUS.md](STATUS.md)
- 想看“后面还要往哪演进”：看 [ROADMAP.md](ROADMAP.md)
- 想看“当前有哪些活跃技术债”：看 [TECH_DEBT.md](TECH_DEBT.md)
- 想看“配置怎么给、服务怎么起”：看 [OPERATIONS.md](OPERATIONS.md)
- 想看“前后端接口契约”：看 [API_CONTRACT.md](API_CONTRACT.md)
- 想看“怎么部署”：看 [DEPLOYMENT.md](DEPLOYMENT.md)
- 想看“模块化蓝图与更完整设计讨论”：看 [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
docs/OPERATIONS.md
+88
View File
@@ -0,0 +1,88 @@
# 配置与运行（OPERATIONS）
> 文档定位：**配置 / 启动 / 环境 / 运维硬性要求的唯一归属**。
> 部署入口与部署文档分工见 [DEPLOYMENT.md](DEPLOYMENT.md)，Linux 详细步骤见 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)；当前状态见 [STATUS.md](STATUS.md)，架构见 [ARCHITECTURE.md](ARCHITECTURE.md)。
---
## 1. 配置来源与优先级
- 配置统一走**环境变量**，代码侧由 [src/shared/config/settings.py](../src/shared/config/settings.py) 的 `Settings` 单例经 `dotenv` + `os.getenv` 读取。
- **本地运行**：仓库根 `.env`（`load_dotenv()` 自动加载；不在仓库内，参照 [.env.example](../.env.example) 复制编辑）。
- **Compose 运行**：compose 文件用 `${VAR}` 从同目录 `.env` 注入容器环境变量（见 [docker-compose.yml](../docker-compose.yml)）。
- **键值约定**：
- `DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD`：**惰性校验、无代码默认**——缺失时 import 不报错（便于测试/静态分析），真正连库时才失败。生产必须显式配置。
- `SECRET_KEY`：JWT 签名密钥，**无默认**；生产必须 ≥32 字符强随机。
- `ADMIN_PASSWORD`：初始管理员密码，**无默认**；首次建库前必须设置。
- `RUSTFS_*`：对象存储（兼容 `MINIO_*` 别名写法）；本地开发缺省值仅为占位，连不上会在用到存储的链路报错。
- `REDIS_*`：默认 `localhost:6379` 无密码（本地开发语义），生产必须显式覆盖。
- `CORS_ORIGINS`：逗号分隔白名单；不设默认放行 `*`，**生产必须显式设置**。
- `LOG_FORMAT`：`json`（生产默认，结构化）/ `text`（开发人可读）；`LOG_LEVEL`：DEBUG/INFO/WARNING/ERROR。
- `DEBUG`：`true` 时额外注册 `/api/debug/*` 调试路由（仍需登录），**生产必须为 false**。
- 新增配置项的规则：只加 `settings.py` + `.env.example`，关键依赖项不给 localhost/弱口令兜底（见 [AGENTS.md](../AGENTS.md) §2）。
## 2. 安装与环境
- 后端依赖：`pip install -r requirements.txt`。
- **OCC 几何能力**：PythonOCC 不走 pip 主路径，通过 conda 环境提供（本项目实践环境名 `gemold`）。无 OCC 环境时项目可启动，但几何分析契约测试自动 skip。
- 前端：`cd frontend && npm install`。
- 数据库迁移：`alembic/`（`alembic.ini` 在仓库根）；数据修复类一次性脚本在 `scripts/migrations/` 与 `scripts/db/`，**不是运行时代码**，勿在服务内引用。
## 3. 本地启动
后端三入口（均含 sys.path 修正，可从仓库根直接跑）：
```bash
# unified（moldinsight + inventory，推荐）：8000
uvicorn src.entrypoints.unified:app --reload --host 0.0.0.0 --port 8000
# moldinsight-only：8000
uvicorn src.entrypoints.moldinsight:app --reload --host 0.0.0.0 --port 8000
# inventory-only：8001
uvicorn src.entrypoints.inventory:app --reload --host 0.0.0.0 --port 8001
```
Celery worker（moldinsight 异步分析链路；本地从 `src` 目录跑，与 [deploy/Dockerfile.celery](../deploy/Dockerfile.celery) CMD 同参）：
```bash
cd src && celery -A celery_app worker --concurrency=2 --loglevel=info
```
前端：
```bash
cd frontend
npm run dev # Vite 开发服务器
npm run gen:api # 从根目录 openapi.json 重新生成 src/types/api.ts（见 API_CONTRACT §4）
```
探活：unified/moldinsight `GET /health` 与 `GET /api/health`；inventory `GET /health`。
## 4. Docker Compose
```bash
docker compose --profile full up -d # frontend + unified backend + moldinsight-celery（推荐）
docker compose --profile moldinsight up -d # moldinsight 单模块栈
docker compose --profile inventory up -d # inventory 单模块栈
```
- 镜像构建：`deploy/build.bat` / `deploy/build.sh`（base → 各服务镜像，见 `deploy/Dockerfile.*`）。
- PostgreSQL / Redis / RustFS 通常**复用服务器已有服务**，不由项目 compose 自带；容器只注入连接配置。
## 5. 运行时硬性要求
- **生产环境必须显式设置**：`SECRET_KEY`、`ADMIN_PASSWORD`、`DB_*`、`CORS_ORIGINS`、`RUSTFS_*`、`REDIS_PASSWORD`、`DEBUG=false`、`LOG_FORMAT=json`。
- **单数据库**：moldinsight 与 inventory 共享同一 PostgreSQL（刻意设计，不拆库）。
- **后台任务一律走 `task_dispatcher`** 与 Celery，不要在路由里 fire-and-forget。
- **uploads/ 与 html_output/ 为运行时产物目录**，不提交、不作为配置源头。
- `scripts/` 下的一次性脚本执行前先确认目标环境（多为不可逆数据迁移）。
## 6. 排障指针
| 症状 | 先看 |
|---|---|
| 起服务连不上数据库 | `.env` 的 `DB_*` 是否与服务器一致（惰性校验：import 成功 ≠ 连接正常） |
| 上传/导出报对象存储错误 | `RUSTFS_*` 四项 + [topics/storage/RUSTFS_STORAGE.md](topics/storage/RUSTFS_STORAGE.md) |
| 分析任务一直 pending | Celery worker 是否在跑；Redis 连通性；`task_dispatcher` 日志 |
| 前端类型与接口对不上 | `openapi.json` 是否重新导出、`npm run gen:api` 是否执行（[API_CONTRACT.md](API_CONTRACT.md) §4） |
| 登录 401 | `SECRET_KEY` 是否跨进程一致（JWT 校验依赖同一密钥） |
| 部署端口/反代问题 | [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)、[deployment/PORT_CONFIG.md](deployment/PORT_CONFIG.md) |
docs/STATUS.md
+5 -144
View File
@@ -1,149 +1,10 @@
# geMoldInsight 项目状态（STATUS）
> 文档定位：**唯一的“当前实现状态 / 当前推荐方案”文档**。
> README 只做导航，不重复维护状态；架构细节见 [ARCHITECTURE.md](ARCHITECTURE.md)，演进路线见 [ROADMAP.md](ROADMAP.md)，技术债见 [TECH_DEBT.md](TECH_DEBT.md)，部署入口见 [DEPLOYMENT.md](DEPLOYMENT.md)。
> 最后更新：2026-09-01。
> 文档定位：**唯一的「现在到哪了」**。README / AGENTS / 各主文档只链接到这里，不复制状态内容。
> 维护规则：每完整完成一个需求，**倒序在本文顶部加一条**（日期 + 主题 + 关键事实）；其余主文档（架构 / 规划 / 技术债 / 部署）维护各自的"当前有效说法"，本文只记录"什么时候做到了哪一步"。维护规则出处见根目录 [AGENTS.md](../AGENTS.md)。
---
> 最后更新：2026-09-15（**项目规范体系对齐 ipc-chat-cortex**——参考 `ipc-chat-cortex` 的 AGENTS.md + docs 规范重整本文档体系：① [AGENTS.md](../AGENTS.md) 重写——硬约束速览（新增：接口变更三件套 Pydantic→openapi.json→gen:api、配置只走 .env 且关键项不兜底、单数据库刻意设计）+ 代码地图逐文件化 + 开发约定映射表（改什么→同步什么文档）；② 新增 [OPERATIONS.md](OPERATIONS.md)（配置来源与优先级 / 本地启动 / Compose / 运维硬性要求）与 [API_CONTRACT.md](API_CONTRACT.md)（端点总览 / 统一约定 / OpenAPI 类型生成流程）；③ 本文件改为日志体，原静态内容分流到各归属文档（推荐部署模式→DEPLOYMENT §1，未完成项→ROADMAP/TECH_DEBT）。**验证**：openapi 导出命令实测可用（conda gemold 环境，unified app 76 paths）；**待办**：checked-in `openapi.json`（2026-07-27，70 paths）已落后当前代码，下次接口变更时按 [API_CONTRACT.md](API_CONTRACT.md) §4 重导出并 `npm run gen:api`。）
## 1. 当前项目状态总览
> 上一条：2026-09-02（**模块化收口 + 文档主骨架建立（基线条目）**：代码侧完成 moldinsight 技术债治理——安全收口（debug/history 权限补齐、任务访问控制收紧）、静默失败修复（`detect-undercuts` 基于真实 shape 重建）、OCC 超时后 executor 重建防毒化全队列、后台任务统一分派、Redis 任务状态改 Hash 原子更新、完成态任务视图缓存、导出缓存与持久化收口、旧入口与死代码删除、Generator 公共接口提取 + 契约测试；详见 [TECH_DEBT.md](TECH_DEBT.md) §2。结构侧完成 `src/entrypoints/` 三入口拆分（moldinsight / inventory / unified）、`shared` 平台能力集中、前端独立 `frontend/` 工程。文档侧建立 `STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT` 主骨架，README 收敛为唯一导航入口，历史材料迁入 [archive/](archive/README.md)。**测试基线**：本地 pip 环境 **47 passed, 1 skipped**（pythonocc 缺失自动 skip）；moldinsight conda + OCC 环境 **88 passed**。inventory 侧少量既有 deprecation warnings 不影响通过。）
geMoldInsight 当前已从早期单体演进为：
- `moldinsight`：模具分析、STEP/STP 处理、批量分析、导出、成本估算
- `inventory`：成品/物料/BOM/库存/采购/销售/财务
- `frontend`：Vue 3 独立前端工程
- `shared`：配置、数据库、认证、日志、应用工厂等共享平台层
当前架构形态可概括为：
> **单仓库 + 单数据库 + 多模块 + 可独立部署**
详细结构与边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。
---
## 2. 当前推荐方案
### 2.1 推荐部署模式
当前推荐部署模式为：
- **unified**：frontend + unified backend + moldinsight celery
适用场景：
- 本地开发
- 集成环境
- 小团队统一部署
- 前端同域反代到单一 backend
详细部署说明见 [DEPLOYMENT.md](DEPLOYMENT.md) 与 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)。
### 2.2 当前代码入口
当前后端已存在独立部署入口：
- [src/entrypoints/moldinsight.py](../src/entrypoints/moldinsight.py)
- [src/entrypoints/inventory.py](../src/entrypoints/inventory.py)
当前 Compose 入口：
- [docker-compose.yml](../docker-compose.yml)
---
## 3. 当前模块化进展
### 3.1 已经成型的部分
- `src/moldinsight/` 与 `src/inventory/` 已具备相对清晰的业务目录边界
- 前端已独立为 `frontend/` 工程，不再是后端静态目录的附属
- 部署入口已按模块拆分到 `src/entrypoints/`
- 基础认证、配置、数据库、日志等能力已集中到 `shared`
### 3.2 当前主要耦合点
当前最大的剩余耦合点主要是：
- `shared` 仍承担较多平台与组合职责
- 共享 ORM 模型仍集中在 `shared.models.database`
- 部分历史文档与当前模块化事实尚未完全收口
这些内容的结构化说明见 [ARCHITECTURE.md](ARCHITECTURE.md)。
---
## 4. 最近已完成的重要整理
### 4.1 moldinsight 技术债治理（本轮已完成）
已完成的重点治理包括：
- 安全收口：debug/history 权限补齐、任务访问控制收紧
- 静默失败修复：`detect-undercuts` 基于真实 shape 重建分析
- OCC 超时后 executor 重建，避免单个任务毒化全队列
- 后台任务统一分派，避免 fire-and-forget 丢失
- Redis 任务状态改为 Hash 原子更新，并兼容旧 string 格式
- 完成态任务视图增加缓存，减少 RustFS 高频回读
- 导出缓存与持久化链路收口，支持重启后再导出
- 删除旧入口与死代码，修正部署陷阱
- Generator 公共接口提取完成，并补充契约测试
详细治理记录见 [TECH_DEBT.md](TECH_DEBT.md)。
### 4.2 测试状态
当前已验证：
- 本地 pip 环境：**47 passed, 1 skipped**
- moldinsight conda + OCC 环境：**88 passed**
说明：
- 无 OCC 环境下，依赖 pythonocc 的契约测试会自动 skip
- inventory 侧仍有少量既有 deprecation warnings，但不影响本轮通过状态
---
## 5. 当前仍在推进 / 尚未完成的重点
### 5.1 文档体系整理
本轮正在进行：
- 将 README 收敛为唯一文档导航入口
- 建立 `STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT` 主骨架
- 收口部署文档与历史文档
### 5.2 仍未完成的功能/结构项
当前仍明确未完成或待下一步推进的重点：
- `advanced_router` 拆分 + Pydantic 请求模型
- 铝价模拟数据增加 `source: "simulated"` 标注，并同步前端展示
- 进一步收敛 shared/platform 边界
- 继续清理当前文档中“现状 / 规划 / 历史”混放问题
更长周期的演进方向见 [ROADMAP.md](ROADMAP.md)。
---
## 6. 报告、模板与归档文档说明
以下文档仍可能被保留用于专题说明、验收、模板复用或历史追溯，但不再承担当前状态入口职责：
- 业务/专题报告：
- [archive/MOLD_ERP_ANALYSIS_REPORT.md](archive/MOLD_ERP_ANALYSIS_REPORT.md)
- [archive/ZERO_FINISHED_INVENTORY_CERTIFICATE.md](archive/ZERO_FINISHED_INVENTORY_CERTIFICATE.md)
- 验收/模板文档：
- [templates/UAT_CHECKLIST.md](templates/UAT_CHECKLIST.md)
- [templates/INTERFACE_INTEGRATION_CATALOG_TEMPLATE.md](templates/INTERFACE_INTEGRATION_CATALOG_TEMPLATE.md)
- 历史材料归档：
- [archive/README.md](archive/README.md)
---
## 7. 文档维护规则
- 当前实现状态只在本文维护
- README 只做导航与最短入门，不重复状态细节
- 架构边界改动更新 [ARCHITECTURE.md](ARCHITECTURE.md)
- 规划变更更新 [ROADMAP.md](ROADMAP.md)
- 技术债状态变更更新 [TECH_DEBT.md](TECH_DEBT.md)
- 部署方式变化更新 [DEPLOYMENT.md](DEPLOYMENT.md) 与 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)
> 此前：2026-09-01（**文档体系专项整理启动**：明确「README 只做导航、每类信息单一归属、历史材料进 archive」的文档治理原则；建立 deployment/ 主题目录与 archive/ 归档目录；部署文档收口为 DEPLOYMENT（入口）+ deployment/LINUX_SETUP（操作）+ deployment/DEPLOY_PORT / PORT_CONFIG（端口补充）三层。）