ljwx-children/docs/workflows/document-management-system.md

📚 完整文档管理系统

🎯 概述

本文档描述了一个完整的软件开发生命周期（SDLC）文档管理系统，涵盖从需求到运维的所有阶段，结合 GitHub 原生功能和自定义平台实现。

📊 软件开发生命周期（SDLC）阶段划分

graph LR
    A[需求分析] --> B[设计阶段]
    B --> C[开发阶段]
    C --> D[测试阶段]
    D --> E[部署阶段]
    E --> F[运维阶段]
    F --> G[迭代优化]
    G --> A

阶段 1: 需求分析（Requirements）

• 输入: 业务需求、用户反馈
• 输出: 需求文档、用户故事、验收标准
• 文档:
  • 业务需求文档 (BRD)
  • 产品需求文档 (PRD)
  • 用户故事 (User Stories)
  • 功能清单 (Feature List)
  • 验收标准 (Acceptance Criteria)

阶段 2: 设计阶段（Design）

• 输入: 需求文档
• 输出: 架构设计、接口设计、数据库设计
• 文档:
  • 系统架构设计 (Architecture Design)
  • 详细设计文档 (Detailed Design)
  • API 接口设计 (API Design)
  • 数据库设计 (Database Schema)
  • 设计评审记录 (Design Review)

阶段 3: 开发阶段（Development）

• 输入: 设计文档
• 输出: 代码、单元测试、技术文档
• 文档:
  • 开发规范 (Coding Standards)
  • 代码注释 (Code Comments)
  • 技术文档 (Technical Documentation)
  • 变更日志 (Changelog)
  • 代码审查记录 (Code Review)

阶段 4: 测试阶段（Testing）

• 输入: 代码、需求文档
• 输出: 测试用例、测试报告、Bug 列表
• 文档:
  • 测试计划 (Test Plan)
  • 测试用例 (Test Cases)
  • 测试报告 (Test Report)
  • Bug 跟踪 (Bug Tracking)
  • 性能测试报告 (Performance Report)

阶段 5: 部署阶段（Deployment）

• 输入: 经过测试的代码
• 输出: 部署文档、发布说明
• 文档:
  • 部署手册 (Deployment Guide)
  • 环境配置 (Environment Setup)
  • 发布说明 (Release Notes)
  • 回滚方案 (Rollback Plan)
  • 部署检查清单 (Deployment Checklist)

阶段 6: 运维阶段（Operations）

• 输入: 运行中的系统
• 输出: 运维文档、监控报告
• 文档:
  • 运维手册 (Operations Manual)
  • 监控配置 (Monitoring Setup)
  • 故障处理 (Incident Response)
  • 备份恢复 (Backup & Recovery)
  • SLA 报告 (SLA Report)

📂 文档目录结构

docs/
├── 01-requirements/              # 需求阶段
│   ├── BRD/                      # 业务需求文档
│   ├── PRD/                      # 产品需求文档
│   ├── user-stories/             # 用户故事
│   ├── acceptance-criteria/      # 验收标准
│   └── templates/                # 模板
│
├── 02-design/                    # 设计阶段
│   ├── architecture/             # 架构设计
│   ├── detailed-design/          # 详细设计
│   ├── api-design/              # API 设计
│   ├── database-design/         # 数据库设计
│   ├── design-reviews/          # 设计评审
│   └── templates/
│
├── 03-development/              # 开发阶段
│   ├── coding-standards/        # 编码规范
│   ├── technical-docs/          # 技术文档
│   ├── changelog/               # 变更日志
│   ├── code-reviews/            # 代码评审
│   └── templates/
│
├── 04-testing/                  # 测试阶段
│   ├── test-plans/              # 测试计划
│   ├── test-cases/              # 测试用例
│   ├── test-reports/            # 测试报告
│   ├── bug-tracking/            # Bug 跟踪
│   ├── performance-reports/     # 性能报告
│   └── templates/
│
├── 05-deployment/               # 部署阶段
│   ├── deployment-guides/       # 部署指南
│   ├── environment-setup/       # 环境配置
│   ├── release-notes/           # 发布说明
│   ├── rollback-plans/          # 回滚方案
│   └── templates/
│
├── 06-operations/               # 运维阶段
│   ├── operations-manual/       # 运维手册
│   ├── monitoring/              # 监控配置
│   ├── incident-response/       # 故障处理
│   ├── backup-recovery/         # 备份恢复
│   ├── sla-reports/            # SLA 报告
│   └── templates/
│
└── workflows/                   # 工作流程
    ├── document-management-system.md  # 本文件
    ├── claude-development-workflow.md
    └── github-integration.md

