API参考文档

概述

本文档详细介绍了邮轮穿舱件管理系统的所有API接口，包括用户管理、工单管理、文章管理、审计日志等核心功能模块。所有接口均基于RESTful架构设计，使用JSON数据格式进行通信。

目录

• 1. 基础信息
• 2. 用户管理API
• 3. 工单管理API
• 4. 文章管理API
• 5. 审计日志API
• 6. 系统架构图
• 7. 数据流程图
• 8. 调用示例

1. 基础信息

1.1 系统配置

• 基础URL: http://localhost:8000
• 协议: HTTP/HTTPS
• 数据格式: JSON
• 字符编码: UTF-8

1.2 认证方式

除用户注册和JWT令牌获取接口外，其他接口均需要JWT认证。

请求头要求:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

1.3 通用响应格式

成功响应:

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

错误响应:

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

1.4 状态码说明

状态码	说明
200	请求成功
201	创建成功
204	删除成功（无内容返回）
400	请求参数错误
401	未授权/认证失败
404	资源不存在
500	服务器内部错误

2. 用户管理API

2.1 认证接口

2.1.1 获取JWT令牌

• 方法: POST
• 路径: /token
• 功能: 用户登录获取JWT访问令牌
• 权限: 无

请求参数:

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

请求示例:

curl -X POST "http://localhost:8000/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=password123"

响应示例:

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

2.2 用户管理接口

2.2.1 用户注册

• 方法: POST
• 路径: /users/register
• 功能: 用户自主注册新账户
• 权限: 无

请求参数:

参数名	类型	必填	描述	示例值
username	string	是	用户名	"newuser"
password	string	是	密码	"password123"
email	string	否	邮箱地址	"user@example.com"
sms	string	否	手机号码	"13800138000"

请求示例:

curl -X POST "http://localhost:8000/users/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "email": "user@example.com"
  }'

2.2.2 获取用户列表

• 方法: GET
• 路径: /users/
• 功能: 分页获取用户列表
• 权限: 需要JWT认证

查询参数:

参数名	类型	必填	描述	示例值
skip	integer	否	跳过的记录数	0
limit	integer	否	返回的记录数	100

请求示例:

curl -X GET "http://localhost:8000/users/?skip=0&limit=10" \
  -H "Authorization: Bearer <JWT_TOKEN>"

2.2.3 用户认证

• 方法: POST
• 路径: /users/authenticate
• 功能: 验证用户名和密码
• 权限: 无

请求示例:

curl -X POST "http://localhost:8000/users/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user1",
    "password": "password123"
  }'

参考文件: docs/user-api.md

3. 工单管理API

3.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
}

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

3.2 接口详情

3.2.1 创建工单

• 方法: POST
• 路径: /ticket/
• 功能: 创建一个新的工单
• 权限: 需要用户认证

请求示例:

curl -X POST "http://localhost:8000/ticket/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "ticket_type": "inspect",
    "ticket_status": "open",
    "target_workpiece": 123,
    "ticket_from": "生产部门",
    "ticket_tos": "维护部门",
    "ticket_content": "设备需要定期检查",
    "ticket_title": "设备检查工单",
    "created_by": 1
  }'

3.2.2 获取工单列表

• 方法: GET
• 路径: /ticket/all
• 功能: 获取系统中所有工单的列表
• 权限: 需要用户认证

请求示例:

curl -X GET "http://localhost:8000/ticket/all" \
  -H "Authorization: Bearer <JWT_TOKEN>"

3.2.3 工单状态说明

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

参考文件: API_Doc_ticket.md

4. 文章管理API

4.1 数据模型

ArticleSchema（响应数据模型）

{
  "id": 1,
  "title": "文章标题",
  "author": "作者名",
  "publishDate": "2025-01-01",
  "content": "文章正文"
}

ArticleIn（请求数据模型）

{
  "title": "文章标题",
  "author": "作者名",
  "publishDate": "2025-01-01",
  "content": "文章正文"
}

4.2 接口详情

4.2.1 获取文章详情

• 方法: GET
• 路径: /article/detail
• 查询参数: id（integer，必填）
• 权限: 需要JWT认证

请求示例:

curl -X GET "http://localhost:8000/article/detail?id=1" \
  -H "Authorization: Bearer <JWT_TOKEN>"

4.2.2 获取文章列表

• 方法: GET
• 路径: /article/list
• 查询参数: skip（可选），limit（可选）
• 权限: 需要JWT认证

请求示例:

curl -X GET "http://localhost:8000/article/list?skip=0&limit=10" \
  -H "Authorization: Bearer <JWT_TOKEN>"

4.2.3 创建文章

• 方法: POST
• 路径: /article/create
• 权限: 需要JWT认证

请求示例:

curl -X POST "http://localhost:8000/article/create" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新文章",
    "author": "作者X",
    "publishDate": "2025-02-01",
    "content": "这是一篇新文章"
  }'

参考文件: src/views/article/api.md

5. 审计日志API

5.1 数据模型

AccessLog（响应数据模型）

{
  "log_id": 1001,
  "action_type": "user_router",
  "action_title": "创建用户",
  "action_description": "创建用户 admin",
  "related_users": "1",
  "related_tickets": null,
  "related_workpieces": null,
  "created_by": 1,
  "updated_by": -1,
  "created_at": "2025-01-01T10:00:00Z",
  "updated_at": "2025-01-01T10:00:00Z"
}

