ruoyi-java/doc/腾讯文档在线编辑功能说明.md

腾讯文档在线编辑功能说明

功能概述

本功能实现了将物流信息直接上传到腾讯文档表格，实现自动发货的功能。系统通过腾讯文档开放平台的API，可以将订单的物流信息自动写入到指定的腾讯文档表格中。

功能特性

1. OAuth2.0授权：支持腾讯文档的OAuth2.0授权流程
2. 物流信息上传：支持批量或单个订单的物流信息上传
3. 自动发货：将物流信息上传到腾讯文档后，自动完成发货流程
4. 表格操作：支持读取、写入、追加表格数据

配置说明

1. 申请腾讯文档开放平台应用

1. 访问 腾讯文档开放平台
2. 注册开发者账号并创建应用
3. 获取 AppID 和 AppSecret
4. 配置授权回调地址：http://your-domain/jarvis/tendoc/oauth/callback

2. 配置应用参数

在 application-dev.yml 中配置腾讯文档相关参数：

tencent:
  doc:
    app-id: your_app_id          # 替换为你的AppID
    app-secret: your_app_secret   # 替换为你的AppSecret
    redirect-uri: http://localhost:30313/jarvis/tendoc/oauth/callback  # 替换为你的回调地址

API接口说明

1. 获取授权URL

接口地址： GET /jarvis/tendoc/authUrl

返回示例：

{
  "code": 200,
  "msg": "获取授权URL成功",
  "data": "https://docs.qq.com/oauth/v2/authorize?client_id=xxx&redirect_uri=xxx&response_type=code&scope=file.read_write"
}

2. OAuth回调

接口地址： GET /jarvis/tendoc/oauth/callback?code=xxx

参数说明：

• code: 授权码（由腾讯文档返回）

返回示例：

{
  "code": 200,
  "msg": "授权成功",
  "data": {
    "access_token": "xxx",
    "refresh_token": "xxx",
    "expires_in": 7200
  }
}

3. 刷新访问令牌

接口地址： POST /jarvis/tendoc/refreshToken

请求体：

{
  "refreshToken": "xxx"
}

4. 上传物流信息（批量）

接口地址： POST /jarvis/tendoc/uploadLogistics

请求体：

{
  "accessToken": "xxx",
  "fileId": "xxx",
  "sheetId": "xxx",
  "orderIds": [1, 2, 3]
}

参数说明：

• accessToken: 访问令牌
• fileId: 腾讯文档文件ID（从文档URL中获取）
• sheetId: 工作表ID（从文档URL中获取）
• orderIds: 订单ID列表

5. 追加物流信息（单个）

接口地址： POST /jarvis/tendoc/appendLogistics

请求体：

{
  "accessToken": "xxx",
  "fileId": "xxx",
  "sheetId": "xxx",
  "orderId": 1
}

6. 自动发货

接口地址： POST /jarvis/tendoc/autoShip

请求体：

{
  "accessToken": "xxx",
  "fileId": "xxx",
  "sheetId": "xxx",
  "orderId": 1
}

功能说明：

• 检查订单是否有物流链接
• 将物流信息上传到腾讯文档表格
• 完成自动发货流程

7. 读取表格数据

接口地址： GET /jarvis/tendoc/readSheet

参数：

• accessToken: 访问令牌
• fileId: 文件ID
• sheetId: 工作表ID
• range: 范围（可选，默认：A1:Z100）

8. 获取文件信息

接口地址： GET /jarvis/tendoc/fileInfo

参数：

• accessToken: 访问令牌
• fileId: 文件ID

9. 获取工作表列表

接口地址： GET /jarvis/tendoc/sheetList

参数：

• accessToken: 访问令牌
• fileId: 文件ID

使用流程

1. 授权流程

1. 调用 GET /jarvis/tendoc/authUrl 获取授权URL
2. 用户在浏览器中访问授权URL，完成授权
3. 授权成功后，腾讯文档会重定向到回调地址，并携带 code 参数
4. 调用 GET /jarvis/tendoc/oauth/callback?code=xxx 获取访问令牌

2. 上传物流信息

1. 获取腾讯文档的文件ID和工作表ID

   • 打开腾讯文档，从URL中获取：https://docs.qq.com/sheet/Dxxxxxxxxxxxxx?tab=BB08J2
   • Dxxxxxxxxxxxxx 为文件ID
   • BB08J2 为工作表ID

2. 调用上传接口

   • 批量上传：POST /jarvis/tendoc/uploadLogistics
   • 单个追加：POST /jarvis/tendoc/appendLogistics
   • 自动发货：POST /jarvis/tendoc/autoShip

3. 表格格式

上传的数据格式（按列顺序）：

1. 内部单号（remark）
2. 订单号（orderId）
3. 下单时间（orderTime）
4. 型号（modelNumber）
5. 地址（address）
6. 物流链接（logisticsLink）
7. 下单人（buyer）
8. 付款金额（paymentAmount）
9. 后返金额（rebateAmount）
10. 备注/状态（status）

注意事项

1. 访问令牌有效期：访问令牌通常有效期为2小时，过期后需要使用 refresh_token 刷新
2. API调用频率：腾讯文档API有调用频率限制，请参考腾讯文档开放平台文档
3. 文件权限：确保应用有权限访问目标文档
4. 表格格式：建议在腾讯文档中先创建表头，确保列顺序与系统一致

错误处理

• 如果访问令牌过期，系统会返回错误信息，需要重新授权或刷新令牌
• 如果文件ID或工作表ID错误，会返回相应的错误提示
• 如果订单信息不完整（如缺少物流链接），自动发货会失败并提示

技术支持

如有问题，请参考：

• 腾讯文档开放平台文档
• 系统日志文件