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,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.