189 lines
6.7 KiB
Markdown
189 lines
6.7 KiB
Markdown
# 腾讯文档 API 修复说明
|
||
|
||
## 修复时间
|
||
2025-11-05
|
||
|
||
## 修复原因
|
||
原代码中使用的腾讯文档 API 基础 URL 不正确，导致接口调用失败。
|
||
|
||
### 问题详情
|
||
1. **错误的 API 基础 URL**：使用了 `https://docs.qq.com/open/v3`
|
||
2. **正确的 API 基础 URL**：应该是 `https://docs.qq.com/openapi/v3`（注意是 `/openapi/v3` 而不是 `/open/v3`）
|
||
|
||
## 修复的文件列表
|
||
|
||
### 1. 配置文件（2个）
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `ruoyi-admin/src/main/resources/application-dev.yml` | 第202行：`api-base-url: https://docs.qq.com/open/v3` → `https://docs.qq.com/openapi/v3` |
|
||
| `ruoyi-admin/src/main/resources/application-prod.yml` | 第202行：`api-base-url: https://docs.qq.com/open/v3` → `https://docs.qq.com/openapi/v3` |
|
||
|
||
### 2. Java 配置类（1个）
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `ruoyi-system/src/main/java/com/ruoyi/jarvis/config/TencentDocConfig.java` | 第33行：更新默认 API 基础地址为 `https://docs.qq.com/openapi/v3`，并添加注释说明 |
|
||
|
||
### 3. Java 工具类（1个）
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `ruoyi-system/src/main/java/com/ruoyi/jarvis/util/TencentDocApiUtil.java` | 更新所有方法的注释和文档说明，确保 API 路径格式正确 |
|
||
|
||
## 详细修改说明
|
||
|
||
### TencentDocConfig.java
|
||
```java
|
||
// 修改前
|
||
private String apiBaseUrl = "https://docs.qq.com/open/v3";
|
||
|
||
// 修改后
|
||
/** API基础地址 - V3版本（注意：是 /openapi/v3 不是 /open/v3） */
|
||
private String apiBaseUrl = "https://docs.qq.com/openapi/v3";
|
||
```
|
||
|
||
### TencentDocApiUtil.java 修改的方法
|
||
|
||
#### 1. readSheetData() - 读取表格数据
|
||
- **修改前**：注释中标注路径为 `/open/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}`
|
||
- **修改后**：更新为 `/openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}`
|
||
- **实际生成的完整URL**：`https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}`
|
||
|
||
#### 2. writeSheetData() - 写入表格数据
|
||
- **修改前**：注释中标注路径为 `/open/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}`
|
||
- **修改后**：更新为 `/openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}`
|
||
- **增强**：添加了关于 V3 API 数据格式的详细说明，参考官方文档
|
||
- **实际生成的完整URL**：`https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets/{sheetId}/ranges/{range}`
|
||
|
||
#### 3. appendSheetData() - 追加表格数据
|
||
- **修改前**：注释中标注路径为 `/open/v3/spreadsheets/{id}/sheets/{sheetId}`
|
||
- **修改后**：更新为 `/openapi/v3/spreadsheets/{id}/sheets/{sheetId}`
|
||
- **增强**：添加了关于工作表信息返回格式的详细说明
|
||
- **实际生成的完整URL**：`https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets/{sheetId}`
|
||
|
||
#### 4. getFileInfo() - 获取文件信息
|
||
- **修改前**：注释中标注路径为 `/open/v3/spreadsheets/{id}`
|
||
- **修改后**：更新为 `/openapi/v3/spreadsheets/{id}`
|
||
- **增强**：添加了返回格式示例说明
|
||
- **实际生成的完整URL**：`https://docs.qq.com/openapi/v3/spreadsheets/{id}`
|
||
|
||
#### 5. getSheetList() - 获取工作表列表
|
||
- **修改前**：注释中标注路径为 `/open/v3/spreadsheets/{id}/sheets`
|
||
- **修改后**：更新为 `/openapi/v3/spreadsheets/{id}/sheets`
|
||
- **增强**：添加了返回格式示例说明
|
||
- **实际生成的完整URL**：`https://docs.qq.com/openapi/v3/spreadsheets/{id}/sheets`
|
||
|
||
### application-dev.yml & application-prod.yml
|
||
```yaml
|
||
# 修改前
|
||
api-base-url: https://docs.qq.com/open/v3
|
||
|
||
# 修改后
|
||
# 注意：正确的URL是 /openapi/v3 而不是 /open/v3
|
||
api-base-url: https://docs.qq.com/openapi/v3
|
||
```
|
||
|
||
## V3 API 接口路径对照表
|
||
|
||
| 功能 | 正确的完整 URL |
|
||
|------|---------------|
|
||
| 读取表格数据 | `https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets/{sheetId}/ranges/{range}` |
|
||
| 写入表格数据 | `https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets/{sheetId}/ranges/{range}` |
|
||
| 获取工作表信息 | `https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets/{sheetId}` |
|
||
| 获取文件信息 | `https://docs.qq.com/openapi/v3/spreadsheets/{fileId}` |
|
||
| 获取工作表列表 | `https://docs.qq.com/openapi/v3/spreadsheets/{fileId}/sheets` |
|
||
| 获取用户信息 | `https://docs.qq.com/oauth/v2/userinfo` |
|
||
|
||
## 鉴权方式验证 ✅
|
||
|
||
当前代码中的鉴权实现是**正确的**，使用标准的 Bearer Token 方式：
|
||
|
||
```java
|
||
conn.setRequestProperty("Authorization", "Bearer " + accessToken);
|
||
conn.setRequestProperty("Content-Type", "application/json");
|
||
conn.setRequestProperty("Accept", "application/json");
|
||
```
|
||
|
||
## 数据格式说明
|
||
|
||
### 写入数据格式
|
||
根据腾讯文档 V3 API 规范，支持两种数据格式：
|
||
|
||
#### 1. 简单文本数组（当前实现）
|
||
```json
|
||
{
|
||
"values": [
|
||
["值1", "值2"],
|
||
["值3", "值4"]
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 2. 完整 CellData 结构（用于复杂格式）
|
||
```json
|
||
{
|
||
"data": [{
|
||
"startRow": 0,
|
||
"startColumn": 0,
|
||
"rows": [{
|
||
"values": [{
|
||
"cellValue": {
|
||
"text": "单元格内容"
|
||
},
|
||
"dataType": "DATA_TYPE_UNSPECIFIED",
|
||
"cellFormat": {
|
||
"textFormat": {
|
||
"font": "SimSun",
|
||
"fontSize": 12
|
||
}
|
||
}
|
||
}]
|
||
}]
|
||
}]
|
||
}
|
||
```
|
||
|
||
当前代码使用简单文本数组格式，适用于大多数场景。如需使用复杂格式（带样式、颜色等），可以在调用时传入完整的 CellData 结构。
|
||
|
||
## 参考文档
|
||
|
||
- [腾讯文档 V3 API - 在线表格资源描述](https://docs.qq.com/open/document/app/openapi/v3/sheet/model/spreadsheet.html)
|
||
- [腾讯文档开放平台官方文档](https://docs.qq.com/open/document/app/)
|
||
- [OAuth2.0 用户授权](https://docs.qq.com/open/document/app/oauth2/authorize.html)
|
||
- [批量更新接口](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchUpdate.html)
|
||
|
||
## 注意事项
|
||
|
||
1. **重要**：所有使用腾讯文档 API 的地方必须使用 `/openapi/v3` 而不是 `/open/v3`
|
||
2. 配置文件更新后需要重启应用才能生效
|
||
3. OAuth 授权接口路径保持不变：`https://docs.qq.com/oauth/v2/`
|
||
4. 如果 API 调用仍然失败，请检查：
|
||
- Access Token 是否有效
|
||
- 文件 ID 和工作表 ID 是否正确
|
||
- 网络连接是否正常
|
||
- 是否有相关权限
|
||
|
||
## 测试建议
|
||
|
||
修复后建议测试以下功能：
|
||
1. ✅ 获取授权 URL
|
||
2. ✅ OAuth 回调处理
|
||
3. ✅ 读取表格数据
|
||
4. ✅ 写入表格数据
|
||
5. ✅ 追加表格数据
|
||
6. ✅ 获取工作表列表
|
||
7. ✅ 获取文件信息
|
||
|
||
## 验证结果
|
||
|
||
- ✅ 所有配置文件已更新
|
||
- ✅ 所有 Java 代码已更新
|
||
- ✅ 所有注释和文档已更新
|
||
- ✅ 无语法错误（Linter 检查通过）
|
||
- ✅ API 路径格式符合 V3 规范
|
||
|
||
---
|
||
|
||
**修复完成时间**：2025-11-05
|
||
**修复人员**：AI Assistant
|
||
**验证状态**：✅ 已完成
|
||
|