From 38f76669d020c25b5ba2a98f281855370233aef6 Mon Sep 17 00:00:00 2001 From: Jacqueline Date: Sun, 8 Dec 2024 16:36:13 -0500 Subject: [PATCH] Add admin backend documentation --- server/src/admin/admin.controller.ts | 11 ++++++++ server/src/admin/admin.data-access.ts | 36 ++++++++++++++++++++++++--- server/src/admin/admin.router.ts | 8 ++++++ 3 files changed, 51 insertions(+), 4 deletions(-) diff --git a/server/src/admin/admin.controller.ts b/server/src/admin/admin.controller.ts index 2907dc14..96d0577f 100644 --- a/server/src/admin/admin.controller.ts +++ b/server/src/admin/admin.controller.ts @@ -96,6 +96,11 @@ export const editReviewVisibility = async ({ return false; }; +/** + * Approves all pending reviews + * @param {Auth} auth: Object that represents the authentication of a request being passed in. + * @returns Result of the approval process or an error message. + */ export const approveReviews = async ({ auth }: VerifyAdminType) => { const userIsAdmin = await verifyTokenAdmin({ auth }); if (userIsAdmin) { @@ -247,6 +252,12 @@ export const updateAllProfessorsDb = async ({ auth }: VerifyAdminType) => { return result; }; +/** + * Resets all professor arrays in the database to empty arrays + * + * @param {Auth} auth: Object that represents the authentication of a request being passed in. + * @returns true if operation was successful, false if operations was not successful, null if token not admin + */ export const resetAllProfessorsDb = async ({ auth }: VerifyAdminType) => { const userIsAdmin = verifyTokenAdmin({ auth }); if (!userIsAdmin) { diff --git a/server/src/admin/admin.data-access.ts b/server/src/admin/admin.data-access.ts index 7b834f50..b19ccece 100644 --- a/server/src/admin/admin.data-access.ts +++ b/server/src/admin/admin.data-access.ts @@ -3,6 +3,11 @@ import { Classes, ReviewDocument, Reviews, Students } from '../../db/schema'; import { UpdateCourseMetrics } from './admin.type'; import { findCourseById } from '../course/course.data-access'; +/** + * Updates metrics for a course based on a recently written review + * @param review the review that was submitted by a user and approved by an admin + * @param state the updated metrics for the specified course + */ export const updateCourseMetrics = async ( review: ReviewDocument, state: UpdateCourseMetrics @@ -25,7 +30,7 @@ export const updateCourseMetrics = async ( }; /* - * Function to return all pending reviews in the database. + * Returns all pending reviews in the database */ export const findPendingReviews = async () => await Reviews.find( @@ -35,7 +40,7 @@ export const findPendingReviews = async () => ).exec(); /* - * Function to return all reported reviews in the database. + * Returns all reported reviews in the database */ export const findReportedReviews = async () => await Reviews.find( @@ -45,7 +50,7 @@ export const findReportedReviews = async () => ).exec(); /* - * Function to count reviews by approved, pending, and reported and return the values. + * Count reviews by approved, pending, and reported and return the total counts */ export const findReviewCounts = async () => { const approvedCount = await Reviews.countDocuments({ visible: 1 }).exec(); @@ -66,7 +71,7 @@ export const findReviewCounts = async () => { }; /* - * Function to count the number of approved reviews per class in the database. + * Counts the number of approved reviews per class in the database. * Count per class is mapped to a CSV string format. */ export const createCourseCSV = async () => { @@ -95,10 +100,20 @@ export const createCourseCSV = async () => { return csv; }; +/** + * Removes pending review from website and database + * @param {string} reviewId: Mongo generated review id. + */ export const removeReviewById = async (reviewId: string) => { await Reviews.deleteOne({ _id: reviewId }); }; +/** + * Updates review visibility on website and profile page + * @param {string} reviewId: Mongo generated review id. + * @param {number} reported: 1 review was reported, 0 otherwise. + * @param {number} visible: 1 if want to set review to visible to public, 0 if review is only visible by admin. + */ export const updateReviewVisibility = async ( reviewId: string, reported: number, @@ -107,6 +122,9 @@ export const updateReviewVisibility = async ( await Reviews.updateOne({ _id: reviewId }, { $set: { visible, reported } }); }; +/** + * Approves all pending reviews at once + */ export const approveAllReviews = async () => { await Reviews.updateMany( { visible: 0, reported: 0 }, @@ -125,6 +143,11 @@ export const findAdminUsers = async () => { return adminUsers; }; +/** + * Removes admin privilege from a user + * @param id netid of user + * @returns result of the database operation + */ export const removeAdminPrivilege = async (id: string) => { const res = await Students.updateOne( { netId: id }, @@ -133,6 +156,11 @@ export const removeAdminPrivilege = async (id: string) => { return res; }; +/** + * Gives a specified user admin privilege + * @param id netid of user + * @returns result of the database operation + */ export const grantAdminPrivilege = async (id: string) => { const res = await Students.updateOne( { netId: id }, diff --git a/server/src/admin/admin.router.ts b/server/src/admin/admin.router.ts index 7ad44639..bc8ab405 100644 --- a/server/src/admin/admin.router.ts +++ b/server/src/admin/admin.router.ts @@ -420,6 +420,10 @@ adminRouter.post('/professors/reset', async (req, res) => { } }); +/** Reachable at POST /api/admin/course/desc + * @body token: a session's current token + * Updates all courses in the db with their course descriptions. For admins only + */ adminRouter.post('/course/desc', async (req, res) => { const { token }: AdminRequestType = req.body; try { @@ -442,6 +446,10 @@ adminRouter.post('/course/desc', async (req, res) => { } }); +/** Reachable at POST /api/admin/subjects/update + * @body token: a session's current token + * Updates all subjects in the db with their full subject names. For admins only + */ adminRouter.post('/subjects/update', async (req, res) => { const { token }: AdminRequestType = req.body; try {