# 腾讯文档 API 数据格式解析说明

## 问题发现

在实际调用腾讯文档 V3 API 时，发现返回的数据格式与预期完全不同。

---

## 数据格式对比

### ❌ 我们最初预期的格式（简单格式）

```json
{
  "values": [
    ["单元格1", "单元格2", "单元格3"],
    ["数据1", "数据2", "数据3"]
  ]
}
```

### ✅ 实际返回的格式（gridData 格式）

```json
{
  "gridData": {
    "startRow": 0,
    "startColumn": 0,
    "rows": [
      {
        "values": [
          {
            "cellValue": {
              "text": "JY202506181808"
            },
            "cellFormat": {
              "textFormat": {
                "font": "Microsoft YaHei",
                "fontSize": 11,
                "bold": false,
                "italic": false,
                "strikethrough": false,
                "underline": false,
                "color": {
                  "red": 0,
                  "green": 0,
                  "blue": 0,
                  "alpha": 255
                }
              },
              "horizontalAlignment": "HORIZONTAL_ALIGNMENT_UNSPECIFIED",
              "verticalAlignment": "VERTICAL_ALIGNMENT_UNSPECIFIED"
            },
            "dataType": "DATA_TYPE_UNSPECIFIED"
          },
          {
            "cellValue": {
              "text": ""
            },
            ...
          }
        ]
      }
    ],
    "rowMetadata": [],
    "columnMetadata": []
  },
  "version": "0"
}
```

---

## 格式差异分析

### 数据层级

**简单格式**：
```
响应
└── values (数组)
    ├── 行1 (数组)
    │   ├── "单元格1"
    │   └── "单元格2"
    └── 行2 (数组)
        ├── "数据1"
        └── "数据2"
```

**gridData 格式**：
```
响应
└── gridData (对象)
    ├── startRow (数字)
    ├── startColumn (数字)
    ├── rows (数组)
    │   └── 行对象
    │       └── values (数组)
    │           └── 单元格对象
    │               ├── cellValue (对象)
    │               │   └── text (字符串) ← 实际文本内容在这里
    │               ├── cellFormat (对象)
    │               └── dataType (字符串)
    ├── rowMetadata (数组)
    └── columnMetadata (数组)
```

### 关键区别

| 项目 | 简单格式 | gridData 格式 |
|------|---------|--------------|
| 根字段 | `values` | `gridData` |
| 行数据 | 直接数组 | 在 `gridData.rows` 中 |
| 单元格数据 | 直接字符串 | 在 `cellValue.text` 中 |
| 格式信息 | 无 | 在 `cellFormat` 中 |
| 元数据 | 无 | 在 `rowMetadata`、`columnMetadata` 中 |

---

## 解决方案

### 1. 创建数据解析器

我们创建了 `TencentDocDataParser` 工具类来统一处理两种格式：

**位置**：`ruoyi-system/src/main/java/com/ruoyi/jarvis/util/TencentDocDataParser.java`

**核心功能**：

#### (1) 解析为简单数组格式
```java
JSONArray parsedValues = TencentDocDataParser.parseToSimpleArray(apiResponse);
```

**输入**（gridData 格式）：
```json
{
  "gridData": {
    "rows": [
      {
        "values": [
          {"cellValue": {"text": "单元格1"}},
          {"cellValue": {"text": "单元格2"}}
        ]
      }
    ]
  }
}
```

**输出**（简单格式）：
```json
[
  ["单元格1", "单元格2"]
]
```

#### (2) 获取指定行数据
```java
JSONArray row = TencentDocDataParser.getRow(apiResponse, 0);  // 获取第1行
```

#### (3) 获取指定单元格文本
```java
String cellText = TencentDocDataParser.getCellText(apiResponse, 0, 2);  // 第1行第3列
```

#### (4) 打印数据结构（调试用）
```java
TencentDocDataParser.printDataStructure(apiResponse, 5);  // 打印前5行
```

### 2. 更新 Service 层

在 `TencentDocServiceImpl.java` 的 `readSheetData` 方法中：

```java
// API 调用
JSONObject result = TencentDocApiUtil.readSheetData(...);

// 解析数据为统一的简单格式
JSONArray parsedValues = TencentDocDataParser.parseToSimpleArray(result);

// 返回包含简化格式的响应
JSONObject response = new JSONObject();
response.put("values", parsedValues);  // 统一格式
response.put("_原始数据", result);     // 保留原始数据供调试

return response;
```

