schn33fuchs/ticketsystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Refined docs and stuff

Browse Source 
Docs link to each other and are generally better
This commit is contained in:
Silas
2026-05-20 12:50:00 +02:00
parent 0db9b76cad
commit 721e43c380
14 changed files with 256 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
frontend/src/auth.rs
View File

@@ -33,14 +33,14 @@ pub struct ProtectedRouteProps {
/// A component that protects routes by enforcing authentication and optional administrator privileges.
///
/// This component fetches the current user's authentication and admin status from the
/// `/api/users/current` endpoint upon mounting. Based on the `AuthState` and the
/// `admin_page` property, it either renders its children or redirects the user.
/// This component uses the backend's validation middleware by fetching the current user's authentication
/// and admin status from the `/api/users/current` endpoint (which requires a valid JWT token).
/// Based on the [`AuthState`] and the `admin_page` property, it either renders its children or redirects the user.
///
/// # Behavior
/// - **Initial Load**: Displays "Loading..." while checking authentication status.
/// - **Initial Load**: Displays "Loading..." while checking authentication status via the backend.
/// - **Not Authenticated**: Redirects to the login page (`crate::Route::Login`).
/// - **Authenticated**:
/// - **Authenticated** (valid JWT token from backend):
/// - If `admin_page` is `true`:
/// - If the user is an administrator (`is_admin: Some(true)`), it renders `children`.
/// - If the user is not an administrator (`is_admin: Some(false)`), it redirects to

56
frontend/src/lib.rs
View File

@@ -10,7 +10,9 @@ use yew_router::prelude::*;
/// Defines the application's various routes and their corresponding paths.
///
/// This enum is used by `yew-router` to map URLs to specific components,
/// enabling navigation within the single-page application.
/// enabling navigation within the single-page application. Each route is protected
/// by [`ProtectedRoute`] middleware where appropriate to enforce authentication and authorization.
/// See [`switch`] for the routing logic.
#[derive(Clone, PartialEq, Routable)]
enum Route {
/// The application's home page.
@@ -65,10 +67,10 @@ pub struct SidebarShellProps {
/// A shell component that provides a consistent layout with a sidebar and a main content area.
///
/// This component is designed to wrap page-specific content, ensuring that the sidebar
/// is always present for navigation.
/// is always present for navigation. Integrates with [`crate::pages::sidebar::Sidebar`] for navigation.
///
/// # Components
/// - [`sidebar::Sidebar`]: The navigation sidebar component.
/// - [`crate::pages::sidebar::Sidebar`]: The navigation sidebar component.
/// - Main content area: Renders the `children` passed to this component.
///
/// # Example
@@ -101,11 +103,11 @@ pub struct AdminCheckWrapperProps {
///
/// This component is used to gate access to pages that should only be accessible before
/// system initialization (e.g., login page). It performs an asynchronous check to the
/// `/api/check-admin` endpoint to determine system state.
/// backend's `/api/check-admin` endpoint (via `crate::handlers::auth::check_admin_exists`) to determine system state.
///
/// # Behavior
/// - **Loading**: Displays "Loading..." while checking admin status
/// - **No Admin**: Automatically redirects to `/setup` page to initialize
/// - **Loading**: Displays "Loading..." while checking admin status from the backend
/// - **No Admin**: Automatically redirects to [`Route::Setup`] page for initialization
/// - **Admin Exists**: Renders the wrapped children (e.g., login page)
///
/// # Example Usage
@@ -115,19 +117,9 @@ pub struct AdminCheckWrapperProps {
/// </AdminCheckWrapper>
/// ```
///
/// # Implementation Detail
/// The check happens in `use_effect_with` on component mount:
/// ```ignore
/// spawn_local(async move {
/// match Request::get("/api/check-admin").send().await {
/// Ok(resp) if resp.status() == 200 => {
/// let has_admin = data["has_admin"].as_bool().unwrap_or(false);
/// admin_exists.set(Some(has_admin));
/// }
/// _ => admin_exists.set(Some(false))
/// }
/// });
/// ```
/// # Backend Integration
/// The check queries the backend's `/api/check-admin` endpoint which returns `{"has_admin": bool}`.
/// This allows the frontend to determine if initial admin setup is required.
#[component(AdminCheckWrapper)]
fn admin_check_wrapper(props: &AdminCheckWrapperProps) -> Html {
let admin_exists = use_state(|| None::<bool>);
@@ -166,18 +158,24 @@ fn admin_check_wrapper(props: &AdminCheckWrapperProps) -> Html {
/// The main routing logic for the application.
///
/// This function takes a `Route` enum variant and returns the corresponding HTML
/// This function takes a [`Route`] enum variant and returns the corresponding HTML
/// content to be rendered. It acts as a central dispatcher for the application's
/// navigation.
/// navigation and authentication flow.
///
/// Many routes are wrapped in a [`ProtectedRoute`] to enforce authentication
/// and authorization, and in a [`SidebarShell`] to maintain consistent layout.
/// Most routes are wrapped in [`ProtectedRoute`] to enforce authentication
/// and authorization based on the `admin_page` flag, and in [`SidebarShell`] to maintain consistent layout.
/// Login and Setup routes use [`AdminCheckWrapper`] instead to handle pre-authentication states.
///
/// # Arguments
/// - `route`: The [`Route`] enum variant representing the current URL path.
///
/// # Returns
/// An `Html` component that should be rendered for the given route.
///
/// # Route Protection
/// - **Admin-required routes** (`admin_page={true}`): Require both authentication and admin privileges
/// - **Public routes** (`admin_page={false}`): Require only authentication
/// - **Pre-auth routes** (`AdminCheckWrapper`): Used before admin creation or login
fn switch(route: Route) -> Html {
match route {
Route::Home => html! {
@@ -259,12 +257,16 @@ fn switch(route: Route) -> Html {
/// The root component of the Yew application.
///
/// This component sets up the application's routing using `yew-router`'s
/// [`BrowserRouter`] and [`Switch`] components. All other application content
/// is rendered based on the current route.
/// `BrowserRouter` and `Switch` components. All other application content
/// is rendered based on the current [`Route`] matched by the `switch` function.
///
/// Uses [`switch`] as the routing dispatcher to handle all route-specific rendering,
/// which applies appropriate middleware like [`ProtectedRoute`] and [`AdminCheckWrapper`].
///
/// # Structure
/// - [`BrowserRouter`]: Enables client-side routing.
/// - [`Switch`]: Renders components based on the matched [`Route`].
/// - `BrowserRouter`: Enables client-side routing.
/// - `Switch`: Renders components based on the matched [`Route`].
/// - `switch` function: Determines which component to render for each route.
#[component(App)]
pub fn app() -> Html {
html! {

23
frontend/src/pages/basic_pages.rs
View File

@@ -4,6 +4,29 @@ use yew::prelude::*;
use yew_router::prelude::*;
#[macro_export]
/// Removes surrounding double quotes from a string.
///
/// This macro takes an expression that evaluates to a string and returns a new `String`
/// with any leading or trailing double quotes removed. It's useful for cleaning up
/// string data that might be inadvertently wrapped in quotes, such as JSON string values.
///
/// # Arguments
///
/// * `$str`: An expression that can be converted into a string slice (`&str`).
///
/// # Examples
///
/// ```rust
/// use your_crate::dequote; // Assuming `dequote` is re-exported or in scope
///
/// let quoted_string = "\"hello world\"";
/// let dequoted_string = dequote!(quoted_string);
/// assert_eq!(dequoted_string, "hello world");
///
/// let already_clean = "no quotes";
/// let dequoted_clean = dequote!(already_clean);
/// assert_eq!(dequoted_clean, "no quotes");
/// ```
macro_rules! dequote {
($str:expr) => {
$str.trim_matches('"').to_string()

2
frontend/src/pages/setup.rs
View File

@@ -29,7 +29,7 @@ pub struct AdminSetupScheme {
/// a form to create the first admin user. Key functionality:
///
/// - **Admin Check**: On mount, verifies if an admin already exists by calling `/api/check-admin`.
/// If an admin is found, the user is redirected to the login page (`crate::Route::Login`).
/// If an admin is found, the user is redirected to the login page ([`crate::Route::Login`]).
/// - **Form Fields**: Collects `first_name`, `last_name`, `username`, `password`, and `confirm_password`.
/// - **Form Validation**:
/// - Ensures password fields are not empty.

5
frontend/src/pages/sidebar.rs
View File

@@ -7,6 +7,11 @@ use wasm_bindgen_futures::spawn_local;
use yew::prelude::*;
use yew_router::prelude::*;
/// The key used to store and retrieve the sidebar's expansion state in `LocalStorage`.
///
/// This constant ensures consistency when accessing the stored state across different
/// parts of the application. The value associated with this key in `LocalStorage`
/// will be a serialized [`SidebarExpandState`] object.
const STORAGE_KEY: &str = "sidebar_state";
/// Represents the expansion state of collapsible menus within the sidebar.

8
frontend/src/pages/user.rs
View File

@@ -102,6 +102,14 @@ pub struct UserProps {
pub id: i16,
}
/// Represents an error response from the API.
///
/// This struct is used to deserialize error messages received from the backend API.
/// It typically contains a human-readable message and an internal status code.
///
/// # Fields
/// - `message`: A `String` containing a description of the error.
/// - `_status`: An internal status code or message, often ignored in frontend display.
#[derive(Deserialize, Debug)]
struct ApiError {
message: String,

60
frontend/src/pages/utilities.rs
View File

@@ -24,6 +24,15 @@ struct TicketPartial {
user_id: i16,
}
/// A partial representation of a user, containing only the fields necessary for statistical analysis.
///
/// This struct is used to efficiently retrieve and process user data for diagnostics
/// without fetching the full user details.
///
/// # Fields
/// - `id`: The unique identifier of the user.
/// - `first_name`: The first name of the user.
/// - `last_name`: The last name of the user.
#[derive(Debug, Deserialize, Clone, PartialEq)]
struct UserPartial {
id: i16,
@@ -37,12 +46,20 @@ struct UserPartial {
/// for calculating and visualizing ticket distribution per room.
///
/// # Fields
/// - `tickets`: A vector of `TicketPartial` containing ticket data relevant for room totals.
/// - `tickets`: A vector of [`TicketPartial`] containing ticket data relevant for room totals.
#[derive(Properties, PartialEq)]
struct RoomTotalsProps {
tickets: Vec<TicketPartial>,
}
/// Properties for components that display user-wise ticket totals.
///
/// This struct passes a list of partial user data and partial ticket data to a component
/// responsible for calculating and visualizing ticket distribution per user.
///
/// # Fields
/// - `users`: A vector of [`UserPartial`] containing user data relevant for user totals.
/// - `tickets`: A vector of [`TicketPartial`] containing ticket data relevant for user totals.
#[derive(Properties, PartialEq)]
struct UserTotalProps {
users: Vec<UserPartial>,
@@ -79,7 +96,7 @@ fn weekday_index(dt: &DateTime<Utc>) -> usize {
/// the total count of tickets submitted on that day.
///
/// # Arguments
/// - `tickets`: A slice of `TicketPartial` items to count.
/// - `tickets`: A slice of [`TicketPartial`] items to count.
///
/// # Returns
/// An array `[usize; 7]` with ticket counts for each weekday.
@@ -93,12 +110,12 @@ fn count_by_weekday(tickets: &[TicketPartial]) -> [usize; 7] {
/// Calculates the occurrences of each weekday within the date range covered by the tickets.
///
/// This function determines the minimum and maximum dates from the provided `TicketPartial`
/// This function determines the minimum and maximum dates from the provided [`TicketPartial`]
/// slice and then counts how many times each weekday occurs within that inclusive date range.
/// This is useful for normalizing ticket counts against the number of available days for each weekday.
///
/// # Arguments
/// - `partials`: A slice of `TicketPartial` items defining the date range.
/// - `partials`: A slice of [`TicketPartial`] items defining the date range.
///
/// # Returns
/// An array `[usize; 7]` where each element represents the number of times a
@@ -147,7 +164,8 @@ fn day_counts(partials: &[TicketPartial]) -> [usize; 7] {
/// Converts a numerical room representation back into a human-readable string format.
///
/// This function is the inverse of the room parsing logic in `SubmitTicket` component.
/// This function is the inverse of the room parsing logic in
/// [`SubmitTicket`](`crate::pages::ticket::SubmitTicket`) component.
/// It converts negative numbers back to "K" prefixed rooms, numbers >= 1000 back to "D" prefixed rooms,
/// and other numbers to their string representation.
///
@@ -318,12 +336,12 @@ pub fn ticket_count_component() -> Html {
///
/// # State
/// Uses `use_state` hooks to manage:
/// - `tickets`: A vector of `TicketPartial` for statistical analysis.
/// - `tickets`: A vector of [`TicketPartial`] for statistical analysis.
/// - `error`: Any error message from API calls.
/// - `loading`: A boolean indicating if data is being fetched.
///
/// # Functionality
/// - Fetches all tickets (as `TicketPartial`) from `/api/tickets`.
/// - Fetches all tickets (as [`TicketPartial`]) from `/api/tickets`.
/// - Calculates:
/// - `counts`: Number of tickets submitted on each weekday.
/// - `occ`: Number of occurrences of each weekday in the ticket date range.
@@ -465,7 +483,7 @@ pub fn submit_stats_component() -> Html {
/// A component that displays the total number of tickets per room.
///
/// This component takes a list of `TicketPartial` items and calculates the
/// This component takes a list of [`TicketPartial`] items and calculates the
/// total number of tickets for each room. It then displays these totals
/// in a sorted list with a bar chart visualization.
///
@@ -477,7 +495,7 @@ pub fn submit_stats_component() -> Html {
/// - **Sorts Results**: Displays rooms sorted by ticket count in descending order.
/// - **Visualizes Data**: Renders a bar chart where the width of each bar is
/// proportional to the ticket count for that room, relative to the room with the maximum tickets.
/// - **Room Formatting**: Uses the `parse_room` function to display room numbers
/// - **Room Formatting**: Uses the [`parse_room`] function to display room numbers
/// in a human-readable format.
///
/// # Example
@@ -522,6 +540,30 @@ fn room_total_component(props: &RoomTotalsProps) -> Html {
}
}
/// A component that displays the total number of tickets per user.
///
/// This component takes lists of [`UserPartial`] and [`TicketPartial`] items to calculate
/// and display the total number of tickets submitted by each user.
/// The results are presented in a sorted list with a bar chart visualization.
///
/// # Props
/// - `users`: A `Vec<UserPartial>` containing partial user data.
/// - `tickets`: A `Vec<TicketPartial>` containing partial ticket data for analysis.
///
/// # Functionality
/// - **Maps User Names**: Creates a map from user IDs to their first and last names for display.
/// - **Calculates Totals**: Aggregates ticket counts for each user.
/// - **Sorts Results**: Displays users sorted by their ticket count in descending order.
/// - **Visualizes Data**: Renders a bar chart where the width of each bar is proportional
/// to the ticket count for that user, relative to the user with the maximum tickets.
/// - **Name Formatting**: Uses the [`dequote!`] macro to clean up user names before display.
///
/// # Example
/// ```rust
/// html! {
/// <UserTotal users={my_user_partials} tickets={my_ticket_partials} />
/// }
/// ```
#[component(UserTotal)]
fn user_total_component(props: &UserTotalProps) -> Html {
let name_map: HashMap<i16, (String, String)> = props