vitepress-template

Appearance

ui-web-admin 管理后台 ​

**本文引用的文件** - [[[[[package.json]]]]](../file/ui-web-admin/package.json) - [[[[[next.config.ts]]]]](../file/ui-web-admin/next.config.ts) - [[[[[src/config/env.ts]]]]](../file/ui-web-admin/src/config/env.ts) - [[[[[src/lib/request.ts]]]]](../file/ui-web-admin/src/lib/request.ts) - [[[[[src/lib/api.ts]]]]](../file/ui-web-admin/src/lib/api.ts) - [[[[[src/app/layout.tsx]]]]](../file/ui-web-admin/src/app/layout.tsx) - [[[[[src/app/(dashboard)/layout.tsx]]]]](../file/ui-web-admin/src/app/dashboard)/layout.tsx) - [[[[[src/app/login/page.tsx]]]]](../file/ui-web-admin/src/app/login/page.tsx) - [[[[[src/app/(dashboard)/system/users/page.tsx]]]]](../file/ui-web-admin/src/app/dashboard)/system/users/page.tsx) - [[[[[src/app/(dashboard)/system/menus/page.tsx]]]]](../file/ui-web-admin/src/app/dashboard)/system/menus/page.tsx) - [[[[[src/app/(dashboard)/tenants/page.tsx]]]]](../file/ui-web-admin/src/app/dashboard)/tenants/page.tsx) - [[[[[src/components/ArcoCompat.tsx]]]]](../file/ui-web-admin/src/components/arcocompat.tsx) - [[[[[docs/architecture-ui-web-admin.md]]]]](../file/ui-web-admin/docs/architecture-ui-web-admin.md)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

ui-web-admin 是一个基于 Next.js 的管理后台前端应用，面向系统运营人员，提供租户管理、系统配置、用户权限、菜单与字典管理、操作日志审计以及内容管理（CMS）等功能。系统采用 Arco Design React 作为 UI 组件库，统一交互风格；通过网关或直连模式对接 bi-sys、bi-tenant、bi-auth 等后端服务，支持多环境部署与主题切换。

项目结构 ​

ui-web-admin 采用 Next.js App Router 结构，核心目录组织如下：

  • src/app: 页面与布局，包含登录页、仪表盘布局与各功能页面
  • src/lib: 请求封装与 API 封装层
  • src/config: 环境变量与运行时配置
  • src/components: 可复用组件（如 Arco 兼容层）
  • public: 静态资源（图标字体等）
  • docs: 文档资料

图表来源

章节来源

核心组件 ​

  • 布局与导航
    • 根布局负责主题注入与全局样式加载，侧边栏布局提供菜单导航、用户信息与主题切换。
  • 登录认证
    • 登录页提供表单校验与加密提交，成功后写入本地 token 并跳转仪表盘。
  • 请求与 API
    • request.ts 封装 fetch、统一鉴权头、错误提示与响应解析；api.ts 对接各业务模块接口。
  • 环境配置
    • env.ts 定义多环境配置与网关路由映射，next.config.ts 基于环境进行 rewrites。
  • UI 兼容
    • ArcoCompat 初始化 Arco Design 在 React 19 下的兼容行为。

章节来源

架构总览 ​

