230 lines
7.5 KiB
Markdown
230 lines
7.5 KiB
Markdown
# 问翻小宝静态帮助中心 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.
|