20 术语表与文档索引

项目：html5-dataviz ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析

0. 本章定位

本章是文档集（00~20 共 21 篇）的最后一篇，承担三个收尾职责：其一，术语表——把散落在各篇的专有名词（清单+约定、双链路、渲染代次、大屏双真源等）收敛为一页对照表，每条给出定义、源码锚点与"详见篇目"，让新维护者不必通读全集也能建立共同语言；其二，源码文件与篇目的反向索引——拿着一个文件名查"哪几篇讲过它"，是改代码前查文档的最短路径；其三，按任务组织的阅读路径——四类高频任务（加案例、加图表库、排查渲染失败、上线检查）各给出一条带顺序的阅读清单，回答"我现在要做 X，应该按什么顺序读哪几节的哪几段"。

整套文档的分工原则在此重申一遍：0002 讲"是什么"（总览、架构、页面），0305 讲"怎么约定"（接口、数据、流程），06 讲"怎么跑"，0708 讲"核心模块与安全面"，0910 讲"质量与性能"，1112 讲"怎么扩展与怎么排查"，1314 讲"债务与配置"，15 讲"契约现状"，1618（本次新增）讲"为什么这么设计、依赖长什么样、代码怎么读"，1920（本次新增）讲"样例可抄、术语可查"。篇与篇之间的重复内容一律以"见《0X-xxx》"引用消化，不再各自展开。

1. 术语表

按"渲染体系 → 数据体系 → 大屏体系 → 工程设施"四组归类，表内"锚点"列为源码中的定义或核心实现位置。

1.1 渲染体系

本组是本项目术语密度最高的一组：双链路、渲染代次、沙箱编译三个词各有专属机制篇，且彼此存在依赖关系——渲染代次保护的是双链路中所有异步边界，沙箱编译是双链路中 component 分支的执行方式，而"清单+约定"是双链路得以分叉的前提。首次阅读建议按表中行序推进，即先理解注册模式再理解分派，最后理解两类执行体各自的竞态与安全语义。

1.2 数据体系

数据体系术语的主线是"文件系统即数据库"背景下的一致性手段：元数据 JSON 与 manifest 投影是同一事实的两份存储，守恒测试是它们的一致性仲裁者，slim 瘦身与缓存 Promise 则分别治理"体积冗余"与"重复加载"两类衍生问题。理解本组术语的钥匙是《04-数据模型》第 5 节的数据生命周期四阶段——每个术语都落在生成期/构建期/运行期/销毁期的某个具体阶段上。

1.3 大屏体系

大屏体系与图表示例体系是两套平行的注册（图表走"清单+约定"，大屏走"双真源手工表"），因此术语几乎不与 1.1/1.2 组重叠。它的特殊工程约束是长时驻留：监控大屏可能连续运行数天，任何微小泄漏都会按天放大，这解释了本组术语中"单一时钟源""清理纪律"等表述的存在。

1.4 工程设施

本组收录横跨渲染/数据/大屏三域的构建与质量设施：分包规则、缓存双表、自动注册、测试工具族。它们的特点是"改一处、动全局"——vendor 桶规则、守恒测试数字、smoke 断言正则都属于牵一发动全身的枢纽，因此每条都标注了对应的变更检查位置（详见列的篇目大多有检查单或回归清单）。

2. 源码文件与篇目反向索引

反向索引的用法是"拿着文件名查文档"：改某个文件前先在表中定位该行，按"→ 篇目"列的优先级顺序读前两篇即可覆盖该文件 80% 以上的设计上下文；若本次改动涉及行为面变化，再顺藤核对"契约测试"类篇目（《09》《15》）确认是否有用例需要同步。表格按源码目录层级排列（构建配置与脚本置于表尾），首列即源码路径，可直接按目录前缀检索。

改某个文件前先查此表，"→ 篇目"列按阅读优先级排序（分派器/容器等核心文件被多篇覆盖，首篇是机制主篇）：

3. 按任务阅读路径

3.1 任务一：新增一个图表案例（最高频）

目标拆解决定读法。加一个 echarts/antv 案例：先读《19》第 3 节拿三种 EChartDemo 模板的形态判断（静态图选 option、异步取数选 onReady、有定时器/监听选 setup 且必须返回清理函数），再按《06》第 5 节的六步 SOP 执行（SFC → manifest → JSON → 缩略图 → 改守恒测试数字 → 本地验证），过程中的字段细节随时回查《19》第 1~2 节的样例，最后跑《11》第 1 节末尾的验证清单。加一个 three/webgl 案例：规范路径是生成器迁移（《11》SOP-E），手工新增时必读《19》4.2/4.3 的壳组件模板与《19》第 1 节的 globals 写法。加一个兜底条目（只收录官方脚本不改写）：读《19》第 2 节样例 ②③ 的代码字段形态与《11》SOP-F 的两步扩展库接入，完成后必跑 sweep-fallback。三条支线的共同收尾是《11》第 7 节的四连命令；共同的易错点是"新增必有 JSON 条目"与"改完跑守恒测试"两条铁律（《11》第 0 节）。

3.2 任务二：新增或下线一个图表库

