本文件定义 docs/ 文档维护规则。写讲义时先确定读者学完要能解释、判断和完成什么，再安排阅读路径、概念、示例与练习；修改实践文档时遵守对应的进度和证据规则。
docs/是学习内容与技术决策的权威来源。- 实践进度状态（含卡片状态规则）以 实践计划与进度 为唯一来源，本目录不重复声明。
- 文档修改必须服务学习闭环：概念准确、推理可跟随、结果可验证且来源可追溯。以读者能否解释机制、判断适用边界并迁移到场景为质量标准，不以篇幅、图表或术语数量衡量。
- 阶段零至阶段七保留七段式骨架，段内可按内容需要重排：
- 快速入门。
- 精简大纲。
- 学习内容详情。
- 坑点提醒。
- 本节自检。
- 本节配套思考题。
- 常见面试题。
- 阶段八使用独立模板，不套阶段零至七格式。
- 不删除既有
⏸️ 短期可以不学框、代码块、面试题三层答法、前端对照。 - 快速入门只做导航和最低理解门槛；精简大纲指明先后关系，正文承担机制、场景、代价与工程落点。前置概念必须先于依赖它的推理；延后阅读或跨讲引用不能替代本讲所需的最低解释，也不能形成循环前置。
- 快速入门中的术语导航只保留一个入口，统一使用「本讲关键词与概念速查」；「关键词速查」「关键概念说明」等作用相同的表格须合并，去除重复定义。合并时保留术语、最低解释和典型用途，机制推演与边界条件留在正文。
- 速览区保留代码示例，用于展示形态，不承担可运行承诺；示例旁须说明关键类型、字段的作用及省略之处，不能让读者靠猜测补全。依赖、开关等可运行前提在正文交代。正文中声称可运行的示例则须给出必要定义和前提。
- 坑点提醒为
##级，与学习内容详情平级；只集中提示正文尚未解决的风险。 ⏸️ 短期可以不学框说明暂缓的是实现细节还是整个概念，并写清本讲仍需掌握的基础；自检要求与这个边界一致。小节标题不重复声明同一取舍。- 上述标准约束新写与后续优化的讲义；存量各讲按需优化时对齐，不做批量回溯。
- 简体中文。
- 术语首次出现必须解释，只出现一次的专业词同样必须解释；先讲实体「是什么、怎么用」，再讲机制「为什么好」。后文推理依赖的概念须在使用前解释到位；「详见后文」只用于补充深度，不得留下当前推理的空缺。
- 易混词成对辨析（如幂等 vs 去重、实体 vs 值对象）。不堆术语；同一概念的再次出现须增加场景、边界或对比，避免重复讲定义。
- 类比采用“生活版 → 技术结论”双段式；当类比可能遮蔽关键差异时，补明不成立的边界。面向前端背景读者时，优先使用 NestJS、npm、RxJS、浏览器请求链路做对照，并说明不能直接等同之处。
- 机制类内容优先用 Mermaid，内嵌于 Markdown 文档；不引入外部图表工具或导出独立 HTML。
- Mermaid 类型按内容选择：流程用 flowchart，时序用 sequenceDiagram，状态用 stateDiagram，类关系用 classDiagram，排期用 gantt。
- Mermaid 节点文本包含半角引号或括号时，用
["..."]包裹或改中文标点。 - 引用精确到「阶段 + 讲次」，消除同名编号歧义。
- 标题与小节名的承诺与内容名实相符。
- 核心原理写成推演（分情形 + 图示或推演文本 + 分工），不是一句结论；讲清成立条件、反例或失效边界。绝对化判断须有依据，数字区分有来源的事实与仅用于说明的假设；涉及版本或产品能力的结论须核对权威来源和适用版本。
- 示例中的关键类型、字段须在使用前或紧邻示例处定义其作用；局部代码片段须标明省略项。引用真实工程代码时，说明它验证了什么、还缺哪些完整设计条件，避免把局部实现误当成全部架构规范。
- 生命周期类机制讲完整闭环（含失败分支）。
- 同一主题散落多处时归位：核心主题独立成节，重复信息源合一；对比表置于各概念展开之后。知识图、速览、正文与总结各承担不同用途，重复呈现须增加推理或应用价值。
- 自检与正文双向对齐：考的必须教过，新增重点同步进自检；区分必学与进阶要求。除概念复述外，至少包含一个场景判断或应用问题，并给出可核对的答案要点或判断标准；后续相关讲义适当安排回忆或迁移练习。
- 面试题不得引入正文没有解释过的新概念，既有三层答法须与正文深度匹配。
- 内容查漏以「学完应能回答的问题」清单反向核查，不依赖通读印象。全文修改完成后，再扫一遍未解释的专业缩写与术语、悬空前置、示例省略项和自检答案依据。
- 重命名文件或目录必须同步审计交叉链接。
- 修改文档结构后使用
rg检查旧路径、旧标题、旧文件名。 - 实践卡片完成记录必须写明日期、结果和可复现证据。
- 未验证内容不得标记完成。
- 后端实现导航树 是面向学习的代码地图，按
boot-server/的真实目录层级记录模块、源码和测试入口。 - 目录是分层依据：类写在实际所在的包中，同一文件只列一次；商品等业务域通过对应的
controller、service、mapper、entity等目录体现，不另建虚拟目录汇总或重复列类。 - 描述只保留定位和理解代码所需的职责、关键行为与验证入口，优先短句；接口细节、技术原理和完成证据留在对应文档或卡片，不把导航树写成第二份实现记录。
- 里程碑、卡片编号及「待开始 / 进行中 / 已完成」等进度状态只引用 实践计划与进度，不在导航树复制维护，也不以源码存在推断卡片完成。
- 新增、删除或调整后端模块、关键接口、数据模型、安全机制或测试入口时，同步核对导航树中的路径与描述；计划中的功能不能写成已实现。