excel-weekly-dashboard

设计可刷新的 Excel 仪表板（Power Query + 结构化表 + 验证 + 数据透视报告）。当您需要可重复的每周 KPI 工作簿并通过最少的手动工作从文件进行更新时使用。

# Excel weekly dashboards at scale

## PURPOSE
Designs refreshable Excel dashboards (Power Query + structured tables + validation + pivot reporting).

## WHEN TO USE
- TRIGGERS:
  - Build me a Power Query pipeline for this file so it refreshes weekly with no manual steps.
  - Turn this into a structured table with validation lists and clean data entry rules.
  - Create a pivot-driven weekly dashboard with slicers for year and ISO week.
  - Fix this Excel model so refresh does not break when new columns appear.
  - Design a reusable KPI pack that updates from a folder of CSVs.
- DO NOT USE WHEN…
  - You need advanced forecasting/valuation modeling (this skill is for repeatable reporting pipelines).
  - You need a BI tool build (Power BI/Tableau) rather than Excel.
  - You need web scraping as the primary ingestion method.

## INPUTS
- REQUIRED:
  - Source data file(s): CSV, XLSX, DOCX-exported tables, or PDF-exported tables (provided by user).
  - Definition of ‘week’ (ISO week preferred) and the KPI fields required.
- OPTIONAL:
  - Data dictionary / column definitions.
  - Known “bad data” patterns to validate (e.g., blank PayNumber, invalid dates).
  - Existing workbook to refactor.
- EXAMPLES:
  - Folder of weekly CSV exports: `exports/2026-W02/*.csv`
  - Single XLSX dump with changing columns month to month

## OUTPUTS
- If asked for **plan only (default)**: a step-by-step build plan + Power Query steps + sheet layout + validation rules.
- If explicitly asked to **generate artifacts**:
  - `workbook_spec.md` (workbook structure and named tables)
  - `power_query_steps.pq` (M code template)
  - `refresh-checklist.md` (from `assets/`)
Success = refresh works after adding a new week’s files without manual edits, and validation catches bad rows.


## WORKFLOW
1. Identify source type(s) (CSV/XLSX/DOCX/PDF-export) and the stable business keys (e.g., PayNumber).
2. Define the canonical table schema:
   - required columns, types, allowed values, and “unknown” handling.
3. Design ingestion with Power Query:
   - Prefer **Folder ingest** + combine, with defensive “missing column” handling.
   - Normalize column names (trim, case, collapse spaces).
4. Design cleansing & validation:
   - Create a **Data_Staging** query (raw-normalized) and **Data_Clean** query (validated).
   - Add validation columns (e.g., `IsValidPayNumber`, `IsValidDate`, `IssueReason`).
5. Build reporting layer:
   - Pivot table(s) off **Data_Clean**
   - Slicers: Year, ISOWeek; plus operational dimensions
6. Add a “Refresh Status” sheet:
   - last refresh timestamp, row counts, query error flags, latest week present
7. STOP AND ASK THE USER if:
   - required KPIs/columns are unspecified,
   - the source files don’t include any stable key,
   - week definition/timezone rules are unclear,
   - PDF/DOCX tables are not reliably extractable without a provided export.


## OUTPUT FORMAT
When producing a **plan**, use this template:

```text
WORKBOOK PLAN
- Sheets:
  - Data_Staging (query output)
  - Data_Clean (query output + validation flags)
  - Dashboard (pivots/charts)
  - Refresh_Status (counts + health checks)
- Canonical Schema:
  - <Column>: <Type> | Required? | Validation
- Power Query:
  - Query 1: Ingest_<name> (Folder/File)
  - Query 2: Clean_<name>
  - Key transforms: <bullets>
- Validation rules:
  - <rule> -> <action>
- Pivot design:
  - Rows/Columns/Values
  - Slicers
```

If asked for artifacts, also output:
- `assets/power-query-folder-ingest-template.pq` (adapted)
- `assets/refresh-checklist.md`


## SAFETY & EDGE CASES
- Read-only by default: provide a plan + snippets unless the user explicitly requests file generation.
- Never delete or overwrite user files; propose new filenames for outputs.
- Prefer “no silent failure”: include row-count checks and visible error flags.
- For PDF/DOCX sources, require user-provided exported tables (CSV/XLSX) or clearly mark extraction risk.


## EXAMPLES
- Input: “Folder of weekly CSVs with PayNumber/Name/Date.”  
  Output: Folder-ingest PQ template + schema + Refresh Status checks + pivot dashboard plan.

- Input: “Refresh breaks when new columns appear.”  
  Output: Defensive missing-column logic + column normalization + typed schema plan.

---

## 中文说明

# 大规模的 Excel 每周仪表板