🏷️ GitHub 文档管理方案

方案 1: GitHub Issues + Projects（推荐）

Issue 标签体系

阶段标签（Phase）:

phase/requirements    # 需求阶段
phase/design         # 设计阶段
phase/development    # 开发阶段
phase/testing        # 测试阶段
phase/deployment     # 部署阶段
phase/operations     # 运维阶段

文档类型标签（Doc Type）:

doc/brd             # 业务需求文档
doc/prd             # 产品需求文档
doc/design          # 设计文档
doc/api             # API 文档
doc/test-case       # 测试用例
doc/test-report     # 测试报告
doc/deployment      # 部署文档
doc/operations      # 运维文档

优先级标签（Priority）:

priority/critical   # P0 - 关键
priority/high       # P1 - 高
priority/medium     # P2 - 中
priority/low        # P3 - 低

状态标签（Status）:

status/draft        # 草稿
status/review       # 审查中
status/approved     # 已批准
status/implemented  # 已实施
status/archived     # 已归档

GitHub Projects 看板设计

主看板：SDLC Overview

┌──────────────┬─────────┬──────────┬─────────┬────────────┬───────────┐
│ Requirements │ Design  │ Develop  │ Testing │ Deployment │ Operations│
├──────────────┼─────────┼──────────┼─────────┼────────────┼───────────┤
│ □ BRD-001    │ □ API-1 │ □ FT-100│ □ TC-01 │ □ DPL-1   │ □ OPS-1   │
│ □ PRD-001    │ □ DB-1  │ □ FT-101│ □ TC-02 │            │           │
│ □ US-001     │         │         │         │            │           │
└──────────────┴─────────┴──────────┴─────────┴────────────┴───────────┘

自定义字段：

字段名	类型	选项
Phase	单选	Requirements/Design/Development/Testing/Deployment/Operations
Doc Type	单选	BRD/PRD/Design/API/Test/Deployment/Operations
Priority	单选	P0/P1/P2/P3
Status	单选	Draft/Review/Approved/Implemented/Archived
Owner	人员	负责人
Reviewer	人员	审查人
Due Date	日期	截止日期
Progress	数字	0-100%
Blocking	文本	阻塞因素
Dependencies	文本	依赖关系

方案 2: GitHub Wiki（文档中心）

Wiki 结构：

Home
├── Requirements
│   ├── Business Requirements
│   ├── Product Requirements
│   └── User Stories
├── Design
│   ├── Architecture
│   ├── API Design
│   └── Database Design
├── Development
│   ├── Coding Standards
│   └── Technical Docs
├── Testing
│   ├── Test Plans
│   └── Test Cases
├── Deployment
│   └── Deployment Guides
└── Operations
    └── Operations Manual

方案 3: GitHub Discussions（协作讨论）

分类：

• 📋 Requirements Discussion
• 🎨 Design Review
• 💻 Development Questions
• 🧪 Testing Feedback
• 🚀 Deployment Planning
• 🔧 Operations Issues

🤖 自动化工作流

1. 文档状态自动化

# .github/workflows/document-lifecycle.yml
name: Document Lifecycle Management

on:
  issues:
    types: [opened, labeled, closed]
  pull_request:
    types: [opened, closed]

jobs:
  track-document:
    runs-on: ubuntu-latest
    steps:
      - name: Document Created
        if: github.event.action == 'opened'
        run: |
          echo "New document created: ${{ github.event.issue.title }}"
          # 发送通知，更新仪表盘

      - name: Document Approved
        if: contains(github.event.issue.labels.*.name, 'status/approved')
        run: |
          echo "Document approved: ${{ github.event.issue.title }}"
          # 移动到下一阶段

      - name: Update Progress
        run: |
          # 计算阶段进度
          # 更新项目看板
          # 生成进度报告

