Antis.Erp.Plat/douyin/README.md

# 抖音物流对接 - 易打单系统
## 项目说明
实现抖音电商平台的易打单功能，对接顺丰物流，实现订单自动获取、运单自动创建、打印预览等功能。
## 技术栈
- **后端**：ASP.NET Core 8.0 + SQLSugar
- **前端**：Vue 3 + Element Plus + TypeScript
- **数据库**：SQL Server / MySQL（可配置）
## 功能模块
### 已实现功能
1. ✅ **抖音开放平台对接**
  - 订单获取（待发货订单）
  - 运单号上传回传
  - OAuth2.0 授权流程
2. ✅ **顺丰物流对接**
  - 运单创建
  - 运单号自动获取
3. ✅ **订单管理**
  - 订单列表查询（支持分页、状态筛选）
  - 订单详情查看
  - 订单实时同步（30秒间隔）
4. ✅ **运单管理**
  - 自动创建运单（订单同步时自动创建）
  - 手动创建运单
  - 运单号自动回传到抖音
5. ✅ **打印预览**
  - 运单打印预览页面
  - 支持浏览器打印
## 项目结构
```
├── DouyinLogistics.API/          # 后端 ASP.NET Core 项目
│   ├── Controllers/              # API 控制器
│   │   ├── AuthController.cs     # 授权相关
│   │   ├── OrdersController.cs   # 订单管理
│   │   └── WaybillController.cs  # 运单预览
│   ├── Services/                 # 业务服务
│   │   ├── DouyinService.cs      # 抖音 API 服务
│   │   ├── SfService.cs          # 顺丰 API 服务
│   │   ├── OrderService.cs       # 订单业务服务
│   │   └── OrderSyncService.cs   # 订单同步后台服务
│   ├── Models/                   # 数据模型
│   └── appsettings.json          # 配置文件
├── frontend/                     # 前端 Vue 项目
│   ├── src/
│   │   ├── views/
│   │   │   └── OrderListView.vue # 订单列表页面
│   │   ├── api/                  # API 接口
│   │   └── router/               # 路由配置
└── README.md
```
## 配置说明
### 后端配置（appsettings.json）
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=DouyinLogistics;User Id=sa;Password=your_password;TrustServerCertificate=True;"
  },
  "Douyin": {
    "AppKey": "7463313337959335475",
    "AppSecret": "648ddb67-b3ba-48a3-905c-ea761e69a87e",
    "CallbackUrl": "https://your-domain.com/api/auth/callback",
    "ApiBaseUrl": "https://openapi-fxg.jinritemai.com"
  },
  "Sf": {
    "CustomerCode": "your_customer_code",      // 顺丰客户编码
    "CheckWord": "your_check_word",             // 顺丰校验码
    "ApiBaseUrl": "https://sf-api.sf-express.com",
    "MonthlyAccount": "your_monthly_account"    // 顺丰月结账号
  },
  "Sender": {
    "Name": "发货人",
    "Phone": "13800138000",
    "Address": "发货地址",
    "Province": "广东省",
    "City": "深圳市",
    "District": "南山区"
  }
}
```
### 需要配置的信息
1. **数据库连接字符串**：根据实际数据库修改
2. **顺丰配置**：
  - `CustomerCode`：顺丰客户编码
  - `CheckWord`：顺丰校验码
  - `MonthlyAccount`：顺丰月结账号
3. **发货人信息**：根据实际情况修改
4. **抖音回调地址**：需要配置为实际部署地址
## 使用步骤
### 1. 数据库准备
- 创建数据库（SQL Server 或 MySQL）
- 修改 `appsettings.json` 中的连接字符串
- 运行项目时会自动创建表结构
### 2. 后端启动
```bash
cd DouyinLogistics.API
dotnet restore
dotnet run
```
后端默认运行在：`https://localhost:5001` 或 `http://localhost:5000`
### 3. 前端启动
```bash
cd frontend
npm install
npm run dev
```
前端默认运行在：`http://localhost:5173`
### 4. 授权配置
#### 方式一：通过授权 URL（推荐）
1. 访问 `/api/auth/authorize` 获取授权 URL
2. 在浏览器中打开授权 URL
3. 完成授权后，系统会自动获取 access_token
#### 方式二：手动设置 Access Token（测试用）
1. 通过抖音开放平台获取 access_token
2. 调用 `/api/auth/set-token` 接口设置 token
```bash
POST /api/auth/set-token
Content-Type: application/json
{
  "accessToken": "your_access_token"
}
```
### 5. 订单同步
系统会自动每 30 秒同步一次订单，也可以手动触发：
- 前端：点击"同步订单"按钮
- API：`POST /api/orders/sync`
### 6. 运单创建
- **自动创建**：订单同步时，如果订单没有运单号，会自动创建
- **手动创建**：在订单列表中点击"创建运单"按钮
### 7. 打印预览
在订单列表中，对于已有运单号的订单，点击"打印预览"按钮，会在新窗口打开打印预览页面。
## API 接口说明
### 订单相关
- `GET /api/orders` - 获取订单列表（支持分页和状态筛选）
- `GET /api/orders/{id}` - 获取订单详情
- `POST /api/orders/sync` - 手动同步订单
- `POST /api/orders/{id}/waybill` - 为订单创建运单
- `GET /api/orders/{id}/waybill-preview` - 获取运单预览数据
### 授权相关
- `GET /api/auth/authorize` - 获取授权 URL
- `GET /api/auth/callback` - 授权回调（由抖音平台调用）
- `POST /api/auth/set-token` - 手动设置 Access Token
### 打印预览
- `GET /api/waybill/{orderId}/preview` - 获取打印预览 HTML
## 工作流程
1. **订单获取**：系统每 30 秒自动从抖音获取待发货订单
2. **订单保存**：将订单保存到本地数据库
3. **运单创建**：自动调用顺丰 API 创建运单
4. **运单号获取**：从顺丰 API 响应中获取运单号
5. **运单号回传**：将运单号上传到抖音平台
6. **打印预览**：用户可以在前端查看和打印运单
## 注意事项
1. **Access Token 管理**：
  - 当前实现中，Access Token 存储在内存中，服务重启后会丢失
  - 生产环境建议将 Access Token 存储到数据库或 Redis 中
  - Access Token 有过期时间，需要实现自动刷新机制
