docs: add market csv and layout design notes

2026-04-23 14:37:14 +08:00
parent 233de28713
commit 24e8a3ba9a
4 changed files with 238 additions and 0 deletions
@@ -0,0 +1,79 @@
+# Market Backend Metrics CSV Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extend CSV export so it appends the six backend metrics already stored on each market record.
+
+**Architecture:** Keep the existing export flow intact and modify only the CSV column definition layer. Reuse `MarketRecord.backendMetrics` as the sole source for the six new CSV columns so the exported data matches what the plugin already loaded into memory.
+
+**Tech Stack:** TypeScript, existing market CSV exporter, Vitest
+
+---
+
+## File Map
+
+- Modify: `src/content/market/csv-exporter.ts`
+  - Append six backend metrics columns after existing CSV columns.
+- Modify: `tests/csv-exporter.test.ts`
+  - Add failing tests for backend metric headers and values.
+
+### Task 1: Backend Metrics CSV Columns
+
+**Files:**
+- Modify: `tests/csv-exporter.test.ts`
+- Modify: `src/content/market/csv-exporter.ts`
+
+- [ ] **Step 1: Write the failing CSV exporter tests**
+
+Add tests for:
+- the six backend metric headers appended after current columns
+- backend metric values exported from `record.backendMetrics`
+- blank cells when `backendMetrics` is absent
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- tests/csv-exporter.test.ts`
+Expected: FAIL because the exporter does not include backend metric columns yet.
+
+- [ ] **Step 3: Write the minimal exporter change**
+
+Append these six columns:
+- `看后搜率`
+- `看后搜数`
+- `新增A3数`
+- `新增A3率`
+- `CPA3`
+- `cp_search`
+
+Each column reads from:
+- `record.backendMetrics?.afterViewSearchRate`
+- `record.backendMetrics?.afterViewSearchCount`
+- `record.backendMetrics?.a3IncreaseCount`
+- `record.backendMetrics?.newA3Rate`
+- `record.backendMetrics?.cpa3`
+- `record.backendMetrics?.cpSearch`
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npm test -- tests/csv-exporter.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Run full verification**
+
+Run:
+
+```bash
+npm test
+npm run build
+```
+
+Expected:
+- full test suite passes
+- build succeeds
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/content/market/csv-exporter.ts tests/csv-exporter.test.ts docs/superpowers/specs/2026-04-22-market-backend-metrics-csv-design.md docs/superpowers/plans/2026-04-22-market-backend-metrics-csv.md
+git commit -m "feat: export backend metrics in csv"
+```
@@ -0,0 +1,61 @@
+# Market Scrollable Plugin Columns Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move plugin-generated market columns out of the right sticky area and into the horizontally scrollable middle area.
+
+**Architecture:** Keep Xingtu's native left and right sticky sections intact. Add a dedicated non-sticky plugin section for the injected columns and continue rendering row state through the existing `MarketRowDom` abstraction.
+
+**Tech Stack:** TypeScript, Vitest, jsdom
+
+---
+
+### Task 1: Lock The Intended Layout In Tests
+
+**Files:**
+- Modify: `tests/market-dom-sync.test.ts`
+- Modify: `tests/market-content-entry.test.ts`
+
+- [ ] **Step 1: Write failing tests for the layout boundary**
+
+Add assertions that:
+- the right sticky header/body widths remain native after plugin columns are added
+- plugin columns live in a dedicated non-sticky section instead of the right sticky section
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- tests/market-dom-sync.test.ts tests/market-content-entry.test.ts`
+
+- [ ] **Step 3: Implement the minimal layout changes**
+
+Update the div-grid sync path so plugin columns are inserted into a separate scrollable section.
+
+- [ ] **Step 4: Re-run the same tests**
+
+Run: `npm test -- tests/market-dom-sync.test.ts tests/market-content-entry.test.ts`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/market-dom-sync.test.ts tests/market-content-entry.test.ts src/content/market/dom-sync.ts
+git commit -m "feat: move market plugin columns into scrollable section"
+```
+
+### Task 2: Verify No Export Regression
+
+**Files:**
+- Verify only: `src/content/market/index.ts`
+- Verify only: `src/content/market/export-range-controller.ts`
+- Verify only: `tests/full-scan-controller.test.ts`
+
+- [ ] **Step 1: Run export-related regression tests**
+
+Run: `npm test -- tests/full-scan-controller.test.ts`
+
+- [ ] **Step 2: Run build**
+
+Run: `npm run build`
+
+- [ ] **Step 3: Report any unrelated failures separately**
+
+Do not broaden the scope unless a new failure is caused by the layout change.