20 - 术语表与文档索引

项目：运营搭建平台（vue3-course） ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析

本篇是文档集（00-20）的收官篇，承担三个职能：其一，术语表——把散落在 20 篇文档与源码注释里的平台词汇收敛为一张统一口径的表，每个术语给出定义与权威展开篇目；其二，源码文件 ↔ 篇目反向索引——拿着一个文件路径能立刻找到"哪几篇讲过它"；其三，按任务阅读路径——四类高频任务（加物料、加数据源类型、上线检查、排查发布失败）各自的文档与源码阅读顺序。术语的首次定义在对应篇目，本表只做口径统一与跳板；表格之外的说明文字补充术语间的关联与易混淆点。

1. 术语表

1.1 搭建模型类

• 物料（Material / Component）：可拖入画布的可复用组件。本项目有两种物料形态：看板线的 EP 物料（本地元表，见 packages/charts/src/meta/elementPlusMetas.ts，53 个）与页面线的独立物料（独立 npm 包进 mock CDN，packages/materials/ 下两个）——两种形态共用同一属性协议（ADR-001）。权威展开：《01-系统架构》3.2、《07-模块详解》第 10 节、《11-扩展开发指南》SOP 一/二。
• 物料元表（ComponentMeta）：描述一个物料的元数据（type/label/category/defaultSize/defaultProps/propSchema/propGroups/container/dataBinding/events），是"组件库面板、属性面板、画布默认尺寸"三个消费者的共同数据源。不是组件实例——组件实例叫 ComponentInstance。权威展开：《15-接口全量参考》第 4 节末的 meta 结构速查、《18-代码走读实录》第 3 节。
• schema / schemaJson：看板的完整 JSON 描述（components/state/methods/layoutMode/canvas），存 dashboard_info.schema_json；发布产物中追加 publishedDataSources 与 accessMode。三端（编辑画布/访客渲染器/出码器）消费同一份 JSON。权威展开：《04-数据模型》4.1、《19-数据契约与示例集》附录。
• 组件实例（ComponentInstance）：schema 树上的单个组件节点（id/type/props/style/visibleWhen/children/dataBinding/events）。复制与区块插入时整树重新生成 id（防选中错乱）。权威展开：《04-数据模型》4.1。
• 画布（Canvas）：编辑器的渲染区，实现为同源 iframe（路由 /page/dashboard-canvas），与编辑器壳经 canvas:* postMessage 协议通信；位置字段以画布为唯一上传方（防双向同步回环）。权威展开：《02-页面设计》2.1、《18-代码走读实录》1.4（防回环协议全文）。
• 布局模式（layoutMode）：flow（文档流，组件按容器纵排）/ absolute（绝对定位，x/y/w/h 生效）双模式，随 schemaJson 持久化。切换时有级联摆放与 flow 迁移（applyFlowMigration）。权威展开：《02-页面设计》第 4 节。
• 容器（Container）：可接收子组件的物料（meta.container.acceptChildren，语义对齐 TinyEngine configure.isContainer）；容器子组件不进顶层栅格。权威展开：《11-扩展开发指南》SOP 一第 3 步。
• 区块（Block）：可复用的组件组合（block_info.components_json），编辑器"区块面板"插入后整树重发 id。权威展开：《00-项目总览》第 2 节功能表。
• 模板（Template）：另存的看板/页面（is_template=1），全局目录人人可读；从模板新建复制 schema 并重置 owner/visibility。两线各一套模板中心。权威展开：《07-模块详解》第 5 节（dashboard-templates.ts）。

1.2 运行时类

