Admin 系统结构

目录

• 功能说明
• 设计思路
• 系统架构
• 目录结构
• 常见问题

---

1. 功能说明

概述

本文档详细介绍 Niucloud Admin 后台管理端的系统架构和目录结构。

适用场景

• Admin 端开发
• 后台功能定制
• 新功能模块开发

---

2. 设计思路

技术栈

• 框架：Vue 3 + TypeScript
• 构建工具：Vite
• UI 组件库：Element Plus
• 状态管理：Pinia
• 路由：Vue Router 4
• HTTP 客户端：Axios

架构特点

• 组件化开发
• 模块化路由
• 统一的状态管理
• 完善的权限控制

---

3. 系统架构

3.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                        用户界面                              │
│              Vue Components + Element Plus                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                      路由层 (Vue Router)                     │
│              页面导航、路由守卫、权限控制                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     状态管理 (Pinia)                         │
│         用户状态、应用配置、权限数据、缓存数据                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     API 请求层 (Axios)                       │
│              请求拦截、响应处理、错误处理                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     后端 API 接口                            │
└─────────────────────────────────────────────────────────────┘

3.2 数据流向

用户操作 → 组件事件 → Pinia Action → API 请求 → 后端处理
                                              ↓
UI 更新 ← 组件渲染 ← 状态更新 ← API 响应 ← 数据处理

---

4. 目录结构

4.1 整体目录

admin/                          # Admin 前端项目
├── public/                     # 静态资源
│   └── favicon.ico
├── src/
│   ├── api/                    # API 接口定义
│   ├── assets/                 # 静态资源
│   ├── components/             # 公共组件
│   ├── dict/                   # 数据字典
│   ├── layouts/                # 布局组件
│   ├── router/                 # 路由配置
│   ├── stores/                 # Pinia 状态管理
│   ├── styles/                 # 样式文件
│   ├── utils/                  # 工具函数
│   ├── views/                  # 页面视图
│   ├── App.vue                 # 根组件
│   ├── main.ts                 # 入口文件
│   └── env.d.ts                # 类型声明
├── index.html                  # HTML 模板
├── package.json                # 依赖配置
├── tsconfig.json               # TypeScript 配置
├── vite.config.ts              # Vite 配置
└── ...

4.2 API 目录 (src/api/)

src/api/
├── sys/                        # 系统管理接口
│   ├── config.ts              # 系统配置
│   ├── user.ts                # 管理员管理
│   └── role.ts                # 角色权限
├── member/                     # 会员管理接口
│   ├── member.ts              # 会员列表
│   └── level.ts               # 会员等级
├── app/                        # 应用管理接口
└── index.ts                    # API 统一导出

4.3 组件目录 (src/components/)

src/components/
├── common/                     # 通用组件
│   ├── table/                 # 表格组件
│   ├── form/                  # 表单组件
│   └── search/                # 搜索组件
├── business/                   # 业务组件
│   ├── upload/                # 上传组件
│   ├── editor/                # 编辑器组件
│   └── selector/              # 选择器组件
└── index.ts                    # 组件统一导出

4.4 视图目录 (src/views/)

src/views/
├── sys/                        # 系统管理
│   ├── config/                # 系统配置
│   ├── user/                  # 管理员管理
│   └── role/                  # 角色权限
├── member/                     # 会员管理
│   ├── list.vue               # 会员列表
│   └── detail.vue             # 会员详情
├── login.vue                   # 登录页
├── error/                      # 错误页面
│   ├── 404.vue
│   └── 403.vue
└── ...

4.5 路由目录 (src/router/)

src/router/
├── index.ts                    # 路由入口
├── routes.ts                   # 路由配置
├── guards.ts                   # 路由守卫
└── modules/                    # 路由模块
    ├── sys.ts                 # 系统管理路由
    ├── member.ts              # 会员管理路由
    └── ...

4.6 状态管理 (src/stores/)

src/stores/
├── index.ts                    # Store 入口
├── modules/
│   ├── user.ts                # 用户状态
│   ├── app.ts                 # 应用配置
│   ├── permission.ts          # 权限状态
│   └── tags.ts                # 标签页状态
└── types/                      # 类型定义

4.7 工具目录 (src/utils/)

src/utils/
├── request.ts                  # Axios 封装
├── auth.ts                     # 认证工具
├── storage.ts                  # 存储工具
├── validate.ts                 # 验证工具
├── format.ts                   # 格式化工具
└── index.ts                    # 工具统一导出

---

5. 常见问题

Q1: 如何添加新页面

步骤：

1. 在 src/views/ 下创建页面组件
2. 在 src/router/modules/ 添加路由配置
3. 在 src/api/ 添加对应的 API 接口

// 1. 创建页面 src/views/demo/list.vue
<template>
  <div class="demo-list">
    <el-table :data="list">
      <!-- 表格内容 -->
    </el-table>
  </div>
</template>

// 2. 添加路由 src/router/modules/demo.ts
const routes = [
  {
    path: '/demo',
    component: Layout,
    children: [
      {
        path: 'list',
        component: () => import('@/views/demo/list.vue'),
        meta: { title: '示例列表' }
      }
    ]
  }
];

Q2: 如何使用状态管理

// 定义 Store
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({
    info: null,
    token: ''
  }),
  actions: {
    setUser(info) {
      this.info = info;
    }
  }
});

// 在组件中使用
import { useUserStore } from '@/stores';

const userStore = useUserStore();
userStore.setUser(userInfo);

Q3: 如何封装 API 请求

// src/api/sys/config.ts
import request from '@/utils/request';

export function getConfig() {
  return request.get('/adminapi/sys/config');
}

export function setConfig(data: any) {
  return request.post('/adminapi/sys/config', data);
}

---

修订记录

版本	日期	修订人	修订内容
v1.0	2026-04-08	Niucloud Team	初始版本