# 腾讯文档 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  
**状态**：待测试验证

