Merge branch 'main' of ssh://git.dev.vifo.cc:222/rui/rui-docs

2026-06-04 09:30:21 +08:00
parent 87b7780dd6 0666c3ec7b
commit 2e38c53434
9 changed files with 2340 additions and 2 deletions
@@ -0,0 +1,129 @@
+# Admin-UI 图标体系说明文档
+
+> 本文档记录 admin-ui 图标配置、映射规则及相关注意事项，避免每次重复分析代码。
+
+---
+
+## 一、图标体系概览
+
+admin-ui 支持 **两类图标**，由 `RuiIcon.vue` 组件统一处理：
+
+| 类型 | 格式示例 | 来源 | 渲染方式 |
+|------|---------|------|---------|
+| **Element Plus 图标** | `Setting`、`UserFilled`、`HomeFilled` | `@element-plus/icons-vue` | `<el-icon>` |
+| **Tabler 图标（Iconify）** | `tabler:settings`、`tabler:users` | `@iconify/vue` | `<Icon :icon="..." />` |
+
+**判断规则**（`RuiIcon.vue`）：
+- 如果字符串包含 `:` → 使用 Iconify 渲染（Tabler 图标）
+- 否则 → 使用 Element Plus 图标组件渲染
+
+---
+
+## 二、图标选择器
+
+**文件位置**：`admin-ui/src/components/IconPicker.vue`
+
+**支持四类图标**：
+1. **Element Plus** - 动态读取 `@element-plus/icons-vue` 全部图标
+2. **Tabler** - 硬编码 102 个常用图标，以 `tabler:` 为前缀
+3. **SVG** - 内联 SVG 代码
+4. **图片/URL** - 粘贴图片 URL
+
+**推荐使用 Tabler 图标**（`tabler:` 前缀），与后端菜单存储格式保持一致。
+
+---
+
+## 三、后端菜单图标存储格式
+
+**当前标准**：所有菜单图标统一使用 `tabler:` 前缀格式
+
+**示例**：
+```
+tabler:settings       → 系统管理
+tabler:users          → 用户管理
+tabler:menu-2         → 菜单管理
+tabler:user-shield    → 角色管理
+tabler:building       → 部门管理
+tabler:book           → 字典管理
+tabler:id             → 岗位管理
+tabler:gift           → 租户套餐
+tabler:shield-check   → 数据权限
+tabler:award          → 用户等级
+tabler:history        → 等级日志
+tabler:device-desktop → 演示中心
+tabler:palette        → 图标演示
+tabler:list           → 列表演示
+```
+
+**历史变更**：
+- 早期使用 Element Plus 图标组件名（如 `SettingOutlined`）
+- 已执行升级脚本 `docs/sql/update_menu_icon.sql` 统一改为 `tabler:` 格式
+
+---
+
+## 四、前端图标映射规则
+
+**文件位置**：`admin-ui/src/composables/useMenu.ts`
+
+`getIconName()` 函数处理逻辑：
+1. 如果 `icon` 字段以 `tabler:` 开头 → **直接透传返回**
+2. 否则 → 按原有映射规则转换为 Element Plus 图标名
+
+**注意**：
+- 后端返回的 `icon` 字段应始终使用 `tabler:` 格式
+- 前端布局文件（SideLayout/TopNavLayout/DoubleLayout）已改为使用 `RuiIcon` 组件渲染菜单图标，支持 `tabler:` 格式
+
+---
+
+## 五、布局文件中的图标渲染
+
+**修改后的渲染方式**（统一使用 `RuiIcon`）：
+
+```vue
+<!-- SideLayout.vue / TopNavLayout.vue -->
+<template #title>
+  <RuiIcon v-if="item.icon" :icon="item.icon" :size="16" class="menu-icon" />
+  <span>{{ item.title }}</span>
+</template>
+
+<!-- DoubleLayout.vue（图标栏） -->
+<div class="icon-btn">
+  <RuiIcon :icon="item.icon" :size="20" />
+</div>
+```
+
+**样式适配**（确保图标颜色与菜单主题一致）：
+```css
+.menu-icon {
+  margin-right: 5px;
+  color: inherit;
+}
+```
+
+---
+
+## 六、新增功能时的图标规范
+
+1. **优先使用 Tabler 图标**（`tabler:` 前缀）
+2. **在 IconPicker 中添加**：如果 IconPicker 的 Tabler 列表中没有需要的图标，添加到 `IconPicker.vue` 的 `tablerIcons` 数组
+3. **后端菜单配置**：在 `config/menus/*.json` 中配置图标时，使用 `tabler:xxx` 格式
+4. **前端自动适配**：无需修改前端代码，`RuiIcon` 组件会自动识别并渲染
+
+---
+
+## 七、常见问题
+
+### Q: 为什么菜单图标显示不出来？
+A: 检查后端返回的 `icon` 字段格式：
+- 正确：`tabler:settings`
+- 错误：`settings`、`Setting`、`tabler-settings`
+
+### Q: 如何查看所有可用的 Tabler 图标？
+A: 在菜单管理页面点击图标选择器，切换到 "Tabler" 标签页查看。
+
+### Q: 能否使用 Element Plus 图标？
+A: 可以，但不推荐。如果必须使用，直接写图标组件名（如 `Setting`），不要加 `tabler:` 前缀。
+
+---
+
+> **维护提示**：本文档位于 `/docs/admin-ui-icon-guide.md`，修改图标体系时必须同步更新。
@@ -0,0 +1,206 @@
+# Admin-UI 功能状态跟踪文档
+
+> 本文档用于记录 admin-ui 前端功能实现状态，避免每次重复分析。
+> **规则**：每次修改 admin-ui 功能后，必须同步更新此文档。
+
+---
+
+## 一、项目概览
+
+- **技术栈**: Vue 3 + Element Plus + Pinia + Vue Router + Axios
+- **构建工具**: Vite + TypeScript + UnoCSS
+- **布局类型**: 侧边栏 / 顶栏 / 混合 / 双栏（4种布局支持）
+- **国际化**: 支持 zh-CN / en-US
+
+---
+
+## 二、功能模块清单
+
+### 1. 系统框架功能
+
+| 功能 | 状态 | 说明 |
+|------|------|------|
+| 登录页 | ✅ 完成 | 支持账号密码登录、记住密码 |
+| 布局切换 | ✅ 完成 | 4种布局（侧边栏/顶栏/混合/双栏）|
+| 主题配置 | ✅ 完成 | 暗黑/明亮模式、主题色、字号 |
+| 多标签页 | ✅ 完成 | TagsBar 支持右键菜单（关闭/刷新/全屏/关闭其他/关闭所有）|
+| 个人中心 | ✅ 完成 | 个人信息修改、密码修改 |
+| 全屏功能 | ✅ 完成 | 支持页面全屏 |
+| 国际化 | ✅ 完成 | 中文/英文切换 |
+| 路由守卫 | ✅ 完成 | 未登录自动跳转、已登录禁止访问登录页 |
+
+### 2. 用户管理模块
+
+| 功能 | 页面 | 状态 | 说明 |
+|------|------|------|------|
+| 用户信息 | user/info/Index.vue | ✅ 完成 | 增删改查、批量删除、状态切换、导出、角色分配、详情查看 |
+| 用户详情 | user/detail/Index.vue | ✅ 完成 | 增删改查、批量删除、导出 |
+| 等级管理 | user/level/Index.vue | ✅ 完成 | 增删改查、批量删除、状态切换、导出 |
+| 等级日志 | user/level-log/Index.vue | ✅ 完成 | 增删改查、批量删除、状态切换、导出 |
+| 收货地址 | user/address/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+| 账户流水 | user/account/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+
+**缺失功能**:
+- ❌ **用户管理页面缺少导入功能**（后端 `/user/admin/user/import` 已提供）
+- ❌ **缺少用户详情管理页面**（后端 `/user/admin/detail/**` 已提供）
+
+### 3. 系统管理模块
+
+| 功能 | 页面 | 状态 | 说明 |
+|------|------|------|------|
+| 菜单管理 | system/menu/Index.vue | ✅ 完成 | 树形展示、图标选择、平台切换、修复图标 |
+| 角色管理 | system/role/Index.vue | ✅ 完成 | 增删改查、菜单权限分配、状态切换、导出 |
+| 部门管理 | system/dept/Index.vue | ✅ 完成 | 树形展示、增删改查、状态切换 |
+| 字典管理 | system/dict/Index.vue | ✅ 完成 | 字典项管理、增删改查、状态切换、导出 |
+| 参数配置 | system/config/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+| 操作日志 | system/log/Index.vue | ✅ 完成 | 查看详情、清空日志、删除、导出 |
+| 登录日志 | system/login-log/Index.vue | ✅ 完成 | 清空日志、删除、导出 |
+| 租户管理 | system/tenant/Index.vue | ✅ 完成 | 初始化租户、修改密码、模块编辑、增删改查、导出 |
+| OAuth2客户端 | system/oauth2-client/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+
+**缺失功能**:
+- ❌ **部门管理页面缺少导出功能**（后端 `/system/admin/dept/export` 已提供）
+- ❌ **菜单管理页面缺少导出功能**（后端 `/system/admin/menu/export` 已提供）
+
+### 4. 订单管理模块
+
+| 功能 | 页面 | 状态 | 说明 |
+|------|------|------|------|
+| 订单列表 | order/list/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+| 退款记录 | order/refund/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+
+### 5. 内容管理模块 (CMS)
+
+| 功能 | 页面 | 状态 | 说明 |
+|------|------|------|------|
+| 文章管理 | cms/article/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+| 分类管理 | cms/category/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+| 轮播图 | cms/banner/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+
+### 6. 营销中心模块
+
+| 功能 | 页面 | 状态 | 说明 |
+|------|------|------|------|
+| 优惠券 | marketing/coupon/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+| 活动管理 | marketing/activity/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 |
+
+### 7. 演示模块
+
+| 功能 | 页面 | 状态 | 说明 |
+|------|------|------|------|
+| 图标演示 | demo/Icons.vue | ✅ 完成 | Tabler 图标库展示 |
+| 列表演示 | demo/list/Index.vue | ✅ 完成 | 标准 CRUD 示例 |
+
+---
+
+## 三、前后端 API 对照表
+
+### 已对接的后端 API
+
+| 后端 Controller | 前端 Service | 对接状态 |
+|----------------|-------------|---------|
+| UserController | userService.ts | ✅ 已对接（缺少 import） |
+| UserDetailController | ❌ 无 | ❌ 未对接 |
+| UserLevelController | levelService.ts | ✅ 已对接 |
+| UserLevelLogController | levelLogService.ts | ✅ 已对接 |
+| SysMenuController | menuService.ts | ✅ 已对接 |
+| SysRoleController | roleService.ts | ✅ 已对接 |
+| SysDeptController | deptService.ts | ✅ 已对接 |
+| SysDictTypeController | dictService.ts | ✅ 已对接 |
+| SysDictItemController | dictItemService.ts | ✅ 已对接 |
+| SysConfigController | configService.ts | ✅ 已对接 |
+| SysOperLogController | operLogService.ts | ✅ 已对接 |
+| SysLoginLogController | loginLogService.ts | ✅ 已对接 |
+| SysTenantController | tenantService.ts | ✅ 已对接 |
+| SystemOAuth2ClientController | oauth2ClientService.ts | ✅ 已对接 |
+
+### 后端有但前端未对接的 API
+
+| 后端接口 | 说明 | 优先级 |
+|---------|------|--------|
+| `GET/POST /user/admin/user/import` | 用户导入 | 低 |
+| `GET /system/admin/dept/export` | 部门导出 | 低 |
+| `GET /system/admin/menu/export` | 菜单导出 | 低 |
+| `POST /system/admin/menu/fix-icons` | 修复菜单图标 | 中（已在前端调用） |
+| `POST /system/admin/tenant/{tenantId}/init` | 初始化租户 | 已对接 |
+| `POST /system/admin/tenant/{tenantId}/admin/password` | 修改租户管理员密码 | 已对接 |
+| `GET /user/admin/detail/**` | 用户详情管理 | **高**（完整页面缺失） |
+
+---
+
+## 四、待办事项 (TODO)
+
+### 高优先级
+- [x] **用户详情管理页面** - ✅ 已完成
+
+### 中优先级
+- [ ] **订单管理功能完善** - 检查订单列表和退款记录页面功能完整性
+- [ ] **CMS 功能完善** - 检查文章、分类、轮播图页面功能完整性
+- [ ] **营销中心功能完善** - 检查优惠券、活动管理页面功能完整性
+- [ ] **用户地址、账户流水页面** - 确认功能是否完整
+
+### 低优先级
+- [ ] **导入导出功能补全** - 用户管理导入、部门管理导出、菜单管理导出
+- [ ] **参数配置页面** - 确认功能完整性
+- [ ] **OAuth2客户端页面** - 确认功能完整性
+
+---
+
+## 五、更新记录
+
+| 日期 | 更新内容 | 更新人 |
+|------|---------|--------|
+| 2025-06-01 | 初始版本，完成系统框架、用户管理、系统管理模块的详细分析 | AI Assistant |
+| 2025-06-01 | 新增用户详情管理页面（Index.vue + UserDetailFormDialog.vue），完善路由、国际化、Service 导出 | AI Assistant |
+| 2025-06-01 | 菜单配置改为 config/menus/ 目录按模块拆分；增加模块管理功能（Nacos配置 + 后端API + 前端模块编辑） | AI Assistant |
+
+---
+
+## 六、使用说明
+
+### 维护规范
+
+1. **新增功能时**：在对应模块表格中添加一行，标记状态
+2. **修改功能时**：更新对应行的状态和说明
+3. **发现问题时**：添加到「待办事项」章节
+4. **完成事项时**：将 TODO 项标记为完成，并记录到「更新记录」
+
+### 提示词模板（复制即用）
+
+#### 场景 1：查看 admin-ui 当前功能状态
+```
+请读取 docs/admin-ui-status.md 文档，告诉我 admin-ui 当前的功能完成情况和还有哪些待办事项。
+```
+
+#### 场景 2：基于文档开发新功能
+```
+请读取 docs/admin-ui-status.md 文档，根据「待办事项」中的高优先级任务，帮我实现【具体功能名称】。
+实现完成后，记得同步更新 docs/admin-ui-status.md 文档中的状态。
+```
+
+#### 场景 3：检查某个模块是否完整
+```
+请读取 docs/admin-ui-status.md 文档，检查【模块名称】模块的功能是否完整，还有哪些缺失？
+```
+
+#### 场景 4：完成修改后更新文档
+```
+我已经完成了【修改内容】，请更新 docs/admin-ui-status.md 文档：
+1. 将对应功能状态标记为完成
+2. 如完成待办事项，将其标记为 [x]
+3. 在「更新记录」中添加一行
+```
+
+#### 场景 5：对比前后端接口
+```
+请读取 docs/admin-ui-status.md 文档，检查「前后端 API 对照表」，告诉我还有哪些后端接口前端未对接。
+```
+
+#### 场景 6：新对话快速上手
+```
+请读取 docs/admin-ui-status.md 文档，快速了解 admin-ui 项目现状，无需分析整个项目。
+```
+
+---
+
+> **提示**：本文档位于 `/docs/admin-ui-status.md`，请确保与代码同步更新。