clqms-fe1/docs/api-docs.yaml

openapi: 3.0.3
info:
  title: CLQMS - Clinical Laboratory Quality Management System API
  description: |
    API for Clinical Laboratory Quality Management System supporting patient management,
    specimen tracking, test ordering, instrument integration, and laboratory operations.
  version: 1.0.0
  contact:
    name: CLQMS API Support
  license:
    name: Proprietary

servers:
  - url: http://localhost/clqms01/
    description: Local development server
  - url: https://clqms01-api.services-summit.my.id/
    description: Production server

tags:
  - name: Authentication
    description: User authentication and session management
  - name: Patients
    description: Patient registration and management
  - name: Patient Visits
    description: Patient visit/encounter management
  - name: Organization
    description: Organization structure (accounts, sites, disciplines, departments, workstations)
  - name: Specimen
    description: Specimen and container management
  - name: Tests
    description: Test definitions and test catalog
  - name: Orders
    description: Laboratory order management
  - name: Results
    description: Patient results reporting
  - name: Edge API
    description: Instrument integration endpoints
  - name: Master Data
    description: Lookup and reference data
  - name: ValueSets
    description: Value set definitions and items
  - name: Demo
    description: Demo/test endpoints (no authentication)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from login endpoint
    cookieAuth:
      type: apiKey
      in: cookie
      name: token
      description: JWT token stored in HTTP-only cookie

  schemas:
    # Common Schemas
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
        code:
          type: integer
          example: 200

    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
        errors:
          type: object

    # Authentication
    LoginRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          example: labuser01
        password:
          type: string
          format: password
          example: secret123

    LoginResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        code:
          type: integer
          example: 200
        message:
          type: string
          example: Login successful

    RegisterRequest:
      type: object
      required:
        - username
        - password
        - email
      properties:
        username:
          type: string
        password:
          type: string
          format: password
        email:
          type: string
          format: email
        full_name:
          type: string

    # Patient
    PatientIdentifier:
      type: object
      properties:
        IdentifierType:
          type: string
          enum: [KTP, PASS, SSN, SIM, KTAS]
          description: |
            KTP: 16 digit numeric
            PASS: alphanumeric max 9
            SSN: 9 digit numeric
            SIM: 19-20 digit numeric
            KTAS: 11 digit numeric
        Identifier:
          type: string
          maxLength: 255

    LinkedPatient:
      type: object
      description: Linked patient reference
      properties:
        InternalPID:
          type: integer
          description: Internal patient ID of the linked patient
        PatientID:
          type: string
          description: Patient ID of the linked patient

    Custodian:
      type: object
      description: Patient custodian/guardian
      properties:
        InternalPID:
          type: integer
          description: Internal patient ID of the custodian
        PatientID:
          type: string
          description: Patient ID of the custodian

    PatAttEntry:
      type: object
      description: Patient address/attorney entry
      properties:
        Address:
          type: string
          description: Address text

    Patient:
      type: object
      required:
        - PatientID
        - Sex
        - NameFirst
        - Birthdate
      properties:
        PatientID:
          type: string
          maxLength: 30
          pattern: '^[A-Za-z0-9]+$'
          description: Internal patient identifier
        AlternatePID:
          type: string
          maxLength: 30
          pattern: '^[A-Za-z0-9]+$'
        Prefix:
          type: string
          maxLength: 10
          enum: [Mr, Mrs, Ms, Dr, Prof]
        Sex:
          type: string
          enum: ['1', '2']
          description: '1: Female, 2: Male'
        NameFirst:
          type: string
          minLength: 1
          maxLength: 60
          pattern: "^[A-Za-z'\\. ]+$"
        NameMiddle:
          type: string
          minLength: 1
          maxLength: 60
        NameMaiden:
          type: string
          minLength: 1
          maxLength: 60
        NameLast:
          type: string
          minLength: 1
          maxLength: 60
        Suffix:
          type: string
          maxLength: 10
        Birthdate:
          type: string
          format: date-time
          description: ISO 8601 UTC datetime
        PlaceOfBirth:
          type: string
          maxLength: 100
        Citizenship:
          type: string
          maxLength: 100
        Street_1:
          type: string
          maxLength: 255
        Street_2:
          type: string
          maxLength: 255
        Street_3:
          type: string
          maxLength: 255
        ZIP:
          type: string
          maxLength: 10
          pattern: '^[0-9]+$'
        Phone:
          type: string
          pattern: "^\\+?[0-9]{8,15}$"
        MobilePhone:
          type: string
          pattern: "^\\+?[0-9]{8,15}$"
        EmailAddress1:
          type: string
          format: email
          maxLength: 100
        EmailAddress2:
          type: string
          format: email
          maxLength: 100
        PatIdt:
          $ref: '#/components/schemas/PatientIdentifier'
        LinkTo:
          type: array
          description: Array of linked patient references
          items:
            $ref: '#/components/schemas/LinkedPatient'
        Custodian:
          $ref: '#/components/schemas/Custodian'
        DeathIndicator:
          type: string
          enum: [Y, N]
          description: 'Y: Yes (deceased), N: No (alive)'
        TimeOfDeath:
          type: string
          format: date-time
          description: ISO 8601 UTC datetime of death
        PatCom:
          type: string
          description: Patient comment/notes
        PatAtt:
          type: array
          description: Patient address entries
          items:
            $ref: '#/components/schemas/PatAttEntry'
        Province:
          type: integer
          description: Province AreaGeoID (foreign key to areageo table)
        ProvinceLabel:
          type: string
          description: Province name (resolved from areageo)
        City:
          type: integer
          description: City AreaGeoID (foreign key to areageo table)
        CityLabel:
          type: string
          description: City name (resolved from areageo)
        Country:
          type: string
          maxLength: 10
          description: Country ISO 3-letter code (e.g., IDN, USA)
        CountryLabel:
          type: string
          description: Country name (resolved from valueset)
        Race:
          type: string
          maxLength: 100
        MaritalStatus:
          type: string
          enum: [A, B, D, M, S, W]
          description: 'A: Annulled, B: Separated, D: Divorced, M: Married, S: Single, W: Widowed'
        Religion:
          type: string
          maxLength: 100
        Ethnic:
          type: string
          maxLength: 100

    PatientListResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/Patient'
        pagination:
          type: object
          properties:
            page:
              type: integer
            perPage:
              type: integer
            total:
              type: integer

    # Patient Visit
    PatientVisit:
      type: object
      properties:
        InternalPVID:
          type: integer
          description: Primary key (auto-generated)
        PVID:
          type: string
          description: Visit ID (auto-generated with DV prefix if not provided)
        InternalPID:
          type: integer
          description: Reference to patient
        EpisodeID:
          type: string
          description: Episode identifier
        SiteID:
          type: integer
          description: Site reference
        CreateDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
        ArchivedDate:
          type: string
          format: date-time
        DelDate:
          type: string
          format: date-time
        PatDiag:
          type: object
          description: Diagnosis information (optional)
          properties:
            DiagCode:
              type: string
            Diagnosis:
              type: string
        PatVisitADT:
          type: object
          description: ADT (Admission/Discharge/Transfer) information (optional)
          properties:
            ADTCode:
              type: string
              enum: [A01, A02, A03, A04, A08]
            LocationID:
              type: integer
            AttDoc:
              type: integer
              description: Attending physician ContactID
            RefDoc:
              type: integer
              description: Referring physician ContactID
            AdmDoc:
              type: integer
              description: Admitting physician ContactID
            CnsDoc:
              type: integer
              description: Consulting physician ContactID

    # PatVisitADT (for standalone ADT operations)
    PatVisitADT:
      type: object
      properties:
        PVADTID:
          type: integer
          description: Primary key (auto-generated)
        InternalPVID:
          type: integer
          description: Reference to patient visit
        ADTCode:
          type: string
          enum: [A01, A02, A03, A04, A08]
          description: |
            A01: Admit
            A02: Transfer  
            A03: Discharge
            A04: Register
            A08: Update
        LocationID:
          type: integer
          description: Location/ward reference
        AttDoc:
          type: integer
          description: Attending physician ContactID
        RefDoc:
          type: integer
          description: Referring physician ContactID
        AdmDoc:
          type: integer
          description: Admitting physician ContactID
        CnsDoc:
          type: integer
          description: Consulting physician ContactID
        CreateDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
        ArchivedDate:
          type: string
          format: date-time
        DelDate:
          type: string
          format: date-time

    # Organization
    Account:
      type: object
      properties:
        id:
          type: integer
        AccountName:
          type: string
        AccountCode:
          type: string
        AccountType:
          type: string

    Site:
      type: object
      properties:
        id:
          type: integer
        SiteName:
          type: string
        SiteCode:
          type: string
        AccountID:
          type: integer

    Discipline:
      type: object
      properties:
        id:
          type: integer
        DisciplineName:
          type: string
        DisciplineCode:
          type: string

    Department:
      type: object
      properties:
        id:
          type: integer
        DeptName:
          type: string
        DeptCode:
          type: string
        SiteID:
          type: integer

    Workstation:
      type: object
      properties:
        id:
          type: integer
        WorkstationName:
          type: string
        WorkstationCode:
          type: string
        SiteID:
          type: integer
        DepartmentID:
          type: integer

    # Specimen
    Specimen:
      type: object
      properties:
        id:
          type: integer
        SpecimenID:
          type: string
        PatientID:
          type: string
        SpecimenType:
          type: string
          description: Specimen type code
        SpecimenTypeLabel:
          type: string
          description: Specimen type display text
        CollectionDate:
          type: string
          format: date-time
        CollectionMethod:
          type: string
          description: Collection method code
        CollectionMethodLabel:
          type: string
          description: Collection method display text
        ContainerID:
          type: integer
        SpecimenStatus:
          type: string
          description: Specimen status code
        SpecimenStatusLabel:
          type: string
          description: Specimen status display text
        BodySite:
          type: string
          description: Body site code
        BodySiteLabel:
          type: string
          description: Body site display text

    ContainerDef:
      type: object
      properties:
        id:
          type: integer
        ContainerCode:
          type: string
        ContainerName:
          type: string
        ConCategory:
          type: string
          description: Container category code
        ConCategoryLabel:
          type: string
          description: Container category display text
        ConSize:
          type: string
          description: Container size code
        ConSizeLabel:
          type: string
          description: Container size display text
        CapColor:
          type: string
          description: Cap color code
        CapColorLabel:
          type: string
          description: Cap color display text

    SpecimenPrep:
      type: object
      properties:
        id:
          type: integer
        PrepCode:
          type: string
        PrepName:
          type: string
        Description:
          type: string

    SpecimenStatus:
      type: object
      properties:
        id:
          type: integer
        StatusCode:
          type: string
        StatusName:
          type: string
        Description:
          type: string
        Status:
          type: string
          description: Status code
        StatusLabel:
          type: string
          description: Status display text
        Activity:
          type: string
          description: Activity code
        ActivityLabel:
          type: string
          description: Activity display text

    SpecimenCollection:
      type: object
      properties:
        id:
          type: integer
        CollectionCode:
          type: string
        CollectionName:
          type: string
        Description:
          type: string
        CollectionMethod:
          type: string
          description: Collection method code
        CollectionMethodLabel:
          type: string
          description: Collection method display text
        Additive:
          type: string
          description: Additive code
        AdditiveLabel:
          type: string
          description: Additive display text
        SpecimenRole:
          type: string
          description: Specimen role code
        SpecimenRoleLabel:
          type: string
          description: Specimen role display text

    # Tests
    TestDefinition:
      type: object
      properties:
        id:
          type: integer
        TestCode:
          type: string
        TestName:
          type: string
        TestType:
          type: string
          enum: [TEST, PARAM, CALC, GROUP, TITLE]
          description: |
            TEST: Technical test
            PARAM: Parameter
            CALC: Calculated
            GROUP: Panel/Profile
            TITLE: Section header
        DisciplineID:
          type: integer
        DepartmentID:
          type: integer
        SpecimenType:
          type: string
        Unit:
          type: string
        Formula:
          type: string
        refnum:
          type: array
          description: Numeric reference ranges (optional). Mutually exclusive with reftxt - a test can only have ONE reference type.
          items:
            type: object
            properties:
              RefNumID:
                type: integer
              NumRefType:
                type: string
                enum: [NMRC, THOLD]
                description: NMRC=Numeric range, THOLD=Threshold
              NumRefTypeLabel:
                type: string
              RangeType:
                type: string
              RangeTypeLabel:
                type: string
              Sex:
                type: string
              SexLabel:
                type: string
              LowSign:
                type: string
              LowSignLabel:
                type: string
              HighSign:
                type: string
              HighSignLabel:
                type: string
              High:
                type: number
                format: float
              Low:
                type: number
                format: float
              AgeStart:
                type: integer
              AgeEnd:
                type: integer
              Flag:
                type: string
              Interpretation:
                type: string
        reftxt:
          type: array
          description: Text reference ranges (optional). Mutually exclusive with refnum - a test can only have ONE reference type.
          items:
            type: object
            properties:
              RefTxtID:
                type: integer
              TxtRefType:
                type: string
                enum: [TEXT, VSET]
                description: TEXT=Free text, VSET=Value set
              TxtRefTypeLabel:
                type: string
              Sex:
                type: string
              SexLabel:
                type: string
              AgeStart:
                type: integer
              AgeEnd:
                type: integer
              RefTxt:
                type: string
              Flag:
                type: string
      examples:
        TEST_simple:
          summary: Technical test - no reference range
          value:
            id: 1
            TestCode: GLU
            TestName: Glucose
            TestType: TEST
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: mg/dL
        TEST_numeric_nmrc:
          summary: Technical test - numeric reference (NMRC)
          value:
            id: 1
            TestCode: GLU
            TestName: Glucose
            TestType: TEST
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: mg/dL
            refnum:
              - RefNumID: 1
                NumRefType: NMRC
                NumRefTypeLabel: Numeric
                RangeType: REF
                RangeTypeLabel: Reference Range
                Sex: '2'
                SexLabel: Male
                LowSign: GE
                LowSignLabel: '>=
                HighSign: LE
                HighSignLabel: '<='
                Low: 70
                High: 100
                AgeStart: 18
                AgeEnd: 99
                Flag: N
                Interpretation: Normal
        TEST_numeric_thold:
          summary: Technical test - threshold reference (THOLD)
          value:
            id: 1
            TestCode: GLU
            TestName: Glucose
            TestType: TEST
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: mg/dL
            refnum:
              - RefNumID: 2
                NumRefType: THOLD
                NumRefTypeLabel: Threshold
                RangeType: PANIC
                RangeTypeLabel: Panic Range
                Sex: '1'
                SexLabel: Female
                LowSign: LT
                LowSignLabel: '<'
                High: 40
                AgeStart: 0
                AgeEnd: 120
                Flag: L
                Interpretation: Critical Low
        TEST_text_text:
          summary: Technical test - text reference (TEXT)
          value:
            id: 1
            TestCode: RBC_MORPH
            TestName: RBC Morphology
            TestType: TEST
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: BLD
            Unit: null
            reftxt:
              - RefTxtID: 1
                TxtRefType: TEXT
                TxtRefTypeLabel: Text
                Sex: '2'
                SexLabel: Male
                AgeStart: 18
                AgeEnd: 99
                RefTxt: 'NORM=Normal;HYPO=Hypochromic;MACRO=Macrocytic'
                Flag: N
        TEST_text_vset:
          summary: Technical test - text reference (VSET)
          value:
            id: 1
            TestCode: STAGE
            TestName: Disease Stage
            TestType: TEST
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: null
            Unit: null
            reftxt:
              - RefTxtID: 2
                TxtRefType: VSET
                TxtRefTypeLabel: Value Set
                Sex: '1'
                SexLabel: Female
                AgeStart: 0
                AgeEnd: 120
                RefTxt: 'STG1=Stage 1;STG2=Stage 2;STG3=Stage 3;STG4=Stage 4'
                Flag: N
        PARAM:
          summary: Parameter - no reference range allowed
          value:
            id: 2
            TestCode: GLU_FAST
            TestName: Fasting Glucose
            TestType: PARAM
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: mg/dL
        CALC_numeric_nmrc:
          summary: Calculated test - numeric reference (NMRC)
          value:
            id: 3
            TestCode: BUN_CR_RATIO
            TestName: BUN/Creatinine Ratio
            TestType: CALC
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: null
            Formula: "BUN / Creatinine"
            refnum:
              - RefNumID: 5
                NumRefType: NMRC
                NumRefTypeLabel: Numeric
                RangeType: REF
                RangeTypeLabel: Reference Range
                Sex: '1'
                SexLabel: Female
                LowSign: GE
                LowSignLabel: '>=
                HighSign: LE
                HighSignLabel: '<='
                Low: 10
                High: 20
                AgeStart: 18
                AgeEnd: 120
                Flag: N
                Interpretation: Normal
        CALC_numeric_thold:
          summary: Calculated test - threshold reference (THOLD)
          value:
            id: 3
            TestCode: BUN_CR_RATIO
            TestName: BUN/Creatinine Ratio
            TestType: CALC
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: null
            Formula: "BUN / Creatinine"
            refnum:
              - RefNumID: 6
                NumRefType: THOLD
                NumRefTypeLabel: Threshold
                RangeType: PANIC
                RangeTypeLabel: Panic Range
                Sex: '1'
                SexLabel: Female
                LowSign: GT
                LowSignLabel: '>'
                Low: 20
                AgeStart: 18
                AgeEnd: 120
                Flag: H
                Interpretation: Elevated - possible prerenal cause

        GROUP:
          summary: Panel/Profile - no reference range allowed
          value:
            id: 4
            TestCode: LIPID
            TestName: Lipid Panel
            TestType: GROUP
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: SER
            Unit: null
        TITLE:
          summary: Section header - no reference range allowed
          value:
            id: 5
            TestCode: CHEM_HEADER
            TestName: '--- CHEMISTRY ---'
            TestType: TITLE
            DisciplineID: 1
            DepartmentID: 1
            SpecimenType: null
            Unit: null

    TestMap:
      type: object
      properties:
        id:
          type: integer
        TestMapID:
          type: integer
        TestCode:
          type: string
        HostCode:
          type: string
        HostName:
          type: string
        ClientCode:
          type: string
        ClientName:
          type: string
        HostType:
          type: string
          description: Host type code
        HostTypeLabel:
          type: string
          description: Host type display text
        ClientType:
          type: string
          description: Client type code
        ClientTypeLabel:
          type: string
          description: Client type display text

    # Orders
    OrderTest:
      type: object
      properties:
        OrderID:
          type: string
        PatientID:
          type: string
        VisitID:
          type: string
        OrderDate:
          type: string
          format: date-time
        OrderStatus:
          type: string
          enum: [ORD, SCH, ANA, VER, REV, REP]
          description: |
            ORD: Ordered
            SCH: Scheduled
            ANA: Analysis
            VER: Verified
            REV: Reviewed
            REP: Reported
        OrderStatusLabel:
          type: string
          description: Order status display text
        Priority:
          type: string
          enum: [R, S, U]
          description: |
            R: Routine
            S: Stat
            U: Urgent
        PriorityLabel:
          type: string
          description: Priority display text
        SiteID:
          type: integer
        RequestingPhysician:
          type: string

    OrderItem:
      type: object
      properties:
        id:
          type: integer
        OrderID:
          type: string
        TestID:
          type: integer
        SpecimenID:
          type: string
        Status:
          type: string

    # Edge API
    EdgeResultRequest:
      type: object
      required:
        - sample_id
        - instrument_id
      properties:
        sample_id:
          type: string
          description: Sample barcode/identifier
        instrument_id:
          type: string
          description: Instrument identifier
        patient_id:
          type: string
          description: Patient identifier (optional)
        results:
          type: array
          items:
            type: object
            properties:
              test_code:
                type: string
              result_value:
                type: string
              unit:
                type: string
              flags:
                type: string
                enum: [H, L, N, A]
                description: H=High, L=Low, N=Normal, A=Abnormal

    EdgeResultResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Result received and queued
        data:
          type: object
          properties:
            edge_res_id:
              type: integer
            sample_id:
              type: string
            instrument_id:
              type: string

    EdgeOrder:
      type: object
      properties:
        OrderID:
          type: string
        PatientID:
          type: string
        SampleID:
          type: string
        Tests:
          type: array
          items:
            type: object
            properties:
              TestCode:
                type: string
              TestName:
                type: string
              SpecimenType:
                type: string
        Priority:
          type: string
        DueDateTime:
          type: string
          format: date-time

    # ValueSets
    ValueSetLibItem:
      type: object
      description: Library/system value set item from JSON files
      properties:
        value:
          type: string
          description: The value/key code
        label:
          type: string
          description: The display label

    ValueSetDef:
      type: object
      description: User-defined value set definition (from database)
      properties:
        VSetID:
          type: integer
          description: Primary key
        SiteID:
          type: integer
          description: Site reference
        VSName:
          type: string
          description: Value set name
        VSDesc:
          type: string
          description: Value set description
        CreateDate:
          type: string
          format: date-time
          description: Creation timestamp
        EndDate:
          type: string
          format: date-time
          nullable: true
          description: Soft delete timestamp
        ItemCount:
          type: integer
          description: Number of items in this value set

    ValueSetItem:
      type: object
      description: User-defined value set item (from database)
      properties:
        VID:
          type: integer
          description: Primary key
        SiteID:
          type: integer
          description: Site reference
        VSetID:
          type: integer
          description: Reference to value set definition
        VOrder:
          type: integer
          description: Display order
        VValue:
          type: string
          description: The value code
        VDesc:
          type: string
          description: The display description/label
        VCategory:
          type: string
          description: Category code
        CreateDate:
          type: string
          format: date-time
          description: Creation timestamp
        EndDate:
          type: string
          format: date-time
          nullable: true
          description: Soft delete timestamp
        VSName:
          type: string
          description: Value set name (from joined definition)

    # Master Data
    Location:
      type: object
      properties:
        LocationID:
          type: integer
          description: Primary key
        SiteID:
          type: integer
          description: Reference to site
        LocCode:
          type: string
          maxLength: 6
          description: Location code (short identifier)
        Parent:
          type: integer
          nullable: true
          description: Parent location ID for hierarchical locations
        LocFull:
          type: string
          maxLength: 255
          description: Full location name
        Description:
          type: string
          maxLength: 255
          description: Location description
        LocType:
          type: string
          description: Location type code (e.g., ROOM, WARD, BUILDING)
        CreateDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
          nullable: true

    Contact:
      type: object
      properties:
        ContactID:
          type: integer
          description: Primary key
        NameFirst:
          type: string
          description: First name (required)
        NameLast:
          type: string
          description: Last name
        Title:
          type: string
          description: Title (e.g., Dr, Mr, Mrs)
        Initial:
          type: string
          description: Middle initial
        Birthdate:
          type: string
          format: date-time
          description: Date of birth
        EmailAddress1:
          type: string
          format: email
          description: Primary email address
        EmailAddress2:
          type: string
          format: email
          description: Secondary email address
        Phone:
          type: string
          description: Primary phone number
        MobilePhone1:
          type: string
          description: Primary mobile number
        MobilePhone2:
          type: string
          description: Secondary mobile number
        Specialty:
          type: string
          description: Medical specialty code
        SubSpecialty:
          type: string
          description: Sub-specialty code
        CreateDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
          description: Occupation display text

    Occupation:
      type: object
      properties:
        OccupationID:
          type: integer
          description: Primary key
        OccCode:
          type: string
          description: Occupation code
        OccText:
          type: string
          description: Occupation name/text
        Description:
          type: string
          description: Additional description
        CreateDate:
          type: string
          format: date-time

    MedicalSpecialty:
      type: object
      properties:
        SpecialtyID:
          type: integer
          description: Primary key
        SpecialtyText:
          type: string
          description: Specialty name/text
        Parent:
          type: integer
          description: Parent specialty ID for hierarchical structure
        Title:
          type: string
          description: Title/abbreviation
        CreateDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time

    Counter:
      type: object
      properties:
        CounterID:
          type: integer
          description: Primary key
        CounterDesc:
          type: string
          description: Counter description/name
        CounterValue:
          type: integer
          description: Current counter value
        CounterStart:
          type: integer
          description: Starting value for the counter
        CounterEnd:
          type: integer
          description: Ending value (for auto-reset)
        CounterReset:
          type: string
          description: Reset pattern (e.g., D=Daily, M=Monthly, Y=Yearly)
        CreateDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time

    # Dashboard
    DashboardSummary:
      type: object
      properties:
        pendingOrders:
          type: integer
        todayResults:
          type: integer
        criticalResults:
          type: integer
        activePatients:
          type: integer

