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

23
backend/src/models.rs
View File

@@ -3,6 +3,7 @@ use serde::{Deserialize, Serialize};
/// API response for a ticket with user information.
///
/// Returned by ticket endpoints. Includes denormalized user data for easier frontend rendering.
/// Created via [`TicketCreateScheme`].
///
/// # Fields
/// - `id`: Unique ticket identifier
@@ -12,7 +13,7 @@ use serde::{Deserialize, Serialize};
/// - `room`: Room number associated with the issue
/// - `status`: Current ticket status (e.g., "open", "in_progress", "resolved")
/// - `date`: When the ticket was created (UTC timestamp)
/// - `user_id`: ID of the user who created the ticket
/// - `user_id`: ID of the user who created the ticket (references [`User`])
/// - `user_first_name`, `user_last_name`: User's name (denormalized for convenience)
///
/// # Example
@@ -47,7 +48,7 @@ pub struct TicketResponse {
/// Complete user record from the database.
///
/// Contains all user information including the password hash.
/// This should NEVER be sent directly to clients - always use `FilteredUser` instead.
/// This should NEVER be sent directly to clients - always use [`FilteredUser`] instead.
///
/// # Fields
/// - `id`: Unique user identifier
@@ -58,7 +59,7 @@ pub struct TicketResponse {
///
/// # Security Note
/// The `pwd` field contains the password hash and should never be included in API responses.
/// Use `filter_user()` to convert to `FilteredUser` for responses.
/// Use [`filter_user()`](`crate::handlers::auth::filter_user`) to convert to [`FilteredUser`] for responses.
#[derive(Deserialize, Serialize, PartialEq, Debug, Clone, sqlx::FromRow)]
pub struct User {
pub id: i16,
@@ -72,7 +73,7 @@ pub struct User {
/// Payload for creating a new ticket.
///
/// Sent to `/api/tickets/create`. The backend automatically associates it with the
/// authenticated user and sets the creation timestamp.
/// authenticated user and sets the creation timestamp. Converted to [`TicketResponse`] for the response.
///
/// # Fields
/// - `category`: Ticket category/type
@@ -89,7 +90,7 @@ pub struct TicketCreateScheme {
/// Payload for updating a ticket.
///
/// Sent to `PATCH /api/tickets/{id}`. Currently only allows status updates.
/// Sent to `PATCH /api/tickets/{id}`. Allows updating the ticket [`TicketResponse::status`].
/// Only admins can update tickets.
///
/// # Fields
@@ -102,10 +103,10 @@ pub struct TicketUpdateScheme {
/// Payload for updating user information.
///
/// Sent to `PATCH /api/users/{id}`. Allows updating profile and admin status.
/// Only admins can update users. Empty password field means no password change.
/// Only admins can update [`User`] records. Empty password field means no password change.
///
/// # Fields
/// - `id`: User ID to update
/// - `id`: [`User`] ID to update
/// - `first_name`, `last_name`: Updated user name
/// - `username`: Updated login username
/// - `make_admin`: New admin privilege status
@@ -123,7 +124,7 @@ pub struct UserUpdateScheme {
/// Payload for creating a new user account.
///
/// Used in both admin registration (`/api/register`) and initial setup (`/api/setup-admin`).
/// The password is hashed server-side before storage using Argon2.
/// The password is hashed server-side before storage using Argon2. Converted to [`User`] for storage.
///
/// # Fields
/// - `first_name`: User's first name
@@ -155,7 +156,7 @@ pub struct LoginScheme {
/// User information sent to clients, excluding password hashes.
///
/// This is the safe version of User data that gets returned in API responses.
/// This is the safe version of [`User`] data that gets returned in API responses.
/// It never includes the password hash or JWT claims. Always use this for responses
/// to prevent leaking sensitive data.
#[derive(Debug, Clone, Serialize)]
@@ -170,10 +171,10 @@ pub struct FilteredUser {
/// JWT token claims embedded in the session token.
///
/// Contains user identification and token validity information.
/// Generated during login and verified by middleware on protected routes.
/// Generated during login via `encode_token` and verified via `decode_token`.
///
/// # Fields
/// - `sub`: Subject - the user ID as a string
/// - `sub`: Subject - the user ID as a string (references [`User`])
/// - `issued`: Unix timestamp when token was created
/// - `expires`: Unix timestamp when token expires (currently 1 hour from creation)
///