feat(问翻小宝): 接入静态帮助中心

docs/superpowers/plans/2026-06-30-wenfan-xiaobao-help-center.md

@@ -0,0 +1,229 @@
+# 问翻小宝静态帮助中心 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.