Initial commit: One Pipe System

完整的管理系统，包含账户管理、卡片管理、套餐管理、财务管理等功能模块。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/API对接说明.md

@@ -0,0 +1,343 @@
+# 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
+- 后端对接：与后端开发人员沟通接口格式
+
+祝对接顺利！🚀