1

2025-11-06 02:22:14 +08:00
parent a3aa8c74e6
commit 350ecde455
5 changed files with 138 additions and 16 deletions
--- a/doc/腾讯文档API_404问题诊断.md
+++ b/doc/腾讯文档API_404问题诊断.md
@@ -0,0 +1,122 @@
+# 腾讯文档 API 404 问题诊断与修复
+
+## 问题现象
+调用腾讯文档 API 时返回 404 Not Found 错误：
+```
+Caused by: java.lang.RuntimeException: 请求被代理拦截，返回了HTML页面。请检查系统代理设置或网络配置。响应: <html><head><title>404 Not Found</title></head><body><center><h1>404 Not Found</h1></center><hr><center>nginx</center></body></html>
+```
+
+## 可能的原因分析
+
+### 1. API 基础 URL 可能不正确
+
+我们当前使用的基础 URL 是：`https://docs.qq.com/openapi/v3`
+
+但根据腾讯文档API的文档路径结构，可能的正确基础 URL 有以下几种：
+
+| 候选URL | 说明 |
+|---------|------|
+| `https://docs.qq.com/open/api/v3` | 推测1：/open/api/v3 |
+| `https://docs.qq.com/openapi/v3` | 推测2：/openapi/v3（当前使用）|
+| `https://docs.qq.com/v3` | 推测3：直接 /v3 |
+| `https://api.docs.qq.com/v3` | 推测4：使用 api 子域名 |
+
+### 2. 可能需要使用不同的接口路径
+
+腾讯文档 V3 API 可能不支持直接的 REST 风格的 ranges 路径，而是使用：
+- **批量更新接口（batchUpdate）**：用于写入数据
+- **批量查询接口（getGridData 或类似）**：用于读取数据
+
+## 诊断步骤
+
+### 步骤1：测试不同的基础 URL
+
+建议创建一个测试方法，尝试不同的基础URL：
+
+```java
+// 测试代码示例
+public void testApiBaseUrls() {
+    String[] candidateUrls = {
+        "https://docs.qq.com/open/api/v3",
+        "https://docs.qq.com/openapi/v3",
+        "https://docs.qq.com/v3",
+        "https://api.docs.qq.com/v3"
+    };
+    
+    for (String baseUrl : candidateUrls) {
+        try {
+            String testUrl = baseUrl + "/spreadsheets/{fileId}";
+            log.info("测试URL: {}", testUrl);
+            // 发送GET请求测试
+            JSONObject result = callApi(accessToken, testUrl, "GET", null);
+            log.info("成功！正确的基础URL是: {}", baseUrl);
+            return;
+        } catch (Exception e) {
+            log.warn("URL {} 失败: {}", baseUrl, e.getMessage());
+        }
+    }
+}
+```
+
+### 步骤2：检查腾讯文档开放平台的实际API文档
+
+访问以下链接查看实际的API调用示例：
+1. 腾讯文档开放平台首页：https://docs.qq.com/open/
+2. 开发文档总览：https://docs.qq.com/open/document/app/
+3. 查找实际的API调用示例（cURL命令或SDK示例）
+
+### 步骤3：检查是否需要使用 batchUpdate 接口
+
+如果直接的 ranges 路径不可用，可能需要使用批量操作接口：
+
+**读取数据**可能需要使用类似的接口：
+- POST `/open/api/v3/spreadsheets/{fileId}:getGridData`
+- 或 POST `/open/api/v3/spreadsheets/{fileId}/values:batchGet`
+
+**写入数据**可能需要使用：
+- POST `/open/api/v3/spreadsheets/{fileId}:batchUpdate`
+- 或 POST `/open/api/v3/spreadsheets/{fileId}/values:batchUpdate`
+
+## 临时解决方案
+
+### 方案1：修改基础URL为 /open/api/v3
+
+尝试修改配置：
+
+```yaml
+# application-dev.yml 和 application-prod.yml
+tencent:
+  doc:
+    api-base-url: https://docs.qq.com/open/api/v3
+```
+
+```java
+// TencentDocConfig.java
+private String apiBaseUrl = "https://docs.qq.com/open/api/v3";
+```
+
+### 方案2：联系腾讯文档技术支持
+
+由于官方文档可能没有详细的API调用示例，建议：
+1. 在腾讯文档开放平台提交工单
+2. 咨询实际的API基础URL和调用方式
+3. 获取完整的API调用示例代码
+
+## 后续行动
+
+1. 首先尝试修改基础URL为 `/open/api/v3`
+2. 如果仍然404，需要查看腾讯文档开放平台控制台的SDK示例或API文档
+3. 考虑使用腾讯文档提供的官方SDK（如果有）
+4. 联系腾讯文档技术支持获取准确的API地址
+
+## 参考信息
+
+- 文档页面路径：`/open/document/app/openapi/v3/...`（这是文档站点）
+- 可能的API路径：`/open/api/v3/...`（这可能是实际API）
+- 当前使用路径：`/openapi/v3/...`（返回404）
+
+---
+
+**更新时间**：2025-11-05  
+**状态**：待测试验证
+