如何做好一份技术文档？从理论到实践的完整指南

class DocumentTarget:
    """
    技术文档目标定位类
    用于定义文档的受众、目标和范围
    """
    
    def __init__(self, audience, objective, scope):
        """
        初始化文档目标
        
        Args:
            audience (str): 目标受众（开发者、测试、产品经理等）
            objective (str): 文档目标（学习、使用、维护等）
            scope (str): 文档范围（模块、系统、平台等）
        """
        self.audience = audience
        self.objective = objective
        self.scope = scope
    
    def generate_outline(self):
        """
        根据目标生成文档大纲
        
        Returns:
            list: 文档章节列表
        """
        outline = []
        
        # 根据受众和目标确定文档结构
        if self.audience == "developer":
            outline.extend([
                "1. 技术架构概述",
                "2. 环境搭建指南", 
                "3. 核心模块详解",
                "4. API接口文档",
                "5. 代码示例",
                "6. 常见问题解答"
            ])
        elif self.audience == "user":
            outline.extend([
                "1. 产品介绍",
                "2. 快速开始",
                "3. 功能详解", 
                "4. 操作指南",
                "5. 故障排查"
            ])
            
        return outline
    
    def validate_content(self, content):
        """
        验证文档内容是否符合目标定位
        
        Args:
            content (str): 文档内容
            
        Returns:
            dict: 验证结果
        """
        validation_result = {
            "audience_match": False,
            "objective_clear": False,
            "scope_appropriate": False,
            "suggestions": []
        }
        
        # 简单的内容验证逻辑
        if self.audience.lower() in content.lower():
            validation_result["audience_match"] = True
        else:
            validation_result["suggestions"].append(
                f"内容应更贴近{self.audience}的需求"
            )
            
        return validation_result

# 使用示例
doc_target = DocumentTarget(
    audience="developer",
    objective="快速上手项目开发", 
    scope="后端API服务"
)

outline = doc_target.generate_outline()
print("文档大纲：")
for item in outline:
    print(f"  {item}")

/**
 * API文档标准模板类
 * 用于生成标准化的API文档描述
 */
class APIDocTemplate {
    /**
     * 构造函数
     * @param {string} apiName - API名称
     * @param {string} method - HTTP方法
     * @param {string} endpoint - 接口端点
     */
    constructor(apiName, method, endpoint) {
        this.apiName = apiName;
        this.method = method;
        this.endpoint = endpoint;
        this.parameters = [];
        this.responses = [];
        this.examples = [];
    }
    
    /**
     * 添加参数说明
     * @param {Object} param - 参数对象
     * @param {string} param.name - 参数名称
     * @param {string} param.type - 参数类型
     * @param {boolean} param.required - 是否必需
     * @param {string} param.description - 参数描述
     * @param {*} param.example - 示例值
     */
    addParameter(param) {
        // 验证参数完整性
        const requiredFields = ['name', 'type', 'required', 'description'];
        for (const field of requiredFields) {
            if (!param.hasOwnProperty(field)) {
                throw new Error(`参数缺少必需字段: ${field}`);
            }
        }
        
        this.parameters.push({
            name: param.name,
            type: param.type,
            required: param.required,
            description: param.description,
            example: param.example || null
        });
    }
    
    /**
     * 添加响应说明
     * @param {Object} response - 响应对象
     * @param {number} response.code - 状态码
     * @param {string} response.description - 描述
     * @param {Object} response.schema - 响应结构
     */
    addResponse(response) {
        this.responses.push(response);
    }
    
    /**
     * 添加使用示例
     * @param {Object} example - 示例对象
     * @param {string} example.title - 示例标题
     * @param {string} example.description - 示例描述
     * @param {string} example.code - 示例代码
     */
    addExample(example) {
        this.examples.push(example);
    }
    