2. 文档审查提醒

# .github/workflows/review-reminder.yml
name: Review Reminder

on:
  schedule:
    - cron: '0 9 * * 1-5'  # 工作日上午9点

jobs:
  remind-reviews:
    runs-on: ubuntu-latest
    steps:
      - name: Check pending reviews
        uses: actions/github-script@v7
        with:
          script: |
            // 查找待审查的文档
            const issues = await github.rest.issues.listForRepo({
              owner: context.repo.owner,
              repo: context.repo.repo,
              labels: 'status/review',
              state: 'open'
            });

            // 发送提醒
            for (const issue of issues.data) {
              // 检查是否超期
              const created = new Date(issue.created_at);
              const now = new Date();
              const days = (now - created) / (1000 * 60 * 60 * 24);

              if (days > 3) {
                await github.rest.issues.createComment({
                  issue_number: issue.number,
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  body: `⚠️ 提醒：此文档已等待审查 ${Math.floor(days)} 天，请尽快审查。`
                });
              }
            }

3. 进度报告生成

# .github/workflows/progress-report.yml
name: Progress Report Generator

on:
  schedule:
    - cron: '0 18 * * 5'  # 每周五下午6点
  workflow_dispatch:

jobs:
  generate-report:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Generate Progress Report
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');

            // 统计各阶段的文档数量和状态
            const phases = ['requirements', 'design', 'development', 'testing', 'deployment', 'operations'];
            const report = {};

            for (const phase of phases) {
              const issues = await github.rest.issues.listForRepo({
                owner: context.repo.owner,
                repo: context.repo.repo,
                labels: `phase/${phase}`,
                state: 'all'
              });

              report[phase] = {
                total: issues.data.length,
                draft: issues.data.filter(i => i.labels.find(l => l.name === 'status/draft')).length,
                review: issues.data.filter(i => i.labels.find(l => l.name === 'status/review')).length,
                approved: issues.data.filter(i => i.labels.find(l => l.name === 'status/approved')).length,
                implemented: issues.data.filter(i => i.labels.find(l => l.name === 'status/implemented')).length
              };
            }

            // 生成 Markdown 报告
            let markdown = `# 📊 Weekly Progress Report\n\n`;
            markdown += `**Generated:** ${new Date().toISOString()}\n\n`;

            for (const [phase, stats] of Object.entries(report)) {
              const progress = stats.total > 0 ?
                ((stats.approved + stats.implemented) / stats.total * 100).toFixed(1) : 0;

              markdown += `## ${phase.toUpperCase()}\n`;
              markdown += `- Total: ${stats.total}\n`;
              markdown += `- Progress: ${progress}%\n`;
              markdown += `- Draft: ${stats.draft} | Review: ${stats.review} | Approved: ${stats.approved} | Implemented: ${stats.implemented}\n\n`;
            }

            // 创建 Issue 发布报告
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: `Weekly Progress Report - ${new Date().toISOString().split('T')[0]}`,
              body: markdown,
              labels: ['report', 'progress']
            });

📈 进度总览和预警系统

GitHub 方案的局限性

GitHub 原生功能在以下方面存在限制：

❌ 可视化不足

• 缺少实时仪表盘
• 图表能力有限
• 无法自定义复杂的数据展示

❌ 预警能力弱

• 无法设置复杂的预警规则
• 缺少实时通知机制
• 无法进行风险评估

❌ 数据分析有限

• 无法进行深度数据挖掘
• 缺少趋势分析
• 无法生成自定义报表

解决方案：自定义进度管理平台

🚀 自定义文档管理平台设计

平台架构