这是改动面最大的扩展（五~六处同步），路径以《11》SOP-C 为主干：库注册表 → 数据集与 DATASET_LOADERS → 渲染链路二选一（全量本地 SFC 路线参照 three/webgl 的现成形态，或 Renderer 加分派分支）→ manifest → vendor 桶规则 → 守恒测试。配套阅读三处：《17》2.3 与第 3 节理解新库依赖的 chunk 归属与升级风险（尤其"是否拖累首屏"一问）；《16》ADR-012 理解下线动作的历史先例与"未知库返回空集"的既成语义；《15》第 3 节理解 loaderKind 分派契约的开放边界（switch default throw 的防御位置）。若新库需要新的渲染执行方式（第五种 loaderKind），先读《09》第 5 节看渲染链测试怎么写，再读《18》第 2 节理解分派器与代次保护的代码事实——新分支必须自带竞态保护与错误呈现，不能寄生在旧链路里。

3.3 任务三：排查一次渲染失败

从《12》第 1 节的"链路三问"开始定链路（数据从哪来/代码谁来跑/资产走哪条路），然后按报错文案对号入座《12》第 2 节的 16 行速查表；决策树在《12》第 3 节，覆盖"详情页不渲染"的主干分叉。需要下沉到代码层时按链路取篇：本地 echarts SFC →《18》第 3 节（waitForInstance 与 myChart 代理的行为细节）；兜底求值 →《18》2.2~2.3（九形参暴露面与三连 throw 的语义）；沙箱编译 →《18》第 1 节 + 开 VITE_SFC_RUNTIME_DEBUG=1（《12》第 6 节）；three →《10》第 4 节（context 上限）。调试手段全景在《12》第 6 节（logger、smoke、sweep、Network chunk 语义、单元测试即文档）。排查前建议先过一遍《12》第 7 节的四个"易被误判"问题，避免在"设计内行为"上浪费时间——尤其"报错消息本身是接口的一部分"这条：多处以正则匹配错误文案，改文案前先检索消费方。

3.4 任务四：部署上线前的检查

按三个层次走。构建与产物：《06》第 3 节的产物特征（五桶分包、按需 chunk、public 原样拷贝）与《10》第 1 节的体积基线表——验收时对照 dist/index.html 的 modulepreload 列表（应只有 vendor 桶）与 Network 面板（首页不下载任何图表库代码）。部署前提：《08》第 7 节的五项前提表（dist 全量托管、SPA fallback、无功能性外链、字体可降级、wasm MIME）逐项核对，其中 SPA fallback 与 MIME 两项是内网服务器准入条件（《14》第 8 节的部署推理题补充了 history 路由的适用边界）。回归验证：pnpm typecheck && pnpm lint && pnpm test 三连后必须起服务跑 pnpm test:smoke——外链零请求断言与 canvas 渲染证据是发布前最后一道人工门禁（smoke 未入 CI，见《13》第 10 条）；涉及依赖变更时按《17》第 3 节的纪律加跑守恒测试与 sweep。若本次上线包含新案例/大屏，《19》与《11》对应 SOP 的验证步骤前置完成，上线阶段只做全量回归。

3.5 补充路径：升级依赖与接手代码库

两个次高频任务一并给出。升级依赖（尤其 three/echarts）：《17》第 2.3/2.1 节的升级风险梯度 → 《14》第 9 节检查单（改 package.json → install/test/smoke 三连）→ 《08》第 6 节（外链回归高发区）→ 《16》ADR-006（vendor 桶字符串匹配的落桶风险）；alias 锚定的五个锁定版本包升级时必须同步改 vite.config.ts（《17》1.4 节）。新人接手代码库：第一周按《00》第 6 节快速上手跑通环境与健康信号 → 《01》建立架构图景 → 《18》走读三个核心文件建立代码手感 → 《09》理解"测试即契约"的质量观 → 《13》了解已知债务避免重复踩坑；《12》第 6 节第 7 条的"注释即文档"原则是本项目最重要的接手须知——最关键的行为依据几乎都写在源码注释里，排查时优先信注释与测试，其次才是文档。

五条路径共用一个元规则：路径是阅读起点而非完整目录。每条路径只列出"从任务出发最先需要的篇目"，任务推进中遇到本表未覆盖的名词，回第 1 节术语表的"详见"列跳转；遇到本表未覆盖的文件，回第 2 节反向索引按文件名检索。两条查表入口加上本节的五条路径，构成"任务 → 篇目 → 文件 → 术语"的完整检索闭环——这份文档集没有设计成必须通读的结构，而是设计成可以从任意入口进入的网状结构，本篇就是那张网的索引页。

4. 文档集总目录与维护约定

维护约定两条。其一，文档与测试的同步优先于文档与文档的同步：任何使《15》表格、《09》用例清单、《19》样例失真的代码变更，应同 PR 修正对应篇目（这正是本项目"注释即文档"文化在文档层的延伸）；其二，数字口径以源码为终审——00~15 篇写作于 webgl 库加入之前，凡案例总数、库数、分类数出现 1688/三库 与 2013/四库（echarts 348 + antv 351 + three 989 + webgl 325）的口径差异时，以 src/data/charts/*.json 与守恒测试的当前值为准，⚠️ 待确认 00/15 两篇是否统一回刷为四库口径。全 21 篇的正文中均不出现未经验证的字面围栏串，代码引用一律以围栏块与行内代码两种形态呈现，引录处标注源文件路径，无法确认之处统一以"⚠️ 待确认"登记——这套写作纪律本身，就是文档集可信度的一部分。