    /**
     * 生成Markdown格式的API文档
     * @returns {string} Markdown格式的文档
     */
    generateMarkdown() {
        let markdown = `## ${this.apiName}\n\n`;
        markdown += `**方法**: \`${this.method}\`\n\n`;
        markdown += `**端点**: \`${this.endpoint}\`\n\n`;
        
        // 参数说明
        if (this.parameters.length > 0) {
            markdown += `### 请求参数\n\n`;
            markdown += `| 参数名 | 类型 | 必需 | 描述 | 示例 |\n`;
            markdown += `|--------|------|------|------|------|\n`;
            
            this.parameters.forEach(param => {
                const required = param.required ? '是' : '否';
                const example = param.example ? `\`${param.example}\` ` : '-';
                markdown += `| ${param.name} | ${param.type} | ${required} | ${param.description} | ${example} |\n`;
            });
            markdown += `\n`;
        }
        
        // 响应说明
        if (this.responses.length > 0) {
            markdown += `### 响应格式\n\n`;
            this.responses.forEach(response => {
                markdown += `**${response.code}**: ${response.description}\n\n`;
                if (response.schema) {
                    markdown += `\`\`\`json\n${JSON.stringify(response.schema, null, 2)}\n\`\`\`\n\n`;
                }
            });
        }
        
        // 使用示例
        if (this.examples.length > 0) {
            markdown += `### 使用示例\n\n`;
            this.examples.forEach((example, index) => {
                markdown += `#### ${example.title}\n\n`;
                markdown += `${example.description}\n\n`;
                markdown += `\`\`\`javascript\n${example.code}\n\`\`\`\n\n`;
            });
        }
        
        return markdown;
    }
}

// 使用示例：创建用户登录API文档
const loginAPI = new APIDocTemplate('用户登录', 'POST', '/api/auth/login');

// 添加参数
loginAPI.addParameter({
    name: 'username',
    type: 'string',
    required: true,
    description: '用户名或邮箱地址',
    example: 'user@example.com'
});

loginAPI.addParameter({
    name: 'password',
    type: 'string', 
    required: true,
    description: '用户密码（6-20位字符）',
    example: 'mypassword123'
});

// 添加响应
loginAPI.addResponse({
    code: 200,
    description: '登录成功',
    schema: {
        success: true,
        token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
        user: {
            id: 12345,
            username: 'user@example.com',
            nickname: '张三'
        }
    }
});

loginAPI.addResponse({
    code: 401,
    description: '用户名或密码错误',
    schema: {
        success: false,
        error: 'Invalid credentials'
    }
});

// 添加示例
loginAPI.addExample({
    title: 'JavaScript fetch 示例',
    description: '使用fetch API进行用户登录',
    code: `
fetch('/api/auth/login', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        username: 'user@example.com',
        password: 'mypassword123'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        localStorage.setItem('token', data.token);
        console.log('登录成功:', data.user);
    } else {
        console.error('登录失败:', data.error);
    }
})
.catch(error => {
    console.error('请求失败:', error);
});`
});

// 生成文档
console.log(loginAPI.generateMarkdown());

class DocumentNavigator:
    """
    文档导航器类
    提供文档导航和索引功能
    """
    
    def __init__(self):
        """初始化导航器"""
        self.sections = {}
        self.index = {}
        self.breadcrumbs = []
    
    def add_section(self, section_id, title, level, parent=None):
        """
        添加文档章节
        
        Args:
            section_id (str): 章节ID
            title (str): 章节标题
            level (int): 章节层级（1-6）
            parent (str): 父章节ID
        """
        self.sections[section_id] = {
            'title': title,
            'level': level,
            'parent': parent,
            'children': [],
            'content': '',
            'keywords': []
        }
        
        # 建立父子关系
        if parent and parent in self.sections:
            self.sections[parent]['children'].append(section_id)
    
    def add_content(self, section_id, content, keywords=None):
        """
        为章节添加内容和关键词
        
        Args:
            section_id (str): 章节ID
            content (str): 章节内容
            keywords (list): 关键词列表
        """
        if section_id in self.sections:
            self.sections[section_id]['content'] = content
            if keywords:
                self.sections[section_id]['keywords'] = keywords
                # 建立关键词索引
                for keyword in keywords:
                    if keyword not in self.index:
                        self.index[keyword] = []
                    self.index[keyword].append(section_id)
    
    def generate_toc(self, max_level=3):
        """
        生成目录
        
        Args:
            max_level (int): 显示的最大层级
            
        Returns:
            str: Markdown格式的目录
        """
        toc = "## 目录\n\n"
        
        # 按层级排序
        sorted_sections = sorted(
            self.sections.items(),
            key=lambda x: (x[1]['level'], x[0])
        )
        
        for section_id, section in sorted_sections:
            if section['level'] <= max_level:
                indent = "  " * (section['level'] - 1)
                toc += f"{indent}- [{section['title']}](#{section_id})\n"
        
        return toc
    
    def search(self, query):
        """
        搜索功能
        
        Args:
            query (str): 搜索关键词
            
        Returns:
            list: 匹配的章节列表
        """
        results = []
        query_lower = query.lower()
        
        # 在标题中搜索
        for section_id, section in self.sections.items():
            if query_lower in section['title'].lower():
                results.append({
                    'section_id': section_id,
                    'title': section['title'],
                    'match_type': 'title'
                })
        
        # 在关键词中搜索
        for keyword, section_ids in self.index.items():
            if query_lower in keyword.lower():
                for section_id in section_ids:
                    results.append({
                        'section_id': section_id,
                        'title': self.sections[section_id]['title'],
                        'match_type': 'keyword',
                        'keyword': keyword
                    })
        
        # 在内容中搜索
        for section_id, section in self.sections.items():
            if query_lower in section['content'].lower():
                results.append({
                    'section_id': section_id,
                    'title': section['title'],
                    'match_type': 'content'
                })
        
        # 去重并按相关性排序
        unique_results = {}
        for result in results:
            key = result['section_id']
            if key not in unique_results:
                unique_results[key] = result
            elif result['match_type'] == 'title':
                unique_results[key] = result  # 标题匹配优先级最高
        
        return list(unique_results.values())
    
    def get_breadcrumbs(self, section_id):
        """
        获取面包屑导航
        
        Args:
            section_id (str): 当前章节ID
            
        Returns:
            list: 面包屑路径
        """
        breadcrumbs = []
        current = section_id
        
        while current:
            section = self.sections.get(current)
            if section:
                breadcrumbs.insert(0, {
                    'id': current,
                    'title': section['title']
                })
                current = section['parent']
            else:
                break
        
        return breadcrumbs

