headless_lms_server/controllers/main_frontend/credit_registration_admin/
audit.rs

1//! The Audit tab: every hand action on the pipeline, whoever took it.
2//!
3//! Two actor kinds share this log. Teachers may retry and resend on their own course, so filtering
4//! by `actor_role` is what makes "which teachers are retrying, and on what" answerable at all — an
5//! admin acting while looking at a course is otherwise indistinguishable from the course's teacher.
6
7use headless_lms_models::credit_registration_admin_actions::{
8    self, CreditRegistrationAdminAction, CreditRegistrationAdminActionFilters,
9    CreditRegistrationAdminActionListRow, CreditRegistrationAdminActionTarget,
10};
11use headless_lms_models::credit_registrations::CreditRegistrationState;
12use utoipa::ToSchema;
13
14use crate::prelude::*;
15
16use super::authorize_credit_registration_admin;
17
18#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, ToSchema)]
19pub struct CreditRegistrationAdminActionRow {
20    pub id: Uuid,
21    pub created_at: DateTime<Utc>,
22    pub action: CreditRegistrationAdminAction,
23    pub target_kind: CreditRegistrationAdminActionTarget,
24    /// `None` for a phase target, which is named by `target_phase`, and for a bulk action over a
25    /// selection, whose ids are in `details`.
26    pub target_id: Option<Uuid>,
27    pub target_phase: Option<String>,
28    pub actor_user_id: Uuid,
29    pub actor_first_name: Option<String>,
30    pub actor_last_name: Option<String>,
31    pub actor_email: Option<String>,
32    /// `global_admin` or `course_teacher`.
33    pub actor_role: String,
34    /// The course whose edit permission authorised a teacher action.
35    pub actor_course_id: Option<Uuid>,
36    /// The course the action was about: a teacher's own, a course target, or the course of a
37    /// targeted registration.
38    pub course_name: Option<String>,
39    /// The student a registration- or link-targeted action was about, so a row names who it
40    /// concerned rather than only an id prefix. `None` for a phase, course or module target.
41    pub target_user_id: Option<Uuid>,
42    pub target_first_name: Option<String>,
43    pub target_last_name: Option<String>,
44    /// In full, like the actor's.
45    pub target_email: Option<String>,
46    pub reason: Option<String>,
47    pub before_state: Option<CreditRegistrationState>,
48    pub after_state: Option<CreditRegistrationState>,
49    pub details: Option<serde_json::Value>,
50    pub affected_row_count: Option<i32>,
51}
52
53#[derive(Debug, Deserialize)]
54pub struct ListAdminActionsQuery {
55    page: Option<u32>,
56    limit: Option<u32>,
57    action: Option<Vec<CreditRegistrationAdminAction>>,
58    actor_user_id: Option<Uuid>,
59    actor_role: Option<String>,
60    target_kind: Option<CreditRegistrationAdminActionTarget>,
61    target_id: Option<Uuid>,
62    target_phase: Option<String>,
63    course_id: Option<Uuid>,
64    from: Option<DateTime<Utc>>,
65    to: Option<DateTime<Utc>>,
66}
67
68/**
69GET `/api/v0/main-frontend/credit-registration-admin/audit` - A page of the global action log,
70newest first.
71
72Covers admin and course-teacher actors alike, and every target kind: a registration, a course
73module, a course, a phase, a student-number link or its token.
74*/
75#[instrument(skip(pool))]
76#[utoipa::path(
77    get,
78    path = "/audit",
79    operation_id = "listCreditRegistrationAdminActions",
80    tag = "credit-registration-admin",
81    params(
82        ("page" = Option<u32>, Query, description = "Page number, from 1"),
83        ("limit" = Option<u32>, Query, description = "Rows per page"),
84        ("action" = Option<Vec<CreditRegistrationAdminAction>>, Query, description = "Action kinds; repeat the parameter for several"),
85        ("actor_user_id" = Option<Uuid>, Query, description = "Who acted"),
86        ("actor_role" = Option<String>, Query, description = "global_admin or course_teacher"),
87        ("target_kind" = Option<CreditRegistrationAdminActionTarget>, Query, description = "What was acted on"),
88        ("target_id" = Option<Uuid>, Query, description = "One target row"),
89        ("target_phase" = Option<String>, Query, description = "One pipeline phase"),
90        ("course_id" = Option<Uuid>, Query, description = "Actions on this course, and actions its teachers took"),
91        ("from" = Option<DateTime<Utc>>, Query, description = "Taken at or after"),
92        ("to" = Option<DateTime<Utc>>, Query, description = "Taken at or before")
93    ),
94    responses(
95        (status = 200, description = "A page of the action log", body = Page<CreditRegistrationAdminActionRow>)
96    )
97)]
98pub async fn list_credit_registration_admin_actions(
99    user: AuthUser,
100    pool: web::Data<PgPool>,
101    query: MultiQuery<ListAdminActionsQuery>,
102) -> ControllerResult<web::Json<Page<CreditRegistrationAdminActionRow>>> {
103    let mut conn = pool.acquire().await?;
104    let token = authorize_credit_registration_admin(&mut conn, user.id).await?;
105
106    let pagination = parse_pagination(query.page, query.limit, 50)?;
107    let actor_role = non_empty(query.actor_role.as_deref());
108    let target_phase = non_empty(query.target_phase.as_deref());
109    let filters = CreditRegistrationAdminActionFilters {
110        actions: query.action.as_deref(),
111        actor_user_id: query.actor_user_id,
112        actor_role,
113        target_kind: query.target_kind,
114        target_id: query.target_id,
115        target_phase,
116        course_id: query.course_id,
117        from: query.from,
118        to: query.to,
119    };
120    let rows = credit_registration_admin_actions::get_page(
121        &mut conn,
122        &filters,
123        pagination.limit(),
124        pagination.offset(),
125    )
126    .await?;
127    let total_count = rows.first().map_or(0, |row| row.total_count);
128
129    token.authorized_ok(web::Json(Page::new(
130        pagination,
131        rows.into_iter().map(to_action_row).collect(),
132        total_count,
133    )))
134}
135
136fn to_action_row(row: CreditRegistrationAdminActionListRow) -> CreditRegistrationAdminActionRow {
137    CreditRegistrationAdminActionRow {
138        actor_first_name: row.actor_first_name,
139        actor_last_name: row.actor_last_name,
140        actor_email: row.actor_email,
141        course_name: row.course_name,
142        target_user_id: row.target_user_id,
143        target_first_name: row.target_first_name,
144        target_last_name: row.target_last_name,
145        target_email: row.target_email,
146        id: row.action.id,
147        created_at: row.action.created_at,
148        action: row.action.action,
149        target_kind: row.action.target_kind,
150        target_id: row.action.target_id,
151        target_phase: row.action.target_phase,
152        actor_user_id: row.action.actor_user_id,
153        actor_role: row.action.actor_role,
154        actor_course_id: row.action.actor_course_id,
155        reason: row.action.reason,
156        before_state: row.action.before_state,
157        after_state: row.action.after_state,
158        details: row.action.details,
159        affected_row_count: row.action.affected_row_count,
160    }
161}
162
163pub fn _add_routes(cfg: &mut ServiceConfig) {
164    cfg.route(
165        "/audit",
166        web::get().to(list_credit_registration_admin_actions),
167    );
168}
headless_lms_server/controllers/main_frontend/credit_registration_admin/audit.rs

headless_lms_server/controllers/main_frontend/credit_registration_admin/
audit.rs
