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

## 功能概述

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

## 配置信息

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