# WMS库存页面MES接口集成设计文档

**日期**: 2026-04-12
**项目**: WIDESEA WMS
**作者**: Claude Code

---

## 一、需求概述

为WMS库存信息页面和库存明细页面添加操作列，调用MES系统的出站/入站/绑定/解绑/NG上报接口，实现WMS与MES的数据同步。

### 功能范围

**库存信息页面（stockInfo.vue）- 托盘级别：**
- 托盘进站（调用MES InboundInContainer接口）
- 托盘出站（调用MES OutboundInContainer接口）

**库存明细页面（stockInfoDetail.vue）- 电芯级别：**
- 托盘电芯绑定（调用MES BindContainer接口）
- 托盘电芯解绑（调用MES UnBindContainer接口）
- 托盘NG电芯上报（调用MES ContainerNgReport接口）

---

## 二、架构设计

### 2.1 系统架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                         前端 (Vue 3)                           │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │  stockInfo.vue   │  │stockInfoDetail   │  │ MesDialog.vue  │ │
│  │  (库存信息)       │  │  .vue(库存明细)   │  │ (确认对话框)    │ │
│  │  + 操作列        │  │  + 操作列         │  │                │ │
│  └────────┬─────────┘  └────────┬─────────┘  └────────┬───────┘ │
│           │                     │                      │         │
│           └─────────────────────┴──────────────────────┘         │
│                              │                                   │
└──────────────────────────────┼───────────────────────────────────┘
                               │ HTTP API
┌──────────────────────────────┼───────────────────────────────────┐
│                               ▼                    后端 (.NET)   │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │ StockController  │→ │  MesController   │  │ MesLogService  │ │
│  │                  │  │                  │  │                │ │
│  └──────────────────┘  └────────┬─────────┘  └────────────────┘ │
│                                 │                                  │
│                                 ▼                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │   IMesService    │→ │   MesService     │  │Dt_MesApiLog    │ │
│  │   (接口定义)      │  │   (HTTP调用)     │  │  (日志表)       │ │
│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  MES系统     │
                        │  (外部接口)   │
                        └──────────────┘
```

### 2.2 技术栈

- **前端**: Vue 3, Element Plus, Pinia
- **后端**: .NET 8, ASP.NET Core, SqlSugar ORM
- **数据库**: SQL Server
- **HTTP客户端**: HttpClient (后端调用MES)

---

## 三、前端设计

### 3.1 库存信息页面 (stockInfo.vue)

#### 操作列设计

**表格列配置：**
```javascript
{
  field: "actions",
  title: "操作",
  width: 200,
  fixed: "right",
  align: "center",
  formatter: (row) => renderActions(row)
}
```

**按钮定义：**
- 进站按钮：调用托盘进站接口
- 出站按钮：调用托盘出站接口

**按钮显示规则：**

| 库存状态 | 进站 | 出站 |
|---------|:----:|:----:|
| 待入库 (0) | ✓ | ✗ |
| 在库 (1) | ✗ | ✓ |
| 出库中 (2) | ✗ | ✓ |
| 锁定 (3) | ✗ | ✗ |

### 3.2 库存明细页面 (stockInfoDetail.vue)

#### 操作列设计

**表格列配置：**
```javascript
{
  field: "actions",
  title: "操作",
  width: 280,
  fixed: "right",
  align: "center",
  formatter: (row) => renderActions(row)
}
```

**按钮定义：**
- 绑定按钮：调用托盘电芯绑定接口
- 解绑按钮：调用托盘电芯解绑接口
- NG上报按钮：调用托盘NG电芯上报接口

**按钮显示规则：**

| 电芯状态 | 绑定 | 解绑 | NG上报 |
|---------|:----:|:----:|:------:|
| 正常 (1) | ✓ | ✓ | ✓ |
| 异常 (2) | ✓ | ✓ | ✓ |
| 已锁定 (99) | ✗ | ✗ | ✗ |

### 3.3 确认对话框组件 (MesConfirmDialog.vue)

**组件职责：**
- 显示即将执行的操作信息
- 展示关键参数（托盘码、设备编码等）
- 提供确认/取消按钮
- 显示调用结果（成功/失败）

**Props定义：**
```typescript
interface MesConfirmDialogProps {
  visible: boolean;
  operationType: 'inbound' | 'outbound' | 'bind' | 'unbind' | 'ngReport';
  palletCode: string;
  stockInfo?: any;
  detailInfo?: any;
}
```

### 3.4 交互流程

```
用户点击操作按钮
    │
    ▼
