first commit

2026-05-10 13:52:46 +08:00
commit ccc63d1e70
4583 changed files with 584341 additions and 0 deletions
--- a/minimax-xlsx/pivot.md
+++ b/minimax-xlsx/pivot.md
@@ -0,0 +1,164 @@
+---
+name: pivot
+description: "Operational playbook for building PivotTables with the MiniMaxXlsx CLI. Treat this as the source of truth before invoking the pivot subcommand."
+---
+
+# Pivot Operations Manual
+
+Use this guide when a workbook needs grouped aggregation, cross-axis summaries, or interactive drilldown.
+
+## 1) Decision Gate
+
+Choose PivotTable mode when one or more conditions are true:
+
+- The request explicitly asks for a pivot table
+- The dataset is large enough that formula-only summaries become hard to maintain
+- The user needs category-by-category totals, count splits, or two-dimensional breakdowns
+- The output must support manual filtering and regrouping inside Excel
+
+Do not force PivotTable mode for trivial one-line totals. Use formulas for simple, static math.
+
+## 2) Input Readiness Contract
+
+Before running any pivot command, confirm:
+
+- Header row exists and every header is unique
+- Source block has no merged cells
+- No blank row breaks inside the data block
+- Aggregation fields are numeric where required
+- Workbook formulas already passed structural checks
+
+Recommended preflight sequence:
+
+```bash
+./scripts/MiniMaxXlsx refcheck working.xlsx
+./scripts/MiniMaxXlsx info working.xlsx --pretty
+```
+
+`info` output is authoritative. Never guess sheet names or ranges manually.
+
+## 3) Seven-Checkpoint Flow
+
+Follow this exact flow to avoid broken files:
+
+1. **Assemble base workbook** with openpyxl (cover, raw data, helper sheets)
+2. **Save once** and run `refcheck`
+3. **Inspect metadata** using `info --pretty`
+4. **Draft pivot command** from inspected headers and ranges
+5. **Run pivot as final write operation**
+6. **Run structural validation** with `check`
+7. **Deliver without reopening output in openpyxl**
+
+Why checkpoint 7 matters: a second openpyxl save can repackage XML relationships and invalidate pivot internals.
+
+## 4) Command Surface
+
+### Required arguments
+
+| Argument | Meaning | Example |
+|---|---|---|
+| `input.xlsx` | Source workbook to read | `working.xlsx` |
+| `output.xlsx` | New workbook to generate | `deliverable.xlsx` |
+| `--source` | Full source range with sheet prefix | `"RevenueLog!B3:H920"` |
+| `--location` | Pivot anchor cell | `"PivotBoard!C4"` |
+| `--values` | Metric + reducer list | `"NetAmount:sum,OrderNo:count"` |
+
+### Optional arguments
+
+| Argument | Meaning | Example |
+|---|---|---|
+| `--rows` | Row grouping fields | `"Region,Channel"` |
+| `--cols` | Column grouping fields | `"Quarter"` |
+| `--filters` | Page filters | `"Year,Owner"` |
+| `--name` | Pivot object name | `"QuarterlyMix"` |
+| `--style` | Theme (`monochrome` / `finance`) | `"monochrome"` |
+| `--chart` | Companion chart (`bar` / `line` / `pie`) | `"line"` |
+
+Supported reducers: `sum`, `count`, `avg`, `average`, `min`, `max`.
+
+## 5) Parameter Assembly Pattern
+
+Build parameters in this order to reduce mistakes:
+
+1. `--location` (destination first)
+2. `--values` (what to aggregate)
+3. `--source` (where data comes from)
+4. `--rows` / `--cols` / `--filters` (how to slice)
+5. `--name` / `--style` / `--chart` (presentation)
+
+This ordering is intentional: start from reporting target, then metric intent, then data origin.
+
+## 6) Fresh Example Set
+
+### Scenario A: Operations latency rollup
+
+```bash
+./scripts/MiniMaxXlsx pivot \
+    ops_raw.xlsx ops_pivot.xlsx \
+    --location "OpsPivot!B5" \
+    --values "LatencyMs:avg,RequestId:count" \
+    --source "ApiEvents!A1:G1800" \
+    --rows "Service,Cluster" \
+    --filters "ReleaseTag" \
+    --name "LatencyOverview" \
+    --style "monochrome" \
+    --chart "line"
+```
+
+### Scenario B: Clinic visit mix by month
+
+```bash
+./scripts/MiniMaxXlsx pivot \
+    clinic_daily.xlsx clinic_report.xlsx \
+    --location "VisitSummary!A4" \
+    --values "VisitFee:sum,VisitId:count" \
+    --source "VisitLog!A1:F2400" \
+    --rows "Department" \
+    --cols "VisitMonth" \
+    --name "DeptVisitMix" \
+    --style "finance" \
+    --chart "bar"
+```
+
+### Scenario C: Warehouse damage composition
+
+```bash
+./scripts/MiniMaxXlsx pivot \
+    warehouse_events.xlsx warehouse_dashboard.xlsx \
+    --location "LossShare!D3" \
+    --values "LossCost:sum" \
+    --source "DamageRecords!A1:E460" \
+    --rows "LossType" \
+    --filters "Warehouse" \
+    --name "LossStructure" \
+    --chart "pie"
+```
+
+## 7) Validation and Release Rule
+
+Run:
+
+```bash
+./scripts/MiniMaxXlsx check deliverable.xlsx
+```
+
+- Exit code `0`: release candidate
+- Non-zero: do not patch the xlsx in place; regenerate from corrected source flow
+
+## 8) Failure Playbook
+
+| Symptom | Likely Cause | Action |
+|---|---|---|
+| Pivot shows no records | Source range clipped | Re-run `info`, expand `--source` to full block |
+| "Field not found" | Header mismatch or typo | Copy header text directly from `info` output |
+| Validation fails on pivot nodes | Damaged pivot relationships | Rebuild from base workbook, run pivot once as final step |
+| CLI execution fails unexpectedly | Workbook locked by another app | Close Excel/WPS process and retry |
+
+## 9) Hard Prohibitions
+
+- Do not manually construct pivot XML
+- Do not run pivot before all openpyxl sheet edits are complete
+- Do not open and save pivot output with openpyxl
+- Do not deliver files that fail `check`
+
+If any prohibition is violated, regenerate the workbook end-to-end.