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

API 对接说明

更新时间: 2026-01-09

---

✅ 已完成的修改

1. 创建了认证 API 服务

文件: src/api/authApi.ts

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登录函数（方便开发测试）

切换方式:

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

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

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

---

🔌 API 接口规范

登录接口

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

请求参数:

{
  username: string    // 用户名
  password: string    // 密码
  remember?: boolean  // 是否记住密码
  captcha?: string    // 验证码（可选）
}

响应格式:

{
  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}

响应格式:

{
  code: 200,
  message: 'success',
  data: {
    id: string | number
    username: string
    realName: string
    roles: string[]
    permissions: string[]
    avatar?: string
    email?: string
    phone?: string
  }
}

---

🔐 权限控制说明

角色定义

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

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

权限格式

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

示例:

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

前端权限验证

路由级权限（在 asyncRoutes.ts 中配置）:

{
  path: '/system/user',
  meta: {
    roles: ['R_SUPER', 'R_ADMIN']  // 只有超管和管理员可访问
  }
}

按钮级权限（使用 v-auth 指令）:

<el-button v-auth="'user:edit'">编辑</el-button>

---

📦 状态码规范

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

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

---

🚀 快速上手

1. 配置API地址

文件: .env.development

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

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

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

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

2. 切换到真实API

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

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切换

// src/composables/useLogin.ts

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

3. Token 检查

打开浏览器控制台（F12）→ Application → Local Storage → 查看 user 键：

{
  "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 行

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

Q4: Token 过期如何处理？

系统已自动处理 Token 过期：

1. 检测到 401 状态码自动跳转登录页
2. 可实现自动刷新 Token（需要后端支持）

---

📝 后端接口开发建议

1. 登录接口返回完整用户信息

避免前端登录后再次调用获取用户信息接口，减少请求次数。

2. 用户信息必须包含 roles

{
  "roles": ["R_ADMIN", "R_USER"]  // 必须
}

3. 支持 Token 刷新机制

// 刷新Token接口
POST /api/auth/refresh
{
  "refreshToken": "refresh-token-here"
}

4. 统一响应格式

{
  code: 200,
  message: "success",
  data: { ... }
}

---

✨ 下一步

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

---

联系支持:

• 前端问题：查看本文档或项目 README
• 后端对接：与后端开发人员沟通接口格式

祝对接顺利！🚀