检查登录状态 ──────→ 未登录 ────→ 提示"请先登录"
    │
    ▼ 已登录
检查操作权限 ──────→ 无权限 ────→ 提示"无权限执行此操作"
    │
    ▼ 有权限
弹出确认对话框
    │
    ▼
用户点击"确认执行"
    │
    ▼
显示loading状态
    │
    ▼
调用后端API
    │
    ├─→ 成功 ────→ 显示成功提示 ────→ 刷新列表
    │
    └─→ 失败 ────→ 显示错误提示 + "重试"按钮
```

---

## 四、后端设计

### 4.1 API接口设计

#### 4.1.1 库存信息相关接口

**托盘进站**
```csharp
/// <summary>
/// 托盘进站 - 调用MES接口
/// </summary>
[HttpPost("inboundInContainer")]
public async Task<WebResponseContent> InboundInContainer([FromBody] InboundInContainerRequestDto dto)
```

**请求DTO：**
```csharp
public class InboundInContainerRequestDto
{
    /// <summary>
    /// 托盘编号
    /// </summary>
    public string PalletCode { get; set; }

    /// <summary>
    /// 库存ID
    /// </summary>
    public long StockId { get; set; }
}
```

**托盘出站**
```csharp
/// <summary>
/// 托盘出站 - 调用MES接口
/// </summary>
[HttpPost("outboundInContainer")]
public async Task<WebResponseContent> OutboundInContainer([FromBody] OutboundInContainerRequestDto dto)
```

**请求DTO：**
```csharp
public class OutboundInContainerRequestDto
{
    /// <summary>
    /// 托盘编号
    /// </summary>
    public string PalletCode { get; set; }

    /// <summary>
    /// 库存ID
    /// </summary>
    public long StockId { get; set; }

    /// <summary>
    /// 产品参数列表（可选）
    /// </summary>
    public List<ParamItemDto> ParamList { get; set; }
}
```

#### 4.1.2 库存明细相关接口

**托盘电芯绑定**
```csharp
/// <summary>
/// 托盘电芯绑定 - 调用MES接口
/// </summary>
[HttpPost("bindContainer")]
public async Task<WebResponseContent> BindContainer([FromBody] BindContainerRequestDto dto)
```

**请求DTO：**
```csharp
public class BindContainerRequestDto
{
    /// <summary>
    /// 托盘编号
    /// </summary>
    public string PalletCode { get; set; }

    /// <summary>
    /// 电芯码列表
    /// </summary>
    public List<string> SfcList { get; set; }

    /// <summary>
    /// 位置信息
    /// </summary>
    public string Location { get; set; }

    /// <summary>
    /// 操作类型：0-默认 1-进站 2-出站 3-进出站
    /// </summary>
    public int OperationType { get; set; } = 1;
}
```

**托盘电芯解绑**
```csharp
/// <summary>
/// 托盘电芯解绑 - 调用MES接口
/// </summary>
[HttpPost("unbindContainer")]
public async Task<WebResponseContent> UnbindContainer([FromBody] UnbindContainerRequestDto dto)
```

**请求DTO：**
```csharp
public class UnbindContainerRequestDto
{
    /// <summary>
    /// 托盘编号
    /// </summary>
    public string PalletCode { get; set; }

    /// <summary>
    /// 电芯码列表
    /// </summary>
    public List<string> SfcList { get; set; }
}
```

**托盘NG电芯上报**
```csharp
/// <summary>
/// 托盘NG电芯上报 - 调用MES接口
/// </summary>
[HttpPost("containerNgReport")]
public async Task<WebResponseContent> ContainerNgReport([FromBody] ContainerNgReportRequestDto dto)
```

**请求DTO：**
```csharp
public class ContainerNgReportRequestDto
{
    /// <summary>
    /// 托盘编号
    /// </summary>
    public string PalletCode { get; set; }

