wangshaoqing/star-chart-search-enhancer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
star-chart-search-enhancer/docs/superpowers/plans/2026-04-22-market-backend-metrics.md

8.6 KiB
Raw Blame History

Market Backend Metrics 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: Connect the extension to the real backend creator search API and render six backend metrics in a new 秒探指标 column while preserving the two existing Xingtu rate columns.

Architecture: Add a background-owned backend metrics request path that uses the existing Logto access token, then batch-request the visible page's star_id values from the content layer and map results back onto per-row UI state. Keep Xingtu-sourced rates untouched and add a second metrics structure for the backend-only values.

Tech Stack: TypeScript, Chrome MV3 background messaging, existing Logto auth flow, Vitest, tsup

File Map

  • Modify: src/shared/auth-messages.ts
    • Add a background message contract for backend metrics search.
  • Create: src/shared/backend-metrics-config.ts
    • Hold the default backend base URL in one place.
  • Create: src/shared/backend-metrics-client.ts
    • Build the backend request and map response rows into extension-friendly metric objects.
  • Modify: src/background/index.ts
    • Handle the new backend metrics runtime message and call the backend client with Logto token.
  • Modify: src/content/market/types.ts
    • Add types for the six backend metrics and merged row state.
  • Modify: src/content/market/result-store.ts
    • Persist backend metrics, loading, success, missing, and failure states.
  • Modify: src/content/market/dom-sync.ts
    • Add one 秒探指标 column and render loading/success/missing/failure states.
  • Modify: src/content/market/index.ts
    • Batch-load visible page star_id values through background and update row state.
  • Test: tests/backend-metrics-client.test.ts
    • Verify request payloads and response mapping.
  • Modify: tests/background-index.test.ts
    • Verify background handles backend metrics requests.
  • Modify: tests/market-content-entry.test.ts
    • Verify the content controller batches visible star_id values and renders the new metrics column.
  • Modify: tests/market-dom-sync.test.ts
    • Verify the new UI cell states.
  • Modify: tests/auth-messages.test.ts
    • Verify new message guards.

Task 1: Shared Backend Metrics Contract

Files:

  • Create: src/shared/backend-metrics-config.ts

  • Create: src/shared/backend-metrics-client.ts

  • Modify: src/shared/auth-messages.ts

  • Test: tests/backend-metrics-client.test.ts

  • Test: tests/auth-messages.test.ts

  • Step 1: Write the failing shared tests

Add tests for:

  • default backend base URL export

  • request body shape using type: "star_id"

  • mapping backend fields:

    • avg_after_view_search_rate
    • avg_after_view_search_cnt
    • avg_a3_increase_cnt
    • avg_new_a3_rate
    • cpa3
    • cp_search

  • new runtime message guard recognition

  • Step 2: Run tests to verify they fail

Run: npm test -- tests/backend-metrics-client.test.ts tests/auth-messages.test.ts Expected: FAIL because the backend metrics files and message shapes do not exist yet.

  • Step 3: Write minimal shared implementation

Implement:

  • DEFAULT_BACKEND_METRICS_BASE_URL

  • a backend client that posts to /api/v1/history/talents/search

  • request/response helpers for runtime messaging

  • Step 4: Run tests to verify they pass

Run: npm test -- tests/backend-metrics-client.test.ts tests/auth-messages.test.ts Expected: PASS

  • Step 5: Commit
git add src/shared/backend-metrics-config.ts src/shared/backend-metrics-client.ts src/shared/auth-messages.ts tests/backend-metrics-client.test.ts tests/auth-messages.test.ts
git commit -m "feat: add backend metrics shared client"

Task 2: Background Search Bridge

Files:

  • Modify: src/background/index.ts

  • Modify: tests/background-index.test.ts

  • Step 1: Write the failing background test

Add a test for a runtime message like:

{
  type: "backend-metrics:search",
  value: {
    starIds: ["111", "222"]
  }
}

Expected behavior:

  • background reads the Logto access token

  • background calls the backend metrics client

  • background returns { ok: true, type: "backend-metrics:result", value: ... }

  • Step 2: Run test to verify it fails