paths:
  # ========================================
  # Authentication Routes
  # ========================================
  /api/auth/login:
    post:
      tags: [Authentication]
      summary: User login
      description: Authenticate user and receive JWT token via HTTP-only cookie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          headers:
            Set-Cookie:
              description: JWT token in HTTP-only cookie
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          description: Missing username
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/logout:
    post:
      tags: [Authentication]
      summary: User logout
      description: Clear JWT token cookie
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/auth/check:
    get:
      tags: [Authentication]
      summary: Check authentication status
      security:
        - bearerAuth: []
        - cookieAuth: []
      responses:
        '200':
          description: Authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated:
                    type: boolean
                  user:
                    type: object
        '401':
          description: Not authenticated

  /api/auth/register:
    post:
      tags: [Authentication]
      summary: Register new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/auth/change_pass:
    post:
      tags: [Authentication]
      summary: Change password
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - current_password
                - new_password
              properties:
                current_password:
                  type: string
                  format: password
                new_password:
                  type: string
                  format: password
      responses:
        '200':
          description: Password changed successfully

  # ========================================
  # V2 Authentication Routes
  # ========================================
  /v2/auth/login:
    post:
      tags: [Authentication]
      summary: V2 User login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'

  /v2/auth/logout:
    post:
      tags: [Authentication]
      summary: V2 User logout
      responses:
        '200':
          description: Logout successful

  /v2/auth/check:
    get:
      tags: [Authentication]
      summary: V2 Check authentication
      responses:
        '200':
          description: Auth check result

  /v2/auth/register:
    post:
      tags: [Authentication]
      summary: V2 Register new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User created

  # ========================================
  # Patient Routes
  # ========================================
  /api/patient:
    get:
      tags: [Patients]
      summary: List patients
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: perPage
          in: query
          schema:
            type: integer
            default: 20
        - name: InternalPID
          in: query
          schema:
            type: integer
          description: Filter by internal patient ID
        - name: PatientID
          in: query
          schema:
            type: string
          description: Filter by patient ID
        - name: Name
          in: query
          schema:
            type: string
          description: Search by patient name
        - name: Birthdate
          in: query
          schema:
            type: string
            format: date
          description: Filter by birthdate (YYYY-MM-DD)
      responses:
        '200':
          description: List of patients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientListResponse'

    post:
      tags: [Patients]
      summary: Create new patient
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '201':
          description: Patient created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    patch:
      tags: [Patients]
      summary: Update patient
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '200':
          description: Patient updated successfully

    delete:
      tags: [Patients]
      summary: Delete patient (soft delete)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - InternalPID
              properties:
                InternalPID:
                  type: integer
                  description: Internal patient record ID
      responses:
        '200':
          description: Patient deleted successfully

  /api/patient/check:
    get:
      tags: [Patients]
      summary: Check if patient exists
      security:
        - bearerAuth: []
      parameters:
        - name: PatientID
          in: query
          schema:
            type: string
          description: Patient ID to check
        - name: EmailAddress1
          in: query
          schema:
            type: string
            format: email
          description: Email address to check
      responses:
        '200':
          description: Patient check result
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Patient'

  /api/patient/{id}:
    get:
      tags: [Patients]
      summary: Get patient by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Internal patient record ID
      responses:
        '200':
          description: Patient details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    $ref: '#/components/schemas/Patient'

  # ========================================
  # Patient Visit Routes
  # ========================================
  /api/patvisit:
    get:
      tags: [Patient Visits]
      summary: List patient visits
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: perPage
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of patient visits
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PatientVisit'
                  total:
                    type: integer
                    description: Total number of records
                  page:
                    type: integer
                    description: Current page number
                  per_page:
                    type: integer
                    description: Number of records per page

    post:
      tags: [Patient Visits]
      summary: Create patient visit
      description: |
        Creates a new patient visit. PVID is auto-generated with 'DV' prefix if not provided.
        Can optionally include PatDiag (diagnosis) and PatVisitADT (ADT information).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - InternalPID
              properties:
                PVID:
                  type: string
                  description: Visit ID (auto-generated with DV prefix if not provided)
                InternalPID:
                  type: integer
                  description: Patient ID (required)
                EpisodeID:
                  type: string
                  description: Episode identifier
                SiteID:
                  type: integer
                  description: Site reference
                PatDiag:
                  type: object
                  description: Optional diagnosis information
                  properties:
                    DiagCode:
                      type: string
                    Diagnosis:
                      type: string
                PatVisitADT:
                  type: object
                  description: Optional ADT information
                  properties:
                    ADTCode:
                      type: string
                      enum: [A01, A02, A03, A04, A08]
                    LocationID:
                      type: integer
                    AttDoc:
                      type: integer
                    RefDoc:
                      type: integer
                    AdmDoc:
                      type: integer
                    CnsDoc:
                      type: integer
      responses:
        '201':
          description: Visit created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      PVID:
                        type: string
                      InternalPVID:
                        type: integer

    patch:
      tags: [Patient Visits]
      summary: Update patient visit
      description: |
        Updates an existing patient visit. InternalPVID is required.
        Can update main visit data, PatDiag, and add new PatVisitADT records.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - InternalPVID
              properties:
                InternalPVID:
                  type: integer
                  description: Visit ID (required)
                PVID:
                  type: string
                InternalPID:
                  type: integer
                EpisodeID:
                  type: string
                SiteID:
                  type: integer
                PatDiag:
                  type: object
                  description: Diagnosis information (will update if exists)
                  properties:
                    DiagCode:
                      type: string
                    Diagnosis:
                      type: string
                PatVisitADT:
                  type: array
                  description: Array of ADT records to add (new records only)
                  items:
                    type: object
                    properties:
                      ADTCode:
                        type: string
                        enum: [A01, A02, A03, A04, A08]
                      LocationID:
                        type: integer
                      AttDoc:
                        type: integer
                      RefDoc:
                        type: integer
                      AdmDoc:
                        type: integer
                      CnsDoc:
                        type: integer
                      sequence:
                        type: integer
                        description: Used for ordering multiple ADT records
      responses:
        '200':
          description: Visit updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      PVID:
                        type: string
                      InternalPVID:
                        type: integer

    delete:
      tags: [Patient Visits]
      summary: Delete patient visit
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Visit deleted successfully

  /api/patvisit/{id}:
    get:
      tags: [Patient Visits]
      summary: Get visit by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: PVID (visit identifier like DV00001)
      responses:
        '200':
          description: Visit details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/PatientVisit'

  /api/patvisit/patient/{patientId}:
    get:
      tags: [Patient Visits]
      summary: Get visits by patient ID
      security:
        - bearerAuth: []
      parameters:
        - name: patientId
          in: path
          required: true
          schema:
            type: integer
          description: Internal Patient ID (InternalPID)
      responses:
        '200':
          description: Patient visits list
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PatientVisit'

  /api/patvisitadt/visit/{visitId}:
    get:
      tags: [Patient Visits]
      summary: Get ADT history by visit ID
      description: Retrieve the complete Admission/Discharge/Transfer history for a visit, including all locations and doctors
      security:
        - bearerAuth: []
      parameters:
        - name: visitId
          in: path
          required: true
          schema:
            type: integer
          description: Internal Visit ID (InternalPVID)
      responses:
        '200':
          description: ADT history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: ADT history retrieved
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        PVADTID:
                          type: integer
                        InternalPVID:
                          type: integer
                        ADTCode:
                          type: string
                          enum: [A01, A02, A03, A04, A08]
                        LocationID:
                          type: integer
                        LocationName:
                          type: string
                        AttDoc:
                          type: integer
                        AttDocFirstName:
                          type: string
                        AttDocLastName:
                          type: string
                        RefDoc:
                          type: integer
                        RefDocFirstName:
                          type: string
                        RefDocLastName:
                          type: string
                        AdmDoc:
                          type: integer
                        AdmDocFirstName:
                          type: string
                        AdmDocLastName:
                          type: string
                        CnsDoc:
                          type: integer
                        CnsDocFirstName:
                          type: string
                        CnsDocLastName:
                          type: string
                        CreateDate:
                          type: string
                          format: date-time
                        EndDate:
                          type: string
                          format: date-time

