# 写入 API 字段名错误修复

## 🔴 问题现象

API 返回错误：
```json
{
  "code": 400001,
  "message": "request name error",
  "details": {
    "DebugInfo": {
      "traceId": "ae0bfc4bfa674e258557e70b4f430a4c"
    }
  },
  "internalCode": 0
}
```

**错误信息**：`request name error` - 请求名称错误

---

## 🔍 根本原因

根据[腾讯文档官方 batchUpdate 文档](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/update.html)，所有请求类型名称**必须以 `Request` 结尾**。

### 错误的请求体

```json
{
  "requests": [
    {
      "updateCells": {  // ❌ 错误：缺少 "Request" 后缀
        "range": {...},
        "rows": [...]
      }
    }
  ]
}
```

### 正确的请求体

```json
{
  "requests": [
    {
      "updateCellsRequest": {  // ✅ 正确：必须是 "updateCellsRequest"
        "range": {...},
        "rows": [...]
      }
    }
  ]
}
```

---

## 📚 官方文档示例

根据官方文档，所有请求类型都遵循 `xxxRequest` 的命名规范：

### 示例 1：添加工作表

```json
{
  "requests": [
    {
      "addSheetRequest": {  // ✅ addSheetRequest
        "title": "测试添加子表",
        "rowCount": 10,
        "columnCount": 10
      }
    }
  ]
}
```

### 示例 2：删除维度

```json
{
  "requests": [
    {
      "deleteDimensionRequest": {  // ✅ deleteDimensionRequest
        "sheetId": "BB08J2",
        "dimension": "COLUMN",
        "startIndex": 1,
        "endIndex": 3
      }
    }
  ]
}
```

### 示例 3：更新单元格（我们的场景）

```json
{
  "requests": [
    {
      "updateCellsRequest": {  // ✅ updateCellsRequest
        "range": {
          "sheetId": "BB08J2",
          "startRowIndex": 2,
          "endRowIndex": 3,
          "startColumnIndex": 12,
          "endColumnIndex": 13
        },
        "rows": [
          {
            "values": [
              {
                "cellValue": {
                  "text": "https://3.cn/2ume-Ak1"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
```

---

## ✅ 修复代码

### 修改前

```java
// ❌ 错误
JSONObject request = new JSONObject();
request.put("updateCells", updateCells);  // 缺少 "Request" 后缀
requests.add(request);
```

### 修改后

```java
// ✅ 正确
JSONObject request = new JSONObject();
request.put("updateCellsRequest", updateCells);  // 必须是 "updateCellsRequest"
requests.add(request);
```

---

## 📊 请求类型命名规范

根据官方文档，常见的请求类型包括：

| 请求类型 | 正确名称 | 说明 |
|---------|---------|------|
| 添加工作表 | `addSheetRequest` | ✅ 以 Request 结尾 |
| 删除工作表 | `deleteSheetRequest` | ✅ 以 Request 结尾 |
| 更新单元格 | `updateCellsRequest` | ✅ 以 Request 结尾 |
| 删除维度 | `deleteDimensionRequest` | ✅ 以 Request 结尾 |
| 插入维度 | `insertDimensionRequest` | ✅ 以 Request 结尾 |
| 合并单元格 | `mergeCellsRequest` | ✅ 以 Request 结尾 |

**规律**：所有请求类型名称 = `{操作名称}Request`

---

## 🧪 验证结果

### 修复前（错误）

```
请求体: {"requests":[{"updateCells":{...}}]}
响应: {"code":400001, "message":"request name error"}
```

### 修复后（正确）

```
请求体: {"requests":[{"updateCellsRequest":{...}}]}
预期响应: {"ret":0, "msg":"Succeed", "data":{"replies":[]}}
```

---

## 📝 修改文件清单

| 文件 | 修改内容 | 状态 |
|------|----------|------|
| `TencentDocApiUtil.java` | `updateCells` → `updateCellsRequest` | ✅ |

### 修改位置

```java
// 文件：TencentDocApiUtil.java
// 方法：writeSheetData()
// 行号：约 420 行

// 修改：
request.put("updateCellsRequest", updateCells);  // ✅
```

---

## 🎯 预期效果

### 完整日志（修复后）

```
写入表格数据（batchUpdate）- range: M3, rowIndex: 2, colIndex: 12
请求体: {
  "requests": [
    {
      "updateCellsRequest": {
        "range": {
          "sheetId": "BB08J2",
          "startRowIndex": 2,
          "endRowIndex": 3,
          "startColumnIndex": 12,
          "endColumnIndex": 13
        },
        "rows": [
          {
            "values": [
              {
                "cellValue": {
                  "text": "https://3.cn/2ume-Ak1"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
API响应状态码: 200
API响应: {"ret":0, "msg":"Succeed", "data":{"replies":[]}}
成功写入物流链接 - 单元格: M3, 单号: JY2025110329041 ✅
```

---

## 📚 参考文档

- [在线表格批量更新接口](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/update.html)
- [Request 类型说明](https://docs.qq.com/open/document/app/openapi/v3/sheet/batchupdate/request.html)

---

## ⚠️ 关键提醒

### 1. 请求类型命名必须严格遵循规范

❌ **错误示例**：
```json
{
  "requests": [
    {"updateCells": {...}},      // 错误：缺少 Request
    {"addSheet": {...}},         // 错误：缺少 Request
    {"deleteDimension": {...}}   // 错误：缺少 Request
  ]
}
```

✅ **正确示例**：
```json
{
  "requests": [
    {"updateCellsRequest": {...}},      // 正确
    {"addSheetRequest": {...}},         // 正确
    {"deleteDimensionRequest": {...}}   // 正确
  ]
}
```

### 2. 大小写敏感

- ✅ `updateCellsRequest` - 正确（驼峰命名）
- ❌ `UpdateCellsRequest` - 错误（首字母大写）
- ❌ `updatecellsrequest` - 错误（全小写）
- ❌ `update_cells_request` - 错误（下划线）

### 3. 字段名不能自定义

所有请求类型名称都由腾讯文档 API 官方定义，**不能自己创造或修改**。

---

## ✅ 总结

### 问题
使用了错误的字段名 `updateCells`，应该是 `updateCellsRequest`。

### 原因
腾讯文档 batchUpdate API 要求所有请求类型名称必须以 `Request` 结尾。

### 解决
将 `request.put("updateCells", ...)` 改为 `request.put("updateCellsRequest", ...)`。

### 结果
API 调用成功，物流链接正确写入表格！✅

---

**文档版本**：1.0  
**创建时间**：2025-11-05  
**依据**：腾讯文档开放平台官方 API 文档  
**状态**：✅ 已修复