graph TB
    subgraph "前端层"
        A[管理仪表盘]
        B[文档编辑器]
        C[进度可视化]
        D[预警中心]
    end

    subgraph "应用层"
        E[API Gateway]
        F[文档服务]
        G[进度追踪服务]
        H[预警服务]
        I[报表服务]
    end

    subgraph "数据层"
        J[(PostgreSQL)]
        K[(Redis Cache)]
        L[文档存储]
    end

    subgraph "集成层"
        M[GitHub API]
        N[通知服务]
        O[Claude API]
    end

    A --> E
    B --> E
    C --> E
    D --> E

    E --> F
    E --> G
    E --> H
    E --> I

    F --> J
    G --> J
    H --> J
    I --> J

    F --> K
    G --> K

    F --> L

    F --> M
    G --> M

    H --> N

    F --> O

核心功能

1. 实时进度仪表盘

功能：

• 📊 各阶段进度可视化（饼图、柱状图、甘特图）
• 🎯 里程碑追踪
• 👥 团队成员工作负载
• ⏰ 时间线视图
• 📈 趋势分析

技术栈：

• 前端：Vue.js 3 + ECharts + D3.js
• 后端：FastAPI
• 实时通信：WebSocket

2. 智能预警系统

预警规则：

# 预警规则引擎
class AlertRules:
    def __init__(self):
        self.rules = []

    def check_overdue(self, document):
        """检查逾期文档"""
        if document.due_date < datetime.now():
            return Alert(
                level='critical',
                message=f'文档 {document.title} 已逾期',
                document_id=document.id
            )

    def check_review_pending(self, document):
        """检查待审查文档"""
        if document.status == 'review':
            days_pending = (datetime.now() - document.review_requested_at).days
            if days_pending > 3:
                return Alert(
                    level='warning',
                    message=f'文档 {document.title} 待审查已 {days_pending} 天',
                    document_id=document.id
                )

    def check_phase_progress(self, phase):
        """检查阶段进度"""
        progress = phase.completed / phase.total if phase.total > 0 else 0
        expected_progress = self.calculate_expected_progress(phase)

        if progress < expected_progress - 0.2:  # 落后20%
            return Alert(
                level='warning',
                message=f'{phase.name} 阶段进度落后',
                details={
                    'actual': progress,
                    'expected': expected_progress
                }
            )

    def check_blocking_issues(self, document):
        """检查阻塞问题"""
        if document.blocking_issues:
            return Alert(
                level='high',
                message=f'文档 {document.title} 存在阻塞问题',
                blocking_issues=document.blocking_issues
            )

预警级别：

• 🔴 Critical - 严重：项目阻塞、严重逾期
• 🟠 High - 高：重要文档待审、关键路径延迟
• 🟡 Warning - 警告：进度落后、资源不足
• 🔵 Info - 信息：提醒、建议

3. 文档关系图谱

# 文档依赖关系
class DocumentGraph:
    def __init__(self):
        self.nodes = {}  # 文档节点
        self.edges = []  # 依赖关系

    def add_document(self, doc):
        self.nodes[doc.id] = doc

    def add_dependency(self, from_doc, to_doc, dep_type):
        """添加依赖关系"""
        self.edges.append({
            'from': from_doc.id,
            'to': to_doc.id,
            'type': dep_type  # 'requires', 'blocks', 'relates'
        })

    def find_critical_path(self):
        """查找关键路径"""
        # 使用拓扑排序和关键路径算法
        pass

    def check_circular_dependency(self):
        """检查循环依赖"""
        # DFS 检测环
        pass

可视化：

// 使用 D3.js 展示文档关系图
const graph = {
  nodes: [
    { id: 'BRD-001', phase: 'requirements', status: 'approved' },
    { id: 'PRD-001', phase: 'requirements', status: 'approved' },
    { id: 'ARCH-001', phase: 'design', status: 'review' },
    { id: 'API-001', phase: 'design', status: 'draft' }
  ],
  links: [
    { source: 'BRD-001', target: 'PRD-001', type: 'requires' },
    { source: 'PRD-001', target: 'ARCH-001', type: 'requires' },
    { source: 'ARCH-001', target: 'API-001', type: 'requires' }
  ]
};

4. 自动化文档生成

使用 Claude API：