    /// <summary>
    /// NG电芯列表
    /// </summary>
    public List<NgSfcItemDto> NgSfcList { get; set; }
}

public class NgSfcItemDto
{
    /// <summary>
    /// 产品条码
    /// </summary>
    public string Sfc { get; set; }

    /// <summary>
    /// NG代码
    /// </summary>
    public string NgCode { get; set; }

    /// <summary>
    /// NG设备
    /// </summary>
    public string NgEquipmentCode { get; set; }

    /// <summary>
    /// NG资源
    /// </summary>
    public string NgResourceCode { get; set; }
}
```

### 4.2 数据库设计

#### 4.2.1 MES接口调用日志表

```sql
CREATE TABLE Dt_MesApiLog (
    Id BIGINT PRIMARY KEY IDENTITY(1,1),
    ApiType NVARCHAR(50) NOT NULL,           -- 接口类型
    RequestJson NVARCHAR(MAX) NULL,          -- 请求JSON
    ResponseJson NVARCHAR(MAX) NULL,         -- 响应JSON
    IsSuccess BIT NOT NULL DEFAULT 0,        -- 是否成功
    ErrorMessage NVARCHAR(500) NULL,         -- 错误信息
    ElapsedMs INT NOT NULL DEFAULT 0,        -- 耗时(毫秒)
    CreateDate DATETIME NOT NULL,            -- 创建时间
    Creator NVARCHAR(50) NULL,               -- 创建人
    INDEX IX_MesApiLog_ApiType (ApiType),
    INDEX IX_MesApiLog_CreateDate (CreateDate)
);
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| Id | bigint | 主键 |
| ApiType | string(50) | 接口类型：InboundInContainer, OutboundInContainer, BindContainer, UnbindContainer, ContainerNgReport |
| RequestJson | string(MAX) | MES接口请求JSON |
| ResponseJson | string(MAX) | MES接口响应JSON |
| IsSuccess | bool | 调用是否成功 |
| ErrorMessage | string(500) | 失败时的错误信息 |
| ElapsedMs | int | 接口调用耗时（毫秒） |
| CreateDate | datetime | 创建时间 |
| Creator | string(50) | 创建人 |

#### 4.2.2 系统配置表扩展

```sql
-- 在 Dt_SystemConfig 表中新增MES配置项
INSERT INTO Dt_SystemConfig (ConfigKey, ConfigValue, Description, CreateDate)
VALUES
('MES_EquipmentCode', 'WCS_001', 'MES设备编码', GETDATE()),
('MES_ResourceCode', 'RESOURCE_001', 'MES资源编码', GETDATE()),
('MES_ApiBaseUrl', 'http://mes-server/api', 'MES接口地址', GETDATE()),
('MES_TimeoutSeconds', '30', 'MES接口超时时间(秒)', GETDATE());
```

### 4.3 服务层设计

#### 4.3.1 MES日志服务接口

```csharp
/// <summary>
/// MES接口日志服务接口
/// </summary>
public interface IMesLogService : IDependency
{
    /// <summary>
    /// 记录MES接口调用日志
    /// </summary>
    Task<bool> LogAsync(MesApiLogDto log);

    /// <summary>
    /// 获取最近的MES接口调用记录
    /// </summary>
    Task<List<MesApiLogDto>> GetRecentLogsAsync(string apiType, int count = 50);
}
```

#### 4.3.2 MES日志服务实现

