Files

万物街 1cd5d3bdef feat: 完成 NestJS 后端核心底座开发 (M1-M6) 和 Ant Design Vue 前端迁移

主要更新：
1. 后端核心底座完成 (M1-M6)：
   - 健康检查、指标监控、分布式锁
   - 事件总线、队列系统、事务管理
   - 安全守卫、多租户隔离、存储适配器
   - 审计日志、配置管理、多语言支持

2. 前端迁移到 Ant Design Vue：
   - 从 Element Plus 迁移到 Ant Design Vue
   - 完善 system 模块 (role/menu/dept)
   - 修复依赖和配置问题

3. 文档完善：
   - AI 开发工作流文档
   - 架构约束和开发规范
   - 项目进度跟踪

4. 其他改进：
   - 修复编译错误和类型问题
   - 完善测试用例
   - 优化项目结构

2025-08-27 11:24:22 +08:00

3.8 KiB

Raw Blame History

文档脚本说明

API 文档自动生成脚本

功能说明

generate-api-docs.js 脚本用于从后端的 Swagger API 自动生成前端文档。

使用方法

1. 安装依赖

cd admin/docs
npm install

2. 运行自动生成脚本

# 使用默认配置（http://localhost:3000）
npm run generate-api

# 指定后端服务地址
BACKEND_URL=http://your-backend-url npm run generate-api

# 开发环境快捷命令
npm run generate-api:dev

3. 查看生成结果

生成完成后，会在以下目录生成文档：

admin/docs/src/wwjcloud/openapi/api/
├── api/                    # 前台 API (对应后端 /api/)
│   ├── index.md           # 前台 API 概览
│   ├── member.md          # 会员管理 API (自动生成)
│   ├── auth.md            # 认证 API (自动生成)
│   └── ...                # 其他模块 API
└── adminapi/              # 后台 API (对应后端 /adminapi/)
    ├── index.md           # 后台 API 概览
    ├── member.md          # 会员管理 API (自动生成)
    ├── admin.md           # 管理员 API (自动生成)
    └── ...                # 其他模块 API

配置说明

环境变量

BACKEND_URL: 后端服务地址，默认为 http://localhost:3000

API 分组配置

脚本会自动处理以下 API 分组：

前台 API: /api-json (对应后端 /api/ 路径)
后台 API: /adminapi-json (对应后端 /adminapi/ 路径)

自动生成内容

生成的文档包含：

API 接口列表: 按模块自动分组
请求参数说明: 自动解析 Swagger 参数定义
响应示例: 统一的响应格式
接口描述: 从 Swagger 自动提取
在线测试链接: 指向后端 Swagger UI

目录结构对齐

前端文档目录结构与后端保持一致：

后端路径             前端文档路径
/api/               → /api/
/adminapi/          → /adminapi/

注意事项

后端服务必须运行: 确保后端服务已启动并可访问
Swagger 配置: 确保后端已正确配置 Swagger 文档
网络连接: 确保能够访问后端服务地址
权限问题: 某些 API 可能需要认证才能访问

故障排除

1. 连接失败

# 检查后端服务是否运行
curl http://localhost:3000/api-json

# 检查网络连接
ping localhost

2. 权限问题

如果 API 需要认证，可以在脚本中添加认证头：

// 在 generate-api-docs.js 中修改
const response = await axios.get(url, {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

3. 文档生成失败

检查输出目录权限：

# 确保目录存在且有写权限
ls -la admin/docs/src/wwjcloud/openapi/api/

自定义配置

如需自定义配置，可以修改 generate-api-docs.js 中的 config 对象：

const config = {
  // 修改后端服务地址
  backendUrl: process.env.BACKEND_URL || 'http://localhost:3000',
  
  // 修改输出目录
  docsDir: path.join(__dirname, '../src/wwjcloud/openapi/api'),
  
  // 添加新的 API 分组
  apiGroups: {
    // ... 现有配置
    custom: {
      name: '自定义 API',
      swaggerPath: '/custom-json',
      outputDir: 'custom',
      prefix: '/custom'
    }
  }
};

集成到 CI/CD

可以将自动生成脚本集成到 CI/CD 流程中：

# GitHub Actions 示例
- name: Generate API Docs
  run: |
    cd admin/docs
    npm install
    npm run generate-api
  env:
    BACKEND_URL: ${{ secrets.BACKEND_URL }}

3.8 KiB Raw Blame History Unescape Escape