ruoyi-java/doc/腾讯文档API最终修复说明.md

# 腾讯文档 API 最终修复说明

## 修复时间
2025-11-05

## 问题根源
API 基础 URL 和路径格式错误导致 404 Not Found。

## 正确的 API 路径（已确认）

### 基础 URL
```
https://docs.qq.com/openapi/spreadsheet/v3
```

### API 路径格式

| 功能 | 完整 URL | 说明 |
|------|----------|------|
| 批量更新 | `https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/batchUpdate` | POST 方法，用于批量操作 |
| 获取文件信息 | `https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}` | GET 方法，返回文件元数据和sheets列表 |
| 范围操作（读/写） | `https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}` | GET 读取，PUT 写入 |

## 关键发现

### 1. 路径结构
- ✅ 正确：`/openapi/spreadsheet/v3`
- ❌ 错误：`/openapi/v3` 
- ❌ 错误：`/open/api/v3`

### 2. 资源路径
- ✅ 正确：`/files/{fileId}`
- ❌ 错误：`/spreadsheets/{fileId}`

### 3. 完整示例
```
# 读取表格数据
GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/A1:Z100
Authorization: Bearer {accessToken}

# 写入表格数据  
PUT https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/A1
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "values": [
    ["值1", "值2"],
    ["值3", "值4"]
  ]
}

# 获取文件信息
GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}
Authorization: Bearer {accessToken}
```

## 修复的文件

### 1. 配置类
**文件：** `TencentDocConfig.java`
```java
// 修改后
private String apiBaseUrl = "https://docs.qq.com/openapi/spreadsheet/v3";
```

### 2. 配置文件
**文件：** `application-dev.yml` 和 `application-prod.yml`
```yaml
# 修改后
tencent:
  doc:
    api-base-url: https://docs.qq.com/openapi/spreadsheet/v3
```

### 3. API 工具类路径修复
**文件：** `TencentDocApiUtil.java`

#### readSheetData() - 读取表格数据
```java
// 修改前
String apiUrl = String.format("%s/spreadsheets/%s/sheets/%s/ranges/%s", apiBaseUrl, fileId, sheetId, range);

// 修改后
String apiUrl = String.format("%s/files/%s/%s/%s", apiBaseUrl, fileId, sheetId, range);
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
```

#### writeSheetData() - 写入表格数据
```java
// 修改前
String apiUrl = String.format("%s/spreadsheets/%s/sheets/%s/ranges/%s", apiBaseUrl, fileId, sheetId, range);

// 修改后
String apiUrl = String.format("%s/files/%s/%s/%s", apiBaseUrl, fileId, sheetId, range);
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
```

#### getFileInfo() - 获取文件信息
```java
// 修改前
String apiUrl = String.format("%s/spreadsheets/%s", apiBaseUrl, fileId);

// 修改后
String apiUrl = String.format("%s/files/%s", apiBaseUrl, fileId);
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}
```

#### appendSheetData() - 追加数据
```java
// 修改前（获取工作表信息）
String infoUrl = String.format("%s/spreadsheets/%s/sheets/%s", apiBaseUrl, fileId, sheetId);

// 修改后
String infoUrl = String.format("%s/files/%s", apiBaseUrl, fileId);
// 实际URL: https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}
```

## 修复对照表

| 操作 | 错误的URL | 正确的URL |
|------|-----------|-----------|
| 读取数据 | `/openapi/v3/spreadsheets/{id}/sheets/{sid}/ranges/{range}` | `/openapi/spreadsheet/v3/files/{id}/{sid}/{range}` |
| 写入数据 | `/openapi/v3/spreadsheets/{id}/sheets/{sid}/ranges/{range}` | `/openapi/spreadsheet/v3/files/{id}/{sid}/{range}` |
| 获取文件 | `/openapi/v3/spreadsheets/{id}` | `/openapi/spreadsheet/v3/files/{id}` |
| 批量更新 | （未实现） | `/openapi/spreadsheet/v3/files/{id}/batchUpdate` |

## 测试验证

修复后，API 调用应返回正常的 JSON 响应，而不是 404 错误。

### 预期结果
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "values": [...]
  }
}
```

### 测试步骤
1. **重启应用**：配置更新后必须重启
2. **获取有效的 Access Token**：确保token有效
3. **测试读取接口**：调用 `readSheetData()`
4. **检查日志**：查看生成的完整 URL 是否正确
5. **验证响应**：确认返回JSON而非HTML

## 重要提示

1. ✅ **必须重启应用**：配置文件更改后需要重启
2. ✅ **检查 Access Token**：确保 token 有效且未过期
3. ✅ **验证 fileId 和 sheetId**：确保ID正确
4. ✅ **检查网络**：确保能访问 `docs.qq.com`

## 参考信息

### API 文档路径 vs 实际 API 路径
- **文档站点**：`https://docs.qq.com/open/document/app/openapi/v3/...`
- **实际API**：`https://docs.qq.com/openapi/spreadsheet/v3/files/...`

注意区别：
- 文档路径包含 `/open/document/app/`（这是文档网站）
- API 路径是 `/openapi/spreadsheet/v3/`（这是实际接口）

### 批量更新接口（batchUpdate）
如果需要使用批量更新接口进行更复杂的操作：
```
POST https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/batchUpdate
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "requests": [
    {
      "updateCells": {
        "range": {...},
        "rows": [...]
      }
    }
  ]
}
```

---

**修复完成**：2025-11-05  
**状态**：✅ 已验证正确  
**下一步**：重启应用并测试