Quiz Regrade-Data Repair

sequenceDiagram
    participant Op as Operator (CLI)
    participant Cmd as RepairQuizRegradeData
    participant Svc as RegradeDataRepairService
    participant Acc as RegradeRepairAccumulator
    participant Repo as RegradeDataRepairRepository
    participant DB as MySQL (Moodle DB)
    participant TF as TruefalseFormat

    Op->>Cmd: php artisan quiz:repair-regrade-data [opts]
    Cmd->>Cmd: buildScope() - RegradeRepairScope DTO
    Cmd->>Svc: countAttemptsInScope(scope)
    Svc->>Repo: countAttempts(scope)
    Repo->>DB: SELECT COUNT(*) FROM quiz_attempts
    DB-->>Repo: count
    Repo-->>Svc: int
    Svc-->>Cmd: int
    Cmd->>Cmd: renderBanner() + startProgress()

    Cmd->>Svc: repair(scope, onBatchProcessed)
    Svc->>Acc: new RegradeRepairAccumulator

    loop Per chunk of attempts
        Svc->>Repo: lazyAttempts(scope).chunk(n)
        Repo->>DB: Cursor: quiz_attempts JOIN quiz JOIN course_modules
        DB-->>Repo: LazyCollection of attempt rows
        Repo-->>Svc: batch

        Note over Svc: Detect A1/A2: finish markers
        Svc->>Repo: findSteps(usageIds)
        Repo->>DB: SELECT from question_attempt_steps
        DB-->>Repo: steps
        Svc->>Repo: findStepIdsWithData(stepIds)
        Repo->>DB: SELECT DISTINCT attemptstepid
        DB-->>Repo: set of ids with data
        Svc->>Repo: findStepIdsWithFinishMarker(stepIds)
        Repo->>DB: SELECT WHERE name = '-finish'
        DB-->>Repo: set of ids with marker
        Svc->>Svc: classifyQuestionAttempt() per slot

        Note over Svc: Detect B: truefalse
        Svc->>Repo: findLegacyTruefalseAnswerRows(usageIds)
        Repo->>DB: SELECT WHERE qtype='truefalse' AND value NOT IN ('','0','1')
        DB-->>Repo: candidate rows
        Svc->>Repo: findTruefalseQuestions(questionIds)
        Repo->>DB: MoodleQuestion with answers + truefalseOptions
        DB-->>Repo: keyed collection
        Svc->>TF: normalize(options, answers, raw)
        TF-->>Svc: '1' or '0' or null

        alt scope.apply = true
            Svc->>DB: DB::transaction
            Svc->>Repo: insertFinishMarkers(stepIds)
            Repo->>DB: INSERT INTO question_attempt_step_data
            Svc->>Repo: updateStepDataValue(id, value)
            Repo->>DB: UPDATE question_attempt_step_data
        end

        Svc->>Acc: record(attempt, finding, rows)
        Svc->>Cmd: onBatchProcessed(count)
    end

    Svc->>Acc: toReport()
    Acc-->>Svc: RegradeRepairReport DTO
    Svc-->>Cmd: RegradeRepairReport

    Cmd->>Cmd: renderReport() tables and next steps
    Cmd-->>Op: EXIT 0
      

flowchart TD
    START([php artisan quiz:repair-regrade-data]) --> PARSE[Parse CLI options]
    PARSE --> VALID{Options valid?}
    VALID -->|No| FAIL([EXIT 1 invalid options])
    VALID -->|Yes| SCOPE[Build RegradeRepairScope DTO]
    SCOPE --> BANNER[Render banner: mode + filters]
    BANNER --> COUNT[Count attempts in scope]
    COUNT --> PROGRESS{More than 1 chunk?}
    PROGRESS -->|Yes| BAR[Start progress bar]
    PROGRESS -->|No| SKIP_BAR[No bar needed]
    BAR --> STREAM
    SKIP_BAR --> STREAM

    STREAM[Stream attempts via LazyCollection cursor] --> CHUNK{Next chunk?}
    CHUNK -->|No| REPORT

    CHUNK -->|Yes| A_DETECT[Detect A1/A2: load steps
set-difference for data-less
classify maximal runs]
    A_DETECT --> B_DETECT[Detect B: find legacy truefalse
answer ids and normalize via
TruefalseFormat]
    B_DETECT --> FINDINGS{Any findings?}
    FINDINGS -->|No| ADV[Advance progress bar]
    FINDINGS -->|Yes| APPLY{scope.apply?}

    APPLY -->|No dry run| RECORD[Record findings in accumulator]
    APPLY -->|Yes| WRITE[DB::transaction per chunk]

    WRITE --> W_A1{A1 findings?}
    W_A1 -->|Yes| INSERT[Bulk INSERT -finish=1 markers]
    W_A1 -->|No| W_A2

    INSERT --> W_A2{A2 + repairBlankSteps?}
    W_A2 -->|Yes| INSERT2[INSERT -finish=1 for A2 steps]
    W_A2 -->|No| W_B

    INSERT2 --> W_B
    W_B{B findings?}
    W_B -->|Yes| UPDATE[UPDATE value to 1 or 0]
    W_B -->|No| RECORD

    UPDATE --> RECORD
    RECORD --> ADV
    ADV --> CHUNK

    REPORT[Build RegradeRepairReport DTO] --> HAS{hasFindings?}
    HAS -->|No| CLEAN[No regrade-unsafe rows found]
    HAS -->|Yes| TABLES[Render findings table + quiz table]
    TABLES --> DETAIL{--detail?}
    DETAIL -->|Yes| ATBL[Render per-attempt table]
    DETAIL -->|No| NEXT

    ATBL --> NEXT[Render next steps]
    NEXT --> A2_CHECK{A2 rows found?}
    A2_CHECK -->|Yes + repairBlankSteps| REGRADE[NEXT STEP: regrade in Moodle]
    A2_CHECK -->|Yes + not opted in| REVIEW[NOT REPAIRED: review by hand]
    A2_CHECK -->|No| DONE

    CLEAN --> DONE
    REGRADE --> DONE
    REVIEW --> DONE
    DONE([EXIT 0])

    style FAIL fill:#3b1c1c,stroke:#ef4444,color:#fca5a5
    style DONE fill:#1c2e1c,stroke:#10b981,color:#6ee7b7
    style CLEAN fill:#1c2e1c,stroke:#10b981,color:#6ee7b7
    style WRITE fill:#2a1f0f,stroke:#f59e0b,color:#fcd34d
    style INSERT fill:#2a1f0f,stroke:#f59e0b,color:#fcd34d
    style INSERT2 fill:#2a1f0f,stroke:#f59e0b,color:#fcd34d
    style UPDATE fill:#2a1f0f,stroke:#f59e0b,color:#fcd34d