工单接口文档

目录

• 概述
• 数据模型
• API接口
• 状态管理
• 架构设计
• 使用示例
• 注意事项

概述

工单接口是邮轮穿舱件管理系统的核心功能模块，提供了完整的工单生命周期管理功能。该系统支持检查和维护两种类型的工单，涵盖工单的创建、分配、状态更新和查询等完整业务流程。

核心功能：

• 工单的创建和初始化
• 工单状态的动态更新
• 多部门间的工单分配和流转
• 工单反馈和附件管理
• 完整的工单历史追踪

技术特性：

• RESTful API设计
• JSON数据格式
• 用户认证机制
• 完整的错误处理

参考文件：API_Doc_ticket.md

数据模型

请求数据模型 (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)

API返回的完整工单数据结构，包含系统生成的标识符和时间戳信息。

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

数据模型关系图

erDiagram
    TICKET ||--o{ TICKET_TYPE : has
    TICKET ||--o{ TICKET_STATUS : has
    TICKET ||--o{ WORKPIECE : targets
    TICKET ||--o{ DEPARTMENT : from
    TICKET ||--o{ DEPARTMENT : to
    TICKET ||--o{ USER : created_by
    TICKET ||--o{ USER : updated_by
    TICKET {
        int ticket_id PK
        string ticket_type
        string ticket_status
        int target_workpiece FK
        string ticket_from
        string ticket_tos
        string ticket_content
        string ticket_title
        string feedback_text
        string image_list
        string reference_list
        int created_by FK
        int updated_by FK
        datetime created_at
        datetime updated_at
    }
    TICKET_TYPE {
        string type_code PK
        string type_name
    }
    TICKET_STATUS {
        string status_code PK
        string status_name
    }

参考文件：API_Doc_ticket.md

API接口

1. 创建工单接口

接口定义：POST /ticket/

功能描述：创建新的工单记录，支持检查和维护两种工单类型。

请求流程：

sequenceDiagram
    participant Client
    participant API_Gateway
    participant Ticket_Service
    participant Database
    
    Client->>API_Gateway: POST /ticket/
    activate API_Gateway
    API_Gateway->>Ticket_Service: 验证并转发请求
    activate Ticket_Service
    Ticket_Service->>Database: 验证数据完整性
    Database-->>Ticket_Service: 验证结果
    Ticket_Service->>Database: 插入新工单记录
    Database-->>Ticket_Service: 返回生成的工单ID
    Ticket_Service-->>API_Gateway: 返回工单详情
    deactivate Ticket_Service
    API_Gateway-->>Client: 201 Created + 工单数据
    deactivate API_Gateway

核心参数验证逻辑：

flowchart TD
    A[接收创建请求] --> B{验证必填字段}
    B -->|缺失字段| C[返回400错误]
    B -->|字段完整| D{验证工单类型}
    D -->|类型无效| C
    D -->|类型有效| E{验证工单状态}
    E -->|状态无效| C
    E -->|状态有效| F{验证用户权限}
    F -->|权限不足| G[返回403错误]
    F -->|权限足够| H[创建工单记录]
    H --> I[返回201响应]
    C --> J[结束]
    G --> J
    I --> J

2. 工单查询接口

接口定义：GET /ticket/{ticket_id} 和 GET /ticket/all

功能描述：支持单个工单详情查询和批量工单列表查询。

查询流程架构：

flowchart TD
    subgraph 查询请求处理
        A[接收查询请求] --> B{查询类型判断}
        B -->|单个工单| C[验证工单ID]
        B -->|所有工单| D[准备批量查询]
    end
    
    subgraph 数据检索层
        C --> E[查询数据库]
        D --> F[查询工单列表]
    end
    
    subgraph 结果处理层
        E --> G{工单存在判断}
        F --> H{结果集判断}
        G -->|存在| I[返回工单详情]
        G -->|不存在| J[返回404错误]
        H -->|有数据| K[返回工单列表]
        H -->|无数据| L[返回404错误]
    end

3. 工单更新接口

接口定义：PUT /ticket/{ticket_id}

功能描述：更新工单信息，支持状态变更、反馈添加等操作。

4. 工单删除接口

接口定义：DELETE /ticket/{ticket_id}

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

参考文件：API_Doc_ticket.md

状态管理

工单状态机

工单系统采用状态机模式管理工单生命周期，支持四种核心状态和相应的状态转换。

stateDiagram-v2
    [*] --> open: 创建工单
    open --> running: 开始处理
    running --> closed: 完成处理
    running --> issue: 遇到问题
    issue --> running: 问题解决
    issue --> closed: 问题处理完成
    closed --> [*]: 工单结束
    
    note right of open
        工单已创建
        等待分配处理
    end note
    
    note right of running
        工单正在处理中
        可更新进度和反馈
    end note
    
    note right of issue
        处理过程中遇到问题
        需要特殊处理
    end note
    
    note right of closed
        工单已完成
        可查看历史记录
    end note

状态转换规则

当前状态	允许操作	目标状态	业务含义
open	start_process	running	开始处理工单
running	complete	closed	完成工单处理
running	report_issue	issue	报告处理问题
issue	resolve	running	解决问题继续处理
issue	complete	closed	直接完成问题工单

工单类型定义

classDiagram
    class TicketType {
        <<enumeration>>
        +INSPECT = "inspect"
        +MAINTENANCE = "maintenance"
    }
    
    class TicketStatus {
        <<enumeration>>
        +OPEN = "open"
        +RUNNING = "running" 
        +CLOSED = "closed"
        +ISSUE = "issue"
    }
    
    class Ticket {
        +ticket_id: int
        +ticket_type: TicketType
        +ticket_status: TicketStatus
        +validateType(): boolean
        +validateStatus(): boolean
        +canTransitionTo(newStatus): boolean
    }
    
    Ticket --> TicketType: has
    Ticket --> TicketStatus: has

参考文件：API_Doc_ticket.md

架构设计

系统组件架构

flowchart TD
    subgraph 前端层
        A[工单创建界面]
        B[工单列表界面]
        C[工单详情界面]
    end
    
    subgraph API网关层
        D[认证拦截器]
        E[请求路由]
        F[响应格式化]
    end
    
    subgraph 业务服务层
        G[工单服务]
        H[验证服务]
        I[通知服务]
    end
    
    subgraph 数据访问层
        J[工单数据模型]
        K[用户数据模型]
        L[部门数据模型]
    end
    
    subgraph 数据存储层
        M[关系数据库]
        N[文件存储]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> G
    G --> H
    G --> J
    J --> M
    G --> I
    I --> N

依赖关系分析

flowchart TD
    subgraph 核心模块
        A[TicketService]
        B[TicketValidator]
        C[TicketRepository]
    end
    
    subgraph 支持模块
        D[UserService]
        E[DepartmentService]
        F[FileService]
    end
    
    subgraph 工具模块
        G[DateUtils]
        H[StringUtils]
        I[ResponseBuilder]
    end
    
    A --> B
    A --> C
    B --> D
    B --> E
    A --> F
    A --> G
    A --> H
    A --> I
    C --> G
    C --> H

数据流架构

flowchart LR
    subgraph 输入数据流
        A[前端请求] --> B[参数验证]
        B --> C[业务逻辑处理]
    end
    
    subgraph 处理数据流
        C --> D[数据持久化]
        D --> E[关联数据处理]
    end
    
    subgraph 输出数据流
        E --> F[响应数据构建]
        F --> G[前端响应]
    end
    
    subgraph 侧边数据流
        H[通知服务] --> I[消息队列]
        I --> J[邮件/短信通知]
    end
    
    C --> H

参考文件：API_Doc_ticket.md

使用示例

完整工单生命周期示例

sequenceDiagram
    participant 生产部门 as 生产部门用户
    participant 系统 as 工单系统
    participant 维护部门 as 维护部门用户
    participant 数据库 as 数据库
    
    生产部门->>系统: 创建检查工单
    系统->>数据库: 保存工单记录(状态:open)
    数据库-->>系统: 返回工单ID
    系统-->>生产部门: 工单创建成功
    
    系统->>维护部门: 新工单通知
    维护部门->>系统: 接收工单(状态:running)
    系统->>数据库: 更新工单状态
    
    维护部门->>系统: 更新处理进度
    系统->>数据库: 保存进度信息
    
    维护部门->>系统: 完成工单处理(状态:closed)
    系统->>数据库: 更新最终状态
    系统-->>维护部门: 工单完成确认
    系统->>生产部门: 工单完成通知

前端集成代码示例

// 工单管理类
class TicketManager {
    constructor(baseUrl, authToken) {
        this.baseUrl = baseUrl;
        this.authToken = authToken;
    }

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

    // 获取工单详情
    async getTicket(ticketId) {
        const response = await fetch(`${this.baseUrl}/ticket/${ticketId}`, {
            headers: {
                'Authorization': `Bearer ${this.authToken}`
            }
        });
        
        if (!response.ok) {
            throw new Error(`获取失败: ${response.status}`);
        }
        
        return await response.json();
    }

    // 更新工单状态
    async updateTicketStatus(ticketId, newStatus, feedback = '') {
        const ticket = await this.getTicket(ticketId);
        const updateData = {
            ...ticket,
            ticket_status: newStatus,
            feedback_text: feedback,
            updated_by: this.getCurrentUserId()
        };
        
        const response = await fetch(`${this.baseUrl}/ticket/${ticketId}`, {
            method: 'PUT',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.authToken}`
            },
            body: JSON.stringify(updateData)
        });
        
        return await response.json();
    }
}

参考文件：API_Doc_ticket.md

注意事项

安全规范

1. 认证要求: 所有API调用必须包含有效的Bearer Token认证
2. 权限控制: 不同角色的用户对工单有不同的操作权限
3. 数据验证: 客户端和服务端都需要进行严格的数据验证

性能优化

1. 批量操作: 对于大量工单查询，建议使用分页机制
2. 缓存策略: 频繁访问的工单数据可以适当缓存
3. 异步处理: 邮件通知等非核心操作可以采用异步处理

错误处理

flowchart TD
    A[API调用] --> B{请求成功}
    B -->|是| C[处理正常响应]
    B -->|否| D{错误类型判断}
    D -->|400错误| E[参数验证失败]
    D -->|404错误| F[资源不存在]
    D -->|500错误| G[服务器内部错误]
    D -->|其他错误| H[网络或未知错误]
    
    E --> I[检查请求参数]
    F --> J[验证资源ID]
    G --> K[联系系统管理员]
    H --> L[重试或检查网络]
    
    I --> M[结束处理]
    J --> M
    K --> M
    L --> M
    C --> M

数据一致性

1. 状态一致性: 确保工单状态转换的逻辑一致性
2. 时间戳管理: 创建时间和更新时间由系统自动维护
3. 引用完整性: 工单相关的用户和部门引用必须有效

参考文件：API_Doc_ticket.md

索引

工单接口系统提供了完整的工单管理解决方案，具有清晰的架构设计和严格的状态管理机制。通过RESTful API设计，支持前后端分离的开发模式，便于系统集成和功能扩展。

核心价值：

• 标准化的工单业务流程
• 灵活的状态管理机制
• 完善的错误处理体系
• 良好的可扩展性设计

后续优化方向：

• 增加工单优先级管理
• 实现工单模板功能
• 添加工单统计和分析功能
• 优化大并发下的性能表现

参考文件：API_Doc_ticket.md