跳到主要内容

API参考文档

概述​

邮轮穿舱件管理系统后台提供完整的RESTful API接口，用于管理用户、权限、工件、工单、图片等核心业务对象。系统基于FastAPI框架构建，支持JWT认证和权限控制。

认证与授权​

JWT认证接口​

端点: POST /token

描述: 使用用户名和密码获取JWT访问令牌

请求参数:

  • username (string, required): 用户名
  • password (string, required): 密码

响应格式:

\{
  "access_token": "jwt_token_string",
  "token_type": "bearer"
\}

错误代码:

  • 401: 认证失败，用户名或密码错误

参考文件: login.py

用户管理接口​

创建用户​

端点: POST /users/

权限: system:write

描述: 创建一个新的用户账户

请求体:

\{
  "username": "string",
  "password": "string",
  "email": "string (optional)",
  "sms": "string (optional)",
  "status": "active|inactive|suspended|deleted (optional)",
  "openid": "string (optional)",
  "is_system": "boolean (optional)"
\}

响应格式: UserSchemaOut

错误代码:

  • 400: 用户名或邮箱已存在
  • 500: 服务器内部错误

参考文件: user_router.py

用户注册​

端点: POST /users/register

描述: 用户自主注册新账户

请求体: 同创建用户 响应格式: UserSchemaOut

参考文件: user_router.py

获取用户列表​

端点: GET /users/

权限: system:read

查询参数:

  • skip (int, optional): 跳过的记录数，默认0
  • limit (int, optional): 返回的记录数，默认100，最大1000

响应格式: List[UserSchemaOut]

参考文件: user_router.py

根据ID获取用户​

端点: GET /users/\{user_id\}

响应格式: UserSchemaOut 错误代码: 404: 用户不存在

参考文件: user_router.py

根据用户名获取用户​

端点: GET /users/username/\{username\}

响应格式: UserSchemaOut

参考文件: user_router.py

更新用户信息​

端点: PUT /users/\{user_id\}

请求体: UserUpdateSchema（支持部分更新） 响应格式: UserSchemaOut

参考文件: user_router.py

删除用户​

端点: DELETE /users/\{user_id\}

响应状态: 204 No Content 错误代码: 404: 用户不存在

参考文件: user_router.py

修改用户状态​

端点: PATCH /users/\{user_id\}/status

请求体:

\{
  "status": "active|inactive|suspended|deleted"
\}

响应格式: UserSchemaOut

参考文件: user_router.py

用户认证​

端点: POST /users/authenticate

请求体: UserLoginSchema 响应格式: UserSchemaOut 错误代码: 401: 认证失败

参考文件: user_router.py

权限管理接口​

获取用户权限列表​

端点: GET /permissions/roles/user/\{user_id\}/scopes

描述: 获取指定用户的所有权限范围

响应格式:

\{
  "user_id": "int",
  "scopes": ["string"]
\}

参考文件: role_router.py

为用户授予权限​

端点: POST /permissions/roles/grant-scope

请求体:

\{
  "user_id": "int",
  "scope_name": "string"
\}

响应格式: \{"message": "权限授予成功"\}

参考文件: role_router.py

为用户撤销权限​

端点: POST /permissions/roles/revoke-scope

请求体: 同授予权限 响应格式: \{"message": "权限撤销成功"\}

参考文件: role_router.py

工件管理接口​

创建工件​

端点: POST /workpiece/

描述: 创建新的工件实体

响应格式: Workpiece ORM对象

参考文件: workpiece_router.py

获取所有工件​

端点: GET /workpiece/all

响应格式: List[Workpiece]

参考文件: workpiece_router.py

删除工件​

端点: DELETE /workpiece/\{wp_id\}

响应格式: \{"message": "Workpiece deleted successfully"\} 错误代码: 404: 工件不存在

参考文件: workpiece_router.py

更新工件状态​

端点: PUT /workpiece/\{wp_id\}/status

请求参数:

  • status (int): 新的状态值

响应格式: 更新后的Workpiece对象

参考文件: workpiece_router.py

工单管理接口​

创建工单​

端点: POST /ticket/

请求体: TicketInSchema 响应格式: TicketOutSchema

参考文件: ticket_router.py

根据工单ID获取工单​

端点: GET /ticket/\{ticket_id\}

响应格式: TicketOutSchema