• 页面方法（Page Methods）：作者随看板保存的函数体源码，AsyncFunction('state','methods', body) 编译执行（对齐 TinyEngine script 插件签名）；方法互调经 methods 参数。无沙箱执行是它的根本约束，公开闸门因此而生。权威展开：《08-安全与权限设计》第 6 节、《18-代码走读实录》ADR-006 关联段、packages/shared/src/runtime.ts。
• 页面状态（Page State）：state 对象的键值变量，供 visibleWhen 显隐条件求值与方法体读写；编辑画布提供快照、访客端持有活状态（三个 Symbol 注入键区分两种语境）。权威展开：《02-页面设计》第 3 节。
• 访客渲染器（useDashboardRenderer）：visitor 桶里的看板渲染 composable——boot 数据初始化、编译页面方法、并行取数（在途去重 + shallowRef 缓存）、错误单节点隔离。权威展开：《10-性能设计与优化》第 2 节。
• boot 注入（DASHBOARD_BOOT）：portal 把 schema 与元信息内联进 /d/:uuid HTML 的机制（< 全量转义防脚本闭合，accessMode/accessToken 剥离）——访客零额外请求拿到结构。权威展开：《15-接口全量参考》第 4 节末。
• AsyncFunction 编译：new Function('return (async function(){}).constructor')() 的运行时求值写法，规避打包器把 async 字面量转译降级（ADR-006）。权威展开：《07-模块详解》第 1 节第 1 条。

1.3 发布与访问控制类

• 三阶段发布（test / pre / prod）：发布 = 内容复制进下一张阶段表（test ← 草稿注入白名单、pre ← test、prod ← pre + 版本自增 + 自动快照），表级快照而非状态字段（ADR-003）；下线 = 阶段表置 status=0。权威展开：《05-核心流程》流程二、《16-决策记录ADR》ADR-003。
• 发布白名单（publishedDataSources）：test 发布时从组件 dataBinding 收集的数据源清单，仅 {id, name, type}，config（含口令）永不进发布产物；访客取数能力只与它有关。权威展开：《08-安全与权限设计》第 6 节、《18-代码走读实录》2.1。
• 双重校验：portal 转发前按本地 prod 行校验白名单一次，work-server 终点不信 portal 的判断再校验一次，然后以 queryParams 固定空对象执行。权威展开：《18-代码走读实录》2.3、《05-核心流程》流程二第 6 步。
• 令牌门（Access Gate）：token 访问模式的验证门——query ?t= 与 7 天 HttpOnly cookie 双通道、timingSafeEqual 常量时间比对、HTML 门与取数门共用同一道门；判定读 dashboard_info 实时行（改模式/轮换令牌即时生效）。权威展开：《05-核心流程》流程四。
• 访客模式（访问方式 accessMode）：public（匿名可访问）/ token（需令牌）二值，实时列；库默认 public——新建即公开是安全清单项。权威展开：《08-安全与权限设计》第 6、10 节。
• 公开闸门（Page Methods Gate）：两条拦截——含页面方法体的看板①不得发布到 prod（public 时）②不得切 public；校验对象是 pre 快照与 prod 产物（草稿删除不免责）。逃生阀 ALLOW_PAGE_METHODS_ON_PUBLIC=1。权威展开：《08-安全与权限设计》第 6 节。
• 快照（Snapshot）：看板历史的全量 JSON 备份，dashboard_snapshot 表以 source 区分三来源（save 保存自动 / manual 手动 / publish 发布）；回滚 = 快照内容写回草稿；编辑器内的撤销重做栈是同名思想的客户端实现。权威展开：《00-项目总览》功能表"历史与回滚"行、《07-模块详解》第 5 节。
• 出码（Codegen）：看板 schema → 可独立运行的 Vue3+Vite 工程 zip（jszip 打包）；图表层 vendor @my/charts 源码、数据源只带 500 行快照、依赖钉死工作区版本——"平台锁定"的逃生阀（ADR-012）。权威展开：《05-核心流程》流程五。

1.4 数据类

