# 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**

```bash
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:

```ts
{
  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**

```bash
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**

```bash
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**

```bash
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:

```bash
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**

```bash
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"
```