# 数据格式规范

## 目录
- [概览](#概览)
- [支持的文件格式](#支持的文件格式)
- [数据结构要求](#数据结构要求)
- [列名规范](#列名规范)
- [数据类型建议](#数据类型建议)
- [完整示例](#完整示例)
- [验证规则](#验证规则)

## 概览
本文档定义了数据可视化Skill所需的输入数据格式规范，确保脚本能够正确解析和处理用户提供的数据。

## 支持的文件格式

### CSV格式（推荐）
- 扩展名：.csv
- 编码：UTF-8（推荐）或GBK
- 分隔符：逗号（,）
- 第一行为表头（列名）

### Excel格式
- 扩展名：.xlsx 或 .xls
- 第一个工作表包含数据
- 第一行为表头（列名）

## 数据结构要求

### 基本要求
1. 数据必须是表格形式（行和列）
2. 第一行必须是列名（表头）
3. 每列的数据类型应该一致
4. 避免在列名中使用特殊字符
5. 建议不要包含合并单元格

### 最小数据集
- 至少1列（用于直方图）
- 至少2列（用于其他图表类型）
- 至少3行数据（建议至少10行以获得有意义的可视化）

## 列名规范

### 命名规则
- 使用有意义的英文或中文列名
- 避免使用纯数字作为列名
- 不要包含特殊字符（如 !@#$%^&*()）
- 建议使用下划线（_）或空格分隔单词
- 列名长度建议不超过50个字符

### 好的列名示例
- "产品名称"
- "销售额"
- "销售日期"
- "customer_name"
- "sales_amount"

### 不好的列名示例
- "col1"
- "数据1"
- "a$b"
- "非常长的列名超过五十个字符会导致显示问题"

## 数据类型建议

### 分类数据（用于X轴或饼图标签）
- 文本类型
- 包含有限的不同值
- 示例：产品类别、地区、部门

### 数值数据（用于Y轴或散点图）
- 整数或小数
- 示例：销售额、数量、价格、分数

### 时间/日期数据（用于有序X轴）
- 标准日期格式：YYYY-MM-DD
- 标准时间格式：HH:MM:SS
- 示例：2023-01-01、2023/01/01、14:30:00

## 完整示例

### 示例1：销售数据（适合柱状图）

```csv
产品名称,销售额,利润
产品A,10000,2000
产品B,15000,3000
产品C,8000,1600
产品D,20000,4000
产品E,12000,2400
```

### 示例2：时间序列数据（适合折线图）

```csv
月份,收入,支出,利润
2023-01,50000,30000,20000
2023-02,55000,32000,23000
2023-03,60000,35000,25000
2023-04,58000,34000,24000
2023-05,62000,36000,26000
2023-06,65000,38000,27000
```

### 示例3：分布数据（适合直方图）

```csv
考试分数
85
92
78
88
95
72
80
89
91
76
83
87
94
79
86
```

### 示例4：相关性数据（适合散点图）

```csv
广告投入,销售额,访问量
1000,5000,10000
2000,9000,18000
1500,7000,14000
3000,12000,25000
2500,10000,20000
1800,8000,16000
2200,9500,19000
```

## 验证规则

在使用数据前，建议进行以下验证：

1. **文件存在性检查**
   - 确认文件路径正确
   - 确认文件可读

2. **格式检查**
   - 确认文件格式为CSV或Excel
   - 确认文件编码正确

3. **结构检查**
   - 确认文件至少有1列
   - 确认文件至少有3行数据（1行表头+2行数据）
   - 确认每行的列数一致

4. **数据质量检查**
   - 检查是否有缺失值
   - 检查数值列是否包含非数值数据
   - 检查分类列是否有足够的多样性

5. **适用性检查**
   - 根据图表类型确认数据是否适合
   - 确认有足够的数据点
   - 确认分类数量在合理范围内