214 lines
5.3 KiB
Markdown
214 lines
5.3 KiB
Markdown
# 腾讯文档在线编辑功能说明
|
||
|
||
## 功能概述
|
||
|
||
本功能实现了将物流信息直接上传到腾讯文档表格，实现自动发货的功能。系统通过腾讯文档开放平台的API，可以将订单的物流信息自动写入到指定的腾讯文档表格中。
|
||
|
||
## 功能特性
|
||
|
||
1. **OAuth2.0授权**：支持腾讯文档的OAuth2.0授权流程
|
||
2. **物流信息上传**：支持批量或单个订单的物流信息上传
|
||
3. **自动发货**：将物流信息上传到腾讯文档后，自动完成发货流程
|
||
4. **表格操作**：支持读取、写入、追加表格数据
|
||
|
||
## 配置说明
|
||
|
||
### 1. 申请腾讯文档开放平台应用
|
||
|
||
1. 访问 [腾讯文档开放平台](https://docs.qq.com/open/document/app/)
|
||
2. 注册开发者账号并创建应用
|
||
3. 获取 `AppID` 和 `AppSecret`
|
||
4. 配置授权回调地址：`http://your-domain/jarvis/tendoc/oauth/callback`
|
||
|
||
### 2. 配置应用参数
|
||
|
||
在 `application-dev.yml` 中配置腾讯文档相关参数：
|
||
|
||
```yaml
|
||
tencent:
|
||
doc:
|
||
app-id: your_app_id # 替换为你的AppID
|
||
app-secret: your_app_secret # 替换为你的AppSecret
|
||
redirect-uri: http://localhost:30313/jarvis/tendoc/oauth/callback # 替换为你的回调地址
|
||
```
|
||
|
||
## API接口说明
|
||
|
||
### 1. 获取授权URL
|
||
|
||
**接口地址：** `GET /jarvis/tendoc/authUrl`
|
||
|
||
**返回示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "获取授权URL成功",
|
||
"data": "https://docs.qq.com/oauth/v2/authorize?client_id=xxx&redirect_uri=xxx&response_type=code&scope=file.read_write"
|
||
}
|
||
```
|
||
|
||
### 2. OAuth回调
|
||
|
||
**接口地址：** `GET /jarvis/tendoc/oauth/callback?code=xxx`
|
||
|
||
**参数说明：**
|
||
- `code`: 授权码（由腾讯文档返回）
|
||
|
||
**返回示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "授权成功",
|
||
"data": {
|
||
"access_token": "xxx",
|
||
"refresh_token": "xxx",
|
||
"expires_in": 7200
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 刷新访问令牌
|
||
|
||
**接口地址：** `POST /jarvis/tendoc/refreshToken`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"refreshToken": "xxx"
|
||
}
|
||
```
|
||
|
||
### 4. 上传物流信息（批量）
|
||
|
||
**接口地址：** `POST /jarvis/tendoc/uploadLogistics`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"accessToken": "xxx",
|
||
"fileId": "xxx",
|
||
"sheetId": "xxx",
|
||
"orderIds": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `accessToken`: 访问令牌
|
||
- `fileId`: 腾讯文档文件ID（从文档URL中获取）
|
||
- `sheetId`: 工作表ID（从文档URL中获取）
|
||
- `orderIds`: 订单ID列表
|
||
|
||
### 5. 追加物流信息（单个）
|
||
|
||
**接口地址：** `POST /jarvis/tendoc/appendLogistics`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"accessToken": "xxx",
|
||
"fileId": "xxx",
|
||
"sheetId": "xxx",
|
||
"orderId": 1
|
||
}
|
||
```
|
||
|
||
### 6. 自动发货
|
||
|
||
**接口地址：** `POST /jarvis/tendoc/autoShip`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"accessToken": "xxx",
|
||
"fileId": "xxx",
|
||
"sheetId": "xxx",
|
||
"orderId": 1
|
||
}
|
||
```
|
||
|
||
**功能说明：**
|
||
- 检查订单是否有物流链接
|
||
- 将物流信息上传到腾讯文档表格
|
||
- 完成自动发货流程
|
||
|
||
### 7. 读取表格数据
|
||
|
||
**接口地址：** `GET /jarvis/tendoc/readSheet`
|
||
|
||
**参数：**
|
||
- `accessToken`: 访问令牌
|
||
- `fileId`: 文件ID
|
||
- `sheetId`: 工作表ID
|
||
- `range`: 范围（可选，默认：A1:Z100）
|
||
|
||
### 8. 获取文件信息
|
||
|
||
**接口地址：** `GET /jarvis/tendoc/fileInfo`
|
||
|
||
**参数：**
|
||
- `accessToken`: 访问令牌
|
||
- `fileId`: 文件ID
|
||
|
||
### 9. 获取工作表列表
|
||
|
||
**接口地址：** `GET /jarvis/tendoc/sheetList`
|
||
|
||
**参数：**
|
||
- `accessToken`: 访问令牌
|
||
- `fileId`: 文件ID
|
||
|
||
## 使用流程
|
||
|
||
### 1. 授权流程
|
||
|
||
1. 调用 `GET /jarvis/tendoc/authUrl` 获取授权URL
|
||
2. 用户在浏览器中访问授权URL，完成授权
|
||
3. 授权成功后，腾讯文档会重定向到回调地址，并携带 `code` 参数
|
||
4. 调用 `GET /jarvis/tendoc/oauth/callback?code=xxx` 获取访问令牌
|
||
|
||
### 2. 上传物流信息
|
||
|
||
1. 获取腾讯文档的文件ID和工作表ID
|
||
- 打开腾讯文档，从URL中获取：`https://docs.qq.com/sheet/Dxxxxxxxxxxxxx?tab=BB08J2`
|
||
- `Dxxxxxxxxxxxxx` 为文件ID
|
||
- `BB08J2` 为工作表ID
|
||
|
||
2. 调用上传接口
|
||
- 批量上传：`POST /jarvis/tendoc/uploadLogistics`
|
||
- 单个追加：`POST /jarvis/tendoc/appendLogistics`
|
||
- 自动发货：`POST /jarvis/tendoc/autoShip`
|
||
|
||
### 3. 表格格式
|
||
|
||
上传的数据格式（按列顺序）：
|
||
1. 内部单号（remark）
|
||
2. 订单号（orderId）
|
||
3. 下单时间（orderTime）
|
||
4. 型号（modelNumber）
|
||
5. 地址（address）
|
||
6. 物流链接（logisticsLink）
|
||
7. 下单人（buyer）
|
||
8. 付款金额（paymentAmount）
|
||
9. 后返金额（rebateAmount）
|
||
10. 备注/状态（status）
|
||
|
||
## 注意事项
|
||
|
||
1. **访问令牌有效期**：访问令牌通常有效期为2小时，过期后需要使用 `refresh_token` 刷新
|
||
2. **API调用频率**：腾讯文档API有调用频率限制，请参考[腾讯文档开放平台文档](https://docs.qq.com/open/document/app/)
|
||
3. **文件权限**：确保应用有权限访问目标文档
|
||
4. **表格格式**：建议在腾讯文档中先创建表头，确保列顺序与系统一致
|
||
|
||
## 错误处理
|
||
|
||
- 如果访问令牌过期，系统会返回错误信息，需要重新授权或刷新令牌
|
||
- 如果文件ID或工作表ID错误，会返回相应的错误提示
|
||
- 如果订单信息不完整（如缺少物流链接），自动发货会失败并提示
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请参考：
|
||
- [腾讯文档开放平台文档](https://docs.qq.com/open/document/app/)
|
||
- 系统日志文件
|
||
|