OneAuth/docs/ui.md

# 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` 或指令控制按钮级别的权限显示。