feat(S6-P21): 组件族参数化(13族/44成员/导航族15文件同源/79→48概念组件)
【本次核心 · S6-P21】 - 族层数据：families.json + 44 份契约注入 family/familyRole/familyParams； data.json / data.js / site/details 同步。13 族 / 44 成员 / 35 独立 → 概念组件 79→48。 - 79 个 slug 全保留、集合逐一不变（铁律 5 对外承诺未破）；frameworks 仍 395 文件、薄壳仍 79。 - 归族判据为契约中可核对字段（semanticTypeCandidates 重叠 / anatomy 为同一骨架子集 / 变体维度同构 / doNotInvent 显式从属声明），每族 mergeBasis 写明依据，不按名字猜。 - 实现层合并（导航族端到端切片）：tools/gen-family-impl.mjs 从 5 端模板生成 TopMenu / SideMenu / MixedNavigation 共 15 文件，参数 direction=top|side|mixed； 三份 CSS md5 完全相同 = 一份样式表服务三个组件。 - 新增 tools/gen-families.mjs、tools/gen-family-impl.mjs、tools/verify-families.mjs、 tools/lib/family-model.mjs、tools/lib/family-impl/nav-menu/*.tpl。 【同时清掉此前已完成但未提交的批次】 生成物（data.json / data.js / site/sources / site/components 薄壳 / sitemap.xml / tests 报告） 跨阶段交织，无法拆成互相自洽的多个提交，故按既有批量风格合并提交： - Package：三端可 import（S5-P18）+ 发布到私有 npm 源 - Docs site：导航语言改下拉（S5-P19）、详情页代码块默认展开、中英切换完整性 - Security：生产部署链审计修复（2026-09-19）+ 线上部署 - Theme modes 日间/夜间/自动；S1-P4 data.js 瘦身；S2-P5 暗色；S2-P6 跨端一致性； S2-P7 行为断言；S2-P9 FAQ；S3-P8 RTL；S3-P9 契约缺口解释层；S4-P12 发布流程 - 补入 tools/pack-deploy.mjs、run-site-smoke.mjs、verify-*.mjs，.dockerignore、 安全审计修复与待决策项.md 【验收】 - node tools/verify-families.mjs → OK: 族层端到端一致（13 族 / 44 成员 / 79 组件不变 / 395 文件不变） - node tools/verify-cross-platform.mjs → 79/79 identical（HEAD 基线 high 44） - node tools/run-regression.mjs → 100%（79/79 页，1017/1017 断言，N/A 34），连跑 8 次一致，0 超时 - 逐页实测：topmenu / sidemenu / mixednavigation 各 13/13，帧内 direction 参数正确，0 JS 错误 - 零运行时依赖 OK；build-site.ps1 ASCII-only OK 【未纳入】site/components/<slug>/ 平台薄壳 316 个 —— 历史从未跟踪且属构建产物，保持现状。
This commit is contained in:
aurora-admin
@@ -0,0 +1,195 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* gen-families.mjs - 族层数据生成器（契约层）
|
||||
*
|
||||
* 产物：
|
||||
* 1. .design_library/aurora-admin/families.json 族模型快照（build-site.ps1 消费）
|
||||
* 2. .design_library/aurora-admin/components/<slug>.json 注入 family / familyRole / familyParams
|
||||
*
|
||||
* 注入策略：**定点插入**，不重排既有 JSON —— 只在 "slug" 行之后插入三个字段，
|
||||
* 其余字节保持不变，保证 git diff 最小且不覆盖他人未提交改动。
|
||||
*
|
||||
* 用法：
|
||||
* node tools/gen-families.mjs # 生成（原子写）
|
||||
* node tools/gen-families.mjs --dry-run # 只报将要发生的改动
|
||||
* node tools/gen-families.mjs --check # 校验磁盘状态与模型一致，不一致则退出码 1
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { FAMILIES, IMPLEMENTED_FAMILIES, memberIndex } from './lib/family-model.mjs';
|
||||
|
||||
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const LIB = path.join(ROOT, '.design_library', 'aurora-admin');
|
||||
const COMPONENTS = path.join(LIB, 'components');
|
||||
const INDEX_FILE = path.join(COMPONENTS, 'index.json');
|
||||
const FAMILIES_FILE = path.join(LIB, 'families.json');
|
||||
|
||||
const MODE = process.argv.includes('--dry-run') ? 'dry' : process.argv.includes('--check') ? 'check' : 'write';
|
||||
|
||||
const problems = [];
|
||||
let changed = 0;
|
||||
let unchanged = 0;
|
||||
|
||||
function writeAtomic(file, content) {
|
||||
const tmp = file + '.tmp';
|
||||
fs.writeFileSync(tmp, content, 'utf8');
|
||||
fs.renameSync(tmp, file);
|
||||
}
|
||||
|
||||
/** 渲染要插入的三行族字段（2 空格缩进，与既有契约格式一致） */
|
||||
function familyLines(entry) {
|
||||
const params = JSON.stringify(entry.params || {});
|
||||
return (
|
||||
` "family": ${JSON.stringify(entry.family)},\n` +
|
||||
` "familyRole": ${JSON.stringify(entry.role)},\n` +
|
||||
` "familyParams": ${params},\n`
|
||||
);
|
||||
}
|
||||
|
||||
/** 移除既有族字段（幂等重跑），返回 { text, had } */
|
||||
function stripFamily(text) {
|
||||
const re = /^ {2}"family(?:Role|Params)?":.*\n?/gm;
|
||||
const had = re.test(text);
|
||||
return { text: text.replace(/^ {2}"family(?:Role|Params)?":.*\n?/gm, ''), had };
|
||||
}
|
||||
|
||||
function main() {
|
||||
if (!fs.existsSync(INDEX_FILE)) {
|
||||
console.error('FAIL: 找不到 ' + path.relative(ROOT, INDEX_FILE));
|
||||
process.exit(2);
|
||||
}
|
||||
const index = JSON.parse(fs.readFileSync(INDEX_FILE, 'utf8'));
|
||||
const bySlug = new Map(index.components.map((c) => [c.slug, c]));
|
||||
|
||||
/* ---- 校验模型自身 ---- */
|
||||
const entries = memberIndex(); // 同一 slug 属于多族会在此抛错
|
||||
const baseSlugs = new Set(FAMILIES.map((f) => f.base));
|
||||
for (const f of FAMILIES) {
|
||||
if (!bySlug.has(f.base)) problems.push(`族 ${f.id} 的基座 ${f.base} 不在 index.json 中`);
|
||||
if (!f.members.some((m) => m.slug === f.base)) problems.push(`族 ${f.id} 的基座 ${f.base} 未登记为成员`);
|
||||
const bases = f.members.filter((m) => m.role === 'base');
|
||||
if (bases.length !== 1) problems.push(`族 ${f.id} 应恰好 1 个 base，实际 ${bases.length}`);
|
||||
for (const m of f.members) {
|
||||
if (!bySlug.has(m.slug)) problems.push(`族 ${f.id} 成员 ${m.slug} 不在 index.json 中`);
|
||||
const dims = (f.paramSurface || []).map((p) => p.name);
|
||||
for (const k of Object.keys(m.params || {})) {
|
||||
if (!dims.includes(k)) problems.push(`族 ${f.id} 成员 ${m.slug} 的参数 ${k} 未在 paramSurface 声明`);
|
||||
}
|
||||
}
|
||||
for (const p of f.paramSurface || []) {
|
||||
if (p.type === 'enum') {
|
||||
if (!Array.isArray(p.values) || p.values.length < 2) problems.push(`族 ${f.id} 参数 ${p.name} 为 enum 但取值少于 2`);
|
||||
for (const m of f.members) {
|
||||
const v = (m.params || {})[p.name];
|
||||
if (v !== undefined && !p.values.map(String).includes(String(v))) {
|
||||
problems.push(`族 ${f.id} 成员 ${m.slug} 的 ${p.name}=${v} 不在 enum 取值内`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
for (const id of IMPLEMENTED_FAMILIES) {
|
||||
if (!FAMILIES.some((f) => f.id === id)) problems.push(`IMPLEMENTED_FAMILIES 含未定义族 ${id}`);
|
||||
}
|
||||
if (problems.length) {
|
||||
console.error('FAIL: 族模型自检未通过');
|
||||
for (const p of problems) console.error(' - ' + p);
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
/* ---- 产物 1：families.json ---- */
|
||||
const payload = {
|
||||
schemaVersion: 1,
|
||||
sourceKind: 'family-model',
|
||||
generatedBy: 'tools/gen-families.mjs',
|
||||
note: '由 tools/lib/family-model.mjs 生成，勿手改。族把「同源组件」表达为「1 个基座 + N 个参数取值」；组件身份（slug）保持不变，data.json 仍完整输出 79 个组件。',
|
||||
totalFamilies: FAMILIES.length,
|
||||
totalMembers: Object.keys(entries).length,
|
||||
implementedFamilies: IMPLEMENTED_FAMILIES,
|
||||
families: FAMILIES.map((f) => ({
|
||||
...f,
|
||||
basePrefix: bySlug.get(f.base) ? bySlug.get(f.base).frameworksPrefix : null,
|
||||
memberCount: f.members.length,
|
||||
members: f.members.map((m) => ({
|
||||
...m,
|
||||
frameworksPrefix: bySlug.get(m.slug) ? bySlug.get(m.slug).frameworksPrefix : null,
|
||||
})),
|
||||
})),
|
||||
};
|
||||
const json = JSON.stringify(payload, null, 2) + '\n';
|
||||
const prev = fs.existsSync(FAMILIES_FILE) ? fs.readFileSync(FAMILIES_FILE, 'utf8') : null;
|
||||
if (prev === json) {
|
||||
console.log('= families.json 无变化');
|
||||
} else if (MODE === 'check') {
|
||||
problems.push('families.json 与模型不一致（需重跑 gen-families.mjs）');
|
||||
} else if (MODE === 'dry') {
|
||||
console.log('~ 将写入 families.json（' + json.length + ' bytes）');
|
||||
} else {
|
||||
writeAtomic(FAMILIES_FILE, json);
|
||||
console.log('+ families.json 写入 ' + json.length + ' bytes / ' + FAMILIES.length + ' 族 / ' + payload.totalMembers + ' 成员');
|
||||
}
|
||||
|
||||
/* ---- 产物 2：79 份契约注入 ---- */
|
||||
const touched = [];
|
||||
for (const slug of Object.keys(entries).sort()) {
|
||||
const file = path.join(COMPONENTS, slug + '.json');
|
||||
if (!fs.existsSync(file)) {
|
||||
problems.push('找不到契约 ' + slug + '.json');
|
||||
continue;
|
||||
}
|
||||
const raw = fs.readFileSync(file, 'utf8');
|
||||
const { text: stripped, had } = stripFamily(raw);
|
||||
const anchor = ` "slug": ${JSON.stringify(slug)},\n`;
|
||||
if (!stripped.includes(anchor)) {
|
||||
problems.push(slug + '.json 缺少锚点行 ' + JSON.stringify(anchor.trim()) + '，跳过注入');
|
||||
continue;
|
||||
}
|
||||
const next = stripped.replace(anchor, anchor + familyLines(entries[slug]));
|
||||
let parsed;
|
||||
try {
|
||||
parsed = JSON.parse(next);
|
||||
} catch (e) {
|
||||
problems.push(slug + '.json 注入后 JSON 解析失败: ' + e.message);
|
||||
continue;
|
||||
}
|
||||
if (parsed.family !== entries[slug].family) {
|
||||
problems.push(slug + '.json 注入结果字段不符');
|
||||
continue;
|
||||
}
|
||||
if (next === raw && had) {
|
||||
unchanged++;
|
||||
continue;
|
||||
}
|
||||
if (MODE === 'check') {
|
||||
problems.push(slug + '.json 族字段缺失或过期');
|
||||
continue;
|
||||
}
|
||||
if (MODE === 'dry') {
|
||||
touched.push(slug);
|
||||
continue;
|
||||
}
|
||||
writeAtomic(file, next);
|
||||
touched.push(slug);
|
||||
}
|
||||
|
||||
if (touched.length) changed = touched.length;
|
||||
|
||||
console.log(
|
||||
`\n${MODE === 'check' ? '[check]' : MODE === 'dry' ? '[dry-run]' : '[write]'} ` +
|
||||
`族 ${FAMILIES.length} / 登记成员 ${payload.totalMembers} / 契约改动 ${changed} / 已最新 ${unchanged}`
|
||||
);
|
||||
if (touched.length) console.log(' 改动契约：' + touched.join(' '));
|
||||
const rest = index.components.filter((c) => !entries[c.slug]);
|
||||
console.log(` 独立组件（不属任何族）：${rest.length} 个 — ${rest.map((c) => c.slug).slice(0, 12).join(' ')}${rest.length > 12 ? ' …' : ''}`);
|
||||
|
||||
if (problems.length) {
|
||||
console.error('\nFAIL:');
|
||||
for (const p of problems) console.error(' - ' + p);
|
||||
process.exit(1);
|
||||
}
|
||||
console.log('\nOK: 族层数据一致');
|
||||
}
|
||||
|
||||
main();
|
||||
Reference in New Issue
Block a user