# 文档管理标准

**状态**: ✅ 稳定
**版本**: v2.0
**最后更新**: 2026-01-04

---

## 📋 目录

- [强制规则](#强制规则)
- [目录结构](#目录结构)
- [文档分类规则](#文档分类规则)
- [命名规范](#命名规范)
- [文档模板](#文档模板)
- [生命周期管理](#生命周期管理)
- [自动化检查](#自动化检查)

---

## 🚨 强制规则

**所有新创建的文档必须遵循以下规则，违规文档将被自动检测并要求修正。**

### 规则 1: 根目录文档限制

**允许保留的文档**（最多10个）:
1. `README.md` - 项目主文档
2. `CLAUDE.md` - AI开发指导
3. `CONTRIBUTING.md` - 贡献指南
4. `CHANGELOG.md` - 版本历史
5. `PROMPT_BLUEPRINT.md` - 工程蓝图
6. `LICENSE` / `LICENSE.md` - 开源协议
7. `CODE_OF_CONDUCT.md` - 行为准则（可选）

**禁止**: 任何其他 `.md` 文档直接放在根目录

### 规则 2: 文档必须分类

所有文档必须归类到以下目录之一：
- `docs/` - 活跃的、需要维护的文档
- `archive/` - 历史文档、实施报告

### 规则 3: 命名规范

- ✅ 使用小写字母 + 连字符（kebab-case）
- ✅ 清晰描述文档内容
- ❌ 禁止使用大写字母、下划线、日期后缀

---

## 📂 目录结构

```
ljwx-health/
├── README.md                       # 项目主文档
├── CLAUDE.md                       # AI 开发指导
├── CONTRIBUTING.md                 # 贡献指南
├── CHANGELOG.md                    # 版本历史
├── PROMPT_BLUEPRINT.md             # 工程蓝图
│
├── docs/                          # 活跃文档（按功能分类）
│   ├── README.md                  # 文档导航中心
│   ├── 01-getting-started/        # 快速开始
│   ├── 02-architecture/           # 架构设计
│   ├── 03-deployment/             # 部署指南
│   │   ├── docker/
│   │   ├── kubernetes/
│   │   └── gitops/
│   ├── 04-operations/             # 运维手册
│   │   ├── database/
│   │   ├── monitoring/
│   │   └── troubleshooting/
│   ├── 05-features/               # 功能文档
│   │   ├── health-monitoring/
│   │   ├── geofence/
│   │   └── multi-tenant/
│   ├── 06-development/            # 开发指南
│   │   ├── backend/
│   │   ├── frontend/
│   │   └── api/
│   ├── 07-compliance/             # 工程规范 ⭐ 本文档
│   └── 08-reference/              # 参考资料
│
└── archive/                       # 历史文档（按时间分类）
    ├── 2025/
    │   ├── fixes/                 # 故障修复报告
    │   ├── implementations/       # 实施完成报告
    │   └── experiments/           # 实验性方案
    └── deprecated/                # 已废弃文档
```

---

## 📋 文档分类规则

### docs/ - 活跃文档

#### 01-getting-started/ - 快速开始

**用途**: 帮助新用户快速上手

**内容类型**:
- 环境要求文档
- 快速部署指南
- 开发环境配置
- 常见问题（FAQ）

**示例**:
- `quick-start-docker.md` - Docker 快速启动
- `prerequisites.md` - 环境要求
- `development-setup.md` - 开发环境配置

#### 02-architecture/ - 架构设计

**用途**: 系统架构和设计决策

**内容类型**:
- 系统架构图
- 数据流设计
- 多租户架构
- 可观测性架构

**示例**:
- `system-overview.md` - 系统架构概览
- `data-flow.md` - 数据流设计
- `multi-tenant.md` - 多租户架构

#### 03-deployment/ - 部署指南

**用途**: 生产环境部署文档

**内容类型**:
- Docker 部署指南
- Kubernetes 部署
- GitOps CI/CD 流程

**子目录**:
- `docker/` - Docker Compose 相关
- `kubernetes/` - Helm Charts, K8s 配置
- `gitops/` - GitHub Actions, Argo CD

**示例**:
- `docker/docker-compose.md` - Docker Compose 部署
- `kubernetes/helm-deployment.md` - Helm 部署指南
- `gitops/github-actions.md` - GitHub Actions 工作流

#### 04-operations/ - 运维手册

**用途**: 日常运维操作文档

**内容类型**:
- 数据库运维（Flyway、备份）
- 监控告警（Grafana、Prometheus）
- 故障排查手册

**子目录**:
- `database/` - 数据库相关
- `monitoring/` - 监控告警
- `troubleshooting/` - 故障排查

**示例**:
- `database/flyway-migrations.md` - 数据库迁移
- `monitoring/grafana-dashboards.md` - Grafana 仪表板
- `troubleshooting/common-issues.md` - 常见问题排查

#### 05-features/ - 功能文档

**用途**: 核心功能说明和使用指南

**内容类型**:
- 功能详细说明
- 用户指南
- API 使用示例

**子目录**:
- `health-monitoring/` - 健康监测相关
- `geofence/` - 电子围栏
- `multi-tenant/` - 多租户功能

**示例**:
- `health-monitoring/alert-system.md` - 告警系统
- `health-monitoring/data-flow-dashboard.md` - 数据流监控
- `geofence/geofence-rules.md` - 围栏规则配置

#### 06-development/ - 开发指南

**用途**: 开发规范和技术指南

**内容类型**:
- 后端开发规范
- 前端开发规范
- API 开发指南

**子目录**:
- `backend/` - Spring Boot 后端
- `frontend/` - Vue3 前端
- `api/` - API 设计和 OpenAPI

**示例**:
- `api/openapi-codegen-guide.md` - OpenAPI 代码生成指南
- `backend/coding-standards.md` - 后端编码规范
- `frontend/component-guidelines.md` - 组件开发指南

#### 07-compliance/ - 工程规范

**用途**: 代码规范、审查流程、安全规范

**内容类型**:
- 文档管理标准 ⭐ 本文档
- 代码审查清单
- 安全规范
- Git 提交规范

**示例**:
- `documentation-standards.md` - 文档管理标准
- `code-review-checklist.md` - 代码审查清单
- `security-guidelines.md` - 安全规范

#### 08-reference/ - 参考资料

**用途**: API 参考、配置参考、工具列表

**内容类型**:
- API 接口文档
- 环境变量配置
- 工具和依赖清单

**示例**:
- `api-reference.md` - API 参考文档
- `environment-variables.md` - 环境变量说明
- `tools-and-dependencies.md` - 工具清单

---

### archive/ - 历史文档

#### archive/2025/fixes/ - 故障修复报告

**用途**: 记录故障修复过程

**内容类型**:
- Bug 修复报告
- 故障排查记录
- 临时解决方案

**示例**:
- `DATA_FLOW_MENU_FIX.md` - 数据流菜单修复
- `login-timeout-fix.md` - 登录超时问题修复

#### archive/2025/implementations/ - 实施完成报告

**用途**: 记录功能实施过程

**内容类型**:
- 功能实施报告
- 性能优化报告
- 技术方案实施记录

**示例**:
- `OPENAPI_CODEGEN_IMPLEMENTATION.md` - OpenAPI 代码生成实施报告
- `alert-optimization-report.md` - 告警系统优化报告

#### archive/2025/experiments/ - 实验性方案

**用途**: 记录技术实验和探索

**内容类型**:
- 技术选型调研
- 性能测试报告
- 概念验证（POC）

**示例**:
- `performance-test-plan.md` - 性能测试方案
- `cache-strategy-experiment.md` - 缓存策略实验

#### archive/deprecated/ - 已废弃文档

**用途**: 存放过时的、不再维护的文档

**内容类型**:
- 旧版本文档
- 已废弃的功能说明
- 历史技术方案

**示例**:
- `old-deployment-guide.md` - 旧版部署指南

---

## 🚦 文档创建决策树

```
创建新文档时，按以下顺序判断：

1️⃣ 是否是项目核心文档？
   ├─ 是 → 根目录（必须经过审批）
   │        示例：README.md, CLAUDE.md
   └─ 否 → 继续判断 ⬇️

2️⃣ 是否是活跃的、需要维护的文档？
   ├─ 是 → docs/ 目录
   │   ├─ 快速开始? → docs/01-getting-started/
   │   ├─ 架构设计? → docs/02-architecture/
   │   ├─ 部署指南? → docs/03-deployment/
   │   ├─ 运维手册? → docs/04-operations/
   │   ├─ 功能说明? → docs/05-features/
   │   ├─ 开发指南? → docs/06-development/
   │   ├─ 工程规范? → docs/07-compliance/
   │   └─ 参考资料? → docs/08-reference/
   └─ 否 → 继续判断 ⬇️

3️⃣ 是否是历史实施报告、修复记录？
   ├─ 是 → archive/2025/
   │   ├─ 故障修复? → archive/2025/fixes/
   │   ├─ 实施报告? → archive/2025/implementations/
   │   └─ 实验方案? → archive/2025/experiments/
   └─ 否 → 继续判断 ⬇️

4️⃣ 是否是已废弃的文档？
   ├─ 是 → archive/deprecated/
   └─ 否 → 重新评估或咨询维护者
```

---

## 📝 命名规范

### 文件命名

**推荐格式**: `{主题}-{子主题}.md`

**✅ 正确示例**:
- `quick-start-docker.md` - 清晰描述内容
- `openapi-codegen-guide.md` - 使用连字符分隔
- `alert-system.md` - 简洁明了

**❌ 错误示例**:
- `QuickStartDocker.md` - 使用了大写字母
- `quick_start_docker.md` - 使用了下划线
- `guide-20260104.md` - 包含日期后缀
- `doc1.md` - 内容不清晰

### 目录命名

**推荐格式**: `{编号}-{主题名称}/`

**✅ 正确示例**:
- `01-getting-started/`
- `06-development/`
- `health-monitoring/`

**❌ 错误示例**:
- `GettingStarted/` - 使用了大写
- `getting_started/` - 使用了下划线

---

## 📄 文档模板

### 功能文档模板

```markdown
# {功能名称}

**状态**: ✅ 稳定 / 🔧 Beta / ⚠️ 实验性
**版本**: v{x.y.z}
**最后更新**: YYYY-MM-DD

---

## 概述

[1-2段功能说明，解释这个功能是什么、解决什么问题]

## 快速开始

[最简单的使用示例，让用户快速上手]

\`\`\`bash
# 示例命令
\`\`\`

## 详细说明

### 功能 A
[详细说明]

### 功能 B
[详细说明]

## 配置参考

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| ... | ... | ... | ... |

## 故障排查

### 问题 1: {问题描述}
**原因**: ...
**解决方案**: ...

## 相关文档

- [相关文档 1](./related-doc-1.md)
- [相关文档 2](./related-doc-2.md)
```

### 实施报告模板

```markdown
# {功能/优化} 实施完成报告

**实施时间**: YYYY-MM-DD
**实施方案**: {方案名称}
**负责人**: {姓名}

---

## 实施总结

### 问题背景
[描述要解决的问题]

### 解决方案
[描述实施的方案]

## 已完成的工作

### 1. {工作项 A}
- ✅ {具体任务}
- ✅ {具体任务}

### 2. {工作项 B}
- ✅ {具体任务}

## 核心收益

| 指标 | 优化前 | 优化后 | 提升幅度 |
|------|-------|-------|---------|
| ... | ... | ... | ... |

## 验收标准

- ✅ {验收项 1}
- ✅ {验收项 2}

## 下一步建议

1. ⏳ {待办事项}
2. ⏳ {待办事项}

---

**文档版本**: v1.0
**归档时间**: YYYY-MM-DD
```

---

## 🔄 生命周期管理

### 1. 创建阶段

**步骤**:
1. 使用决策树确定文档类型和位置
2. 选择合适的文档模板
3. 使用规范的文件名创建文档
4. 添加状态标识和版本信息

**检查清单**:
- [ ] 文档位置符合规范
- [ ] 文件名使用 kebab-case
- [ ] 包含状态标识和版本
- [ ] 添加到 docs/README.md 导航（如果是重要文档）

### 2. 活跃阶段

**维护规则**:
- 定期更新"最后更新"日期
- 维护文档状态标识
  - ✅ **稳定**: 已验证，可用于生产
  - 🔧 **Beta**: 功能可用，但可能有变更
  - ⚠️ **实验性**: 仅供测试
- 保持文档与代码同步

### 3. 归档阶段

**归档条件**:
- 功能实施完成 → `archive/2025/implementations/`
- 故障修复完成 → `archive/2025/fixes/`
- 实验结束 → `archive/2025/experiments/`
- 文档过时 → `archive/deprecated/`

**归档步骤**:
1. 添加归档标记到文档顶部
2. 移动到对应的 archive/ 子目录
3. 从 docs/README.md 中移除导航链接（如有）
4. 更新 CHANGELOG.md

---

## 🛠️ 自动化检查

### 检查脚本

**位置**: `scripts/check-doc-location.sh`

**功能**:
- ✅ 检查根目录是否有违规文档
- ✅ 统计 docs/ 目录结构
- ✅ 统计 archive/ 目录
- ✅ 提供归档建议

**使用方法**:
```bash
./scripts/check-doc-location.sh
```

**集成到 Git Hooks**:
```bash
# .git/hooks/pre-commit
#!/bin/bash
./scripts/check-doc-location.sh
```

### CI/CD 集成

在 GitHub Actions 中自动检查：

```yaml
name: 文档合规性检查

on: [push, pull_request]

jobs:
  doc-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 检查文档位置
        run: ./scripts/check-doc-location.sh
```

---

## ✅ 检查清单

创建文档时，请确认：

- [ ] 文档位置符合分类规则
- [ ] 文件名使用 kebab-case
- [ ] 包含状态标识（✅/🔧/⚠️）
- [ ] 包含版本号
- [ ] 包含"最后更新"日期
- [ ] 内容清晰、格式规范
- [ ] 添加到导航（如果是重要文档）
- [ ] 通过自动化检查脚本

---

## 📞 问题反馈

如有文档管理相关问题，请：

1. 查看 `CLAUDE.md` 中的简化版规范
2. 运行 `./scripts/check-doc-location.sh` 获取建议
3. 提交 Issue 或 Pull Request

---

**本文档本身也是一个示例**，展示了如何编写符合规范的文档。

**最后更新**: 2026-01-04
**维护者**: LJWX Health Team