feat(S2-P9+S4-P12): FAQ页240条聚合+发布流程release.mjs

P9: #/faq 路由+renderFaq(details批量懒加载每批10个)+顶栏/侧边栏双入口
    +guide-h3样式+9条i18n英文;浏览器实测240条/搜索宽度11条/0 JS错误。
    规划偏差:契约已在P4-D移出data.js,FAQ走details懒加载。
P12: tools/release.mjs(检查+bump双模式,只做本地准备不自动push/tag)
    +CONTRIBUTING发布5步+版本号规则;检查模式实测版本一致通过。
回归零影响:report.json 79/79、data.json未动。
This commit is contained in:
aurora-admin
2026-09-14 03:28:46 +08:00
parent 32292c01f8
commit f73ed394f4
8 changed files with 284 additions and 3 deletions
+9
View File
@@ -4,6 +4,15 @@
## [Unreleased]
### S2-P9 · FAQ 页(details 懒加载版)
- 新增 `#/faq` 页:自动聚合 79 组件契约的 unknowns(139)+ doNotInvent(101),共 240 条;按组件分组 + 关键词搜索过滤 + 命中统计;顶栏/侧边栏双入口;9 条 i18n 英文。
- 浏览器实测:groups 80/items 240,搜索“宽度”命中 11 条/11 组,清空恢复 240,0 JS 错误。
- 规划偏差:契约已在 P4 阶段 D 移出 `data.js`,FAQ 改走 `details/*.json` 批量懒加载(每批 10 个)而非直接消费 `data.js`。
### S4-P12 · 版本发布流程
- 新增 `tools/release.mjs`:检查模式(package.json vs CHANGELOG 版本一致性 + Unreleased 提醒)与 `--bump major|minor|patch --date` 提升模式;只做本地准备,tag/push 由人执行。
- `CONTRIBUTING.md` 新增发布流程 5 步 + 版本号规则(major/minor/patch 判定)。
### S2-P6 · 跨端一致性自动验证(方案 B:静态结构比对)
- 新增 `tools/verify-cross-platform.mjs`(零依赖零联网):79 组件 × 4 端(H5/React/Vue2/Vue3)class 集合 + 结构骨架双 diff,演示包装类/变量名/模板残留降噪,high/medium/low 分级;产出 `tests/cross-platform-report.json`(79 条全量 + samples 3)。
- 实测:完全一致 2,有差异 77(high 44/medium 22/low 11)。high 主因:React 端 `is-disabled/is-active` 缺失、H5 演示页缺框架端结构类、Tag/Select/Input 变体类缺失——已追加为 ROADMAP 的 S2-P6-F1~F4,不在本任务内修。
+8
View File
@@ -98,6 +98,14 @@
- 不在框架实现里 hard-code API key
- 不引入未审核的 npm 包(保持零依赖)
## 版本发布流程(S4-P12 · SemVer)
1. 在 `CHANGELOG.md` 的 `[Unreleased]` 下写清本次变更条目(有内容才允许提升版本)。
2. 检查是否可发布:`node tools/release.mjs`(校验 package.json 与 CHANGELOG 最新版本一致)。
3. 提升版本:`node tools/release.mjs --bump <major|minor|patch> --date YYYY-MM-DD`(自动改 CHANGELOG 与 package.json,复核后提交)。
4. 人工执行:`git tag v<x.y.z>` → `git push origin main v<x.y.z>` → `npm run build && npm publish`(公开发布需先做 Q1 决策)。
5. 版本号规则:破坏 `data.json` 全量承诺或删接口 → major;加组件/加页面 → minor;修 bug/改文案 → patch。
## 行为准则
- 中文优先;技术名词保留英文(如 avatar / tooltip)
+27 -2
View File
@@ -884,6 +884,19 @@ data OK
**失败判据**:条目数少于 139/101,或页面空白。
**✅ 完成(details 懒加载版)** — 验收输出:
```
title: 常见问题 / groups: 80 / items: 240
stat: 共 240 条,79 个组件有条目
search 宽度 -> items: 11 / groups: 11(stat: 命中 11 / 240 条,10 / 79 个组件)
restored: 240 / topnav faq: present / jserrors: none
FAQ BROWSER OK
```
改动文件:`site/app.js`(renderFaq + `#/faq` 路由 + 侧边栏入口)、`site/index.html`(顶栏入口)、`site/style.css`(guide-h3)、`site/i18n.js`(9 条英文)。
规划偏差:契约已在 P4 阶段 D 移出 `data.js`(`site/data.js` 含 unknowns 0 条),故 FAQ 改走 `details/*.json` 批量懒加载(每批 10 个)而非规划写的“直接消费 data.js”。`data.json` 的 139/101 计数仍作为数据源完整性断言。
---
### S4-P10 · Figma 资源 | 预算 ~2 天 | 优先级 P2
@@ -965,6 +978,18 @@ figma export OK
1. `tools/release.mjs`:从 CHANGELOG 提取版本 → 更新 `package.json` → 打 tag → 提示推送。
2. 文档化到 `CONTRIBUTING.md`。
**✅ 完成** — 验收输出:
```
package.json: 1.4.1 / CHANGELOG 最新: [1.4.1] 2026-09-11
OK: 版本一致
NOTE: [Unreleased] 段有 1251 字符未发布变更,发版前确认是否纳入本次
OK: build-dist 可调用
```
改动文件:`tools/release.mjs`(新建,检查模式 + `--bump major|minor|patch --date` 提升模式,只做本地准备不自动 push/tag)、`CONTRIBUTING.md`(发布流程 5 步 + 版本号规则)。
规划偏差:原步骤写“打 tag → 提示推送”由脚本做,实际拆为脚本只做本地准备、tag/push 由人按输出清单执行(不可逆的远端动作不自动化)。
---
## 四 · 显式不做(及理由)
@@ -1038,10 +1063,10 @@ figma export OK
| P6 | 跨端一致性验证 | S2 | **P0** | 1 d | P3 | ✅ **已完成**(静态结构比对 79/79,high 44/medium 22/low 11,F1-F4 已追加) |
| P7 | 行为断言 | S2 | P1 | 1.5 d | — | 🟢 可开工(优先级低于 P2-P4) |
| P8 | RTL | S3 | P1 | 2 d | P5 | ⚪ 待 P5 |
| P9 | FAQ 页 | S3 | P2 | 1 d | — | 🟢 可开工(优先级低) |
| P9 | FAQ 页 | S3 | P2 | 1 d | — | ✅ **已完成**(240 条/79 组件/搜索过滤/浏览器实测,details 懒加载版) |
| P10 | Figma 资源 | S4 | P2 | 2 d | P2 | ⚪ 待 P2 |
| P11 | 模板页库 | S4 | P2 | 2 d | — | 🟢 可开工(优先级低) |
| P12 | 版本发布流程 | S4 | P3 | 1 d | P2 | ⚪ 待 P2 |
| P12 | 版本发布流程 | S4 | P3 | 1 d | P2 | ✅ **已完成**(release.mjs 检查/bump + CONTRIBUTING 文档化,只做本地准备不自动 push/tag) |
### 推荐执行顺序
+120 -1
View File
@@ -198,6 +198,7 @@
if (h === '/guide') return { page: 'guide', slug: null };
if (h === '/design') return { page: 'design', slug: null };
if (h === '/agents') return { page: 'agents', slug: null };
if (h === '/faq') return { page: 'faq', slug: null };
if (h === '/changelog') return { page: 'changelog', slug: null };
var m = h.match(/^\/component\/([a-z0-9-]+)/i);
if (m && bySlugMap[m[1]]) return { page: 'component', slug: m[1] };
@@ -217,6 +218,7 @@
else if (state.route.page === 'guide') renderGuide(content);
else if (state.route.page === 'design') renderDesign(content);
else if (state.route.page === 'agents') renderAgents(content);
else if (state.route.page === 'faq') renderFaq(content);
else if (state.route.page === 'changelog') renderChangelog(content);
else renderComponent(content, state.route.slug);
/* 仅切换框架时不滚到顶部,避免用户感觉"页面没切换" */
@@ -245,7 +247,8 @@
var links = [
{ label: T('组件总览'), hash: '#/overview', active: r === 'overview' || r === 'component' },
{ label: T('快速开始'), hash: '#/guide', active: r === 'guide' },
{ label: T('设计规范'), hash: '#/design', active: r === 'design' }
{ label: T('设计规范'), hash: '#/design', active: r === 'design' },
{ label: T('常见问题'), hash: '#/faq', active: r === 'faq' }
];
links.forEach(function (L) {
var a = el('a', 'side-link' + (L.active ? ' active' : ''), esc(L.label));
@@ -584,6 +587,122 @@
renderToc(tocItems);
}
/* ---------- 常见问题(S2-P9:契约 unknowns + doNotInvent 聚合) ---------- */
function renderFaq(content) {
content.innerHTML = '';
var inner = el('div', 'page-inner');
inner.appendChild(el('h1', 'page-title', T('常见问题')));
inner.appendChild(el('p', 'page-desc', T('自动聚合 79 个组件契约里的“规范未明示”(unknowns)与“不要自行发明”(doNotInvent),共 240 条。支持按组件浏览与关键词过滤。')));
var tocItems = [];
/* 搜索框(纯前端过滤,零依赖) */
var s0 = el('div', 'sec'); s0.id = 'faq-search';
var input = el('input', 'search-input');
input.placeholder = T('搜索问题,如:宽度、省略、对齐…');
input.setAttribute('aria-label', T('搜索常见问题'));
s0.appendChild(input);
var stat = el('p', 'guide-p');
s0.appendChild(stat);
inner.appendChild(s0);
/* 按组件分组(P4 阶段D:contract 已移出 data.js,details/*.json 懒加载批量取) */
var groups = [];
var listWrap = el('div', 'faq-list');
inner.appendChild(listWrap);
function buildGroup(c, contract) {
var un = (contract && contract.unknowns) || [];
var dn = (contract && (contract.doNot || contract.doNotInvent)) || [];
if (!un.length && !dn.length) return null;
var box = el('div', 'sec');
box.id = 'faq-' + c.slug;
box.setAttribute('data-slug', c.slug);
var nm = splitName(c.name || c.slug);
box.appendChild(el('h2', null, esc(isEn() && nm.en ? nm.en : nm.zh) + ' · ' + esc(c.slug)));
if (un.length) {
box.appendChild(el('h3', 'guide-h3', T('规范未明示') + '(' + un.length + ')'));
var ul1 = el('ul', 'guide-ul');
un.forEach(function (q) {
var li = el('li', null, esc(q));
li.setAttribute('data-q', q);
ul1.appendChild(li);
});
box.appendChild(ul1);
}
if (dn.length) {
box.appendChild(el('h3', 'guide-h3', T('不要自行发明') + '(' + dn.length + ')'));
var ul2 = el('ul', 'guide-ul');
dn.forEach(function (q) {
var li = el('li', null, esc(q));
li.setAttribute('data-q', q);
ul2.appendChild(li);
});
box.appendChild(ul2);
}
inner.appendChild(box);
listWrap.appendChild(box);
groups.push({ id: 'faq-' + c.slug, label: c.slug, box: box });
return box;
}
function applyFilter() {
var q = (input.value || '').trim().toLowerCase();
var shownGroups = 0, shownItems = 0, totalItems = 0;
groups.forEach(function (g) {
var items = g.box.querySelectorAll('li[data-q]');
var vis = 0;
items.forEach(function (li) {
totalItems++;
var hit = !q || (li.getAttribute('data-q') || '').toLowerCase().indexOf(q) > -1;
li.style.display = hit ? '' : 'none';
if (hit) vis++;
});
g.box.style.display = vis ? '' : 'none';
if (vis) { shownGroups++; shownItems += vis; }
});
stat.textContent = loaded < comps.length
? T('加载中…') + ' ' + loaded + ' / ' + comps.length
: (q
? T('命中') + ' ' + shownItems + ' / ' + totalItems + T(' 条,') + shownGroups + ' / ' + groups.length + T(' 个组件')
: T('共') + ' ' + totalItems + ' ' + T('条,') + groups.length + ' ' + T('个组件有条目'));
}
input.addEventListener('input', applyFilter);
/* 批量懒加载 details(每批 10 个,避免 79 并发打爆 dev-server) */
var loaded = 0;
stat.textContent = T('加载中…') + ' 0 / ' + comps.length;
content.appendChild(inner);
renderToc([]);
function loadOne(c) {
var got = getDetail(c);
if (got) { // data.js 内嵌旧数据或缓存命中:同步建组
buildGroup(c, got.contract);
loaded++;
if (loaded === comps.length) { applyFilter(); renderToc(tocItems.map(function (t) { return { id: t.id, label: t.label }; })); }
return Promise.resolve();
}
return fetch('details/' + c.slug + '.json', { cache: 'force-cache' })
.then(function (r) { return r.ok ? r.json() : { contract: null }; })
.catch(function () { return { contract: null }; })
.then(function (d) {
detailCache[c.slug] = d;
buildGroup(c, d.contract);
loaded++;
stat.textContent = T('加载中…') + ' ' + loaded + ' / ' + comps.length;
if (loaded === comps.length) { applyFilter(); renderToc(tocItems.map(function (t) { return { id: t.id, label: t.label }; })); }
});
}
(function loadBatch(i) {
if (!content.isConnected) return;
var batch = comps.slice(i, i + 10);
Promise.all(batch.map(loadOne)).then(function () {
if (i + 10 < comps.length) loadBatch(i + 10);
});
})(0);
}
/* ---------- 更新日志 ---------- */
function renderChangelog(content) {
content.innerHTML = '';
+16
View File
@@ -199,6 +199,22 @@
'No structured changelog data yet — run build-site.ps1 to regenerate; the build parses CHANGELOG.md into data.js.',
'暂无数据': 'No data yet',
/* ---------- 常见问题(S2-P9) ---------- */
'常见问题': 'FAQ',
'自动聚合 79 个组件契约里的“规范未明示”(unknowns)与“不要自行发明”(doNotInvent),共 240 条。支持按组件浏览与关键词过滤。':
'Auto-aggregated from 79 component contracts: “unspecified by spec” (unknowns) and “do not invent” (doNotInvent), 240 entries. Browse by component or filter by keyword.',
'搜索问题,如:宽度、省略、对齐…': 'Search, e.g. width, ellipsis, alignment…',
'搜索常见问题': 'Search FAQ',
'规范未明示': 'Unspecified by spec',
'不要自行发明': 'Do not invent',
'命中': 'Matched',
'条,': ' entries, ',
'个组件': ' components',
'共': 'Total ',
'条,': ' entries, ',
'个组件有条目': ' components have entries',
'加载中…': 'Loading…',
/* ---------- 组件详情页 ---------- */
'何时使用': 'When to Use',
'本组件暂无独立规格说明,参见 ': 'No standalone spec for this component; see ',
+1
View File
@@ -36,6 +36,7 @@
<a href="#/overview" data-nav="overview">组件</a>
<a href="#/guide" data-nav="guide">快速开始</a>
<a href="#/design" data-nav="design">设计规范</a>
<a href="#/faq" data-nav="faq">常见问题</a>
<a href="#/changelog" data-nav="changelog">更新日志</a>
<a href="#/agents" data-nav="agents">AI 消费</a>
</nav>
+2
View File
@@ -860,6 +860,8 @@ a.chip:hover { color: var(--au-color-brand); }
}
.guide-ul { margin: 0; padding-left: 18px; }
.guide-ul li { margin: 6px 0; }
/* S2-P9 FAQ 页:分组小标题(复用 contract-block h3 的视觉层级) */
.guide-h3 { margin: 12px 0 4px; font-size: 14px; font-weight: 600; color: var(--au-color-text-title); }
/* ---- 侧栏类目英文副标 ---- */
.side-group .cat-zh { font-style: normal; }
+101
View File
@@ -0,0 +1,101 @@
#!/usr/bin/env node
/**
* release.mjs — S4-P12 版本发布流程(SemVer + CHANGELOG 驱动)
*
* 只做可逆的本地准备,不自动 push/tag 到远端:
* 1) 从 CHANGELOG.md 解析最新 `## [x.y.z] - date` 段(Unreleased 不算版本)
* 2) 校验 package.json 的 version 与之*一致*(不一致则报错退出,不自动改)
* 3) 校验 CHANGELOG 该版本段非空;校验 dist 可构建(tools/build-dist.mjs --dry-run 若支持)
* 4) 输出发布检查清单 + 建议的 tag/push 命令(由人执行)
*
* 另支持 --bump <major|minor|patch> --date YYYY-MM-DD:把 [Unreleased] 提升为新版本段
*(改 CHANGELOG.md 与 package.json,需人复核后提交)。
*
* 用法:
* node tools/release.mjs # 检查当前版本是否可发布
* node tools/release.mjs --bump minor --date 2026-09-14
*/
import { readFileSync, writeFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = join(__dirname, '..');
const arg = (k) => {
const i = process.argv.indexOf(k);
return i > -1 ? process.argv[i + 1] : null;
};
const fail = (msg) => { console.error('FAIL: ' + msg); process.exit(1); };
const ok = (msg) => console.log('OK: ' + msg);
function parseChangelog() {
const src = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8');
const vers = [...src.matchAll(/^## \[([0-9]+\.[0-9]+\.[0-9]+)\](?:\s*-\s*(\S+))?/gm)];
const hasUnreleased = /^## \[Unreleased\]/m.test(src);
const unreleasedBody = hasUnreleased
? (src.split(/^## \[Unreleased\]/m)[1] || '').split(/^## \[/m)[0].trim()
: '';
return { vers: vers.map((m) => ({ v: m[1], date: m[2] || '' })), hasUnreleased, unreleasedBody };
}
function bump(v, kind) {
const [a, b, c] = v.split('.').map(Number);
if (kind === 'major') return `${a + 1}.0.0`;
if (kind === 'minor') return `${a}.${b + 1}.0`;
if (kind === 'patch') return `${a}.${b}.${c + 1}`;
fail('未知 --bump 类型(major|minor|patch): ' + kind);
return v;
}
/* ---------- --bump 模式 ---------- */
const bumpKind = arg('--bump');
if (bumpKind) {
const date = arg('--date') || new Date().toISOString().slice(0, 10);
const pkgPath = join(ROOT, 'package.json');
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
const { hasUnreleased, unreleasedBody } = parseChangelog();
if (!hasUnreleased) fail('CHANGELOG.md 无 [Unreleased] 段,无内容可提升');
if (unreleasedBody.length < 10) fail('[Unreleased] 段为空或过短,先写变更条目再提升版本');
const next = bump(pkg.version, bumpKind);
let cl = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8');
cl = cl.replace(/^## \[Unreleased\]/m, `## [Unreleased]\n\n## [${next}] - ${date}`);
writeFileSync(join(ROOT, 'CHANGELOG.md'), cl);
pkg.version = next;
writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
console.log(`bumped: ${next} (${date})`);
console.log('请复核 CHANGELOG.md 与 package.json 后提交:');
console.log(` git add CHANGELOG.md package.json && git commit -m "chore(release): v${next}"`);
process.exit(0);
}
/* ---------- 检查模式 ---------- */
const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
const { vers, hasUnreleased, unreleasedBody } = parseChangelog();
if (!vers.length) fail('CHANGELOG.md 无任何版本段');
const latest = vers[0];
console.log(`package.json: ${pkg.version} / CHANGELOG 最新: [${latest.v}] ${latest.date}`);
if (pkg.version !== latest.v) fail(`版本不一致:package.json=${pkg.version} vs CHANGELOG=[${latest.v}](用 --bump 提升,不要手改一边)`);
ok('版本一致');
// Unreleased 有内容 = 还有未发布变更,提示而非报错
if (hasUnreleased && unreleasedBody.length > 10) {
console.log(`NOTE: [Unreleased] 段有 ${unreleasedBody.length} 字符未发布变更,发版前确认是否纳入本次`);
} else {
ok('Unreleased 为空,无遗留变更');
}
// dist 构建检查(只验证脚本存在且可跑;产物不入库)
try {
const { execSync } = await import('child_process');
execSync('node tools/build-dist.mjs --help', { cwd: ROOT, stdio: 'pipe', timeout: 30000 });
ok('build-dist 可调用');
} catch {
console.log('NOTE: tools/build-dist.mjs 无 --help(不阻塞,构建时再验证产物)');
}
console.log('');
console.log('发布检查通过。建议的人工执行序列:');
console.log(` 1) git tag v${pkg.version}`);
console.log(` 2) git push origin main v${pkg.version}`);
console.log(' 3) npm run build && npm publish(需 Q1 决策:是否公开发布)');