# 文档生成服务
class DocumentGenerator:
    def __init__(self, claude_client):
        self.claude = claude_client

    async def generate_test_cases(self, design_doc):
        """从设计文档生成测试用例"""
        prompt = f"""
        基于以下设计文档，生成详细的测试用例：

        {design_doc.content}

        请生成：
        1. 功能测试用例
        2. 边界测试用例
        3. 异常测试用例
        4. 性能测试用例

        格式：
        - 测试用例ID
        - 测试描述
        - 前置条件
        - 测试步骤
        - 预期结果
        """

        response = await self.claude.messages.create(
            model="claude-sonnet-4.5",
            messages=[{"role": "user", "content": prompt}]
        )

        return self.parse_test_cases(response.content)

    async def generate_deployment_guide(self, code_repo):
        """生成部署文档"""
        # 分析代码仓库结构
        # 生成部署步骤
        # 生成配置说明
        pass

5. 数据分析和报表

关键指标：

class ProjectMetrics:
    def calculate_velocity(self, team, sprint):
        """计算团队速度"""
        completed_story_points = sum(
            task.story_points
            for task in sprint.tasks
            if task.status == 'completed'
        )
        return completed_story_points

    def calculate_burn_down(self, sprint):
        """燃尽图数据"""
        daily_remaining = []
        for day in sprint.days:
            remaining = sum(
                task.story_points
                for task in sprint.tasks
                if task.completed_at > day or not task.completed_at
            )
            daily_remaining.append({
                'date': day,
                'remaining': remaining
            })
        return daily_remaining

    def calculate_cycle_time(self, phase):
        """计算周期时间"""
        documents = phase.documents.filter(status='completed')
        cycle_times = [
            (doc.completed_at - doc.started_at).days
            for doc in documents
        ]
        return {
            'average': sum(cycle_times) / len(cycle_times),
            'median': statistics.median(cycle_times),
            'p90': statistics.quantiles(cycle_times, n=10)[8]
        }

📱 用户界面设计

主仪表盘界面

┌─────────────────────────────────────────────────────────────────┐
│  📊 项目进度总览                          用户: Admin  [设置]    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┬─────┐│
│  │需求分析  │  设计    │  开发    │  测试    │  部署    │运维 ││
│  │  85%     │  70%     │  45%     │  20%     │   5%     │ 0% ││
│  │ ████▌    │ ███▌     │ ██▏      │ █        │ ▌        │    ││
│  └──────────┴──────────┴──────────┴──────────┴──────────┴─────┘│
│                                                                  │
│  🚨 预警信息 (3)                                                │
│  ┌────────────────────────────────────────────────────────┐    │
│  │ 🔴 [Critical] API-005 设计文档逾期 3 天                │    │
│  │ 🟠 [High] TC-023 测试用例待审查 5 天                   │    │
│  │ 🟡 [Warning] 开发阶段进度落后 15%                      │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                  │
│  📈 趋势分析                    📋 最近活动                     │
│  ┌──────────────────────┐      ┌──────────────────────┐        │
│  │   完成率趋势         │      │ • 张三 提交了 BRD-10│        │
│  │                      │      │ • 李四 审查了 API-03│        │
│  │    /\  /\            │      │ • 王五 完成了 TC-15 │        │
│  │   /  \/  \    /\     │      │ • 赵六 更新了 DEP-02│        │
│  │  /        \  /  \    │      └──────────────────────┘        │
│  │ /          \/    \   │                                       │
│  └──────────────────────┘                                       │
│                                                                  │
│  🎯 里程碑                                                       │
│  ┌────────────────────────────────────────────────────────┐    │
│  │ ✅ M1: 需求分析完成 (2024-01-15)                       │    │
│  │ ✅ M2: 设计评审通过 (2024-02-01)                       │    │
│  │ 🔄 M3: Alpha 版本发布 (2024-03-01) - 进度 45%         │    │
│  │ ⏳ M4: Beta 版本发布 (2024-04-01)                      │    │
│  └────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

文档列表界面

