文档分类分级管理体系¶

文件夹结构¶

Text Only

docs/
├── 01-active/                          # 生效中的文档（权威文档）
│   ├── LOGIN/
│   │   ├── login_design_final.md       # 登录功能完整设计（权威）
│   │   ├── login_quick_reference.md    # 登录快速参考
│   │   └── README.md                   # 登录文档说明
│   ├── AUTHENTICATION/
│   │   ├── superadmin_login.md         # 超级管理员登录
│   │   └── README.md
│   └── README.md                       # 生效文档总览
│
├── 02-archived/                        # 已归档的文档（过期/废弃）
│   ├── LOGIN/
│   │   ├── login_failure_handling_guide.md
│   │   ├── password_login_captcha_guide.md
│   │   ├── security_fixes_password_login.md
│   │   ├── sms_protection_guide.md
│   │   └── ARCHIVE_LOG.md              # 归档日志
│   └── README.md                       # 归档文档总览
│
└── 03-reference/                       # 参考文档（非权威）
    ├── DOCUMENTATION_MANAGEMENT.md     # 文档管理方案
    ├── DOCUMENTATION_MANAGEMENT_SUMMARY.md
    └── README.md                       # 参考文档说明

文档分级¶

第一级：生效文档（01-active）¶

定义：当前项目使用的权威文档
特点：
与代码实现保持同步
定期更新和维护
是开发的唯一真实来源
管理：
每次功能变更时更新
版本号和修改日期必须标注
包含完整的实现细节和测试清单

第二级：归档文档（02-archived）¶

定义：已过期、废弃或被替代的文档
特点：
不再使用，仅供参考
包含历史信息和设计演变过程
便于追踪功能变更历史
管理：
移入时添加归档日志
标注过期原因和时间
保留原始内容，不修改

第三级：参考文档（03-reference）¶

定义：管理方案、指南、流程等辅助文档
特点：
不涉及具体功能实现
指导开发流程和最佳实践
相对稳定，不频繁变更
管理：
定期审查，确保仍然适用
可根据需要更新

归档流程¶

何时归档¶

功能被替代 - 新功能替代旧功能
设计变更 - 功能设计发生重大变更
文档过期 - 文档内容与代码不一致
功能移除 - 功能被完全移除

归档步骤¶

Text Only

1. 确认文档需要归档
   ↓
2. 在 docs/02-archived/{CATEGORY}/ARCHIVE_LOG.md 中添加记录
   ↓
3. 将文档移入 docs/02-archived/{CATEGORY}/
   ↓
4. 更新 docs/01-active/ 中的相关文档
   ↓
5. 更新 CLAUDE.md 中的文档引用
   ↓
6. 提交 git commit

归档日志格式¶

在 docs/02-archived/{CATEGORY}/ARCHIVE_LOG.md 中添加：

Markdown

## 归档记录

### 文档名称
- **原始路径**: docs/01-active/LOGIN/login_failure_handling_guide.md
- **归档时间**: 2026-03-15
- **归档原因**: 被 login_design_final.md 替代
- **关键变更**:
  - 验证码显示时机：失败 2 次后 → 失败 1 次后
  - 失败次数计数：仅手机号 → Phone + IP
- **备注**: 保留用于历史参考，不再使用

文档更新流程¶

Text Only

功能变更需求
  ↓
检查是否需要更新现有文档
  ├─ 是 → 更新 docs/01-active/ 中的文档
  └─ 否 → 创建新文档
  ↓
检查是否需要归档旧文档
  ├─ 是 → 移入 docs/02-archived/，添加归档日志
  └─ 否 → 继续
  ↓
更新代码实现
  ↓
更新 CLAUDE.md 中的文档引用
  ↓
提交 git commit（引用文档路径）

文档命名规范¶

生效文档（01-active）¶

Text Only

{功能名称}_{描述}.md

示例：
- login_design_final.md
- login_quick_reference.md
- superadmin_login.md

归档文档（02-archived）¶

Text Only

{功能名称}_{描述}.md（保持原名）

示例：
- login_failure_handling_guide.md
- password_login_captcha_guide.md

参考文档（03-reference）¶

Text Only

{类型}_{描述}.md

示例：
- documentation_management.md
- git_commit_guidelines.md

文档版本管理¶

每个生效文档顶部应包含：

Markdown

# 文档标题

**版本**: 2.0
**最后更新**: 2026-03-15
**更新者**: Claude
**状态**: ✅ 生效中

## 版本历史

### v2.0 (2026-03-15)
- 修改验证码显示时机：失败 1 次后显示
- 修改失败次数计数：基于 Phone + IP
- 添加短信验证码重发规则

### v1.0 (2026-03-11)
- 初始版本

文档查找指南¶

查找生效文档¶

Bash

# 查找所有生效文档
find docs/01-active -name "*.md"

# 查找特定功能的文档
find docs/01-active -path "*LOGIN*" -name "*.md"

查找归档文档¶

Bash

# 查找所有归档文档
find docs/02-archived -name "*.md"

# 查看归档日志
cat docs/02-archived/LOGIN/ARCHIVE_LOG.md

文档审查清单¶

每月进行一次文档审查：

检查 docs/01-active/ 中的文档是否与代码一致
检查是否有需要归档的文档
检查版本号和修改日期是否正确
检查是否有遗漏的文档
更新 CLAUDE.md 中的文档引用

与 CLAUDE.md 的关系¶

CLAUDE.md 是项目的主入口文档，应该：

引用生效文档 - 指向 docs/01-active/ 中的文档
不引用归档文档 - 除非需要说明历史背景
保持简洁 - 只包含关键信息，详细内容在专门文档中
定期更新 - 每次文档变更时同步更新

示例：

Markdown

## 登录功能文档

**权威文档**: `docs/01-active/LOGIN/login_design_final.md`

所有登录相关的功能设计、实现细节、测试清单都在此文档中。

### 快速参考
- `docs/01-active/LOGIN/login_quick_reference.md`

### 历史文档
- 查看 `docs/02-archived/LOGIN/ARCHIVE_LOG.md` 了解功能演变过程

总结¶

方面	说明
分类	按功能模块分类（LOGIN、AUTHENTICATION 等）
分级	生效 → 归档 → 参考
版本	每个文档标注版本号和修改日期
归档	添加归档日志，说明原因和时间
查找	按分类和分级查找
维护	定期审查，确保一致性

关键原则： - ✅ 生效文档是唯一真实来源 - ✅ 归档文档保留历史信息 - ✅ 参考文档指导开发流程 - ✅ 定期审查，确保一致性