# 腾讯文档 V3 写入数据问题分析

## 🔴 问题现象

尝试使用腾讯文档 V3 API 的 `batchUpdate` 接口写入单元格数据时，始终返回错误：

```json
{
  "code": 400001,
  "message": "request name error"
}
```

**尝试过的请求类型**：
1. ❌ `updateCells` - 报错：request name error
2. ❌ `updateCellsRequest` - 报错：request name error
3. 🔄 `repeatCellRequest` - 正在测试

---

## 🔍 根本问题分析

### 观察到的现象

1. **读取数据成功**：
   ```
   GET /openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
   ✅ 成功返回数据
   ```

2. **批量更新失败**：
   ```
   POST /openapi/spreadsheet/v3/files/{fileId}/batchUpdate
   ❌ request name error
   ```

3. **官方文档示例**：
   - ✅ `addSheetRequest` - 添加工作表（结构操作）
   - ✅ `deleteDimensionRequest` - 删除维度（结构操作）
   - ❓ `updateCellsRequest` - **官方文档未提及**

### 可能的原因

#### 原因 1：V3 API 不支持单元格数据写入

腾讯文档 V3 API 的 `batchUpdate` 接口可能**只支持结构性操作**，不支持数据写入：

| 支持的操作 | 说明 |
|-----------|------|
| ✅ addSheetRequest | 添加工作表 |
| ✅ deleteSheetRequest | 删除工作表 |
| ✅ deleteDimensionRequest | 删除行/列 |
| ✅ insertDimensionRequest | 插入行/列 |
| ✅ mergeCellsRequest | 合并单元格 |
| ❌ updateCellsRequest | **数据写入（不支持？）** |
| ❌ writeCellsRequest | **数据写入（不支持？）** |

#### 原因 2：V3 API 文档不完整

腾讯文档官方文档可能没有公开所有可用的请求类型，或者写入数据的接口使用不同的端点。

#### 原因 3：需要使用 V2 API

腾讯文档 V2 API 可能有专门的写入接口，但 V2 API 已被标记为"已废弃"。

---

## 💡 可能的解决方案

### 方案 1：使用 repeatCellRequest（当前尝试）

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

**说明**：`repeatCell` 通常用于在范围内重复填充相同的单元格内容，可能可以用于单个单元格写入。

---

### 方案 2：使用 V2 API（如果 V1/V3 都不支持）

腾讯文档 V2 API 可能有不同的接口结构。需要查看 V2 文档。

**优点**：
- 可能有专门的数据写入接口
- 可能更简单直接

**缺点**：
- V2 API 已标记为"已废弃"
- 未来可能不再维护

---

### 方案 3：使用 append 接口追加数据

如果目标是追加新数据（而不是更新现有单元格），可以使用 `appendDimension` 或类似接口。

**限制**：
- 只能追加，不能更新指定位置的单元格
- 不适用于我们的场景（需要更新指定行的物流列）

---

### 方案 4：联系腾讯文档官方支持

**如果以上方案都不行**，需要：
1. 查看腾讯文档开放平台的完整 API 文档
2. 在官方论坛/社区提问
3. 联系技术支持获取帮助

---

## 🧪 测试步骤

### 测试 repeatCellRequest

1. **重启应用**

2. **发送测试请求**：
   ```bash
   curl -X POST 'http://localhost:30313/jarvis/tencentDoc/fillLogisticsByOrderNo' \
     -H 'Content-Type: application/json' \
     -d '{
       "accessToken": "YOUR_ACCESS_TOKEN",
       "fileId": "DUW50RUprWXh2TGJK",
       "sheetId": "BB08J2",
       "headerRow": 2
     }'
   ```

3. **查看日志**：
   ```
   写入表格数据（batchUpdate）- range: M3
   请求体: {
     "requests": [
       {
         "repeatCellRequest": {
           "range": {...},
           "cell": {...},
           "fields": "cellValue"
         }
       }
     ]
   }
   ```

4. **预期结果**：
   - ✅ 如果成功：`{"ret":0, "msg":"Succeed"}`
   - ❌ 如果失败：继续尝试其他方案

---

## 📚 参考资料

### 官方文档

- [批量更新接口](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)
- [在线表格总览](https://docs.qq.com/open/document/app/openapi/v3/sheet/)

### 需要确认的问题

1. ❓ 腾讯文档 V3 API 是否支持单元格数据写入？
2. ❓ 如果支持，正确的请求类型名称是什么？
3. ❓ 是否需要使用不同的 API 端点？
4. ❓ 是否需要特殊权限或配置？

---

## 🎯 下一步行动

### 优先级 1：测试 repeatCellRequest

当前代码已修改为使用 `repeatCellRequest`，需要测试是否可行。

### 优先级 2：查找完整的 Request 类型列表

需要找到腾讯文档 V3 API 支持的**所有** Request 类型的完整列表，确认是否有数据写入相关的类型。

### 优先级 3：考虑备选方案

如果 batchUpdate 确实不支持数据写入：
1. 查找是否有其他 V3 API 端点支持写入
2. 考虑使用 V2 API
3. 联系官方技术支持

---

## 💬 给用户的建议

**当前状态**：
- ✅ 数据读取完全正常
- ✅ 数据库匹配完全正常
- ❌ 数据写入遇到 API 限制

**如果 repeatCellRequest 也失败**：

建议联系腾讯文档开放平台技术支持，询问：
1. V3 API 如何写入单元格数据？
2. 是否有相关的官方示例代码？
3. batchUpdate 支持哪些 Request 类型？

**腾讯文档开放平台**：
- 官网：https://docs.qq.com/open/
- 反馈入口：https://docs.qq.com/open/feedback

---

**文档版本**：1.0  
**创建时间**：2025-11-05  
**状态**：🔄 问题分析中，正在测试 repeatCellRequest