Run: npm test -- tests/background-index.test.ts Expected: FAIL because background does not handle the new message.

  • Step 3: Write minimal background implementation

Add:

  • a new message type guard branch

  • lazy creation of the backend metrics client

  • token injection via the existing auth controller

  • Step 4: Run test to verify it passes

Run: npm test -- tests/background-index.test.ts Expected: PASS

  • Step 5: Commit
git add src/background/index.ts tests/background-index.test.ts
git commit -m "feat: wire backend metrics search in background"

Task 3: Row State and DOM Rendering

Files:

  • Modify: src/content/market/types.ts

  • Modify: src/content/market/result-store.ts

  • Modify: src/content/market/dom-sync.ts

  • Modify: tests/market-dom-sync.test.ts

  • Step 1: Write the failing DOM rendering tests

Add tests for:

  • header contains 秒探指标

  • success state renders six metric labels and values

  • loading state renders 加载中...

  • missing state renders 暂无数据

  • failed state renders 加载失败

  • Step 2: Run tests to verify they fail

Run: npm test -- tests/market-dom-sync.test.ts Expected: FAIL because the new column and states are not implemented.

  • Step 3: Write minimal row-state and rendering implementation

Add:

  • backend metrics types

  • store methods for backend metrics status transitions

  • DOM helpers to insert and render the compact metrics panel

  • Step 4: Run tests to verify they pass

Run: npm test -- tests/market-dom-sync.test.ts Expected: PASS

  • Step 5: Commit
git add src/content/market/types.ts src/content/market/result-store.ts src/content/market/dom-sync.ts tests/market-dom-sync.test.ts
git commit -m "feat: render backend metrics column"

Task 4: Content Batch Loading

Files:

  • Modify: src/content/market/index.ts

  • Modify: tests/market-content-entry.test.ts

  • Step 1: Write the failing content integration tests

Add tests for:

  • collecting visible page authorId values as star_id[]

  • sending one background request for the page instead of one request per row

  • mapping result rows by star_id

  • rendering 暂无数据 when a row is absent from backend response

  • Step 2: Run tests to verify they fail

Run: npm test -- tests/market-content-entry.test.ts Expected: FAIL because the content controller still uses per-row Xingtu loading only.

  • Step 3: Write minimal content implementation

Change the controller so it:

  • leaves old Xingtu rates logic intact

  • batches backend metrics requests per visible page

  • merges backend results into the store by authorId

  • updates the new metrics cell state

  • Step 4: Run tests to verify they pass

Run: npm test -- tests/market-content-entry.test.ts Expected: PASS

  • Step 5: Commit
git add src/content/market/index.ts tests/market-content-entry.test.ts
git commit -m "feat: batch load backend metrics for market rows"

Task 5: Full Verification

Files:

  • Modify only if needed based on failures

  • Step 1: Run focused backend metrics test suite

Run:

npm test -- tests/backend-metrics-client.test.ts tests/auth-messages.test.ts tests/background-index.test.ts tests/market-dom-sync.test.ts tests/market-content-entry.test.ts

Expected: PASS

  • Step 2: Run the full test suite

Run: npm test Expected: PASS

  • Step 3: Run production build

Run: npm run build Expected: PASS and updated assets in dist/

  • Step 4: Manual verification checklist

Verify in the extension:

  • popup login still works

  • current page still shows old two Xingtu rate columns

  • new 秒探指标 column appears

  • rows show loading before data arrives

  • success rows show six backend metrics

  • unmatched rows show 暂无数据

  • backend/network issues show 加载失败

  • Step 5: Final commit

git add src/background/index.ts src/content/market/index.ts src/content/market/dom-sync.ts src/content/market/result-store.ts src/content/market/types.ts src/shared/backend-metrics-config.ts src/shared/backend-metrics-client.ts src/shared/auth-messages.ts tests/backend-metrics-client.test.ts tests/auth-messages.test.ts tests/background-index.test.ts tests/market-dom-sync.test.ts tests/market-content-entry.test.ts
git commit -m "feat: add backend metrics to market plugin"