|
|
# VBase 前端界面设计文档
|
|
|
|
|
|
本文档基于 `vigo`/`vhtml` 框架，根据后端设计 (`docs/design.md`) 规划前端界面架构与组件设计。
|
|
|
|
|
|
## 1. 目录结构规范
|
|
|
|
|
|
遵循 `vhtml` 框架约定，建议采用以下目录结构：
|
|
|
|
|
|
```
|
|
|
/ui/
|
|
|
├── assets/ # 静态资源
|
|
|
│ ├── global.css # 全局样式 (Color vars, Reset)
|
|
|
│ └── ...
|
|
|
├── c/ # 业务特定组件 (尽量复用 vhtml-ui，仅存放业务强相关组件)
|
|
|
├── layout/ # 页面布局及局部组件
|
|
|
│ ├── default.html # 后台管理布局 (Sidebar + Header)
|
|
|
│ ├── public.html # 公共布局 (Login/Register, Center aligned)
|
|
|
│ ├── header.html # <layout-header>
|
|
|
│ └── sidebar.html # <layout-sidebar>
|
|
|
├── page/ # 页面路由组件
|
|
|
│ ├── auth/ # 认证模块
|
|
|
│ │ ├── login.html
|
|
|
│ │ └── register.html
|
|
|
│ ├── dashboard/ # 仪表盘
|
|
|
│ │ └── index.html
|
|
|
│ ├── sys/ # 系统管理 (User, Org, OAuth)
|
|
|
│ │ ├── user/
|
|
|
│ │ │ ├── index.html # 用户列表
|
|
|
│ │ │ └── form.html # 用户创建/编辑
|
|
|
│ │ ├── org/
|
|
|
│ │ │ ├── index.html # 组织列表
|
|
|
│ │ │ └── detail.html # 组织详情/设置
|
|
|
│ │ └── oauth/
|
|
|
│ │ ├── index.html # 应用列表
|
|
|
│ │ └── form.html # 应用注册
|
|
|
│ ├── user/ # 个人中心
|
|
|
│ │ └── profile.html
|
|
|
│ ├── 404.html
|
|
|
│ └── 403.html
|
|
|
├── env.js # 全局环境配置 (Axios, Router guard)
|
|
|
├── routes.js # 路由定义
|
|
|
└── root.html # 根入口
|
|
|
```
|
|
|
|
|
|
## 2. 布局设计 (Layouts)
|
|
|
|
|
|
### 2.1 Public Layout (`layout/public.html`)
|
|
|
- **用途**: 登录、注册、404、403 等无需鉴权的页面。
|
|
|
- **结构**: 居中容器，背景简约，包含 Logo 和主体内容插槽。
|
|
|
|
|
|
### 2.2 Default Layout (`layout/default.html`)
|
|
|
- **用途**: 系统核心业务页面。
|
|
|
- **结构**:
|
|
|
- **Sidebar (Left)**: 导航菜单 (Dashboard, User, Org, OAuth, Settings)。支持折叠。
|
|
|
- **Header (Top)**: 面包屑导航, 组织切换器 (Org Switcher), 用户头像/下拉菜单 (Profile, Logout)。
|
|
|
- **Main Content**: 路由视图插槽 (`<router-view>`)。
|
|
|
- **特性**: 需集成 `OrgID` 切换逻辑，切换组织时更新全局状态并刷新数据。
|
|
|
|
|
|
## 3. 核心模块界面规划与权限
|
|
|
|
|
|
### 3.1 认证模块 (Auth)
|
|
|
- **权限**: 公开访问 (Guest)
|
|
|
- **登录页 (`/login`)**: 用户名/邮箱 + 密码。集成 OAuth2 第三方登录按钮。
|
|
|
- **注册页 (`/register`)**: 基本信息填写。
|
|
|
|
|
|
### 3.2 仪表盘 (Dashboard)
|
|
|
- **权限**: 登录用户 (Authenticated)
|
|
|
- **概览页 (`/`)**: 展示核心指标。
|
|
|
- **普通用户**: 仅可见个人或所属项目的数据概览。
|
|
|
- **管理员**: 可见整个组织或系统的宏观数据。
|
|
|
|
|
|
### 3.3 组织管理 (Org Module)
|
|
|
- **组织列表 (`/org`)**:
|
|
|
- **权限**: 登录用户 (Authenticated)
|
|
|
- 展示用户加入的所有组织。
|
|
|
- “创建组织”入口：视系统配置开放给所有用户或仅限特定用户。
|
|
|
- **组织详情/设置 (`/org/:id`)**:
|
|
|
- **权限**: 组织成员 (Member of Org)
|
|
|
- **基本信息**: 仅 **Org Admin** 可修改名称、Logo。
|
|
|
- **成员管理**: 仅 **Org Admin** 可邀请、移除成员或修改角色。
|
|
|
- **只读视图**: 普通成员仅可查看组织信息和成员列表。
|
|
|
|
|
|
### 3.4 用户管理 (User Module)
|
|
|
- **用户列表 (`/sys/user`)**:
|
|
|
- **权限**: 系统管理员 (System Admin Only)
|
|
|
- 全局用户管理表格，包含搜索、分页、禁用/启用用户功能。
|
|
|
- **个人资料 (`/profile`)**:
|
|
|
- **权限**: 登录用户 (Authenticated)
|
|
|
- 基本信息修改 (头像, 昵称)、账号安全 (修改密码, 绑定第三方账号)。
|
|
|
|
|
|
### 3.5 OAuth2 Provider (OAuth Module)
|
|
|
- **应用管理 (`/sys/oauth`)**:
|
|
|
- **权限**: 登录用户 (Authenticated)
|
|
|
- 开发者注册的 OAuth 应用列表。
|
|
|
- **创建/编辑应用**: 用户仅可管理自己创建的应用。
|
|
|
- **系统级应用**: 仅 **System Admin** 可见或管理系统预置应用。
|
|
|
|
|
|
## 4. 组件策略
|
|
|
|
|
|
### 4.1 基础组件库
|
|
|
本项目直接使用 **vhtml-ui** 组件库，无需重复封装基础组件。
|
|
|
- 按钮、输入框、卡片、模态框、表格等均直接使用库组件。
|
|
|
- 组件文档：`http://localhost:4000/v/README.md`
|
|
|
|
|
|
### 4.2 业务组件
|
|
|
- 仅当组件包含特定业务逻辑且多处复用时，封装为自定义组件。
|
|
|
- 命名规范：使用短前缀（如 `c-` 或直接目录名）。
|
|
|
- 存放位置：
|
|
|
- 全局复用：`/ui/c/`
|
|
|
- 局部复用：直接存放在调用方同级目录或 `_components` 子目录中。
|
|
|
|
|
|
## 5. 路由规划 (`routes.js`)
|
|
|
|
|
|
```javascript
|
|
|
const routes = [
|
|
|
// Public
|
|
|
{ path: '/login', component: '/page/auth/login.html', layout: 'public', meta: { guest: true } },
|
|
|
{ path: '/register', component: '/page/auth/register.html', layout: 'public', meta: { guest: true } },
|
|
|
|
|
|
// Dashboard (Default Layout)
|
|
|
{
|
|
|
path: '/',
|
|
|
layout: 'default',
|
|
|
meta: { auth: true }, // 登录用户均可访问
|
|
|
component: '/page/dashboard/index.html'
|
|
|
},
|
|
|
|
|
|
// Org Management
|
|
|
{ path: '/org', component: '/page/sys/org/index.html', layout: 'default', meta: { auth: true } },
|
|
|
{
|
|
|
path: '/org/:id',
|
|
|
component: '/page/sys/org/detail.html',
|
|
|
layout: 'default',
|
|
|
meta: { auth: true } // 页面内部需校验是否为成员
|
|
|
},
|
|
|
|
|
|
// User System
|
|
|
{ path: '/profile', component: '/page/user/profile.html', layout: 'default', meta: { auth: true } },
|
|
|
{
|
|
|
path: '/users',
|
|
|
component: '/page/sys/user/index.html',
|
|
|
layout: 'default',
|
|
|
meta: { auth: true, roles: ['admin'] } // 仅系统管理员
|
|
|
},
|
|
|
|
|
|
// OAuth Management
|
|
|
{ path: '/oauth/apps', component: '/page/sys/oauth/index.html', layout: 'default', meta: { auth: true } },
|
|
|
|
|
|
// Errors
|
|
|
{ path: '/403', component: '/page/403.html', layout: 'public' },
|
|
|
{ path: '*', component: '/page/404.html', layout: 'public' }
|
|
|
]
|
|
|
```
|
|
|
|
|
|
## 6. 交互与状态管理
|
|
|
|
|
|
- **全局状态 (`$env.$G`)**:
|
|
|
- `user`: 当前登录用户信息。
|
|
|
- `currentOrg`: 当前选中的组织上下文 (影响 Header 显示和 API 请求 Header)。
|
|
|
- `token`: JWT Token 管理。
|
|
|
- **API 请求**:
|
|
|
- 使用 `$axios` 拦截器，自动注入 `Authorization: Bearer ...`。
|
|
|
- 自动注入 `X-Org-ID` (当 `currentOrg` 存在时)。
|
|
|
- **权限控制**:
|
|
|
- 路由守卫 (`beforeEnter`) 检查登录状态和角色。
|
|
|
- 页面内使用 `v-if` 或指令控制按钮级别的权限显示。
|