# 试产排程评估系统 — 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
```