# 问翻小宝静态帮助中心 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:** Build the first-stage Wenfan Xiaobao static help center with local keyword matching, article answers, related actions, and local page screenshots.

**Architecture:** Store help content in frontend static TypeScript data, search it with pure local scoring functions, and render matched articles inside the existing chat-style Wenfan page. Screenshots are generated by a Node script that opens local routes with Chrome/Edge headless and writes PNG files to `public/help/wenfan-xiaobao/`.

**Tech Stack:** Next.js App Router, React client components, TypeScript, Tailwind CSS, Node built-ins, Chrome/Edge headless screenshot command.

---

## File Map

- Create `apps/web/lib/wenfan-help-articles.ts`: static article data and shared types.
- Create `apps/web/lib/wenfan-help-search.ts`: query normalization, scoring, search results, fallback suggestions.
- Create `apps/web/lib/wenfan-help-search.test.ts`: TDD tests for keywords, synonyms, fallback, related articles.
- Modify `apps/web/app/wenfan-xiaobao/page.tsx`: replace static mock chat with local search-driven chat UI.
- Modify `apps/web/lib/wenfan-xiaobao-ui.test.ts`: assert page imports help search and renders help answer surfaces.
- Create `apps/web/scripts/capture-wenfan-help-screenshots.mjs`: local screenshot script.
- Create `apps/web/public/help/wenfan-xiaobao/*.png`: generated help images.

## Task 1: Static Help Search Tests

**Files:**
- Create: `apps/web/lib/wenfan-help-search.test.ts`

- [ ] **Step 1: Write the failing test**

```ts
import test from 'node:test';
import assert from 'node:assert/strict';
import { getFallbackHelpSuggestions, searchHelpArticles } from './wenfan-help-search';
import { WENFAN_HELP_ARTICLES } from './wenfan-help-articles';

test('searchHelpArticles matches common product creation phrasing', () => {
  const result = searchHelpArticles('产品怎么新建，要填什么字段', WENFAN_HELP_ARTICLES);
  assert.equal(result[0]?.article.id, 'product-create');
});

test('searchHelpArticles matches demand adoption and version inclusion synonyms', () => {
  const result = searchHelpArticles('需求怎么纳入版本号里面', WENFAN_HELP_ARTICLES);
  assert.equal(result[0]?.article.id, 'version-requirement-include');
});

test('searchHelpArticles matches dev task test submission phrasing', () => {
  const result = searchHelpArticles('开发任务怎么提测', WENFAN_HELP_ARTICLES);
  assert.equal(result[0]?.article.id, 'dev-task-workflow');
});

test('searchHelpArticles keeps related article ids from the matched article', () => {
  const result = searchHelpArticles('AI拆解测试用例在哪里', WENFAN_HELP_ARTICLES);
  assert.equal(result[0]?.article.id, 'ai-decompose');
  assert.ok(result[0]?.relatedArticles.some((article) => article.id === 'product-plan'));
});

test('getFallbackHelpSuggestions returns starter examples when no article matches', () => {
  assert.deepEqual(getFallbackHelpSuggestions().slice(0, 3), [
    '怎么新建产品？',
    '怎么把需求纳入版本？',
    '开发任务怎么提测？',
  ]);
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pnpm --filter web test`

Expected: TypeScript fails because `wenfan-help-search` and `wenfan-help-articles` do not exist.

## Task 2: Static Help Article Data

**Files:**
- Create: `apps/web/lib/wenfan-help-articles.ts`

- [ ] **Step 1: Create types and 12 article records**

Create `HelpArticle`, `HelpImage`, `WENFAN_HELP_ARTICLES`, and 12 records:

```ts
export type HelpImage = {
  src: string;
  alt: string;
  caption: string;
};

export type HelpArticle = {
  id: string;
  title: string;
  category: string;
  keywords: string[];
  scenario: string;
  entry: string;
  steps: string[];
  requiredFields: string[];
  statusFlow: string[];
  notes: string[];
  images: HelpImage[];
  relatedIds: string[];
};
```

Every article must include module words, action words, oral phrasing, synonyms, and common spelling variants in `keywords`.

- [ ] **Step 2: Run test to verify remaining failure**

Run: `pnpm --filter web test`

Expected: TypeScript still fails because `searchHelpArticles` is not implemented.

## Task 3: Local Help Search Engine

**Files:**
- Create: `apps/web/lib/wenfan-help-search.ts`

- [ ] **Step 1: Implement local scoring**

Implement:

```ts
export type HelpSearchResult = {
  article: HelpArticle;
  score: number;
  matchedKeywords: string[];
  relatedArticles: HelpArticle[];
};

export function normalizeHelpQuery(input: string): string;
export function searchHelpArticles(query: string, articles?: HelpArticle[]): HelpSearchResult[];
export function getFallbackHelpSuggestions(): string[];
```

Scoring rules:

- Exact title inclusion: +20
- Category inclusion: +12
- Keyword inclusion: +10 per keyword
- Step / required field / status flow / note inclusion: +3 per hit
- Query shorter than 2 normalized characters returns empty results.

- [ ] **Step 2: Run tests to verify pass**

Run: `pnpm --filter web test`

Expected: all help search tests pass.

## Task 4: Chat Page Integration

**Files:**
- Modify: `apps/web/app/wenfan-xiaobao/page.tsx`
- Modify: `apps/web/lib/wenfan-xiaobao-ui.test.ts`

- [ ] **Step 1: Update UI static test first**

Add assertions that the page imports `searchHelpArticles`, renders `HelpAnswer`, and contains article sections for entry, required fields, status flow, notes, and images.

- [ ] **Step 2: Run test to verify it fails**

Run: `pnpm --filter web test`

Expected: `wenfan xiaobao page` static test fails because page has not been wired to help search.

- [ ] **Step 3: Implement local chat behavior**

Use `useState` for input and messages. On send:

- Search local help articles.
- If matched, append a user message and an article answer message.
- If no match, append fallback suggestions.
- Quick question buttons call the same send function.

Render `HelpAnswer` with article title, scenario, entry, steps, required fields, status flow, notes, images, and related buttons.

- [ ] **Step 4: Run tests to verify pass**

Run: `pnpm --filter web test`

Expected: all tests pass.

## Task 5: Screenshot Script and Images

**Files:**
- Create: `apps/web/scripts/capture-wenfan-help-screenshots.mjs`
- Create directory: `apps/web/public/help/wenfan-xiaobao/`

- [ ] **Step 1: Implement Chrome/Edge headless screenshot script**

The script should:

- Detect Chrome or Edge on Windows.
- Use `--headless=new --screenshot=<file> --window-size=1440,1000 <url>`.
- Capture the approved route list from `http://localhost:3000`.
- Write PNG files into `apps/web/public/help/wenfan-xiaobao/`.

- [ ] **Step 2: Run screenshot script**

Run: `node apps/web/scripts/capture-wenfan-help-screenshots.mjs`

Expected: PNG files are created for the configured routes. If the dev server is not available, the script exits with a clear message.

## Task 6: Final Verification

**Files:**
- All files touched above.

- [ ] **Step 1: Run full tests**

Run: `pnpm --filter web test`

Expected: 0 failures.

- [ ] **Step 2: Run type check**

Run: `pnpm --filter web type-check`

Expected: exit code 0.

- [ ] **Step 3: Check route response**

Run: `curl.exe -I http://localhost:3000/wenfan-xiaobao`

Expected: HTTP 200.

- [ ] **Step 4: Inspect git status**

Run: `git status --short`

Expected: only intended Wenfan help center files and earlier Wenfan UI files are changed.