新增调整

mcp-for-erp/MCP工具说明文档.md

@@ -0,0 +1,383 @@
+# MCP for ERP — 工具说明文档
+
+> 服务对象：汽车零部件（小型阀体外壳）智能报价智能体
+> 服务定位：ERP 侧核价基础数据与成本计算引擎（只读 + 计算，不写库）
+> 版本：v1.1（2026-08-09）
+
+---
+
+## 1 服务概览
+
+| 项 | 值 |
+|----|----|
+| 服务名 | `mcp-for-erp-auto` |
+| 框架 | MCPServer（mcp 2.0.0 内置高级框架），`@app.tool()` 装饰器注册 |
+| 传输协议 | Streamable HTTP（JSON-RPC 2.0） |
+| 远程端点 | `https://erp-data.dongsk.top/mcp` |
+| 本地端点 | `http://0.0.0.0:8001/mcp`（`cd src && python3 server.py`） |
+| 数据库 | PostgreSQL 15+，库 `smart_quotation_auto`（仅服务层内部经 `db.py` 连接池访问） |
+| 工具数 | **5 个**（全部只读/计算） |
+
+### 工具一览
+
+| # | 工具 | 功能 | 报价环节 |
+|---|------|------|----------|
+| 1 | `query_material_master` | 查询物料主数据（体积/密度/吨位/后处理） | 基础数据 |
+| 2 | `match_material_grade` | 客户牌号 → 内部等效牌号对照 | 材质确认 |
+| 3 | `get_die_casting_params` | 压铸参数：铝水重量、节拍、铸造成本 | 压铸成本 |
+| 4 | `get_machining_estimate` | 机加工工时估算（固化工装节拍） | 机加工成本 |
+| 5 | `calculate_part_cost` | 汇总核价，输出最终单价 | 最终报价 |
+
+---
+
+## 2 调用约定
+
+### 2.1 客户端注册（mcpServers）
+
+```json
+{
+  "mcpServers": {
+    "erp": { "url": "https://erp-data.dongsk.top/mcp" }
+  }
+}
+```
+
+### 2.2 JSON-RPC 调用流程
+
+1. `initialize`（握手，获取 `Mcp-Session-Id`）
+2. `notifications/initialized`（通知，无响应体）
+3. `tools/list`（可选，列出工具）
+4. `tools/call`（调用工具，`params: {name, arguments}`）
+
+### 2.3 兜底命令行客户端（纯标准库）
+
+```bash
+python3 scripts/mcp_http_client.py erp <工具名> '<JSON参数>'
+# 示例
+python3 scripts/mcp_http_client.py erp calculate_part_cost '{"material_code":"VHB-AT-001","annual_qty":300000}'
+```
+
+### 2.4 返回通用约定
+
+- 所有工具返回 **JSON 字符串**（`ensure_ascii=False`，中文不转义）。
+- 查询类工具返回 `{"total": N, "<集合名>": [...]}`；操作/计算类工具返回 `{"success": true|false, ...}`。
+- 失败统一形态：`{"success": false, "message": "<原因>"}`（查询类失败以 `total: 0` 空集表达）。
+- 金额/重量：浮点数，成本保留 2 位小数，重量保留 3 位小数；日期 `YYYY-MM-DD`，月份 `YYYY-MM`。
+
+---
+
+## 3 工具详解
+
+### 3.1 query_material_master — 查询物料主数据
+
+**功能**：按物料编码精确查询，或按零件类别、材质牌号、压铸吨位组合过滤。返回物料档案（含体积、密度、净重、吨位、表面处理），是核价的起点数据。
+
+**入参**（全部可选；全部不传 = 返回全表）：
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `material_code` | string | 否 | — | 物料编码，精确匹配，如 `VHB-AT-001` |
+| `part_category` | string | 否 | — | 零件类别，精确匹配，如 `阀体外壳` |
+| `material_grade` | string | 否 | — | 客户材质牌号，精确匹配，如 `ADC12` |
+| `die_casting_ton` | int | 否 | — | 压铸机吨位，精确匹配，如 `400` |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | int | 命中条数 |
+| `materials[]` | array | 物料行列表 |
+| `materials[].material_code` | string | 物料编码（内部主键） |
+| `materials[].part_name` | string | 零件名称 |
+| `materials[].part_category` | string | 零件类别 |
+| `materials[].material_grade` | string | 客户材质牌号 |
+| `materials[].density` | decimal | 密度 g/cm³（JSON 中为字符串） |
+| `materials[].volume_cc` | decimal | 零件体积 cm³（算铝水重量的依据） |
+| `materials[].net_weight_kg` | decimal | 净重 kg（算后处理成本的依据） |
+| `materials[].die_casting_ton` | int | 压铸机吨位 |
+| `materials[].surface_treatment` | string | 表面处理（阳极氧化/钝化/无等） |
+| `materials[].unit` | string | 计量单位 |
+| `materials[].created_at` | string | 建档时间 |
+
+**返回示例**：
+
+```json
+{
+  "total": 1,
+  "materials": [
+    {
+      "material_code": "VHB-AT-001",
+      "part_name": "变速箱阀体外壳",
+      "part_category": "阀体外壳",
+      "material_grade": "ADC12",
+      "density": "2.700",
+      "volume_cc": "444.44",
+      "net_weight_kg": "1.200",
+      "die_casting_ton": 400,
+      "surface_treatment": "阳极氧化",
+      "unit": "件",
+      "created_at": "2026-08-07 12:18:51.484993"
+    }
+  ]
+}
+```
+
+---
+
+### 3.2 match_material_grade — 材质牌号对照
+
+**功能**：把客户指定牌号（GB/ASTM/JIS/EN/ISO 任一体系或内部码）对照为企业内部等效牌号，返回密度与铝锭参考价。支持模糊匹配与热处理后缀自动剥离（如 `A356-T6` → `A356`，最多剥 2 段）。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `customer_grade` | string | **是** | — | 客户牌号，大小写不敏感，模糊匹配六大码系 |
+| `standard` | string | 否 | — | 标准体系提示（当前实现未参与过滤，保留参数） |
+
+**返回字段**（命中时）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `matched` | bool | 是否命中 |
+| `customer_grade` | string | 原客户牌号 |
+| `internal_code` | string | 内部等效牌号，如 `AL-ADC12` |
+| `density` | float | 密度 g/cm³ |
+| `price_per_kg` | float | 铝锭参考价 ¥/kg（兜底价，核价优先取月度价） |
+| `all_mappings[]` | array | 全部命中行（含 gb/astm/jis/en/iso/internal 六码、grade_group 材质族） |
+
+**未命中返回**：
+
+```json
+{ "matched": false, "message": "未找到材质 AD12" }
+```
+
+**返回示例**（`ADC12`）：
+
+```json
+{
+  "matched": true,
+  "customer_grade": "ADC12",
+  "internal_code": "AL-ADC12",
+  "density": 2.7,
+  "price_per_kg": 18.5,
+  "all_mappings": [
+    {
+      "grade_group": "铝合金",
+      "gb_code": "ZAlSi10Cu(ADC12)",
+      "astm_code": "A380",
+      "jis_code": "ADC12",
+      "en_code": "EN AC-4600",
+      "iso_code": "AlSi9Cu3",
+      "internal_code": "AL-ADC12",
+      "density": "2.700",
+      "price_per_kg": "18.50"
+    }
+  ]
+}
+```
+
+**业务规则**：未命中时 Skill 层应回退默认铝价并产生 warning（TC-06 场景），不应中断报价。
+
+---
+
+### 3.3 get_die_casting_params — 获取压铸参数
+
+**功能**：按物料编码取压铸参数。核心输出：铝水重量（体积×密度×1.05 损耗）、压铸机吨位、模次节拍、单件压铸成本。体现 MVP 原则「**靠体积算铝水重量、压铸机吨位固定工时**」。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `material_code` | string | **是** | — | 物料编码 |
+| `volume_cc` | float | 否 | 物料档案体积 | 覆盖体积（图纸实测体积优先于档案默认值） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | bool | 成功标记 |
+| `material_code` | string | 物料编码 |
+| `volume_cc` | float | 采用体积 cm³ |
+| `density` | float | 密度 g/cm³ |
+| `aluminum_weight_kg` | float | 铝水重量 = 体积×密度/1000×1.05，3 位小数 |
+| `die_casting_ton` | int | 压铸机吨位 |
+| `cycle_time_sec` | float | 模次节拍（秒/模，按吨位固化） |
+| `machine_rate` | float | 机台费率 ¥/小时 |
+| `mold_cavities` | int | 模穴数 |
+| `casting_cost_per_part` | float | 单件压铸成本 = (节拍/3600)×费率/模穴数，2 位小数 |
+
+**失败返回**：`{"success": false, "message": "未找到物料 XXX"}` 或 `{"success": false, "message": "未找到 400T 压铸机参数"}`
+
+**返回示例**（VHB-AT-001，444.44cc，400T）：
+
+```json
+{
+  "success": true,
+  "material_code": "VHB-AT-001",
+  "volume_cc": 444.44,
+  "density": 2.7,
+  "aluminum_weight_kg": 1.26,
+  "die_casting_ton": 400,
+  "cycle_time_sec": 30.0,
+  "machine_rate": 260.0,
+  "mold_cavities": 1,
+  "casting_cost_per_part": 2.17
+}
+```
+
+---
+
+### 3.4 get_machining_estimate — 机加工工时估算
+
+**功能**：按孔清单（钻孔/攻丝/铰孔）与铣面数量估算机加工总工时与刀具成本。所有规格节拍来自固化表 `machining_cycle`（工装节拍），逐项累加。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `material_code` | string | **是** | — | 物料编码（回显用） |
+| `drill_holes` | array[object] | 否 | [] | 钻孔清单，元素 `{"spec": "Φ6", "count": 2}` |
+| `tap_holes` | array[object] | 否 | [] | 攻丝清单，元素 `{"spec": "M6×1.0", "count": 2}` |
+| `ream_holes` | array[object] | 否 | [] | 铰孔清单，元素 `{"spec": "Φ8H7", "count": 1}` |
+| `mill_faces` | int | 否 | 0 | 铣面数量 |
+
+孔元素字段：`spec`（规格字符串，缺省 Φ8 / M8×1.25 / Φ8H7）、`count`（数量，缺省 1）。
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | bool | 成功标记 |
+| `material_code` | string | 物料编码 |
+| `total_time_sec` | float | 总工时（秒），2 位小数 |
+| `total_time_hours` | float | 总工时（小时），4 位小数 |
+| `total_tool_cost` | float | 刀具成本合计 ¥ |
+| `details[]` | array | 逐项明细：`operation`（drill/tap/ream/mill）、`spec`、`count`、`total_time_sec` |
+
+**返回示例**（钻 Φ6×2 + 攻 M6×1.0×2 + 铣面×1）：
+
+```json
+{
+  "success": true,
+  "material_code": "VHB-AT-001",
+  "total_time_sec": 26.0,
+  "total_time_hours": 0.0072,
+  "total_tool_cost": 1.5,
+  "details": [
+    { "operation": "drill", "spec": "Φ6", "count": 2, "total_time_sec": 6.0 },
+    { "operation": "tap", "spec": "M6×1.0", "count": 2, "total_time_sec": 8.0 },
+    { "operation": "mill", "spec": "face", "count": 1, "total_time_sec": 12.0 }
+  ]
+}
+```
+
+**注意**：固化表中不存在的规格**静默跳过**（不计工时也不报错）；毛坯件（无孔无面）返回总工时 0，Skill 层应产生 warning（TC-07 场景）。
+
+---
+
+### 3.5 calculate_part_cost — 汇总核价（最终单价）
+
+**功能**：一站式核价。材料成本（铝水重量×当月铝价）+ 压铸成本 + 机加工成本 + 后处理成本 → 小计 × (1+管理费率) × (1+利润率) = 最终单价。铝价优先取 `material_price_history` 最新月度价并留痕月份；机加工费率按材质族（铝合金 60 / 灰铁 75 / 球铁 80 ¥/h）取 `machining_rate`。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `material_code` | string | **是** | — | 物料编码 |
+| `annual_qty` | int | **是** | — | 年用量（件/年） |
+| `drill_holes` | array[object] | 否 | [] | 同 3.4 |
+| `tap_holes` | array[object] | 否 | [] | 同 3.4 |
+| `ream_holes` | array[object] | 否 | [] | 同 3.4 |
+| `mill_faces` | int | 否 | 0 | 铣面数量 |
+| `overhead_rate` | float | 否 | 0.12 | 管理费率 |
+| `profit_rate` | float | 否 | 0.15 | 利润率 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | bool | 成功标记 |
+| `material_code` / `part_name` | string | 物料编码 / 零件名称 |
+| `cost_breakdown.material_cost` | float | 材料成本 = 铝水重量×铝价 |
+| `cost_breakdown.aluminum_weight_kg` | float | 铝水重量（含 1.05 损耗） |
+| `cost_breakdown.aluminum_price_per_kg` | float | 采用铝价 ¥/kg |
+| `cost_breakdown.price_basis_month` | string | 铝价月份 `YYYY-MM`（留痕；无月度价时为 null） |
+| `cost_breakdown.internal_code` | string | 内部牌号 |
+| `cost_breakdown.grade_group` | string | 材质族（决定机加工费率） |
+| `cost_breakdown.casting_cost` | float | 单件压铸成本 |
+| `cost_breakdown.die_casting_ton` | int | 压铸机吨位 |
+| `cost_breakdown.machining_cost` | float | 机加工成本 = 工时×费率 |
+| `cost_breakdown.machining_hours` | float | 机加工总工时（小时） |
+| `cost_breakdown.machining_rate_per_hour` | float | 机加工费率 ¥/h |
+| `cost_breakdown.post_process_cost` | float | 后处理成本 = 净重×工艺费率 |
+| `cost_breakdown.surface_treatment` | string | 表面处理工艺 |
+| `total_cost` | float | 四项成本小计 |
+| `overhead_rate` / `overhead` | float | 管理费率 / 管理费额 |
+| `profit_rate` | float | 利润率 |
+| `unit_price` | float | **最终单价** = (total_cost+overhead)×(1+profit_rate) |
+| `currency` | string | 固定 `CNY` |
+
+**返回示例**（VHB-AT-001，30 万件/年，钻 Φ6×2/攻 M6×1.0×2/铰 Φ8H7×1/铣面×1）：
+
+```json
+{
+  "success": true,
+  "material_code": "VHB-AT-001",
+  "part_name": "变速箱阀体外壳",
+  "cost_breakdown": {
+    "material_cost": 23.31,
+    "aluminum_weight_kg": 1.26,
+    "aluminum_price_per_kg": 18.5,
+    "price_basis_month": "2026-08",
+    "internal_code": "AL-ADC12",
+    "grade_group": "铝合金",
+    "casting_cost": 2.17,
+    "die_casting_ton": 400,
+    "machining_cost": 0.53,
+    "machining_hours": 0.0089,
+    "machining_rate_per_hour": 60.0,
+    "post_process_cost": 6.0,
+    "surface_treatment": "阳极氧化"
+  },
+  "total_cost": 32.01,
+  "overhead_rate": 0.12,
+  "overhead": 3.84,
+  "profit_rate": 0.15,
+  "unit_price": 41.23,
+  "currency": "CNY"
+}
+```
+
+**失败返回**：`{"success": false, "message": "未找到物料 XXX"}`
+
+---
+
+## 4 附录
+
+### 4.1 核心公式
+
+```
+铝水重量(kg)   = 体积(cm³) × 密度(g/cm³) / 1000 × 1.05(损耗系数)
+材料成本       = 铝水重量 × 铝锭单价(当月月度价，缺省 18.5)
+压铸成本       = (节拍秒 / 3600) × 机台费率 / 模穴数          ← 吨位固化节拍
+机加工成本     = Σ(工序固化节拍×数量) / 3600 × 材质族费率
+后处理成本     = 净重(kg) × 表面处理费率
+单价           = (四项成本小计 × (1+管理费率)) × (1+利润率)
+```
+
+### 4.2 依赖数据表
+
+| 表 | 用途 |
+|----|------|
+| `material_master` | 物料主数据（体积/密度/吨位/后处理） |
+| `material_grade_mapping` | 五标准体系牌号对照 + 材质族 + 参考铝价 |
+| `material_price_history` | 月度铝价留痕（核价取最新月） |
+| `die_casting_params` | 吨位 → 节拍/费率/模穴数 |
+| `machining_cycle` | 工序规格固化节拍与刀具费率 |
+| `machining_rate` | 材质族机加工费率（60/75/80 ¥/h） |
+| `post_process_rate` | 表面处理费率（¥/kg） |
+
+### 4.3 与 CRM 服务的协作
+
+ERP 服务只读不写。报价存档链路（create_inquiry → save_quotation → update_opportunity）由 `mcp-for-crm` 承担，见《MCP for CRM — 工具说明文档》。