```csharp
/// <summary>
/// MES接口日志服务实现
/// </summary>
public class MesLogService : IMesLogService
{
    private readonly ISqlSugarClient _db;

    public async Task<bool> LogAsync(MesApiLogDto log)
    {
        var entity = new Dt_MesApiLog
        {
            ApiType = log.ApiType,
            RequestJson = log.RequestJson,
            ResponseJson = log.ResponseJson,
            IsSuccess = log.IsSuccess,
            ErrorMessage = log.ErrorMessage,
            ElapsedMs = log.ElapsedMs,
            CreateDate = DateTime.Now,
            Creator = log.Creator
        };

        return await _db.Insertable(entity).ExecuteCommandAsync() > 0;
    }

    public async Task<List<MesApiLogDto>> GetRecentLogsAsync(string apiType, int count = 50)
    {
        return await _db.Queryable<Dt_MesApiLog>()
            .Where(x => x.ApiType == apiType)
            .OrderByDescending(x => x.CreateDate)
            .Take(count)
            .ToListAsync();
    }
}
```

---

## 五、接口调用流程

### 5.1 托盘进站流程

```
用户点击"进站"按钮
    │
    ▼
前端弹出确认对话框（显示托盘码、设备编码等）
    │
    ▼
用户确认
    │
    ▼
前端调用 POST /api/StockInfo/inboundInContainer
    │
    ▼
后端 StockInfoController.InboundInContainer()
    │
    ├─→ 1. 验证库存状态（仅"待入库"状态允许进站）
    │
    ├─→ 2. 获取系统配置（设备编码、资源编码）
    │
    ├─→ 3. 构造MES请求对象
    │
    ├─→ 4. 调用 IMesService.InboundInContainer()
    │   │
    │   ├─→ 记录开始时间
    │   ├─→ 发送HTTP请求到MES
    │   ├─→ 记录响应、耗时
    │   └─→ 保存日志到 Dt_MesApiLog
    │
    ├─→ 5. 返回结果给前端
    │
    └─→ 前端显示成功/失败提示
```

### 5.2 托盘电芯绑定流程

```
用户点击"绑定"按钮
    │
    ▼
前端弹出确认对话框（显示托盘码、电芯码列表）
    │
    ▼
用户确认
    │
    ▼
前端调用 POST /api/StockInfoDetail/bindContainer
    │
    ▼
后端 StockInfoDetailController.BindContainer()
    │
    ├─→ 1. 验证电芯状态（非"已锁定"状态允许绑定）
    │
    ├─→ 2. 获取系统配置
    │
    ├─→ 3. 构造MES请求对象（包含电芯码列表）
    │
    ├─→ 4. 调用 IMesService.BindContainer()
    │   │
    │   ├─→ 记录开始时间
    │   ├─→ 发送HTTP请求到MES
    │   ├─→ 记录响应、耗时
    │   └─→ 保存日志到 Dt_MesApiLog
    │
    ├─→ 5. 返回结果给前端
    │
    └─→ 前端显示成功/失败提示
```

---

## 六、错误处理

### 6.1 错误类型

| 错误类型 | 说明 | 处理方式 |
|---------|------|---------|
| 网络超时 | MES服务器无响应或连接超时 | 显示错误提示，提供"重试"按钮 |
| 业务校验失败 | 托盘不存在、电芯已绑定等 | 显示MES返回的错误信息 |
| 认证失败 | MES接口认证信息过期 | 显示"MES认证失败，请联系管理员" |
| 参数错误 | 请求参数不完整或格式错误 | 显示"参数错误：{具体错误}" |
| 未知错误 | MES系统返回异常响应 | 显示"MES系统异常，请稍后重试" |

### 6.2 前端错误提示

```javascript
// 成功提示
ElMessage.success('托盘进站成功');

// 失败提示
ElMessage.error({
  message: 'MES服务器连接超时，请检查网络后重试',
  showRetry: true,
  onRetry: () => retryOperation()
});
```

### 6.3 后端错误日志

```csharp
try
{
    // 调用MES接口
}
catch (HttpRequestException ex)
{
    // 网络异常
    await _mesLogService.LogAsync(new MesApiLogDto
    {
        ApiType = "InboundInContainer",
        IsSuccess = false,
        ErrorMessage = $"网络异常: {ex.Message}",
        ElapsedMs = elapsedMs
    });
    return ResponseContent.Error("MES服务器连接失败，请检查网络");
}
catch (Exception ex)
{
    // 其他异常
    _logger.LogError(ex, "调用MES接口异常");
    return ResponseContent.Error($"MES接口调用失败: {ex.Message}");
}
```

