feat(website): 优化新闻轮播功能并更新导航链接

scripts/update_api_docs.py

@@ -0,0 +1,115 @@
+#!/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()