基于 Vue3 + TypeScript + Ant Design Vue 的现代化企业级后台管理系统，支持 COS 混合部署模式，提供完整的业务开发解决方案。

• 🎯 COS 混合部署: 支持腾讯云 COS 静态资源分离部署，提升访问速度
• 📊 动态表格/表单: 基于 JSON Schema 的动态表格和表单生成器
• 🧩 组件化架构: 严格的组件开发规范，支持业务组件和通用组件分离
• 🌐 国际化支持: 完整的 i18n 多语言解决方案
• 🎨 主题定制: 支持亮色/暗色主题切换和自定义主题
• 📱 响应式设计: 完美适配桌面端和移动端
• 🔐 权限管理: 基于角色的访问控制 (RBAC)
• ⚡ 性能优化: 路由懒加载、组件按需加载、虚拟滚动等

• 前端框架: Vue 3.5+ + TypeScript 5.x
• UI 组件库: Ant Design Vue 4.x
• 构建工具: Vite 5.x + Rollup
• 状态管理: Pinia + 持久化插件
• 路由管理: Vue Router 4.x
• 样式方案: UnoCSS + Less
• 代码规范: ESLint + Prettier + Husky
• 测试工具: Mock Service Worker (MSW)
• 部署方案: Docker + 腾讯云 COS

• Node.js >= 20.0.0
• Yarn >= 4.0.0

# 克隆项目
git clone https://github.com/buqiyuan/vue3-antdv-admin

# 进入项目目录
cd vue3-antdv-admin

# 安装依赖
yarn install

# 启动开发服务器
yarn dev

# 构建生产版本
yarn build

# 预览构建结果
yarn preview

# 部署到 COS (自动版本管理)
yarn deploy

# 指定版本类型部署
yarn deploy:major    # 主版本号 +1
yarn deploy:minor    # 次版本号 +1  
yarn deploy:patch    # 修订版本号 +1

# 清理指定版本
yarn deploy:clean

# 查看当前版本
yarn deploy:version

src/
├── api/                    # API 接口定义
│   ├── backend/           # 后端 API (自动生成)
│   └── demo/              # 演示 API
├── assets/                # 静态资源
├── components/            # 组件库
│   ├── basic/            # 基础组件
│   ├── business/         # 业务组件  
│   └── core/             # 核心组件 (动态表格/表单)
├── hooks/                 # 组合式函数
├── layout/               # 布局组件
├── locales/              # 国际化配置
├── router/               # 路由配置
├── store/                # 状态管理
├── styles/               # 全局样式
├── utils/                # 工具函数
└── views/                # 页面组件
    ├── dashboard/        # 仪表盘
    ├── system/           # 系统管理
    └── ...

views/
└── 业务模块名/
    └── 页面名称/
        ├── index.vue          # 页面主文件
        ├── components/        # 页面专用组件
        │   ├── EditModal.vue
        │   └── DetailDrawer.vue
        └── hooks/            # 页面专用逻辑
            └── useTableData.ts

<template>
  <div class="page-container">
    <div class="page-header">
      <h1>{{ title }}</h1>
    </div>
    <div class="page-content">
      <!-- 页面内容 -->
    </div>
  </div>
</template>

<script lang="ts">
import { defineComponent, reactive, toRefs, onMounted } from 'vue'

export default defineComponent({
  name: 'PageName',
  setup() {
    // 响应式数据
    const state = reactive({
      title: '页面标题',
      loading: false,
      dataSource: [],
    })

    // 业务方法
    const methods = {
      /**
       * 初始化页面数据
       */
      async initData() {
        state.loading = true
        try {
          // 数据加载逻辑
        }
        finally {
          state.loading = false
        }
      },

      /**
       * 处理用户操作
       */
      handleAction() {
        // 操作逻辑
      },
    }

    // 生命周期
    onMounted(() => {
      methods.initData()
    })

    return {
      ...toRefs(state),
      ...methods,
    }
  },
})
</script>

<style lang="less" scoped>
.page-container {
  @apply p-4;
}

.page-header {
  @apply mb-4 pb-4 border-b border-gray-200;
}

.page-content {
  @apply bg-white rounded-lg p-4;
}
</style>

