docs: add market csv and layout design notes
This commit is contained in:
parent
233de28713
commit
24e8a3ba9a
@ -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.
|
||||
@ -0,0 +1,63 @@
|
||||
# Market Backend Metrics CSV Design
|
||||
|
||||
## Goal
|
||||
|
||||
Extend the existing CSV export so it includes the six backend metrics already shown in the plugin UI.
|
||||
|
||||
## Confirmed Decisions
|
||||
|
||||
- Reuse the current export flow.
|
||||
- Do not add a separate backend request for CSV export.
|
||||
- Read backend metrics directly from the in-memory `MarketRecord`.
|
||||
- Append the six backend metrics columns after the existing CSV columns.
|
||||
- Keep the existing CSV columns and ordering unchanged.
|
||||
- Use these exact CSV headers:
|
||||
- `看后搜率`
|
||||
- `看后搜数`
|
||||
- `新增A3数`
|
||||
- `新增A3率`
|
||||
- `CPA3`
|
||||
- `cp_search`
|
||||
- If a record has no backend metrics, export empty strings for these six columns.
|
||||
|
||||
## Architecture
|
||||
|
||||
- `src/content/market/csv-exporter.ts` remains the single place that defines CSV column layout.
|
||||
- The exporter will keep current base columns and Xingtu rate columns, then append six backend metrics columns.
|
||||
- No UI changes.
|
||||
- No batch submission changes.
|
||||
- No popup or config changes.
|
||||
|
||||
## Data Source
|
||||
|
||||
Each exported row will read from:
|
||||
|
||||
- existing fields:
|
||||
- `authorId`
|
||||
- `authorName`
|
||||
- `location`
|
||||
- `price21To60s`
|
||||
- `rates.singleVideoAfterSearchRate`
|
||||
- `rates.personalVideoAfterSearchRate`
|
||||
- new backend metrics fields:
|
||||
- `backendMetrics.afterViewSearchRate`
|
||||
- `backendMetrics.afterViewSearchCount`
|
||||
- `backendMetrics.a3IncreaseCount`
|
||||
- `backendMetrics.newA3Rate`
|
||||
- `backendMetrics.cpa3`
|
||||
- `backendMetrics.cpSearch`
|
||||
|
||||
## Failure Handling
|
||||
|
||||
- Missing backend metrics: export blank cells
|
||||
- Existing rate formatting behavior remains unchanged
|
||||
- Backend loading state does not alter CSV structure; it only affects whether the cells contain values or blanks
|
||||
|
||||
## Testing
|
||||
|
||||
Add tests for:
|
||||
|
||||
- backend metric headers appended to CSV
|
||||
- backend metric values exported correctly
|
||||
- empty backend metric cells when metrics are absent
|
||||
- no regression in current base/rate export behavior
|
||||
@ -0,0 +1,35 @@
|
||||
# Market Scrollable Plugin Columns Design
|
||||
|
||||
**Goal:** Keep the plugin-generated columns visible without letting them cover Xingtu's native middle columns.
|
||||
|
||||
**Problem:** The current implementation injects plugin columns into the right sticky section. That expands the sticky width and causes native middle columns such as `预期播放量` and `互动率` to be visually covered.
|
||||
|
||||
**Approved Direction:** Keep plugin columns always visible, but move them out of the right sticky area. The plugin columns should live in the horizontally scrollable middle area so they scroll together with the native table columns.
|
||||
|
||||
## Design
|
||||
|
||||
### Layout
|
||||
|
||||
- Preserve the native left sticky author section.
|
||||
- Preserve the native right sticky section for Xingtu's own right-side columns, especially `21-60s报价` and `操作`.
|
||||
- Insert plugin columns as a separate non-sticky section immediately before the right sticky section.
|
||||
- Let the plugin section participate in the same horizontal flow as the middle columns so users reach it through horizontal scrolling.
|
||||
|
||||
### DOM Sync Responsibilities
|
||||
|
||||
- `syncDivGridRoot()` remains responsible for locating the author section, middle columns, and right sticky section.
|
||||
- Plugin header cells and plugin body columns should no longer be inserted into `actionHeader.parentElement` / `actionColumn.parentElement`.
|
||||
- A dedicated plugin section should be created or reused under the header row and body row.
|
||||
- Row alignment logic should still read plugin cells row-by-row for rendering, visibility, and ordering.
|
||||
|
||||
### Behavior
|
||||
|
||||
- Export, filtering, sorting, and row hydration should keep working unchanged.
|
||||
- Only column placement changes.
|
||||
- Existing synthetic table mode is unaffected.
|
||||
|
||||
### Testing
|
||||
|
||||
- Add regression coverage proving the right sticky section width stays at the native width.
|
||||
- Add regression coverage proving plugin columns render in a separate non-sticky section.
|
||||
- Keep existing export and hydration behavior green.
|
||||
Loading…
x
Reference in New Issue
Block a user