项目：html5-examples ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
这是文档集的最后一篇，回答三个"用得着"的问题：这个词到底指什么（术语表，含跨篇用词的统一口径）、这段代码在哪些篇里被讲过（源码文件与篇目的反向索引）、我现在要做某件事该按什么顺序读（按任务的阅读路径）。前三篇式的"机制讲解"到此收束，本篇是查用型工具篇——它的成功标准不是通读酣畅，而是你在任意一篇里迷路时能从这里三步内找回坐标。
关于术语的口径先说一句总原则：本项目源码注释里的用词与 AGENTS.md 的产品词汇表并非处处一致（如 catalog.ts 注释称"64 项子生成器"而实际条目数在 52-66 间漂移，见《13-技术债务》第 3 条），本术语表以文档集内部一致为准绳，个别词条给出了"源码写法 / 建议口径"的双轨表述。术语定义尽量给出首次出现的篇目，那里有最完整的语境。
这一组术语回答"站上的内容到底有几种存在方式"。它的背景是：内容板块在三次拆分（见《00-项目总览》§4）之后收敛为四类形态，每类都有独立的加载与渲染链路，混用称呼会让扩展工作落错文件——比如说"加个示例"而实际需求是 SFC 演示，就会照 SOP-A 改 JSON 却发现根本走不到 iframe 沙箱。下表给出标准口径与出处，其中"四种示例形态"是全文档集的骨架概念，先读懂它再读任何机制篇目都会顺一半。
| 术语 | 定义 | 首详篇目 |
|---|---|---|
| 四种示例形态 | JSON 示例 / SFC 演示 / CSS 生成器 / 配置型数据（动效、模板、SVG 课程）——各自独立的"注册处+加载机制+渲染机制"三位一体契约 | 《01》§2.1 |
| JSON 示例 | 存于 src/content/examples/*.json 的 CodeExample 条目，经 buildSrcDoc 进入 iframe 沙箱渲染，是馆藏主体 | 《03》§3.1 |
| SFC 演示 | src/components/examples/demos/ 下的 73 个自包含 Vue 组件，defineAsyncComponent 页面内渲染（非沙箱，可用真实浏览器 API） | 《11》场景三 |
| 生成器 | CSS 实验室里"调参数产出 CSS"的工具组件，共享 BaseGenerator 骨架与 gen-:kind 动态路由 | 《07》§2 |
| 工作台 | 不走 BaseGenerator 的三个特殊工具页（Flex/Grid/渐变），独立页面 + 页面级 store | 《05》流程五 |
| sourceGroup | 示例二级分组 slug，治理产物（把混乱的 categorySlug 归并为 8 个标准分组）；文件名即分组值 | 《04》§2.3、§3 |
| 卡片墙 | CssGeneratorRouter 的默认 Tab：展示某 kind 的样式变体，可"应用到生成器"回填参数 | 《07》§2.3 |
| 姊妹项目 | 2026 年从本项目拆出的 html5-dataviz（图表）、html5-games（游戏）、devtools（工具箱）；拆分模式为"前端先行、后端滞后清理、旧路径留 redirect" | 《00》§4 |
这一组术语围绕"内容如何安全地跑在用户浏览器里"。核心词只有两个——srcdoc 与 sandbox 属性——但衍生概念（舞台容器、代码快照、可视区懒渲染）都是围绕"隔离要花钱"这个事实展开的：隔离越彻底，每个预览的内存与加载成本越高，于是项目发明了一整套"只让正在看的那个示例付费"的机制。理解了这个动机，下面每个词条就不再是孤立的技术点，而是同一笔账的不同还法。
| 术语 | 定义 | 首详篇目 |
|---|---|---|
| 沙箱内核 | src/utils/sandbox.ts 的 buildSrcDoc/needsSameOrigin/getSandboxAttributes 三函数构成的渲染接合面 | 《07》§1.1 |
| srcdoc | iframe 的内联文档属性；示例渲染的唯一通道，每个预览是一个完整文档实例 | 《16》ADR-03 |
| example-stage | html5 主题示例的舞台容器（flex 居中、100vh），补偿导入期被清洗的 body 布局样式 | 《18》§1.2 |
| 代码快照 | ExampleCodeSnapshot.vue：列表卡片渲染源码前 12 行（Shiki + 渐隐 mask），替代 iframe 预览以避免千卡千 iframe | 《10》§2 |
| 可视区懒渲染 | PreviewPane 用 IntersectionObserver 在示例进入视口才创建 iframe | 《10》§2 |
| 变体（snippet） | DemoSnippet { label, css?, html?, js? }：css/js 追加、html 整体替换的非对称合并语义 | 《18》§1.1 |
| chunk 失效自愈 | router.onError 捕获动态 import 失败后整页 reload（标志位防连环刷新）；只覆盖路由级懒加载 | 《16》ADR-10 |
| manualChunks | vite.config.ts 的 19 组拆包规则，设计总纲"每个示例只下载自己的库" | 《14》§1.4 |
这一组是文档集与源码注释里最高频出现的"行话"，也是新人最容易被卡住的地方——它们大多是项目自造的复合词（如"两行登记""懒加载双锁"），在通用技术语境里查不到。每个词条的定义都刻意写成"一句话可执行"的粒度：看到词就能想起它落在哪个文件、约束什么行为。若需要完整机制叙述，跟随"首详篇目"列跳转即可。
| 术语 | 定义 | 首详篇目 |
|---|---|---|
| 内容在前端、行为在后端 | 数据域切分总纲：内容域走 git JSON、目录域走 PostgreSQL、行为域走运行时 API | 《00》§1.2、《04》§1 |
| 三分法 | 上条的三域划分及其衍生的备份/回滚/灰度策略差异 | 《04》§1 |
| 冻结资产 | 前端零消费但仍在注册运行的后端模块（examples/chart-examples/visual-demos/knowledge/oss/run）；正确态度是"不删不加，待专项清理" | 《13》第 2 条 |
| 懒加载双锁 | cache + loadingPromise 双变量的模块级单例加载（失败置空允许重试），api/examples.ts 与 highlighter.ts 同款 | 《16》ADR-01 |
| last-request-wins | useResourceFetch 的竞态保护：requestId 序号快照 + AbortController 双保险，三个出口全比对 | 《18》§2 |
| URL 即状态 | 筛选状态镜像到 URL query（replaceState），刷新/分享不丢；单向写、不回读防回环 | 《18》§3 |
| KeepAlive 白名单 | 路由 meta.keepAliveComponent 声明式登记缓存页，App.vue 动态收集 | 《02》§1.1 |
| 覆盖层 | localStorage 键 examples-overrides-v1：详情页"保存"只写 html/css/js 三字段的本机临时编辑，刷新仍生效、清缓存即还原、永不回流 JSON | 《16》ADR-12 |
| 稳定序 | loadAll 的排序规则：数字 id 升序在前、非数字 id 按 title 中文 locale 排后——保证分页跨页不重不漏 | 《05》流程一 |
| 两行登记 | 新增生成器的边际成本：generatorComponents 一行 kind 映射 + catalog 一条 ToolItem，路由零改动 | 《11》场景二 |
| toolPath / TOOL_ROUTE_PATHS | 路由路径单一事实源（src/config/css-lab/routes.ts）：catalog 的 link 必须由此派生，缺键即类型错误 | 《07》§2.1 |
| 模块级单例 | 状态定义在模块顶层而非函数/组件内（如 useFavorites 的 favorites Set），等效全局 store 而不进 Pinia | 《05》流程四 |
这一组术语横跨前后端，最需要统一口径的原因是同一件事在两侧的叫法不同：后端源码说 refreshAccessToken（旋转），前端源码说 refreshAuth（静默刷新），文档里统称"刷新链路"；后端说"宽容模式守卫"，前端对应物是"401 全局处理器"，两者其实是同一条失败路径的两岸。下表词条以文档集用语为准，源码函数名在定义里注明。
| 术语 | 定义 | 首详篇目 |
|---|---|---|
| AuthResult | 登录/注册/刷新统一的返回结构：{ accessToken, refreshToken, expiresIn, user } | 《19》§2 |
| 双 token | access token（JWT）+ refresh token（64 字节随机 hex 落库、可吊销、一次性旋转） | 《16》ADR-11 |
| 旋转与重用检测 | refreshAccessToken 的安全机制：旧 token 用后即吊销；已吊销 token 再用即判泄露并全量吊销该用户令牌 | 《19》§3 |
| 提前 5 分钟刷新 | authStore 的 REFRESH_AHEAD_SECONDS = 300：模块级定时器在过期前静默换新；恢复会话后必须重挂 | 《08》§2.2 |
| 宽容模式守卫 | 全局 JwtAuthGuard 特判：完全无凭证放行且 req.user 为 undefined，有凭证但无效才 401 | 《08》§3 |
| 双通道鉴权 | Bearer 优先、auth-token httpOnly cookie 兜底的凭证传输设计（前端 client.ts 与后端 jwt.strategy 对称实现） | 《08》§2.1 |
| DTO 即契约 | 全局 ValidationPipe（whitelist + forbidNonWhitelisted + transform）：未声明字段直接 400 并返回字段级 message 数组 | 《19》§8 |
| 分页钳制 | clampPage/clampLimit 把非法分页参数静默回退并钳上限——"列表接口永远给出可用结果" | 《03》§7 |
| 乐观更新 | useFavorites 先发请求、成功后才改本地状态并 toast；失败状态不变 | 《05》流程四 |
| 依赖注入式 HTTP 客户端 | client.ts 经 setAuthTokenProvider/setAuthFailureHandler 两注入点解耦 authStore（依赖反转，避免循环 import） | 《03》§4 |
有三组词最容易在阅读与沟通中串味，单独辨析。"示例"一词的三种所指：日常说"加一个示例"多指 JSON 示例（SOP-A）；SFC 演示在源码里也叫 demo/演示（PlaygroundPage 的演示清单）；而"示例数据"有时泛指整个内容域。书面沟通建议用全称（JSON 示例 / SFC 演示），本术语表 1.1 节的四个形态名即为标准口径。"工具"与"生成器"：catalog.ts 的类型是 ToolItem、注释常写"工具"（历史沿袭——板块曾叫 /tools 工具箱），拆分后站内只剩 CSS 工具，产品词汇表要求叫"CSS 实验室"，条目层面"生成器"指 gen-* 组件、"工作台"指三个独立页面、"速查表"指 cheatsheet，三者注册路径不同（见《15》§3.2 的例外注）。"收藏"的两套实现：示例收藏（favorites 模块，走后端）与知识库文档收藏（knowledge/favorites，冻结）同名不同物；前端 useFavorites 专指前者，含模块级状态与 clearFavorites 登出隔离语义，后者在本文档集一律带"knowledge 前缀"表述。
按"拿到一个文件名，该读哪几篇"组织。约定：★ 表示该篇对此文件有逐段走读或逐函数讲解；○ 表示有机制概括；△ 表示仅在使用说明中提及。
| 源码文件 | ★走读 | ○机制 | △提及 |
|---|---|---|---|
src/utils/sandbox.ts | 《18》§1、《07》§1.1 | 《01》§6、《08》§1、《03》§3.2 | 《16》ADR-03/04/05 |
src/composables/useResourceFetch.ts | 《18》§2、《07》§1.4 | 《01》§5 | 《10》§5 |
src/composables/useListFilter.ts | 《18》§3、《07》§1.5 | 《02》§2.2 | 《09》§1.1（单测） |
src/views/css-lab/css/generators/BaseGenerator.vue | 《18》§4.1、《07》§2.4 | 《05》流程五 | 《11》场景二 |
src/views/css-lab/css/generators/RgbaColorGenerator.vue | 《18》§4.2 | — | 《19》§10 |
src/api/examples.ts | 《07》§1.2 | 《01》§2.2、《03》§3.3、《04》§3 | 《16》ADR-01/02/12 |
src/api/client.ts | 《07》§1.3 | 《03》§4、《15》§2.1 | 《09》§1.1 |
src/stores/authStore.ts | 《05》流程三 | 《08》§2、《15》§2.2 | 《12》§1 |
src/router/index.ts | 《02》§1.1 | 《01》§5（自愈）、《10》§4 | 《06》§3.2 |
src/views/ExamplesLibraryPage.vue | 《02》§2.2 | 《05》流程一 | 《01》§5（URL 即状态） |
src/views/css-lab/css/CssGeneratorRouter.vue | 《07》§2.3 | 《05》流程五 | 《11》场景二 |
src/config/css-lab/catalog.ts | 《07》§2.1 | 《04》§2.5、《13》第 3 条 | 《19》§10 |
src/content/examples/*.json | 《04》§3 | 《03》§3.1、《19》§9 | 《11》场景一/六 |
src/types/index.ts / types/tool.ts | 《04》§2 | 《03》§3.1 | 《15》§3.3 |
src/composables/usePreview.ts | 《07》§1.6 | 《01》§6、《10》§2 | — |
src/utils/highlighter.ts | 《07》§1.6（概述） | 《01》§7、《10》§3.2 | 《16》ADR-5（AGENTS 口径） |
src/utils/sfcRuntime.ts | 《01》§7 | 《10》§3.2、《17》§2.1 | — |
vite.config.ts | 《14》§1（逐段） | 《10》§3、《06》§3.1 | 《17》§2.4 |
server/src/main.ts | 《07》§3.1、《14》§2 | 《08》§5、《06》§2.2 | 《19》§0 |
server/src/modules/auth/** | 《07》§3.2 | 《08》§2、《19》§1-5 | 《13》第 6 条 |
server/src/modules/favorites/** | 《07》§3.3 | 《19》§6 | 《05》流程四 |
server/src/modules/examples/** | 《07》§3.5 | 《15》§1.4 | 《13》第 2 条 |
server/src/app.module.ts | 《07》§3.1 | 《01》§3、《04》§4 | 《13》第 5 条 |
package.json（根/server） | 《14》§4 | 《17》全篇 | 《06》§4 |
AGENTS.md / README.md | — | 《13》第 1 条（漂移登记） | 《00》§8 |
这张表的用法：改一个文件前，先扫它所在行的"★走读"列——那是最接近原文的讲解，能告诉你改动会落在哪些机制的交界处；review 别人的 PR 时同理。反过来说，若某文件你常改却在本表查不到（比如 src/views/PlaygroundPage.vue 只在《11》场景三出现），说明文档集对它的覆盖还是"操作级"而非"机制级"，照 AGENTS.md 第 15 节回写清单补篇即可。
表的维护规则有两条，都与"文档集怎么才不会腐烂"有关。其一，行随文件走而不是随功能走：新增文件时先判断它属于哪条机制链（数据加载、渲染沙箱、认证……），把链条上已有的篇目填进后两列，而不是新开一行只写"见某篇"——链条视角能暴露"新文件改动了老机制"这种最危险的变更。其二，星级诚实：○ 与 △ 的区别是"读过原文后能否只凭该篇定位到函数"，拿不准就降级为 △；虚高的星级会让人跳过原文，违背这套索引存在的意义。此外提醒一处刻意的省略：node_modules、dist、备份/、gui-test-screenshots/、public/ 的静态资源不在索引范围——前三者非源码，后两者是内容资产，其治理规则分别在《00》§5 与《04》§4.1。
五条路径覆盖维护者的五类高频任务，每条都按"最小路径（只读必需的，直接动手）— 展开路径（机制依据与易错点）— 验证清单"三段组织。路径的设计原则是动手所需的知识不与理解所需的知识混编：最小路径刻意只给操作文档（SOP），机制与决策篇目放在展开层——急于交付的人走最小路径不会迷路，想弄懂原理的人顺展开路径能一路读到 ADR 与走读实录。各路径共用同一个总入口约定：任何一步卡住，先查 §1 术语表确认用词，再查 §2 反向索引定位机制篇目，最后查《12-FAQ》对症状。
目标：给示例库加一条内容。最小路径（约 15 分钟）：《11》场景一 → 《06》SOP-A → 动手。展开路径：动手前补读《04》§3（JSON 结构与编辑纪律：id 永不复用、不要手动重排、tags 复用词汇）与《03》§3.1（CodeExample 字段全表）；遇到"html5 主题预览布局不对"回《18》§1.2（example-stage 机制）；遇到"改了没生效"回《12》§1（localStorage 覆盖层残留是头号嫌疑）。验证：pnpm lint && pnpm typecheck + 详情页预览/源码/设备切换三检（《11》场景一的验证清单）。
目标：给 CSS 实验室加一个"调参数抄代码"的工具。最小路径：《11》场景二 → 《18》§4（BaseGenerator 契约与最小实现范本）→ 动手，全程应为"写一个组件 + 登记两行"。展开路径：《07》§2.2-2.3 理解路由分发与卡片墙聚合（决定你的 kind 要不要进 FAMILY 族）；《19》§10 是可直接照抄的最小配置；《04》§2.5（ToolItem 十色系统与字段语义）用于选 accent 与 icon。易错点预读：TOOL_ROUTE_PATHS 缺键会类型报错（这是保护不是障碍）；类型必须从 generatorTypes.ts 导入（TS2614 陷阱，《18》§4.1）。验证：/css-lab/css/gen-xxx 直达、首页 Bento 计数 +1、侧栏可搜索、代码浮层可复制（《11》场景二验证清单）。
目标：若业务重新要求"后台即时改内容、不发版生效"，需要把内容域迁回 PostgreSQL 并恢复前端消费。路径（按依赖顺序）：《16》ADR-01/02/12 三条决策是前置认知——签名兼容承诺（ADR-02）意味着迁移只需替换 src/api/examples.ts 内部实现；《03》§5-6 是新 api 模块的编写惯例，《15》§1.4 是尚在服务的后端端点契约，《19》§8 有其报文实例；《07》§3.5 提示 examples 模块的 service 实现仍完整（含 QueryBuilder 过滤），恢复成本主要在数据回填（8 个 JSON → server/scripts/ 导入脚本族）与覆盖层语义的取舍（localStorage 覆盖要么废弃、要么升级为服务端草稿，《05》流程二的建议是后者）。决策清单：先回答"内容是否需要不发版的运行时写入"（是才迁）；迁移后 updateExample 的落点要从覆盖层改回 API；最后按《13》第 2 条的流程处理 examples 模块从"冻结"转"活跃"的登记与测试补课。⚠️ 待确认：反向迁移前应先确认 HTML5 主题 categories 表数据与 8 分组的对应关系是否仍准确（治理产物 sourceGroup 的库内覆盖度未验证）。
目标：把项目部署到生产并确认安全与完整性。路径：《06》§3（构建与两种部署形态选型）→ 《06》§7 运维检查清单（九项核对）→ 《08》§8 安全核对单（JWT_SECRET/DB_SYNC/CORS/RUN_ADMIN_TOKEN/admin 限制/cookie Secure）。展开：遇到"刷新深链 404"查《06》§6 的 SPA fallback；遇到"预览白屏"查《08》§1 的 <base> 同源约束与《12》§3；字体外链与缓存头策略见《10》§6 第 2 条；发版后的"白屏一次自愈"属正常现象（《10》§4）。一条最有用的实战建议（出自《06》§6）：本地正常、部署后异常的案例九成落在路径差异、协议网络差异、环境变量差异三点上——VITE_API_BASE_URL 是构建期注入，改 env 必须重新构建而不是重启进程。
若你是新接手的维护者，综合前四条路径的最优顺序是：第 1 天读《00》§6 跑起来 + 《01》§5（八条决策表建立全局观）；第 2 天沿《00》§8 第二站纵切面走一遍源码（列表页 → 数据层 → 沙箱）；第 3 天读《16》（12 条 ADR 把"为什么"补齐）与《13》（知道哪些是坑哪些是冻结资产）；第 4-5 天按 3.1/3.2 各做一次真实的内容提交走完整门禁。一周后你应当能独立回答三类问题：改动落在哪个域、哪篇文档讲了它、验证清单是什么。
这条路径背后有一个值得明说的学习理论：先操作、后机制、再决策。直接通读全部 21 篇的吸收率极低，因为机制描述在没有操作记忆支撑时会滑过去不留痕；反过来，先做一次真实提交（哪怕只是加一个示例），让"改了 JSON → 卡片出现 → 预览渲染"的因果链在手上过一遍，再读《07》的机制篇就会不断出现"原来当时是它在起作用"的印证感。ADR 放在第三天也是同理——决策的分量只有撞过它的后果才能体会，比如亲手经历过一次"改了示例没生效"（覆盖层残留），《16》ADR-12 的权衡取舍才会从文字变成经验。
| 篇目 | 一句话定位 |
|---|---|
| 00-项目总览 | 定位、规模、技术栈、目录导览、快速上手 |
| 01-系统架构 | 分层、四种形态、数据流、八条决策表、权衡记录 |
| 02-页面设计 | 路由总表、页面五性格、状态管理范式 |
| 03-接口设计 | 三层接口观、端点总表、契约设计意图 |
| 04-数据模型 | 三域数据、实体全表、迁移史、编辑纪律 |
| 05-核心流程 | 五条端到端流程图解 + 设计解读 |
| 06-部署运行 | 环境、构建、双部署形态、SOP、运维清单 |
| 07-模块详解 | 前端基建 + CSS 实验室 + 后端模块逐个深读 |
| 08-安全与权限 | 三层安全模型、隐患清单、加固前置条件 |
| 09-测试与质量保障 | 四道防线、测试资产、后端 CI 缺口 |
| 10-性能设计与优化 | 三个规模数字、四层性能机制、优化立项清单 |
| 11-扩展开发指南 | 六个扩展场景的展开版 SOP |
| 12-FAQ 与故障排查 | 调试入口、决策树、高频问题深挖 |
| 13-技术债务与演进建议 | 债务登记 + 三次专项路线图 |
| 14-配置与环境详解 | 配置逐段解读、环境变量全清单、姊妹项目对照 |
| 15-接口全量参考 | 端点查表手册（条目冲突以此为准） |
| 16-决策记录 ADR | 12 条关键决策的五段式考古 |
| 17-依赖全景 | 全部依赖逐个解析 + 健康度评估 |
| 18-代码走读实录 | 四处核心代码逐段带码走读 |
| 19-数据契约与示例集 | 十组核心报文实例 + 内容域契约 |
| 20-术语表与文档索引 | 本篇：术语、反向索引、任务路径 |
21 篇至此构成完整闭环：00-06 讲"是什么与怎么跑"，07-10 讲"怎么实现的"，11-15 讲"怎么扩展与查证"，16-20 讲"为什么这样设计与如何找到它们"。文档集的维护约定沿用 AGENTS.md 第 15 节的回写清单：凡源码变更触及本篇反向索引表中的行，应同步更新对应篇目；凡新增全局机制（新的 composable、新的守卫、新的存储键），先入《07》或《08》，再回本篇 §1 补词条——术语表活着，文档集才活着。
本篇完。全文档集共 21 篇（00-20），完。