可复用技术知识库模板 private
可复用技术知识库模板
这不是 QMGame 的运行时实现，而是以后分析任何 Unity/前后端模块时使用的文档模板。目标是让知识可以迁移，而不是只留下某个项目的类名列表。
1. 每个模块固定回答的八个问题
新建模块文章时按下面顺序写，不要把代码、流程和经验混成一段：
- 一句话结论：这个模块的真实职责是什么。
- 边界：它属于 Logic、Rendering、Network、Server、Editor 还是 Content Pipeline。
- 输入和输出：输入事件/配置/资源，输出状态/对象/消息/文件。
- 完整时序：从入口到完成、失败、取消和重试。
- 源码证据：类、方法、资产、配置字段和协议名。
- 可扩展点：新增角色、地图、技能、节点或平台时要改什么。
- 排错矩阵：现象对应的第一检查点和下一跳。
- 跨项目抽象：去掉项目名后，哪些接口和原则可以直接复用。
2. 推荐文章骨架
# [模块名]
> 一句话结论。说明本文范围，不解释哪些内容。
[返回目录](/topics/qmgame-technical-guide/)
## 1. 结论和边界
## 2. 运行时/编辑器/服务端职责
## 3. 输入、输出和数据结构
## 4. 端到端时序
## 5. 关键代码（每段先解释再贴代码）
## 6. 配置和资产制作
## 7. 生命周期、取消、重试和销毁
## 8. 联机/跨线程/异步边界
## 9. 新项目迁移步骤
## 10. 排错矩阵
## 11. 源码索引和证据等级每个小节只回答一个问题。一个小节超过两个屏幕时，拆成二级文章，并在目录中保留“快速导读”和“深入实现”两条入口。
3. 证据等级
文档必须把“代码确认的事实”和“设计建议”分开：
| 标记 | 含义 | 写法 |
|---|---|---|
SOURCE | 在源码、Prefab、Controller 或协议中直接确认 | 给出文件路径、类/方法和关键字段 |
ASSET | 在 Unity 资源序列化文件或 Inspector 配置中确认 | 给出资源路径、GUID 或字段名 |
RUNTIME | 通过运行日志、Profiler 或复现确认 | 给出复现条件和观察点 |
INFERRED | 根据多个事实推导，尚未直接观测 | 明确写“推断”，不要写成确定事实 |
RECOMMENDATION | 面向新项目的改进建议 | 与当前项目实现分段 |
禁止把“典型 Unity 做法”写成“当前项目就是这样做的”。如果没有读到 Controller 资源、Prefab 或服务端处理器，只能写成待验证项。
4. 流程图和代码的写法
4.1 流程图
先画责任边界，再画调用细节：
flowchart LR
Input[输入/网络/编辑器] --> Logic[Logic 状态]
Logic --> Adapter[跨层接口]
Adapter --> View[Rendering]
View --> Feedback[VFX/Audio/UI/Camera]
跨端流程使用 sequenceDiagram，并标出消息方向、权威端和失败回包。
4.2 关键代码
代码片段必须同时说明：
- 它在哪个生命周期阶段执行。
- 它读取哪个输入。
- 它改变哪个状态。
- 它为什么不能被另一层直接替代。
- 如果复制到别的项目，哪些类型需要替换。
不要整段粘贴 200 行文件；只保留能证明结论的 5-30 行，并链接完整源码路径。
5. 迁移说明的固定格式
任何可复用模块，都写一张“迁移表”：
| QMGame 依赖 | 新项目替换为 | 保留的抽象 |
|---|---|---|
MessageCenter | 任意事件总线 | 生命周期事件和订阅释放 |
| Entitas Context | ECS/领域容器 | 实体、事件、系统顺序 |
AddressablesX/AMF | Addressables/AssetBundle/Resources | 异步句柄、引用计数、失败处理 |
WorldAdapter | 世界会话对象 | 当前地图、当前玩家、场景状态 |
CameraManager | 相机编排器 | 相机选择、目标绑定、效果栈 |
MapProcessor | 地图解析器 | 数据文件到运行时元素的转换 |
迁移步骤要可执行：依赖清单、接口替换、资源重建、网络契约、测试场景、验收日志。
6. 生命周期和资源所有权
每篇文章都必须明确：
- 谁创建对象。
- 谁持有引用。
- 谁负责异步完成后的二次有效性检查。
- 谁销毁、回收或取消订阅。
- 切图、重连、对象池复用时如何避免旧回调污染新对象。
对于 Camera、VFX、Animator、NavMesh、UI 等表现对象，必须说明它们是否拥有逻辑状态。通常表现对象只消费逻辑状态，不应成为权威数据源。
7. 复用前的验收清单
- 能从目录在三分钟内找到入口、时序、源码和排错段落。
- 当前项目事实与通用建议分开。
- 所有关键结论都有文件或资源证据。
- 正常、失败、取消、重试、重连和销毁路径都写了。
- 依赖项目专有类型的地方都有替换表。
- 代码片段能解释，而不是只有粘贴。
- 变更后同步更新目录、交叉链接和源码索引。
- 文章标题不使用项目临时名，使用可搜索的能力名。
8. 维护策略
文档更新与代码改动按模块绑定：
| 代码改动 | 至少检查的文章 |
|---|---|
| Scene/Map/Addressables | 场景加载、地图流水线、资源加载、排错 |
| Camera/Follow/Shake | Rendering、玩家动画/表现、相机专题 |
| Hero spawn/PlayerId | 玩家创建、联机同步、Loading Ready |
| NavMesh/MoveController | 客户端寻路、服务端校验、联机同步 |
| Protocol/Session/Battle | 网络协议、联机同步、服务端分布式 |
| Editor exporter/config | Editor 扩展、内容生产、配置模块 |
每次发布时记录：代码版本、资源版本、配置版本、文档更新时间和未验证项。这样下一个项目可以复用“方法”和“验收标准”，而不是误复制旧项目的 GUID、端口或类名。