文档管理系统¶
概述¶
此文件夹包含项目的所有文档，按分类和分级进行组织。
文件夹结构¶
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
│
├── DOCUMENTATION_STRUCTURE.md # 文档分类分级管理体系
└── README.md # 本文件
文档分级¶
第一级：生效文档（01-active）¶
- 定义: 当前项目使用的权威文档
- 特点: 与代码实现保持同步，是开发的唯一真实来源
- 管理: 每次功能变更时更新，版本号和修改日期必须标注
- 查看:
docs/01-active/README.md
第二级：归档文档（02-archived）¶
- 定义: 已过期、废弃或被替代的文档
- 特点: 不再使用，仅供参考，包含历史信息
- 管理: 移入时添加归档日志，标注过期原因和时间
- 查看:
docs/02-archived/README.md
第三级：参考文档（03-reference）¶
- 定义: 管理方案、指南、流程等辅助文档
- 特点: 不涉及具体功能实现，指导开发流程
- 管理: 定期审查，确保仍然适用
- 查看:
docs/03-reference/README.md
快速导航¶
查找生效文档¶
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
查找参考文档¶
Bash
# 查找所有参考文档
find docs/03-reference -name "*.md"
常用文档¶
登录功能¶
- 📖 权威文档:
docs/01-active/LOGIN/login_design_final.md - 📖 快速参考:
docs/01-active/LOGIN/login_quick_reference.md - 📖 归档日志:
docs/02-archived/LOGIN/ARCHIVE_LOG.md
文档管理¶
- 📖 管理体系:
docs/DOCUMENTATION_STRUCTURE.md - 📖 管理方案:
docs/03-reference/DOCUMENTATION_MANAGEMENT.md - 📖 管理总结:
docs/03-reference/DOCUMENTATION_MANAGEMENT_SUMMARY.md
文档更新流程¶
Text Only
功能变更需求
↓
检查是否需要更新现有文档
├─ 是 → 更新 docs/01-active/ 中的文档
└─ 否 → 创建新文档
↓
检查是否需要归档旧文档
├─ 是 → 移入 docs/02-archived/，添加归档日志
└─ 否 → 继续
↓
更新代码实现
↓
更新 CLAUDE.md 中的文档引用
↓
提交 git commit（引用文档路径）
文档审查¶
定期审查（每月）¶
- 检查 docs/01-active/ 中的文档是否与代码一致
- 检查是否有需要归档的文档
- 检查版本号和修改日期是否正确
- 检查是否有遗漏的文档
- 更新 CLAUDE.md 中的文档引用
代码审查时¶
- 检查是否需要更新文档
- 检查文档与代码是否一致
- 检查是否需要添加新文档
与 CLAUDE.md 的关系¶
CLAUDE.md 是项目的主入口文档，应该：
- 引用生效文档 - 指向
docs/01-active/中的文档 - 不引用归档文档 - 除非需要说明历史背景
- 保持简洁 - 只包含关键信息，详细内容在专门文档中
- 定期更新 - 每次文档变更时同步更新
文档命名规范¶
生效文档（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
**版本**: X.Y
**最后更新**: YYYY-MM-DD
**更新者**: 名字
**状态**: ✅ 生效中
## 版本历史
### vX.Y (YYYY-MM-DD)
- 变更说明
### vX.Y-1 (YYYY-MM-DD)
- 变更说明
常见问题¶
Q: 如何找到特定功能的文档？¶
A: 按功能模块查找，例如登录功能在 docs/01-active/LOGIN/ 文件夹中。
Q: 文档过期了怎么办？¶
A: 将其移入 docs/02-archived/，并在 ARCHIVE_LOG.md 中添加记录。
Q: 如何追踪文档变更历史？¶
A: 查看文档顶部的版本历史，或查看 git 提交记录。
Q: 代码与文档不一致怎么办？¶
A: 优先更新文档，然后更新代码，确保文档是真实来源。
Q: 如何创建新文档？¶
A: 参考 DOCUMENTATION_STRUCTURE.md 中的命名规范和版本管理规则。
相关资源¶
- 📋
DOCUMENTATION_STRUCTURE.md- 详细的文档分类分级管理体系 - 📋
CLAUDE.md- 项目主入口文档 - 📋
git log- 查看文档变更历史
最后更新¶
📅 2026-03-15 👤 Claude