$1
    delete:
      tags: [Patient Visits]
      summary: Delete ADT visit (soft delete)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - PVADTID
              properties:
                PVADTID:
                  type: integer
                  description: ADT record ID to delete
      responses:
        '200':
          description: ADT visit deleted successfully

  /api/patvisitadt/{id}:
    get:
      tags: [Patient Visits]
      summary: Get ADT record by ID
      description: Retrieve a single ADT record by its ID, including location and doctor details
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: ADT record ID (PVADTID)
      responses:
        '200':
          description: ADT record retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: ADT record retrieved
                  data:
                    type: object
                    properties:
                      PVADTID:
                        type: integer
                      InternalPVID:
                        type: integer
                      ADTCode:
                        type: string
                        enum: [A01, A02, A03, A04, A08]
                      LocationID:
                        type: integer
                      LocationName:
                        type: string
                      AttDoc:
                        type: integer
                      AttDocFirstName:
                        type: string
                      AttDocLastName:
                        type: string
                      RefDoc:
                        type: integer
                      RefDocFirstName:
                        type: string
                      RefDocLastName:
                        type: string
                      AdmDoc:
                        type: integer
                      AdmDocFirstName:
                        type: string
                      AdmDocLastName:
                        type: string
                      CnsDoc:
                        type: integer
                      CnsDocFirstName:
                        type: string
                      CnsDocLastName:
                        type: string
                      CreateDate:
                        type: string
                        format: date-time
                      EndDate:
                        type: string
                        format: date-time

