manta/gofaster/ROLE_MANAGEMENT_API_GUIDE.md

# 角色管理前后台交互指南

## 概述

本文档介绍如何将前台角色管理功能连接到真实的后端API，实现完整的前后台交互。

## 功能特性

### ✅ 已实现功能

1. **角色CRUD操作**
   - 获取角色列表（支持分页）
   - 创建新角色
   - 更新角色信息
   - 删除角色

2. **API测试模式**
   - 支持测试模式切换（无需JWT认证）
   - 支持正式模式（需要JWT认证）
   - 实时API连接测试

3. **错误处理**
   - 统一的错误响应格式
   - 友好的错误提示
   - 网络连接异常处理

4. **用户体验**
   - 加载状态显示
   - 操作确认提示
   - 实时数据刷新

## 快速开始

### 1. 启动服务

使用完整启动脚本同时启动前后台：

```powershell
# 标准模式启动
.\start-full.ps1

# 调试模式启动
.\start-full.ps1 -Debug

# 测试模式启动
.\start-full.ps1 -Test
```

### 2. 访问应用

- **前端应用**: http://localhost:8081
- **后端API**: http://localhost:8080
- **API文档**: http://localhost:8080/swagger/index.html

### 3. 测试API连接

1. 进入角色管理页面
2. 点击"测试模式"按钮切换到测试模式
3. 点击"新建角色"测试创建功能
4. 查看角色列表测试获取功能

## API接口说明

### 基础信息

- **API基础路径**: `/api/auth/roles`
- **测试路径**: `/api/auth/roles/test`
- **认证方式**: JWT Bearer Token
- **响应格式**: JSON

### 接口列表

#### 1. 获取角色列表

```http
GET /api/auth/roles?page=1&pageSize=10
```

**响应格式**:
```json
{
  "code": 200,
  "message": "获取角色列表成功",
  "data": {
    "data": [
      {
        "id": 1,
        "name": "管理员",
        "code": "ADMIN",
        "description": "系统管理员",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "page": 1,
    "size": 10,
    "total": 1
  }
}
```

#### 2. 创建角色

```http
POST /api/auth/roles
Content-Type: application/json

{
  "name": "新角色",
  "code": "NEW_ROLE",
  "description": "角色描述"
}
```

**响应格式**:
```json
{
  "code": 200,
  "message": "角色创建成功",
  "data": {
    "id": 2,
    "name": "新角色",
    "code": "NEW_ROLE",
    "description": "角色描述",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

#### 3. 更新角色

```http
PUT /api/auth/roles/{id}
Content-Type: application/json

{
  "name": "更新后的角色",
  "code": "UPDATED_ROLE",
  "description": "更新后的描述"
}
```

#### 4. 删除角色

```http
DELETE /api/auth/roles/{id}
```

**响应格式**:
```json
{
  "code": 200,
  "message": "角色删除成功",
  "data": null
}
```

## 前端组件使用

### 1. 角色管理主页面

```vue
<template>
  <RoleManagement />
</template>

<script>
import { RoleManagement } from '@/modules/role-management'

export default {
  components: {
    RoleManagement
  }
}
</script>
```

### 2. API测试页面

```vue
<template>
  <RoleApiTest />
</template>

<script>
import { RoleApiTest } from '@/modules/role-management'

export default {
  components: {
    RoleApiTest
  }
}
</script>
```

### 3. 直接使用服务

```javascript
import { roleService } from '@/modules/role-management'

// 获取角色列表
const roles = await roleService.getRoles(1, 10)

// 创建角色
const newRole = await roleService.createRole({
  name: '测试角色',
  code: 'TEST_ROLE',
  description: '测试描述'
})

// 更新角色
const updatedRole = await roleService.updateRole(1, {
  name: '更新后的角色',
  code: 'UPDATED_ROLE',
  description: '更新后的描述'
})

// 删除角色
await roleService.deleteRole(1)
```

## 配置说明

### 1. API基础URL配置

前端配置文件: `app/src/config/app.config.js`

```javascript
export const appConfig = {
  development: {
    apiBaseUrl: 'http://localhost:8080/api',
    // ...
  }
}
```

### 2. 测试模式配置

通过localStorage控制测试模式：

```javascript
// 启用测试模式
localStorage.setItem('role-test-mode', 'true')

// 禁用测试模式
localStorage.setItem('role-test-mode', 'false')

// 检查测试模式状态
const isTestMode = localStorage.getItem('role-test-mode') === 'true'
```

### 3. JWT认证配置

```javascript
// 设置JWT token
localStorage.setItem('token', 'your-jwt-token')

// 清除JWT token
localStorage.removeItem('token')
```

## 错误处理

### 1. 网络错误

```javascript
try {
  const response = await roleService.getRoles()
} catch (error) {
  if (error.code === 0) {
    console.error('网络连接失败')
  } else if (error.code === 401) {
    console.error('认证失败，请重新登录')
  } else {
    console.error('请求失败:', error.message)
  }
}
```

### 2. 业务错误

```javascript
const response = await roleService.createRole(roleData)
if (response.code !== 200) {
  console.error('业务错误:', response.message)
}
```

## 开发调试

### 1. 启用调试模式

```powershell
# 启动调试模式
.\start-full.ps1 -Debug
```

### 2. 查看API日志

后端日志文件: `backend/logs/app.log`

### 3. 使用API测试页面

访问角色管理API测试页面，可以：
- 查看API配置信息
- 手动测试各个接口
- 查看详细的请求响应
- 切换测试模式

### 4. 浏览器开发者工具

- 打开Network面板查看API请求
- 查看Console面板的错误信息
- 使用Application面板查看localStorage

## 常见问题

### Q1: API连接失败

**解决方案**:
1. 检查后端服务是否启动
2. 确认API基础URL配置正确
3. 检查防火墙设置
4. 查看后端日志

### Q2: 认证失败

**解决方案**:
1. 切换到测试模式（无需认证）
2. 检查JWT token是否有效
3. 重新登录获取新token

### Q3: 数据不显示

**解决方案**:
1. 检查API响应格式
2. 确认数据库中有数据
3. 查看浏览器控制台错误

### Q4: 创建/更新失败

**解决方案**:
1. 检查必填字段是否填写
2. 确认角色名称和代码唯一性
3. 查看后端验证错误信息

## 扩展功能

### 1. 权限管理

可以扩展角色管理功能，添加：
- 角色权限分配
- 权限树形展示
- 批量权限操作

### 2. 用户角色分配

可以添加：
- 用户角色分配页面
- 批量角色分配
- 角色继承关系

### 3. 角色模板

可以添加：
- 角色模板管理
- 快速创建角色
- 角色导入导出

## 技术栈

### 前端
- Vue 3 (Composition API)
- Axios (HTTP客户端)
- Vue Router (路由管理)

### 后端
- Go (Gin框架)
- GORM (ORM)
- JWT (认证)

### 数据库
- MySQL/PostgreSQL
- Redis (缓存)

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交代码
4. 创建Pull Request

## 许可证

MIT License