diff --git a/.planning/phases/10-docs-restructure/10-34-SUMMARY.md b/.planning/phases/10-docs-restructure/10-34-SUMMARY.md new file mode 100644 index 0000000..3de1760 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-34-SUMMARY.md @@ -0,0 +1,145 @@ +--- +phase: 10-docs-restructure +plan: 34 +subsystem: docs +tags: [vitepress, markdown, advanced-iii, loading, loader, extension-points] + +requires: + - phase: 10-docs-restructure + provides: 10-33 已完成 docs/advanced 目录重组,高级 I / II 位于 i/ 与 ii/,III 侧边栏为空 +provides: + - docs/advanced/iii/loading-system.md:数据端加载系统的模型、阶段、配置与三类扩展点 + - 全文唯一的渲染端内容,限定在「渲染端如何消费加载进度」接口级小节 +affects: [10-39 侧边栏注册与互链, 10-40 读者审阅] + +actuals: + tokens: 3830 + tasks: 3 + commits: 2 + plan_head_before: b4083fb9ce0140343c28f344bec4d8001d15202b + +tech-stack: + added: [] + patterns: + - 系统类页面先讲模型再讲接口(D-82):LoadTask → LoadManager → MotaDataLoader 三层,ILoadTaskStarter 作为环境适配点 + - 使用与自定义各半(D-77):主干讲阶段顺序与配置约定,扩展点集中讲「加配置 / 加资源 / 换环境」 + - 边界与特殊情况统一放文末「边界与注意」(D-61) + - 代码块给完整类 / 函数上下文并带解释性注释(D-62 / D-65 / D-70) + - 渲染端内容只做接口级消费,不写场景、UI 生命周期与 ClientCore 初始化顺序 + +key-files: + created: + - docs/advanced/iii/loading-system.md + - .planning/phases/10-docs-restructure/10-34-SUMMARY.md + modified: [] + +key-decisions: + - Task 0 的汇报关卡已由用户预批准满足:用户明确表示「这些都是文档编写工作,不涉及代码本身,直接批准执行 10-33 至 10-37」,本计划据此继续,未再单独等待「可以执行」 + - 页面按「模型 → 阶段 → 配置 → 三个扩展点 → 进度 → 渲染端接口小节 → 边界」组织;渲染端内容不单独成页 + - 不写 getTotalByte 的总字节语义、不承诺 loading / dataLoaded 只加载一次、不写重复配置 id 的稳定告警(D-72) + - 自定义任务示例显式按 DEV / 构建后分别给出地址,因为自行构造的 LoadTask 地址不会被加载器改写 + - 本地数据包只作为 ILoadTaskStarter 的设计能力一句话说明,不给实现代码 + - 未在 docs/.vitepress/config.ts 注册本页,也未链接尚不存在的 III 页面;留给 10-39 + +patterns-established: + - 高级 III 页面的结构:系统模型 → 阶段 / 关键接口 → 扩展点 → 进度等观察量 → 接口级渲染端小节 → 边界 + - 页面内至少保留一条 ../i/ 或 ../ii/ 链接与一条 ../../intermediate/ 链接,用于把读者接回既有教程 + +requirements-completed: [] + +coverage: + - id: D1 + description: 加载三层模型、六段阶段顺序与 CoreState.load 的插件时机包裹关系写清 + verification: + - kind: other + ref: '10-34-PLAN.md Task 1 自动门禁 PAGE-OK;人工对照 packages/loader/src/* 与 packages-user/data-state/src/loader/*' + status: pass + human_judgment: false + - id: D2 + description: 三类扩展点各有完整代码块,渲染端内容限定在接口级小节,边界集中在文末 + verification: + - kind: other + ref: '10-34-PLAN.md Task 1 自动门禁 PAGE-OK;构建产物 h1=1、language-ts=3、language-text=3、table=3' + status: pass + human_judgment: false + - id: D3 + description: prettier --check 通过,构建 build complete 且无 dead link + verification: + - kind: other + ref: 'prettier --check 通过;cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 输出 build complete in 19.28s,无 dead link' + status: pass + human_judgment: false + +duration: 约 10 分钟 +completed: 2026-10-26 +status: complete +--- + +# Phase 10 Plan 34: 加载系统原理页 Summary + +**写出高级 III 第一篇数据端原理页:以 `LoadTask` → `LoadManager` → `MotaDataLoader` 三层模型开场,讲清六段加载顺序与配置约定,再给出「加配置 / 加资源 / 换环境」三类扩展点;渲染端只保留接口级消费小节,边界统一收口到文末。** + +## Performance + +- **Duration:** 约 10 分钟 +- **Started:** 2026-10-26T20:46:36Z +- **Completed:** 2026-10-26 +- **Tasks:** 3/3(Task 0 由用户预批准满足;Task 1 / Task 2 已执行) +- **Files created:** 2(页面 + 本 SUMMARY) + +## Accomplishments + +- 新建 `docs/advanced/iii/loading-system.md`,单 H1《加载系统》,246 行。 +- 主体结构为:`系统模型` → `一次加载的阶段` → `配置文件与处理器` → `扩展点:加一份配置` → `扩展点:加一种资源` → `扩展点:换一个加载环境` → `进度` → `渲染端如何消费加载进度` → `边界与注意`。 +- 系统模型讲清三层职责与 `ILoadTaskStarter` 的环境适配点;阶段小节给出「核心配置 → onCoreConfigLoaded → 额外配置 → onExtraConfigLoaded → 自定义任务 → 完成」,并说明 `CoreState.load()` 把插件 `initialize` 放在 `loader.start()` 之前、`afterLoad` 放在之后。 +- 配置小节讲清 JSONC 前缀切分、前缀缺失 / JSON 解析失败的表现为空对象、`addCoreConfig` 与 `addExtraConfig` 的差异、额外配置 URL 相对内容目录,以及加载器统一处理 DEV / 构建路径。 +- 三类扩展点均给出完整类或函数上下文并带解释性注释:插件 `initialize` 中 `addExtraConfig`;`LoadTask` + processor + starter + `addCustomTask`;实现 `ILoadTaskStarter` 的 `BaseURLLoadStarter`。 +- 渲染端小节只保留接口级消费:`RenderLoaderHooks` 追加渲染侧配置,加载场景迭代同一个 `loader.start()` 并从 `loader.manager` 读计数。 +- 文末「边界与注意」覆盖:配置 id 去重、`addCustomTask` 调用时机、前缀缺失 / 解析失败、自定义任务路径、starter 返回契约、自定义任务必须设置 starter、字节进度在总量未知时可能不准、`start()` 必须被迭代。 + +## Fact Verification + +正文事实按当前源码复核,research 的行号未直接搬入页面: + +- `packages/loader/src/task.ts`、`manager.ts`、`types.ts`、`starter.ts`:`LoadTask`、`LoadManager`、`ILoadTaskStarter` / `IResponseLike`、`LoadDataType` 五值、`WebLoadStarter`。 +- `packages-user/data-state/src/loader/loader.ts`、`types.ts`、`jsoncProcessor.ts`:`addCoreConfig` / `addExtraConfig` / `addCustomTask` / `getConfig`、六段顺序、`PrefixedJSONCProcessor` 的前缀与 66 / 67 错误处理、额外配置 URL 相对内容目录。 +- `packages-user/data-state/src/core.ts`:`CoreState.load()` 的 `initialize` → `loader.start()` → `afterLoad`。 +- `src/data/loader/hook.ts`:`DefaultDataLoaderHook` 从核心配置追加 `enemy` / `item` / `map-list` / `tile` 等额外配置。 +- `packages-user/client-modules/src/loader/hook.ts`:`RenderLoaderHooks` 追加贴图 / 音频 / 动画 / 字体配置。 +- `src/client/entry.ts`、`src/client/ui/load.tsx`、`packages-user/client-modules/src/client.ts`:渲染端复用数据端配置、追加 `client` 核心配置、加载场景迭代 `loader.start()` 并读取 manager 计数。 +- 与 research 的模型与接口描述一致;执行中发现的注释 / 实现与 research 描述不一致的疑点,已只在对话报告,未写入正文(D-72)。 + +## Deliberately Not Written + +- `getTotalByte` 的「总字节」语义;正文只描述已加载字节、任务数与比例。 +- 「`loading` / `dataLoaded` 守卫只加载一次」的承诺。 +- 重复配置 id 的稳定告警码;只写「同一 id 只登记一份配置」。 +- File System Access API / 本地数据包的实现代码;只说明 `ILoadTaskStarter` 支持这种设计能力。 +- 渲染场景结构、UI 生命周期、`ClientCore` 初始化顺序;也因而全文没有出现 `src/client`。 +- 源码行号、源码叙述、「模板」与「[需改]」标记(D-80 / D-83)。 + +## Gates + +- `node node_modules/prettier/bin/prettier.cjs --check docs/advanced/iii/loading-system.md`:通过(All matched files use Prettier code style)。 +- 结构门禁:CRLF、单 H1、九个主体小节齐备、`src/client` 未出现、无模板标记、相对 `.md` 链接目标全部存在。 +- 构建门禁:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,退出码 0,输出 `build complete in 19.28s`,无 `dead link`。 +- 渲染抽查:构建产物 `public/_docs/advanced/iii/loading-system.html` 中页面 H1 = 1、TS 代码块 = 3、text 代码块 = 3、表格 = 3,标题层级与代码高亮正常。 + +## Handoff to 10-39 + +- 本页尚未注册进 `docs/.vitepress/config.ts` 的「高级 III · 原理与架构」分组(`items: []`),也未链接尚未存在的 III 导览或其它 III 页面。 +- 10-39 需要:注册本页到侧边栏、替换 `docs/advanced/index.md` 与 `docs/advanced/ii/index.md` 中「高级 III 尚未编写」的占位,并在 III 导览中把本页列入阅读路径。 + +## Deviations from Plan + +None - 计划按既定任务执行;Task 0 的汇报关卡由用户预批准满足,已记录在 `key-decisions`。 + +## Issues Encountered + +- 工作区存在与本计划无关的既有改动(`packages-user/client-base/*`、`.planning/phases/09-*`、`packages-user/client-base/src/map/__test__/`),所有提交均只暂存本计划文件。 + +## Self-Check: PASSED + +- 文件存在:`docs/advanced/iii/loading-system.md`、`.planning/phases/10-docs-restructure/10-34-SUMMARY.md` +- 提交存在:`16b91af`(Task 1)、本 SUMMARY 的 Task 2 提交 +- 门禁存在:prettier `--check` 通过、`build complete in 19.28s`、无 dead link、`PAGE-OK` diff --git a/docs/advanced/iii/loading-system.md b/docs/advanced/iii/loading-system.md index 565952e..511e8d9 100644 --- a/docs/advanced/iii/loading-system.md +++ b/docs/advanced/iii/loading-system.md @@ -206,7 +206,7 @@ export class BaseURLLoadStarter implements ILoadTaskStarter { ## 进度 -`LoadManager` 是异步迭代器:`load()` 每推进一次,迭代值就是当前已加载的字节数。`MotaDataLoader.start()` 把同样的迭代值转发出来,所以 `for await` 迭代加载器就能跟着加载进度走。 +`LoadManager` 的 `load()` 返回异步迭代器:每推进一次,迭代值就是当前已加载的字节数。`MotaDataLoader.start()` 把同样的迭代值转发出来,所以 `for await` 迭代加载器就能跟着加载进度走。 加载过程中可以读取这些计数: