H5P Gradebook Audit — hvp:audit-gradebook

sequenceDiagram
    autonumber
    actor Op as Operator (CLI)
    participant Cmd as AuditHvpGradebook
    participant Svc as HvpGradebookAuditService
    participant Repo as HvpGradebookAuditRepository
    participant DB as Shared MySQL (Moodle schema)
    participant CSV as CSV file

    Op->>Cmd: php artisan hvp:audit-gradebook --course --hvp --student --chunk --top --csv
    Cmd->>Cmd: Build HvpGradebookAuditScope (positive int ids, chunk at least 1)
    Cmd-->>Op: "READ ONLY (no changes written)"
    Cmd->>Svc: audit(scope)
    Svc->>Repo: sourceRows(scope)
    Repo-->>Svc: LazyCollection (not run yet)
    loop Each chunk, lazyById on x.id
        Repo->>DB: SELECT root xAPI rows JOIN hvp, grade_items LEFT JOIN course, grade_grades + cmid subquery
        DB-->>Repo: Up to chunk rows
        Repo-->>Svc: Rows
        loop Each row
            Svc->>Svc: expected = raw_score / max_score x grademax
            alt Grades agree within 0.00001
                Svc->>Svc: Skip
            else Missing, stale or protected
                Svc->>Svc: Push HvpGradebookFinding G1 / G2 / G3
            end
        end
    end
    Svc-->>Cmd: HvpGradebookAuditReport (findings, resultsScanned)
    Cmd-->>Op: "H5P scores scanned: N"
    alt No findings
        Cmd-->>Op: "No gradebook findings" (exit 0)
    else Findings exist
        Cmd-->>Op: Summary table (G code, label, count)
        Cmd-->>Op: Per-activity table, busiest first, limited by --top
        opt --csv given
            Cmd->>CSV: fputcsv header + one row per finding
            alt File opens
                Cmd-->>Op: "Wrote N finding(s)" (exit 0)
            else File cannot open
                Cmd-->>Op: Error (exit 1)
            end
        end
    end

There is no HTTP request, controller, FormRequest or event in this feature. The command is the entry point and the only output is the console and an optional CSV file.

flowchart TD
    A([Operator runs hvp:audit-gradebook]) --> B[Parse options into HvpGradebookAuditScope]
    B --> C[Repository streams root xAPI rows in chunks]
    C --> F1{"parent_id null, max_score > 0, gradetype = VALUE?"}
    F1 -- No --> X1[Excluded by the query]
    F1 -- Yes --> D["expected = raw_score / max_score x grademax"]
    D --> E{"Gradebook row present and finalgrade not null?"}
    E -- No --> P1{"Overridden or locked?"}
    P1 -- Yes --> G3a[G3: overridden or locked]
    P1 -- No --> G1[G1: missing gradebook grade]
    E -- Yes --> M{"abs of stored minus expected within 0.00001?"}
    M -- Yes --> OK[Match: no finding]
    M -- No --> P2{"Overridden or locked?"}
    P2 -- Yes --> G3b[G3: overridden or locked]
    P2 -- No --> G2[G2: stale gradebook grade]
    G1 --> R[Collect into HvpGradebookAuditReport]
    G2 --> R
    G3a --> R
    G3b --> R
    OK --> R
    R --> T{"Any findings?"}
    T -- No --> S0(["Print clean message, exit 0"])
    T -- Yes --> S1[Print summary and per-activity tables]
    S1 --> CS{"--csv given?"}
    CS -- No --> S2([exit 0])
    CS -- Yes --> FO{"File opens for writing?"}
    FO -- Yes --> S3(["Write CSV, exit 0"])
    FO -- No --> S4(["Print error, exit 1"])

    classDef good fill:#064e3b,stroke:#10b981,color:#e2e8f0
    classDef warn fill:#451a03,stroke:#f59e0b,color:#e2e8f0
    classDef bad fill:#450a0a,stroke:#ef4444,color:#e2e8f0
    class OK,S0,S2,S3 good
    class G3a,G3b,X1 warn
    class G1,G2,S4 bad

This is a CLI command, so outcomes are exit codes, not HTTP status codes: 0 (SUCCESS) for a clean or reported run, 1 (FAILURE) only when the CSV file cannot be opened.