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 个 —— 历史从未跟踪且属构建产物，保持现状。

CHANGELOG.md

@@ -4,6 +4,100 @@
 
 ## [Unreleased]
 
+### Design system · 组件族参数化：79 个并列组件 → 48 个概念组件（S6-P21）
+
+- **问题**：79 个并列组件里有 44 个是同源变体，却各自手写了一遍。导航最典型——`topmenu` / `sidemenu` / `mixednavigation` 三份实现，差异只是"一级菜单横排还是竖排"；规范契约自己就写着从属关系：`alertmodal` 与 `confirmmodal` 的 `doNotInvent` 原文是「弹窗尺寸档位（见 Modal 契约）」，`steps` 与 `steplist` 的 `semanticTypeCandidates` 完全相同（均为 `steps|wizard`）。并列表达让消费方看到 6 个表格组件，而它们实际是「一个 Table + 一个 feature 参数」。
+- **新增族层（纯追加，不破坏任何既有承诺）**：新增 `.design_library/aurora-admin/families.json`；`data.json` 增顶层 `families` 与每组件 `family` / `familyRole` / `familyParams`；`site/details/<slug>.json` 同步三元组。**13 族 / 44 成员 / 35 个独立组件；`data.json` 仍完整输出 79 个组件，slug 集合逐一不变**（铁律 5）。
+- **归族判据可核对，不按名字猜**：每族在 `tools/lib/family-model.mjs` 里必写 `mergeBasis`，依据是契约中四类可核对字段——`semanticTypeCandidates` 重叠、`anatomy` 为同一骨架的子集、变体维度同构、`doNotInvent` 的显式从属声明。
+- **实现层合并（导航族端到端切片）**：`tools/gen-family-impl.mjs` 从 `tools/lib/family-impl/nav-menu/` 的 5 端模板生成 `TopMenu` / `SideMenu` / `MixedNavigation` 共 15 个文件，参数为 `direction=top|side|mixed`。三份 CSS 的 **md5 完全相同**——一份样式表服务三个组件；改模板 + 重跑即三端同步，不再存在"改了 topmenu 忘了 sidemenu"。
+- **为什么是「生成」而不是「抽共享模块」**：`tools/pack-deploy.mjs`（薄壳 79 / 实现 395）、`tools/precompute.mjs`（79 / 395）、`tools/verify-cross-platform.mjs`、`tools/verify-package-import.mjs` 四处硬断言文件数与导出数。抽跨文件 import 会同时打破它们，并失去"单文件可拷贝"。生成把重复消除在源头，而不改动文件图。
+- **生成器护栏**：目标文件有未提交改动、且不含生成物标记时拒绝覆盖（除非 `--force`）——防止把工作区里没提交的手工调整冲掉。
+- **跨端口径（两个数必须分开说，免得把自己的改动说大成整体改善）**：已提交 HEAD 为 `identical 2 / differing 77 / high 44`；本任务改动前的工作区已是 `79/79`（既有未提交改动先清了跨端漂移）；本任务改造后仍为 **`identical 79 / differing 0`，与工作区持平**。中途曾掉到 76/79：族模板最初把方向写成对象字面量 `{ direction: 'side' }`，Vue 端 class 提取器会把其中的字符串值收作变体记号、H5/JSX 端不会。探针实验确认成因后改用独立常量 `FAMILY_DIRECTION` 承载方向，四端回到 79/79——是改代码对齐既有约定，未放宽校验脚本。提取器本身的不对称仍未修，已登记 ROADMAP S6-P22。
+- **顺带修掉一处既有 RTL 不一致**：`MixedNavigation.css` 原文件同时写 `border-inline-start` 与 `border-left-color`（逻辑属性与物理属性混用，RTL 下两侧指示条表现不一致）；族模板统一为逻辑属性。
+- **验收**：族层 `node tools/verify-families.mjs` → `OK: 族层端到端一致（13 族 / 44 成员 / 79 组件不变 / 395 文件不变）`，退出码 0；`node tools/gen-family-impl.mjs --only=nav-menu` 幂等（重跑 0 写入）；回归 100%（79/79 页，1017/1017 断言，N/A 34）**连跑 8 次一致、0 超时**；零运行时依赖不变（`dependencies` 为空）。
+
+### Package · 发布到私有 npm 源（可直接 npm install）
+
+- **发布位置**：自建 Gitea 的 npm registry `https://gitea.mymoyu.top/api/packages/root/npm/`（Gitea 27.3.1），**匿名可读**——实测无凭据 `npm view` / `npm install` 均成功。
+- **已发布 3 个可互换的包名**（内容一致：三端入口各 79 组件 + 令牌 + 组件样式）：
+
+  | 包名 | 用途 |
+  |---|---|
+  | `@root/ui` | **推荐**：scoped 名，项目 `.npmrc` 写一行 `@root:registry=…` 即可，其余依赖仍走公共源 |
+  | `chunyu-ui` | 非 scoped 别名，需 `--registry=` 显式指定源 |
+  | `aurora-admin-design` | 仓库原名，同上 |
+
+- **踩到的坑（已写进 README）**：非 scoped 包**不能**用 `@包名:registry=` 写法——该语法只对 scoped 名生效，实测报 404。故推荐 scoped 名 + 一行 `.npmrc`。
+- **端到端验证**：建 Vite + Vue 3 工程，`.npmrc` 一行配置 + `npm install @root/ui`（公共依赖同时走公共源）→ `vite build` 通过（169 模块）→ 浏览器实测：`AaButton` 渲染、品牌色 `rgb(47, 84, 235)` 生效、`AaTag` 正常、点击计数交互正常、0 JS 报错。
+- **未发布到公共 npm**：本机无 npm 凭据（`npm whoami` → `ENEEDAUTH`，无 `~/.npmrc`、无 token 环境变量），`npm publish` 到 registry.npmjs.org 被拒。公共 npm 上 `chunyu-ui` / `aurora-admin-design` 均未被占用（可用），是否发布待定。
+- README 增补「从私有 npm 源安装」段（含正确的 `.npmrc` 写法与三端 import 示例）。
+
+### Docs site · 导航语言选择改为下拉（S5-P19）
+
+- **问题**：顶栏语言控件是「中 / EN」双段按钮——11px 圆角、28px 高、靠 2px 字号差和品牌色表示当前语言。两个语言标签同时高亮显示，当前语言靠粗细区分，一是看不出「点了会怎样」（无展开暗示），二是与旁边 34px 的框架选择器、搜索框不同高，三是纯鼠标控件：没有 `aria-haspopup`、没有键盘路径。
+- **改为下拉选择**：触发器 = 地球图标 + 当前语言名（简体中文 / English）+ 箭头，34px 高与相邻控件齐平，展开时箭头旋转 180°、边框转品牌色并带聚焦环；菜单 186px 卡片，含「界面语言」标题分隔线、语言名 + `ZH`/`EN` 角标 + 选中对勾，8px 顶栏令牌阴影。
+- **交互与无障碍**：`role="listbox"` + `aria-selected` + `aria-expanded`；点击展开/收起、点击外部关闭、`Esc` 关闭并回焦触发器、`↑`/`↓` 循环移动、`Home`/`End` 跳首尾、`Enter`/`Space` 选中、`Tab` 关闭且不抢焦点；选中后触发器重新获得焦点。语言名始终以该语言自身书写（简体中文 / English），不随界面语言翻译。
+- **令牌与暗色**：颜色/圆角/阴影全部走 `--au-*` 令牌，未新增任何硬编码色值；暗色模式实测菜单底色 `rgb(28,31,38)`，选中项对比度 4.57、菜单标题 6.50、触发器 4.57（均 ≥ 4.5）。`prefers-reduced-motion: reduce` 下关闭菜单动画与箭头过渡。
+- **窄屏**：≤1100px 收起语言名（触发器 56px，与旧控件同宽）。实测改动前顶栏在 1024px 溢出 13px、900px 溢出 9px（旧控件同样外露），现 ≥860px 全部为 0；≤820px 的溢出与语言控件无关，已登记为 ROADMAP S5-P20。
+- **i18n**：新增 `界面语言` / `选择语言` 两条，移除随之作废的 `切换到简体中文` / `切换到英语`（原按钮的 aria-label），一进一出净增 0 条。
+- **验收适配**（验收命令本身随控件形态更新，判据强度不变）：`tools/verify-i18n.mjs` 的两条静态检查改指新 id/绑定，并新增「旧控件不得残留」检查；`tools/run-site-smoke.mjs` 的点击路径改为「开菜单 → 选项」，并补 8 条下拉行为断言（`aria-expanded`、Esc、方向键、焦点回位、选中态、触发器文案）。
+- 回归 100%（79/79 页，1017/1017 断言，N/A 34），连跑 8 次一致；`smoke:site` 30/30；`verify:i18n` 16/16；`verify:theme`、`verify-dark`、`verify-site-routing` 全过；零运行时依赖不变。
+
+### Package · 三端可 import（组件库真正可用）
+
+- **问题**：`dist/` 只发 CSS 与演示 HTML，`package.json` 的 `main` 甚至指向一个 CSS 文件，**没有任何可 import 的组件**——`import { AaButton } from 'aurora-admin-design/vue3'` 这类标准用法不成立。S1-P2 的任务范围写的是「能拿到令牌 + 组件样式」，因此这是**范围缺口**而非实现错误（已按 AGENTS 第五节登记为 ROADMAP S5-P18）。
+- **新增三端聚合入口**：`dist/react/index.js`、`dist/vue3/index.js`、`dist/vue2/index.js`（各导出 79 个 `Aa*` 组件）+ 单组件源码。组件以 `.vue` / `.jsx` 源码发布，由宿主构建链编译（无额外编译产物与源码不同步的风险，且保持零构建依赖）。
+- **`package.json`**：补 `exports` 映射（`.` / `./tokens.css` / `./components/*` / `./react` / `./vue3` / `./vue2` / `./manifest.json`）与 `peerDependencies`（`react >=17`、`vue >=2.6`，均为 optional）。
+- **修掉两个「组件无法编译」的真实缺陷**（此前从未被发现，因为从未真编译过）：
+  - `RangeQuickPicker` 的 `presetRange` 给 `const start` / `const end` 重新赋值 → **React 与 Vue 3 两端都无法编译**；已改为 `let` 并与 Vue 2 参照实现对齐（`start` 改为 `new Date(...)` 而非 `setMonth/setDate` 就地修改，行为一致）。
+  - `CodeInput.vue3.vue` 内 `function emit()` 遮蔽了 `const emit = defineEmits(...)` → 重复声明，编译失败；已重命名为 `emitChange()`。
+- **样式随包发布**：56 个组件的 Vue 两端用 `<style src="./<Prefix>.css">` 引用外部样式、79 个 JSX 用 `import './<Prefix>.css'`。打包时把同名 CSS 一并放入 `dist/react|vue3|vue2/`，否则会出现「import 成功但样式全丢」。断链检查已纳入验证脚本。
+- **新增 `tools/verify-package-import.mjs`**：结构级（入口/断链/exports/零依赖，15 项，零依赖可跑）+ 编译级（esbuild + `@vue/compiler-sfc` 真编译 79 个 SFC、vue/react SSR 真渲染 `AaButton` 断言 DOM，5 项）。编译级依赖可用 `AA_VERIFY_DEPS_DIR` 指向隔离目录，避免污染仓库 `node_modules`。
+- **端到端验证（真实工程，非模拟）**：分别建 Vite + Vue 3 与 Vite + React 工程，以 `file:` 依赖真实 `npm install` 本包，只写 README 里的那几行 `import` → `vite build` 通过（Vue 170 模块 / React 189 模块），浏览器实测：组件真渲染、品牌色 `rgb(47, 84, 235)` 生效（证明令牌与样式链正确）、`loading` 态 `disabled` 与 spinner 正确、点击交互正常、0 JS 报错。
+- 回归 100%（79/79 页，1017/1017 断言，N/A 34）；S1-P2 原始验收命令（tokens/aggregate/79+index/zero-dep/css usable/pack contents）全部仍通过。
+
+### Docs site · 组件详情页代码块默认展开（含修复异步填充漏填）
+
+- 组件详情页源码区改为**默认展开**：`demo-strip` 初始态由折叠改为展开，进页面即可看到当前框架源码，省掉一次点击；展开条箭头与提示文案随状态同步（▲ 收起代码 / ▼ 展开代码）。
+- **修复既有缺陷（默认展开后被放大）**：源码异步加载后的填充回调**签名错位**——`listenSrc(slug + '/' + kind, fillCode)` 直接传函数，而 `notifySrc` 的回调签名是 `(text, error)`，于是源码文本被当成 `kind` 与 `'html'` 比对，永远不相等，**首次展开的代码区一片空白**（实测全新加载展开后字符数 0，离开组件再回来才有内容）。已改为闭包绑定 `kind`；并新增 `codeWrap.__fillCurrent()`，在代码区插入 DOM 后补填一次（命中内存缓存时源码是同步取得的，插入前填充会被 `isConnected` 守卫跳过）。
+- 浏览器实测（本地 dev-server）：首次进详情页即展开且有内容（cascader 7713 字符）、切到未访问组件自动填充（tree 5159 字符）、切 CSS tab 正常（1067 字符）、折叠再展开内容保留、0 JS 报错。
+- 回归 100%（79/79 页，1017/1017 断言，N/A 34），文档站冒烟 ×2 全过。注：当日连跑 27 次中 2 次出现 1016/1017 的偶发失败，`tests/*.html` 不加载 `site/app.js`（grep 计数 0），与本改动无关；因 `tests/report.json` 不记录是哪条断言失败，已立任务包 S5-P17 追踪可追溯性。
+- **顺带修掉「部署了但浏览器还在跑旧版」**：`nginx.conf` 之前没有任何 `Cache-Control`，浏览器对 `app.js` 走启发式缓存——实测重新部署后页面仍执行旧 `app.js`（同一页面内 `fetch` 能取到新版、`<script src="app.js">` 却用缓存，`duration=0`）。已在 server 级统一加 `add_header Cache-Control "no-cache" always;`：每次带 `If-None-Match` 重新校验，未变更返回 304（实测 app.js 带 ETag 请求 → 304），开销极小但部署立即生效。
+
+### Security · 生产部署链审计修复（2026-09-19）
+
+- **规范原文泄漏（根因）**：`.dockerignore` 里 `*.md` / `*.ps1` / `*.yml` / `*.png` 等 glob 在 Docker 下**只匹配构建上下文根目录**，嵌套路径全部失效（真实构建实证：`sub/nested.md` 仍进镜像）。改为 `**/` 前缀并补齐嵌套 glob；`.design_library/aurora-admin/{specs,agent-reports,preview,ui_kits}` 与嵌套 `*.md` 实测不再进入镜像（修复前线上 `GET /.design_library/aurora-admin/specs/组件1.txt` → 200 / 8623B）。
+- **`nginx.conf` 加固**：补 `absolute_redirect off;`（根路径 302 曾丢失宿主端口 `:3311` 落到无服务的 :80）、`server_tokens off;`、与 `site/dev-server.js` 逐字一致的 CSP 及 `X-Content-Type-Options` / `Referrer-Policy` / `Permissions-Policy` / `X-Frame-Options`；`/healthz` 改用 `default_type` 修掉重复 `Content-Type`。
+- **`Dockerfile`**：补 `COPY sitemap.xml`（修复前生产 `/sitemap.xml` → 404）。
+- **`site/dev-server.js`**：修复单个 `GET /site/%00` 触发 `ERR_INVALID_ARG_VALUE` 未捕获异常打挂进程的问题——新增编码形态与解码后 NUL 双重拦截、`fs.readFile` try/catch；白名单、安全头、302/404 行为保持（92 条合法路径 status / content-type / 字节级一致）。新增 `AA_PORT` 开关（默认仍 3311）供验证脚本隔离端口。
+- **消除动态求值 sink**：`site/app.js` 与 `tools/precompute.mjs` 原先把 `defineEmits([...])` 字面量交给函数构造器求值（实测 `defineEmits([1,globalThis.__pwned='x'])` 会真的执行；构建期同源 → 可打穿 CI）。改为只解析字符串字面量的 `parseStringLiteralArray`（构建期实现独立成 `tools/lib/parse-string-literal-array.mjs`），非字面量元素整体拒绝返回 null。等价性：158 个 `frameworks/*.vue` 双实现抽取结果不一致 0（54 处字面量 / 96 条事件名）。
+- 新增验证脚本 `tools/verify-dev-server.mjs`（20 checks，含 3 条修复前必失败的反例断言）与 `tools/verify-emits-parse.mjs`（17 checks，含构建期副本漂移门）。
+- ⚠️ **规划修正**：`PLAN.md` §8「不改 `site/dev-server.js`（已工作良好）」的立论已被实测推翻，按 AGENTS.md 第五节「以实测为准」处理并在此标注。
+- 回归：100%（79/79 页，1017/1017 断言，N/A 34），连跑 9 次一致，0 超时；主 agent 另独立复跑 1 次亦 100%。
+
+### Deploy · 线上部署（2026-09-19）
+
+- 新增 `tools/pack-deploy.mjs`：以 `.dockerignore` 为**唯一真源**打包部署目录（实现 Docker 的匹配语义，含「`*.md` 只匹配根目录」这一实测结论），带硬断言（规范原文/agent-reports/preview/ui_kits 绝不出现；站点运行必需文件必须出现；薄壳 79、实现文件 395）。部署配置文件（`docker-compose.yml` 等）始终保留——`.dockerignore` 只管镜像构建上下文。
+- 按 AGENTS §九 流程首次实际部署到 `192.168.5.7`：备份 → 解到暂存目录核对 → 替换 → `docker compose build && up -d`（回滚目录 `/opt/aurora-admin.pre-audit-20260919-0609`）。
+- 部署后验收：`specs/组件1.txt`、`agent-reports/*`、嵌套 `SKILL.md`/`README.md` → **404**；`sitemap.xml` → 200；`tests/report.json` → 200（首页通过率角标恢复数据源）；根路径 302 → `Location: /site/`（相对，不再丢端口）；`Server: nginx` 无版本号；CSP 等 5 条安全头齐备且 `/healthz` 只 1 条 `Content-Type`；**396/396 条 sitemap URL 全部 200**；容器 `healthy`。
+- 顺带消除历史漂移：线上组件文件由 09-06 快照更新为当前工作树（此前后者与线上有 288 个文件不一致）。
+- 决策：**暂不对外公用** —— 保持 `127.0.0.1:3311` 回环访问（需 SSH 隧道），不加反代/域名/认证；容器运行期加固与对外承诺口径统一另立任务包（ROADMAP S5-P14/P15/P16）。
+
+### Theme modes · 日间 / 夜间 / 自动
+- 文档站主题选择扩展为 `light` / `dark` / `auto` 三态；自动模式跟随 `prefers-color-scheme` 并监听系统主题变化。
+- 新增可访问的主题模式菜单、跨标签页 `aa-mode` 同步和 iframe 主题同步。
+- ThemeSwitcher H5 / React / Vue 2 / Vue 3 统一 `auto` 模式枚举与 ARIA 语义。
+
+### Fixed — 文档站中英切换完整性
+- 修复语言切换后相关组件、主题面板、搜索分类与详情目录仍显示初始语言的问题。
+- 补齐加载态、重试、契约详情等动态文案的英文词典覆盖，并为顶栏切换器补充无障碍名称与状态。
+- 新增 `tools/verify-i18n.mjs` 静态校验与 `tools/run-site-smoke.mjs` 浏览器冒烟测试。
+
+### S3-P9 · 契约缺口解释层
+- 为 Card 契约的 `doNotInvent` / `unknowns` 增加结构化解释：分别说明设计边界、开放问题、出现原因与待确认决策。
+- 组件详情页明确区分“不要自行发明（设计边界）”与“规范未明示（待确认）”，不把现有实现值冒充正式规范。
+- 保持 hover 行为与卡片网格间距待定，未擅自写入 16px/24px 或固定状态规则。
+
 ### S2-P7 · 行为断言（6 试点全绿）
 - 新增 `tests/_behaviors.js`：8 动词（click-toggles-class/click-adds-node/click-removes-node/click-sets-attr/input-clears/input-filters/keyboard-activates/tab-switches）+ `@input` 相对定位 + `@doc` 全文档查询 + 同步 pump + page-load 幂等缓存；`_runtime.js` 聚合 + 重载清缓存；`_template.html` 引入；6 演示页 `data-behavior` 标注；79 测试页重生成。
 - 全量回归：100%（79/79 页，1009/1009 断言，N/A 35）。关键修复：runner 兜底重跑导致行为断言第二轮误报，加缓存解决。