434 lines
18 KiB
Markdown
434 lines
18 KiB
Markdown
# 试产排程评估系统 — MCP 服务说明
|
||
|
||
**服务名称：** `bexell-scheduling`
|
||
**协议版本：** MCP (Model Context Protocol)，Streamable HTTP 传输
|
||
**挂载路径：** `/bexell/mcp`
|
||
**部署方式：** mcp-server-demo 单进程多模组之一（与 ERP/CRM 模组共享进程与端口 8001）
|
||
**鉴权方式：** 动态 Bearer Token（mcp-auth 后端校验）
|
||
**生成时间：** 2026-09-02
|
||
|
||
---
|
||
|
||
## 一、概述
|
||
|
||
Bexell 模组是 **mcp-server-demo** 统一服务中的一个独立 MCP 模组，基于 **MCPServer** 框架（MCP Python SDK）实现，对外提供 4 个 MCP Tool，服务"试产排程评估及优化"场景。
|
||
|
||
统一服务通过 Starlette `Mount` 将三个模组挂载到不同路径，单进程、单端口（8001）：
|
||
|
||
| 模组 | MCP 端点 | 服务名称 |
|
||
|------|----------|----------|
|
||
| ERP | `http://localhost:8001/erp/mcp` | `mcp-for-erp-auto` |
|
||
| CRM | `http://localhost:8001/crm/mcp` | `mcp-for-crm-auto` |
|
||
| **Bexell** | **`http://localhost:8001/bexell/mcp`** | **`bexell-scheduling`** |
|
||
|
||
MCP 服务面向 **IndepthAI Skill 层**（`trial-production-scheduling-evaluator`）提供数据查询与产能计算能力，是智能体完成"试产排程评估"任务的核心数据通道。
|
||
|
||
---
|
||
|
||
## 二、架构定位
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ IndepthAI Skill 层 │
|
||
│ trial-production-scheduling-evaluator │
|
||
│ （解析输入 → 调用 MCP → 格式化输出） │
|
||
└──────────────────┬───────────────────────┘
|
||
│ MCP 协议（Streamable HTTP + Bearer Token）
|
||
┌──────────────────▼───────────────────────┐
|
||
│ mcp-server-demo 统一服务 (:8001) │
|
||
│ │
|
||
│ /erp/mcp ── ERP 模组 │
|
||
│ /crm/mcp ── CRM 模组 │
|
||
│ /bexell/mcp ── Bexell 模组（4 工具）◄──│
|
||
│ │
|
||
│ 鉴权：mcp-auth 后端 verify-token API │
|
||
└──────────────────┬───────────────────────┘
|
||
│ SQLAlchemy ORM（独立连接池）
|
||
┌──────────────────▼───────────────────────┐
|
||
│ PostgreSQL (bexell_schedule_ai) │
|
||
│ 5 张表 + 1 个视图，无需新增 │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
**模组化优势：**
|
||
|
||
| 维度 | 说明 |
|
||
|------|------|
|
||
| 独立连接池 | Bexell 模组使用 `BEXELL_DB_*` 环境变量配置独立 SQLAlchemy Engine，与 ERP/CRM 数据库完全隔离 |
|
||
| 独立鉴权 | 使用 `BEXELL_MCP_AUTH_API_KEY` 调用 mcp-auth 后端，token 校验按 service 隔离 |
|
||
| 统一运维 | 单进程、单端口，三个模组共享 uvicorn 服务与生命周期管理 |
|
||
| 数据一致性 | Tool 计算复用同一数据库，评估公式在单条聚合 SQL 内完成 |
|
||
| 可演进性 | 模组目录结构统一（tools.py / db.py / models.py），可独立拆分部署 |
|
||
|
||
---
|
||
|
||
## 三、鉴权
|
||
|
||
MCP 端点已启用 **动态 Bearer Token 鉴权**，未携带或携带无效 token 的请求返回 `401 Unauthorized`。
|
||
|
||
**校验流程：**
|
||
|
||
1. 客户端在请求头携带 `Authorization: Bearer <token>`
|
||
2. MCP 服务调用 mcp-auth 后端 `POST {MCP_AUTH_API_URL}/api/auth/verify-token`，以 `X-API-Key: {BEXELL_MCP_AUTH_API_KEY}` 标识调用方服务
|
||
3. 后端统一查询 `mcp_auth.mcp_token` 表，返回 `{"valid": bool, "client_id": str, "service_scope": str}`
|
||
4. token 与 `bexell-scheduling` 服务作用域匹配才校验通过
|
||
5. 进程内缓存校验结果 30s（`MCP_AUTH_CACHE_TTL`），减少对后端的重复调用
|
||
|
||
**客户端配置示例：**
|
||
|
||
```json
|
||
{
|
||
"bexell-scheduling": {
|
||
"type": "http",
|
||
"url": "http://127.0.0.1:8001/bexell/mcp",
|
||
"headers": {
|
||
"Content-Type": "application/json",
|
||
"Accept": "application/json, text/event-stream",
|
||
"Authorization": "Bearer <token>"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**相关环境变量：**
|
||
|
||
| 环境变量 | 说明 |
|
||
|----------|------|
|
||
| `MCP_PUBLIC_URL` / `BEXELL_MCP_PUBLIC_URL` | 服务对外地址（OAuth 资源元数据），模组独立地址未设置时回退通用值 |
|
||
| `MCP_AUTH_API_URL` | mcp-auth 后端地址，如 `https://mcp-auth-admin.digiwincloud.com.cn/mcp-auth-api` |
|
||
| `BEXELL_MCP_AUTH_API_KEY` | Bexell 模组独立 API Key（由 mcp-auth 后端签发） |
|
||
| `MCP_AUTH_CACHE_TTL` | token 校验结果缓存秒数，默认 30 |
|
||
|
||
---
|
||
|
||
## 四、MCP Tool 清单
|
||
|
||
| # | Tool 名称 | 类型 | 用途 |
|
||
|---|-----------|------|------|
|
||
| 1 | `get_equipment_by_type` | 基础查询 | 按设备类型查询该类型所有设备的基础产能信息 |
|
||
| 2 | `get_schedule_occupied` | 基础查询 | 获取指定类型全部设备的已占用产能合计 |
|
||
| 3 | `get_product_load` | 基础查询 | 查询指定品号在目标设备类型各设备上的标准产能 |
|
||
| 4 | `evaluate_trial_capacity` | **一体化计算** | 服务端一次性完成全部数据聚合和公式计算，返回评估结果与推荐设备 |
|
||
|
||
---
|
||
|
||
## 五、Tool 详细说明
|
||
|
||
### 5.1 `get_equipment_by_type` — 按类型查询设备产能
|
||
|
||
**用途：** 根据设备类型获取该类型所有设备的基础产能参数，供 Skill 做数据展示或分步计算。
|
||
|
||
**输入参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `equipment_type` | string | 是 | 设备类型，可选值：`冲压`、`表面`、`检测` |
|
||
|
||
**输出字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `equipment_code` | string | 设备编号（如 CY001、DN003、VJ002） |
|
||
| `equipment_name` | string | 设备名称（如 冲压机1、镀镍机3） |
|
||
| `equipment_type` | string | 设备类型 |
|
||
| `max_capacity` | number | 极限产能（H） |
|
||
| `standard_capacity` | number | 标准产能（H） |
|
||
| `min_startup` | number | 最小开机产能（H） |
|
||
| `line_change_cost` | number | 换线成本系数 |
|
||
|
||
**数据来源：** `equipment_capacity` 表（ORM 模型 `EquipmentCapacity`）
|
||
**查询逻辑：** `WHERE equipment_type = :type ORDER BY equipment_code`
|
||
|
||
**设备类型与数量：**
|
||
|
||
| 设备类型 | 编号范围 | 数量 |
|
||
|----------|----------|------|
|
||
| 冲压 | CY001 ~ CY010 | 10 台 |
|
||
| 表面 | DN001 ~ DN012 | 12 台 |
|
||
| 检测 | VJ001 ~ VJ005 | 5 台 |
|
||
|
||
---
|
||
|
||
### 5.2 `get_schedule_occupied` — 查询排产占用产能
|
||
|
||
**用途：** 获取指定类型全部设备当前已被排产计划占用的产能合计，反映设备负荷现状。
|
||
|
||
**输入参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `equipment_type` | string | 是 | 设备类型，如 `冲压`、`表面`、`检测` |
|
||
|
||
**输出字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `equipment_code` | string | 设备编号 |
|
||
| `equipment_name` | string | 设备名称 |
|
||
| `total_occupied_capacity` | number | 占用产能合计（H），无排产时为 0 |
|
||
|
||
**数据来源：** `product_equipment_schedule` 表（ORM 模型 `ProductEquipmentSchedule`）
|
||
**查询逻辑：** `GROUP BY equipment_code`，`SUM(occupied_capacity)`，`COALESCE` 无记录返回 0
|
||
|
||
---
|
||
|
||
### 5.3 `get_product_load` — 查询品号设备标准产能
|
||
|
||
**用途：** 获取指定品号在目标设备类型各设备上生产时的标准产能消耗系数，用于计算试产需求对设备产能的占用量。
|
||
|
||
**输入参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `product_code` | string | 是 | 品号，如 `A0001`、`A0002`、`A0003` |
|
||
| `equipment_type` | string | 是 | 设备类型，如 `冲压`、`表面`、`检测` |
|
||
|
||
**输出字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `product_code` | string | 品号 |
|
||
| `product_name` | string | 品名 |
|
||
| `equipment_code` | string | 设备编号 |
|
||
| `equipment_name` | string | 设备名称 |
|
||
| `standard_capacity` | number | 该品号在该设备上每生产 1 件所消耗的产能（H/件） |
|
||
|
||
**数据来源：** `product_equipment_load` 表 JOIN `equipment_capacity` 表（ORM 模型 `ProductEquipmentLoad`）
|
||
**查询逻辑：** 按品号 + 设备类型联合过滤，按设备编号排序
|
||
|
||
**品号与标准产能示例（以 A0003 圆柱电池钢壳为例）：**
|
||
|
||
| 设备类型 | 设备编号 | 标准产能（H/件） |
|
||
|----------|----------|-----------------|
|
||
| 冲压 | CY001~CY010 | 0.2 |
|
||
| 表面 | DN001~DN012 | 0.1 |
|
||
| 检测 | VJ001~VJ005 | 0.01 |
|
||
|
||
---
|
||
|
||
### 5.4 `evaluate_trial_capacity` — 一体化试产产能评估 ⭐
|
||
|
||
**用途：** 核心工具。服务端一次性完成全部数据聚合和公式计算，返回每台设备的可用产能明细和最优推荐设备。Skill 层只需调用一次即可完成评估，无需多次查询和自行计算。
|
||
|
||
**评估范围：** 覆盖该品号配置了标准产能的**全部设备类型**（冲压/表面/检测）的所有设备，结果按可用产能降序混合排名。
|
||
|
||
**输入参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `product_code` | string | 是 | 品号，如 `A0003` |
|
||
| `trial_quantity` | integer | 是 | 试产数量，如 `10` |
|
||
|
||
**输出结构：**
|
||
|
||
```json
|
||
{
|
||
"product_code": "A0003",
|
||
"product_name": "圆柱电池钢壳",
|
||
"trial_quantity": 10,
|
||
"evaluated_at": "2026-08-22T15:30:00",
|
||
"results": [
|
||
{
|
||
"rank": 1,
|
||
"equipment_code": "CY003",
|
||
"equipment_name": "冲压机3",
|
||
"equipment_type": "冲压",
|
||
"max_capacity": 15.00,
|
||
"occupied_capacity": 8.00,
|
||
"line_change_cost": 1.00,
|
||
"min_startup_buffer": 0.40,
|
||
"product_standard_capacity": 0.2,
|
||
"trial_demand": 2.00,
|
||
"available_capacity": 3.60,
|
||
"status": "可用"
|
||
}
|
||
],
|
||
"recommended": {
|
||
"equipment_code": "CY003",
|
||
"equipment_name": "冲压机3",
|
||
"available_capacity": 3.60
|
||
}
|
||
}
|
||
```
|
||
|
||
**输出字段说明（results 数组内每条记录）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `rank` | integer | 排名（按可用产能降序，跨设备类型混合排名） |
|
||
| `equipment_code` | string | 设备编号 |
|
||
| `equipment_name` | string | 设备名称 |
|
||
| `equipment_type` | string | 设备类型 |
|
||
| `max_capacity` | number | 极限产能（H） |
|
||
| `occupied_capacity` | number | 当前占用产能合计（H） |
|
||
| `line_change_cost` | number | 换线成本 |
|
||
| `min_startup_buffer` | number | 最小开机缓冲（= min_startup × 0.1） |
|
||
| `product_standard_capacity` | number | 该品号在该设备的标准产能（H/件） |
|
||
| `trial_demand` | number | 试产需求（= 试产数量 × 标准产能） |
|
||
| `available_capacity` | number | **可用产能**（核心指标） |
|
||
| `status` | string | 状态：`可用`（≥0）或 `已满负荷`（<0） |
|
||
|
||
**核心计算公式：**
|
||
|
||
```
|
||
可用产能 = 极限产能
|
||
− 占用产能合计
|
||
− 换线成本
|
||
− 最小开机 × 0.1
|
||
− 试产数量 × 品号标准产能
|
||
```
|
||
|
||
**数据来源（一次聚合查询，单条 SQL 完成）：**
|
||
|
||
| 公式因子 | 来源表 | 字段 |
|
||
|----------|--------|------|
|
||
| 极限产能 | `equipment_capacity` | `max_capacity` |
|
||
| 占用产能合计 | `product_equipment_schedule` | `SUM(occupied_capacity)` |
|
||
| 换线成本 | `equipment_capacity` | `line_change_cost` |
|
||
| 最小开机 | `equipment_capacity` | `min_startup` |
|
||
| 品号标准产能 | `product_equipment_load` | `standard_capacity` |
|
||
| 品名 | `product_info` | `product_name` |
|
||
|
||
**推荐逻辑：** 取 `results` 中排名第一（可用产能最大）且 `available_capacity >= 0` 的设备；若无设备满足条件，`recommended` 返回 `null`。
|
||
|
||
---
|
||
|
||
## 六、Tool 调用策略
|
||
|
||
| 场景 | 推荐方式 | 说明 |
|
||
|------|---------|------|
|
||
| **试产评估（默认）** | 直接调用 `evaluate_trial_capacity` | 一次调用完成全部计算，Skill 只需格式化输出 |
|
||
| **分步调试 / 中间数据展示** | Tool 1 → Tool 2 → Tool 3 → Skill 内计算 | 适用于需要逐步展示数据来源或教学演示场景 |
|
||
| **仅查看设备信息** | 调用 `get_equipment_by_type` | 不涉及排产计算，纯基础数据查询 |
|
||
| **仅查看负荷现状** | 调用 `get_schedule_occupied` | 查看当前排产占用情况 |
|
||
|
||
---
|
||
|
||
## 七、数据模型依赖
|
||
|
||
Bexell 模组复用 `bexell_schedule_ai` 库中以下现有表和 ORM 模型（定义于 `src/modules/bexell/models.py`），**无需新增任何表结构**：
|
||
|
||
| 表 / 视图 | ORM 模型 | 说明 |
|
||
|-----------|----------|------|
|
||
| `sys_parameter` | `SysParameter` | 系统参数（`sys_s_parameter` = 影响系数 0.1） |
|
||
| `equipment_capacity` | `EquipmentCapacity` | 设备基础产能（极限/标准/最小开机/换线成本） |
|
||
| `product_info` | `ProductInfo` | 品号主数据 |
|
||
| `product_equipment_load` | `ProductEquipmentLoad` | 品号 × 设备标准产能（81 行种子数据） |
|
||
| `product_equipment_schedule` | `ProductEquipmentSchedule` | 排产明细（排产数量 & 占用产能） |
|
||
| `v_equipment_realtime_capacity` | —（视图） | 设备实时产能视图（评估工具未直接使用，供查询参考） |
|
||
|
||
**表关系：**
|
||
|
||
```
|
||
┌─────────────────────┐
|
||
│ sys_parameter │ 系统参数（影响系数 0.1）
|
||
└─────────────────────┘
|
||
|
||
┌─────────────────────┐ ┌──────────────────────────┐
|
||
│ equipment_capacity │────▶│ product_equipment_load │
|
||
│ • 设备基础产能 │ │ • 品号×设备 标准产能 │
|
||
│ • 极限/标准/开机 │ │ • 关联 product_info │
|
||
│ • 换线成本 │ │ • 关联 equipment_capacity│
|
||
└──────────┬──────────┘ └──────────────────────────┘
|
||
│
|
||
│ LEFT JOIN（占用产能聚合）
|
||
▼
|
||
┌──────────────────────────────┐
|
||
│ product_equipment_schedule │
|
||
│ • 排产明细 │
|
||
│ • 排产数量 & 占用产能 │
|
||
└──────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 八、Skill 集成
|
||
|
||
MCP 服务配套 Skill：**`trial-production-scheduling-evaluator`**
|
||
|
||
**Skill 执行流程：**
|
||
|
||
```
|
||
用户输入（品号 + 试产数量 + 设备类型）
|
||
│
|
||
▼
|
||
Step 1: 解析参数 & 校验
|
||
│
|
||
▼
|
||
Step 2: 调用 evaluate_trial_capacity
|
||
│ 传入 product_code + trial_quantity
|
||
▼
|
||
Step 3: 结果排序 & 状态标记
|
||
│ 可用产能 ≥ 0 → "可用"
|
||
│ 可用产能 < 0 → "已满负荷"
|
||
▼
|
||
Step 4: 格式化输出评估报告
|
||
• 推荐设备（★）
|
||
• 全部候选设备明细表
|
||
• 风险提示
|
||
```
|
||
|
||
**触发场景：**
|
||
- 评估试产排程
|
||
- 查询设备可用产能
|
||
- 推荐试产设备
|
||
- 计算设备产能负荷
|
||
|
||
---
|
||
|
||
## 九、错误处理
|
||
|
||
| 错误场景 | 返回内容 |
|
||
|----------|---------|
|
||
| token 缺失 / 无效 / 服务作用域不匹配 | MCP 层返回 `401 Unauthorized`（本地缓存 30s，后端不可达时同样拒绝） |
|
||
| 品号不存在 | `{"error": "品号 XXX 不存在"}` |
|
||
| 品号在某设备无标准产能配置 | 该设备不参与排名（JOIN 过滤），不报错 |
|
||
| 所有设备已满负荷 | `recommended` 返回 `null`，`results` 中所有 `status` 为 "已满负荷" |
|
||
| 数据库连接失败 | 由 SQLAlchemy（`pool_pre_ping`）与统一服务异常处理捕获 |
|
||
|
||
---
|
||
|
||
## 十、技术实现要点
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 框架 | MCPServer（MCP Python SDK），非 FastAPI 挂载 |
|
||
| 挂载方式 | `server.py` 中 `Starlette Mount("/bexell", bexell_server.streamable_http_app(streamable_http_path="/mcp"))`，子路径 `/mcp` |
|
||
| 鉴权 | `get_auth(service="BEXELL")` 构建 `AuthSettings` + `ApiTokenVerifier`，Bearer Token 动态校验 |
|
||
| 数据库访问 | 模组独立 SQLAlchemy Engine（`BEXELL_DB_*` 环境变量），`pool_size=10`、`pool_pre_ping=True` |
|
||
| ORM 模型 | `src/modules/bexell/models.py` 中定义 5 张表模型 |
|
||
| 核心计算 | `evaluate_trial_capacity` 通过单条聚合 SQL 完成（LEFT JOIN 占用聚合 + JOIN 品号负荷），避免多次往返 |
|
||
| 影响系数 | 公式中 `0.1` 对应 `sys_parameter.sys_s_parameter`（当前为 SQL 硬编码） |
|
||
| 并发安全 | 每次工具调用独立获取/关闭 DB Session |
|
||
| 生命周期 | 父 app lifespan 统一管理 session manager 启动与连接池关闭（`close_bexell_engine`） |
|
||
|
||
---
|
||
|
||
## 十一、文件结构
|
||
|
||
```
|
||
mcp-server-demo/
|
||
├── .env.example # 环境变量模板（BEXELL_MCP_AUTH_API_KEY、BEXELL_DB_* 等）
|
||
├── sql/bexell_init.sql # bexell_schedule_ai 建表 + 种子数据（5 表 + 1 视图）
|
||
├── src/
|
||
│ ├── server.py # 统一服务入口：Mount("/bexell") + lifespan
|
||
│ ├── auth.py # 动态 Bearer Token 鉴权（mcp-auth 后端校验）
|
||
│ └── modules/
|
||
│ └── bexell/
|
||
│ ├── __init__.py
|
||
│ ├── tools.py # MCPServer + 4 个 MCP Tool
|
||
│ ├── db.py # 独立 SQLAlchemy Engine / SessionLocal
|
||
│ └── models.py # 5 张表 ORM 模型
|
||
└── docs/bexell/
|
||
└── mcp-services.md # 本文档
|
||
```
|
||
|
||
**启动方式：**
|
||
|
||
```bash
|
||
cd mcp-server-demo
|
||
set -a; source .env; set +a
|
||
cd src && python server.py
|
||
# Bexell MCP 端点: http://localhost:8001/bexell/mcp
|
||
```
|