# 原型说明 - 角色管理

## 1. 页面目标

- **页面用途：** 管理系统内的角色配置，支持角色的增删改查以及菜单权限分配
- **原型范围：** 角色列表页、新增/编辑角色弹窗、菜单权限弹窗

## 2. 页面结构

- **页面标题区：** ArtTableHeader（表头），左侧"新增角色"按钮，支持列配置和刷新
- **筛选区域：** RoleSearch 搜索栏（可折叠），包含角色名称、角色编码、角色描述、角色状态、创建日期区间
- **统计区域：** 无
- **列表区域：** ArtTable 表格，展示角色ID、角色名称、角色编码、角色描述、角色状态、创建日期
- **操作按钮：**
  - 顶部：新增角色
  - 行内：菜单权限、编辑角色、删除角色（ButtonMore 下拉）
- **弹窗/抽屉：**
  - RoleEditDialog：新增/编辑角色（居中弹窗，宽度 30%）
  - RolePermissionDialog：菜单权限配置（居中弹窗，宽度 520px）

## 3. 组件对应

| 区域 | 组件 | 文件 |
|-----|------|------|
| 页面入口 | index.vue | src/views/system/role/index.vue |
| 搜索栏 | RoleSearch | src/views/system/role/modules/role-search.vue |
| 编辑弹窗 | RoleEditDialog | src/views/system/role/modules/role-edit-dialog.vue |
| 权限弹窗 | RolePermissionDialog | src/views/system/role/modules/role-permission-dialog.vue |
| 列表钩子 | useTable | src/hooks/core/useTable.ts |
| 权限树 | ElTree（Element Plus） | 内置 |

## 4. API 接口

| 接口 | 方法 | 路径 | 说明 |
|-----|------|------|------|
| fetchGetRoleList | GET | /api/role/list | 获取角色列表（已实现） |
| fetchAddRole | POST | /api/role/add | 新增角色（待实现） |
| fetchEditRole | PUT | /api/role/edit | 编辑角色（待实现） |
| fetchDeleteRole | DELETE | /api/role/delete | 删除角色（待实现） |
| fetchRolePermissions | GET | /api/role/permissions | 获取角色权限（待实现） |
| fetchSavePermissions | POST | /api/role/permissions | 保存角色权限（待实现） |

## 5. 数据类型

```typescript
interface RoleListItem {
  roleId: number
  roleName: string
  roleCode: string
  description: string
  enabled: boolean
  createTime: string
}

interface RoleSearchParams {
  roleId?: number
  roleName?: string
  roleCode?: string
  description?: string
  enabled?: boolean
  startTime?: string | null
  endTime?: string | null
  current?: number
  size?: number
}
```

## 6. 交互说明

### 查询
- 用户填写搜索条件，点击"查询"按钮
- RoleSearch 触发 `@search` 事件，将 daterange 拆分为 startTime 和 endTime
- 调用 `replaceSearchParams` 更新参数，触发 `getData()` 刷新表格

### 重置
- 点击"重置"按钮，清空表单
- RoleSearch 触发 `@reset` 事件，父组件调用 `resetSearchParams()`

### 新增角色
- 点击"新增角色"按钮，dialogType 设为 'add'，dialogVisible 打开
- RoleEditDialog 监听 dialogType 动态显示标题
- 表单重置为默认值 enabled: true

### 编辑角色
- 点击行内"编辑角色"，dialogType 设为 'edit'，currentRoleData 传入当前行数据
- RoleEditDialog 打开并回填表单

### 删除角色
- 点击行内"删除角色"，弹出 ElMessageBox 确认框
- 确认后调用删除接口，刷新数据

### 菜单权限
- 点击行内"菜单权限"，打开 RolePermissionDialog
- 加载菜单树（从 useMenuStore 读取 menuList）
- 支持展开/收起、全部选择/取消、保存权限

## 7. 路由配置

```typescript
{
  path: 'role',
  name: 'Role',
  component: '/system/role',
  meta: {
    title: '角色管理',
    keepAlive: true,
    roles: ['R_SUPER', 'R_ADMIN']
  }
}
```

## 8. 视觉与布局

- 搜索栏默认隐藏（showSearchBar = false），点击"筛选"按钮展开
- 表格列：角色ID（宽度100）、角色名称/编码/描述（最小宽度）、状态（宽度100）、创建日期（宽度180，可排）
- 操作列固定右侧（width: 80），使用 ButtonMore 下拉
- 编辑弹窗宽度 30%，权限弹窗宽度 520px，均居中显示

## 9. 待确认

- [ ] 删除角色接口是否需要二次确认
- [ ] 角色编码是否需要全局唯一性校验
- [ ] 角色状态变更是否需要单独接口（而非编辑时修改）
- [ ] 权限弹窗中的默认选中数据是否从接口加载
- [ ] 菜单权限是否需要支持"数据权限"配置

## 10. 实现建议

1. **API 补全：** 建议先补齐 /api/role/add、/api/role/edit、/api/role/delete、/api/role/permissions、/api/role/savePermissions 五个接口
2. **Mock 数据：** 正式接口未完成前，可在 src/mock 文件夹下添加角色相关 mock 数据
3. **权限回显：** RolePermissionDialog 中应新增 fetchGetRoleMenuIds 接口用于编辑时回显已选菜单
4. **角色编码：** 建议后端对 roleCode 做唯一性约束，前端在编辑时禁止修改 roleCode
