mirror of
https://github.com/motajs/template.git
synced 2026-10-30 04:40:18 +08:00
docs(10-34): 加载系统原理页收口
This commit is contained in:
parent
16b91afdce
commit
e0c7be2953
145
.planning/phases/10-docs-restructure/10-34-SUMMARY.md
Normal file
145
.planning/phases/10-docs-restructure/10-34-SUMMARY.md
Normal file
@ -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<T,R>`、`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`
|
||||
@ -206,7 +206,7 @@ export class BaseURLLoadStarter implements ILoadTaskStarter {
|
||||
|
||||
## 进度
|
||||
|
||||
`LoadManager` 是异步迭代器：`load()` 每推进一次，迭代值就是当前已加载的字节数。`MotaDataLoader.start()` 把同样的迭代值转发出来，所以 `for await` 迭代加载器就能跟着加载进度走。
|
||||
`LoadManager` 的 `load()` 返回异步迭代器：每推进一次，迭代值就是当前已加载的字节数。`MotaDataLoader.start()` 把同样的迭代值转发出来，所以 `for await` 迭代加载器就能跟着加载进度走。
|
||||
|
||||
加载过程中可以读取这些计数：
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user