openapi: 3.1.0
info:
  title: Ladill Care API
  version: 1.1.0
  description: |
    Healthcare management API at care.ladill.com.
    Assessment and pathway endpoints require organization `settings.rollout.assessments_engine = true`.
    Public IDs are UUIDs (never internal integer FKs).
servers:
  - url: https://care.ladill.com/api/v1
paths:
  /health:
    get:
      summary: Health check
      servers:
        - url: https://care.ladill.com/api
  /patients:
    get:
      summary: List patients
    post:
      summary: Register patient
  /patients/{patient}:
    get:
      summary: Patient dashboard
    put:
      summary: Update patient
    delete:
      summary: Archive patient
  /appointments:
    get:
      summary: List appointments
    post:
      summary: Book appointment
  /bills:
    get:
      summary: List bills
  /drugs:
    get:
      summary: List pharmacy inventory
    post:
      summary: Add drug

  /assessment-templates:
    get:
      summary: List current system assessment templates
      tags: [Assessments]
      security: [{ sanctum: [] }]
      responses:
        '200':
          description: Template catalog with questions
        '404':
          description: Assessments engine not enabled

  /patients/{patient}/assessments:
    parameters:
      - $ref: '#/components/parameters/PatientUuid'
    get:
      summary: List assessments for a patient
      tags: [Assessments]
      security: [{ sanctum: [] }]
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [draft, completed, cancelled] }
        - name: template_code
          in: query
          schema: { type: string }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Paginated assessments
    post:
      summary: Start assessment (idempotent draft)
      tags: [Assessments]
      security: [{ sanctum: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [template_code]
              properties:
                template_code: { type: string, example: nihss }
                consultation_uuid: { type: string, format: uuid, nullable: true }
                visit_uuid: { type: string, format: uuid, nullable: true }
      responses:
        '200':
          description: Existing draft returned
        '201':
          description: New draft created
        '403':
          description: Capture not allowed for role/template

  /consultations/{consultation}/assessments:
    post:
      summary: Start assessment linked to consultation
      tags: [Assessments]
      security: [{ sanctum: [] }]
      parameters:
        - $ref: '#/components/parameters/ConsultationUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [template_code]
              properties:
                template_code: { type: string }
      responses:
        '200':
          description: Existing draft
        '201':
          description: Created

  /assessments/{assessment}:
    parameters:
      - $ref: '#/components/parameters/AssessmentUuid'
    get:
      summary: Get assessment with answers and score
      tags: [Assessments]
      security: [{ sanctum: [] }]
      responses:
        '200':
          description: Assessment detail
    put:
      summary: Save draft answers (keyed by question code)
      tags: [Assessments]
      security: [{ sanctum: [] }]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                answers:
                  type: object
                  additionalProperties: true
                  example: { chief_complaint: "Headache", pain_score: 4 }
                notes: { type: string, nullable: true }
      responses:
        '200':
          description: Updated
        '422':
          description: Not draft or validation error

  /assessments/{assessment}/complete:
    post:
      summary: Complete assessment (validates required; materializes score if strategy set)
      tags: [Assessments]
      security: [{ sanctum: [] }]
      parameters:
        - $ref: '#/components/parameters/AssessmentUuid'
      responses:
        '200':
          description: Completed with optional score
        '422':
          description: Missing required answers or already completed

  /assessments/{assessment}/cancel:
    post:
      summary: Cancel draft assessment
      tags: [Assessments]
      security: [{ sanctum: [] }]
      parameters:
        - $ref: '#/components/parameters/AssessmentUuid'
      responses:
        '200':
          description: Cancelled

  /assessments/{assessment}/fhir:
    get:
      summary: Export assessment as FHIR R4 Bundle (Questionnaire + QuestionnaireResponse)
      tags: [Assessments]
      security: [{ sanctum: [] }]
      parameters:
        - $ref: '#/components/parameters/AssessmentUuid'
      responses:
        '200':
          description: application/fhir+json Bundle
          content:
            application/fhir+json:
              schema:
                type: object

  /pathways:
    get:
      summary: List active clinical pathway catalog
      tags: [Pathways]
      security: [{ sanctum: [] }]
      responses:
        '200':
          description: Pathway catalog with template bindings

  /patients/{patient}/pathways:
    parameters:
      - $ref: '#/components/parameters/PatientUuid'
    get:
      summary: Active and historical patient pathways
      tags: [Pathways]
      security: [{ sanctum: [] }]
      responses:
        '200':
          description: Active + history
    post:
      summary: Activate pathway (creates required draft assessments)
      tags: [Pathways]
      security: [{ sanctum: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pathway_code]
              properties:
                pathway_code: { type: string, example: stroke }
                consultation_uuid: { type: string, format: uuid, nullable: true }
                activation_diagnosis_text: { type: string, nullable: true }
      responses:
        '201':
          description: Activated (idempotent if already active)

  /patients/{patient}/pathways/{patientPathway}/deactivate:
    post:
      summary: Deactivate active pathway
      tags: [Pathways]
      security: [{ sanctum: [] }]
      parameters:
        - $ref: '#/components/parameters/PatientUuid'
        - name: patientPathway
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Deactivated

  /consultations/{consultation}/pathway-suggestions:
    get:
      summary: Suggest pathways from persisted diagnoses only
      tags: [Pathways]
      security: [{ sanctum: [] }]
      parameters:
        - $ref: '#/components/parameters/ConsultationUuid'
      responses:
        '200':
          description: Ranked suggestions with match reasons
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        pathway_code: { type: string }
                        pathway_name: { type: string }
                        rank: { type: integer }
                        match_reason: { type: string }
                        already_active: { type: boolean }

components:
  securitySchemes:
    sanctum:
      type: http
      scheme: bearer
  parameters:
    PatientUuid:
      name: patient
      in: path
      required: true
      schema: { type: string, format: uuid }
    ConsultationUuid:
      name: consultation
      in: path
      required: true
      schema: { type: string, format: uuid }
    AssessmentUuid:
      name: assessment
      in: path
      required: true
      schema: { type: string, format: uuid }