项目结构

这里将详细说明 Elysia Admin 的整体结构，包括前端和后端的目录组织、文件功能及模块划分，能够帮助开发人员快速了解项目架构。

整体结构

elysia-admin/
├── admin/                      # Vue 3 前端
├── server/                     # Elysia + Bun 后端
├── docs/                       # VitePress 文档站
├── .ai/                        # AI 开发指南（模块 SOP、代码示例等）
├── .cursor/                    # Cursor 规则与 Skill
├── .claude/                    # Claude 规则
├── .codex/                     # Codex 配置
├── .kiro/                      # Kiro Steering
├── .trae/                      # Trae 规则
├── .vscode/                    # VS Code 工作区配置
├── AGENTS.md                   # 项目级 AI 指引
├── elysia-admin.code-workspace
├── LICENSE
├── README.md
└── .gitignore

前端结构

前端采用 Vue 3 框架构建，遵循模块化、组件化的设计原则。

├── src
│   ├── api                     # API 接口相关代码
│   │   ├── auth.ts             # 认证相关 API 接口定义（登录、注册、用户信息等）
│   │   └── system-manage.ts    # 系统管理相关 API 接口定义（菜单、用户、角色管理等）
│   ├── App.vue                 # Vue 根组件，定义应用全局结构和入口
│   ├── assets                  # 静态资源目录
│   │   ├── images              # 图片资源目录
│   │   ├── styles              # 全局样式文件
│   │   │   ├── core            # 核心样式（系统级样式）
│   │   │   ├── custom          # 自定义样式（业务级样式）
│   │   │   └── index.scss      # 样式入口文件
│   │   └── svg                 # SVG 相关资源
│   │       └── loading.ts      # 加载动画 SVG 定义
│   ├── components              # 组件目录
│   │   ├── business            # 业务组件（业务相关自定义组件）
│   │   │   └── comment-widget  # 评论组件
│   │   └── core                # 核心组件（系统级通用组件库）
│   │       ├── banners         # 横幅组件
│   │       ├── base            # 基础组件
│   │       ├── cards           # 卡片组件
│   │       ├── charts          # 图表组件
│   │       ├── forms           # 表单组件
│   │       ├── layouts         # 布局组件
│   │       ├── media           # 媒体组件
│   │       ├── others          # 其他组件
│   │       ├── tables          # 表格组件
│   │       ├── text-effect     # 文本特效组件
│   │       ├── theme           # 主题相关组件
│   │       ├── views           # 视图组件
│   │       └── widget          # 小部件组件
│   ├── config                  # 项目配置目录
│   │   ├── assets              # 静态资源配置
│   │   │   └── images.ts       # 图片资源路径配置
│   │   ├── modules             # 模块化配置
│   │   │   ├── component.ts    # 组件配置
│   │   │   ├── fastEnter.ts    # 快捷入口配置
│   │   │   ├── festival.ts     # 节日/活动配置
│   │   │   └── headerBar.ts    # 顶部栏配置
│   │   ├── index.ts            # 配置入口文件
│   │   └── setting.ts          # 系统设置配置
│   ├── directives              # Vue 自定义指令
│   │   ├── business            # 业务指令
│   │   │   ├── highlight.ts    # 高亮指令
│   │   │   └── ripple.ts       # 波纹效果指令
│   │   ├── core                # 核心指令
│   │   │   ├── auth.ts         # 认证指令
│   │   │   └── roles.ts        # 角色权限指令
│   │   └── index.ts            # 指令入口文件
│   ├── enums                   # 枚举定义
│   │   ├── appEnum.ts          # 应用级枚举（主题类型、语言类型等）
│   │   └── formEnum.ts         # 表单相关枚举（表单状态、验证规则等）
│   ├── env.d.ts                # TypeScript 环境声明文件
│   ├── hooks                   # Vue 3 Composable 函数（可复用逻辑）
│   │   ├── core                # 核心 Hooks
│   │   │   ├── useAppMode.ts   # 应用模式相关逻辑
│   │   │   ├── useAuth.ts      # 认证相关逻辑
│   │   │   ├── useCeremony.ts  # 节日/仪式相关逻辑
│   │   │   ├── useChart.ts     # 图表相关逻辑
│   │   │   ├── useCommon.ts    # 通用逻辑
│   │   │   ├── useFastEnter.ts # 快捷入口逻辑
│   │   │   ├── useHeaderBar.ts # 顶部栏逻辑
│   │   │   ├── useLayoutHeight.ts # 布局高度计算逻辑
│   │   │   ├── useTable.ts     # 表格逻辑
│   │   │   ├── useTableColumns.ts # 表格列配置逻辑
│   │   │   ├── useTableHeight.ts # 表格高度计算逻辑
│   │   │   └── useTheme.ts     # 主题切换逻辑
│   │   └── index.ts            # Hooks 入口文件
│   ├── locales                 # 国际化（i18n）资源
│   │   ├── index.ts            # 国际化入口文件
│   │   └── langs               # 多语言文件
│   │       ├── en.json         # 英文语言包
│   │       └── zh.json         # 中文语言包
│   ├── main.ts                 # 项目主入口文件
│   ├── mock                    # Mock 数据目录
│   │   ├── json                # JSON 格式 Mock 数据
│   │   │   └── chinaMap.json   # 中国地图数据
│   │   ├── temp                # 临时 Mock 数据
│   │   │   ├── articleList.ts  # 文章列表数据
│   │   │   ├── commentDetail.ts # 评论详情数据
│   │   │   ├── commentList.ts  # 评论列表数据
│   │   │   └── formData.ts     # 表单数据
│   │   └── upgrade             # 更新日志数据
│   │       └── changeLog.ts    # 变更日志数据
│   ├── plugins                 # 插件配置
│   │   ├── echarts.ts          # ECharts 图表库配置
│   │   └── index.ts            # 插件入口文件
│   ├── router                  # Vue Router 路由相关代码
│   │   ├── core                # 路由核心功能
│   │   │   ├── ComponentLoader.ts # 组件加载器
│   │   │   ├── IframeRouteManager.ts # Iframe 路由管理器
│   │   │   ├── MenuProcessor.ts # 菜单处理器
│   │   │   ├── RouteRegistry.ts # 路由注册器
│   │   │   ├── RouteTransformer.ts # 路由转换器
│   │   │   ├── RouteValidator.ts # 路由验证器
│   │   │   └── index.ts        # 核心功能入口
│   │   ├── guards              # 路由守卫
│   │   │   ├── afterEach.ts    # 全局后置守卫
│   │   │   └── beforeEach.ts   # 全局前置守卫
│   │   ├── modules             # 路由模块定义
│   │   │   ├── article.ts      # 文章模块路由
│   │   │   ├── dashboard.ts    # 仪表盘路由
│   │   │   ├── examples.ts     # 示例页面路由
│   │   │   ├── exception.ts    # 异常页面路由
│   │   │   ├── help.ts         # 帮助页面路由
│   │   │   ├── index.ts        # 路由模块入口
│   │   │   ├── result.ts       # 结果页面路由
│   │   │   ├── safeguard.ts    # 安全防护路由
│   │   │   ├── system.ts       # 系统管理路由
│   │   │   ├── template.ts     # 模板页面路由
│   │   │   └── widgets.ts      # 小组件路由
│   │   ├── routes              # 路由配置
│   │   │   ├── asyncRoutes.ts  # 异步路由（动态路由）
│   │   │   └── staticRoutes.ts # 静态路由（固定路由）
│   │   ├── index.ts            # 路由主入口
│   │   └── routesAlias.ts      # 路由别名定义
│   ├── store                   # Pinia 状态管理
│   │   ├── modules             # 状态管理模块
│   │   │   ├── menu.ts         # 菜单状态管理
│   │   │   ├── setting.ts      # 设置状态管理
│   │   │   ├── table.ts        # 表格状态管理
│   │   │   ├── user.ts         # 用户状态管理
│   │   │   └── worktab.ts      # 工作标签页状态管理
│   │   └── index.ts            # Pinia 入口文件
│   ├── types                   # TypeScript 类型定义
│   │   ├── api                 # API 相关类型
│   │   │   └── api.d.ts        # API 接口类型定义
│   │   ├── common              # 通用类型定义
│   │   │   ├── index.ts        # 通用类型入口
│   │   │   └── response.ts     # 响应类型定义
│   │   ├── component           # 组件相关类型
│   │   │   ├── chart.ts        # 图表组件类型
│   │   │   └── index.ts        # 组件类型入口
│   │   ├── config              # 配置相关类型
│   │   │   └── index.ts        # 配置类型定义
│   │   ├── import              # 自动导入类型声明
│   │   │   ├── auto-imports.d.ts # 自动导入的函数类型
│   │   │   └── components.d.ts # 自动导入的组件类型
│   │   ├── router              # 路由相关类型
│   │   │   └── index.ts        # 路由类型定义
│   │   ├── store               # 状态管理相关类型
│   │   │   └── index.ts        # Store 类型定义
│   │   └── index.ts            # 类型定义总入口
│   ├── utils                   # 工具函数目录
│   │   ├── constants           # 常量定义
│   │   │   ├── index.ts        # 常量入口
│   │   │   └── links.ts        # 链接常量
│   │   ├── form                # 表单相关工具
│   │   │   ├── index.ts        # 表单工具入口
│   │   │   ├── responsive.ts   # 响应式表单工具
│   │   │   └── validator.ts    # 表单验证工具
│   │   ├── http                # HTTP 请求工具
│   │   │   ├── error.ts        # 错误处理
│   │   │   ├── index.ts        # HTTP 工具入口
│   │   │   └── status.ts       # 状态码处理
│   │   ├── navigation          # 导航相关工具
│   │   │   ├── index.ts        # 导航工具入口
│   │   │   ├── jump.ts         # 页面跳转工具
│   │   │   ├── route.ts        # 路由工具
│   │   │   └── worktab.ts      # 工作标签页工具
│   │   ├── storage             # 存储相关工具
│   │   │   ├── index.ts        # 存储工具入口
│   │   │   ├── storage-config.ts # 存储配置
│   │   │   ├── storage-key-manager.ts # 存储键管理
│   │   │   └── storage.ts      # 存储工具实现
│   │   ├── sys                 # 系统相关工具
│   │   │   ├── console.ts      # 控制台工具
│   │   │   ├── error-handle.ts # 错误处理
│   │   │   ├── index.ts        # 系统工具入口
│   │   │   ├── mittBus.ts      # 事件总线
│   │   │   └── upgrade.ts      # 升级相关工具
│   │   ├── table               # 表格相关工具
│   │   │   ├── tableCache.ts   # 表格缓存
│   │   │   ├── tableConfig.ts  # 表格配置
│   │   │   └── tableUtils.ts   # 表格工具函数
│   │   ├── ui                  # UI 相关工具
│   │   │   ├── animation.ts    # 动画工具
│   │   │   ├── colors.ts       # 颜色工具
│   │   │   ├── emojo.ts        # 表情工具
│   │   │   ├── index.ts        # UI 工具入口
│   │   │   ├── loading.ts      # 加载动画工具
│   │   │   └── tabs.ts         # 标签页工具
│   │   ├── index.ts            # 工具函数总入口
│   │   └── router.ts           # 路由工具函数
│   └── views                   # 页面组件目录
├── tsconfig.json               # TypeScript 配置文件
├── .env                        # 环境变量配置文件
├── .env.development            # 开发环境变量配置文件
├── .env.production             # 生产环境变量配置文件
├── .gitattributes              # Git 属性文件
├── .gitignore                  # Git 忽略文件
├── .prettierignore             # Prettier 忽略文件
├── .prettierrc                 # Prettier 配置文件
├── .stylelintignore            # Stylelint 忽略文件
├── .stylelintrc                # Stylelint 配置文件
├── commitlint.config.cjs       # Commitlint 配置文件
├── eslint.config.mjs           # ESLint 配置文件
├── index.html                  # HTML 入口文件
├── package.json                # 项目依赖配置文件
├── pnpm-lock.yaml              # pnpm 锁定文件
└── vite.config.ts              # Vite 配置文件

