# Label Replace API Documentation
# 标签替换接口文档

## 接口概述
该接口用于处理标签替换请求，允许客户端提交中性面单号及其他相关信息来请求替换标签，支持正常换单和冻结换单功能。

## 请求信息

### URL
```
POST /api/label-replace
```

### 请求方法
`POST`

### 请求头
```
Content-Type: application/json
```

### 请求参数
| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| BillOfLadingNumber | string | 否 | 提单号 |
| MasterPackageNumber | string | 否 | 大包号 |
| ReferenceNumber | string | 否 | 参考号（一般表示订单号） |
| NeutralWaybillNumber | string | 是 | 中性面单单号（必填） |
| FinalMileTrackingNumber | string | 否 | 尾程跟踪单号 |
| Label | string | 否 | 标签内容（一般为PDF，可能是base64或其他格式） |
| ReplaceStatus | string | 否 | 换单状态（Y表示正常换单，N表示冻结换单，默认为Y） |

### 请求示例

#### 正常换单请求
```json
{
  "BillOfLadingNumber": "BL12345678",
  "MasterPackageNumber": "MP98765432",
  "ReferenceNumber": "ORD123456",
  "NeutralWaybillNumber": "NW1234567890",
  "FinalMileTrackingNumber": "FM1234567890",
  "Label": "base64_encoded_pdf_content",
  "ReplaceStatus": "Y"
}
```

#### 冻结换单请求
```json
{
  "NeutralWaybillNumber": "NW1234567890",
  "ReplaceStatus": "N"
}
```

## 响应信息

### 成功响应

#### 响应状态码
`200 OK`

#### 响应头
```
Content-Type: application/json
```

#### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| neutralWaybillNumber | string | 请求中的中性面单单号 |
| replaceStatus | string | 实际使用的换单状态 |
| labelReplaced | boolean | 标签是否成功替换（正常换单为true，冻结换单为false） |
| message | string | 响应消息 |

#### 成功响应示例

##### 正常换单响应
```json
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "Y",
  "labelReplaced": true,
  "message": "Label replacement request processed successfully"
}
```

##### 冻结换单响应
```json
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "N",
  "labelReplaced": false,
  "message": "Label replacement request has been frozen"
}
```

### 错误响应

#### 响应状态码
`400 Bad Request`

#### 错误响应示例

##### 缺少必填字段
```json
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
```

##### 请求体为空
```json
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
```

##### 无效的换单状态
```json
{
  "status": "error",
  "message": "Invalid replace status. Use 'Y' for normal replacement or 'N' for frozen replacement"
}
```

##### 服务器错误
```json
{
  "status": "error",
  "message": "具体错误信息"
}
```

## 实现细节

### 代码位置
`/d:/EPproject/LabelReplaceServer/src/CONTROLLER/Controllers/TagController.cs` 第117-174行

### 核心逻辑
1. 验证请求是否包含必填的中性面单单号
2. 验证换单状态参数的有效性（只能是Y或N）
3. 记录请求日志，包括中性面单单号和换单状态
4. 处理标签替换业务逻辑（根据换单状态决定是否执行换单）
5. 返回响应结果，包含实际的换单状态和处理结果

### 日志记录
接口会记录以下关键信息：
- 收到的标签替换请求及中性面单号
- 换单状态信息
- 处理结果及中性面单号
- 任何发生的错误信息

## 注意事项

1. **必填字段**：必须提供`NeutralWaybillNumber`字段
2. **换单状态**：如果提供`ReplaceStatus`字段，只能是"Y"或"N"，默认为"Y"
3. **数据格式**：所有字符串字段应确保格式正确
4. **标签内容**：如果提供`Label`字段，应确保其为有效的格式（如base64编码的PDF）
5. **并发处理**：接口设计支持并发请求，每个请求相互独立
6. **错误处理**：所有错误都会返回适当的HTTP状态码和详细的错误消息

## 文档更新日志

| 日期 | 更新内容 | 更新人 |
|------|----------|--------|
| 2026-01-13 | 1. 初始创建文档<br>2. 添加换单状态字段说明<br>3. 完善请求/响应示例 | 系统生成 |