# M11 / issue-99 M2 鉴权与角色教程正文

- Issue：`#99`
- 里程碑：`M11 教程正文整理：从大纲到系列文章`
- 分支：`fys-dev/docs-m11-issue-99-m2-auth-article`
- 日期：`2026-03-27`

## 背景

仓库已经完成 `M1 ~ M10` 的第一轮功能闭环，也已经具备里程碑大纲、开发日志和 README 导览，但面向外部读者的正文教程仍未开始落地。

为了继续保持“渐进式、可教学、可追踪”的节奏，本轮先从 `M2` 开始，把现有大纲扩展为第一篇可独立阅读的正文文章。

## 本次目标

- 在 `docs/50-教程文章/` 下建立正文文章目录
- 将 `M2` 教程大纲扩写为一篇完整正文
- 保持文章聚焦 `M2`，不越界进入 `M3 ~ M10`
- 让正文和开发日志、教程大纲之间形成清晰分层

## 非目标

- 不新增任何功能代码
- 不重构现有 `M2` 实现
- 不一次性扩写 `M3 ~ M10` 全部正文
- 不把正文写成开发日志或提交清单

## Plan

1. 先复盘 `M2` 大纲与 `issue-05 ~ issue-09` 开发日志，确认正文素材是否充足
2. 在 GitHub 创建 `M11` 与 `issue-99`，把教程整理也纳入标准流程
3. 编写 `M2` 正文与 `docs/50-教程文章/README.md`
4. 做一轮文档级 review 与手动校对，再进入提交阶段

## 实际改动

- 新增 `docs/50-教程文章/README.md`
- 新增 `docs/50-教程文章/01-M2-鉴权与角色-为什么先做最小登录闭环.md`
- 新增本篇开发日志，记录本轮文档任务

## Review 记录

### 是否符合当前 Issue 与里程碑目标

符合。当前只做了：

- 建立正文文章目录
- 扩写 `M2` 正文
- 补充本轮文档任务日志

没有提前进入：

- `M3 ~ M10` 正文扩写
- 功能实现改动
- 文档体系大规模重排

### 是否可继续抽离复用结构

- `docs/50-教程文章/README.md` 已形成正文目录入口，后续 `M3 ~ M10` 可继续追加
- 当前正文结构可作为后续里程碑文章的写作模板：
  - 为什么先做这个
  - 里程碑目标
  - issue 拆解顺序
  - 关键设计取舍
  - 测试思路
  - 踩坑
  - 与下一里程碑的衔接

### Review 结论

- 通过
- 可进入文档级自测

## 自测结果

### 1. 文档结构校对

- 检查 `docs/50-教程文章/README.md` 是否能作为正文入口
- 结果：通过

### 2. 正文范围校对

- 检查文章是否仍聚焦 `M2`
- 结果：通过
- 备注：正文以“为什么先做最小登录闭环”为主线，没有扩写到后续功能细节

### 3. 分层校对

- 检查正文、大纲、开发日志是否职责清晰
- 结果：通过
- 结论：
  - `docs/40-教程与博客/` 继续承载里程碑大纲
  - `docs/30-开发日志/` 继续承载 issue 过程记录
  - `docs/50-教程文章/` 开始承载对外正文

## 遇到的问题

### 1. 容易把正文写成开发日志

- 风险：如果沿着 issue 顺序平铺，很容易变成“做了什么”的流水账
- 处理：改成围绕“为什么先做鉴权与角色”来组织正文结构

### 2. 容易一次性把所有里程碑都写满

- 风险：这样会再次失去教程节奏
- 处理：本轮只落 `M2`，先把正文写作流程走通

## 后续可继续沉淀的点

- 为 `M3 ~ M10` 建立连续的正文文章目录
- 逐步把已有大纲扩成正文
- 在正文足够丰富后，再整理适合公开发布的系列文章导航或 VitePress 侧边栏
