API接口规范

文档概述

本文档详细说明了邮轮穿舱件管理系统前端与后端API的交互规范和接口定义。基于对项目代码结构和API文档的分析，本文档涵盖了认证机制、HTTP请求处理、用户管理、工单管理等核心功能的接口规范。

参考文件来源：

• README.md
• docs/user-api.md
• src/http/index.js
• API_Doc_ticket.md
• package.json

1. 系统架构概述

1.1 技术栈分析

前端技术栈：

• Vue.js 2.6.14 - 前端框架
• Vue Router 3.6.5 - 路由管理
• Vuex 3.6.2 - 状态管理
• Vuetify 2.6.0 - UI组件库
• Axios 1.7.5 - HTTP客户端
• js-cookie 3.0.5 - Cookie管理

后端交互：

• RESTful API架构
• JWT认证机制
• JSON数据格式
• HTTP/HTTPS协议

1.2 系统架构图

flowchart TD
    subgraph Frontend
        A[Vue Components] --> B[Vue Router]
        A --> C[Vuex Store]
        B --> D[Views]
        C --> D
        D --> E[HTTP Service]
    end
    
    subgraph Backend
        F[Authentication API] --> G[User Management API]
        F --> H[Ticket Management API]
        G --> I[Workpiece Management API]
        H --> I
    end
    
    E --> F
    E --> G
    E --> H
    E --> I
    
    style A fill:#e1f5fe
    style E fill:#f3e5f5
    style F fill:#e8f5e8
    style H fill:#fff3e0

2. HTTP请求处理规范

2.1 Axios配置

前端使用Axios作为HTTP客户端，配置如下：

// src/http/index.js 配置示例
const service = axios.create({
  baseURL: process.env.VUE_APP_API || "",
  withCredentials: false,
});

关键配置说明：

• baseURL: 通过环境变量动态配置API基础路径
• withCredentials: false: 不携带Cookie凭证
• 请求拦截器自动添加JWT认证头
• 响应拦截器处理统一错误响应

2.2 请求拦截器

// 请求拦截器 - 自动添加认证头
service.interceptors.request.use(
  config => {
    const token = Cookies.get('token');
    if (token) {
      config.headers['Authorization'] = `Bearer ${token}`;
    }
    return config;
  },
  error => {
    return Promise.reject(error);
  }
);

2.3 通用响应格式

成功响应格式：

{
  "data": {},
  "message": "操作成功"
}

错误响应格式：

{
  "detail": "错误描述信息"
}

3. 认证接口规范

3.1 JWT认证流程

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Cookie
    
    User->>Frontend: 输入用户名密码
    Frontend->>Backend: POST /token
    Backend-->>Frontend: JWT Token
    Frontend->>Cookie: 存储token
    Frontend->>Backend: 后续请求携带token
    Backend-->>Frontend: 认证数据

3.2 认证接口详情

3.2.1 获取JWT令牌

接口信息：

• 方法: POST
• 路径: /token
• 认证: 不需要
• 数据格式: application/x-www-form-urlencoded

请求参数：

参数名	类型	必填	描述	示例值
username	string	是	用户名	"admin"
password	string	是	密码	"password123"

响应示例：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

4. 用户管理接口规范

4.1 用户状态枚举

状态值	描述
active	激活状态
inactive	非激活状态
suspended	暂停状态
deleted	已删除状态

4.2 用户接口列表

4.2.1 用户注册

接口信息：

• 方法: POST
• 路径: /users/register
• 认证: 不需要

请求参数：

{
  "username": "newuser",
  "password": "password123",
  "email": "user@example.com",
  "sms": "13800138000",
  "status": "active",
  "openid": "wx_openid_123",
  "is_system": false
}

4.2.2 用户列表查询

接口信息：

• 方法: GET
• 路径: /users/
• 认证: 需要JWT

查询参数：

参数名	类型	必填	描述	限制
skip	integer	否	跳过的记录数	≥0
limit	integer	否	返回的记录数	1-1000

5. 工单管理接口规范

5.1 工单数据模型

5.1.1 请求数据模型 (TicketInSchema)

{
  "ticket_type": "inspect",
  "ticket_status": "open",
  "target_workpiece": 123,
  "ticket_from": "生产部门",
  "ticket_tos": "维护部门",
  "ticket_content": "设备需要检查",
  "ticket_title": "设备检查工单",
  "feedback_text": "检查完成",
  "image_list": "image1.jpg,image2.jpg",
  "reference_list": "ref1,ref2",
  "created_by": 1
}

5.1.2 响应数据模型 (TicketOutSchema)