### 3. 向后兼容性

解析器会自动检测数据格式：
- 如果有 `gridData` 字段 → 解析为 gridData 格式
- 如果有 `values` 字段 → 直接返回（简单格式）
- 如果都没有 → 返回空数组

```java
public static JSONArray parseToSimpleArray(JSONObject apiResponse) {
    // 方式1：检查是否有 gridData 字段（V3 API 新格式）
    JSONObject gridData = apiResponse.getJSONObject("gridData");
    if (gridData != null) {
        return parseGridData(gridData);
    }
    
    // 方式2：检查是否有 values 字段（简单格式）
    JSONArray values = apiResponse.getJSONArray("values");
    if (values != null) {
        return values;
    }
    
    // 如果都没有，返回空数组
    return new JSONArray();
}
```

---

## 使用示例

### 示例 1：读取表头

```java
// 读取第2行（索引为1）作为表头
String headerRange = "A2:Z2";
JSONObject headerData = tencentDocService.readSheetData(accessToken, fileId, sheetId, headerRange);

// 获取简化后的数据
JSONArray headerValues = headerData.getJSONArray("values");
if (headerValues != null && !headerValues.isEmpty()) {
    JSONArray headerRow = headerValues.getJSONArray(0);  // 第一行数据
    
    // 遍历表头列
    for (int i = 0; i < headerRow.size(); i++) {
        String columnName = headerRow.getString(i);
        System.out.println("第 " + (i+1) + " 列: " + columnName);
    }
}
```

### 示例 2：查找特定列

```java
// 读取表头行
JSONObject headerData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A2:Z2");
JSONArray headerValues = headerData.getJSONArray("values");
JSONArray headerRow = headerValues.getJSONArray(0);

// 查找"物流单号"列的索引
int logisticsColumn = -1;
for (int i = 0; i < headerRow.size(); i++) {
    String columnName = headerRow.getString(i);
    if ("物流单号".equals(columnName)) {
        logisticsColumn = i;
        break;
    }
}

System.out.println("物流单号列在第 " + (logisticsColumn + 1) + " 列（索引: " + logisticsColumn + "）");
```

### 示例 3：读取数据行

```java
// 读取数据行（第3行到第100行）
JSONObject sheetData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A3:Z100");
JSONArray dataValues = sheetData.getJSONArray("values");

// 遍历每一行
for (int i = 0; i < dataValues.size(); i++) {
    JSONArray row = dataValues.getJSONArray(i);
    
    // 获取订单号（假设在第1列，索引0）
    String orderNo = row.getString(0);
    
    // 获取物流单号（假设在第13列，索引12）
    String logisticsNo = row.getString(12);
    
    System.out.println("订单号: " + orderNo + ", 物流单号: " + logisticsNo);
}
```

---

## 真实数据示例

根据用户提供的截图，表格结构：

```
第1行：合并单元格，包含链接（这是合并的标题行）
第2行：表头
  A列：日期
  B列：公司
  C列：草号
  D列：型号
  E列：数量
  F列：姓名
  G列：电话
  H列：地址
  I列：价格
  J列：备注
  K列：打聚戳图
  L列：是否安排
  M列：物流单号
  N列：标记

第3行及以后：数据行
  A列：3月10日
  B列：（空）
  C列：JY20251032904
  ...
  M列：（物流单号，可能为空）
```

### 处理代码示例

