diff --git a/astro.config.mjs b/astro.config.mjs index 85e1df58..358f215f 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -47,6 +47,12 @@ export default defineConfig({ { label: 'Frontend Tutor-Times Design', link: '/frontend/tutor-times/tutor-times-design', + label: 'Frontend Component Documentation List', + link: '/frontend/component_list', + }, + { + label: 'staff grant extension', + link: '/frontend/staff_grant_extension', }, { label:'Frontend Tutor-Times Requirements', @@ -103,6 +109,10 @@ export default defineConfig({ label: 'setting', link: '/backend/api/setting', }, + { + label: 'staff grant extension', + link: '/backend/api/staff_grant_extension', + }, { label: 'students', link: '/backend/api/students', diff --git a/src/content/docs/backend/API/api_list.md b/src/content/docs/backend/API/api_list.md index ade70ac5..464b647c 100644 --- a/src/content/docs/backend/API/api_list.md +++ b/src/content/docs/backend/API/api_list.md @@ -6,26 +6,27 @@ title: Doubtfire API Below is the list of the APIs used by doubtfire-api. -| API detail | Description | -| ---------------- | --------------------------------- | -| activity_types | Operations about activity_types | -| admin | Operations about admins | -| auth | Operations about auths | -| campuses | Operations about campuses | -| csv | Operations about csvs | -| projects | Operations about projects | -| settings | Operations about settings | -| students | Operations about students | -| submission | Operations about submissions | -| tasks | Operations about tasks | -| teaching_periods | Operations about teaching_periods | -| tii_actions | Operations about tii_actions | -| tii_eula | Operations about tii_eulas | -| tii_hook | Operations about tii_hooks | -| tutorials | Operations about tutorials | -| unit_roles | Operations about unit_roles | -| units | Operations about units | -| users | Operations about users | -| webcals | Operations about webcals | +| API detail | Description | +| --------------------- | --------------------------------- | +| activity_types | Operations about activity_types | +| admin | Operations about admins | +| auth | Operations about auths | +| campuses | Operations about campuses | +| csv | Operations about csvs | +| projects | Operations about projects | +| settings | Operations about settings | +| staff_grant_extension | Operations about extensions | +| students | Operations about students | +| submission | Operations about submissions | +| tasks | Operations about tasks | +| teaching_periods | Operations about teaching_periods | +| tii_actions | Operations about tii_actions | +| tii_eula | Operations about tii_eulas | +| tii_hook | Operations about tii_hooks | +| tutorials | Operations about tutorials | +| unit_roles | Operations about unit_roles | +| units | Operations about units | +| users | Operations about users | +| webcals | Operations about webcals | Detail operations regarding each APIs are listed in following pages. diff --git a/src/content/docs/backend/API/staff_grant_extension.md b/src/content/docs/backend/API/staff_grant_extension.md new file mode 100644 index 00000000..37c04c2a --- /dev/null +++ b/src/content/docs/backend/API/staff_grant_extension.md @@ -0,0 +1,86 @@ +--- +title: Doubtfire API Documentation +--- + +# API: Staff Grant Extension +staff_grant_extension: Operation to allow staff to grant task extensions to students +This markdown document provides detailed documentation for the "staff_grant_extension" API endpoint, including its URL, method, parameters, responses, and example request using curl. + +This "staff_grant_extension" API has the following operation: + +- **POST** /api/units/{unit_id}/staff-grant-extension + +## Detail of Operations related to staff_grant_extension. + +### POST:Grant extensions to multiple students +POST /api/units/{unit_id}/staff-grant-extension + +- URL: `/api/units/{unit_id}/staff_grant_extension` +- Method: `POST` +- Description: This endpoint allows staff to grant extensions to multiple students at once for a specific task. The operation is atomic—either all extensions are granted or none are. Students not found in the unit are automatically skipped without affecting the transaction +- Parameters: + +| Parameter | Description | Parameter Type | Data Type | Mandatory | +| -------------------| --------------------------| -------------- | --------- | --------- | +| student_ids | List of student IDs | formData | Array | Yes | +| task_definition_id | ID of the task definition | formData | Integer | Yes | +| weeks_requested | Number of weeks to extend | formData | Integer | Yes | +| comment | Reason for extension | formData | String | Yes | + +- Response: + `201` + +- Example Request: + + ```bash + curl -X POST http://localhost:3000/api/units/123/staff-grant-extension \ + -H 'Content-Type: application/json' \ + -H 'Username: tutor' \ + -H 'Auth_Token: abc123def456' \ + -d '{ + "student_ids": [456, 676], + "task_definition_id": 789, + "weeks_requested": 1, + "comment": "Unit wide extension" + }' + +- Response Body: + ```json + { + "successful": [ + { + "student_id": 456, + "project_id": 999, + "weeks_requested": 1, + "extension_response": "Extension granted. New due date: Jun 1", + "task_status": { + "status": "in-progress", + "extensions": 1 + } + } + ], + "skipped": [], + "failed": [] + } + ``` +- Skipped Response Body: + ```json + { + "successful": [], + "skipped": [ + { + "student_id": 999999, + "reason": "Student not found in unit" + } + ], + "failed": [] + } + ``` +- Error Responses: + ```json + { + "student_id": 123, + "project_id": 999, + "error": "Task is past due date" + } + ``` \ No newline at end of file diff --git a/src/content/docs/frontend/component_list.md b/src/content/docs/frontend/component_list.md new file mode 100644 index 00000000..f7641671 --- /dev/null +++ b/src/content/docs/frontend/component_list.md @@ -0,0 +1,14 @@ +--- +title: Doubtfire Component +--- + +# List of Doubtfire Components + +Below is the list of the APIs used by doubtfire-api. + + +| Component Name | Description | +| --------------------- | --------------------------------- | +| staff_grant_extension | Operations about extensions | + +Detail operations regarding each components are listed in following pages. \ No newline at end of file diff --git a/src/content/docs/frontend/page.md b/src/content/docs/frontend/page.md deleted file mode 100644 index f05133ec..00000000 --- a/src/content/docs/frontend/page.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Example ---- - -# Add topic diff --git a/src/content/docs/frontend/staff_grant_extension.md b/src/content/docs/frontend/staff_grant_extension.md new file mode 100644 index 00000000..dfb1b7ba --- /dev/null +++ b/src/content/docs/frontend/staff_grant_extension.md @@ -0,0 +1,98 @@ +--- +title: Doubtfire Component Documentation +--- + +# Component: Staff Grant Extension + + +## Component Overview + +| Name | File Path | +|---------------------------------|---------------------------------------------------------------------------------| +| `GrantExtensionDialogComponent` | `src/app/admin/modals/grant-extension-form/grant-extension-dialog.component.ts` | +| `GrantExtensionFormComponent` | `src/app/admin/modals/grant-extension-form/grant-extension-form.component.ts` | + +This feature allows staff to grant an extension for a task to a specific student using a modal form dialog. It submits data to the backend via the `ExtensionService`. + +--- + +## UI Behavior + +- Launched via a dialog modal +- Form fields: + - **Student** (dropdown) + - **Extension Duration** (slider in days) + - **Reason** (textarea) + - **Optional Notes** +- Two buttons: + - `Cancel`: Closes modal + - `Grant Extension`: Submits data + +--- + +## Component Responsibilities + +### `GrantExtensionDialogComponent` + +- Displays the modal container +- Injects and closes `MatDialogRef` +- Embeds `` inside dialog UI + +### `GrantExtensionFormComponent` + +- Handles form logic with Angular Reactive Forms +- Maintains a hardcoded student list (`students[]`) +- Sends `POST` request using `ExtensionService` +- Manages validation, UI state (`isSubmitting`), and error handling + +--- + +## Sample Usage + +### Dialog Trigger + +```ts +this.dialog.open(GrantExtensionDialogComponent); +``` + +--- + +## Sample Usage + +| Field | FormControl Name | Type | Validation | Notes | +| -------- | ---------------- | ------ | ----------------- | ------------------------------------- | +| Student | `student` | select | Required | Populated from hardcoded `students[]` | +| Duration | `extension` | slider | Required, min = 1 | Values from 1 to 30 days | +| Reason | `reason` | text | Required | User-provided reason for extension | +| Notes | `notes` | text | Optional | Additional context | + +--- + +## Example Request + +```ts +this.extensionService.grantExtension(unitId, payload).subscribe(...) +``` +Calls backend endpoint: + +```ruby +POST /api/units/:unit_id/staff-grant-extension +``` + +--- + +## Success Behavior + +Displays snackbar: +"Extension granted successfully!" + +Closes dialog + +## Error Handling +Displays snackbar with error message from backend or a generic fallback. + +Example: + +```ts +this.snackBar.open(`Failed to grant extension: ${errorMsg}`, 'Close', { duration: 5000 }); +```