# 使用示例：构建API文档导航
navigator = DocumentNavigator()

# 添加章节结构
navigator.add_section('intro', '概述', 1)
navigator.add_section('quickstart', '快速开始', 1)
navigator.add_section('api', 'API参考', 1)
navigator.add_section('auth', '认证与授权', 2, 'api')
navigator.add_section('user', '用户管理', 2, 'api')
navigator.add_section('login', '用户登录', 3, 'user')
navigator.add_section('register', '用户注册', 3, 'user')

# 添加内容和关键词
navigator.add_content('login', '用户登录API允许用户通过用户名和密码进行身份验证...', 
                     ['登录', '认证', 'JWT', 'token'])
navigator.add_content('register', '用户注册API允许新用户创建账号...', 
                     ['注册', '用户创建', '验证'])

# 生成目录
print(navigator.generate_toc())

# 搜索功能演示
search_results = navigator.search('登录')
print(f"\n搜索'登录'的结果:")
for result in search_results:
    print(f"- {result['title']} (匹配类型: {result['match_type']})")

# 面包屑导航演示
breadcrumbs = navigator.get_breadcrumbs('login')
print(f"\n'login'章节的面包屑导航:")
print(" > ".join([bc['title'] for bc in breadcrumbs]))

/**
 * 代码示例管理器
 * 用于管理和验证技术文档中的代码示例
 * 
 * @author 技术文档团队
 * @version 1.0
 * @since 2024-01-01
 */
public class CodeExampleManager {
    
    /**
     * 示例代码的复杂度等级
     */
    public enum ComplexityLevel {
        BASIC,      // 基础示例：展示基本用法
        INTERMEDIATE, // 中级示例：展示常见场景
        ADVANCED    // 高级示例：展示复杂场景和最佳实践
    }
    
    /**
     * 代码示例类
     */
    public static class CodeExample {
        private String title;           // 示例标题
        private String description;     // 示例描述
        private ComplexityLevel level;  // 复杂度等级
        private String language;        // 编程语言
        private String code;           // 示例代码
        private List<String> dependencies; // 依赖列表
        private String expectedOutput;  // 预期输出
        
        /**
         * 构造函数
         * 
         * @param title 示例标题
         * @param description 示例描述
         * @param level 复杂度等级
         * @param language 编程语言
         * @param code 示例代码
         */
        public CodeExample(String title, String description, 
                          ComplexityLevel level, String language, String code) {
            this.title = title;
            this.description = description;
            this.level = level;
            this.language = language;
            this.code = code;
            this.dependencies = new ArrayList<>();
        }
        
        /**
         * 添加依赖
         * 
         * @param dependency 依赖名称
         */
        public void addDependency(String dependency) {
            this.dependencies.add(dependency);
        }
        