---

## 七、权限控制

### 7.1 功能权限定义

建议在系统中新增以下功能权限：

| 权限代码 | 权限名称 | 说明 |
|---------|---------|------|
| MES_INBOUND | MES进站操作 | 允许执行托盘进站操作 |
| MES_OUTBOUND | MES出站操作 | 允许执行托盘出站操作 |
| MES_BIND | MES绑定操作 | 允许执行电芯绑定操作 |
| MES_UNBIND | MES解绑操作 | 允许执行电芯解绑操作 |
| MES_NG_REPORT | MES NG上报 | 允许执行NG上报操作 |

### 7.2 权限验证

```csharp
[HttpPost("inboundInContainer")]
[Permission("MES_INBOUND")]
public async Task<WebResponseContent> InboundInContainer([FromBody] InboundInContainerRequestDto dto)
{
    // 接口实现
}
```

---

## 八、文件变更清单

### 8.1 前端文件

```
WMS/WIDESEA_WMSClient/src/
├── views/stock/
│   ├── stockInfo.vue                         # 修改：添加操作列
│   └── stockInfoDetail.vue                   # 修改：添加操作列
├── components/
│   └── MesConfirmDialog.vue                  # 新增：MES确认对话框
└── api/
    └── mes.js                                # 新增：MES API调用
```

### 8.2 后端文件

```
WMS/WIDESEA_WMSServer/
├── Controllers/
│   └── Stock/
│       ├── StockInfoController.cs            # 修改：添加进站/出站接口
│       └── StockInfoDetailController.cs      # 修改：添加绑定/解绑/NG上报接口
├── Services/
│   └── Mes/
│       ├── IMesLogService.cs                 # 新增：日志服务接口
│       └── MesLogService.cs                  # 新增：日志服务实现
└── DTO/
    ├── Mes/
    │   ├── MesApiLogDto.cs                   # 新增：日志DTO
    │   ├── InboundInContainerRequestDto.cs   # 新增：进站请求DTO
    │   ├── OutboundInContainerRequestDto.cs  # 新增：出站请求DTO
    │   ├── BindContainerRequestDto.cs        # 新增：绑定请求DTO
    │   ├── UnbindContainerRequestDto.cs      # 新增：解绑请求DTO
    │   └── ContainerNgReportRequestDto.cs    # 新增：NG上报请求DTO
    └── Models/
        └── Mes/
            └── Dt_MesApiLog.cs                # 新增：日志实体
```

### 8.3 数据库文件

```
Database/
└── Scripts/
    └── 20260412_MesApiLog.sql                # 新增：日志表创建脚本
```

---

## 九、测试要点

### 9.1 功能测试

| 测试场景 | 预期结果 |
|---------|---------|
| 待入库状态托盘点击进站 | 弹出确认对话框，确认后成功调用 |
| 在库状态托盘点击进站 | 进站按钮不显示 |
| 网络中断时点击操作 | 显示网络错误提示，提供重试按钮 |
| MES返回业务错误 | 显示MES返回的具体错误信息 |
| 点击操作后刷新页面 | 操作记录已保存到日志表 |

### 9.2 性能测试

| 指标 | 目标值 |
|------|--------|
| MES接口响应时间 | < 2秒 |
| 前端按钮点击响应 | < 100ms |
| 日志写入耗时 | < 50ms |

---

## 十、后续优化建议

1. **批量操作**：支持选中多个托盘/电芯批量调用MES接口
2. **自动重试**：对于网络超时等临时故障，自动重试3次
3. **接口监控**：增加MES接口调用的实时监控和告警
4. **参数配置化**：将超时时间、重试次数等参数做成可配置项
5. **操作审计**：增加操作审计日志，记录谁在什么时间执行了什么操作

---

**文档版本**: 1.0
**最后更新**: 2026-04-12