#!/usr/bin/env python3
"""
API文档格式统一脚本
用于批量更新API文档格式，使其符合统一的规范标准
"""

import os
import re
from pathlib import Path

def update_api_documentation(file_path):
    """更新单个API文档文件的格式"""
    
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        
        # 1. 添加版本号和统一头部格式
        if not re.search(r'# .*API 文档 \(v\d+\.\d+\.\d+\)', content):
            content = re.sub(r'# (.+?) API 文档', r'# \1 API 文档 (v1.0.0)', content)
        
        # 2. 统一接口概述部分
        overview_pattern = r'## 1\. 接口概述\n\n### 1\.1 功能范围\n([\s\S]*?)\n### 1\.2 基础路径'
        if not re.search(overview_pattern, content):
            # 添加标准的接口概述结构
            content = re.sub(r'## 1\. 接口概述\n\n', 
                           '## 1. 接口概述\n\n### 1.1 功能范围\n- 功能点1\n- 功能点2\n- 功能点3\n\n### 1.2 基础路径\n', 
                           content)
        
        # 3. 添加权限控制和全局错误码
        if '### 1.3 权限控制' not in content:
            content = content.replace('### 1.2 基础路径', 
                                    '### 1.2 基础路径\n`/api/v1/[系统名称]`\n\n### 1.3 权限控制\n- 公开接口（无需认证）：数据查询\n- 管理接口（需要认证）：数据管理\n- 系统接口（高级权限）：配置管理\n\n### 1.4 全局错误码\n| 状态码 | 说明               |\n|--------|--------------------|\n| 400    | 请求参数无效       |\n| 401    | 未授权             |\n| 403    | 权限不足           |\n| 404    | 资源不存在         |\n| 500    | 服务器内部错误     |')
        
        # 4. 统一接口定义格式
        # 将旧的接口定义格式转换为新的表格格式
        content = re.sub(r'### (\d+\.\d+) (.+?)\n```\n(\w+) (.+?)\n```\n\n\*\*请求参数\*\*:\n- (.+?)\n\n\*\*响应示例\*\*:', 
                        r'### \1 \2\n```\n\3 \4\n```\n\n**请求参数**:\n| 参数名      | 类型   | 必填 | 说明               |\n|-------------|--------|------|--------------------|\n| \5          | string | 是   | 参数说明           |\n\n**响应示例**:', 
                        content)
        
        # 5. 添加版本历史
        if '## 版本历史' not in content and '## 3. 版本历史' not in content:
            content += '\n## 3. 版本历史\n\n### v1.0.0 (2024-01-20)\n- 新增: 按照API文档规范标准统一格式\n- 优化: 统一响应格式和错误处理\n- 功能: 完成基础接口定义'
        
        # 写入更新后的内容
        with open(file_path, 'w', encoding='utf-8') as f:
            f.write(content)
            
        print(f"✓ 已更新: {file_path}")
        return True
        
    except Exception as e:
        print(f"✗ 更新失败 {file_path}: {e}")
        return False

def main():
    """主函数"""
    api_docs_dir = Path("/Users/ainongkeji/code/vue/xlxumu/docs/design/api")
    
    if not api_docs_dir.exists():
        print(f"API文档目录不存在: {api_docs_dir}")
        return
    
    print("开始统一API文档格式...")
    print("=" * 50)
    
    # 获取所有API文档文件
    api_files = []
    for ext in ['*.md', '*.markdown']:
        api_files.extend(api_docs_dir.glob(ext))
    
    updated_count = 0
    total_count = len(api_files)
    
    for file_path in api_files:
        if update_api_documentation(file_path):
            updated_count += 1
    
    print("=" * 50)
    print(f"完成! 已更新 {updated_count}/{total_count} 个API文档")
    
    # 生成检查报告
    generate_check_report(api_docs_dir)

def generate_check_report(api_docs_dir):
    """生成格式检查报告"""
    print("\n格式检查报告:")
    print("-" * 30)
    
    check_items = [
        ("版本号标识", r'# .*API 文档 \(v\d+\.\d+\.\d+\)'),
        ("权限控制", r'### 1\.3 权限控制'),
        ("全局错误码", r'### 1\.4 全局错误码'),
        ("统一响应格式", r'"status": "success"'),
        ("版本历史", r'## .*版本历史')
    ]
    
    api_files = []
    for ext in ['*.md', '*.markdown']:
        api_files.extend(api_docs_dir.glob(ext))
    
    for file_path in api_files:
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        
        print(f"\n检查文件: {file_path.name}")
        
        for check_name, pattern in check_items:
            if re.search(pattern, content):
                print(f"  ✓ {check_name}")
            else:
                print(f"  ✗ {check_name} (缺失)")

if __name__ == "__main__":
    main()