工单API接口规范文档

概述

工单API系统为邮轮穿舱件管理系统提供完整的工单管理功能，支持工单的创建、查询、更新和删除等核心操作。系统采用FastAPI框架构建，基于Tortoise-ORM进行数据持久化，支持检查和维护两种类型的工单管理。

系统架构

整体架构图

flowchart TD
    subgraph 前端层
        A[Web前端] --> B[移动端应用]
    end
    
    subgraph API网关层
        C[FastAPI路由] --> D[JWT认证中间件]
    end
    
    subgraph 业务逻辑层
        E[工单服务] --> F[访问日志服务]
    end
    
    subgraph 数据访问层
        G[Tortoise ORM] --> H[PostgreSQL数据库]
    end
    
    B --> C
    D --> E
    E --> G
    F --> G

组件依赖关系

flowchart TD
    A[ticket_router.py] --> B[ticket_service.py]
    B --> C[ticket.py]
    B --> D[ticket_schema.py]
    E[access_log_service.py] --> F[access_log.py]
    A --> E
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0

数据模型

工单实体模型

classDiagram
    class Ticket {
        +ticket_id: IntField (PK)
        +ticket_type: CharField
        +ticket_status: CharField
        +target_workpiece: IntField
        +ticket_from: CharField
        +ticket_tos: CharField
        +ticket_content: TextField
        +ticket_title: CharField
        +feedback_text: TextField
        +image_list: CharField
        +reference_list: CharField
        +created_by: IntField
        +updated_by: IntField
        +created_at: DatetimeField
        +updated_at: DatetimeField
    }

数据模式定义

TicketInSchema - 请求数据模型：

• 用于工单创建和更新的输入验证
• 包含工单所有可编辑字段的约束定义
• 支持工单类型和状态的枚举验证

TicketOutSchema - 响应数据模型：

• 包含工单完整信息输出
• 自动包含系统生成的字段（如ticket_id、时间戳）
• 用于API响应数据格式化

API接口规范

1. 创建工单

接口: POST /ticket/

功能描述: 创建新的工单记录

请求流程:

sequenceDiagram
    participant Client as 客户端
    participant Router as ticket_router
    participant Service as ticket_service
    participant Model as Ticket模型
    participant DB as 数据库
    
    Client->>Router: POST /ticket/
    Router->>Service: service_create_ticket()
    Service->>Model: Ticket.create()
    Model->>DB: INSERT操作
    DB-->>Model: 返回新记录
    Model-->>Service: 返回Ticket对象
    Service-->>Router: 返回TicketOutSchema
    Router-->>Client: 201 Created

请求示例:

{
  "ticket_type": "inspect",
  "ticket_status": "open",
  "target_workpiece": 123,
  "ticket_from": "生产部门",
  "ticket_tos": "维护部门",
  "ticket_content": "设备需要定期检查",
  "ticket_title": "设备检查工单",
  "created_by": 1
}

响应示例:

{
  "ticket_id": 1,
  "ticket_type": "inspect",
  "ticket_status": "open",
  "target_workpiece": 123,
  "ticket_from": "生产部门",
  "ticket_tos": "维护部门",
  "ticket_content": "设备需要定期检查",
  "ticket_title": "设备检查工单",
  "feedback_text": "",
  "image_list": "",
  "reference_list": "",
  "created_by": 1,
  "updated_by": -1,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T10:00:00Z"
}

2. 获取单个工单

接口: GET /ticket/{ticket_id}

功能描述: 根据工单ID获取工单详情

查询流程:

flowchart TD
    A[接收工单ID] --> B{ID有效性验证}
    B -->|有效| C[查询数据库]
    B -->|无效| D[返回400错误]
    C --> E{记录存在}
    E -->|存在| F[返回工单数据]
    E -->|不存在| G[返回404错误]

响应示例:

{
  "ticket_id": 1,
  "ticket_type": "inspect",
  "ticket_status": "running",
  "target_workpiece": 123,
  "ticket_from": "生产部门",
  "ticket_tos": "维护部门",
  "ticket_content": "设备需要定期检查",
  "ticket_title": "设备检查工单",
  "feedback_text": "检查进行中",
  "image_list": "check1.jpg",
  "reference_list": "",
  "created_by": 1,
  "updated_by": 2,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T11:30:00Z"
}