{
  "ticket_id": 1,
  "ticket_type": "inspect",
  "ticket_status": "open",
  "target_workpiece": 123,
  "ticket_from": "生产部门",
  "ticket_tos": "维护部门",
  "ticket_content": "设备需要检查",
  "ticket_title": "设备检查工单",
  "feedback_text": "检查完成",
  "image_list": "image1.jpg,image2.jpg",
  "reference_list": "ref1,ref2",
  "created_by": 1,
  "updated_by": 2,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T11:00:00Z"
}

5.2 工单类型和状态

工单类型：

类型	值	说明
检查工单	inspect	用于设备检查、质量检查等
维护工单	maintenance	用于设备维护、修理等

工单状态：

状态	值	说明
开放	open	工单已创建，等待处理
进行中	running	工单正在处理中
已关闭	closed	工单已完成并关闭
问题	issue	工单处理过程中遇到问题

5.3 工单接口详情

5.3.1 创建工单

接口信息：

• 方法: POST
• 路径: /ticket/
• 认证: 需要

请求示例：

const ticketData = {
  ticket_type: "inspect",
  ticket_status: "open",
  target_workpiece: 123,
  ticket_from: "生产部门",
  ticket_tos: "质检部门",
  ticket_content: "产品质量检查",
  ticket_title: "产品质量检查工单",
  created_by: 1
};

5.3.2 获取工单列表

接口信息：

• 方法: GET
• 路径: /ticket/all
• 认证: 需要

6. 错误处理规范

6.1 HTTP状态码说明

状态码	说明	处理建议
200	请求成功	正常处理响应数据
201	创建成功	处理新创建的资源
204	删除成功	无内容返回，确认操作成功
400	请求参数错误	检查请求参数格式和内容
401	未授权/认证失败	重新登录获取有效token
404	资源不存在	检查请求路径和资源ID
500	服务器内部错误	联系系统管理员

6.2 前端错误处理策略

// 统一错误处理示例
service.interceptors.response.use(
  response => {
    return response;
  },
  error => {
    if (error.response.status === 401) {
      // 跳转到登录页面
      router.push('/login');
    } else if (error.response.status === 500) {
      // 显示服务器错误提示
      showError('服务器内部错误，请稍后重试');
    }
    return Promise.reject(error);
  }
);

7. 数据流架构

7.1 前端数据流图

flowchart LR
    A[用户操作] --> B[Vue组件]
    B --> C[Actions]
    C --> D[HTTP请求]
    D --> E[后端API]
    E --> F[Mutations]
    F --> G[State更新]
    G --> H[组件重新渲染]
    H --> A
    
    style A fill:#e3f2fd
    style D fill:#fce4ec
    style E fill:#e8f5e8
    style G fill:#fff3e0

7.2 组件依赖关系

graph TD
    A[App.vue] --> B[Router]
    A --> C[Store]
    B --> D[LoginView.vue]
    B --> E[HomeView.vue]
    B --> F[Admin Views]
    B --> G[Workpiece Views]
    
    F --> F1[UserAdmin.vue]
    F --> F2[TicketAdmin.vue]
    F --> F3[ImageAdmin.vue]
    
    G --> G1[WorkpieceView.vue]
    G --> G2[WorkpieceEdit.vue]
    
    style A fill:#bbdefb
    style D fill:#c8e6c9
    style F fill:#ffecb3
    style G fill:#d7ccc8

8. 安全规范

8.1 认证安全

• JWT token存储在Cookie中，避免XSS攻击
• 所有敏感接口都需要JWT认证
• token有过期时间，需要定期刷新
• 密码传输使用HTTPS加密

8.2 数据验证

• 前端进行基础数据格式验证
• 后端进行完整业务逻辑验证
• 文件上传限制类型和大小
• SQL注入防护

9. 性能优化建议

9.1 请求优化

• 使用请求拦截器统一处理认证
• 实现请求缓存机制
• 批量处理相关请求
• 合理设置请求超时时间

9.2 数据优化

• 分页查询大数据集
• 懒加载非关键数据
• 使用Vuex进行状态管理
• 实现数据本地缓存

索引

本文档详细说明了邮轮穿舱件管理系统前端与后端API的完整交互规范。通过分析项目代码结构和API文档，建立了清晰的接口定义、数据模型和错误处理机制。前端采用Vue.js技术栈，通过Axios进行HTTP通信，使用JWT进行身份认证，实现了用户管理、工单管理等核心功能。

关键特性：

• 统一的HTTP请求处理机制
• 完整的JWT认证流程
• 标准化的数据模型定义
• 完善的错误处理策略
• 清晰的组件架构设计

该规范为前后端开发提供了明确的接口约定，确保了系统的高效、稳定运行。