# 顺丰开放平台对接信息

## 配置位置

顺丰相关配置位于 **抖音物流子项目** 中：

```
douyin/DouyinLogistics.API/appsettings.json → "Sf" 节
```

### 配置结构（SfConfig）

| 配置项 | 说明 | 代码属性 | 当前值（占位符） |
|---|---|---|---|
| CustomerCode | 顺丰客户编码（即 partnerID） | `SfConfig.CustomerCode` | `your_customer_code` |
| CheckWord | 顺丰校验码（用于签名） | `SfConfig.CheckWord` | `your_check_word` |
| MonthlyAccount | 顺丰月结账号 | `SfConfig.MonthlyAccount` | `your_monthly_account` |
| ApiBaseUrl | API 基础地址 | `SfConfig.ApiBaseUrl` | `https://sf-api.sf-express.com` |

**注意**：所有本地配置文件中的顺丰凭证均为占位符，实际生产凭证配置在服务器运行环境中（未提交到 Git）。

### appsettings.json 配置示例

```json
{
  "Sf": {
    "CustomerCode": "实际客户编码",
    "CheckWord": "实际校验码",
    "ApiBaseUrl": "https://sf-api.sf-express.com",
    "MonthlyAccount": "实际月结账号"
  }
}
```

## 相关代码文件

| 文件 | 说明 |
|---|---|
| `douyin/DouyinLogistics.API/Models/SfConfig.cs` | 顺丰配置模型类 |
| `douyin/DouyinLogistics.API/Services/SfService.cs` | 顺丰 API 调用服务 |
| `douyin/DouyinLogistics.API/Models/SfWaybillResponse.cs` | 顺丰运单响应模型 |
| `douyin/DouyinLogistics.API/Controllers/OrdersController.cs` | 订单控制器（调用顺丰创建运单） |
| `douyin/DouyinLogistics.API/Services/OrderService.cs` | 订单服务（调用 SfService） |

## 已对接的顺丰 API

### 1. 创建运单（已实现）

- **服务代码**：`EXP_RECE_CREATE_ORDER`
- **API 地址**：`POST {ApiBaseUrl}/sf-express-service/sfexpressService`
- **签名方式**：`SHA256( Base64(msgData) + timestamp + CheckWord )` → Base64
- **请求格式**：

```json
{
  "partnerID": "CustomerCode",
  "requestID": "UUID",
  "serviceCode": "EXP_RECE_CREATE_ORDER",
  "timestamp": "毫秒时间戳",
  "msgData": "Base64编码的请求JSON",
  "msgDigest": "签名"
}
```

- **响应示例**（来自数据库 `api_order_dispath.sfSendBody`）：

```json
{
  "success": true,
  "errorCode": "S0000",
  "msgData": {
    "orderId": "648498145050693",
    "originCode": "025",
    "waybillNoInfoList": [
      { "waybillType": 1, "waybillNo": "SF7444495309022" }
    ],
    "routeLabelInfo": [...]
  }
}
```

### 2. 路由查询（未实现，待对接）

- **服务代码**：`EXP_RECE_SEARCH_ROUTES`
- **用途**：通过快递单号查询物流轨迹
- **需要的信息**：拦截时间、拦截状态、退回单号

### 3. 拦截件查询（未实现，待对接）

- **服务代码**：待确认（可能是 `EXP_RECE_SEARCH_INTERCEPT` 或通过路由查询获取）
- **用途**：查询拦截状态和退回单号

## 数据库相关表

### `api_order_dispath`（ncc_wutong 库）

存储订单发货记录和顺丰 API 响应。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| manOrderId | varchar | 主订单 |
| orderId | varchar | 单个订单 ID |
| addTime | datetime | 发货时间 |
| status | int | 状态 |
| billNo | varchar | 快递单号（如 SF7444495309022） |
| sfSendBody | text | 顺丰下单 API 完整响应 JSON |
| sfMdBody | text | 顺丰面单数据 |
| batchId | varchar | 批量订单 ID |

### `wt_kdljjl`（ncc_wutong 库）

快递拦截记录表（目前数据为空，无 API 自动同步）。

| 字段 | 类型 | 说明 |
|---|---|---|
| F_Id | 主键 | 主键 |
| F_Thd | 退货单 | 退货单号 |
| F_Ddh | 订单号 | 原始订单号 |
| F_Kdgs | 快递公司 | 如"顺丰" |
| F_Ljsj | datetime | 拦截时间 |
| F_Ljzt | 拦截状态 | 拦截状态 |
| F_Ddzt | 订单状态 | 订单状态 |
| F_Bgzt | 包裹状态 | 包裹状态 |
| F_Shzt | 审核状态 | 审核状态 |

**缺少字段**：退回单号（需新增）

## 发货人信息

```json
{
  "Name": "PongGame",
  "Phone": "18014801756",
  "Address": "浦洲路39号沿海创中心A301",
  "Province": "江苏省",
  "City": "南京市",
  "District": "浦口区"
}
```

## 待办事项

- [ ] 获取生产环境的实际 CustomerCode、CheckWord、MonthlyAccount 并补充到本文档
- [ ] 对接顺丰路由查询接口（EXP_RECE_SEARCH_ROUTES），获取物流轨迹
- [ ] 对接顺丰拦截查询，获取拦截时间、拦截状态
- [ ] 在 `wt_kdljjl` 表中新增"退回单号"字段
- [ ] 实现通过快递单号自动查询并填充拦截信息