ruoyi-java/doc/腾讯文档同步物流使用说明.md

腾讯文档同步物流使用说明

功能概述

系统已配置好腾讯文档开放平台的应用信息，实现了自动获取和管理访问令牌的功能。用户只需完成首次授权，后续系统会自动使用有效的访问令牌。

配置信息

应用信息已配置在 application-dev.yml 中：

• 应用ID: 90aa0b70e7704c2abd2a42695d5144a4
• 应用密钥: G8ZdSWcoViIawygo7JSolE86PL32UO0O

首次授权流程

1. 获取授权URL

访问接口获取授权URL：

GET /jarvis/tendoc/authUrl

或者直接在浏览器访问：

https://docs.qq.com/oauth/v2/authorize?client_id=90aa0b70e7704c2abd2a42695d5144a4&redirect_uri=YOUR_CALLBACK_URL&response_type=code&scope=all&state=RANDOM_STATE

2. 完成授权

1. 在授权页面完成授权
2. 授权成功后，腾讯文档会重定向到回调地址
3. 系统会自动保存访问令牌到Redis，无需手动操作

3. 验证授权

访问接口检查token状态：

GET /jarvis/tendoc/tokenStatus

返回示例：

{
  "code": 200,
  "msg": "访问令牌有效",
  "data": {
    "hasToken": true,
    "token": "90aa0b70e7704c2abd2..."
  }
}

使用流程

1. 在订单列表页面

1. 找到有物流链接的订单
2. 点击"同步物流"按钮
3. 填写文件ID和工作表ID

2. 获取文件ID和工作表ID

从腾讯文档URL中获取：

https://docs.qq.com/sheet/Dxxxxxxxxxxxxx?tab=BB08J2

• Dxxxxxxxxxxxxx 是文件ID
• BB08J2 是工作表ID

3. 开始同步

1. 系统会自动检查后端是否有有效的访问令牌
2. 如果有，直接开始同步
3. 如果没有，会提示需要先完成授权

Token管理

自动刷新

• 系统会自动检查token是否即将过期（提前5分钟）
• 如果即将过期，会自动使用refresh_token刷新
• 刷新后的新token会自动保存

手动设置Token（可选）

如果通过其他方式获取了token，可以手动设置：

POST /jarvis/tendoc/setToken
{
  "accessToken": "xxx",
  "refreshToken": "xxx",
  "expiresIn": 7200
}

清除Token

如需清除token，可以调用：

tencentDocTokenService.clearToken()

API接口说明

1. 获取授权URL

• 接口: GET /jarvis/tendoc/authUrl
• 说明: 用于首次授权，获取授权URL

2. OAuth回调

• 接口: GET /jarvis/tendoc/oauth/callback?code=xxx&state=xxx
• 说明: 腾讯文档授权回调，会自动保存token到后端

3. 检查Token状态

• 接口: GET /jarvis/tendoc/tokenStatus
• 说明: 检查当前token是否有效

4. 手动设置Token

• 接口: POST /jarvis/tendoc/setToken
• 说明: 手动设置token（可选）

5. 同步物流链接

• 接口: POST /jarvis/tendoc/fillLogisticsByOrderNo
• 说明: 根据单号填充物流链接，自动使用后端保存的token
• 参数:

  {
    "fileId": "文件ID",
    "sheetId": "工作表ID",
    "headerRow": 1,
    "orderNoColumn": null,
    "logisticsLinkColumn": null
  }
  

注意事项

1. 回调地址配置：

   • 必须在腾讯文档开放平台配置回调地址
   • 回调地址必须是HTTPS（生产环境）
   • 回调地址：https://your-domain.com/jarvis/tendoc/oauth/callback

2. Token有效期：

   • Access Token有效期：2小时
   • Refresh Token有效期：30天
   • 系统会自动刷新，无需手动操作

3. Redis存储：

   • Token存储在Redis中，key格式：tendoc:token:{appId}
   • Refresh Token key格式：tendoc:refresh_token:{appId}
   • 过期时间key格式：tendoc:token_expire:{appId}

4. 同步逻辑：

   • 系统会自动从上次处理的最大行数-100开始读取
   • 避免重复处理历史数据
   • 自动识别列位置（单号列和物流链接列）

故障排查

Token无效

如果提示"访问令牌无效"：

1. 检查是否完成首次授权
2. 检查Redis中是否有token
3. 尝试重新授权

授权失败

如果授权失败：

1. 检查回调地址是否正确配置
2. 检查回调地址是否在腾讯文档开放平台的白名单中
3. 检查应用ID和应用密钥是否正确

同步失败

如果同步失败：

1. 检查文件ID和工作表ID是否正确
2. 检查表格是否有权限访问
3. 查看后端日志获取详细错误信息