# 腾讯文档 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  
**验证状态**：✅ 已完成