post:
  operationId: editStaff
  summary: Edit a staff user profile
  description: |
    Permission: **ADMIN, OWNER**

    Updates one or more profile fields of an existing staff account.
    All fields except `staff_id` and `updated_by` are optional — only
    provided fields are applied.

    **Business error codes** (returned in `EditStaffResponse.code`):
    | Code | Meaning |
    |------|---------|
    | `0`  | Success |
    | `1`  | Staff not found |
    | `2`  | Forbidden (insufficient permissions) |
    | `3`  | Phone number already exists |
    | `4`  | Email already exists |
    | `5`  | User is deactivated |
  tags: [staffManagement]
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/EditStaffRequest"
        example:
          staff_id: "6643f1a2b4c5d60012e34abc"
          first_name: "Jane"
          last_name: "Doe"
          second_last_name: "Smith"
          email: "jane.doe@nova.com"
          phone: "+5219981234567"
  responses:
    "200":
      description: Staff profile updated — DTO returned directly
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/EditStaffResponse"
          example:
            code: 0
            message: "success"
            staff_id: "6643f1a2b4c5d60012e34abc"
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"