```java
// 1. 读取表头（第2行）
JSONObject headerData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A2:Z2");
JSONArray headerValues = headerData.getJSONArray("values");
JSONArray headerRow = headerValues.getJSONArray(0);

// 2. 查找关键列的索引
int orderNoColumn = -1;      // 订单号列（草号）
int logisticsColumn = -1;    // 物流单号列

for (int i = 0; i < headerRow.size(); i++) {
    String columnName = headerRow.getString(i);
    if (columnName != null) {
        if (columnName.contains("草号")) {
            orderNoColumn = i;
        }
        if (columnName.contains("物流单号")) {
            logisticsColumn = i;
        }
    }
}

System.out.println("订单号列索引: " + orderNoColumn);        // 预期: 2（C列）
System.out.println("物流单号列索引: " + logisticsColumn);    // 预期: 12（M列）

// 3. 读取数据行（从第3行开始）
JSONObject sheetData = tencentDocService.readSheetData(accessToken, fileId, sheetId, "A3:Z100");
JSONArray dataValues = sheetData.getJSONArray("values");

// 4. 处理每一行数据
for (int i = 0; i < dataValues.size(); i++) {
    JSONArray row = dataValues.getJSONArray(i);
    
    // 获取订单号
    String orderNo = orderNoColumn >= 0 && orderNoColumn < row.size() 
        ? row.getString(orderNoColumn) 
        : null;
    
    // 获取物流单号
    String logisticsNo = logisticsColumn >= 0 && logisticsColumn < row.size() 
        ? row.getString(logisticsColumn) 
        : null;
    
    if (orderNo != null && !orderNo.isEmpty()) {
        System.out.println("第 " + (i+3) + " 行 - 订单号: " + orderNo + ", 物流单号: " + logisticsNo);
        
        // 如果物流单号为空，可以填充
        if (logisticsNo == null || logisticsNo.isEmpty()) {
            System.out.println("  → 需要填充物流单号");
        }
    }
}
```

---

## 写入数据注意事项

### 写入接口的数据格式

根据腾讯文档 API 规范，写入数据时仍然使用简单格式：

```java
// 写入数据（简单格式）
Object[][] values = {
    {"数据1", "数据2", "数据3"}
};

tencentDocService.writeSheetData(accessToken, fileId, sheetId, "A10", values);
```

**不需要**转换为 gridData 格式，API 会自动处理。

---

## 调试技巧

### 1. 启用详细日志

```yaml
logging:
  level:
    com.ruoyi.jarvis.util.TencentDocDataParser: DEBUG
    com.ruoyi.jarvis.service.impl.TencentDocServiceImpl: DEBUG
```

### 2. 查看数据结构

当调用 `readSheetData` 时，会自动打印前3行数据结构：

```
数据结构（共 98 行，显示前 3 行）：
  第 1 行（15列）: ["日期","公司","草号",...,"物流单号","标记"]
  第 2 行（15列）: ["3月10日","","JY20251032904",...,"",""]
  第 3 行（15列）: ["3月10日","","JY20250309184",...,"6649902864",""]
```

### 3. 检查原始响应

Service 返回的数据中包含 `_原始数据` 字段，可以查看 API 的原始响应：

```java
JSONObject result = tencentDocService.readSheetData(...);
JSONObject originalData = result.getJSONObject("_原始数据");
System.out.println("原始响应: " + originalData.toJSONString());
```

---

## 常见问题

### Q1：为什么会有两种数据格式？

**A**：腾讯文档 V3 API 使用 gridData 格式以支持更丰富的格式信息（字体、颜色、对齐方式等）。但对于简单的数据读写，我们只需要文本内容，因此解析器会提取纯文本数据。

### Q2：读取的数据是否包含格式信息？

**A**：gridData 格式包含完整的格式信息（字体、颜色等），但我们的解析器只提取文本内容。如果需要格式信息，可以从 `_原始数据` 字段中获取。

### Q3：解析器会影响性能吗？

**A**：解析器只是简单的 JSON 遍历和文本提取，性能影响很小。对于大数据量（数千行），建议分批读取。

### Q4：是否兼容旧代码？

**A**：完全兼容。解析后的数据格式与旧代码期望的格式一致（`{"values": [[]]}`），无需修改现有代码。

---

## 总结

### 关键要点

1. ✅ **腾讯文档 V3 API 使用 gridData 格式**
2. ✅ **创建了 TencentDocDataParser 统一处理**
3. ✅ **Service 层自动解析为简单格式**
4. ✅ **完全向后兼容，无需修改上层代码**
5. ✅ **保留原始数据供调试使用**

### 文件清单

- ✅ `TencentDocDataParser.java` - 数据解析器（新增）
- ✅ `TencentDocServiceImpl.java` - Service 层（已更新）
- ✅ `腾讯文档API数据格式解析说明.md` - 本文档（新增）

---

**文档版本**：1.0  
**创建时间**：2025-11-05  
**适用场景**：腾讯文档 V3 API 数据格式解析