Agentic Coding 实战一：从零做销售数据看板

# 销售看板项目规格

## R - 角色 / 背景
我是公司会计。每周要从 ERP 导出的销售 Excel 里，
做一份给老板的看板。希望做成网页，每周一早上自动生成。

## F - 功能
读取 sales.csv（ERP 导出格式），生成网页看板：

数据清洗规则（我的专业！）：
- amount 为负的行是退款，单独统计但不算入销售
- 客户名为空视为散户，归到「未分类」
- date 列要解析成日期
- product 列去前后空格

展示内容：
1. 4 个 KPI 卡片：总销售额 / 有效订单数 / 客单价 / 毛利率
2. 销售趋势：按周汇总的折线图
3. Top 10 客户表格（按销售额降序）
4. 异常预警：环比下降超过 20% 的客户标红

界面：
- 单页 HTML，能本地打开
- 简洁商务风（蓝灰主色）
- 手机也能看

## C - 验收标准
- 给定 sales.csv 跑一遍，生成 dashboard.html
- 用真实数据核对：总销售额要等于 Excel 里 SUMIF(amount>0)，
  Top 1 客户要对得上，毛利率要符合行业 25%-35% 的常识

# 销售看板 - 任务分解

## L2 模块
1. 数据层：读 CSV + 清洗
2. 计算层：KPI + Top 客户 + 趋势
3. 展示层：生成 HTML 看板

## L3 任务清单（节选）
- 1.1 写 load_data()：读 sales.csv
- 1.2 写 clean_data()：清洗规则
- 1.3 写测试验证清洗结果
- 2.1 写 calc_kpis()：4 个 KPI
- 2.2 写 top_customers()：Top 10
- 2.3 写 weekly_trend()：周趋势
- 2.4 写 detect_anomalies()：异常预警
- 3.1 生成基础 HTML 框架
- 3.2 渲染 KPI 卡片
- 3.3 嵌入折线图（Chart.js）
- 3.4 渲染客户表格 + 红色预警

## MVP（最小可用版）
完成 1.1 + 1.2 + 2.1 + 3.1 + 3.2 就能跑起来。

mkdir sales-dashboard
cd sales-dashboard
git init

在当前目录建一个 Python 项目，结构如下：
- data/            放 CSV 数据
- src/             放源代码
- tests/           放测试
- output/          放生成的 HTML
- SPEC.md          项目规格
- .gitignore       忽略规则
- requirements.txt 依赖清单

先创建好这些目录和空文件，再写一份示例 sales.csv 放 data/ 里
（10 行假数据，含中文客户名、有退款行、有空字段）。

date,customer,product,amount,cost
2026-06-01,北京科技有限公司,服务A,15000,9000
2026-06-02,上海贸易,产品B,8000,5600
2026-06-03,,产品A,3000,1800
2026-06-04,深圳科技,服务A,22000,13000
2026-06-05,北京科技有限公司,产品B,-5000,-3000

git add .
git commit -m "项目初始化：目录结构 + 示例数据"

任务：实现数据层（SPEC.md 里的模块 1）

请实现 src/data_loader.py，包含两个函数：
1. load_data(file_path)：用 pandas 读 CSV，date 列解析为日期，
   amount 列转 float
2. clean_data(df)：amount 大于 0 为有效订单，小于 0 为退款；
   customer 为空的填「未分类」，返回有效订单、退款单和散单数量

并写 tests/test_data_loader.py，至少 5 个测试用例：正常数据、
含退款、含空客户名、缺失 amount 字段、空文件。跑通测试后告诉我。

# src/data_loader.py
import pandas as pd

def load_data(file_path):
    df = pd.read_csv(file_path, encoding='utf-8-sig')
    df['date'] = pd.to_datetime(df['date'], errors='coerce')
    df['amount'] = df['amount'].astype(float)
    return df

def clean_data(df):
    valid = df[df['amount'] > 0].copy()
    refunds = df[df['amount'] < 0].copy()
    valid['customer'] = valid['customer'].fillna('未分类').str.strip()
    unknown = (valid['customer'] == '未分类').sum()
    return {'valid': valid, 'refunds': refunds,
            'unknown_customer_count': unknown}

python -m pytest tests/ -v

任务：实现展示层（SPEC.md 里的模块 3）

请实现 src/render.py，生成 output/dashboard.html：
1. 单页 HTML，所有 CSS/JS 内联，不依赖外部文件
2. 用 Chart.js（CDN 引入）画折线图
3. 顶部 4 个 KPI 卡片并排，中间销售趋势折线图，下方 Top 10 客户表格
4. 主色 #2563eb，背景 #f8fafc，文字 #1e293b
5. 异常客户在表格里整行标红（背景 #fef2f2）
6. 响应式，手机也能看

入口 main.py 调用所有模块，生成最终 dashboard.html。
写完跑 python main.py，确认文件生成成功。

sales-dashboard/
├── data/sales.csv
├── src/
│   ├── data_loader.py
│   ├── calculator.py
│   └── render.py
├── tests/
│   ├── test_data_loader.py
│   └── test_calculator.py
├── output/dashboard.html
├── main.py
├── SPEC.md
├── CLAUDE.md
├── requirements.txt
└── .gitignore