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)

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