---
name: excel-report-generator
description: >
  根据用户上传的原始数据，生成格式化的 Excel 报告，包含数据清洗、
  图表生成、摘要统计三个环节。当用户需要数据报告、Excel 输出、
  自动化统计时触发。
---

# Excel 报告生成器

## 执行流程

### 第一步：读取并验证数据

1. 检查文件是否存在，格式是否为 .csv 或 .xlsx
2. 读取文件，输出基本信息：
   - 总行数、总列数
   - 各列的数据类型
   - 空值数量统计
3. 若发现严重问题（如文件为空、格式不支持），停止并告知用户

**输出**：数据基本信息报告（在对话中展示）

---

### 第二步：数据清洗

运行 `scripts/clean_data.py`，执行：
- 删除完全重复的行
- 将数值列中的空值填充为 0
- 去除字符串首尾空格

输出清洗后的数据到 `/home/claude/cleaned_data.csv`

**输出**：清洗报告（删除了多少行、修改了多少值）

---

### 第三步：生成统计摘要

运行 `scripts/calc_stats.py`，计算：
- 各数值列的均值、中位数、标准差
- 按时间列分组的趋势数据（若存在时间列）

输出到 `/home/claude/stats.json`

---

### 第四步：生成 Excel 报告

运行 `scripts/gen_excel.py`，生成包含以下内容的 Excel 文件：
- Sheet1：清洗后的原始数据
- Sheet2：统计摘要表格
- Sheet3：折线图（若存在时间序列数据）

将最终文件保存到 `/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**输出**：调用 present_files 展示文件，提供下载链接

---

### 错误处理

任意步骤失败时：
1. 展示完整错误信息
2. 说明可能的原因
3. 询问用户是否想要跳过当前步骤或修改参数后重试

# 文件路径：scripts/pipeline.py
# 单一主脚本，通过 --step 参数控制执行哪一步

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """第二步：数据清洗"""
    print(f"正在清洗数据：{input_file}")
    # 实际清洗逻辑...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """第三步：统计计算"""
    print(f"正在计算统计数据：{input_file}")
    # 实际统计逻辑...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """第四步：生成 Excel"""
    print(f"正在生成 Excel 报告：{output_file}")
    # 实际生成逻辑...
    return {"status": "success", "output": output_file}

STEPS = {
    "clean": step_clean,
    "stats": step_stats,
    "excel": step_excel,
}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--step",   required=True, choices=STEPS.keys(),
                        help="要执行的步骤：clean / stats / excel")
    parser.add_argument("--input",  required=True, help="输入文件路径")
    parser.add_argument("--output", required=True, help="输出文件路径")
    args = parser.parse_args()

    import json
    result = STEPS[args.step](args.input, args.output)
    print(json.dumps(result, ensure_ascii=False, indent=2))

# 第二步：数据清洗
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/runoob_sales.csv \
  --output /home/claude/cleaned_data.csv

# 第三步：统计计算
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

# 文件路径：scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
    检查某步骤的前置文件是否已生成

    参数：
        step_name:      当前步骤名称（用于错误提示）
        required_files: 需要存在的文件路径列表

    返回：
        True 表示所有依赖就绪，False 表示有文件缺失
    """
    missing = [f for f in required_files if not os.path.exists(f)]

    if missing:
        print(f"错误：{step_name} 缺少前置文件：")
        for f in missing:
            print(f"  - {f}")
        print("请先完成前置步骤。")
        return False

    return True

# 使用示例：在第四步生成 Excel 前检查前置文件
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("生成 Excel 报告", deps):
        sys.exit(1)
    print("所有前置文件就绪，开始生成报告...")