mcp-for-erp/数据表与种子数据说明.md

@@ -0,0 +1,239 @@
+# MCP for ERP — 数据表结构与种子数据说明文档
+
+> 数据库：PostgreSQL 15+，库 `smart_quotation_auto`（与 CRM 服务共库不同表）
+> 建表/种子脚本：`sql/init.sql`（v3，幂等可重跑）；执行入口：`cd src && python3 seed.py`
+> 版本：v1.0（2026-08-09）
+
+---
+
+## 1 概览
+
+| # | 表名 | 用途 | 主键 | 种子行数 |
+|---|------|------|------|----------|
+| 1 | `material_master` | 物料主数据（体积/密度/吨位/后处理） | material_code | 16 |
+| 2 | `material_grade_mapping` | 五标准体系牌号对照 | id（SERIAL） | 13 |
+| 3 | `die_casting_params` | 压铸参数（吨位→固化节拍/费率/模穴） | tonnage | 9 |
+| 4 | `machining_cycle` | 机加工固化工装节拍 | id（SERIAL） | 26 |
+| 5 | `post_process_rate` | 后处理费率（¥/kg） | id（SERIAL） | 10 |
+| 6 | `material_price_history` | 月度材料价格留痕 | id（SERIAL） | 260（13 牌号×20 月） |
+| 7 | `machining_rate` | 材质族机加工费率 | grade_group | 4 |
+
+**表关系**：`material_master.material_grade` →（经 match_material_grade 模糊对照）→ `material_grade_mapping`（internal_code/grade_group）→ `material_price_history`（按 internal_code 取最新月价）、`machining_rate`（按 grade_group 取费率）；`material_master.die_casting_ton` → `die_casting_params.tonnage`；机加工工时查 `machining_cycle`（operation_type+spec）；后处理查 `post_process_rate`（process_type = material_master.surface_treatment）。
+
+---
+
+## 2 表结构详解
+
+### 2.1 material_master — 物料主数据
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `material_code` | VARCHAR(50) | PRIMARY KEY | 物料编码，如 `VHB-AT-001` |
+| `part_name` | VARCHAR(200) | NOT NULL | 零件名称 |
+| `part_category` | VARCHAR(50) | NOT NULL | 零件类别（种子全为「阀体外壳」） |
+| `material_grade` | VARCHAR(50) | NOT NULL | 客户材质牌号（对照表输入） |
+| `density` | DECIMAL(6,3) | NOT NULL DEFAULT 2.700 | 密度 g/cm³ |
+| `volume_cc` | DECIMAL(10,2) | NOT NULL | 零件体积 cm³（**算铝水重量的依据**） |
+| `net_weight_kg` | DECIMAL(8,3) | NOT NULL | 净重 kg（**算后处理成本的依据**） |
+| `die_casting_ton` | INTEGER | NOT NULL | 压铸机吨位（关联 die_casting_params） |
+| `surface_treatment` | VARCHAR(50) | — | 表面处理（关联 post_process_rate） |
+| `unit` | VARCHAR(10) | DEFAULT '件' | 计量单位 |
+| `created_at` | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 建档时间 |
+
+### 2.2 material_grade_mapping — 材质牌号对照表
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `id` | SERIAL | PRIMARY KEY | 自增主键 |
+| `grade_group` | VARCHAR(50) | NOT NULL | 材质族：铝合金/铸铝/铸铁/球墨铸铁（决定机加工费率） |
+| `gb_code` | VARCHAR(80) | — | GB 牌号 |
+| `astm_code` | VARCHAR(80) | — | ASTM 牌号 |
+| `jis_code` | VARCHAR(80) | — | JIS 牌号 |
+| `en_code` | VARCHAR(80) | — | EN 牌号 |
+| `iso_code` | VARCHAR(80) | — | ISO 牌号 |
+| `internal_code` | VARCHAR(50) | NOT NULL，UNIQUE(uq_grade_mapping) | 内部等效牌号 |
+| `density` | DECIMAL(6,3) | NOT NULL | 密度 g/cm³ |
+| `price_per_kg` | DECIMAL(10,2) | NOT NULL | 铝锭/材料参考价 ¥/kg（兜底价） |
+
+> 对照匹配对六列码值做大小写不敏感 LIKE 模糊匹配；带热处理后缀（如 A356-T6）自动剥后缀重试。
+
+### 2.3 die_casting_params — 压铸参数表
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `tonnage` | INTEGER | PRIMARY KEY | 压铸机吨位 |
+| `shot_weight_kg` | DECIMAL(8,3) | NOT NULL | 射出重量 kg（参考值） |
+| `cycle_time_sec` | DECIMAL(8,2) | NOT NULL | 模次节拍 秒/模（**吨位固化**） |
+| `machine_rate` | DECIMAL(10,2) | NOT NULL | 机台费率 ¥/小时 |
+| `mold_cavities` | INTEGER | DEFAULT 1 | 模穴数（压铸成本按穴分摊） |
+
+### 2.4 machining_cycle — 机加工节拍表（固化工装节拍）
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `id` | SERIAL | PRIMARY KEY | 自增主键 |
+| `operation_type` | VARCHAR(30) | NOT NULL | drill 钻孔 / tap 攻丝 / ream 铰孔 / mill 铣面 |
+| `spec` | VARCHAR(50) | NOT NULL | 规格：Φ6、M6×1.0、Φ8H7、face；UNIQUE(operation_type, spec) |
+| `cycle_time_sec` | DECIMAL(8,2) | NOT NULL | 单件固化节拍（秒） |
+| `tool_rate` | DECIMAL(8,4) | DEFAULT 0 | 单件刀具成本 ¥ |
+| `notes` | VARCHAR(200) | — | 备注（通孔/盲孔等） |
+
+### 2.5 post_process_rate — 后处理费率表
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `id` | SERIAL | PRIMARY KEY | 自增主键 |
+| `process_type` | VARCHAR(50) | NOT NULL，UNIQUE(uq_post_process) | 工艺名（与物料 surface_treatment 对应） |
+| `unit` | VARCHAR(10) | DEFAULT 'kg' | 计价单位 |
+| `rate` | DECIMAL(10,2) | NOT NULL | 费率 ¥/kg |
+| `currency` | VARCHAR(10) | DEFAULT 'CNY' | 币种 |
+
+### 2.6 material_price_history — 材料价格历史表
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `id` | SERIAL | PRIMARY KEY | 自增主键 |
+| `internal_code` | VARCHAR(50) | NOT NULL | 内部牌号；UNIQUE(internal_code, price_date) |
+| `price_date` | DATE | NOT NULL | 价格月份（每月 1 日） |
+| `price_per_kg` | DECIMAL(10,2) | NOT NULL | 当月参考价 ¥/kg |
+| `source` | VARCHAR(100) | DEFAULT '市场参考价' | 数据来源留痕 |
+
+> 核价取法：`ORDER BY price_date DESC LIMIT 1`（最新月），并在返回中带 `price_basis_month` 留痕。
+
+### 2.7 machining_rate — 机加工费率表
+
+| 列 | 类型 | 约束/默认 | 说明 |
+|----|------|-----------|------|
+| `grade_group` | VARCHAR(50) | PRIMARY KEY | 材质族 |
+| `rate_per_hour` | DECIMAL(10,2) | NOT NULL | 费率 ¥/小时 |
+| `notes` | VARCHAR(200) | — | 备注 |
+
+---
+
+## 3 种子数据详解
+
+### 3.1 material_master — 16 种阀体外壳
+
+覆盖设计：铝合金 12 / 灰铸铁 2（HT250、HT300）/ 球墨铸铁 1（QT500-7）/ 铸铝 1（ZL101）；吨位 160~1000T 全谱系；体积 96.3~1037 cm³。
+
+| 物料编码 | 零件名称 | 牌号 | 密度 | 体积cm³ | 净重kg | 吨位 | 后处理 |
+|----------|----------|------|------|---------|--------|------|--------|
+| VHB-AT-001 | 变速箱阀体外壳 | ADC12 | 2.700 | 444.44 | 1.200 | 400 | 阳极氧化 |
+| VHB-BK-002 | 制动阀体壳 | HT250 | 7.200 | 388.89 | 2.800 | 630 | 电泳涂装 |
+| VHB-SP-003 | 转向器阀体壳 | A356-T6 | 2.650 | 296.30 | 0.785 | 280 | 钝化 |
+| VHB-EG-004 | 发动机油路阀体壳 | EN AC-4600 | 2.700 | 555.56 | 1.500 | 400 | 阳极氧化 |
+| VHB-CL-005 | 离合器控制阀体壳 | ADC10 | 2.700 | 480.00 | 1.300 | 400 | 阳极氧化 |
+| VHB-TR-006 | 变速箱液压控制阀体 | AlSi9Cu3 | 2.700 | 620.00 | 1.670 | 630 | 电泳涂装 |
+| VHB-EB-007 | 电子制动阀体壳 | AlSi10MnMg | 2.650 | 350.00 | 0.930 | 400 | 钝化 |
+| VHB-QT-008 | 悬架阻尼阀体壳 | QT500-7 | 7.100 | 520.00 | 3.690 | 630 | 喷涂 |
+| VHB-MN-009 | 微型泵阀体壳 | ADC12 | 2.700 | 96.30 | 0.260 | 160 | 钝化 |
+| VHB-LG-010 | 大型主阀体壳 | ADC12 | 2.700 | 1037.00 | 2.800 | 800 | 电泳涂装 |
+| VHB-TC-011 | 涡轮增压控制阀体壳 | ADC12 | 2.700 | 320.00 | 0.860 | 350 | 钝化 |
+| VHB-EG-012 | EGR阀体壳 | ADC10 | 2.700 | 265.00 | 0.720 | 280 | 钝化 |
+| VHB-WP-013 | 水泵阀体壳 | AlSi12 | 2.650 | 380.00 | 1.010 | 400 | 阳极氧化 |
+| VHB-TM-014 | 热管理阀体壳(新能源) | AlSi10MnMg | 2.650 | 505.00 | 1.340 | 500 | 钝化 |
+| VHB-OP-015 | 机油泵阀体壳 | ZL101 | 2.650 | 210.00 | 0.560 | 200 | 钝化 |
+| VHB-HD-016 | 重卡制动阀体壳 | HT300 | 7.250 | 850.00 | 6.160 | 1000 | 达克罗 |
+
+### 3.2 material_grade_mapping — 13 条牌号对照
+
+覆盖设计：铝合金 7 / 铸铝 1 / 铸铁 3 / 球墨铸铁 2；每条六码齐全（GB/ASTM/JIS/EN/ISO/内部码）。
+
+| 材质族 | GB | ASTM | JIS | EN | ISO | 内部码 | 密度 | 参考价¥/kg |
+|--------|----|------|-----|----|----|--------|------|-----------|
+| 铝合金 | ZAlSi10Cu(ADC12) | A380 | ADC12 | EN AC-4600 | AlSi9Cu3 | AL-ADC12 | 2.700 | 18.50 |
+| 铝合金 | ZAlSi7Mg(A356) | A356 | AC4C-T6 | EN AC-4210 | AlSi7Mg | AL-A356 | 2.650 | 20.00 |
+| 铝合金 | ZAlSi9Cu(AlSi9Cu) | B443 | AC4B | EN AC-4600 | AlSi9Cu | AL-4600 | 2.700 | 18.00 |
+| 铸铝 | ZL101 | 356.0 | AC4C | EN AC-4200 | AlSi7 | AL-ZL101 | 2.650 | 19.00 |
+| 铸铁 | HT250 | G2500 | FC250 | EN-GJL-250 | GJL-250 | IR-HT250 | 7.200 | 6.50 |
+| 球墨铸铁 | QT500-7 | D5007 | FCD500 | EN-GJS-500 | GJS-500 | IR-QT500 | 7.100 | 7.20 |
+| 铝合金 | ZAlSi8Cu(ADC10) | A384 | ADC10 | EN AC-4650 | AlSi8Cu | AL-ADC10 | 2.700 | 18.20 |
+| 铝合金 | ZAlSi10MnMg | — | — | AlSi10MnMg | AlSi10MnMg | AL-S10MM | 2.650 | 22.00 |
+| 铝合金 | ZAlSi12 | 413.0 | AC3A | EN AC-4420 | AlSi12 | AL-S12 | 2.650 | 17.80 |
+| 铸铁 | HT200 | G3000 | FC200 | EN-GJL-200 | GJL-200 | IR-HT200 | 7.200 | 6.00 |
+| 铸铁 | HT300 | G3500 | FC300 | EN-GJL-300 | GJL-300 | IR-HT300 | 7.250 | 6.80 |
+| 球墨铸铁 | QT450-10 | D4510 | FCD450 | EN-GJS-450 | GJS-450 | IR-QT450 | 7.100 | 7.00 |
+| 球墨铸铁 | QT600-3 | D6003 | FCD600 | EN-GJS-600 | GJS-600 | IR-QT600 | 7.100 | 7.50 |
+
+> 脚本含修正语句：`IR-QT%` 组别归位「球墨铸铁」（历史数据曾误归「铸铁」）。
+
+### 3.3 die_casting_params — 9 档吨位
+
+| 吨位 | 射出重量kg | 节拍秒/模 | 机台费率¥/h | 模穴数 |
+|------|-----------|-----------|-------------|--------|
+| 160 | 0.50 | 15.00 | 120.00 | **2**（一模两腔） |
+| 200 | 0.80 | 18.00 | 140.00 | **2** |
+| 280 | 1.20 | 22.00 | 180.00 | 1 |
+| 350 | 1.80 | 26.00 | 220.00 | 1 |
+| 400 | 2.50 | 30.00 | 260.00 | 1 |
+| 500 | 3.20 | 36.00 | 320.00 | 1 |
+| 630 | 4.00 | 42.00 | 380.00 | 1 |
+| 800 | 6.50 | 55.00 | 520.00 | 1 |
+| 1000 | 8.50 | 65.00 | 650.00 | 1 |
+
+> **故意不含 1250T**：用于回退测试（未命中吨位场景）。
+
+### 3.4 machining_cycle — 26 条固化节拍
+
+| 工序 | 规格谱系 | 条数 | 节拍范围(秒) | 刀具费范围(¥) |
+|------|----------|------|--------------|----------------|
+| drill 钻孔 | Φ3 / Φ4 / Φ5 / Φ6 / Φ8 / Φ10 / Φ12 / Φ14 / Φ16 / Φ20 / Φ24 | 11 | 2.00~12.00 | 0.10~0.60 |
+| tap 攻丝 | M4×0.7 / M5×0.8 / M6×1.0 / M8×1.25 / M10×1.5 / M12×1.75 / M14×2.0 / M16×2.0 | 8 | 3.00~9.00 | 0.15~0.45 |
+| ream 铰孔 | Φ6H7 / Φ8H7 / Φ10H7 / Φ12H7 / Φ16H7 / Φ20H7 | 6 | 5.00~12.00 | 0.45~1.10 |
+| mill 铣面 | face（单面） | 1 | 12.00 | 0.80 |
+
+> **故意不含 Φ25 钻孔 / M18 攻丝**：用于回退测试（未知规格静默跳过场景）。
+
+### 3.5 post_process_rate — 10 种后处理
+
+| 工艺 | 费率¥/kg | 工艺 | 费率¥/kg |
+|------|----------|------|----------|
+| 喷砂 | 1.50 | 粉末喷涂 | 3.00 |
+| 钝化 | 2.00 | 磷化 | 1.80 |
+| 阳极氧化 | 5.00 | 达克罗 | 4.00 |
+| 电泳涂装 | 3.50 | 硬质阳极氧化 | 8.00 |
+| 喷涂 | 2.50 | 化学镀镍 | 9.00 |
+
+> **故意不含「镀铬」**：用于回退测试（未命中后处理场景，成本计 0）。
+
+### 3.6 material_price_history — 260 行月度价格（2025-01 ~ 2026-08）
+
+生成规则（脚本内 CTE 批量生成，非手工录入）：
+
+- 13 个内部牌号 × 20 个月 = 260 行，`source='市场参考价'`。
+- 每月价格 = 对照表参考价 × 月份系数；铝系用 `al_factor`（0.92~1.02 波动），铁系（铸铁/球墨铸铁）用 `ir_factor`（0.95~1.01 波动）。
+- **最新月（2026-08）系数 = 1.00**，即与对照表 `price_per_kg` 完全一致——保证核价结果与静态对照表口径可对账（如 AL-ADC12 当月价 18.50）。
+
+### 3.7 machining_rate — 4 条材质族费率
+
+| 材质族 | 费率¥/h | 备注 |
+|--------|---------|------|
+| 铝合金 | 60.00 | 常规机加工费率 |
+| 铸铝 | 60.00 | 同铝合金 |
+| 铸铁 | 75.00 | 刀具损耗高，费率上浮 |
+| 球墨铸铁 | 80.00 | 强度高，费率最高 |
+
+---
+
+## 4 幂等性与重跑机制
+
+`init.sql` 整体可重复执行，无副作用（NF-3）：
+
+1. **建表**：`CREATE TABLE IF NOT EXISTS`。
+2. **历史去重**：对 SERIAL 表先按业务键删除重复行（保留最小 id）。
+3. **补唯一约束**：`DO $$ ... ADD CONSTRAINT ... EXCEPTION WHEN duplicate_table` 幂等加约束（uq_machining_cycle / uq_grade_mapping / uq_post_process）。
+4. **种子写入**：全部 `ON CONFLICT (...) DO NOTHING`。
+5. **月度价格**：`UNIQUE(internal_code, price_date)` + `ON CONFLICT DO NOTHING`，重跑不翻倍。
+
+---
+
+## 5 数据维护约定
+
+| 场景 | 操作 | 约束 |
+|------|------|------|
+| 月度铝价更新 | `material_price_history` 追加新月行 | 核价自动取最新月并留痕 `price_basis_month` |
+| 新增机加工规格 | `machining_cycle` 增行 | 不改旧行（历史报价可复算） |
+| 新增吨位 | `die_casting_params` 增行 | 同上 |
+| 新增物料 | `material_master` 增行 | material_grade 须能命中对照表，否则走回退 |
+
+> ERP 侧全部为只读基础数据：无 MCP 写工具，数据变更仅通过 SQL/脚本进行。