1

2025-11-05 22:47:06 +08:00
parent 2335361160
commit cddfde34df
6 changed files with 465 additions and 9 deletions
--- a/doc/腾讯文档同步物流使用说明.md
+++ b/doc/腾讯文档同步物流使用说明.md
@@ -0,0 +1,178 @@
+# 腾讯文档同步物流使用说明
+
+## 功能概述
+
+系统已配置好腾讯文档开放平台的应用信息，实现了自动获取和管理访问令牌的功能。用户只需完成首次授权，后续系统会自动使用有效的访问令牌。
+
+## 配置信息
+
+应用信息已配置在 `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
+```
+
+返回示例：
+```json
+{
+  "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，可以调用：
+```java
+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**
+- **参数**: 
+  ```json
+  {
+    "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. 查看后端日志获取详细错误信息
+