---
name: edge-spreadsheet-docs
description: edge_collector 表格、CSV、XLSX 文档处理规范。用于整理点位清单、协议模板、测试用例、数据质量统计、AI 分析数据摘要、设备清单、问题回溯表和导入导出表格，支持读取、生成、校验 CSV/XLSX。
---

# edge_collector 表格文档处理

## 适用场景

- 点位清单和协议模板对照。
- 系统测试用例表。
- 数据质量统计表。
- 设备/网关清单。
- 故障问题回溯表。
- AI 分析输入/输出摘要。
- CSV/XLSX 导入导出检查。

## 工具选择

- 简单 CSV：优先用 Python `csv` 或 `pandas`。
- XLSX 格式和样式：使用 `openpyxl`。
- 需要公式：使用 Excel 公式，不在 Python 中硬编码计算结果。
- 大文件分析：分块读取，避免一次性加载导致内存过高。

## 表格设计

每张表应明确：

- 表名。
- 数据来源。
- 时间范围。
- 字段含义。
- 单位。
- 是否脱敏。
- 生成时间。

## 当前项目常用列

点位/设备：

```text
网关名称, 网关ID, 设备名称, 设备ID, 点位名称, 点位ID, 协议, 数据类型, 单位, 说明
```

测试用例：

```text
编号, 模块, 场景, 前置条件, 操作步骤, 预期结果, 实际结果, 状态, 问题记录
```

数据质量：

```text
对象, 时间范围, 原始点数, 有效点数, 分析点数, 最大间隔, 缺口数量, 重复值比例, 结论
```

## 校验

CSV：

```bash
python3 - <<'PY'
import csv
with open("file.csv", newline="", encoding="utf-8-sig") as f:
    rows = list(csv.reader(f))
print(len(rows), rows[0] if rows else [])
PY
```

XLSX：

```python
from openpyxl import load_workbook
wb = load_workbook("file.xlsx", data_only=False)
print(wb.sheetnames)
```

## 注意

- 中文 CSV 优先使用 `utf-8-sig`，方便 Excel 打开。
- 导出给用户的表格不要出现内部字段名、接口路径或密钥。
- 公式表必须检查 `#REF!`、`#DIV/0!`、`#VALUE!`、`#NAME?`。
- 修改既有模板时保留原列顺序和样式，除非用户明确要求调整。