参考文件: ticket_router.py

更新工单​

端点: PUT /ticket/\{ticket_id\}

请求体: TicketInSchema 响应格式: TicketOutSchema

参考文件: ticket_router.py

删除工单​

端点: DELETE /ticket/\{ticket_id\}

响应格式: TicketOutSchema

参考文件: ticket_router.py

获取所有工单实体​

端点: GET /ticketEntity/all

响应格式: List[TicketOutSchema]

参考文件: ticket_router.py

图片管理接口​

创建新图片实体​

端点: POST /image/create

描述: 上传新图片实体到系统

请求参数:

  • image (file): 图片文件

响应格式: Image ORM对象

参考文件: image_router.py

删除图片实体​

端点: DELETE /image/delete

查询参数: image_id (int) 响应格式: {"msg": "ok"}

参考文件: image_router.py

获取图片OSS键​

端点: GET /image/keyById

查询参数: id (int) 响应格式: Image ORM对象 错误代码: 404: 图片实体不存在

参考文件: image_router.py

绑定图片到工件​

端点: POST /image/enable/bind

请求体:

\{
  "image_id": "int",
  "workpiece_id": "int"
\}

参考文件: image_router.py

解绑图片到工件​

端点: POST /image/disable/bind

请求体: 同绑定接口

参考文件: image_router.py

获取未绑定图片实体​

端点: GET /image/status/list/unbinds

响应格式: List[Image]

参考文件: image_router.py

获取所有绑定元组​

端点: GET /image/status/list/binds

响应格式: List[绑定元组]

参考文件: image_router.py

获取所有图片实体​

端点: GET /image/status/list/imageEntity

响应格式: List[Image]

参考文件: image_router.py

根据key搜索图片​

端点: GET /image/searchByKey

查询参数: key (string) 响应格式: 搜索结果

参考文件: image_router.py

根据ID搜索图片​

端点: GET /image/searchById

查询参数: image_id (int) 响应格式: 搜索结果

参考文件: image_router.py

统计管理接口​

统计摘要接口​

端点: GET /stat/countInfo

描述: 获取系统统计摘要

响应格式:

\{
  "user_count": "int",
  "ticket_count": "int", 
  "image_count": "int",
  "log_count": "int"
\}

参考文件: stat_router.py

系统状态接口​

根状态检查​

端点: GET /

响应格式: {"message": "system works fine"}

参考文件: main.py

API状态检查​

端点: GET /info

响应格式: {"status": "ok"}

参考文件: main.py

数据模型​

UserSchemaIn​

\{
  "username": "string",
  "password": "string", 
  "email": "string?",
  "sms": "string?",
  "status": "UserStatus?",
  "openid": "string?",
  "is_system": "boolean?"
\}

参考文件: user_schema.py

UserSchemaOut​

包含所有用户字段及创建/更新时间戳

参考文件: user_schema.py

TicketInSchema/TicketOutSchema​

包含工单类型、状态、关联工件、内容等字段

参考文件: ticket_schema.py

错误处理​

系统使用标准HTTP状态码：

  • 200: 成功
  • 400: 请求参数错误
  • 401: 认证失败
  • 403: 权限不足
  • 404: 资源不存在
  • 500: 服务器内部错误

错误响应格式：

\{
  "error": "错误类型",
  "message": "错误描述", 
  "status_code": "HTTP状态码"
\}

系统架构图​

flowchart TD
    A[客户端] --> B[FastAPI应用]
    B --> C[认证中间件]
    C --> D[路由层]
    D --> E[服务层]
    E --> F[数据访问层]
    F --> G[数据库]
    
    subgraph 路由模块
        H[用户管理]
        I[权限管理]
        J[工件管理]
        K[工单管理]
        L[图片管理]
        M[统计管理]
    end
    
    D --> H
    D --> I
    D --> J
    D --> K
    D --> L
    D --> M

索引​

本API文档详细描述了邮轮穿舱件管理系统的所有接口端点，包括认证授权、用户管理、权限控制、工件管理、工单处理、图片管理等核心功能。所有接口均支持JWT认证，部分接口需要特定的权限范围才能访问。

系统采用RESTful设计原则，提供清晰的错误处理机制和完整的数据模型定义。开发者可以根据业务需求选择合适的接口进行集成开发。

参考文件汇总: