import { AttendanceSourceEnum } from '../enum/attendance-source.enum';
import { AttendanceStatus } from '../enum/attendance-status.enum';

/**
 * One entry in the program_user_attendance.attendance_events log — at most one
 * event per source at a time. A new mark from a source replaces (not appends
 * alongside) whatever mark that source held before; an undo removes that
 * source's entry outright. The effective attendance status is derived from
 * this log by the resolution engine (see attendance-resolution.util.ts).
 */
export interface AttendanceEvent {
  source: AttendanceSourceEnum;
  /**
   * Present/absent this event asserts. Optional for backward compatibility:
   * legacy events written before the SESSION_ATTENDANCE module carry no status
   * and are read as PRESENT (TRD §5). Join-click and QR are always PRESENT.
   */
  status?: AttendanceStatus;
  /** ISO 8601 timestamp of when the event occurred. */
  occurredAt: string;
  /** Acting user id; null for self/system events, actor id for manual marks. */
  performedBy: number | null;
  /**
   * The actor's ACTIVE role at the time of the event (role name, e.g. `shoba`,
   * `relational_manager`, `admin`). One user id may hold several roles; the
   * source above is derived from whichever role was active for this action, and
   * this field records it so the mark is unambiguous. Null/absent for
   * system/self events (join, provider).
   */
  performedByRole?: string | null;
}