        /**
         * 设置预期输出
         * 
         * @param expectedOutput 预期的执行结果
         */
        public void setExpectedOutput(String expectedOutput) {
            this.expectedOutput = expectedOutput;
        }
        
        /**
         * 验证代码示例的完整性
         * 
         * @return 验证结果
         */
        public ValidationResult validate() {
            ValidationResult result = new ValidationResult();
            
            // 检查标题是否为空
            if (title == null || title.trim().isEmpty()) {
                result.addError("示例标题不能为空");
            }
            
            // 检查代码是否为空
            if (code == null || code.trim().isEmpty()) {
                result.addError("示例代码不能为空");
            }
            
            // 检查代码注释覆盖率
            if (code != null) {
                double commentRatio = calculateCommentRatio(code);
                if (commentRatio < 0.2) { // 注释应占代码的20%以上
                    result.addWarning("代码注释不足，建议增加更多说明");
                }
            }
            
            // 根据复杂度检查依赖
            if (level == ComplexityLevel.BASIC && !dependencies.isEmpty()) {
                result.addWarning("基础示例应尽量避免外部依赖");
            }
            
            return result;
        }
        
        /**
         * 计算代码注释比例
         * 
         * @param code 代码内容
         * @return 注释行数占总行数的比例
         */
        private double calculateCommentRatio(String code) {
            String[] lines = code.split("\n");
            int commentLines = 0;
            
            for (String line : lines) {
                String trimmed = line.trim();
                // 简单的注释识别逻辑
                if (trimmed.startsWith("//") || 
                    trimmed.startsWith("/*") || 
                    trimmed.startsWith("*") ||
                    trimmed.startsWith("#")) {
                    commentLines++;
                }
            }
            
            return lines.length > 0 ? (double) commentLines / lines.length : 0;
        }
        
        /**
         * 生成Markdown格式的示例
         * 
         * @return Markdown格式的代码示例
         */
        public String toMarkdown() {
            StringBuilder md = new StringBuilder();
            
            // 标题和描述
            md.append("### ").append(title).append("\n\n");
            md.append(description).append("\n\n");
            
            // 复杂度标识
            md.append("**复杂度**: ").append(level.name()).append("\n\n");
            
            // 依赖列表
            if (!dependencies.isEmpty()) {
                md.append("**依赖**:\n");
                for (String dep : dependencies) {
                    md.append("- ").append(dep).append("\n");
                }
                md.append("\n");
            }
            
            // 代码块
            md.append("```").append(language.toLowerCase()).append("\n");
            md.append(code).append("\n");
            md.append("```\n\n");
            
            // 预期输出
            if (expectedOutput != null && !expectedOutput.isEmpty()) {
                md.append("**预期输出**:\n");
                md.append("```\n");
                md.append(expectedOutput).append("\n");
                md.append("```\n\n");
            }
            
            return md.toString();
        }
        
        // Getters...
        public String getTitle() { return title; }
        public String getDescription() { return description; }
        public ComplexityLevel getLevel() { return level; }
        public String getLanguage() { return language; }
        public String getCode() { return code; }
        public List<String> getDependencies() { return dependencies; }
        public String getExpectedOutput() { return expectedOutput; }
    }
    
    /**
     * 验证结果类
     */
    public static class ValidationResult {
        private List<String> errors = new ArrayList<>();
        private List<String> warnings = new ArrayList<>();
        
        public void addError(String error) {
            errors.add(error);
        }
        
        public void addWarning(String warning) {
            warnings.add(warning);
        }
        
        public boolean isValid() {
            return errors.isEmpty();
        }
        
        public List<String> getErrors() { return errors; }
        public List<String> getWarnings() { return warnings; }
    }
    
    // 示例集合
    private List<CodeExample> examples = new ArrayList<>();
    
    /**
     * 添加代码示例
     * 
     * @param example 代码示例
     */
    public void addExample(CodeExample example) {
        examples.add(example);
    }
    
    /**
     * 按复杂度获取示例
     * 
     * @param level 复杂度等级
     * @return 指定复杂度的示例列表
     */
    public List<CodeExample> getExamplesByLevel(ComplexityLevel level) {
        return examples.stream()
                .filter(example -> example.getLevel() == level)
                .collect(Collectors.toList());
    }
    