• 数据源（DataSource）：看板组件的数据绑定目标，五类判别联合（mysql/postgresql/api/csv/static），config 按类型异构、敏感项加密落库；以 connectionId 引用连接而非内联 host/port。权威展开：《04-数据模型》4.2、《11-扩展开发指南》SOP 三。
• 数据库连接（DB Connection）：SQL 类数据源的主机凭据载体（db_connection_info），口令 AES-256-GCM 密文落库；管理台必须先建连接再建 SQL 数据源。权威展开：《08-安全与权限设计》第 7 节。
• 唯一解密出口（executeDataSourceQuery）：全仓唯一调用 openConfigSecrets 的运行时取数路径，编辑器路径与访客路径在此汇聚；明文不出该函数。权威展开：《08-安全与权限设计》第 7 节、《18-代码走读实录》ADR-005 关联段。
• mock 数据（mockData）：数据源 config 的可选字段，配置后前端适配器优先使用（编辑态联调、离线演示、出码兜底）。权威展开：《04-数据模型》4.2 注释。
• 参数占位符（{{name}}）：SQL/API 模板里的参数位，执行时经 buildParameterizedQuery 转驱动绑定值（防注入）；API 的 authority 段禁止占位符（assertStaticAuthority）。权威展开：《08-安全与权限设计》第 7 节。
• net-guard：API 数据源的 SSRF 收口层（packages/work-server/src/util/net-guard.ts）——恒拒元数据地址（含 IPv6 包裹写法）、默认拒内网、不跟随重定向、超时/重试钳制。权威展开：《08-安全与权限设计》第 7 节、《13-技术债务与演进建议》第 1 节 #1。

1.5 平台件类