## 目的
设计可刷新的 Excel 仪表板（Power Query + 结构化表 + 验证 + 数据透视报告）。

## 何时使用
- 触发条件：
  - 为这个文件搭建一条 Power Query 管道，使其每周刷新且无需手动步骤。
  - 将其转换为带验证列表和规范化录入规则的结构化表。
  - 创建一个由数据透视驱动、带年份和 ISO 周切片器的每周仪表板。
  - 修复这个 Excel 模型，使其在出现新列时刷新不会中断。
  - 设计一个可复用的 KPI 套件，从一个 CSV 文件夹自动更新。
- 不要在以下情况使用……
  - 你需要高级的预测/估值建模（本技能面向可重复的报告管道）。
  - 你需要构建 BI 工具（Power BI/Tableau）而非 Excel。
  - 你需要把网页抓取作为主要的数据摄取方式。

## 输入
- 必需：
  - 源数据文件：CSV、XLSX、DOCX 导出的表格，或 PDF 导出的表格（由用户提供）。
  - “周”的定义（推荐 ISO 周）以及所需的 KPI 字段。
- 可选：
  - 数据字典 / 列定义。
  - 需要验证的已知“坏数据”模式（例如空的 PayNumber、无效日期）。
  - 需要重构的现有工作簿。
- 示例：
  - 每周 CSV 导出的文件夹：`exports/2026-W02/*.csv`
  - 列每月变化的单个 XLSX 转储文件

## 输出
- 如果只要求**计划（默认）**：分步搭建计划 + Power Query 步骤 + 工作表布局 + 验证规则。
- 如果明确要求**生成产物**：
  - `workbook_spec.md`（工作簿结构与命名表）
  - `power_query_steps.pq`（M 代码模板）
  - `refresh-checklist.md`（来自 `assets/`）
成功标准 = 添加新一周的文件后无需手动编辑即可刷新成功，且验证能捕获到坏数据行。


## 工作流
1. 识别源类型（CSV/XLSX/DOCX/PDF 导出）以及稳定的业务键（例如 PayNumber）。
2. 定义规范的表结构（schema）：
   - 必需列、类型、允许值，以及“未知值”的处理方式。
3. 用 Power Query 设计数据摄取：
   - 优先采用**文件夹摄取（Folder ingest）** + 合并，并对“缺失列”做防御性处理。
   - 规范化列名（修剪空格、统一大小写、合并多余空格）。
4. 设计清洗与验证：
   - 创建 **Data_Staging** 查询（原始-规范化）和 **Data_Clean** 查询（已验证）。
   - 添加验证列（例如 `IsValidPayNumber`、`IsValidDate`、`IssueReason`）。
5. 构建报告层：
   - 基于 **Data_Clean** 的数据透视表
   - 切片器：Year、ISOWeek；以及业务维度
6. 添加一个“刷新状态”工作表：
   - 上次刷新时间戳、行数、查询错误标志、当前最新周
7. 在以下情况下停止并向用户询问：
   - 必需的 KPI/列未指定，
   - 源文件不包含任何稳定键，
   - 周定义/时区规则不清晰，
   - 在没有用户提供导出的情况下，PDF/DOCX 表格无法可靠提取。


## 输出格式
在生成**计划**时，使用此模板：

```text
WORKBOOK PLAN
- Sheets:
  - Data_Staging (query output)
  - Data_Clean (query output + validation flags)
  - Dashboard (pivots/charts)
  - Refresh_Status (counts + health checks)
- Canonical Schema:
  - <Column>: <Type> | Required? | Validation
- Power Query:
  - Query 1: Ingest_<name> (Folder/File)
  - Query 2: Clean_<name>
  - Key transforms: <bullets>
- Validation rules:
  - <rule> -> <action>
- Pivot design:
  - Rows/Columns/Values
  - Slicers
```

如果要求生成产物，还需输出：
- `assets/power-query-folder-ingest-template.pq`（已适配）
- `assets/refresh-checklist.md`


## 安全与边界情况
- 默认只读：除非用户明确要求生成文件，否则只提供计划 + 代码片段。
- 绝不删除或覆盖用户文件；为输出建议新的文件名。
- 优先“不静默失败”：包含行数检查和可见的错误标志。
- 对于 PDF/DOCX 源，要求用户提供导出的表格（CSV/XLSX），否则明确标注提取风险。


## 示例
- 输入：“带有 PayNumber/Name/Date 的每周 CSV 文件夹。”  
  输出：文件夹摄取 PQ 模板 + schema + 刷新状态检查 + 数据透视仪表板计划。

- 输入：“出现新列时刷新会中断。”  
  输出：防御性的缺失列逻辑 + 列名规范化 + 带类型的 schema 计划。