# 数据源 Schema

本报告生成器为 **通用型数据报告引擎**，不依赖固定的 Schema，可接受任意结构的 Excel 文件作为输入。

## 数据要求

### 基本要求

- **格式**：Excel 文件（.xlsx / .xls）或 CSV 文件（.csv）
- **编码**：UTF-8（推荐），CSV 文件自动编码检测（支持 utf-8 / gbk / latin-1 等）
- **文件大小**：建议单文件不超过 50MB
- **行数**：支持数百～数十万行

### 列类型建议

引擎通过 `data_profiler.py` 自动检测每列的数据角色，支持以下类型：

| 角色 | 检测方式 | 适用场景 |
|------|---------|---------|
| **数值列** | dtype 判断 + 列名关键词 + 值分布分析 | 销售额、台数、金额、数量、评分等可计算指标 |
| **分类列** | 唯一值基数 + 列名关键词 + 值内容分析 | 国家、状态、类型、部门、负责人等分组维度 |
| **时间列** | dtype 判断 + 列名关键词 + 日期格式解析 | 日期、时间戳、月份等时间序列维度 |
| **ID 列** | 列名关键词 + 值模式（邮箱/电话/长数字串） | 客户编号、订单号、合同号、邮箱等标识字段 |
| **文本列** | 高基数文本 + 列名关键词 | 备注、描述、地址、摘要等非结构化内容 |
| **布尔列** | 值内容（是/否、true/false、0/1） | 开关状态、是否标记等二值字段 |

> 引擎支持**值内容驱动的自动识别**：当列名无法明确判断时，通过采样分析列中实际数据内容（如检测到 >50% 的邮箱格式则自动归类为 ID 列，检测到是/否值则归类为分类列）来提高识别准确率。

## 自动推断能力

`data_profiler.py` 是数据探查核心引擎，提供以下自动推断能力：

### 1. 列类型与角色推断

| 分析维度 | 检测内容 |
|---------|---------|
| 列类型推断 | 数值列（int/float）、分类列（低基数）、时间列、文本列、ID 列、布尔列 |
| 值模式分析 | 百分比值、二值（是/否）、序数值（高/中/低）、电话格式、邮箱格式、URL、纯数字ID |
| 语义关键词匹配 | 通过列名关键词推断业务含义（支持中英文，覆盖 100+ 关键词） |

### 2. 统计特征提取

| 分析维度 | 检测内容 |
|---------|---------|
| 基础统计 | count、sum、mean、median、min、max、std |
| 分位数 | p25（下四分位）、p75（上四分位） |
| 分布形态 | 偏度（skewness）、峰度（kurtosis）、偏态方向、变差系数（CV） |
| 集中度分析 | 高度集中（CV<0.3）/ 中度集中 / 适度分散 / 高度分散 |

### 3. 分类维度分析

| 分析维度 | 检测内容 |
|---------|---------|
| 基数统计 | 唯一值数量、占比 |
| 集中度 | Herfindahl-Hirschman 指数（HHI），识别头部集中度 |
| 分布描述 | Top-N 项及其占比 |

### 4. 数据质量评估

| 评分维度 | 权重 | 检测内容 |
|---------|------|---------|
| 完整性 | 30% | 缺失率综合评分，高缺失列标识（>30%） |
| 数值健康度 | 25% | 异常值比例、负值检查、零值过多检查 |
| 唯一性 | 20% | ID 列的识别和覆盖度 |
| 时间一致性 | 15% | 时间范围的合法性和有序性 |
| 分类完整性 | 10% | 分类列缺失比例 |

### 5. 衍生关系检测

引擎自动检测数值列之间的潜在算术关系：

| 关系类型 | 示例 | 用途 |
|---------|------|------|
| 减法关系 | `A - B ≈ C` | 发现派生指标（如：总需求 - 已下单 = 未下单） |
| 加法关系 | `A + B ≈ C` | 发现总和关系 |
| 比例关系 | `A / B ≈ 常数` | 发现固定比率（如：转化率、占比） |

### 6. 数据问题检测

`detect_data_issues()` 自动扫描：

- **高缺失率列**（>50%）— 建议排除或补全
- **中度缺失列**（>10%）— 提示关注
- **异常值**（IQR 3倍以外）— 标识离群点
- **负值** — 对非负指标列进行标记
- **常量列** — 仅 1 个唯一值，对分析无贡献

## 数据加载

`data_loader.py` 提供自动格式检测、编码识别、智能清洗等通用加载能力。

### 自动格式检测

`auto_detect_file_format()` 根据扩展名自动识别：