    /**
     * 验证所有示例
     * 
     * @return 验证报告
     */
    public Map<String, ValidationResult> validateAllExamples() {
        Map<String, ValidationResult> results = new HashMap<>();
        
        for (CodeExample example : examples) {
            results.put(example.getTitle(), example.validate());
        }
        
        return results;
    }
}

// 使用示例
CodeExampleManager manager = new CodeExampleManager();

// 创建基础示例
CodeExampleManager.CodeExample basicExample = new CodeExampleManager.CodeExample(
    "简单的HTTP请求",
    "演示如何使用HttpURLConnection发送GET请求",
    CodeExampleManager.ComplexityLevel.BASIC,
    "Java",
    """
    // 导入必要的类
    import java.net.HttpURLConnection;
    import java.net.URL;
    import java.io.BufferedReader;
    import java.io.InputStreamReader;
    
    public class SimpleHttpRequest {
        /**
         * 发送GET请求的示例方法
         * 
         * @param urlString 请求的URL
         * @return 服务器响应内容
         */
        public static String sendGetRequest(String urlString) throws Exception {
            // 创建URL对象
            URL url = new URL(urlString);
            
            // 打开连接
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            
            // 设置请求方法为GET
            connection.setRequestMethod("GET");
            
            // 设置请求头
            connection.setRequestProperty("User-Agent", "JavaApp/1.0");
            
            // 获取响应码
            int responseCode = connection.getResponseCode();
            System.out.println("响应码: " + responseCode);
            
            // 读取响应内容
            BufferedReader reader = new BufferedReader(
                new InputStreamReader(connection.getInputStream())
            );
            String line;
            StringBuilder response = new StringBuilder();
            
            while ((line = reader.readLine()) != null) {
                response.append(line).append("\\n");
            }
            reader.close();
            
            return response.toString();
        }
        
        // 主方法演示用法
        public static void main(String[] args) {
            try {
                String result = sendGetRequest("https://api.github.com/users/octocat");
                System.out.println("响应内容: " + result);
            } catch (Exception e) {
                System.err.println("请求失败: " + e.getMessage());
            }
        }
    }
    """
);

basicExample.setExpectedOutput("响应码: 200\n响应内容: {\"login\":\"octocat\",...}");
manager.addExample(basicExample);

class DocumentToolComparator:
    """
    文档工具比较器
    用于评估和比较不同的文档工具
    """
    
    def __init__(self):
        """初始化比较器"""
        self.tools = {}
        self.criteria = {
            'ease_of_use': {'weight': 0.2, 'description': '易用性'},
            'collaboration': {'weight': 0.25, 'description': '协作功能'},
            'version_control': {'weight': 0.2, 'description': '版本控制'},
            'customization': {'weight': 0.15, 'description': '定制化能力'},
            'integration': {'weight': 0.1, 'description': '集成能力'},
            'cost': {'weight': 0.1, 'description': '成本'}
        }
    
    def add_tool(self, name, scores, features):
        """
        添加文档工具
        
        Args:
            name (str): 工具名称
            scores (dict): 各项评分（1-10分）
            features (list): 特色功能列表
        """
        self.tools[name] = {
            'scores': scores,
            'features': features,
            'total_score': 0
        }
        
        # 计算加权总分
        total = 0
        for criterion, weight_info in self.criteria.items():
            if criterion in scores:
                total += scores[criterion] * weight_info['weight']
        
        self.tools[name]['total_score'] = total
    
    def compare_tools(self):
        """
        比较所有工具并生成报告
        
        Returns:
            str: 比较报告
        """
        # 按总分排序
        sorted_tools = sorted(
            self.tools.items(),
            key=lambda x: x[1]['total_score'],
            reverse=True
        )
        
        report = "# 文档工具比较报告\n\n"
        report += "## 评分标准\n\n"
        
        for criterion, info in self.criteria.items():
            report += f"- **{info['description']}** (权重: {info['weight']*100}%)\n"
        
        report += "\n## 工具排名\n\n"
        report += "| 排名 | 工具名称 | 总分 | 易用性 | 协作功能 | 版本控制 | 定制化 | 集成能力 | 成本 |\n"
        report += "|------|----------|------|--------|----------|----------|--------|----------|------|\n"
        
        for i, (name, data) in enumerate(sorted_tools, 1):
            scores = data['scores']
            report += f"| {i} | {name} | {data['total_score']:.1f} | "
            report += f"{scores.get('ease_of_use', 0)} | "
            report += f"{scores.get('collaboration', 0)} | "
            report += f"{scores.get('version_control', 0)} | "
            report += f"{scores.get('customization', 0)} | "
            report += f"{scores.get('integration', 0)} | "
            report += f"{scores.get('cost', 0)} |\n"
        
        report += "\n## 详细分析\n\n"
        
        for name, data in sorted_tools:
            report += f"### {name}\n\n"
            report += f"**总分**: {data['total_score']:.1f}/10\n\n"
            report += "**特色功能**:\n"
            for feature in data['features']:
                report += f"- {feature}\n"
            report += "\n"
        
        return report
    
    def get_recommendation(self, priorities):
        """
        根据优先级推荐工具
        
        Args:
            priorities (list): 优先考虑的标准列表
            
        Returns:
            dict: 推荐结果
        """
        recommendations = {}
        
        for priority in priorities:
            if priority in self.criteria:
                best_tool = max(
                    self.tools.items(),
                    key=lambda x: x[1]['scores'].get(priority, 0)
                )
                recommendations[priority] = {
                    'tool': best_tool[0],
                    'score': best_tool[1]['scores'].get(priority, 0)
                }
        
        return recommendations