┌─────────────────────────────────────────────────────────────────┐
│  📚 文档管理                    [+ 新建文档] [导入] [导出]      │
├─────────────────────────────────────────────────────────────────┤
│  筛选: [阶段 ▾] [类型 ▾] [状态 ▾] [负责人 ▾]     🔍 搜索...   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ID      │ 标题          │ 阶段  │ 类型 │ 状态  │ 负责人│ 进度│
│ ─────────┼───────────────┼───────┼──────┼───────┼──────┼─────│
│ BRD-001  │ 用户管理需求  │ 需求  │ BRD  │ 已批准│ 张三  │100% │
│ PRD-001  │ 用户管理产品  │ 需求  │ PRD  │ 已批准│ 李四  │100% │
│ ARCH-001 │ 系统架构设计  │ 设计  │架构  │ 审查中│ 王五  │ 80% │
│ API-001  │ 用户 API 设计│ 设计  │ API  │ 草稿  │ 赵六  │ 30% │
│ TC-001   │ 登录测试用例  │ 测试  │测试  │ 待审查│ 钱七  │ 90% │
│                                                                  │
│  显示 1-5 / 共 47 条                         [< 1 2 3 4 5 >]  │
└─────────────────────────────────────────────────────────────────┘

🔧 实施步骤

阶段 1: 使用 GitHub 原生方案（立即可用）

第 1 周：搭建基础

# 1. 创建标签系统
./scripts/setup-labels.sh

# 2. 创建 GitHub Project
gh project create --owner @me --title "SDLC Management"

# 3. 配置自定义字段
# 在 GitHub UI 中添加自定义字段

# 4. 创建文档模板
# 复制 .github/ISSUE_TEMPLATE/ 中的模板

第 2-3 周：配置自动化

# 5. 部署 GitHub Actions 工作流
git add .github/workflows/document-lifecycle.yml
git add .github/workflows/review-reminder.yml
git add .github/workflows/progress-report.yml
git commit -m "feat: add document management workflows"
git push

第 4 周：培训和试运行

• 团队培训
• 创建示例文档
• 调整工作流

阶段 2: 开发自定义平台（4-8 周）

Week 1-2: 后端开发

• 数据库设计
• API 开发
• GitHub API 集成
• Claude API 集成

Week 3-4: 前端开发

• 仪表盘界面
• 文档管理界面
• 可视化图表

Week 5-6: 预警系统

• 预警规则引擎
• 通知服务集成
• 实时监控

Week 7-8: 测试和部署

• 集成测试
• 性能优化
• 部署上线

📊 效果对比

GitHub 原生方案 vs 自定义平台

功能	GitHub 原生	自定义平台
文档管理	✅ Issues + Wiki	✅ 专业文档系统
进度追踪	⚠️ Projects（有限）	✅ 实时仪表盘
可视化	⚠️ 基础图表	✅ 高级图表 + 图谱
预警系统	❌ 无	✅ 智能预警
数据分析	⚠️ 基础统计	✅ 深度分析
自动化	✅ Actions	✅ Actions + 自定义
Claude 集成	⚠️ 手动	✅ 深度集成
成本	免费/低	中/高
维护成本	低	中
学习曲线	低	中

建议方案

小型团队（<10人）：

• ✅ 使用 GitHub 原生方案
• ✅ 配合简单的脚本和自动化
• ✅ 成本低，快速上手

中型团队（10-50人）：

• ✅ GitHub 原生 + 轻量级仪表盘
• ✅ 重点开发预警系统
• ✅ 平衡成本和功能

大型团队（>50人）：

• ✅ 完整的自定义平台
• ✅ 深度集成和自动化
• ✅ 专业的进度管理

🎓 最佳实践

文档管理

1. 统一命名规范

   [阶段]-[类型]-[编号]-[标题]
   例如: REQ-BRD-001-用户管理需求
   

2. 版本控制

   • 所有文档使用 Git 管理
   • 重要变更创建 PR
   • 保留历史版本

3. 审查流程

   • 草稿 → 审查 → 批准 → 实施
   • 至少 2 人审查
   • 记录审查意见

4. 定期回顾

   • 每周进度回顾
   • 每月文档审计
   • 季度总结改进

进度管理

1. 设置合理的里程碑
2. 及时更新进度
3. 关注关键路径
4. 主动处理预警

---

下一步：

• 查看 实施脚本
• 查看 自定义平台设计
• 查看 预警规则配置

维护者: 项目管理团队 最后更新: 2024-12-29 版本: 1.0.0