data-report/generate-data-report-ppt/references/data-schema.md

数据源 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 等逐级尝试）

核心加载函数

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。

列名规范化示例

from scripts.data_loader import normalize_column_names

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

数据探查

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, '总需求台数')           # 数值详细统计（含分布形态）

配置驱动的指标计算

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)

推荐配置生成

from scripts.agent_analyzer import analyze_and_recommend

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

完整工作流示例

# 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)