Skip to content

Update grant extension feature docs for frontend and API #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
samindiii wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update grant extension feature docs for frontend and API #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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',
Expand Down
43 changes: 22 additions & 21 deletions src/content/docs/backend/API/api_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
86 changes: 86 additions & 0 deletions src/content/docs/backend/API/staff_grant_extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
```
14 changes: 14 additions & 0 deletions src/content/docs/frontend/component_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 0 additions & 5 deletions src/content/docs/frontend/page.md
View file
Open in desktop

This file was deleted.

98 changes: 98 additions & 0 deletions src/content/docs/frontend/staff_grant_extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<f-grant-extension-form>` 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 });
```