# RTSport API — v0.3
# Frontend-driven contract from the AT dashboard mock.
# These are the endpoints the frontend currently fetches or POSTs to.
# Socrates: wire these. Auth, roles, and FERPA matrix in contract.md.

openapi: "3.0.3"
info:
  title: RTSport API
  version: "0.3"
  description: |
    Athletic training case management for high school sports.
    Current frontend targets: AT dashboard, sideline entry, athlete detail overlay.

servers:
  - url: https://api.hoffdesk.com/rtsport/v1
    description: Production
  - url: https://hoffdesk.com/api/v1
    description: Current mock server path

paths:
  # ── Dashboard ────────────────────────────────────────
  /events/sideline-entry:
    post:
      summary: Submit a sideline injury/incident entry
      description: Called by the 3-tap sideline entry flow after all 3 selections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - school_id
                - athlete_id
                - body_part
                - severity
              properties:
                school_id:
                  type: string
                  example: "schl_001"
                athlete_id:
                  type: string
                  example: "ath_001"
                body_part:
                  type: string
                  example: "Ankle"
                severity:
                  type: string
                  enum: [mild, moderate, severe]
                  example: "moderate"
                removed_from_play:
                  type: boolean
                  default: false
                timestamp:
                  type: string
                  format: date-time
                  description: ISO-8601 timestamp of when the injury occurred
      responses:
        "200":
          description: Entry created
          content:
            application/json:
              schema:
                type: object
                properties:
                  case_id:
                    type: string
                    example: "cas_abc123"
                  athlete:
                    type: string
                    example: "Jake Larson"
                  body_part:
                    type: string
                    example: "Ankle"
                  severity:
                    type: string
                    example: "moderate"
                  athlete_status:
                    type: string
                    enum: [removed, evaluated]
        "400":
          description: Validation error — missing required fields

  # ── Athlete Detail ───────────────────────────────────
  /athletes/{athlete_id}:
    get:
      summary: Get athlete profile
      parameters:
        - name: athlete_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Athlete profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Athlete"

  /cases/{athlete_id}:
    get:
      summary: Get active case for an athlete (latest if multiple)
      parameters:
        - name: athlete_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Full case data including milestones and timeline
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Case"
        "404":
          description: No active case found for this athlete

  /athletes/{athlete_id}/case:
    get:
      summary: Combined endpoint — returns athlete + active case in one call
      description: |
        Frontend currently makes TWO separate fetches (athletes.json + cases.json)
        and joins on athlete_id. This endpoint wraps both into one response
        for the athlete detail overlay.
      parameters:
        - name: athlete_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Athlete and case data merged
          content:
            application/json:
              schema:
                type: object
                properties:
                  athlete:
                    $ref: "#/components/schemas/Athlete"
                  case:
                    $ref: "#/components/schemas/Case"

  # ── Dashboard Data ───────────────────────────────────
  /dashboard/at:
    get:
      summary: AT dashboard — quick stats and active cases
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    type: object
                    properties:
                      full_count:
                        type: integer
                        example: 72
                      modified_count:
                        type: integer
                        example: 8
                      out_count:
                        type: integer
                        example: 3
                  active_cases:
                    type: array
                    items:
                      $ref: "#/components/schemas/CaseSummary"
                  recent_activity:
                    type: array
                    items:
                      $ref: "#/components/schemas/ActivityItem"

  # ── Sideline ─────────────────────────────────────────
  /body-parts:
    get:
      summary: Body part categories and parts for the sideline entry picker
      responses:
        "200":
          description: Body part hierarchy (categories → parts)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BodyPartCategory"

components:
  schemas:
    Athlete:
      type: object
      required:
        - id
        - first_name
        - last_name
        - sport
        - team
        - grade
      properties:
        id:
          type: string
          example: "ath_001"
        first_name:
          type: string
          example: "Jake"
        last_name:
          type: string
          example: "Larson"
        sport:
          type: string
          example: "Football"
        team:
          type: string
          example: "Varsity"
        grade:
          type: integer
          example: 11
        initials:
          type: string
          example: "JL"
          description: Computed from first/last name, could also be server-generated
        active:
          type: boolean
          default: true

    Case:
      type: object
      required:
        - case_id
        - athlete_id
        - injury
        - status
      properties:
        case_id:
          type: string
          example: "cas_001"
        athlete_id:
          type: string
          example: "ath_001"
        injury:
          type: string
          example: "Ankle Sprain (Grade 2)"
        injury_date:
          type: string
          format: date
          example: "2026-04-28"
        body_part:
          type: string
          example: "Ankle"
        side:
          type: string
          enum: [Left, Right, null]
          nullable: true
          example: "Right"
        severity:
          type: string
          enum: [mild, moderate, severe]
        attention:
          type: string
          enum: [stable, urgent, warning]
          description: >-
            stable = on track. warning = behind schedule, need check-in.
            urgent = medical concern, review today.
        status:
          type: string
          enum: [active, cleared, referred]
        phase:
          type: integer
          example: 2
        total_phases:
          type: integer
          example: 4
        phase_label:
          type: string
          description: Human-readable current phase name
          example: "Active Rehab"
        projected_return:
          type: string
          format: date
          nullable: true
          example: "2026-05-12"
        last_updated:
          type: string
          example: "2026-05-01 14:00"
        last_updated_by:
          type: string
          example: "You"
        notified:
          type: array
          items:
            type: string
          example: ["Coach Andrews", "Parent"]
        milestones:
          type: array
          items:
            $ref: "#/components/schemas/Milestone"
        timeline:
          type: array
          items:
            $ref: "#/components/schemas/TimelineEvent"

    Milestone:
      type: object
      properties:
        num:
          type: integer
          description: Phase number (1-based)
          example: 2
        label:
          type: string
          description: Phase name
          example: "Active Rehab"
        status:
          type: string
          enum: [done, current, pending]
        completed:
          type: string
          format: date
          nullable: true
        note:
          type: string
          example: "Walking without limp. ROM 75%. Strength work initiated."

    TimelineEvent:
      type: object
      properties:
        date:
          type: string
          example: "Apr 28 · 3:15 PM"
          description: Display-ready date string or ISO-8601 timestamp
        title:
          type: string
          example: "Initial Assessment"
        note:
          type: string
          example: "Grade 2 lateral ankle sprain. Swelling +2, unable to bear weight."
        by:
          type: string
          example: "You"
        type:
          type: string
          enum: [assessment, restriction, milestone, clearance, note]
          description: Drives the colored dot in the timeline UI

    CaseSummary:
      type: object
      properties:
        athlete_id:
          type: string
        athlete_name:
          type: string
        initials:
          type: string
        sport:
          type: string
        injury:
          type: string
        injury_short:
          type: string
          example: "Ankle sprain (Grade 2)"
        status:
          type: string
          enum: [active, cleared, referred]
        status_label:
          type: string
          example: "Phase 2/4"
        avatar_color:
          type: string
          description: CSS-compatible color string for avatar background
          example: "teal"

    ActivityItem:
      type: object
      properties:
        type:
          type: string
          enum: [cleared, out, modified]
        text:
          type: string
          example: "Marcus Johnson cleared for full practice"
        time_ago:
          type: string
          example: "2h ago"

    BodyPartCategory:
      type: object
      properties:
        name:
          type: string
          example: "Lower Body"
        parts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: "ankle"
              label:
                type: string
                example: "Ankle"
              icon:
                type: string
                example: "🦶"