| 格式 | 扩展名 | 支持说明 |
|------|--------|---------|
| Excel (.xlsx) | `.xlsx` | 标准 Excel 格式，主力支持 |
| Excel 97 (.xls) | `.xls` | 兼容模式，如遇读取错误建议另存为 .xlsx |
| CSV | `.csv` | 自动编码检测（utf-8 → gbk → latin-1 等逐级尝试） |

### 核心加载函数

```python
from scripts.data_loader import (
    load_generic_excel,
    load_generic_all_sheets,
    load_generic_csv,
    auto_detect_date_column,
    load_generic_file_info,
    normalize_column_names,
)

# 加载主表（自动识别 xlsx/xls/csv，自动清洗）
df = load_generic_excel('任意数据文件.xlsx')
df = load_generic_excel('任意数据文件.csv', encoding='gbk')  # CSV 可指定编码
df = load_generic_excel('data.xlsx', sheet_name='Sheet1')    # 指定 sheet

# 合并所有 Sheet（Excel 文件）
df_all = load_generic_all_sheets('多sheet文件.xlsx')

# 直接加载 CSV（带自动编码检测）
df_csv = load_generic_csv('data.csv')

# 轻量文件信息（不加载全量数据）
info = load_generic_file_info('data.xlsx')
# 返回: {format, sheet_names, sheet_count, file_size_mb}
```

### 智能清洗特性

`load_generic_excel()` 与 `_clean_generic_dataframe()` 自动执行：

| 清洗步骤 | 说明 |
|---------|------|
| 去除全空行列 | `dropna(how='all')` 清除完全为空的行和列 |
| 去除 Unnamed 列 | 自动过滤 pandas 自动生成的 Unnamed 列 |
| **列名规范化** | 全角括号→半角、去除首尾空格、统一空白字符 |
| **汇总行自动去除** | 自动检测底部"合计/总计/小计/total/sum"等汇总行并移除 |
| 空首尾行清理 | 检测并裁剪前导和尾随的完全空行 |
| 日期智能解析 | object 类型列尝试 `pd.to_datetime()`，成功 >70% 则转换 |
| 数值智能解析 | object 类型列尝试 `pd.to_numeric()`，成功 >70% 则转换 |

> 注意：`load_generic_all_sheets()` 会给每行添加 `_source_sheet` 列标记来源 sheet。

### 列名规范化示例

```python
from scripts.data_loader import normalize_column_names

# 全角括号 → 半角：   描述（国家+车型+台数+交期） → 描述(国家+车型+台数+交期)
# 首尾空格去除：         "  客户姓名  "           → "客户姓名"
# 换行符替换：           "客户\n姓名"             → "客户 姓名"
```

## 数据探查

```python
from scripts.data_profiler import profile_dataframe, detect_data_issues

# 自动探查数据结构
profile = profile_dataframe(df)

# 检测数据问题
issues = detect_data_issues(df)

# 生成探索摘要
from scripts.data_profiler import generate_summary_text
print(generate_summary_text(profile))

# 分类分布细化分析
from scripts.data_profiler import profile_category_distribution, profile_numeric_series
dist = profile_category_distribution(df, '客户类型')       # 分类分布（含 HHI 集中度）
stats = profile_numeric_series(df, '总需求台数')           # 数值详细统计（含分布形态）
```

## 配置驱动的指标计算

```python
from scripts.metrics_calculator import (
    calc_generic_metrics,
    calc_generic_trend,
    calc_generic_distribution,
    calc_generic_ranking,
    generate_generic_insights,
)
from scripts.report_config import ReportConfig, MetricDef

# 按配置计算指标
metrics = calc_generic_metrics(df, config)

# 按指定列计算趋势
trend = calc_generic_trend(df, '日期列', '数值列')

# 分布分析
dist = calc_generic_distribution(df, '分类列', '数值列')

# 排行分析
ranking = calc_generic_ranking(df, '排行维度列', '数值列')

# 智能洞察生成
insights = generate_generic_insights(profile, metrics)
```

## 推荐配置生成

```python
from scripts.agent_analyzer import analyze_and_recommend

# 根据数据探查结果自动推荐指标集和页面结构
recommendations = analyze_and_recommend(profile, period_type)
```

## 完整工作流示例

```python
# 1. 加载数据
df = load_generic_excel('data.xlsx')

# 2. 数据探查
profile = profile_dataframe(df)

# 3. 自动推荐
recs = analyze_and_recommend(profile)

# 4. 构建配置（可人工确认调整）
config = ReportConfig(
    title='数据分析报告',
    metrics=[...],  # 从 recs['suggested_metrics'] 选取
    pages=[...],    # 从 recs['suggested_pages'] 选取
)

# 5. 计算指标
metrics = calc_generic_metrics(df, config)

# 6. 生成 PPT
output_path, issues = quality_assured_build(DATA_FILE, config, OUTPUT_FILE)
```