From 6464e899424b86a712094eb494e05f6e6b875d90 Mon Sep 17 00:00:00 2001 From: chenjw28 <792430652@qq.com> Date: Tue, 15 Sep 2026 18:02:25 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 262 ++++++++++++++++++++++++------------------- README.md | 10 +- docs/API_CONTRACT.md | 108 ++++++++++++++++++ docs/ARCHITECTURE.md | 2 + docs/OPERATIONS.md | 88 +++++++++++++++ docs/STATUS.md | 149 +----------------------- 6 files changed, 353 insertions(+), 266 deletions(-) create mode 100644 docs/API_CONTRACT.md create mode 100644 docs/OPERATIONS.md diff --git a/AGENTS.md b/AGENTS.md index 890c4c0..b81818c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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) | 历史文档归档入口 | diff --git a/README.md b/README.md index 637738d..a2cd5e0 100644 --- a/README.md +++ b/README.md @@ -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) | --- diff --git a/docs/API_CONTRACT.md b/docs/API_CONTRACT.md new file mode 100644 index 0000000..ae00ad8 --- /dev/null +++ b/docs/API_CONTRACT.md @@ -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 `）。登录：`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` 仅服务于非同域场景。 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index fd27ad6..64e8db7 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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) diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md new file mode 100644 index 0000000..151a93f --- /dev/null +++ b/docs/OPERATIONS.md @@ -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) | diff --git a/docs/STATUS.md b/docs/STATUS.md index daf2ce1..61ca50e 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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（端口补充）三层。）