# 使用示例：比较文档工具
comparator = DocumentToolComparator()

# 添加工具评分
comparator.add_tool('GitBook', {
    'ease_of_use': 8,
    'collaboration': 9,
    'version_control': 8,
    'customization': 7,
    'integration': 8,
    'cost': 6
}, [
    'Markdown支持',
    '实时协作编辑',
    'Git集成',
    '美观的界面',
    '搜索功能强大'
])

comparator.add_tool('Notion', {
    'ease_of_use': 9,
    'collaboration': 9,
    'version_control': 6,
    'customization': 9,
    'integration': 8,
    'cost': 7
}, [
    '块状编辑',
    '数据库功能',
    '模板丰富',
    '多媒体支持',
    '任务管理'
])

comparator.add_tool('Confluence', {
    'ease_of_use': 7,
    'collaboration': 9,
    'version_control': 8,
    'customization': 8,
    'integration': 9,
    'cost': 5
}, [
    'Atlassian生态',
    '企业级功能',
    '权限管理',
    '宏功能',
    'JIRA集成'
])

comparator.add_tool('VuePress', {
    'ease_of_use': 6,
    'collaboration': 5,
    'version_control': 10,
    'customization': 9,
    'integration': 7,
    'cost': 10
}, [
    '静态站点生成',
    'Vue.js技术栈',
    '高度可定制',
    '开源免费',
    'GitHub Pages集成'
])

# 生成比较报告
print(comparator.compare_tools())

# 获取针对性推荐
recommendations = comparator.get_recommendation(['collaboration', 'cost'])
print("针对性推荐:")
for criterion, rec in recommendations.items():
    print(f"- {criterion}: {rec['tool']} (评分: {rec['score']})")

from datetime import datetime, timedelta
from typing import List, Dict, Optional
import json

