one-pipe-system/docs/API对接说明.md

# API 对接说明

> 更新时间: 2026-01-09

---

## ✅ 已完成的修改

### 1. 创建了认证 API 服务
**文件**: `src/api/authApi.ts`

```typescript
import { AuthService } from '@/api/authApi'

// 登录
AuthService.login({ username, password, remember })

// 获取用户信息
AuthService.getUserInfo()

// 登出
AuthService.logout()

// 刷新Token
AuthService.refreshToken(refreshToken)
```

### 2. 修改了登录逻辑
**文件**: `src/composables/useLogin.ts`

**关键修改**:
- ✅ 添加了 `USE_MOCK` 开关（第 29 行）
- ✅ 创建了 `handleRealLogin()` 真实API登录函数
- ✅ 保留了 `handleMockLogin()` Mock登录函数（方便开发测试）

**切换方式**:
```typescript
// 文件: src/composables/useLogin.ts 第 29 行

// 使用 Mock 数据（开发测试）
const USE_MOCK = true

// 使用真实 API（生产环境）
const USE_MOCK = false  // ← 当前设置
```

---

## 🔌 API 接口规范

### 登录接口

**请求地址**: `POST /api/auth/login`

**请求参数**:
```typescript
{
  username: string    // 用户名
  password: string    // 密码
  remember?: boolean  // 是否记住密码
  captcha?: string    // 验证码（可选）
}
```

**响应格式**:
```typescript
{
  code: number        // 状态码：200 成功
  message: string     // 消息
  data: {
    token: string              // 访问令牌 (必需)
    refreshToken?: string      // 刷新令牌 (可选)
    expiresIn?: number         // 过期时间(秒) (可选)
    userInfo: {                // 用户信息 (推荐返回，避免二次请求)
      id: string | number
      username: string
      realName: string
      roles: string[]          // 角色列表 ['R_SUPER', 'R_ADMIN', ...]
      permissions: string[]    // 权限列表 ['*:*:*', 'user:edit', ...]
      avatar?: string
      email?: string
      phone?: string
      // ... 其他用户信息
    }
  }
}
```

### 获取用户信息接口

**请求地址**: `GET /api/auth/userInfo`

**请求头**:
```
Authorization: Bearer {token}
```

**响应格式**:
```typescript
{
  code: 200,
  message: 'success',
  data: {
    id: string | number
    username: string
    realName: string
    roles: string[]
    permissions: string[]
    avatar?: string
    email?: string
    phone?: string
  }
}
```

---

## 🔐 权限控制说明

### 角色定义
系统预定义了以下角色（可根据需求调整）：

```typescript
enum UserRole {
  SUPER_ADMIN = 'R_SUPER',     // 超级管理员
  ADMIN = 'R_ADMIN',            // 管理员
  AGENT = 'R_AGENT',            // 代理商
  ENTERPRISE = 'R_ENTERPRISE'   // 企业客户
}
```

### 权限格式
权限使用通配符格式：`模块:操作:范围`

**示例**:
- `*:*:*` - 所有权限
- `user:*:*` - 用户模块所有权限
- `user:edit:*` - 用户编辑权限
- `card:view:own` - 查看自己的卡

### 前端权限验证

**路由级权限**（在 `asyncRoutes.ts` 中配置）:
```typescript
{
  path: '/system/user',
  meta: {
    roles: ['R_SUPER', 'R_ADMIN']  // 只有超管和管理员可访问
  }
}
```

**按钮级权限**（使用 `v-auth` 指令）:
```vue
<el-button v-auth="'user:edit'">编辑</el-button>
```

---

## 📦 状态码规范

**推荐使用的状态码** (已在 `src/utils/http/status.ts` 定义):

```typescript
export enum ApiStatus {
  success = 200,           // 成功
  unauthorized = 401,      // 未授权
  forbidden = 403,         // 禁止访问
  notFound = 404,          // 未找到
  serverError = 500        // 服务器错误
}
```

---

## 🚀 快速上手

### 1. 配置API地址

**文件**: `.env.development`

```env
# API 地址前缀
VITE_API_URL = http://your-backend-api.com

# 或者使用代理（推荐）
VITE_API_URL = /api
```

**文件**: `vite.config.ts` (如果使用代理)

```typescript
server: {
  proxy: {
    '/api': {
      target: 'http://your-backend-api.com',  // 后端地址
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}
```

### 2. 切换到真实API

**文件**: `src/composables/useLogin.ts` 第 29 行

```typescript
const USE_MOCK = false  // 改为 false
```

### 3. 测试登录

1. 启动开发服务器：`npm run dev`
2. 访问登录页面：`http://localhost:3006/#/auth/login`
3. 输入后端提供的测试账号密码
4. 点击登录

---

## 🔧 调试技巧

### 1. 查看请求/响应

打开浏览器开发者工具（F12）→ Network 标签，查看：
- 请求URL
- 请求参数
- 响应数据
- 状态码

### 2. Mock 和真实API切换

```typescript
// src/composables/useLogin.ts

const USE_MOCK = true   // 开发时使用 Mock
const USE_MOCK = false  // 对接时使用真实 API
```

### 3. Token 检查

打开浏览器控制台（F12）→ Application → Local Storage → 查看 `user` 键：
```json
{
  "isLogin": true,
  "accessToken": "your-token-here",
  "info": { ... }
}
```

### 4. 请求拦截器日志

**文件**: `src/utils/http/interceptors.ts`

已自动添加请求/响应日志，在控制台可以看到：
- 🚀 发送请求
- ✅ 请求成功
- ❌ 请求失败

---

## ⚠️ 常见问题

### Q1: 登录后提示"获取用户角色失败"

**原因**: 后端返回的用户信息中没有 `roles` 字段

**解决**:
1. 确保后端返回的 `userInfo.roles` 是数组
2. 至少包含一个角色，如：`["R_ADMIN"]`

### Q2: 登录成功但页面一直转圈

**原因**: 路由守卫中没有通过权限验证

**解决**:
1. 检查用户信息中是否有 `roles` 字段
2. 临时开启开发模式跳过权限验证（见下文）

### Q3: 如何临时跳过权限验证？

**文件**: `src/router/guards/beforeEach.ts` 第 28 行

```typescript
const DEV_MODE_SKIP_AUTH = true  // 改为 true，跳过所有权限验证
```

### Q4: Token 过期如何处理？

系统已自动处理 Token 过期：
1. 检测到 401 状态码自动跳转登录页
2. 可实现自动刷新 Token（需要后端支持）

---

## 📝 后端接口开发建议

### 1. 登录接口返回完整用户信息
避免前端登录后再次调用获取用户信息接口，减少请求次数。

### 2. 用户信息必须包含 roles
```json
{
  "roles": ["R_ADMIN", "R_USER"]  // 必须
}
```

### 3. 支持 Token 刷新机制
```typescript
// 刷新Token接口
POST /api/auth/refresh
{
  "refreshToken": "refresh-token-here"
}
```

### 4. 统一响应格式
```typescript
{
  code: 200,
  message: "success",
  data: { ... }
}
```

---

## ✨ 下一步

1. ✅ 后端提供测试环境API地址
2. ✅ 配置 `VITE_API_URL` 或代理
3. ✅ 切换 `USE_MOCK = false`
4. ✅ 测试登录功能
5. ✅ 根据实际API调整请求/响应格式
6. ✅ 完善其他业务接口

---

**联系支持**:
- 前端问题：查看本文档或项目 README
- 后端对接：与后端开发人员沟通接口格式

祝对接顺利！🚀