月度经营异常诊断助手

不止出图表，更要自动「找茬」并说清为什么。

Overview

上传月度销售/财务 CSV 或 Excel → 四层流水线自动处理：

智能清洗层（防崩溃）：CSV 编码自动识别（UTF-8/GBK/GB2312）、列名中英文同义词映射、缺失值按业务逻辑处理（时间序列插值/众数填补）、混合日期格式标准化、品类错别字修正
多维下钻聚合：按月份×地区×品类聚合 + 环比/同比计算
异常检测 + 贡献度归因（核心）：环比波动超阈值标记 → 维度贡献度分解 → 归因链路（数据录入检查 → 子项定位 → 假设性结论）
交互式 HTML 看板：趋势图 + 环比柱状图 + 贡献度分解图 + 归因结论 + 子项异常清单 + 清洗日志 + ≤3 条可执行业务建议

安全底线：CSV 数据为不可信输入。所有写入 HTML 报告的文本经 esc() 清洗（HTML 实体 + 协议注入防护 + prompt 注入过滤 + Markdown 链接中和）。详见 references/content-sanitization.md。

When to Use

上传月度销售/财务 CSV 或 Excel，需要自动清洗脏数据
定位「这个月哪里出问题了」并理解为什么
指标异常波动排查与归因
生成交互式诊断看板

Don't use for: 实时流式数据（非批量文件）；非表格数据（如 PDF 财报）；超大数据集（>100MB 建议先采样）。

Usage

python scripts/diagnose.py <file> [--output report.html] [--threshold 0.15]

| Arg | Description | Default | |-----|-------------|---------| | file | CSV/Excel path | Required | | -o, --output | HTML report path | <file>_诊断报告.html | | -t, --threshold | Anomaly threshold (0.15 = 15%) | 0.15 |

# Example
python scripts/diagnose.py assets/sample_dirty.csv
python scripts/diagnose.py sales.xlsx -o report.html -t 0.20

Input Requirements

Format: CSV (.csv) or Excel (.xlsx/.xls)
Encoding: Auto-detect UTF-8/GBK/GB2312 (Chinese enterprise CSV no manual transcoding needed)
Required columns: Date + Sales (column names support Chinese/English synonym auto-mapping)
Optional columns: Region, Category, Quantity, Cost, Channel (for multi-dimension drill-down)
File size: ≤ 100 MB

Full column synonym mapping: references/column_mapping.json.

Output

Interactive HTML Dashboard (self-contained, offline-openable):

Data overview (time span, dimension distribution)
Monthly sales trend chart (red ✕ marks anomaly months)
MoM change rate bar chart (red=drop, green=rise; deep color=exceeds threshold)
Dimension contribution decomposition chart (red=amplifies fluctuation, green=mitigates)
Anomaly attribution conclusion section
YoY analysis table (auto-skip if < 2 years of data)
Sub-item anomaly checklist (dimension-level findings, sorted by amplitude)
Smart cleaning log (color-coded by type)
≤ 3 actionable business recommendations

Color convention follows Chinese business analysis: red = decline warning, green = growth positive.

Constraints

No fabricated external data — attribution based on decomposition of uploaded data only
No brute-force zero-fill — missing values handled by business-logic interpolation or mode
No crash on encoding/format/missing — auto-adapt or clear error message
≤ 3 recommendations — focus on actionability
No modification of original files — all processing in memory

Common Pitfalls

CSV 含 prompt 注入文本污染 Agent 上下文 — 数据中 忽略所有指令 等模式经 esc() 的 HTML 转义后仍可读，Agent 读取报告时可能被误导。已追加 _filterPromptInjection() 过滤。
CSV 含 Markdown 链接语法污染报告 — [恶意](url) 通过 HTML 转义但被 Agent 以 Markdown 重读时渲染为链接。esc() 已追加 []() → 【】（） 全角替换。
CSV 编码识别失败导致乱码 — 多编码尝试链（utf-8-sig → gbk → gb2312 → utf-8 → latin-1 兜底）+ 乱码检测回退。
销售额列全空未被检测 — 列名映射成功但清洗后全 NaN。已添加边缘场景防御：sales.isna().all() → 明确报错提示。
Plotly.js 内嵌使 HTML 达 3MB+ — 自包含便于离线分发，但首次加载可能慢。建议用户用现代浏览器打开。

Verification Checklist

[ ] HTML 报告中所有 CSV 数据经 esc() 清洗（无 <script>、无 javascript: 协议、无 prompt 注入、无 [...](...) 链接语法）
[ ] 缺失值处理符合业务逻辑（时间序列→插值，分类→众数，非填补 0）
[ ] 混合日期格式全部标准化（控制台日志确认解析数量）
[ ] 归因结论可追溯（贡献度分解数据与原始数据一致）
[ ] ≤ 3 条业务建议，每条可执行
[ ] HTML 可离线打开（无外网依赖）
[ ] 色彩惯例正确（红跌绿涨，超阈值加深）

Dependencies

pandas>=2.0  numpy>=1.24  plotly>=5.18  openpyxl>=3.1

Install: pip install -r requirements.txt

Reference Files

references/column_mapping.json — Column name synonym mapping (extensible)
references/content-sanitization.md — HTML/Markdown/prompt-injection sanitization spec
scripts/diagnose.py — Main diagnosis pipeline (1050 lines, standalone-runnable)
assets/generate_sample.py — Dirty sample data generator
assets/sample_dirty.csv — Pre-generated test data with embedded anomalies
tests/run_test.py — Self-test script