Assignment “Additional files” — introattachment exposure

sequenceDiagram
    autonumber
    actor B as Browser (Student)
    participant R as Route /api/v1/assignments/{id}
    participant Rq as ShowAssignmentRequest
    participant C as AssignmentController
    participant S as AssignmentService
    participant G as ActivityAccessGuard
    participant Ctx as ContextResolver
    participant AR as AssignmentRepository
    participant FR as FileRepository
    participant DB as Moodle MySQL (shared)
    participant Res as AssignmentResource
    participant U as MoodleFileUrl
    participant PF as PluginfileController
    participant PC as FilePermissionChecker

    B->>R: GET /api/v1/assignments/{assignmentId}
Authorization: Bearer <sanctum>
    R->>Rq: resolve + auth:sanctum + throttle
    Rq->>Rq: rules() (path-only) → toDTO()
    Rq-->>C: ShowAssignmentDTO{assignmentId, studentId}
    C->>S: showFull($dto)

    S->>AR: findById(assignmentId)
    AR->>DB: SELECT ... FROM assign WHERE id = ?
    DB-->>AR: assign row
    AR-->>S: MoodleAssign

    S->>G: assertAccessible(cm, studentId)
    G->>DB: module visible? active enrolment?
    DB-->>G: ok
    G-->>S: granted

    S->>Ctx: resolve cm context (contextlevel = 70)
    Ctx->>DB: SELECT id FROM context WHERE contextlevel=70 AND instanceid=?
    DB-->>Ctx: cmContextId
    Ctx-->>S: cmContextId

    Note over S,FR: loadIntroAttachments() — new in this feature
    alt cmContextId > 0
        S->>FR: findAllInArea(cmContextId, 'mod_assign', 'introattachment', 0)
        FR->>DB: SELECT * FROM files WHERE contextid=? AND component=?
AND filearea=? AND itemid=? AND filename != '.'
        DB-->>FR: file rows (placeholders excluded)
        FR-->>S: Collection<MoodleFile>
    else cmContextId == 0
        S-->>S: collect() (empty)
    end

    S-->>C: bag[... , intro_attachments]

    C->>Res: withIntroAttachments($bag['intro_attachments'])
    C->>Res: withPluginfileResolution(...) + withFilters(...)
    Res->>Res: buildIntroAttachments() — sort by filepath, filename
    loop each MoodleFile
        Res->>U: pluginfileUrl($file)
        U-->>Res: signed /pluginfile/... (24h expiry)
    end
    Res-->>C: data.intro_attachments[]
    C-->>B: 200 { success, data: { ..., intro_attachments: [...] } }

    Note over B,PC: Later — student clicks a file
    B->>PF: GET /pluginfile/{cmContextId}/mod_assign/introattachment/0/brief.pdf
?expires=&signature=
    PF->>PF: validate HMAC signature
    PF->>PC: check(file, studentId)
    PC->>DB: context level = 70 → checkModuleAccess()
module visible + active enrolment
    DB-->>PC: ok
    PC-->>PF: allowed
    PF-->>B: 200 file stream (Content-Type: application/pdf)

flowchart TD
    A["GET /api/v1/assignments/{assignmentId}"] --> B{"auth:sanctum
token valid?"}
    B -- no --> B1["401 Unauthenticated"]:::err
    B -- yes --> T{"throttle
60 req/min?"}
    T -- exceeded --> T1["429 Too Many Requests"]:::err
    T -- ok --> C["ShowAssignmentRequest → ShowAssignmentDTO"]

    C --> D{"assignment exists?"}
    D -- no --> D1["404 ASSIGNMENT_NOT_FOUND
AssignmentNotFoundException"]:::err
    D -- yes --> E{"module visible AND
student actively enrolled?"}
    E -- no --> E1["403 MODULE_NOT_AVAILABLE
ModuleNotAvailableException"]:::err
    E -- yes --> F{"plugin payload valid?"}
    F -- no --> F1["422 INVALID_PLUGIN_PAYLOAD"]:::err
    F -- yes --> G["resolve course-module context
(contextlevel = 70)"]

    G --> H{"cmContextId > 0?"}
    H -- no --> I["intro_attachments = []
(graceful degrade)"]:::warn
    H -- yes --> J["FileRepository::findAllInArea
contextid, mod_assign, introattachment, 0
filename != '.'"]

    J --> K{"rows found?"}
    K -- no --> I
    K -- yes --> L["sort by filepath, then filename"]
    L --> M["map → id, filename, filepath,
mimetype ?? application/octet-stream,
size, time_created"]
    M --> N["MoodleFileUrl::pluginfileUrl()
24h temporary signed URL"]
    N --> O["intro_attachments[]"]

    I --> P["AssignmentResource::toArray()"]
    O --> P
    P --> Q["200 OK
{ data: { ..., intro_attachments } }"]:::ok

    Q --> R["Student clicks a file URL"]
    R --> S{"signature valid
and not expired?"}
    S -- no --> S1["403 Invalid / expired signature"]:::err
    S -- yes --> U{"FilePermissionChecker
context level 70 → checkModuleAccess"}
    U -- "module hidden or
enrolment inactive" --> U1["403 FILE_ACCESS_DENIED"]:::err
    U -- allowed --> V{"file record exists?"}
    V -- no --> V1["404 File not found"]:::err
    V -- yes --> W["200 file stream
(?forcedownload=1 to force download)"]:::ok

    classDef ok fill:#10b98122,stroke:#10b981,color:#d1fae5;
    classDef err fill:#ef444422,stroke:#ef4444,color:#fee2e2;
    classDef warn fill:#f59e0b22,stroke:#f59e0b,color:#fef3c7;