99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# 后端 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
|
||
``` |