3. 更新工单

接口: PUT /ticket/{ticket_id}

功能描述: 更新指定工单的信息

更新状态转换:

stateDiagram-v2
    [*] --> open : 创建工单
    open --> running : 开始处理
    running --> closed : 完成处理
    running --> issue : 遇到问题
    issue --> running : 问题解决
    issue --> closed : 问题关闭
    closed --> [*] : 工单结束

请求示例:

{
  "ticket_type": "inspect",
  "ticket_status": "closed",
  "target_workpiece": 123,
  "ticket_from": "生产部门",
  "ticket_tos": "维护部门",
  "ticket_content": "设备检查已完成",
  "ticket_title": "设备检查工单",
  "feedback_text": "检查完成，设备状态良好",
  "image_list": "check1.jpg,result1.jpg",
  "reference_list": "report_001"
}

4. 删除工单

接口: DELETE /ticket/{ticket_id}

功能描述: 删除指定的工单记录

删除流程:

sequenceDiagram
    participant C as 客户端
    participant R as 路由层
    participant S as 服务层
    participant M as 模型层
    
    C->>R: DELETE /ticket/1
    R->>S: service_delete_ticket(1)
    S->>M: Ticket.filter(ticket_id=1).first()
    M-->>S: 返回工单对象
    S->>M: ticket.delete()
    M-->>S: 删除确认
    S-->>R: 操作完成
    R-->>C: 200 OK

5. 获取所有工单

接口: GET /ticketEntity/all

功能描述: 获取系统中所有工单的列表

数据流图:

flowchart LR
    A[数据库查询] --> B[数据转换]
    B --> C[格式验证]
    C --> D[响应输出]
    
    subgraph 数据处理
        E[工单记录] --> F[TicketOutSchema转换]
        F --> G[列表封装]
    end
    
    A --> E
    G --> D

响应示例:

[
  {
    "ticket_id": 1,
    "ticket_type": "inspect",
    "ticket_status": "closed",
    "target_workpiece": 123,
    "ticket_from": "生产部门",
    "ticket_tos": "维护部门",
    "ticket_content": "设备检查已完成",
    "ticket_title": "设备检查工单",
    "feedback_text": "检查完成，设备状态良好",
    "image_list": "check1.jpg,result1.jpg",
    "reference_list": "report_001",
    "created_by": 1,
    "updated_by": 2,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
]

错误处理机制

错误状态码映射

状态码	错误类型	处理逻辑
200	成功	正常返回请求数据
201	创建成功	返回新创建的工单信息
400	请求参数错误	工单类型或状态不存在
404	资源不存在	工单记录不存在
500	服务器内部错误	数据库连接或操作异常

异常处理流程

flowchart TD
    A[API请求] --> B[参数验证]
    B --> C{验证通过}
    C -->|是| D[业务处理]
    C -->|否| E[返回400错误]
    D --> F{处理成功}
    F -->|是| G[返回成功响应]
    F -->|否| H[异常捕获]
    H --> I[日志记录]
    I --> J[返回对应错误]

安全认证

JWT认证流程

sequenceDiagram
    participant C as 客户端
    participant M as 中间件
    participant R as 路由
    participant S as 服务
    
    C->>M: 请求携带Token
    M->>M: verify_jwt_token()
    M-->>C: 401未认证
    M->>R: 认证通过
    R->>S: 调用服务方法
    S-->>R: 返回业务数据
    R-->>C: 返回响应

性能优化建议

数据库查询优化

• 使用Tortoise-ORM的预加载机制减少N+1查询
• 对常用查询字段建立索引（ticket_id, ticket_status）
• 实现分页查询避免大数据量传输

缓存策略

• 对频繁访问的工单详情实现缓存
• 使用Redis缓存工单列表查询结果
• 设置合理的缓存过期时间

参考源文件

• ticket_api.md
• ticket.py
• ticket_schema.py
• ticket_router.py
• ticket_service.py

索引

工单API系统提供了完整的工单管理功能，采用清晰的分层架构设计，具有良好的可扩展性和维护性。系统通过严格的数据验证、完善的错误处理和详细的操作日志，确保了工单数据的安全性和可靠性。建议在实际使用中根据业务需求进一步完善工单状态流转规则和权限控制机制。