Solos Admin

Solos Admin 是一个面向中后台项目的 Vue 3 通用管理模板。它不是绑定某个业务的后台，而是提供一套可直接二开的后台骨架：路由菜单、权限、请求、Mock、布局、常用页面模板和质量门槛都已经预置。

适用场景

• 企业内部管理后台
• SaaS 管理端
• 运营平台
• 内容管理系统
• 数据看板与配置平台
• 需要快速搭建权限、菜单、列表、表单、详情页的 Vue 项目

技术栈

• Vue 3 + <script setup lang="ts">
• Vite 8
• TypeScript
• Vue Router + unplugin-vue-router
• Pinia
• Element Plus
• UnoCSS + Iconify
• alova
• ECharts
• MdEditorV3
• xlsx
• Vitest + Vue Test Utils
• ESLint + Prettier

核心能力

• 文件路由：src/pages 下的页面自动注册为路由
• Route Meta：页面标题、图标、权限、缓存、隐藏状态集中在 definePage().meta
• 后台布局：侧边栏、顶栏、标签页、面包屑、内容区
• 菜单派生：根据路由与后端访问授权生成菜单
• 权限体系：登录态、角色路由权限、按钮权限 key
• 请求层：alova/fetch 统一封装
• API 模式：mock / real 可切换
• Mock 数据：本地可完整演示登录、权限、菜单和列表数据
• 页面模板：列表、表单、详情、高级搜索、批量操作、行内编辑、树形表格
• 内容示例：图表、Markdown、上传、Excel 导入导出
• 质量门槛：类型检查、单元测试、构建、Lint、格式检查

快速开始

pnpm install
pnpm dev

默认开发环境使用 mock API，可以直接登录体验。

默认演示账号：

• 管理员：登录页选择 管理员
• 编辑员：登录页选择 编辑员

常用命令

pnpm dev           # 启动开发服务
pnpm typecheck     # TypeScript / Vue 类型检查
pnpm test          # 运行单元测试
pnpm build         # 类型检查并构建生产包
pnpm lint          # ESLint 检查
pnpm format:check  # Prettier 格式检查
pnpm check         # 模板完整质量门槛
pnpm preview       # 预览生产构建

API 模式

开发环境默认：

VITE_API_MODE=mock
VITE_API_BASE_URL=

生产环境默认：

VITE_API_MODE=real
VITE_API_BASE_URL=https://api.example.com

模式说明：

• VITE_API_MODE=mock
  • 使用 src/api/mock.ts
  • 适合模板演示、本地开发、无后端联调
• VITE_API_MODE=real
  • 使用真实后端
  • 需要配置 VITE_API_BASE_URL

更多说明见：docs/api-integration.md、docs/mock-guide.md 和 docs/template-contracts.md。

目录结构

src/
  api/              # alova 客户端、响应处理、mock、模块 API
  auth/             # token refresh、登录过期事件
  components/admin/ # 后台通用组件
  composables/      # 页面查询、表单、权限、搜索、tabs 等复用逻辑
  constants/        # 常量
  layouts/          # AdminLayout / BlankLayout
  pages/            # 文件路由页面
  router/           # 路由守卫、菜单与访问控制
  stores/           # app/user/permission/tabs
  styles/           # 全局样式
  types/            # 模板契约、应用类型与路由类型扩展

docs/               # 模板使用与二开文档

详细说明见：docs/project-structure.md。

新增页面

1. 在 src/pages 下新增 .vue 页面。
2. 使用 definePage({ meta: ... }) 声明页面元信息。
3. 如果要显示在菜单中，提供 meta.title，并确保没有设置 hidden: true。
4. 如果页面需要权限控制，设置 roles 或 permissions。
5. 如果页面需要接口，在 src/api/modules 下新增 API method。

示例：

<script setup lang="ts">
definePage({
  meta: {
    title: '用户管理',
    icon: 'i-ep-user',
    layout: 'admin',
    requiresAuth: true,
    roles: ['admin'],
    permissions: ['system:user:view'],
    order: 10,
  },
})
</script>

路由、菜单、权限详细约定见：docs/route-menu-permission.md。

模板边界

Solos Admin 默认遵循以下边界：

• 桌面端后台优先，不作为移动端模板
• 默认使用 RBAC 权限模型
• 路由能力由前端 definePage().meta 声明
• 可访问范围由后端 /auth/access 返回
• 按钮权限由用户 profile 的 permissions 控制
• Mock 只用于模板演示和本地开发，不代表生产鉴权方案
• 模板不绑定任何业务领域，业务模块应放在独立页面/API 模块中扩展

文档

• docs/getting-started.md：快速开始
• docs/project-structure.md：目录结构与模块边界
• docs/route-menu-permission.md：路由、菜单和权限约定
• docs/template-contracts.md：路由 Meta、后端访问清单与 API 响应契约
• docs/api-integration.md：真实后端接入契约
• docs/mock-guide.md：Mock 模式和本地演示数据
• docs/crud-guide.md：标准 CRUD 页面建议
• docs/deployment.md：构建与部署
• docs/faq.md：常见问题

二开建议

拿到模板后通常需要先改：

• package.json 的项目名
• 登录页品牌文案
• 侧边栏 Logo / 系统名称
• favicon
• 主题色和基础样式
• .env.* 的 API 地址
• src/api/modules 里的业务 API
• src/pages 下的业务页面
• src/api/mock.ts 中的本地演示数据

质量门槛

提交前建议运行：

pnpm check

该命令会依次执行：

1. pnpm lint
2. pnpm format:check
3. pnpm test
4. pnpm build

后续规划

• 强化 route meta 校验测试
• 抽象标准 CRUD composable
• 增加更多组件级测试
• 增加 CI 示例
• 增加主题/品牌初始化脚本