# 腾讯文档在线编辑功能说明

## 功能概述

本功能实现了将物流信息直接上传到腾讯文档表格，实现自动发货的功能。系统通过腾讯文档开放平台的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/)
- 系统日志文件