5.2 接口详情

5.2.1 获取日志详情

• 方法: GET
• 路径: /log/detail/{log_id}
• 权限: 默认认证

请求示例:

curl -X GET "http://localhost:8000/log/detail/1001"

5.2.2 获取所有访问日志

• 方法: GET
• 路径: /log/all
• 查询参数: skip（可选），limit（可选）
• 权限: 默认认证

请求示例:

curl -X GET "http://localhost:8000/log/all?skip=0&limit=50"

5.2.3 操作类型说明

类型	说明
auth_router	认证路由
user_router	用户路由
article_router	文章路由
ticket_router	工单路由
workpiece_info_router	作品信息路由

参考文件: src/views/audit/api.md

6. 系统架构图

flowchart TD
    subgraph Frontend["前端应用"]
        A[Vue.js应用] --> B[路由管理]
        B --> C[状态管理]
        C --> D[HTTP客户端]
    end
    
    subgraph Backend["后端API服务"]
        E[认证服务] --> F[用户管理]
        E --> G[工单管理]
        E --> H[文章管理]
        E --> I[审计日志]
        F --> J[数据库]
        G --> J
        H --> J
        I --> J
    end
    
    subgraph Infrastructure["基础设施"]
        K[Axios HTTP客户端]
        L[JWT认证]
        M[Cookie管理]
    end
    
    D --> K
    K --> E
    L --> E
    M --> L

架构说明:

• 前端采用Vue.js框架，使用Vue Router进行路由管理，Vuex进行状态管理
• 后端提供RESTful API服务，包含认证、用户管理、工单管理、文章管理、审计日志等模块
• 使用Axios作为HTTP客户端，JWT进行认证，Cookie管理用户会话
• 所有API请求通过统一的HTTP拦截器进行认证令牌管理

参考文件: src/http/index.js

7. 数据流程图

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端应用
    participant Auth as 认证服务
    participant API as API服务
    participant DB as 数据库
    
    User->>Frontend: 访问系统
    Frontend->>Auth: 请求JWT令牌
    Auth-->>Frontend: 返回access_token
    Frontend->>API: API请求(带token)
    
    alt 用户管理操作
        API->>DB: 用户数据操作
        DB-->>API: 返回结果
        API->>API: 记录审计日志
    else 工单管理操作
        API->>DB: 工单数据操作
        DB-->>API: 返回结果
        API->>API: 记录审计日志
    else 文章管理操作
        API->>DB: 文章数据操作
        DB-->>API: 返回结果
        API->>API: 记录审计日志
    end
    
    API-->>Frontend: 返回操作结果
    Frontend-->>User: 显示结果

流程说明:

1. 用户访问系统，前端应用向认证服务请求JWT令牌
2. 认证成功后，前端携带token访问各API服务
3. API服务处理业务逻辑，操作数据库并记录审计日志
4. 操作结果返回给前端，最终展示给用户

8. 调用示例

8.1 完整用户登录和工作流程

// 用户登录示例
const login = async (username, password) => {
    try {
        // 获取JWT令牌
        const tokenResponse = await fetch('/token', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
            },
            body: `username=${username}&password=${password}`
        });
        
        if (!tokenResponse.ok) {
            throw new Error('登录失败');
        }
        
        const { access_token } = await tokenResponse.json();
        
        // 存储token
        localStorage.setItem('token', access_token);
        
        // 获取用户信息
        const userResponse = await fetch('/users/username/' + username, {
            headers: {
                'Authorization': `Bearer ${access_token}`
            }
        });
        
        const user = await userResponse.json();
        return { user, token: access_token };
    } catch (error) {
        console.error('登录错误:', error);
        throw error;
    }
};

// 创建工单示例
const createTicket = async (ticketData) => {
    const token = localStorage.getItem('token');
    
    const response = await fetch('/ticket/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        body: JSON.stringify(ticketData)
    });
    
    if (!response.ok) {
        throw new Error('创建工单失败');
    }
    
    return await response.json();
};

8.2 错误处理示例

// 统一错误处理
const handleApiError = (error) => {
    if (error.response) {
        switch (error.response.status) {
            case 401:
                // 未授权，跳转到登录页
                window.location.href = '/login';
                break;
            case 404:
                // 资源不存在
                console.error('请求的资源不存在');
                break;
            case 500:
                // 服务器错误
                console.error('服务器内部错误');
                break;
            default:
                console.error('请求失败:', error.response.status);
        }
    } else {
        console.error('网络错误:', error.message);
    }
};

// 使用示例
try {
    const result = await someApiCall();
    // 处理成功结果
} catch (error) {
    handleApiError(error);
}

索引

本文档全面介绍了邮轮穿舱件管理系统的API接口，涵盖了用户认证、工单管理、文章管理、审计日志等核心功能。所有接口遵循RESTful设计原则，使用统一的认证和错误处理机制。

关键特性:

• 基于JWT的认证机制
• 统一的数据格式和错误处理
• 完整的审计日志记录
• 分页查询支持
• 详细的错误状态码

参考文件:

• package.json
• README.md
• src/http/index.js

通过本文档，开发人员可以快速了解系统API的使用方法，实现前后端的高效协作。