# 后端 Caller / Device 字段接收清单

> **说明**：客户端（变色龙换单软件）已改造完成，所有业务 API 请求均携带以下 Header。后端需在以下接口中接收并记录这些字段。
>
> ⚠️ 旧 OMS 接口（`InternalGetLabel.ashx`）不需要改造。

---

## 一、Header 规范

| Header 名称 | 值 | 示例 | 空值行为 | 回退策略 |
|-------------|-----|------|----------|----------|
| `Caller` | 当前登录用户名 | `zhangsan` | 未登录时不发送 | 回退为 `"system"` |
| `DeviceCode` | 设备唯一编码（GUID） | `a1b2c3d4e5f67890abcd` | 不发送 | — |
| `DeviceName` | 设备名称（计算机名） | `PC-WAREHOUSE-01` | 不发送 | — |

---

## 二、设备编码生成逻辑

- **首次运行**：自动生成 32 位 GUID（去掉横线），持久化到 `config.xml`
- **后续运行**：直接读取 `config.xml` 中的编码，不会变化
- **设备名称**：取自 `Environment.MachineName`，首次运行时写入 `config.xml`

---

## 三、需改造接口清单

### 3.1 面单/标签 PDF 下载接口

| # | 方法 | API 端点 | 说明 |
|---|------|----------|------|
| 1 | GET | `{base}/api/label/label-replace/waybill/{trackingNumber}/download` | 换单接口下载面单 PDF |
| 2 | GET | `{base}/api/label/label-replace/waybill/{trackingNumber}/downloadNoTri` | 换单接口下载面单 PDF（不触发皮带机） |
| 3 | GET | `{base}/api/bagtag/{tagNumber}/print` | 获取袋牌 PDF |
| 4 | GET | `{base}/api/shipping-handover/{bolNumber}/print` | 获取 BOL PDF |

### 3.2 袋牌管理接口

| # | 方法 | API 端点 | 说明 | 额外改造 |
|---|------|----------|------|----------|
| 5 | POST | `{base}/api/bagtag/generate` | 生成袋牌 | — |
| 6 | POST | `{base}/api/bagtag/auto-pack/start` | 启动自动集包 | 请求体 `creator` 字段值为当前用户名 |

### 3.3 BOL 创建/关联接口

| # | 方法 | API 端点 | 说明 | 额外改造 |
|---|------|----------|------|----------|
| 7 | GET | `{base}/api/shipping-handover/generate-number?channel={channel}` | 生成 BOL 单号 | — |
| 8 | GET | `{base}/api/shipping-handover/create?HandoverNumber={...}&Channel={...}&Creator={...}&TimeZone=America/New_York` | 创建 BOL | URL 参数 `Creator` 值为当前用户名 |
| 9 | GET | `{base}/api/bagtag/available?channel={channel}` | 查询可用袋牌 | — |
| 10 | GET | `{base}/api/shipping-handover/bag-tag/associate-by-number/{bolId}?bagTagNumbers={...}` | 关联袋牌到 BOL | — |
| 11 | GET | `{base}/api/shipping-handover/{bolNumber}/print` | 打印 BOL | — |

---

## 四、汇总

| 维度 | 数量 |
|------|------|
| **涉及接口总数** | 11 |
| **GET 请求** | 9 |
| **POST 请求** | 2 |
| **每个请求携带 Header** | `Caller` + `DeviceCode` + `DeviceName`（3 个） |

---

## 五、环境 Base URL

| 环境 | Base URL |
|------|----------|
| 测试环境 | `http://172.232.21.79:5002` |
| 生产环境 | `https://lr.tooexp.com` |

---

## 六、后端改造要点

1. 在以上 **11 个接口**中，从 HTTP Header 读取以下字段：
   - `Caller` — 截库调用人（用户名）
   - `DeviceCode` — 设备唯一编码（GUID）
   - `DeviceName` — 设备名称（计算机名）
2. 将以上字段记录到操作日志/审计日志中
3. 第 **6 号接口**（自动集包）：请求体 `creator` 字段值为当前用户名
4. 第 **8 号接口**（创建 BOL）：URL 参数 `Creator` 值为当前用户名
5. 如 `Caller` Header 为空，建议回退兼容 `"system"`

---

## 七、请求示例

```
GET /api/label/label-replace/waybill/YW202605270001/download HTTP/1.1
Host: 172.232.21.79:5002
Caller: zhangsan
DeviceCode: a1b2c3d4e5f67890abcdef1234567890
DeviceName: PC-WAREHOUSE-01
satoken: xxxxx-xxxxx-xxxxx
```