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

问翻小宝静态帮助中心 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

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:

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:

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.