• admin 桶 / visitor 桶：@my/work-front 一个包的两个构建产物桶（dist/admin/** 编辑器+管理台、dist/visitor/** 访客渲染器）；服务端构建只拷自己的桶——portal 公开目录物理上不存在编辑器代码（桶隔离）。权威展开：《01-系统架构》第 1 节、《06-部署运行》第 5 节。
• 权限码（Permission Code）：RBAC 的原子授权单元（资源:动作，如 dashboard:publish），种子矩阵在 packages/init-database/src/sql/insert_role_permission_*.sql；requirePermission(code) 路由级拦截。权威展开：《08-安全与权限设计》第 4 节。
• 可见范围（visibility）：资产级读控制（private/department/public，租户内语义），四类资产共用 visibility.ts 一套判定；写判定是 ownership（仅 owner，无主首写认领）。权威展开：《08-安全与权限设计》第 5 节。
• 四把密钥：JWT_SECRET（登录态）/ SECRET_BOX_KEY（凭据加密主密钥）/ INTERNAL_TOKEN（服务间通道）/ PASSWORD_SALT（废弃迁移期）——生命周期与轮换剧本各不相同。权威展开：《08-安全与权限设计》第 2 节、《14-配置与环境详解》1.1。
• mock CDN：文件型 CDN 抽象（packages/mocks/mock-cdn），承载物料包与页面产物（按 <name>/<version>/ 版本化目录）；服务端经 createSyncCDNMirror 回源落盘。权威展开：《07-模块详解》第 10 节。
• server-kit：两服务端共用基建包（连接池/事务、安全响应头、cookie/CSRF、限流、CDN 镜像），门面模式。权威展开：《07-模块详解》第 7 节。
• PV 埋点 / 访问统计：服务端埋点（30 分钟 (uuid,ip) 去重、爬虫 UA 直跳、fire-and-forget），dashboard_visit_log/page_visit_log 表按天聚合。权威展开：《10-性能设计与优化》第 2 节。
• TinyEngine 借鉴：tiny-engine-study/ 是 OpenTiny TinyEngine 2.11.0 源码副本（仅参考不参与构建）；借鉴账本在 tiny-engine-borrow-plan.md（9 项任务全部完成）。权威展开：《07-模块详解》第 12 节、《16-决策记录ADR》ADR-001/007/008/011。

术语表的三组易混淆点值得单独点破。物料 vs 元表 vs 组件实例：物料是口语总称，元表是"它是什么、怎么配"的声明（注册端），组件实例是"树上的一个节点"（数据）——元表全局唯一，实例千千万。快照 vs 发布 vs 模板：快照是时间轴上的备份（可回滚），发布是向阶段表的复制（向访客可见），模板是目录里的另存（可复制新建）——三者都复制 schema 但服务对象完全不同。访问方式的两个"门"：令牌门管"人能不能进"（HTML 与取数共用），白名单管"进来了能碰哪些数据"——token 模式下两道门都要过，public 模式只有白名单一道。

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

下表覆盖"文档集展开过的高价值文件"，按包分组。行首是文件路径（相对 vue3-course/），"篇目"列给主要展开位置（篇内小节不再列细）。

反向索引的使用方法：改代码前先在此表定位"谁讲过它"，顺该篇的展开读到机制层；若表中没有，先查 07 篇（模块详解覆盖全部包的关键文件），再退到 00 篇第 2 节功能表按功能域定位。

3. 按任务阅读路径

路径 A：给看板线加一个物料（EP 通用组件）

读：11 篇 SOP 一（步骤/坑）→ 15 篇第 4 节（ComponentMeta 结构）→ 18 篇第 3 节（注册与渲染走读，理解 name 对齐为什么是硬约束）→ 09 篇第 3 节（prop-configurator.test.ts 等回归入口）。动手触点：packages/charts/src/meta/elementPlusMetas.ts；验证走 11 篇 SOP 一的验证段。若要给物料加自定义配置器，加读 SOP 六与 16 篇 ADR-007。

路径 B：加一种数据源类型

读：11 篇 SOP 三（六步触点图）→ 04 篇 4.2 节（config 判别联合）→ 08 篇第 7 节（安全边界——凡发外网请求必读）→ 18 篇 2.3 节关联段（为什么不能绕过 executeDataSourceQuery）。动手触点：packages/shared/src/schema/index.ts（type 联合）→ packages/work-server/src/util/data-query/（新查询器）→ service/data-query.ts（switch 加 case）→ service/datasource.ts（SUPPORTED_TYPES）。验证补 data-query.test.ts 用例（09 篇夹具自删纪律）。

路径 C：上线检查

读：06 篇第 2.1 节（生产四步）→ 14 篇第 4 节（deploy-ops 八条硬约束展开：顺序/密钥/轮换/默认账号/哈希迁移/限流口径/单实例/CI 口径）→ 12 篇第 8 节（线上健康检查五项清单）→ 08 篇第 10 节（已知隐患，决定哪些开关必须保持默认）。启动报错对照 12 篇第 2 节表（三道自检都是 fail-fast 设计而非 bug）；冒烟三连（登录/发布一个看板/访客取数）通过才算上线完成。

路径 D：排查发布失败

读：12 篇第 5 节（发布与数据源类故障表）→ 05 篇流程二（发布时序，定位卡在哪一阶段）→ 08 篇第 6 节（若是公开闸门拒绝——理解"查 pre 不查草稿"）→ 18 篇第 2 节（源码级走读，确认报错对应哪个分支）。常见四类根因速记：跳阶段被拒（补 test/pre）、公开闸门拒绝（删方法体或切 token，且要重推 test→pre）、白名单缺失（发布后新绑的数据源要重走三阶段）、名称/权限问题（403 文案分流见 12 篇第 3 节）。涉及 GCM/解密报错一律先查 08 篇第 2 节密钥清单——任何情况下不要清库。

路径 E（补充）：接手编辑器 / 排查画布异常

读：02 篇第 2 节（布局与协议总图）→ 18 篇第 1 节（历史栈与单例走读）→ 12 篇第 4 节（编辑器故障表，"单向数据流某一环断了"的定位法）→ 10 篇第 1 节（性能约束）。调试口诀：控制台监听 message 事件看 canvas:* 消息双向流动，断在哪一环问题就在哪一层。

4. 文档集总目与分工

最后给全 21 篇的一页总目（含本篇），按"概念 → 参考 → 实践"三段排布：概念与架构——00 项目总览、01 系统架构、16 决策记录 ADR、20 术语表与索引（本篇）；设计参考——02 页面设计、03 接口设计、04 数据模型、07 模块详解、15 接口全量参考、17 依赖全景、19 数据契约与示例集；流程与运维——05 核心流程、06 部署运行、08 安全与权限设计、10 性能设计与优化、14 配置与环境详解；质量与演进——09 测试与质量保障、12 FAQ 与故障排查、11 扩展开发指南、13 技术债务与演进建议、18 代码走读实录。阅读顺序建议：新人按 00 → 01 → 05 → 07 建立骨架，再按第 3 节的任务路径进入专题；所有篇目开头都有"与其他篇目的分工"说明，交叉引用统一用「见《0X-xxx》」格式。本套文档的维护约定沿用既有 16 篇：行号与结论以当前源码为准，无法确认的标 ⚠️ 待确认，正文不出现裸三反引号串（代码引用一律四反引号围栏）。