rui-docs/frontend/design/rui-admin功能设计文档.md

rui-admin 功能设计文档

1. 项目概述

rui-admin 是睿核通用平台框架的后台管理前端系统，基于 Vue 3 + Element Plus + UnoCSS 构建，提供完整的系统管理、用户管理、内容管理、订单管理、营销管理等功能。

2. 功能模块划分

2.1 系统管理（system）- 核心模块

功能	状态	后端API	说明
菜单管理	✅ 已完成	SysMenuController	树形结构、图标修复
角色管理	✅ 已完成	SysRoleController	CRUD + 权限分配
部门管理	✅ 已完成	SysDeptController	树形表格
字典管理	✅ 已完成	SysDictTypeController	字典类型 + 字典项
参数配置	✅ 已完成	SysConfigController	系统参数维护
租户管理	✅ 已完成	SysTenantController	多租户管理
操作日志	⏳ 待开发	需新建	用户操作审计
登录日志	⏳ 待开发	需新建	登录行为记录
OAuth2客户端	⏳ 待开发	SystemOAuth2ClientController	客户端管理前端

2.2 用户中心（user）- 核心模块

功能	状态	后端API	说明
用户管理	✅ 已完成	UserController	用户CRUD
用户等级	✅ 已完成	UserLevelController	等级体系管理
用户详情	⏳ 待开发	UserDetailController	用户详细信息
等级日志	⏳ 待开发	UserLevelLogController	等级变更记录
用户账户	⏳ 待开发	需评估	账户安全设置
用户地址	⏳ 待开发	需新建	收货地址管理

2.3 系统设置（settings）- 基础模块

功能	状态	后端API	说明
个人设置	⏳ 待开发	需评估	个人信息修改
系统设置	⏳ 待开发	SysConfigController	全局参数配置界面
密码修改	⏳ 待开发	UserController	修改登录密码

2.4 订单管理（order）- 业务模块

功能	状态	后端API	说明
订单列表	⏳ 预留	需新建服务	订单查询、状态管理
退款管理	⏳ 预留	需新建服务	退款申请处理

2.5 内容管理（cms）- 业务模块

功能	状态	后端API	说明
文章管理	⏳ 预留	需新建服务	CMS文章CRUD
分类管理	⏳ 预留	需新建服务	文章分类
轮播管理	⏳ 预留	需新建服务	Banner管理

2.6 营销管理（marketing）- 业务模块

功能	状态	后端API	说明
优惠券	⏳ 预留	需新建服务	优惠券CRUD
活动管理	⏳ 预留	需新建服务	营销活动

3. 开发优先级

Phase 1：核心功能完善（立即开始）

1. 操作日志（system/log）

   • 后端：创建 OperLog 实体、Mapper、Service、Controller
   • 前端：日志列表页、详情弹窗
   • 优先级：🔴 高

2. 用户详情（user/info/detail）

   • 后端：UserDetailController 已有，补充前端
   • 前端：用户详情查看/编辑
   • 优先级：🔴 高

3. 等级日志（user/level-log）

   • 后端：UserLevelLogController 已有，补充前端
   • 前端：等级变更记录列表
   • 优先级：🟡 中

4. 系统设置（settings）

   • 后端：复用 SysConfigController
   • 前端：参数配置界面（与 system/config 区别：更友好的展示）
   • 优先级：🟡 中

Phase 2：基础功能补充（近期）

5. 登录日志（system/login-log）

   • 后端：创建 LoginLog 实体、Mapper、Service、Controller
   • 前端：登录记录列表
   • 优先级：🟡 中

6. OAuth2客户端管理（system/client）

   • 后端：SystemOAuth2ClientController 已有
   • 前端：客户端CRUD
   • 优先级：🟡 中

7. 个人中心（profile）

   • 后端：复用现有接口
   • 前端：个人信息展示与修改
   • 优先级：🟢 低

Phase 3：业务模块（按需）

8. 订单管理 - 需新建 rui-service-order 服务
9. CMS内容管理 - 需新建 rui-service-cms 服务
10. 营销管理 - 需新建 rui-service-marketing 服务

4. 技术规范

4.1 前端规范

// 页面结构标准
views/
├── {module}/
│   ├── Index.vue          # 列表页（必须）
│   ├── {Module}FormDialog.vue  # 表单弹窗（新增/编辑）
│   └── {Module}DetailDialog.vue # 详情弹窗（可选）

4.2 后端规范

// Controller 标准结构
@RestController
@RequestMapping("/{模块}/admin/{功能}")
public class XxxController extends BaseController<IService, Entity> {
    // 自动获得：page、list、getById、save、updateById、remove
}

4.3 API 路径规范

类型	路径前缀	示例
对外管理	/{模块}/admin/{功能}	/system/admin/log
内部调用	/{模块}/inner/{功能}	/system/inner/client
对外入口	/{模块}/entry/{功能}	/auth/entry/login

