1

2025-11-06 02:32:27 +08:00
parent 350ecde455
commit ff2002642a
7 changed files with 717 additions and 43 deletions
--- a/doc/腾讯文档API最终修复说明.md
+++ b/doc/腾讯文档API最终修复说明.md
@@ -0,0 +1,191 @@
+# 腾讯文档 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  
+**状态**：✅ 已验证正确  
+**下一步**：重启应用并测试
+
--- a/doc/腾讯文档API鉴权修复指南.md
+++ b/doc/腾讯文档API鉴权修复指南.md
@@ -0,0 +1,240 @@
+# 腾讯文档 API 鉴权修复指南
+
+## 关键发现
+
+根据腾讯文档官方 API 文档，发现了之前鉴权方式的重大错误：
+
+### 正确的鉴权方式
+
+腾讯文档 V3 API 需要**三个请求头**进行鉴权：
+
+```http
+Access-Token: {访问令牌}
+Client-Id: {应用ID}
+Open-Id: {开放平台用户ID}
+```
+
+**而不是**：
+```http
+Authorization: Bearer {访问令牌}  ❌ 错误！
+```
+
+## 推荐方案：使用应用级账号 Token
+
+### 什么是应用级账号 Token？
+
+- 不需要用户授权流程
+- 直接使用 `client_id` 和 `client_secret` 获取
+- 响应包含所有需要的信息
+
+### API 接口
+
+**请求：**
+```http
+GET https://docs.qq.com/oauth/v2/app-account-token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET
+```
+
+**响应：**
+```json
+{
+  "access_token": "ACCESSTOKENEXAMPLE",
+  "token_type": "Bearer",
+  "refresh_token": "REFRESHTOKENEXAMPLE",
+  "expires_in": 259200,
+  "scope": "scope.file.editable,scope.folder.creatable",
+  "user_id": "bcb50c8a4b724d86bbcf6fc64c5e2b22"
+}
+```
+
+### 字段映射
+
+| 响应字段 | 对应请求头 | 说明 |
+|---------|-----------|------|
+| `access_token` | `Access-Token` | 访问令牌 |
+| 请求参数 `client_id` | `Client-Id` | 应用ID |
+| `user_id` | `Open-Id` | 开放平台用户ID（关键！） |
+
+## 完整的 API 调用流程
+
+### 步骤1：获取应用级账号 Token
+
+```java
+JSONObject tokenInfo = TencentDocApiUtil.getAppAccountToken(appId, appSecret);
+
+String accessToken = tokenInfo.getString("access_token");
+String openId = tokenInfo.getString("user_id");  // 这就是 Open-Id！
+String clientId = appId;  // Client-Id 就是 appId
+```
+
+### 步骤2：调用业务 API
+
+```java
+// 设置请求头
+conn.setRequestProperty("Access-Token", accessToken);
+conn.setRequestProperty("Client-Id", clientId);
+conn.setRequestProperty("Open-Id", openId);
+conn.setRequestProperty("Content-Type", "application/json");
+```
+
+### 步骤3：发送请求
+
+```http
+GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/A1:Z100
+Access-Token: ACCESSTOKENEXAMPLE
+Client-Id: YOUR_CLIENT_ID
+Open-Id: bcb50c8a4b724d86bbcf6fc64c5e2b22
+Content-Type: application/json
+```
+
+## 代码修改方案
+
+### 方案 A：简单封装（推荐）
+
+在 Service 层创建一个包装类来管理鉴权信息：
+
+```java
+public class TencentDocAuth {
+    private String accessToken;
+    private String clientId;
+    private String openId;
+    private long expiresAt;
+    
+    // 获取或刷新 Token
+    public static TencentDocAuth getAuth(String appId, String appSecret) {
+        JSONObject tokenInfo = TencentDocApiUtil.getAppAccountToken(appId, appSecret);
+        
+        TencentDocAuth auth = new TencentDocAuth();
+        auth.accessToken = tokenInfo.getString("access_token");
+        auth.openId = tokenInfo.getString("user_id");
+        auth.clientId = appId;
+        auth.expiresAt = System.currentTimeMillis() + tokenInfo.getIntValue("expires_in") * 1000;
+        
+        return auth;
+    }
+    
+    // Getters...
+}
+```
+
+### 方案 B：修改现有方法签名
+
+修改 `callApi` 方法，添加必要的参数：
+
+```java
+public static JSONObject callApi(String accessToken, String clientId, String openId, 
+                                  String apiUrl, String method, String body) {
+    conn.setRequestProperty("Access-Token", accessToken);
+    conn.setRequestProperty("Client-Id", clientId);
+    conn.setRequestProperty("Open-Id", openId);
+    // ...
+}
+```
+
+然后更新所有调用此方法的地方。
+
+## 实现步骤
+
+### 1. 添加获取应用级账号 Token 的方法 ✅
+
+已在 `TencentDocApiUtil.java` 中添加：
+```java
+public static JSONObject getAppAccountToken(String appId, String appSecret)
+```
+
+### 2. 修改 callApi 方法 ✅
+
+已更新为：
+```java
+public static JSONObject callApi(String accessToken, String clientId, String openId, 
+                                  String apiUrl, String method, String body)
+```
+
+### 3. 更新所有调用点（待完成）
+
+需要更新以下方法：
+- `readSheetData()`
+- `writeSheetData()`
+- `appendSheetData()`
+- `getFileInfo()`
+- `getSheetList()`
+
+以及所有调用这些方法的 Service 类。
+
+## 测试验证
+
+### 1. 获取应用级账号 Token
+
+```java
+JSONObject tokenInfo = TencentDocApiUtil.getAppAccountToken(
+    "YOUR_CLIENT_ID",
+    "YOUR_CLIENT_SECRET"
+);
+
+System.out.println("Access Token: " + tokenInfo.getString("access_token"));
+System.out.println("Open-Id: " + tokenInfo.getString("user_id"));
+```
+
+### 2. 调用表格 API
+
+```java
+String accessToken = tokenInfo.getString("access_token");
+String clientId = "YOUR_CLIENT_ID";
+String openId = tokenInfo.getString("user_id");
+
+JSONObject result = TencentDocApiUtil.readSheetData(
+    accessToken, clientId, openId,
+    "YOUR_FILE_ID", "SHEET_ID", "A1:Z10",
+    "https://docs.qq.com/openapi/spreadsheet/v3"
+);
+```
+
+## 注意事项
+
+### 1. Token 有效期
+
+应用级账号 Token 默认有效期为 3 天（259200秒），需要定期刷新。
+
+### 2. 存储安全
+
+- `client_secret` 必须保密
+- Token 应该缓存并在过期前刷新
+- 不要在日志中打印完整的 Token
+
+### 3. 权限范围
+
+应用级账号的权限取决于申请时的 scope：
+- `scope.sheet` - 读取表格
+- `scope.sheet.editable` - 编辑表格
+- `scope.file.editable` - 编辑文件
+- `scope.folder.creatable` - 创建文件夹
+
+## 错误排查
+
+### 401 Unauthorized
+
+- 检查 Access-Token 是否正确
+- 检查 Token 是否过期
+- 检查是否包含所有三个请求头
+
+### 403 Forbidden
+
+- 检查应用是否有相应的权限 (scope)
+- 检查 Open-Id 是否正确
+
+### 404 Not Found
+
+- 检查 URL 路径是否正确
+- 确认基础 URL 为 `https://docs.qq.com/openapi/spreadsheet/v3`
+- 确认路径格式为 `/files/{fileId}/...`
+
+## 参考文档
+
+- [批量更新接口](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchUpdate.html)
+- [获取应用级账号 Token](https://docs.qq.com/open/document/app/oauth2/app-account-token.html)
+- [请求头部说明](https://docs.qq.com/open/document/app/openapi/v3/)
+
+---
+
+**更新时间**：2025-11-05  
+**状态**：部分完成，需要更新所有调用点
+