项目：webCommand ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
这是文档集的收尾篇，承担两个职责。其一，术语表：把 00-19 各篇反复使用、但在源码里各有精确锚点的 32 个术语收拢成一张带"权威定义位置"的对照表——每个术语给出一句定义、源码锚点（真实路径，可直接打开核对）、与展开它的篇目编号。术语按领域分五组：命令系统、数据与同步、服务端横切、配置与部署、质量保障。其二，索引：源码文件到篇目的反向索引（46 个文件），以及"按任务找文档"的六条阅读路径——前者回答"我正在读这个文件，该看哪几篇"，后者回答"我要做这件事，该按什么顺序读"。与前 20 篇的关系是纯粹的索引层：本篇不引入任何新事实，所有条目都能在对应篇目或源码里找到完整叙述；若发现本篇定义与源码冲突，以源码为准并视为文档缺陷上报到《13》的"注释与实现矛盾"类别。
| 术语 | 一句话定义 | 源码锚点 | 展开 |
|---|---|---|---|
| 命令注册表 | commandList 数组在加载时展开成的 func/别名到命令对象的字典，是命令查找的唯一依据 | app/core/commandRegister.ts | 《07》§3、《00》§2 |
| 命令契约 | CommandType 接口：func/name/alias/params/options/subCommands/action/collapsible 八要素 | app/core/command.d.ts | 《11》SOP-1 |
| 命令别名 | 顶层命令在注册时把 alias 逐个写入 commandMap；子命令别名在执行时线性扫描匹配 | commandRegister.ts 尾部与 commandExecutor.getCommand | 《15》§3 |
| 子命令递归 | 父命令把去掉首个 token 的剩余文本当新命令递归执行（user login xxx → login xxx） | app/core/commandExecutor.ts 64-70 行 | 《05》§2、《18》§2.3 |
| 递归深度上限 | depth > 10 报"命令层级过深"，防自指自定义命令导致栈溢出 | commandExecutor.ts 31-34 行 | 《18》§2.3 |
| 自定义命令回退 | commandMap 查不到时查 customStore，命中则文本宏展开后重新进入解释器（内置命令恒优先） | commandExecutor.ts 43-57 行 | 《18》§2.3 |
| 声明式选项解析 | 把 options 配置翻译成 getopts 的 alias/string/boolean/default 四表 | commandExecutor.doParse | 《18》§2.4 |
| 必填参数自动校验 | 执行器统一消费 params[].required，父命令（有 subCommands）跳过 | commandExecutor.validateRequiredParams | 《18》§2.4 |
| 帮助自省 | 任意命令 --help 复用 helpCommand 渲染其 name/params/options 元数据 | commandExecutor.doAction | 《11》SOP-1 |
| 输出快照清洗 | 序列化输出列表到 localStorage 前，把组件输出换为占位文本、递归清洗 resultList | app/components/outputSnapshot.ts 的 sanitizeForSnapshot | 《04》§7、《09》§3 |
| 密码脱敏 | 历史命令与命令回显里 -p/--password 的取值替换为 ***（正则 (\S+) 有含空格口令缝隙，《13》⚠️-14） | outputSnapshot.ts 的 redactSensitiveText | 《08》§6、《13》A/B 档 |
| 提示符 | [用户名@空间当前目录]$，随登录态与 space cd 实时变化 | Terminal.vue 的 spacePrompt | 《02》§4 |
| 命令面板 | Ctrl+K 打开的模糊过滤面板，聚合内置命令与自定义命令（条目为创建时快照，《13》⚠️-21） | app/components/CommandPalette.vue | 《02》§5 |
| 术语 | 一句话定义 | 源码锚点 | 展开 |
|---|---|---|---|
| 八键结构 | localStorage 的固定八个键：六个 store 持久化键 + 命令历史 + 输出快照 | 六个 store 的 persist.key 与 Terminal.vue 127-129 行 | 《04》§7、《16》ADR-007 |
| 云同步 blob | 服务端 user_data.content 列里的整包 JSON 字符串，服务端不解析，结构由前端定义 | server/models/UserData.ts | 《04》§6、《16》ADR-005 |
| 写前合并 | 每次上传前先拉云端、合并、再上传合并结果的同步协议（flush 五步） | app/composables/useCloudSync.ts 的 flush | 《05》§4、《18》§4.1 |
| 合并回环 | 合并写入 store → $subscribe 触发 → 再上传 的死循环；由 applyingRemote 闸门 + 判等短路双重切断 | useCloudSync.ts 34-35、66-67 行 | 《18》§4.1 |
| LWW（逐条后写胜出） | 同 key 条目按 updateTime 毫秒取更晚者，无 updateTime 视为 0（历史数据恒劣势） | app/composables/cloudMerge.ts 的 mergeKeyed | 《18》§4.2 |
| 墓碑 | 删除记录 条目id -> 删除时刻 表，合并时抑制已删条目被另一端复活 | cloudMerge.ts；todoStore.deleteTaskById | 《16》ADR-006 |
| 墓碑保留窗口 | 30 天（TOMBSTONE_RETENTION_MS）后墓碑被剪枝，之后同名条目可被重新合并回来 | cloudMerge.ts 第 9 行 | 《18》§4.2 |
| 整包较新者胜 | 配置类数据（theme/terminalConfig）不做字段级合并，按 updatedAt 取较新整包 | cloudMerge.ts 的 localIsFresher；themeStore.applyCloudTheme | 《05》§4.4 |
| 结构嗅探 | blob 无版本号，解析靠运行时形状判断（旧版裸数组 → 新版 items+deleted） | todoStore.parseCloud | 《18》§4.3 |
| 同步注册表 | 六类可同步数据的唯一清单 + 惰性 store 加载器，登录/注销两处遍历 | app/composables/cloudSyncRegistry.ts | 《07》§4、《11》SOP-3 |
| 展示态与真相分离 | 前端 store 的 loginUser 只是展示态，会话与服务端库才是真相，启动时对账 | app/core/commands/user/userStore.getAndSetLoginUser | 《08》§2 |
| 软删除 | user 表 isDelete=1 标记删除；副作用是唯一索引仍占用，用户名永久不可重注册 | server/services/userService.deleteAccount | 《13》⚠️-3 |
| 术语 | 一句话定义 | 源码锚点 | 展开 |
|---|---|---|---|
| 包络 | 所有业务接口统一的 {code,data,message} 外壳；ok/fail 与 bizHandler 实现 | server/utils/response.ts | 《03》§4、《19》§1 |
| 业务错误码 | 与 HTTP 状态解耦的七档：40000/40100/40300/40400/42900/50000/50010 | response.ts 的 ERROR_CODE | 《19》§1 |
| 准入纯函数 | 不连库即可测的判定函数，返回可判别联合，放行时交回生效 userId/type | server/utils/dataAccess.ts、server/utils/accountPolicy.ts | 《08》§7、《16》ADR 决策五 |
| 分级限额 | 数据类（todo/space/note）1MB、配置类 64KB 的按类型尺寸上限 | dataAccess.contentLimitFor | 《04》§6、《08》§7 |
| 内存限流器 | Map + 滑动窗口 + 定时清扫，键上限 10000；三实例 10/30/120 每分钟 | server/utils/rateLimit.ts | 《08》§8、《16》ADR-009 |
| 单实例假设 | 限流与验证码存进程内存，重启即失效；多副本前必须外置 Redis | rateLimit.ts、passwordReset.ts 头注释 | 《13》§3 |
| 验证码哈希存储 | 验证码以 sha256(email:code) 落内存，10 分钟 TTL、5 次上限、60 秒重发 | server/services/passwordReset.ts | 《08》§4 |
| 防枚举 | 登录"用户不存在/密码错误"同形；reset-code 对未注册邮箱也返回 true | userService.verifyCredentials、reset-code.post.ts | 《08》§3-4 |
| 会话对账 | current 接口从库重读用户而非信任会话旧值 | server/api/user/current.post.ts | 《19》§4 |
| 真实 IP 信任 | 仅 TRUST_PROXY 开启时读 x-forwarded-for 首段，防伪造绕限流 | rateLimit.getClientIp | 《14》§3 |
| 出站 HTTP 助手 | 服务端 fetch 封装：8 秒超时、UA 伪装、状态码校验 | server/utils/httpClient.ts | 《03》§2 |
| 启动迁移插件 | Nitro 启动时跑迁移，失败不阻断启动，状态写入 appStatus 由探活暴露 | server/plugins/migrate.ts | 《18》§3.3 |
| 迁移水位 | schema_migrations 表记录已应用的迁移 id，按 id 升序补跑 | server/utils/migrations.ts | 《18》§3.2 |
| 幂等 DDL | 迁移语句全部 CREATE TABLE IF NOT EXISTS 化，容忍部分应用中间态重试 | migrations.ts 头注释 | 《16》ADR-010 |
| 假健康 | 进程活着但注册登录不可用的状态；探活靠查真表而非内存标志防误报 | server/api/health.get.ts 注释 | 《06》§5、《16》ADR-012 |
| 术语 | 一句话定义 | 源码锚点 | 展开 |
|---|---|---|---|
| 运行期配置解析 | setting()：NUXT_* 前缀 > 裸名 > 构建期默认值，两级环境变量写法都生效 | server/utils/appConfig.ts | 《14》§1、《16》ADR-004 |
| 产物零凭证 | 构建期不读敏感环境变量，.output 里无口令；deploy.sh 扫描兜底 | nuxt.config.ts 174-183 行；scripts/deploy.sh scan_artifact | 《06》§4、《14》§2 |
| 产物补装 mysql2 | sequelize 动态加载 mysql2 不被 Nitro 打包，Dockerfile 临时目录安装后合并 | Dockerfile 10-14 行 | 《17》§4、《06》§5 |
| SPA 外壳 | spa-loading-template.html 静态外壳，noscript 承载 SEO/GEO 兜底 | app/spa-loading-template.html | 《01》§2、《02》§3 |
| 探活契约 | /api/health 200/503 两态，healthcheck 与 deploy verify 消费 | server/api/health.get.ts；docker-compose.example.yml | 《19》§10 |
| 术语 | 一句话定义 | 源码锚点 | 展开 |
|---|---|---|---|
| 双轨测试 | node:test 跑纯函数与静态契约（零依赖）；vitest 跑路由层与前端单测 | package.json scripts；vitest.config.ts | 《09》§1-3、《16》ADR-011 |
| 契约测试 | 钉住跨端一致性的静态比对：CLOUD_DATA_TYPES、MIN_PASSWORD_LENGTH、ApiResult | test/cloudDataType.spec.ts、test/accountPolicy.spec.ts | 《09》§2 |
| Nitro 全局替身 | vitest setup 注入 defineEventHandler/readBody/getQuery 等全局，让路由 handler 可在 node 环境执行 | test/routes/nitroGlobals.ts | 《09》§3 |
| 冒烟回放 | 真库端到端 26 断言：迁移建表、blob 逐字往返、跨用户隔离、注销闭环、限流 429 | scripts/smoke-cloud-sync.sh | 《09》§4、《19》§11 |
| 五步门禁 | format:check → lint → typecheck → test → test:routes 的本机发布前置 | scripts/check-all.sh | 《09》§5 |
术语表的行是平铺的，但术语之间有结构。挑三组最容易"单个都懂、合起来就糊涂"的术语画出关系，作为读表的注脚。
命令系统组：一个请求经过的四个术语。用户敲入的文本先碰到命令注册表（commandMap，func 与别名各占一个键），命中后由声明式选项解析把文本拆成位置参数与选项，必填参数自动校验依据命令契约里的 required 声明拦截缺参请求，最后才轮到命令的 action——若输入的是 user login 这类带层级的形式，子命令递归会在匹配与解析之间插一脚，把剩余文本当新命令从头走一遍（受递归深度上限保护）。这五个术语的次序就是执行器的执行次序，与《18》走读一的段落一一对应；而命令别名横跨两端——顶层命令的别名在注册时静态展开，子命令的别名在匹配时动态扫描，这是新人最容易混淆的一处不对称。自定义命令回退则站在整个链条之后：只有注册表明确说"查无此命令"时它才出场，这个次序保证了内置命令永远优先于用户定义。
数据与同步组：一条数据的一生。一条待办在本地诞生于 LWW 所依赖的 updateTime 时间戳，活着时进入八键结构里的 todo-store 键；被删除时不消失，而是留下一条墓碑——它在墓碑保留窗口（30 天）内阻止其他设备把它复活，超窗后被结构嗅探之外的剪枝逻辑清掉。当另一台设备改动触发写前合并时，本地的整包状态与云同步 blob（服务端只存不解析的那串 JSON）在合并原语里相遇：逐条数据走 LWW 与墓碑裁决，配置类数据（主题、终端配置）则走整包较新者胜，不拆字段。合并结果写回 store 的瞬间，合并回环的两个闸门（applyingRemote 与判等短路）决定"这次合并是否再次触发上传"。这组术语共同回答一个问题：为什么服务端可以只有一张表——因为所有语义都被推到了客户端的这些原语里（这正是《16》ADR-005 的决策内容）。
服务端横切组：一个请求穿过的三层。请求先撞上内存限流器（三个实例按路由分组，键是真实 IP 信任解析出的客户端地址），通过后进入路由 handler，被包络包住——无论内部抛出什么业务错误码，出口永远同构；需要身份的接口在读会话后调用准入纯函数做最后裁决，云数据接口再多过一道分级限额。这层之外还有两组"看门"术语：防枚举决定错误消息的形状（登录与验证码接口刻意模糊内部状态），假健康则定义探活的责任——/api/health 必须查真表而不是读内存标志，否则单实例假设下"进程活着但库没起来"的静默半死状态会被漏报。读这组术语的诀窍是记住方向：它们全部是请求的守门人，而不是业务的一部分——这也解释了为什么它们能被抽成与数据库无关的纯函数（ADR-011 的测试对象）。
反向索引的用法是"从文件找文档"：接到一个 bug 单或评审一个 PR 时，先在下表定位改动文件，看"详述"列是否有对应篇目——有则先读再改，能避免踩中已被登记过的设计约束（例如改 migrations.ts 前先读《18》§3 与 ADR-010，就知道"幂等"是硬约束而非建议）。表中未收录的文件（40 余个命令实现、测试与脚本细节）多数属于"自包含、零横切"的性质，直接读源码即可；需要定位时用第 2.1 节的命令系统术语表或《00》§2 的功能清单反查。下表按"工程根 → app → server → 脚本与测试"的顺序列出 46 个最有阅读价值的文件。"职责"列只给一句话，"详述"列给主要展开篇目（次要引用不列全，可用各篇目录检索）。文件路径均相对 webCommand/ 工程根。
| 文件 | 职责一句话 | 详述 |
|---|---|---|
nuxt.config.ts | SPA 开关、模块注册、runtimeConfig 双轨、SEO head | 《14》§2、《01》§2、《16》ADR-001/002/004 |
package.json | 29 个依赖与 nine 类脚本 | 《17》全文 |
auth.d.ts | 会话 User 类型扩展（id/username/email） | 《03》§3、《08》§2 |
vitest.config.ts | 第二轨测试的 include 收窄与全局替身 | 《09》§3 |
eslint.config.mjs | 质量规则（no-explicit-any error）与 Prettier 分工 | 《09》§5 |
.env.example | 环境变量占位与注释文档 | 《14》§3 |
Dockerfile | node:22-slim 运行镜像，补装 mysql2 | 《06》§5、《17》§4 |
docker-compose.example.yml | 编排模板：healthcheck 与 NUXT_* 环境变量 | 《06》§5、《14》§5 |
app/app.vue | 根组件，仅承载唯一页面 | 《02》§1 |
app/pages/index.vue | 唯一页面：会话恢复 + 云同步初始化 + 执行器入口 | 《18》§2.1、《05》§3 |
app/spa-loading-template.html | SPA 静态外壳与 noscript SEO 兜底 | 《01》§2 |
app/components/Terminal.vue | 终端主组件：输出列表、提交、折叠、历史、快照 | 《02》§4、《18》§2.2 |
app/components/ContentOutput.vue | 单条输出的文本/组件渲染 | 《02》§4 |
app/components/CommandPalette.vue | Ctrl+K 命令面板 | 《02》§5 |
app/components/shortcuts.ts | 全局快捷键注册 | 《02》§5 |
app/components/history.ts | 历史上翻/下翻与 ! 序号执行 | 《02》§5 |
app/components/hint.ts | 输入提示（防抖）与 Tab 循环补全 | 《02》§5 |
app/components/outputSnapshot.ts | 快照清洗与密码脱敏纯函数 | 《04》§7、《09》§3 |
app/components/type.d.ts | 全局 namespace Terminal 类型 | 《02》附录 |
app/core/command.d.ts | 命令契约八要素 | 《11》SOP-1、《18》§2.4 |
app/core/commandRegister.ts | 命令清单 → commandMap（含别名） | 《00》§2、《18》§2.3 |
app/core/commandExecutor.ts | 解释器：匹配/解析/递归/校验/执行 | 《18》§2.3-2.4、《05》§2 |
app/core/commands/user/userStore.ts | 登录态展示 store 与会话对账 | 《05》§3、《08》§2 |
app/core/commands/user/userConstant.ts | LOCAL_USER 与 MIN_PASSWORD_LENGTH 前端副本 | 《03》§6 |
app/core/commands/todo/todoStore.ts | todo store：墓碑写入、合并装配、结构嗅探 | 《18》§4.3、《04》§6 |
app/core/commands/theme/themeStore.ts | 主题 store：配置类整包合并的样例 | 《05》§4.4 |
app/core/commands/data/exportCommand.ts | 备份导出（覆盖不全，《13》⚠️-2） | 《13》A 档 |
app/core/commands/custom/customStore.ts | 自定义命令 store（执行器回退数据源） | 《18》§2.3 |
app/composables/useCloudSync.ts | 同步工厂：写前合并时序与防回环 | 《18》§4.1、《05》§4 |
app/composables/cloudMerge.ts | 合并原语：LWW/墓碑/剪枝/整包比较 | 《18》§4.2、《16》ADR-006 |
app/composables/cloudSyncRegistry.ts | 六类数据同步清单与惰性加载 | 《11》SOP-3 |
app/plugins/pinia-persistedstate.client.ts | 持久化插件注册（防重复） | 《04》§7、《17》§5 |
app/utils/myAxios.ts | axios 封装：同源 /api、withCredentials、ApiResult | 《03》§1、《17》§6 |
app/utils/smartText.ts | HTML 转义 + 链接化（v-html 安全兜底） | 《08》§6 |
app/utils/error.ts | errMsg 统一错误文案提取 | 《07》§4 |
app/utils/myDayjs.ts | dayjs 封装 | 《17》§2 |
server/api/user/*.post.ts（7 个路由） | 账号七接口：login/register/current/logout/reset-code/reset-password/delete | 《19》§2-8、《03》§2 |
server/api/data/index.get.ts | 云数据读取（白名单准入） | 《19》§9 |
server/api/data/sync.post.ts | 云数据 upsert 写入 | 《19》§9 |
server/api/health.get.ts | 探活：查真表定健康 | 《16》ADR-012、《19》§10 |
server/api/weather.get.ts | 天气代理（限流/参数/出站/转译四步） | 《18》§2.5 |
server/models/User.ts | user 表模型与 toSafeUser 脱敏 | 《04》§3 |
server/models/UserData.ts | user_data 表模型（blob 存储体） | 《04》§3 |
server/services/userService.ts | 注册/凭证/改密/注销业务与事务 | 《05》§3、6、《08》§3 |
server/services/passwordReset.ts | 内存验证码签发与校验 | 《08》§4 |
server/utils/response.ts | 包络、BizError、错误码 | 《03》§4、《19》§1 |
server/utils/rateLimit.ts | 三实例内存限流器与真实 IP | 《08》§8、《16》ADR-009 |
server/utils/dataAccess.ts | 云数据准入纯函数与分级限额 | 《08》§7 |
server/utils/accountPolicy.ts | 口令/邮箱校验与注销三条件 | 《08》§5 |
server/utils/appConfig.ts | 运行期配置解析（setting/resolveDbConfig） | 《14》§1、《16》ADR-004 |
server/utils/db.ts | Sequelize 懒加载单例 | 《04》§2 |
server/utils/migrations.ts | 极简 SQL 迁移器 | 《18》§3、《16》ADR-010 |
server/utils/appStatus.ts | 运行期状态标志（schemaReady/schemaError） | 《06》§5 |
server/utils/httpClient.ts | 出站 fetch 助手（8s 超时） | 《03》§2、《17》§6 |
server/thirdparty/mailer.ts | SMTP transporter 缓存单例 | 《17》§6 |
server/thirdparty/background.ts | 随机壁纸 API（服务端 axios 遗留） | 《17》§6 |
scripts/check-all.sh | 五步质量门禁 | 《09》§5 |
scripts/deploy.sh | 构建 + 凭据扫描 + 部署核验 | 《06》§4、《14》§6 |
scripts/smoke-cloud-sync.sh | 真库 26 断言端到端冒烟 | 《09》§4、《19》§11 |
scripts/backup-db.sh | 数据库备份（防呆缺口 ⚠️-23） | 《13》B 档、《06》§6 |
test/cloudMerge.spec.ts | 合并算法全场景用例 | 《09》§2 |
test/routes/dataRoutes.test.ts | 数据路由行为（含伪造 userId 无效） | 《08》§7、《09》§3 |
六条路径覆盖最高频的六类任务。每条按"先读什么、再改什么、以什么收尾"组织，篇目编号可对照第 6 节的总索引。
路径一：加一个新命令（最常见）。先读《11》SOP-1 拿三步模板，再读《18》§2.3-2.4 理解执行器如何消费你写的声明（subCommands/params[].required 的语义），动手时对照 app/core/commands/weather/weatherCommand.ts（最小可用样例：参数 join、业务失败转异常、防御性解析）与 app/core/commandRegister.ts（注册进清单）。收尾三件事：help 里能看到新命令（数组顺序即展示顺序）、--help 自省可渲染、pnpm typecheck 过。若命令要发请求，补读《03》§1 确认包络约定。
路径二：修一个同步冲突 bug。按数据流顺序读：《18》§4.1（flush 五步与防回环）→ 《18》§4.2（mergeKeyed 的判定矩阵）→ 《18》§4.3（store 装配层与结构嗅探）→ 《05》§4（全链路时序图，补齐网络视角）→ 《16》ADR-005/006（当初为什么这样设计，避免把正确修复改回错误行为）。改完必须给 test/cloudMerge.spec.ts 补用例（本仓库传统：事故沉淀为测试），并跑 test:all。
路径三：上线/发布前检查。按《06》§4 的构建流程 → 《14》§3 环境变量清单逐项核对（NUXT_SESSION_PASSWORD ≥32、DB_* 齐全、TRUST_PROXY 按反代拓扑）→ scripts/deploy.sh（自带凭据扫描）→ 部署后 curl /api/health 确认 200 且 schemaReady: true（《19》§10 的报文）→ 跑一遍《19》§11 的冒烟回放链。有异常按《12》§4 的排查决策树走。
路径四：排查登录问题。先分清三种"登录失败"：接口报错（读《19》§3 的四种失败报文与《12》§2 速查表）、会话恢复失败（读《05》§3 与 userStore.getAndSetLoginUser 的三分支）、cookie 层问题（读《08》§2 的 Secure/SameSite 属性与《14》§3.2 的配置排错三案例）。服务端侧补读 userService.verifyCredentials（防枚举的同形错误）与 check-env.ts（生产启动校验——密钥过短会让所有登录态接口 500，是"全站突然登不上"的第一嫌疑）。
路径五：新增一类云同步数据。读《11》SOP-3 三步 + 《18》§4.3（装配层要写什么）+ 《16》ADR-005（为什么服务端零改动）。关键动作：store 的 serialize/merge 装配、cloudSyncRegistry 登记类型、确认 server/utils/dataAccess.ts 白名单同步（契约测试 cloudDataType.spec.ts 会强制提醒）、决定数据类还是配置类限额。
路径六：变更数据库表结构。读《18》§3 全节（迁移器怎么跑、失败怎么办）+ 《11》SOP-5 + 《16》ADR-010/008（幂等与水位的约束）。铁律：新迁移语句必须幂等、id 零填充升序、与 Sequelize 模型同步修改、动库前 backup-db.sh（注意《13》⚠️-23 的防呆缺口先修复）、动完跑冒烟第 2 节验证。
六条路径之外，还有两类没有固定路径的任务，给出兜底方法。性能类任务（"同步怎么变慢了""首屏卡"）：先读《10》§1 的负载画像判断问题属于哪一层（渲染、网络还是数据库），再按其 §7 的度量方法取基线数——没有基线不要动手改，这是《10》反复强调的纪律。安全事件类任务（"有人刷我接口""疑似数据串号"）：先读《08》§1 的威胁模型定位边界被突破的位置，再按 §9 的隐患清单对照是否属于已知项；涉及云数据的越权怀疑，一律先复核 dataAccess 准入链路与 test/routes/dataRoutes.test.ts 的钉子用例，确认防线是否还在原位。兜底之后还有共同的一步：若排查中发现文档与源码不一致，把不一致登记进《13》的债务清单，并回到本篇第 7 节的维护约定执行同步——索引的准确性本身就是这个项目的运维能力之一，路径可以走错一次，索引不能错第二次。
| 篇目 | 一句话定位 |
|---|---|
| 00-项目总览 | 项目是什么、功能清单、技术栈速览、快速上手 |
| 01-系统架构 | 前后端分层、端到端数据流、关键设计决策概览 |
| 02-页面设计 | 组件树、终端 UI 交互、Pinia 状态设计 |
| 03-接口设计 | REST 契约、认证机制、错误处理约定 |
| 04-数据模型 | MySQL 表、blob 内部结构、八键结构、内存态 |
| 05-核心流程 | 命令执行/登录/云同步/找回/注销五条端到端时序 |
| 06-部署运行 | 本地开发、Docker 链路、运维备份、测试体系 |
| 07-模块详解 | 逐模块职责与依赖地图 |
| 08-安全与权限设计 | 威胁模型、会话/口令/验证码/准入纵深 |
| 09-测试与质量保障 | 双轨测试四层金字塔、门禁、缺口分析 |
| 10-性能设计与优化 | 负载画像、渲染/同步/DB 成本、优化清单 |
| 11-扩展开发指南 | 六个 SOP：加命令/接口/同步类型/配置/迁移 |
| 12-FAQ 与故障排查 | 报错速查、根因机理、排查决策树 |
| 13-技术债务与演进建议 | 债务清单（A/B/C 档）、取舍登记表、扩容路线 |
| 14-配置与环境详解 | 配置两条总线、nuxt.config 走读、环境变量全量 |
| 15-接口全量参考 | 全部端点参数表与命令注册表速查 |
| 16-决策记录 ADR | 12 条关键决策的背景/备选/决策/证据/后果 |
| 17-依赖全景 | 29 个依赖逐个解析与健康度评估 |
| 18-代码走读实录 | 三条核心路径的逐段带码走读 |
| 19-数据契约与示例集 | 10 个核心接口的完整报文示例与 curl |
| 20-术语表与文档索引 | 术语表、文件反向索引、任务阅读路径（本篇） |
索引类文档最大的风险是腐化——文件改名、篇目调整都会让对照表失真。给本篇立三条维护约定。其一，改名同步：任何源码文件改名/删除时，必须 grep 本篇第 4 节的文件列并同步（《13》⚠️-18 的教训：注释指错文件比没有注释更误导，索引同理）。其二，新增篇目顺延：第 6 节总索引只增不改号，保证跨篇引用稳定（与《13》债务编号"保留空洞不作重排"同一原则）。其三，术语复议：若某术语在源码里改名（例如墓碑换成删除标记），旧术语保留一行并标注"已更名，见新术语"，而不是原地覆盖——术语表是理解旧文档与新代码之间翻译层，翻译层断裂的成本高于表行数增长。三条约定的共同目的是让第 1 节的承诺持续成立：本篇不生产事实，只索引事实；索引的价值完全取决于它与源码的同步频率。