• 基础组件 (components/basic/): 通用 UI 组件，无业务逻辑
• 业务组件 (components/business/): 包含特定业务逻辑的组件
• 页面组件 (views/*/components/): 页面专用组件

• 单一职责: 每个组件只负责一个功能
• 数据操作内化: API 调用和数据处理在组件内部完成
• UI 反馈内化: 消息提示、确认框等与业务操作一起处理
• 事件通信简化: 减少复杂数据传递，优先使用简单通知机制

components/basic/组件名/
├── index.vue              # 组件主文件
├── types.ts              # 类型定义
├── hooks/                # 组件专用逻辑
│   └── useComponentLogic.ts
└── __tests__/            # 单元测试
    └── index.test.ts

// api/demo/user.ts
import { request } from '@/utils/request'

export interface UserInfo {
  id: number
  name: string
  email: string
}

export interface UserListParams {
  page: number
  pageSize: number
  keyword?: string
}

/**
 * 获取用户列表
 */
export function getUserList(params: UserListParams) {
  return request<UserInfo[]>({
    url: '/api/users',
    method: 'GET',
    params,
  })
}

/**
 * 创建用户
 */
export function createUser(data: Omit<UserInfo, 'id'>) {
  return request<UserInfo>({
    url: '/api/users',
    method: 'POST',
    data,
  })
}

// 在组件中使用
import { message } from 'ant-design-vue'
import { createUser, getUserList } from '@/api/demo/user'

const methods = {
  /**
   * 加载用户数据
   */
  async loadUsers() {
    try {
      state.loading = true
      const response = await getUserList({
        page: state.pagination.current,
        pageSize: state.pagination.pageSize,
        keyword: state.searchKeyword,
      })
      state.dataSource = response.data
      state.pagination.total = response.total
    }
    catch (error) {
      message.error('加载用户数据失败')
      console.error('Load users error:', error)
    }
    finally {
      state.loading = false
    }
  },

  /**
   * 创建用户
   */
  async handleCreateUser(userData: Omit<UserInfo, 'id'>) {
    try {
      await createUser(userData)
      message.success('用户创建成功')
      // 刷新列表
      await methods.loadUsers()
    }
    catch (error) {
      message.error('用户创建失败')
      throw error // 让调用方处理错误
    }
  },
}

// store/modules/user.ts
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    userInfo: null as UserInfo | null,
    permissions: [] as string[],
    token: '',
  }),

  getters: {
    isLoggedIn: state => !!state.token,
    hasPermission: state => (permission: string) =>
      state.permissions.includes(permission),
  },

  actions: {
    /**
     * 用户登录
     */
    async login(credentials: LoginParams) {
      const response = await loginApi(credentials)
      this.token = response.token
      this.userInfo = response.userInfo
      this.permissions = response.permissions
      return response
    },

    /**
     * 用户登出
     */
    logout() {
      this.token = ''
      this.userInfo = null
      this.permissions = []
    },
  },

  persist: {
    key: 'user-store',
    storage: localStorage,
    paths: ['token', 'userInfo'],
  },
})

• 命名规范: 使用 camelCase 命名变量和函数，PascalCase 命名组件和类
• 文件命名: 组件文件使用 PascalCase，其他文件使用 kebab-case
• 注释规范: 所有函数必须添加 JSDoc 注释说明功能、参数和返回值
• 类型定义: 严格使用 TypeScript，避免使用 any 类型

• 组件懒加载: 路由组件使用动态导入
• 列表虚拟化: 大数据量列表使用虚拟滚动
• 图片优化: 使用 WebP 格式，添加懒加载
• 缓存策略: 合理使用 keep-alive 缓存页面

• 优先使用 UnoCSS: 原子化 CSS 类，提高开发效率
• 组件样式隔离: 使用 scoped 避免样式污染
• 响应式设计: 使用 UnoCSS 响应式前缀适配不同屏幕
• 主题变量: 使用 CSS 变量支持主题切换

• 统一错误处理: 在 request 拦截器中处理通用错误
• 用户友好提示: 使用 message 组件显示操作结果
• 错误边界: 使用 ErrorBoundary 组件捕获组件错误
• 日志记录: 重要操作添加日志记录

• XSS 防护: 用户输入内容进行转义处理
• CSRF 防护: API 请求携带 CSRF Token
• 权限校验: 前端路由和后端接口都要进行权限校验
• 敏感信息: 不在前端存储敏感信息

• Vue Language Features (Volar)
• TypeScript Vue Plugin (Volar)
• ESLint
• Prettier
• UnoCSS
• Auto Rename Tag
• Bracket Pair Colorizer

# 代码检查
yarn lint

# 代码格式化
yarn lint:fix

# 类型检查
yarn type-check

# 清理缓存
yarn clean:cache

# 生成 API 类型
yarn openapi

• 在线预览
• 项目文档
• API 文档
• 后端仓库
• 部署指南
• 更新日志

遵循 Conventional Commits 规范：

• feat: 新功能
• fix: 修复问题
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• perf: 性能优化
• test: 测试相关
• chore: 构建工具或依赖更新

1. Fork 项目到个人仓库
2. 创建功能分支: git checkout -b feature/new-feature
3. 提交代码: git commit -m 'feat: add new feature'
4. 推送分支: git push origin feature/new-feature
5. 创建 Pull Request

MIT License

---

默认账号: admin / a123456