ui-web-admin 通过 Next.js 的 rewrites 将前端请求代理至后端服务，支持两种模式：

  • 网关模式：所有 /api/v1/* 请求转发到统一网关，再由网关路由到具体服务（sys、tenant）。
  • 直连模式：开发环境下直接转发到各服务地址（如 /api/v1/sys、/api/v1/tenant-m、/api/v1/auth）。

图表来源

章节来源

详细组件分析 ​

登录与认证流程 ​

  • 登录页收集用户名与密码，调用 authApi.login，成功后将 access_token 写入 localStorage，并跳转到仪表盘。
  • 请求层在发起请求时自动附加 Authorization: Bearer token；当收到 401 时清理 token 并跳转登录页。

图表来源

章节来源

用户管理界面 ​

  • 功能点
    • 列表分页、搜索（用户名/昵称）、状态开关、新增/编辑/删除、重置密码。
    • 表单包含部门选择、角色多选、手机号/邮箱、状态等字段。
  • 交互与校验
    • 新增时必填密码，编辑时可选修改密码；确认密码与密码一致性校验。
    • 状态切换通过 PUT /users/{id}/status 更新。
  • 批量操作
    • 当前页面未实现“全选”批量勾选，但支持逐条启停与删除。

图表来源

章节来源

菜单管理界面 ​

  • 功能点
    • 支持树形菜单展示、展开/折叠、新增/编辑/删除子级菜单。
    • 菜单类型区分：目录、菜单、按钮；不同类型显示不同的表单项。
    • 支持按名称/状态筛选。
  • 数据结构
    • 列表与树互转：listToTree 将扁平列表转换为树形结构；默认树视图展开所有节点。
  • 交互细节
    • 上级菜单使用 TreeSelect，父级为 '0' 表示根目录。
    • 菜单类型变化时动态渲染对应表单项。

图表来源

章节来源

租户管理界面 ​

  • 功能点
    • 列表支持按租户编码/名称/状态筛选；支持启用/停用、删除、编辑。
    • 新增租户时需填写联系人、电话、套餐、到期时间与初始密码。
    • 分页与横向滚动适配宽表。
  • 业务逻辑
    • 状态切换通过 PUT /tenants/{id}/status 实现。
    • 到期时间使用日期选择器并格式化为字符串。

图表来源

章节来源

权限控制与安全机制 ​

  • 登录态
    • 登录成功写入 token；后续请求自动附加 Authorization 头。
    • 401 自动清空 token 并跳转登录页。
  • 主题与本地存储
    • arco-theme 与用户信息缓存于 localStorage，确保刷新后状态一致。
  • 表单校验
    • 用户管理中的密码一致性校验、必填项校验；菜单管理根据类型动态渲染字段。

章节来源

组件库使用与界面设计规范 ​

  • 组件库
    • 使用 @arco-design/web-react，统一风格与交互。
  • 设计规范
    • 使用 ArcoCompat 确保 React 19 兼容；全局样式与图标字体在根布局引入。
    • 侧边栏菜单与头部工具条提供一致的操作入口与反馈。

章节来源

依赖关系分析 ​

  • 环境与路由
    • env.ts 定义环境配置与 API 路由映射；next.config.ts 基于环境决定 rewrite 目标。
  • 请求与 API
    • request.ts 提供统一 fetch 封装；api.ts 将业务模块与后端接口解耦。
  • 页面与布局
    • 仪表盘布局负责菜单、用户信息与主题切换；登录页负责认证流程。

图表来源

章节来源

性能考量 ​

  • 传输与解析
    • 使用 JSONBig 解析大整数，避免精度丢失。
  • 网络代理
    • 通过 Next.js rewrites 减少跨域与代理复杂度；网关模式便于集中治理。
  • UI 渲染
    • 表格列宽固定与横向滚动，减少重排；树形菜单默认展开关键节点以提升可读性。

章节来源

故障排查指南 ​

  • 登录失败/频繁跳转登录
    • 检查本地 token 是否存在；确认后端返回的 access_token 正确写入。
    • 查看请求头 Authorization 是否携带 Bearer token。
  • 接口 401
    • request.ts 已处理 401 清理 token 并跳转登录；检查后端 JWT 签发与过期策略。
  • 网关/直连异常
    • 确认 NEXT_PUBLIC_APP_ENV 与 env.ts 中的配置一致；核对 next.config.ts 的 rewrite 目标。
  • 表单校验失败
    • 用户管理中的密码一致性校验、必填项提示；菜单管理根据类型动态显示字段。

章节来源

结论 ​

ui-web-admin 以 Next.js 为基础，结合 Arco Design React 提供了统一、可扩展的管理后台体验。通过清晰的布局与模块化页面，覆盖系统配置、租户管理、用户权限与日志审计等核心能力；借助 env 与 rewrites 的灵活配置，满足多环境与网关直连的部署需求。建议在后续迭代中补充用户管理的批量操作能力与更细粒度的权限控制策略。

附录 ​

  • 最佳实践
    • 使用统一的请求封装与 API 层，便于替换与测试。
    • 页面内尽量使用受控组件与表单校验，减少副作用。
    • 对长列表与树形结构启用必要的虚拟化/懒加载策略（如后续扩展）。
  • 用户体验优化
    • 保持一致的主题与交互反馈；对关键操作提供二次确认。
    • 表单字段按类型动态渲染，减少无效输入。
  • 开发指南
    • 通过脚本设置 NEXT_PUBLIC_APP_ENV 选择环境；开发时优先使用直连模式，联调时切换网关模式。
    • 新增页面遵循现有目录与命名约定，复用 api.ts 的接口定义。

章节来源