后端结构

后端采用 Elysia.js 框架构建，遵循分层架构设计。

├── database                      # 数据库定义
│   ├── schema                    # 业务表 Schema
│   ├── sql                       # 初始化 SQL、模块 handoff SQL
│   └── base-schema.ts            # 公共字段定义
├── script                        # 构建 / 注册表 / 种子脚本
├── test                          # 单元测试
│   ├── core
│   ├── shared
│   └── types
├── public                        # 静态资源
├── src
│   ├── config                    # 环境配置
│   ├── constants                 # 枚举与字典常量
│   ├── core                      # 核心基础设施
│   │   └── database              # PG / Redis / Repository / 事务
│   ├── infrastructure            # 外部集成
│   │   ├── clients               # 第三方客户端
│   │   │   └── payment           # 支付客户端
│   │   │       └── providers     # alipay / paypal / wechat / crypto
│   │   ├── cron                  # 进程内定时任务
│   │   ├── queue                 # BullMQ 队列
│   │   │   ├── config
│   │   │   ├── core
│   │   │   ├── runtime
│   │   │   └── queues            # flow-buffer / system-cron / trade-order
│   │   └── storage               # 对象存储
│   │       └── providers         # cos / kodo / oss / rustfs
│   ├── middleware                # 中间件
│   │   └── guards                # 认证 / 权限 / IP 黑名单 / 限流
│   ├── modules                   # 业务模块
│   │   ├── auth                  # 认证
│   │   ├── business-merchant     # 商户管理
│   │   ├── business-orders       # 订单管理
│   │   ├── business-payments     # 支付管理
│   │   ├── business-refund       # 退款管理
│   │   ├── monitor-cache         # 缓存监控
│   │   ├── monitor-job           # 定时任务监控
│   │   ├── monitor-online        # 在线用户监控
│   │   ├── system-api            # API 接口管理
│   │   ├── system-dept           # 部门管理
│   │   ├── system-dict           # 字典管理
│   │   ├── system-ip-black       # IP 黑名单
│   │   ├── system-login-log      # 登录日志
│   │   ├── system-menu           # 菜单管理
│   │   ├── system-notice         # 通知公告
│   │   ├── system-oper-log       # 操作日志
│   │   ├── system-role           # 角色管理
│   │   ├── system-storage        # 存储配置
│   │   └── system-user           # 用户管理
│   ├── worker-sandbox            # 队列沙箱任务注册
│   ├── shared                    # 共享工具函数
│   ├── types                     # 类型定义
│   ├── app.ts                    # 应用入口
│   └── index.ts                  # 总入口
├── Dockerfile
├── drizzle.config.ts
├── package.json
├── bun.lock
├── tsconfig.json
└── README.md