class DocumentVersionManager:
    """
    文档版本管理器
    管理文档的版本控制、更新策略和生命周期
    """
    
    class DocumentVersion:
        """文档版本类"""
        
        def __init__(self, version: str, content: str, author: str, 
                     changelog: str = "", is_major: bool = False):
            """
            初始化文档版本
            
            Args:
                version: 版本号（如1.0.0）
                content: 文档内容
                author: 作者
                changelog: 变更日志
                is_major: 是否为主要版本
            """
            self.version = version
            self.content = content
            self.author = author
            self.changelog = changelog
            self.is_major = is_major
            self.created_at = datetime.now()
            self.status = "active"  # active, deprecated, archived
            
        def to_dict(self) -> Dict:
            """转换为字典格式"""
            return {
                'version': self.version,
                'author': self.author,
                'changelog': self.changelog,
                'is_major': self.is_major,
                'created_at': self.created_at.isoformat(),
                'status': self.status,
                'content_hash': hash(self.content)
            }
    
    def __init__(self, document_id: str):
        """
        初始化版本管理器
        
        Args:
            document_id: 文档唯一标识
        """
        self.document_id = document_id
        self.versions: List[DocumentVersionManager.DocumentVersion] = []
        self.current_version: Optional[DocumentVersionManager.DocumentVersion] = None
        
    def create_version(self, content: str, author: str, 
                      changelog: str = "", is_major: bool = False) -> str:
        """
        创建新版本
        
        Args:
            content: 文档内容
            author: 作者
            changelog: 变更日志
            is_major: 是否为主要版本
            
        Returns:
            str: 新版本号
        """
        # 生成版本号
        if not self.versions:
            version_number = "1.0.0"
        else:
            last_version = self.versions[-1].version
            major, minor, patch = map(int, last_version.split('.'))
            
            if is_major:
                version_number = f"{major + 1}.0.0"
            elif self._has_significant_changes(content):
                version_number = f"{major}.{minor + 1}.0"
            else:
                version_number = f"{major}.{minor}.{patch + 1}"
        
        # 创建新版本
        new_version = self.DocumentVersion(
            version=version_number,
            content=content,
            author=author,
            changelog=changelog,
            is_major=is_major
        )
        
        self.versions.append(new_version)
        self.current_version = new_version
        
        return version_number
    
    def _has_significant_changes(self, new_content: str) -> bool:
        """
        判断是否有重大变更（简化的实现）
        
        Args:
            new_content: 新内容
            
        Returns:
            bool: 是否有重大变更
        """
        if not self.current_version:
            return True
            
        old_content = self.current_version.content
        
        # 简单的变更检测：内容长度变化超过20%
        length_change = abs(len(new_content) - len(old_content)) / len(old_content)
        
        return length_change > 0.2
    
    def get_version(self, version: str) -> Optional[DocumentVersion]:
        """
        获取指定版本
        
        Args:
            version: 版本号
            
        Returns:
            DocumentVersion: 版本对象，如果不存在则返回None
        """
        for v in self.versions:
            if v.version == version:
                return v
        return None
    
    def get_version_history(self) -> List[Dict]:
        """
        获取版本历史
        
        Returns:
            List[Dict]: 版本历史列表
        """
        return [v.to_dict() for v in self.versions]
    
    def deprecate_version(self, version: str, reason: str = ""):
        """
        废弃指定版本
        
        Args:
            version: 版本号
            reason: 废弃原因
        """
        version_obj = self.get_version(version)
        if version_obj:
            version_obj.status = "deprecated"
            version_obj.deprecation_reason = reason
    
    def cleanup_old_versions(self, keep_count: int = 10):
        """
        清理旧版本，只保留指定数量的版本
        
        Args:
            keep_count: 保留的版本数量
        """
        if len(self.versions) > keep_count:
            # 保留最新的版本和所有主要版本
            versions_to_keep = []
            
            # 添加所有主要版本
            for v in self.versions:
                if v.is_major or v.status == "active":
                    versions_to_keep.append(v)
            
            # 添加最新的版本
            sorted_versions = sorted(
                self.versions, 
                key=lambda x: x.created_at, 
                reverse=True
            )
            
            for v in sorted_versions[:keep_count]:
                if v not in versions_to_keep:
                    versions_to_keep.append(v)
            
            # 归档其他版本
            for v in self.versions:
                if v not in versions_to_keep:
                    v.status = "archived"
    
    def generate_changelog(self) -> str:
        """
        生成变更日志
        
        Returns:
            str: Markdown格式的变更日志
        """
        changelog = f"# {self.document_id} 变更日志\n\n"
        
        for version in reversed(self.versions):
            changelog += f"## 版本 {version.version}"
            if version.is_major:
                changelog += " (主要版本)"
            changelog += f" - {version.created_at.strftime('%Y-%m-%d')}\n\n"
            
            changelog += f"**作者**: {version.author}\n\n"
            
            if version.changelog:
                changelog += f"**变更内容**:\n{version.changelog}\n\n"
            else:
                changelog += "**变更内容**: 无详细说明\n\n"
            
            changelog += "---\n\n"
        
        return changelog

# 使用示例
doc_manager = DocumentVersionManager("api-documentation")

# 创建初始版本
initial_content = """
# API文档

## 用户管理接口

### 登录接口
POST /api/auth/login
"""

v1 = doc_manager.create_version(
    content=initial_content,
    author="张三",
    changelog="初始版本发布",
    is_major=True
)

print(f"创建版本: {v1}")

# 添加新功能
updated_content = initial_content + """

### 注册接口
POST /api/auth/register

### 用户信息接口  
GET /api/user/profile
"""

v2 = doc_manager.create_version(
    content=updated_content,
    author="李四", 
    changelog="添加注册和用户信息接口"
)

print(f"创建版本: {v2}")

# 生成变更日志
print("\n" + doc_manager.generate_changelog())