上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/InterfaceDocument.md
+++ b/InterfaceDocument.md
@@ -0,0 +1,270 @@
+# 标签替换服务接口文档
+
+## 1. 接口概述
+
+本文档描述了标签替换服务提供的RESTful API接口，包括接口地址、请求参数、响应格式和示例等信息。所有接口均遵循RESTful设计原则，使用JSON格式进行数据交换。
+
+## 2. 接口列表
+
+| 接口名称 | 接口地址 | 请求方法 | 功能描述 |
+|----------|----------|----------|----------|
+| 标签替换 | /api/Tag/replace | POST | 替换文本中的标签变量 |
+| 物流消息解析 | /api/Tag/logistics-parse | POST | 解析物流接口消息 |
+| 标签替换请求处理 | /api/Tag/label-replace | POST | 处理标签替换请求 |
+
+## 3. 标签替换接口
+
+### 3.1 接口地址
+```
+POST /api/Tag/replace
+```
+
+### 3.2 请求参数
+
+**请求体 (JSON格式):**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| Id | string | 否 | 请求ID |
+| Text | string | 是 | 包含标签的文本 |
+| Variables | Dictionary<string, string> | 是 | 标签变量键值对 |
+
+**请求示例:**
+```json
+{
+  "Id": "request-123",
+  "Text": "Hello {name}, welcome to {company}!",
+  "Variables": {
+    "name": "张三",
+    "company": "标签替换服务"
+  }
+}
+```
+
+### 3.3 响应参数
+
+**响应体 (JSON格式):**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| status | string | 请求状态，ok表示成功，error表示失败 |
+| timestamp | datetime | 响应时间戳 |
+| input | string | 输入文本 |
+| variables | Dictionary<string, string> | 标签变量 |
+| result | string | 替换后的文本 |
+
+**响应示例 (成功):**
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-01-16T08:30:00Z",
+  "input": "Hello {name}, welcome to {company}!",
+  "variables": {
+    "name": "张三",
+    "company": "标签替换服务"
+  },
+  "result": "Hello 张三, welcome to 标签替换服务!"
+}
+```
+
+**响应示例 (失败):**
+```json
+{
+  "status": "error",
+  "message": "请求处理失败"
+}
+```
+
+## 4. 物流消息解析接口
+
+### 4.1 接口地址
+```
+POST /api/Tag/logistics-parse
+```
+
+### 4.2 请求参数
+
+**请求体 (JSON格式):**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| Id | string | 否 | 请求ID |
+| RequestType | string | 是 | 请求类型 |
+| LogisticsInterface | string | 是 | 物流接口消息内容 |
+
+**请求示例:**
+```json
+{
+  "Id": "logistics-123",
+  "RequestType": "order",
+  "LogisticsInterface": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<orderInfo>\n  <orderNo>ORD-20260116-001</orderNo>\n  <consignee>李四</consignee>\n  <phone>13800138000</phone>\n  <address>北京市朝阳区</address>\n</orderInfo>"
+}
+```
+
+### 4.3 响应参数
+
+**响应体 (JSON格式):**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| status | string | 请求状态，ok表示成功，error表示失败 |
+| timestamp | datetime | 响应时间戳 |
+| requestId | string | 请求ID |
+| requestType | string | 请求类型 |
+| parsedData | Dictionary<string, string> | 解析后的物流数据 |
+
+**响应示例 (成功):**
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-01-16T08:45:00Z",
+  "requestId": "logistics-123",
+  "requestType": "order",
+  "parsedData": {
+    "orderNo": "ORD-20260116-001",
+    "consignee": "李四",
+    "phone": "13800138000",
+    "address": "北京市朝阳区"
+  }
+}
+```
+
+**响应示例 (失败):**
+```json
+{
+  "status": "error",
+  "message": "物流接口消息不能为空"
+}
+```
+
+## 5. 标签替换请求处理接口
+
+### 5.1 接口地址
+```
+POST /api/Tag/label-replace
+```
+
+### 5.2 请求头
+
+| 头名称 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| customer_code | string | 是 | 客户代码 |
+| api_key | string | 是 | API密钥 |
+
+### 5.3 请求参数
+
+**请求体 (JSON格式):**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| BillOfLadingNumber | string | 否 | 提单号 |
+| MasterPackageNumber | string | 否 | 大包号 |
+| ReferenceNumber | string | 否 | 参考号（一般表示订单号） |
+| NeutralWaybillNumber | string | 是 | 中性面单单号 |
+| FinalMileTrackingNumber | string | 否 | 尾程跟踪单号 |
+| Label | string | 否 | 标签内容（一般为PDF，可能是base64或其他格式） |
+| ReplaceStatus | string | 否 | 换单状态（Y表示正常换单，N表示冻结换单） |
+
+**请求示例:**
+```json
+{
+  "BillOfLadingNumber": "BL-2026-001",
+  "MasterPackageNumber": "MP-2026-001",
+  "ReferenceNumber": "REF-2026-001",
+  "NeutralWaybillNumber": "NW-20260116-0001",
+  "FinalMileTrackingNumber": "FM-20260116-0001",
+  "Label": "base64 encoded PDF content...",
+  "ReplaceStatus": "Y"
+}
+```
+
+### 5.4 响应参数
+
+**响应体 (JSON格式):**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| Status | string | 请求状态，ok表示成功，error表示失败 |
+| Timestamp | datetime | 响应时间戳 |
+| Id | int | 记录ID |
+| NeutralWaybillNumber | string | 中性面单单号 |
+| ReplaceStatus | string | 换单状态 |
+| LabelReplaced | bool | 是否成功换单 |
+| Message | string | 操作消息 |
+| ErrorDetails | string | 错误详情（仅状态为error时有效） |
+
+**响应示例 (成功):**
+```json
+{
+  "Status": "ok",
+  "Timestamp": "2026-01-16T09:00:00Z",
+  "Id": 1001,
+  "NeutralWaybillNumber": "NW-20260116-0001",
+  "ReplaceStatus": "Y",
+  "LabelReplaced": true,
+  "Message": "标签替换成功"
+}
+```
+
+**响应示例 (失败):**
+```json
+{
+  "Status": "error",
+  "Timestamp": "2026-01-16T09:00:00Z",
+  "NeutralWaybillNumber": "NW-20260116-0001",
+  "ReplaceStatus": null,
+  "LabelReplaced": false,
+  "Message": "Invalid API credentials",
+  "ErrorDetails": "API密钥验证失败"
+}
+```
+
+## 6. 错误码说明
+
+| 错误码 | HTTP状态码 | 错误信息 | 说明 |
+|--------|------------|----------|------|
+| 400 | 400 | Bad Request | 请求参数错误或格式不正确 |
+| 401 | 401 | Unauthorized | API密钥验证失败 |
+| 500 | 500 | Internal Server Error | 服务器内部错误 |
+
+## 7. 调用示例
+
+### 7.1 使用cURL调用标签替换接口
+
+```bash
+curl -X POST -H "Content-Type: application/json" -d '{"Text": "Hello {name}!", "Variables": {"name": "张三"}}' http://localhost:5000/api/Tag/replace
+```
+
+### 7.2 使用Python调用标签替换请求处理接口
+
+```python
+import requests
+import json
+
+url = "http://localhost:5000/api/Tag/label-replace"
+headers = {
+    "Content-Type": "application/json",
+    "customer_code": "customer-001",
+    "api_key": "your-api-key"
+}
+
+payload = {
+    "NeutralWaybillNumber": "NW-20260116-0001",
+    "Label": "base64 encoded PDF content..."
+}
+
+response = requests.post(url, headers=headers, data=json.dumps(payload))
+print(response.json())
+```
+
+## 8. 接口调用限制
+
+- 每个API密钥的调用频率限制为1000次/分钟
+- 每个请求的最大大小限制为10MB
+- 对于大量数据的处理，建议使用批量接口（如果提供）
+
+## 9. 文档版本控制
+
+| 版本 | 更新日期 | 更新内容 | 更新人 |
+|------|----------|----------|--------|
+| 1.0 | 2026-01-16 | 初始版本 | API文档团队 |