2. **顺丰 API 对接**：
  - 需要先向顺丰申请 API 接入权限
  - 获取 CustomerCode、CheckWord 等配置信息
  - 根据实际 API 文档调整接口调用方式
3. **抖音 API 对接**：
  - 确保 AppKey 和 AppSecret 配置正确
  - 回调地址需要在抖音开放平台配置
  - 注意 API 调用频率限制
4. **数据库**：
  - 首次运行会自动创建表结构
  - 建议定期备份数据库
5. **实时同步**：
  - 当前设置为 30 秒同步一次，可根据实际需求调整
  - 修改 `OrderSyncService.cs` 中的 `_syncInterval` 值
## 开发建议
1. **日志记录**：建议添加更详细的日志记录，方便排查问题
2. **异常处理**：完善异常处理机制，提高系统稳定性
3. **配置管理**：敏感信息建议使用环境变量或密钥管理服务
4. **单元测试**：添加单元测试，确保代码质量
5. **API 文档**：使用 Swagger 生成 API 文档（已集成）
## 问题排查
1. **订单同步失败**：
  - 检查 Access Token 是否有效
  - 检查抖音 API 配置是否正确
  - 查看后端日志
2. **运单创建失败**：
  - 检查顺丰 API 配置是否正确
  - 检查发货人信息是否完整
  - 查看顺丰 API 返回的错误信息
3. **前端无法访问后端**：
  - 检查后端是否正常运行
  - 检查 CORS 配置
  - 检查 API 地址配置
## 后续优化
- Access Token 持久化存储
- Access Token 自动刷新
- 支持更多物流公司
- 批量打印功能
- 订单统计报表
- 异常订单处理
- 消息通知功能
## 许可证
MIT License