5. 数据库设计（新增表）

5.1 操作日志表（rui_sys_oper_log）

CREATE TABLE rui_sys_oper_log (
    id              BIGINT          NOT NULL,
    tenant_id       BIGINT          NOT NULL DEFAULT 0,
    oper_type       TINYINT         NOT NULL DEFAULT 1 COMMENT '操作类型 1:新增 2:修改 3:删除 4:查询 5:导出 6:登录 7:登出',
    title           VARCHAR(200)    NOT NULL COMMENT '操作模块',
    method          VARCHAR(500)    DEFAULT NULL COMMENT '请求方法',
    request_url     VARCHAR(500)    DEFAULT NULL,
    request_method  VARCHAR(10)     DEFAULT NULL COMMENT 'GET/POST/PUT/DELETE',
    request_params  TEXT            DEFAULT NULL,
    response_data   TEXT            DEFAULT NULL,
    user_id         BIGINT          DEFAULT NULL,
    user_name       VARCHAR(100)    DEFAULT NULL,
    oper_ip         VARCHAR(128)    DEFAULT NULL,
    oper_location   VARCHAR(255)    DEFAULT NULL,
    status          TINYINT         NOT NULL DEFAULT 1 COMMENT '状态 0:失败 1:成功',
    error_msg       TEXT            DEFAULT NULL,
    cost_time       BIGINT          DEFAULT 0 COMMENT '耗时(ms)',
    created_at      DATETIME(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
    PRIMARY KEY (id),
    INDEX idx_user (user_id),
    INDEX idx_tenant (tenant_id),
    INDEX idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='操作日志';

5.2 登录日志表（rui_sys_login_log）

CREATE TABLE rui_sys_login_log (
    id              BIGINT          NOT NULL,
    tenant_id       BIGINT          NOT NULL DEFAULT 0,
    user_id         BIGINT          DEFAULT NULL,
    username        VARCHAR(100)    DEFAULT NULL,
    login_type      TINYINT         NOT NULL DEFAULT 1 COMMENT '登录类型 1:密码 2:短信 3:微信',
    client_id       VARCHAR(100)    DEFAULT NULL,
    ip              VARCHAR(128)    DEFAULT NULL,
    location        VARCHAR(255)    DEFAULT NULL,
    browser         VARCHAR(200)    DEFAULT NULL,
    os              VARCHAR(200)    DEFAULT NULL,
    status          TINYINT         NOT NULL DEFAULT 1 COMMENT '状态 0:失败 1:成功',
    msg             VARCHAR(500)    DEFAULT NULL,
    created_at      DATETIME(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
    PRIMARY KEY (id),
    INDEX idx_user (user_id),
    INDEX idx_tenant (tenant_id),
    INDEX idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='登录日志';

6. 实施计划

第1周：Phase 1 核心功能

• 后端：操作日志 AOP 拦截 + API
• 前端：system/log 页面
• 前端：user/info 详情弹窗
• 前端：user/level-log 页面

第2周：Phase 2 基础功能

• 后端：登录日志 API
• 前端：system/login-log 页面
• 前端：settings 系统设置页
• 前端：profile 个人中心

第3周+：Phase 3 业务模块（按需）

• 订单服务 + 前端页面
• CMS服务 + 前端页面
• 营销服务 + 前端页面

7. 前端组件规划

7.1 复用组件

组件	用途	位置
RuiTable	通用表格	components/RuiTable.vue
RuiIcon	图标渲染	components/RuiIcon.vue
IconPicker	图标选择	components/IconPicker.vue

7.2 新增组件需求

组件	用途	优先级
LogDetailDialog	日志详情展示	🔴 高
UserDetailPanel	用户信息卡片	🔴 高
ConfigGroupPanel	配置分组展示	🟡 中

8. 权限设计

8.1 菜单权限

system:menu:list    - 菜单列表
system:menu:add     - 新增菜单
system:menu:edit    - 编辑菜单
system:menu:remove  - 删除菜单
system:log:list     - 日志列表
system:log:remove   - 删除日志

8.2 数据权限

• 超级管理员：查看所有租户数据
• 租户管理员：仅查看本租户数据
• 普通用户：仅查看个人数据

9. 注意事项

1. 操作日志性能：大量操作日志可能影响性能，建议：

   • 异步写入（MQ或线程池）
   • 定期归档（30天前的日志迁移到历史表）
   • 提供日志清理功能

2. 登录日志安全：

   • 记录失败登录尝试，用于安全审计
   • 支持 IP 黑名单
   • 异常登录告警

3. 预留模块：

   • order/cms/marketing 为业务预留模块
   • 需要时创建对应后端服务
   • 前端页面保持占位状态即可