抖音物流对接 - 易打单系统

项目说明

实现抖音电商平台的易打单功能，对接顺丰物流，实现订单自动获取、运单自动创建、打印预览等功能。

技术栈

• 后端：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）

{
  "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. 后端启动

cd DouyinLogistics.API
dotnet restore
dotnet run

后端默认运行在：https://localhost:5001 或 http://localhost:5000

3. 前端启动

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

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