$2/account/{id}:
    get:
      tags: [Organization]
      summary: Get account by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Account details

  # ========================================
  # Organization - Site Routes
  # ========================================
  /api/organization/site:
    get:
      tags: [Organization]
      summary: List sites
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of sites

    post:
      tags: [Organization]
      summary: Create site
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Site'
      responses:
        '201':
          description: Site created

    patch:
      tags: [Organization]
      summary: Update site
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                SiteName:
                  type: string
                SiteCode:
                  type: string
                AccountID:
                  type: integer
      responses:
        '200':
          description: Site updated

    delete:
      tags: [Organization]
      summary: Delete site
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Site deleted

  /api/organization/site/{id}:
    get:
      tags: [Organization]
      summary: Get site by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Site details

  # ========================================
  # Organization - Discipline Routes
  # ========================================
  /api/organization/discipline:
    get:
      tags: [Organization]
      summary: List disciplines
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of disciplines

    post:
      tags: [Organization]
      summary: Create discipline
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Discipline'
      responses:
        '201':
          description: Discipline created

    patch:
      tags: [Organization]
      summary: Update discipline
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                DisciplineName:
                  type: string
                DisciplineCode:
                  type: string
      responses:
        '200':
          description: Discipline updated

    delete:
      tags: [Organization]
      summary: Delete discipline
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Discipline deleted

  /api/organization/discipline/{id}:
    get:
      tags: [Organization]
      summary: Get discipline by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Discipline details

  # ========================================
  # Organization - Department Routes
  # ========================================
  /api/organization/department:
    get:
      tags: [Organization]
      summary: List departments
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of departments

    post:
      tags: [Organization]
      summary: Create department
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Department'
      responses:
        '201':
          description: Department created

    patch:
      tags: [Organization]
      summary: Update department
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                DeptName:
                  type: string
                DeptCode:
                  type: string
                SiteID:
                  type: integer
      responses:
        '200':
          description: Department updated

    delete:
      tags: [Organization]
      summary: Delete department
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Department deleted

  /api/organization/department/{id}:
    get:
      tags: [Organization]
      summary: Get department by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Department details

  # ========================================
  # Organization - Workstation Routes
  # ========================================
  /api/organization/workstation:
    get:
      tags: [Organization]
      summary: List workstations
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of workstations

    post:
      tags: [Organization]
      summary: Create workstation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workstation'
      responses:
        '201':
          description: Workstation created

    patch:
      tags: [Organization]
      summary: Update workstation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                WorkstationName:
                  type: string
                WorkstationCode:
                  type: string
                SiteID:
                  type: integer
                DepartmentID:
                  type: integer
      responses:
        '200':
          description: Workstation updated

    delete:
      tags: [Organization]
      summary: Delete workstation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Workstation deleted

  /api/organization/workstation/{id}:
    get:
      tags: [Organization]
      summary: Get workstation by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Workstation details

  # ========================================
  # Specimen Routes
  # ========================================
  /api/specimen:
    get:
      tags: [Specimen]
      summary: List specimens
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of specimens

    post:
      tags: [Specimen]
      summary: Create specimen
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Specimen'
      responses:
        '201':
          description: Specimen created

    patch:
      tags: [Specimen]
      summary: Update specimen
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Specimen'
      responses:
        '200':
          description: Specimen updated

  /api/specimen/{id}:
    get:
      tags: [Specimen]
      summary: Get specimen by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Specimen details

  /api/specimen/container:
    get:
      tags: [Specimen]
      summary: List container definitions
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of container definitions

    post:
      tags: [Specimen]
      summary: Create container definition
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContainerDef'
      responses:
        '201':
          description: Container definition created

    patch:
      tags: [Specimen]
      summary: Update container definition
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Container definition updated

  /api/specimen/container/{id}:
    get:
      tags: [Specimen]
      summary: Get container definition by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Container definition details

  # ContainerDef aliases (same as /api/specimen/container)
  /api/specimen/containerdef:
    get:
      tags: [Specimen]
      summary: List container definitions (alias)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of container definitions

    post:
      tags: [Specimen]
      summary: Create container definition (alias)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContainerDef'
      responses:
        '201':
          description: Container definition created

    patch:
      tags: [Specimen]
      summary: Update container definition (alias)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Container definition updated

  /api/specimen/prep:
    get:
      tags: [Specimen]
      summary: List specimen preparations
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of specimen preparations

    post:
      tags: [Specimen]
      summary: Create specimen preparation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecimenPrep'
      responses:
        '201':
          description: Specimen preparation created

    patch:
      tags: [Specimen]
      summary: Update specimen preparation
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Specimen preparation updated

  /api/specimen/prep/{id}:
    get:
      tags: [Specimen]
      summary: Get specimen preparation by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Specimen preparation details

  /api/specimen/status:
    get:
      tags: [Specimen]
      summary: List specimen statuses
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of specimen statuses

    post:
      tags: [Specimen]
      summary: Create specimen status
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecimenStatus'
      responses:
        '201':
          description: Specimen status created

    patch:
      tags: [Specimen]
      summary: Update specimen status
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Specimen status updated

  /api/specimen/status/{id}:
    get:
      tags: [Specimen]
      summary: Get specimen status by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Specimen status details

  /api/specimen/collection:
    get:
      tags: [Specimen]
      summary: List specimen collection methods
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of collection methods

    post:
      tags: [Specimen]
      summary: Create specimen collection method
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecimenCollection'
      responses:
        '201':
          description: Collection method created

    patch:
      tags: [Specimen]
      summary: Update specimen collection method
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Collection method updated

  /api/specimen/collection/{id}:
    get:
      tags: [Specimen]
      summary: Get specimen collection method by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Collection method details

  # ========================================
  # Tests Routes
  # ========================================
  /api/tests:
    get:
      tags: [Tests]
      summary: List test definitions
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: perPage
          in: query
          schema:
            type: integer
        - name: SiteID
          in: query
          schema:
            type: integer
          description: Filter by site ID
        - name: TestType
          in: query
          schema:
            type: string
            enum: [TEST, PARAM, CALC, GROUP, TITLE]
          description: Filter by test type
        - name: VisibleScr
          in: query
          schema:
            type: integer
            enum: [0, 1]
          description: Filter by screen visibility (0=hidden, 1=visible)
        - name: VisibleRpt
          in: query
          schema:
            type: integer
            enum: [0, 1]
          description: Filter by report visibility (0=hidden, 1=visible)
        - name: TestSiteName
          in: query
          schema:
            type: string
          description: Search by test name or code
      responses:
        '200':
          description: List of test definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TestDefinition'

    post:
      tags: [Tests]
      summary: Create test definition
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestDefinition'
      responses:
        '201':
          description: Test definition created

    patch:
      tags: [Tests]
      summary: Update test definition
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestDefinition'
      responses:
        '200':
          description: Test definition updated

  /api/tests/{id}:
    get:
      tags: [Tests]
      summary: Get test definition by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Test definition details

  # ========================================
  # Orders Routes
  # ========================================
  /api/ordertest:
    get:
      tags: [Orders]
      summary: List orders
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: perPage
          in: query
          schema:
            type: integer
        - name: InternalPID
          in: query
          schema:
            type: integer
          description: Filter by internal patient ID
        - name: OrderStatus
          in: query
          schema:
            type: string
            enum: [ORD, SCH, ANA, VER, REV, REP]
          description: |
            ORD: Ordered
            SCH: Scheduled
            ANA: Analysis
            VER: Verified
            REV: Reviewed
            REP: Reported
      responses:
        '200':
          description: List of orders

    post:
      tags: [Orders]
      summary: Create order
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - PatientID
                - Tests
              properties:
                PatientID:
                  type: string
                VisitID:
                  type: string
                Priority:
                  type: string
                  enum: [R, S, U]
                  description: |
                    R: Routine
                    S: Stat
                    U: Urgent
                SiteID:
                  type: integer
                RequestingPhysician:
                  type: string
                Tests:
                  type: array
                  items:
                    type: object
                    properties:
                      TestID:
                        type: integer
                      SpecimenType:
                        type: string
      responses:
        '201':
          description: Order created successfully

    patch:
      tags: [Orders]
      summary: Update order
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderTest'
      responses:
        '200':
          description: Order updated

    delete:
      tags: [Orders]
      summary: Delete order
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Order deleted

  /api/ordertest/status:
    post:
      tags: [Orders]
      summary: Update order status
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - OrderID
                - OrderStatus
              properties:
                OrderID:
                  type: string
                OrderStatus:
                  type: string
                  enum: [ORD, SCH, ANA, VER, REV, REP]
                  description: |
                    ORD: Ordered
                    SCH: Scheduled
                    ANA: Analysis
                    VER: Verified
                    REV: Reviewed
                    REP: Reported
      responses:
        '200':
          description: Order status updated

  /api/ordertest/{id}:
    get:
      tags: [Orders]
      summary: Get order by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order details

  # ========================================
  # Edge API Routes
  # ========================================
  /api/edge/results:
    post:
      tags: [Edge API]
      summary: Receive results from instrument (tiny-edge)
      description: |
        Receives instrument results and stores them in the edgeres table for processing.
        This endpoint is typically called by the tiny-edge middleware connected to laboratory analyzers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EdgeResultRequest'
      responses:
        '201':
          description: Result received and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeResultResponse'
        '400':
          description: Invalid JSON payload

  /api/edge/orders:
    get:
      tags: [Edge API]
      summary: Fetch pending orders for instruments
      description: Returns orders that need to be sent to laboratory instruments for testing
      parameters:
        - name: instrument_id
          in: query
          schema:
            type: string
          description: Filter by instrument
        - name: status
          in: query
          schema:
            type: string
          enum: [pending, acknowledged]
          description: Filter by status
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EdgeOrder'

  /api/edge/orders/{orderId}/ack:
    post:
      tags: [Edge API]
      summary: Acknowledge order delivery
      description: Mark order as acknowledged by the instrument
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
          description: Edge order ID
      responses:
        '200':
          description: Order acknowledged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/edge/status:
    post:
      tags: [Edge API]
      summary: Log instrument status update
      description: Receive status updates from laboratory instruments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - instrument_id
                - status
              properties:
                instrument_id:
                  type: string
                status:
                  type: string
                  enum: [online, offline, error, maintenance]
                message:
                  type: string
                timestamp:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Status logged

  # ========================================
  # ValueSet Routes
  # ========================================
  /api/valueset:
    get:
      tags: [ValueSets]
      summary: List lib value sets
      description: List all library/system value sets from JSON files with item counts. Returns an object where keys are value set names and values are item counts.
      security:
        - bearerAuth: []
      parameters:
        - name: search
          in: query
          schema:
            type: string
          description: Optional search term to filter value set names
      responses:
        '200':
          description: List of lib value sets with item counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    additionalProperties:
                      type: integer
                      description: Number of items in each value set
                    example:
                      sex: 3
                      marital_status: 6
                      order_status: 6

  /api/valueset/{key}:
    get:
      tags: [ValueSets]
      summary: Get lib value set by key
      description: |
        Get a specific library/system value set from JSON files.
        
        **Available value set keys:**
        - `activity_result` - Activity Result
        - `additive` - Additive
        - `adt_event` - ADT Event
        - `area_class` - Area Class
        - `body_site` - Body Site
        - `collection_method` - Collection Method
        - `container_cap_color` - Container Cap Color
        - `container_class` - Container Class
        - `container_size` - Container Size
        - `country` - Country
        - `death_indicator` - Death Indicator
        - `did_type` - DID Type
        - `enable_disable` - Enable/Disable
        - `entity_type` - Entity Type
        - `ethnic` - Ethnic
        - `fasting_status` - Fasting Status
        - `formula_language` - Formula Language
        - `generate_by` - Generate By
        - `identifier_type` - Identifier Type
        - `location_type` - Location Type
        - `marital_status` - Marital Status
        - `math_sign` - Math Sign
        - `numeric_ref_type` - Numeric Reference Type
        - `operation` - Operation (CRUD)
        - `order_priority` - Order Priority
        - `order_status` - Order Status
        - `race` - Race (Ethnicity)
        - `range_type` - Range Type
        - `reference_type` - Reference Type
        - `religion` - Religion
        - `requested_entity` - Requested Entity
        - `result_type` - Result Type
        - `result_unit` - Result Unit
        - `sex` - Sex
        - `site_class` - Site Class
        - `site_type` - Site Type
        - `specimen_activity` - Specimen Activity
        - `specimen_condition` - Specimen Condition
        - `specimen_role` - Specimen Role
        - `specimen_status` - Specimen Status
        - `specimen_type` - Specimen Type
        - `test_activity` - Test Activity
        - `test_type` - Test Type
        - `text_ref_type` - Text Reference Type
        - `unit` - Unit
        - `v_category` - VCategory
        - `ws_type` - Workstation Type
      security:
        - bearerAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
            enum: [activity_result, additive, adt_event, area_class, body_site, collection_method, container_cap_color, container_class, container_size, country, death_indicator, did_type, enable_disable, entity_type, ethnic, fasting_status, formula_language, generate_by, identifier_type, location_type, marital_status, math_sign, numeric_ref_type, operation, order_priority, order_status, race, range_type, reference_type, religion, requested_entity, result_type, result_unit, sex, site_class, site_type, specimen_activity, specimen_condition, specimen_role, specimen_status, specimen_type, test_activity, test_type, text_ref_type, unit, v_category, ws_type]
          description: Value set key name
      responses:
        '200':
          description: Lib value set details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValueSetLibItem'

  /api/valueset/refresh:
    post:
      tags: [ValueSets]
      summary: Refresh lib ValueSet cache
      description: Clear and reload the library/system ValueSet cache from JSON files. Call this after modifying JSON files in app/Libraries/Data/.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lib ValueSet cache refreshed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Cache cleared

  /api/valueset/user/items:
    get:
      tags: [ValueSets]
      summary: List user value set items
      description: List value set items from database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: VSetID
          in: query
          schema:
            type: integer
          description: Filter by ValueSet ID
        - name: search
          in: query
          schema:
            type: string
          description: Search term to filter by VValue, VDesc, or VSName
        - name: param
          in: query
          schema:
            type: string
          description: Alternative search parameter (alias for search)
      responses:
        '200':
          description: List of user value set items
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValueSetItem'

    post:
      tags: [ValueSets]
      summary: Create user value set item
      description: Create value set item in database (user-defined)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - VSetID
              properties:
                SiteID:
                  type: integer
                  description: Site reference (default 1)
                VSetID:
                  type: integer
                  description: Reference to value set definition (required)
                VOrder:
                  type: integer
                  description: Display order (default 0)
                VValue:
                  type: string
                  description: The value code
                VDesc:
                  type: string
                  description: The display description/label
      responses:
        '201':
          description: User value set item created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ValueSetItem'

  /api/valueset/user/items/{id}:
    get:
      tags: [ValueSets]
      summary: Get user value set item by ID
      description: Get value set item from database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User value set item details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    $ref: '#/components/schemas/ValueSetItem'

    put:
      tags: [ValueSets]
      summary: Update user value set item
      description: Update value set item in database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                SiteID:
                  type: integer
                  description: Site reference
                VSetID:
                  type: integer
                  description: Reference to value set definition
                VOrder:
                  type: integer
                  description: Display order
                VValue:
                  type: string
                  description: The value code
                VDesc:
                  type: string
                  description: The display description/label
      responses:
        '200':
          description: User value set item updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ValueSetItem'

    delete:
      tags: [ValueSets]
      summary: Delete user value set item
      description: Delete value set item from database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User value set item deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string

  /api/valueset/user/def:
    get:
      tags: [ValueSets]
      summary: List user value set definitions
      description: List value set definitions from database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: search
          in: query
          schema:
            type: string
          description: Optional search term to filter definitions
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: Number of items per page
      responses:
        '200':
          description: List of user value set definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValueSetDef'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer

    post:
      tags: [ValueSets]
      summary: Create user value set definition
      description: Create value set definition in database (user-defined)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                SiteID:
                  type: integer
                  description: Site reference (default 1)
                VSName:
                  type: string
                  description: Value set name
                VSDesc:
                  type: string
                  description: Value set description
      responses:
        '201':
          description: User value set definition created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ValueSetDef'

  /api/valueset/user/def/{id}:
    get:
      tags: [ValueSets]
      summary: Get user value set definition by ID
      description: Get value set definition from database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User value set definition details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    $ref: '#/components/schemas/ValueSetDef'

    put:
      tags: [ValueSets]
      summary: Update user value set definition
      description: Update value set definition in database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                SiteID:
                  type: integer
                  description: Site reference
                VSName:
                  type: string
                  description: Value set name
                VSDesc:
                  type: string
                  description: Value set description
      responses:
        '200':
          description: User value set definition updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ValueSetDef'

    delete:
      tags: [ValueSets]
      summary: Delete user value set definition
      description: Delete value set definition from database (user-defined)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User value set definition deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string

  # ========================================
  # Master Data Routes
  # ========================================
  /api/location:
    get:
      tags: [Master Data]
      summary: List locations
      security:
        - bearerAuth: []
      parameters:
        - name: LocCode
          in: query
          schema:
            type: string
          description: Filter by location code
        - name: LocName
          in: query
          schema:
            type: string
          description: Filter by location name (searches in LocFull)
      responses:
        '200':
          description: List of locations
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'

    post:
      tags: [Master Data]
      summary: Create location
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - LocCode
                - LocFull
              properties:
                SiteID:
                  type: integer
                LocCode:
                  type: string
                  maxLength: 6
                Parent:
                  type: integer
                LocFull:
                  type: string
                  maxLength: 255
                Description:
                  type: string
                  maxLength: 255
                LocType:
                  type: string
      responses:
        '201':
          description: Location created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: object

    patch:
      tags: [Master Data]
      summary: Update location
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - LocCode
                - LocFull
              properties:
                LocationID:
                  type: integer
                SiteID:
                  type: integer
                LocCode:
                  type: string
                  maxLength: 6
                Parent:
                  type: integer
                LocFull:
                  type: string
                  maxLength: 255
                Description:
                  type: string
                  maxLength: 255
                LocType:
                  type: string
      responses:
        '200':
          description: Location updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: object

    delete:
      tags: [Master Data]
      summary: Delete location
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - LocationID
              properties:
                LocationID:
                  type: integer
      responses:
        '200':
          description: Location deleted

  /api/location/{id}:
    get:
      tags: [Master Data]
      summary: Get location by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: LocationID (primary key)
      responses:
        '200':
          description: Location details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Location'

  /api/contact:
    get:
      tags: [Master Data]
      summary: List contacts
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of contacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'

    post:
      tags: [Master Data]
      summary: Create contact
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - NameFirst
              properties:
                NameFirst:
                  type: string
                  description: First name (required)
                NameLast:
                  type: string
                  description: Last name
                Title:
                  type: string
                  description: Title (e.g., Dr, Mr, Mrs)
                Initial:
                  type: string
                  description: Middle initial
                Birthdate:
                  type: string
                  format: date-time
                EmailAddress1:
                  type: string
                  format: email
                EmailAddress2:
                  type: string
                  format: email
                Phone:
                  type: string
                MobilePhone1:
                  type: string
                MobilePhone2:
                  type: string
                Specialty:
                  type: string
                SubSpecialty:
                  type: string
      responses:
        '201':
          description: Contact created

    patch:
      tags: [Master Data]
      summary: Update contact
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - NameFirst
              properties:
                ContactID:
                  type: integer
                NameFirst:
                  type: string
                NameLast:
                  type: string
                Title:
                  type: string
                Initial:
                  type: string
                Birthdate:
                  type: string
                  format: date-time
                EmailAddress1:
                  type: string
                  format: email
                EmailAddress2:
                  type: string
                  format: email
                Phone:
                  type: string
                MobilePhone1:
                  type: string
                MobilePhone2:
                  type: string
                Specialty:
                  type: string
                SubSpecialty:
                  type: string
      responses:
        '200':
          description: Contact updated

    delete:
      tags: [Master Data]
      summary: Delete contact
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ContactID
              properties:
                ContactID:
                  type: integer
      responses:
        '200':
          description: Contact deleted

  /api/contact/{id}:
    get:
      tags: [Master Data]
      summary: Get contact by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: ContactID (primary key)
      responses:
        '200':
          description: Contact details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Contact'

  /api/occupation:
    get:
      tags: [Master Data]
      summary: List occupations
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of occupations
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Occupation'

    post:
      tags: [Master Data]
      summary: Create occupation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - OccCode
                - OccText
              properties:
                OccCode:
                  type: string
                  description: Occupation code (required)
                OccText:
                  type: string
                  description: Occupation name/text (required)
                Description:
                  type: string
                  description: Additional description
      responses:
        '201':
          description: Occupation created

    patch:
      tags: [Master Data]
      summary: Update occupation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - OccCode
                - OccText
              properties:
                OccupationID:
                  type: integer
                OccCode:
                  type: string
                OccText:
                  type: string
                Description:
                  type: string
      responses:
        '200':
          description: Occupation updated

  /api/occupation/{id}:
    get:
      tags: [Master Data]
      summary: Get occupation by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: OccupationID (primary key)
      responses:
        '200':
          description: Occupation details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Occupation'

  /api/medicalspecialty:
    get:
      tags: [Master Data]
      summary: List medical specialties
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of medical specialties
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MedicalSpecialty'

    post:
      tags: [Master Data]
      summary: Create medical specialty
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - SpecialtyText
              properties:
                SpecialtyText:
                  type: string
                  description: Specialty name/text (required)
                Parent:
                  type: integer
                  description: Parent specialty ID
                Title:
                  type: string
                  description: Title/abbreviation
      responses:
        '201':
          description: Medical specialty created

    patch:
      tags: [Master Data]
      summary: Update medical specialty
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - SpecialtyText
              properties:
                SpecialtyID:
                  type: integer
                SpecialtyText:
                  type: string
                Parent:
                  type: integer
                Title:
                  type: string
      responses:
        '200':
          description: Medical specialty updated

  /api/medicalspecialty/{id}:
    get:
      tags: [Master Data]
      summary: Get medical specialty by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: SpecialtyID (primary key)
      responses:
        '200':
          description: Medical specialty details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/MedicalSpecialty'

  /api/counter:
    get:
      tags: [Master Data]
      summary: List counters
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of counters
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Counter'

    post:
      tags: [Master Data]
      summary: Create counter
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                CounterDesc:
                  type: string
                  description: Counter description/name
                CounterValue:
                  type: integer
                  description: Current counter value
                CounterStart:
                  type: integer
                  description: Starting value
                CounterEnd:
                  type: integer
                  description: Ending value (for auto-reset)
                CounterReset:
                  type: string
                  description: Reset pattern (D=Daily, M=Monthly, Y=Yearly)
      responses:
        '201':
          description: Counter created

    patch:
      tags: [Master Data]
      summary: Update counter
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                CounterID:
                  type: integer
                CounterDesc:
                  type: string
                CounterValue:
                  type: integer
                CounterStart:
                  type: integer
                CounterEnd:
                  type: integer
                CounterReset:
                  type: string
      responses:
        '200':
          description: Counter updated

    delete:
      tags: [Master Data]
      summary: Delete counter
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - CounterID
              properties:
                CounterID:
                  type: integer
      responses:
        '200':
          description: Counter deleted

  /api/counter/{id}:
    get:
      tags: [Master Data]
      summary: Get counter by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: CounterID (primary key)
      responses:
        '200':
          description: Counter details
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Counter'

  /api/areageo:
    get:
      tags: [Master Data]
      summary: List geographical areas
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of geographical areas

  /api/areageo/provinces:
    get:
      tags: [Master Data]
      summary: Get list of provinces
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of provinces

  /api/areageo/cities:
    get:
      tags: [Master Data]
      summary: Get list of cities
      security:
        - bearerAuth: []
      parameters:
        - name: province_id
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of cities

  # ========================================
  # Dashboard & Results (Protected)
  # ========================================
  /api/dashboard:
    get:
      tags: [Dashboard]
      summary: Get dashboard summary
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dashboard summary data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardSummary'

  /api/result:
    get:
      tags: [Results]
      summary: Get patient results
      security:
        - bearerAuth: []
      parameters:
        - name: PatientID
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of results

  /api/sample:
    get:
      tags: [Specimen]
      summary: Get samples
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of samples

  # ========================================
  # Demo Routes (No Auth)
  # ========================================
  /api/demo/order:
    post:
      tags: [Demo]
      summary: Create demo order (no authentication)
      description: Test endpoint for creating orders without authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                PatientID:
                  type: string
                Tests:
                  type: array
                  items:
                    type: object
      responses:
        '201':
          description: Demo order created

  /api/demo/orders:
    get:
      tags: [Demo]
      summary: List demo orders (no authentication)
      responses:
        '200':
          description: List of demo orders