ljwx-health/docs/07-compliance/documentation-standards.md

文档管理标准

状态: ✅ 稳定 版本: 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/ - 使用了下划线

---

📄 文档模板

功能文档模板

# {功能名称}

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

---

## 概述

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

## 快速开始

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

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

## 详细说明

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

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

## 配置参考

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

## 故障排查

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

## 相关文档

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

实施报告模板

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

**实施时间**: 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/ 目录
• ✅ 提供归档建议

使用方法:

./scripts/check-doc-location.sh

集成到 Git Hooks:

# .git/hooks/pre-commit
#!/bin/bash
./scripts/check-doc-location.sh

CI/CD 集成

在 GitHub Actions 中自动检查：

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