Local-Gift

sequenceDiagram
participant Client
participant API as Backend
participant DB as Database

Client->>API: POST /gifts/use<br/>{gift_id, supplier_code? OR pin?}

API->>API: Validate gift_id format

alt Invalid gift_id format
    API-->>Client: 400 Bad Request<br/>(Invalid gift ID format)
else Valid gift_id format
    alt Neither supplier_code nor PIN provided
        API-->>Client: 400 Bad Request<br/>(Either supplier_code or PIN must be provided)
    else Valid request
        API->>DB: SELECT gift FOR UPDATE<br/>(Lock row)
        DB-->>API: Gift data (locked)

        alt Gift not found
            API-->>Client: 400 Bad Request<br/>(Gift code not found)
        else Gift found
            API->>API: Validate gift status, dates

            alt Invalid status or dates
                API-->>Client: 400 Bad Request<br/>(Already used/Not valid/Expired)
            else Valid gift
                API->>DB: Get supplier_code for gift<br/>(from QRGiftSupplier by gift_code)
                DB-->>API: Gift's supplier_code

                alt Gift has no supplier
                    API-->>Client: 400 Bad Request<br/>(Gift does not belong to any supplier)
                else Check supplier_code or PIN
                    alt Case 1: supplier_code provided (Supplier App)
                        API->>API: Compare gift's supplier_code<br/>with provided supplier_code

                        alt Supplier codes don't match
                            API-->>Client: 400 Bad Request<br/>(Gift does not belong to this supplier)
                        else Supplier codes match
                            API->>API: Update gift:<br/>- gift_status = USED<br/>- gift_used_datetime = now()<br/>- updated_at = now()
                            API->>DB: UPDATE gift<br/>COMMIT transaction
                            DB-->>API: Success
                            API-->>Client: 200 OK<br/>(GiftUseResponse)
                        end
                    else Case 2: PIN provided (Enduser App)
                        API->>DB: SELECT supplier_account<br/>by PIN AND supplier_code
                        DB-->>API: SupplierAccount data

                        alt Invalid PIN or PIN doesn't match supplier
                            API-->>Client: 400 Bad Request<br/>(Invalid PIN)
                        else Valid PIN
                            API->>API: Update gift:<br/>- gift_status = USED<br/>- gift_used_datetime = now()<br/>- gift_used_supplier_account_id<br/>- updated_at = now()
                            API->>DB: UPDATE gift<br/>COMMIT transaction
                            DB-->>API: Success
                            API-->>Client: 200 OK<br/>(GiftUseResponse)
                        end
                    end
                end
            end
        end
    end
end