179 lines
4.3 KiB
Markdown
179 lines
4.3 KiB
Markdown
# 腾讯文档同步物流使用说明
|
||
|
||
## 功能概述
|
||
|
||
系统已配置好腾讯文档开放平台的应用信息，实现了自动获取和管理访问令牌的功能。用户只需完成首次授权，后续系统会自动使用有效的访问令牌。
|
||
|
||
## 配置信息
|
||
|
||
应用信息已配置在 `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. 查看后端日志获取详细错误信息
|
||
|