CC/ruoyi-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
ruoyi-java/doc/腾讯文档同步物流使用说明.md
荒 cddfde34df 1
2025-11-05 22:47:06 +08:00

4.3 KiB
Raw Permalink Blame History

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

功能概述

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

配置信息

应用信息已配置在 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. 查看后端日志获取详细错误信息