首页 / 大项目模块

大项目模块

比功能模块多两份文档的那一档：在「快速了解 + 快速定位 bug + 可复用的技术与实现方式」之上，再加技术方案文档（设计思路 / 模块结构 / 关键实现）和 使用文档（配置方式 / 接入步骤 / 注意事项）。

1. 什么算大项目模块

不看代码行数，看三个信号，命中任意一条就按这一档留档：

有策划要配表 / 摆 Entity

一旦策划要动手，就必须有使用文档。没有使用文档的后果见 W36-01 / W36-04：策划把复活点摆进 StaticMesh，还填了个根本不生效的 Params.Location。

有其他业务方要接入

别人调你的接口，就必须有接入步骤和注意事项。口头交接一次，第三个人来问的时候你已经忘了。

涉及跨端约定（服务器 / 编辑器）

协议字段语义、编辑器 Scheme 校验规则，这些是两方共同持有的契约。不写下来就会出现「两侧对同一字段理解不同」这类最难查的问题。

#	章节	内容	关键判据
1	模块定位	一句话说清管什么、不管什么	边界写出来，尤其「不管什么」
2	技术方案 · 设计思路	为什么这么设计，否决了哪些方案	否决理由比选中方案值钱
3	技术方案 · 模块结构	Controller / Model / Component 各自职责，数据流向	能画出「数据从哪来到哪去」
4	技术方案 · 关键实现	核心时序、状态机、协议握手、异步等待与兜底	贴真实代码片段，标文件行号
5	使用文档 · 配置方式	配置表字段逐个说明、编辑器里在哪填	字段含义 + 取值范围 + 填错的后果
6	使用文档 · 接入步骤	从零接入的有序步骤	照着做能跑通，不需要问人
7	使用文档 · 注意事项	已知限制、不能这么用、容易踩的地方	每条都对应一次真实事故
8	遇到的坑	开发和线上踩过的坑，图文留档	现象 → 根因 → 修法，可分类筛
9	可复用的技术	抽出来能用在别处的手法	下次类似需求直接抄这一节
10	排查速查表	现象 → 先查什么	不写原理，只写「先看哪」

2–4 是技术方案文档，5–7 是使用文档两份文档不建议拆成两个 HTML。同一页里用 <h2> 分开就行—— 拆文件的结果通常是其中一份长期不更新。

这是大项目模块页里唯一会持续增长的章节，也是别人拿不到的部分。留档要求：分类 + 图文。

和问题留档库共用同一套标签，方便交叉检索：

配置摆放时序竞态状态残留语义分歧日志盲区注释误导

写法：容器加 data-filter-scope，每张坑卡加 data-cat="标签1 标签2"，筛选按钮和计数自动生成。

<div data-filter-scope>
  <div class="rec" data-cat="配置摆放 坠落重生">...</div>
  <div class="rec" data-cat="时序竞态 传送">...</div>
</div>

截图直接嵌正文，点击全屏放大。图片放模块自己的 img/ 子目录：

截图projects/{项目名}/img/{序号}-{说明}.png

视频共享盘路径（不嵌页面），用 .attach 记路径

日志原始 .logcompr 路径 + 关键行号

完整写法见周报 · 图文留档的三种写法，和周报共用同一套样式。

建目录

projects/{项目名}/index.html + projects/{项目名}/img/

复制页面骨架

从留档模板 §1 抄，注意 data-root="../../"（多一层目录）。

按 §2 的十个章节填

2–4 技术方案、5–7 使用文档，缺一个都不算大项目模块留档完成。

登记两处

本页 §5 列表 + assets/site.js 的 NAV「大项目模块」组 + assets/search-index.js。

过一遍交付自查清单

交付标准 §4，十条勾满才算交付完成。

传送已按“大项目模块”标准建立文档分类；其他项目后续按 §4 补充。