diff --git a/docs/ENCOACH_ODOO19_BACKEND_SRS.md b/docs/ENCOACH_ODOO19_BACKEND_SRS.md index 2500333..84d0ba3 100644 --- a/docs/ENCOACH_ODOO19_BACKEND_SRS.md +++ b/docs/ENCOACH_ODOO19_BACKEND_SRS.md @@ -1,9 +1,9 @@ # EnCoach Platform — Odoo 19 Backend SRS -**Version:** 1.0 +**Version:** 2.0 **Date:** March 2026 **Status:** Definitive -**Purpose:** Complete backend specification for an Odoo 19 developer to build all required modules, models, and REST API endpoints for the EnCoach Adaptive Learning Platform. +**Purpose:** Complete backend specification for an Odoo 19 developer to build all required modules, models, and REST API endpoints for the EnCoach Adaptive Learning Platform. Includes courseware, communication, notification, FAQ, enhanced approval workflows, plagiarism detection, and official exam access modes. --- @@ -33,9 +33,15 @@ 22. [Subscription and Payments](#22-subscription-and-payments) 23. [Support Tickets](#23-support-tickets) 24. [File Storage](#24-file-storage) -25. [Approval Workflows](#25-approval-workflows) -26. [Non-Functional Requirements](#26-non-functional-requirements) -27. [Implementation Priority](#27-implementation-priority) +25. [Approval Workflows (Enhanced)](#25-approval-workflows-enhanced) +26. [Courseware and Content Delivery](#26-courseware-and-content-delivery) +27. [Communication System](#27-communication-system) +28. [Notification Engine](#28-notification-engine) +29. [FAQ System](#29-faq-system) +30. [Plagiarism Detection](#30-plagiarism-detection) +31. [Official Exam Access](#31-official-exam-access) +32. [Non-Functional Requirements](#32-non-functional-requirements) +33. [Implementation Priority](#33-implementation-priority) --- @@ -47,7 +53,7 @@ This document specifies the complete Odoo 19 backend for the EnCoach Adaptive Le ### 1.2 Frontend Contract -The React frontend has 24 API service modules that define the exact endpoints the backend must implement. This SRS documents every endpoint, its expected request/response shape, and the underlying Odoo models. +The React frontend has 29 API service modules that define the exact endpoints the backend must implement. This SRS documents every endpoint, its expected request/response shape, and the underlying Odoo models. ### 1.3 Key Principles @@ -163,8 +169,12 @@ All OpenEduCat models need `to_api_dict()` methods on the `encoach_lms_api` inhe | 29 | `encoach_adaptive_ai` | Custom | AI services for diagnostics, plan generation, coaching, content generation | | 30 | `encoach_sis` | Custom | UTAS SIS integration (sync, mapping) | | 31 | `encoach_branding` | Custom | Whitelabeling configuration | +| 32 | `encoach_courseware` | Custom | Course chapters, chapter materials, chapter progress tracking, AI workbench for content generation | +| 33 | `encoach_communication` | Custom | Discussion boards, threaded posts, announcements, direct messaging | +| 34 | `encoach_notification` | Custom | Notification engine, configurable rules, email/in-app delivery, user preferences | +| 35 | `encoach_faq` | Custom | FAQ categories and items, role-filtered, searchable | -**Total: 8 OpenEduCat (ported) + 23 custom = 31 modules** +**Total: 8 OpenEduCat (ported) + 27 custom = 35 modules** --- @@ -611,17 +621,48 @@ Traditional institutional exams (midterms, finals) managed through OpenEduCat. S Exam-wrapper assignments where an EnCoach exam is assigned to students/classrooms. -### 13.2 API Endpoints +### 13.2 Enhanced Fields (Late Submission + Plagiarism) + +Add to `encoach.assignment`: + +| Field | Type | Description | +|-------|------|-------------| +| `late_deadline` | Datetime | Final late submission cutoff | +| `penalty_type` | Selection | `none`, `percentage`, `fixed_deduction` | +| `penalty_value` | Float | Penalty amount | +| `max_submissions` | Integer | Maximum allowed submissions (0 = unlimited) | +| `allow_extensions` | Boolean | Student extension requests | +| `plagiarism_enabled` | Boolean | Enable GPTZero plagiarism check | +| `plagiarism_max_checks` | Integer | Max plagiarism checks per submission | +| `reminder_count` | Integer | Number of reminders | +| `reminder_frequency` | Selection | `once`, `daily`, `custom` | + +### 13.3 Extension Request Model (`encoach.extension.request`) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one (`res.users`) | Requesting student | +| `assignment_id` | Many2one | Target assignment | +| `reason` | Text | Justification | +| `requested_date` | Datetime | New deadline | +| `status` | Selection | `pending`, `approved`, `rejected` | +| `approved_by` | Many2one | Approving teacher | +| `response_note` | Text | Teacher response | + +### 13.4 API Endpoints | Method | Path | Auth | Description | |--------|------|------|-------------| | `GET` | `/api/assignments` | JWT | Paginated assignments | | `GET` | `/api/assignments/{id}` | JWT | Assignment detail | -| `POST` | `/api/assignments` | JWT | Create assignment | +| `POST` | `/api/assignments` | JWT | Create assignment (includes late submission fields) | | `PATCH` | `/api/assignments/{id}` | JWT | Update assignment | | `DELETE` | `/api/assignments/{id}` | JWT | Delete assignment | | `POST` | `/api/assignments/{id}/archive` | JWT | Archive assignment | | `POST` | `/api/assignments/{id}/start` | JWT | Start assignment (student) | +| `POST` | `/api/assignments/{id}/request-extension` | JWT (student) | Request deadline extension | +| `GET` | `/api/assignments/{id}/extension-requests` | JWT (teacher) | List extension requests | +| `POST` | `/api/extension-requests/{id}/respond` | JWT (teacher) | Approve/reject extension | --- @@ -1107,32 +1148,431 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u --- -## 25. Approval Workflows +## 25. Approval Workflows (Enhanced) ### 25.1 Model (`encoach.approval.workflow`) | Field | Type | Description | |-------|------|-------------| | `name` | Char | Workflow name | -| `type` | Selection | `exam_publish`, `assignment_publish`, `content_publish` | -| `steps` | One2many | Approval steps | +| `type` | Selection | `exam_publish`, `assignment_publish`, `content_publish`, `material_publish` | +| `stage_ids` | One2many | Approval stages (ordered) | | `entity_id` | Many2one | Entity | +| `allow_bypass` | Boolean | Whether bypass is allowed | | `active` | Boolean | Active flag | -### 25.2 API Endpoints +### 25.2 Model (`encoach.approval.stage`) + +| Field | Type | Description | +|-------|------|-------------| +| `workflow_id` | Many2one | Parent workflow | +| `sequence` | Integer | Stage order | +| `approver_id` | Many2one | Assigned approver (`res.users`) | +| `max_days` | Integer | Maximum days before auto-escalation | +| `auto_escalate` | Boolean | Whether to auto-escalate on timeout | +| `notification_email` | Char | Email for stage notifications | +| `status` | Selection | `pending`, `approved`, `rejected`, `escalated`, `bypassed` | +| `comment` | Text | Reviewer comment | +| `acted_at` | Datetime | When action was taken | + +### 25.3 Model (`encoach.approval.request`) + +| Field | Type | Description | +|-------|------|-------------| +| `workflow_id` | Many2one | Workflow template | +| `res_model` | Char | Target model (e.g., `encoach.exam`) | +| `res_id` | Integer | Target record ID | +| `current_stage_id` | Many2one | Current active stage | +| `requester_id` | Many2one | User who submitted for approval | +| `state` | Selection | `in_progress`, `approved`, `rejected`, `bypassed` | +| `bypass_reason` | Text | Justification if bypassed | +| `created_at` | Datetime | Request creation time | + +### 25.4 API Endpoints | Method | Path | Auth | Description | |--------|------|------|-------------| | `GET` | `/api/approval-workflows` | JWT | Paginated workflows | -| `POST` | `/api/approval-workflows` | JWT | Create workflow | -| `PATCH` | `/api/approval-workflows/{id}` | JWT | Update workflow | +| `POST` | `/api/approval-workflows` | JWT | Create workflow with stages | +| `GET` | `/api/approval-workflows/{id}` | JWT | Get workflow with stages | +| `PATCH` | `/api/approval-workflows/{id}` | JWT | Update workflow and stages | | `DELETE` | `/api/approval-workflows/{id}` | JWT | Delete workflow | +| `POST` | `/api/approval-requests` | JWT | Submit item for approval | +| `GET` | `/api/approval-requests` | JWT | List approval requests (filter: state, type) | +| `POST` | `/api/approval-requests/{id}/approve` | JWT | Approve current stage | +| `POST` | `/api/approval-requests/{id}/reject` | JWT | Reject at current stage | +| `POST` | `/api/approval-requests/{id}/bypass` | JWT | Bypass approval (requires justification) | +| `POST` | `/api/approval-requests/{id}/return` | JWT | Return to specific stage | + +### 25.5 Cron: Auto-Escalation + +A server cron runs daily to check approval stages that have exceeded `max_days`. For stages with `auto_escalate = True`, the system automatically advances to the next stage and sends a notification email to the new approver with escalation reason. --- -## 26. Non-Functional Requirements +## 26. Courseware and Content Delivery -### 26.1 Performance +**Module:** `encoach_courseware` +**Dependencies:** `encoach_core`, `openeducat_core`, `encoach_ai` + +### 26.1 Model (`encoach.course.chapter`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char (required) | Chapter title | +| `course_id` | Many2one (`op.course`) | Parent course | +| `sequence` | Integer | Display order | +| `description` | Text | Chapter description | +| `start_date` | Datetime | Scheduled start date | +| `end_date` | Datetime | Optional end date | +| `unlock_mode` | Selection | `auto_date`, `manual`, `prerequisite` | +| `is_unlocked` | Boolean | Current unlock status | +| `topic_id` | Many2one (`encoach.topic`) | Bridge to adaptive engine | +| `material_ids` | One2many | Chapter materials | +| `assignment_ids` | Many2many (`encoach.assignment`) | Linked assignments | +| `exam_ids` | Many2many (`encoach.exam`) | Linked exams/quizzes | +| `active` | Boolean | Soft-delete flag | + +### 26.2 Model (`encoach.chapter.material`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char (required) | Material title | +| `chapter_id` | Many2one | Parent chapter | +| `type` | Selection | `pdf`, `document`, `video`, `audio`, `image`, `link`, `article` | +| `file` | Binary (attachment=True) | Uploaded file | +| `url` | Char | External URL | +| `description` | Text | Description | +| `sequence` | Integer | Display order | +| `allow_download` | Boolean | Student download permission | +| `is_book` | Boolean | Course book flag | +| `book_chapters` | Text | JSON book chapter structure | +| `active` | Boolean | Soft-delete flag | + +### 26.3 Model (`encoach.chapter.progress`) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one (`res.users`) | Student | +| `chapter_id` | Many2one | Chapter | +| `status` | Selection | `not_started`, `in_progress`, `completed` | +| `started_at` | Datetime | First access time | +| `completed_at` | Datetime | Completion time | +| `materials_completed` | Integer | Count of materials viewed | +| `materials_total` | Integer | Computed total materials | + +### 26.4 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/courses/{courseId}/chapters` | JWT | List chapters (ordered by sequence) | +| `POST` | `/api/courses/{courseId}/chapters` | JWT (teacher) | Create chapter | +| `GET` | `/api/chapters/{id}` | JWT | Chapter detail with material count | +| `PATCH` | `/api/chapters/{id}` | JWT (teacher) | Update chapter | +| `DELETE` | `/api/chapters/{id}` | JWT (teacher) | Soft-delete chapter | +| `POST` | `/api/chapters/{id}/unlock` | JWT (teacher) | Manually unlock | +| `POST` | `/api/chapters/{id}/lock` | JWT (teacher) | Manually lock | +| `PATCH` | `/api/courses/{courseId}/chapters/reorder` | JWT (teacher) | Reorder (body: `{ids: []}`) | +| `GET` | `/api/chapters/{id}/progress` | JWT | Student progress | +| `POST` | `/api/chapters/{id}/progress/complete` | JWT (student) | Mark chapter completed | +| `GET` | `/api/chapters/{chapterId}/materials` | JWT | List materials | +| `POST` | `/api/chapters/{chapterId}/materials` | JWT (teacher) | Upload material (multipart) | +| `PATCH` | `/api/materials/{id}` | JWT (teacher) | Update material metadata | +| `DELETE` | `/api/materials/{id}` | JWT (teacher) | Delete material | +| `GET` | `/api/materials/{id}/download` | JWT | Download file (streaming response) | +| `POST` | `/api/materials/{id}/viewed` | JWT (student) | Record material view | +| `PATCH` | `/api/chapters/{chapterId}/materials/reorder` | JWT (teacher) | Reorder materials | + +### 26.5 AI Workbench Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/workbench/generate-outline` | JWT (teacher) | AI generates course outline from requirements (topic, objectives, complexity) | +| `POST` | `/api/workbench/generate-chapter` | JWT (teacher) | AI generates content for a specific chapter | +| `POST` | `/api/workbench/generate-rubric` | JWT (teacher) | AI generates grading rubric | +| `POST` | `/api/workbench/regenerate` | JWT (teacher) | Regenerate specific section | +| `POST` | `/api/workbench/suggest-materials` | JWT (teacher) | AI suggests supplementary materials based on student performance profiles | +| `POST` | `/api/workbench/publish` | JWT (teacher) | Publish generated content to course chapters (may trigger approval workflow) | + +AI Workbench uses GPT-4o (temp 0.7 for generation) and calls `encoach_ai` service layer. + +### 26.6 Cron: Auto-Unlock Chapters + +Server cron runs every hour. For chapters with `unlock_mode = 'auto_date'` and `start_date <= now()` and `is_unlocked = False`, set `is_unlocked = True` and trigger notification. + +--- + +## 27. Communication System + +**Module:** `encoach_communication` +**Dependencies:** `encoach_core`, `openeducat_core` + +### 27.1 Model (`encoach.discussion.board`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char (required) | Board title | +| `course_id` | Many2one (`op.course`) | Associated course | +| `batch_id` | Many2one (`op.batch`) | Associated batch (optional) | +| `chapter_id` | Many2one (`encoach.course.chapter`) | Associated chapter (optional) | +| `assignment_id` | Many2one | Associated assignment (optional) | +| `is_enabled` | Boolean | Teacher toggle | +| `allow_student_posts` | Boolean | Student thread creation permission | +| `post_count` | Integer | Computed count of posts | + +### 27.2 Model (`encoach.discussion.post`) + +| Field | Type | Description | +|-------|------|-------------| +| `board_id` | Many2one | Parent board | +| `parent_id` | Many2one (self) | Parent post for threading | +| `author_id` | Many2one (`res.users`) | Author | +| `title` | Char | Thread title (root posts only) | +| `content` | Text | Post body (markdown) | +| `attachment_ids` | Many2many (`ir.attachment`) | File attachments | +| `is_pinned` | Boolean | Teacher pin | +| `is_resolved` | Boolean | Resolved flag (Q&A mode) | +| `reply_count` | Integer | Computed child count | +| `created_at` | Datetime | Post timestamp | + +### 27.3 Model (`encoach.announcement`) + +| Field | Type | Description | +|-------|------|-------------| +| `title` | Char (required) | Announcement title | +| `content` | Text | Body (markdown) | +| `author_id` | Many2one (`res.users`) | Author | +| `course_id` | Many2one (`op.course`) | Target course (null = system-wide) | +| `batch_id` | Many2one (`op.batch`) | Target batch (null = all batches) | +| `priority` | Selection | `normal`, `important`, `urgent` | +| `is_published` | Boolean | Published status | +| `published_at` | Datetime | Publish timestamp | +| `expires_at` | Datetime | Expiry time | +| `send_email` | Boolean | Also send via email | +| `attachment_ids` | Many2many (`ir.attachment`) | Attachments | + +### 27.4 Model (`encoach.message`) + +| Field | Type | Description | +|-------|------|-------------| +| `sender_id` | Many2one (`res.users`) | Sender | +| `recipient_id` | Many2one (`res.users`) | Recipient | +| `subject` | Char | Subject line | +| `content` | Text | Message body | +| `is_read` | Boolean | Read flag | +| `read_at` | Datetime | Read timestamp | +| `attachment_ids` | Many2many (`ir.attachment`) | Attachments | +| `send_email_copy` | Boolean | Send email copy | +| `created_at` | Datetime | Sent time | + +### 27.5 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/discussion-boards` | JWT | List boards (filter: `course_id`, `batch_id`) | +| `POST` | `/api/discussion-boards` | JWT (teacher) | Create board | +| `PATCH` | `/api/discussion-boards/{id}` | JWT (teacher) | Update settings | +| `GET` | `/api/discussion-boards/{id}/posts` | JWT | Paginated posts (threaded) | +| `POST` | `/api/discussion-boards/{id}/posts` | JWT | Create post/reply | +| `PATCH` | `/api/posts/{id}` | JWT | Update own post | +| `DELETE` | `/api/posts/{id}` | JWT (teacher/admin) | Delete post | +| `POST` | `/api/posts/{id}/pin` | JWT (teacher) | Pin/unpin toggle | +| `POST` | `/api/posts/{id}/resolve` | JWT (teacher) | Mark as resolved | +| `GET` | `/api/announcements` | JWT | List announcements (filter: `course_id`, `priority`) | +| `POST` | `/api/announcements` | JWT (teacher/admin) | Create announcement | +| `PATCH` | `/api/announcements/{id}` | JWT | Update | +| `DELETE` | `/api/announcements/{id}` | JWT | Delete | +| `POST` | `/api/announcements/{id}/publish` | JWT | Publish | +| `GET` | `/api/messages` | JWT | Inbox (filter: `is_read`) | +| `GET` | `/api/messages/sent` | JWT | Sent messages | +| `POST` | `/api/messages` | JWT | Send message | +| `GET` | `/api/messages/{id}` | JWT | Message detail (auto-marks read) | +| `DELETE` | `/api/messages/{id}` | JWT | Delete message | +| `GET` | `/api/messages/unread-count` | JWT | Unread count `{count: N}` | + +### 27.6 Email Integration + +When `send_email = True` on announcements or `send_email_copy = True` on messages, the module uses Odoo's `mail.thread` mixin to send emails through the configured outgoing mail server. + +--- + +## 28. Notification Engine + +**Module:** `encoach_notification` +**Dependencies:** `encoach_core` + +### 28.1 Model (`encoach.notification`) + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one (`res.users`) | Recipient | +| `title` | Char | Notification title | +| `message` | Text | Body | +| `type` | Selection | `deadline`, `chapter_unlock`, `result_release`, `announcement`, `assignment`, `exam`, `message`, `system` | +| `action_url` | Char | Frontend URL to navigate to | +| `is_read` | Boolean | Read status | +| `read_at` | Datetime | Read timestamp | +| `channel` | Selection | `in_app`, `email`, `both` | +| `created_at` | Datetime | Created time | + +### 28.2 Model (`encoach.notification.rule`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Rule name | +| `event_type` | Selection | `assignment_due`, `exam_due`, `chapter_unlock`, `result_release`, `submission_graded`, `extension_response` | +| `days_before` | Integer | Days before event to trigger | +| `frequency` | Selection | `once`, `daily`, `custom` | +| `custom_intervals` | Text (JSON) | Custom intervals array (e.g., `[7, 3, 1]`) | +| `channel` | Selection | `in_app`, `email`, `both` | +| `entity_id` | Many2one | Entity scope | +| `active` | Boolean | Active flag | + +### 28.3 Model (`encoach.notification.preferences`) + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one (`res.users`) | One per user | +| `email_enabled` | Boolean | Master email toggle | +| `assignment_alerts` | Boolean | Assignment notifications | +| `exam_alerts` | Boolean | Exam notifications | +| `chapter_alerts` | Boolean | Chapter unlock notifications | +| `announcement_alerts` | Boolean | Announcement notifications | +| `message_alerts` | Boolean | Message notifications | + +### 28.4 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/notifications` | JWT | Paginated list (filter: `type`, `is_read`) | +| `POST` | `/api/notifications/{id}/read` | JWT | Mark as read | +| `POST` | `/api/notifications/read-all` | JWT | Mark all as read | +| `GET` | `/api/notifications/unread-count` | JWT | `{count: N}` | +| `GET` | `/api/notification-rules` | JWT (admin) | List rules | +| `POST` | `/api/notification-rules` | JWT (admin) | Create rule | +| `PATCH` | `/api/notification-rules/{id}` | JWT (admin) | Update rule | +| `DELETE` | `/api/notification-rules/{id}` | JWT (admin) | Delete rule | +| `GET` | `/api/notification-preferences` | JWT | Get user preferences | +| `PATCH` | `/api/notification-preferences` | JWT | Update preferences | + +### 28.5 Crons + +1. **Deadline Reminders:** Runs daily. Checks all active rules, matches upcoming events (assignments, exams) within `days_before`, creates notifications and sends emails per user preferences. +2. **Chapter Unlock Notifications:** Triggered by the courseware cron when chapters are auto-unlocked. + +--- + +## 29. FAQ System + +**Module:** `encoach_faq` +**Dependencies:** `encoach_core` + +### 29.1 Model (`encoach.faq.category`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Category name | +| `sequence` | Integer | Display order | +| `icon` | Char | Icon identifier | +| `audience` | Selection | `student`, `entity`, `both` | +| `active` | Boolean | Active flag | + +### 29.2 Model (`encoach.faq.item`) + +| Field | Type | Description | +|-------|------|-------------| +| `question` | Char | Question text | +| `answer` | Text | Answer (markdown, embedded images/video) | +| `category_id` | Many2one | Parent category | +| `audience` | Selection | `student`, `entity`, `both` | +| `image` | Binary | Optional image | +| `video_url` | Char | Optional video URL | +| `sequence` | Integer | Display order | +| `active` | Boolean | Active flag | + +### 29.3 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/faq/categories` | Public/JWT | List categories (filter: `audience`) | +| `POST` | `/api/faq/categories` | JWT (admin) | Create category | +| `PATCH` | `/api/faq/categories/{id}` | JWT (admin) | Update category | +| `DELETE` | `/api/faq/categories/{id}` | JWT (admin) | Delete category | +| `GET` | `/api/faq/items` | Public/JWT | List items (filter: `category_id`, `audience`, `search`) | +| `POST` | `/api/faq/items` | JWT (admin) | Create item | +| `PATCH` | `/api/faq/items/{id}` | JWT (admin) | Update item | +| `DELETE` | `/api/faq/items/{id}` | JWT (admin) | Delete item | + +--- + +## 30. Plagiarism Detection + +**Module enhancement:** `encoach_ai_grading` (add plagiarism sub-service) + +### 30.1 Plagiarism Report Storage + +Add to `encoach.submission` or create `encoach.plagiarism.report`: + +| Field | Type | Description | +|-------|------|-------------| +| `submission_id` | Many2one | Target submission | +| `overall_score` | Float | AI probability score (0-1) | +| `per_sentence` | Text (JSON) | Per-sentence analysis from GPTZero | +| `report_pdf` | Binary | Generated PDF report | +| `checked_at` | Datetime | When check was run | + +### 30.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/plagiarism/check` | JWT (teacher) | Submit text for GPTZero analysis | +| `GET` | `/api/plagiarism/report/{submissionId}` | JWT | Get plagiarism report | +| `GET` | `/api/plagiarism/report/{submissionId}/download` | JWT | Download PDF report | + +### 30.3 Integration + +- Uses GPTZero `v2/predict/text` endpoint (already configured in `encoach_ai_grading`) +- Can be enabled/disabled per assignment via `plagiarism_enabled` boolean on `encoach.assignment` +- Configurable max submissions for plagiarism check via `plagiarism_max_checks` integer + +--- + +## 31. Official Exam Access + +**Module enhancement:** `encoach_exam` (add official access modes) + +### 31.1 Model Extensions + +Add to `encoach.exam`: + +| Field | Type | Description | +|-------|------|-------------| +| `is_exercise` | Boolean | Exercise (practice, no journey tracking) vs Exam | +| `is_official` | Boolean | Official exam flag | +| `access_mode` | Selection | `normal`, `link`, `landing_page`, `separate_login` | +| `access_token` | Char | Unique access token (auto-generated) | +| `access_code` | Char | Exam access code | +| `activation_start` | Datetime | Exam start time | +| `activation_end` | Datetime | Exam end time | +| `generate_unique_per_student` | Boolean | AI generates unique variant per student | +| `reminder_count` | Integer | Number of reminders to send | +| `reminder_frequency` | Selection | `once`, `daily`, `custom` | + +### 31.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/exam/{id}/generate-link` | JWT (teacher) | Generate unique access token/URL | +| `GET` | `/api/exam/access/{token}` | Public | Access exam via token (validates token, returns exam info) | +| `POST` | `/api/exam/official-login` | Public | Login with exam code + credentials | +| `POST` | `/api/exam/{id}/suspend` | JWT (teacher) | Suspend exam | +| `POST` | `/api/exam/{id}/revoke` | JWT (teacher) | Revoke exam access | + +--- + +## 32. Non-Functional Requirements + +### 32.1 Performance | ID | Requirement | |----|-------------| @@ -1140,7 +1580,7 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u | NFR-PERF-02 | AI endpoints may take up to 30s (use async job for long operations) | | NFR-PERF-03 | Pagination: default `size=20`, max `size=100` | -### 26.2 Security +### 32.2 Security | ID | Requirement | |----|-------------| @@ -1151,7 +1591,7 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u | NFR-SEC-05 | File upload size limit: 50MB | | NFR-SEC-06 | API keys stored in `ir.config_parameter`, never in code | -### 26.3 Scalability +### 32.3 Scalability | ID | Requirement | |----|-------------| @@ -1159,7 +1599,7 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u | NFR-SCALE-02 | Support 50+ subjects, 500+ topics per subject, 1000+ resources per subject | | NFR-SCALE-03 | Database indices on all foreign keys and frequently filtered fields | -### 26.4 Reliability +### 32.4 Reliability | ID | Requirement | |----|-------------| @@ -1167,7 +1607,7 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u | NFR-REL-02 | Webhook processing is idempotent | | NFR-REL-03 | Soft-delete for resources (preserve completion records) | -### 26.5 API Conventions +### 32.5 API Conventions | Convention | Detail | |-----------|--------| @@ -1181,7 +1621,7 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u --- -## 27. Implementation Priority +## 33. Implementation Priority | Priority | Modules | Rationale | |----------|---------|-----------| @@ -1190,25 +1630,33 @@ Files are stored as `ir.attachment` records. For production, configure Odoo to u | **P1** | `encoach_taxonomy`, `encoach_adaptive`, `encoach_adaptive_api`, `encoach_adaptive_ai` | Core adaptive learning loop | | **P1** | `encoach_exam`, `encoach_ai_generation`, `encoach_ai_grading` | Exam engine | | **P1** | `encoach_resources` | Learning content | +| **P2** | `encoach_courseware` (chapters, materials, progress, AI workbench) | Structured course delivery | +| **P2** | `encoach_communication` (discussions, announcements, messaging) | Collaboration | | **P2** | `openeducat_timetable`, `openeducat_attendance`, `openeducat_classroom` (port to v19) | LMS timetable/attendance | | **P2** | `openeducat_admission` (port to v19) + admission endpoints | Enrollment workflow | | **P2** | Academic years/terms, departments endpoints | Institutional calendar | | **P2** | `encoach_ai`, `encoach_ai_media` | AI services + media | | **P2** | `encoach_assignment`, `encoach_classroom` | Assignments + groups | +| **P3** | `encoach_notification` (rules, email delivery, preferences) | User engagement | +| **P3** | Enhanced approval workflows (stages, escalation, bypass) | Governance | +| **P3** | Plagiarism detection (GPTZero integration) | Academic integrity | +| **P3** | Official exam access modes (link, landing, separate login) | Exam security | +| **P3** | Late submission handling, extension requests | Assignment workflow | | **P3** | `openeducat_exam` (port to v19) + institutional exam endpoints | Institutional assessment | | **P3** | `openeducat_assignment` (port to v19) + submission endpoints | Homework workflow | | **P3** | Subject registration endpoints | Student subject selection | | **P3** | `encoach_training`, analytics endpoints | Training + analytics | | **P3** | `encoach_sis`, `encoach_branding` | University integration | +| **P4** | `encoach_faq` (categories, items, role-filtered) | User support | | **P4** | `encoach_subscription` (Stripe, PayPal, Paymob) | Payments | | **P4** | `encoach_ticket` | Support | -| **P4** | Approval workflows, storage | Operational features | +| **P4** | Storage | Operational features | --- ## Appendix A: Complete Endpoint Summary -Total API endpoints: **200+** +Total API endpoints: **280+** | Service Area | Endpoint Count | |-------------|---------------| @@ -1236,7 +1684,15 @@ Total API endpoints: **200+** | Subscriptions & Payments | 8 + 3 webhooks | | Tickets | 4 | | Storage | 2 | -| Approval Workflows | 4 | +| Approval Workflows (Enhanced) | 11 | +| **Courseware (Chapters + Materials + Workbench)** | **23** | +| **Discussion Boards + Posts** | **9** | +| **Announcements** | **5** | +| **Messaging** | **6** | +| **Notifications + Rules + Preferences** | **10** | +| **FAQ (Categories + Items)** | **8** | +| **Plagiarism Detection** | **3** | +| **Official Exam Access** | **5** | --- @@ -1273,9 +1729,31 @@ res.users ──extends──> encoach.user ├── op.exam.session ──> op.exam ──> op.exam.attendees │ └── op.marksheet.register ──> op.marksheet.line │ - └── op.assignment ──> op.assignment.sub.line (submissions) + ├── op.assignment ──> op.assignment.sub.line (submissions) + │ + ├── encoach.course.chapter ──> op.course + │ ├── encoach.chapter.material + │ ├── encoach.chapter.progress ──> res.users + │ └── encoach.topic (bridge to adaptive) + │ + ├── encoach.discussion.board ──> op.course / op.batch / encoach.course.chapter + │ └── encoach.discussion.post (self-referencing for threads) + │ + ├── encoach.announcement ──> op.course / op.batch + │ + ├── encoach.message ──> res.users (sender/recipient) + │ + ├── encoach.notification ──> res.users + │ └── encoach.notification.rule (event triggers) + │ + ├── encoach.faq.category ──> encoach.faq.item + │ + ├── encoach.approval.workflow ──> encoach.approval.stage + │ └── encoach.approval.request + │ + └── encoach.plagiarism.report ──> submission ``` --- -*This SRS is the definitive backend specification for the EnCoach platform on Odoo 19. It covers all 200+ REST API endpoints expected by the React frontend, all Odoo models (OpenEduCat + custom), and all AI service integrations.* +*This SRS is the definitive backend specification for the EnCoach platform on Odoo 19. It covers all 280+ REST API endpoints expected by the React frontend, 35 Odoo modules (8 OpenEduCat + 27 custom), and all AI service integrations.* diff --git a/docs/ENCOACH_UNIFIED_SRS.md b/docs/ENCOACH_UNIFIED_SRS.md index 73f648f..ebf819c 100644 --- a/docs/ENCOACH_UNIFIED_SRS.md +++ b/docs/ENCOACH_UNIFIED_SRS.md @@ -61,11 +61,25 @@ 34. [Institutional Exam Sessions](#34-institutional-exam-sessions) 35. [Assignment File Submissions](#35-assignment-file-submissions) -**Part IX -- Technical Specifications** -36. [Data Models](#36-data-models) -37. [REST API Specification](#37-rest-api-specification) -38. [Frontend Page Inventory](#38-frontend-page-inventory) -39. [Non-Functional Requirements](#39-non-functional-requirements) +**Part IX -- Courseware and Content Delivery** +36. [Course Chapters](#36-course-chapters) +37. [Chapter Materials](#37-chapter-materials) +38. [AI Workbench for Course Content](#38-ai-workbench-for-course-content) + +**Part X -- Communication** +39. [Discussion Boards](#39-discussion-boards) +40. [Announcements](#40-announcements) +41. [Messaging](#41-messaging) + +**Part XI -- Notifications and FAQ** +42. [Notification Engine](#42-notification-engine) +43. [FAQ System](#43-faq-system) + +**Part XII -- Technical Specifications** +44. [Data Models](#44-data-models) +45. [REST API Specification](#45-rest-api-specification) +46. [Frontend Page Inventory](#46-frontend-page-inventory) +47. [Non-Functional Requirements](#47-non-functional-requirements) --- @@ -352,9 +366,9 @@ The current permission model is IELTS-hardcoded (`generate_reading`, `createWrit | FR-SIDE-03 | Logout ends session and clears state | | FR-SIDE-04 | Ticket badge shows assigned count | -**Student sidebar:** Dashboard, Subjects, Courses, Subject Registration, Assignments, Grades, Attendance, Timetable, Profile +**Student sidebar:** Dashboard, Subjects, Courses, Subject Registration, Assignments, Grades, Attendance, Timetable, Discussions, Messages, Announcements, Journey, Profile -**Teacher sidebar:** Dashboard, Courses, Assignments, Attendance, Students, Timetable, Profile +**Teacher sidebar:** Dashboard, Courses, Assignments, Attendance, Students, Timetable, Discussions, Announcements, Profile **Admin sidebar (grouped):** @@ -723,15 +737,31 @@ Courses are managed through OpenEduCat models exposed via REST API. The frontend | FR-EX-05 | Columns: title, creator, module, rubrics, difficulty, exercises, timer, access, created at | Production | | FR-EX-06 | Row actions: set public/private, edit, load, delete | Production | | FR-EX-07 | **NEW:** Subject filter (English, Math, IT) alongside module filter | New | +| FR-EX-08 | **NEW:** Exercise vs Exam differentiation -- `is_exercise` flag; exercises are self-paced practice (no journey tracking), exams are official graded assessments | Client | +| FR-EX-09 | **NEW:** `is_official` flag on exams -- official exams track to student journey and support special access modes | Client | +| FR-EX-10 | **NEW:** Official exam access modes: (1) unique shareable link, (2) landing page access, (3) separate login screen | Client | +| FR-EX-11 | **NEW:** Exam activation control -- teacher sets start date, end date, activation status | Client | +| FR-EX-12 | **NEW:** Different exam for each student option (AI generates unique variants per student) | Client | +| FR-EX-13 | **NEW:** Configurable reminder frequency -- number of reminders, notification via email and system notification | Client | +| FR-EX-14 | **NEW:** Exam suspend/revoke actions | Client | +| FR-EX-15 | **NEW:** Student inquiry and extension requests on exams | Client | -### 16.2 Rubrics (Production Parity) +### 16.2 Official Exam Access (NEW) + +| Access Mode | Description | Route | +|-------------|-------------|-------| +| **Link Access** | Teacher generates a unique URL; students access exam via the link without full platform login | `/exam/access/{token}` | +| **Landing Page** | Exam appears on the public landing page; students authenticate with exam code + credentials | `/exam/official/{code}` | +| **Separate Login** | Dedicated login screen for the exam only; no access to other platform features | `/exam/login/{examId}` | + +### 16.4 Rubrics (Production Parity) | ID | Requirement | |----|-------------| | FR-RUB-01-05 | Search, pagination, create rubric, filter dropdown, metadata and edit | | FR-RG-01-05 | Rubric groups: search, pagination, create, filter, edit/delete | -### 16.3 Exam Structures (Production Parity) +### 16.5 Exam Structures (Production Parity) | ID | Requirement | |----|-------------| @@ -803,13 +833,53 @@ Courses are managed through OpenEduCat models exposed via REST API. The frontend | IT Scenario | AI evaluation | GPT-4o evaluates against rubric | | All Writing | AI detection | GPTZero per-sentence analysis | -### 19.2 Approval Workflows (Production Parity) +### 19.2 Plagiarism Detection (NEW) -| ID | Requirement | -|----|-------------| -| FR-AWF-01 | List/filter workflows | -| FR-AWF-02 | Create templates / add workflow | +| ID | Requirement | Source | +|----|-------------|--------| +| FR-PLAG-01 | Enable/disable plagiarism check per assignment or exam | Client | +| FR-PLAG-02 | Automatic GPTZero analysis on submission | Client | +| FR-PLAG-03 | Downloadable plagiarism report (PDF) per submission | Client | +| FR-PLAG-04 | Configurable number of allowed submissions with plagiarism check | Client | +| FR-PLAG-05 | Teacher views plagiarism score and per-sentence analysis in grading interface | Client | +| FR-PLAG-06 | Aggregate plagiarism overview for assignment (flagged submissions count) | Client | + +**API Endpoints:** + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/plagiarism/check` | Run plagiarism check on text/submission | +| `GET` | `/api/plagiarism/report/{submissionId}` | Get plagiarism report | +| `GET` | `/api/plagiarism/report/{submissionId}/download` | Download report as PDF | + +### 19.3 Approval Workflows (Enhanced) + +| ID | Requirement | Source | +|----|-------------|--------| +| FR-AWF-01 | List/filter workflows | Production | +| FR-AWF-02 | Create templates / add workflow | Production | | FR-AWF-03 | **NEW:** AI Grading Assistant on workflow page | New frontend | +| FR-AWF-04 | **NEW:** Configurable approval stages with number of days per stage (shown as calendar) | Client | +| FR-AWF-05 | **NEW:** Auto-escalation -- if time passes, automatically move to next authority with highlighted reason | Client | +| FR-AWF-06 | **NEW:** Bypass option -- terminate approval flow with mandatory justification sent to final authority | Client | +| FR-AWF-07 | **NEW:** Comments saved through the approval process | Client | +| FR-AWF-08 | **NEW:** Status view of approval progress (first reviewer, rejected, final reviewer, etc.) | Client | +| FR-AWF-09 | **NEW:** Final authority can choose who to pass back the exam to | Client | +| FR-AWF-10 | **NEW:** Configurable email notifications per approval stage | Client | +| FR-AWF-11 | **NEW:** Approval applies to both exams and course materials | Client | + +**Approval Stage Model:** + +| Field | Type | Description | +|-------|------|-------------| +| `workflow_id` | Many2one | Parent workflow | +| `sequence` | Integer | Stage order | +| `approver_id` | Many2one | Approver user | +| `max_days` | Integer | Maximum days before auto-escalation | +| `notification_email` | Char | Email for notifications | +| `status` | Selection | `pending`, `approved`, `rejected`, `escalated`, `bypassed` | +| `comment` | Text | Reviewer comment | +| `acted_at` | Datetime | When action was taken | --- @@ -900,6 +970,34 @@ Each simulated AI component in the new frontend maps to a real backend service: | FR-ASG-04 | Breadcrumb navigation | | FR-ASG-05 | Assignment execution via `/exam?assignment={id}` | | FR-ASG-06 | **NEW:** Subject-scoped assignments (assign Math exams, IT exams, not just IELTS) | +| FR-ASG-07 | **NEW:** Late submission handling -- configurable late submission date/time with penalty structure | Client | +| FR-ASG-08 | **NEW:** Extension requests -- students can request deadline extensions through the platform | Client | +| FR-ASG-09 | **NEW:** Submission tracking -- status flow (start date, extension granted, submitted, in review, graded) | Client | +| FR-ASG-10 | **NEW:** Configurable number of allowed submissions per assignment | Client | +| FR-ASG-11 | **NEW:** Revision history -- track all submission versions per student | Client | +| FR-ASG-12 | **NEW:** Reminder notifications -- configurable frequency, sent via email and system notification | Client | + +### 25.2 Late Submission Policy + +| Field | Type | Description | +|-------|------|-------------| +| `late_deadline` | Datetime | Final late submission cutoff | +| `penalty_type` | Selection | `none`, `percentage`, `fixed_deduction` | +| `penalty_value` | Float | Penalty amount (e.g., 10 = 10% or 10 points) | +| `max_submissions` | Integer | Maximum allowed submissions (0 = unlimited) | +| `allow_extensions` | Boolean | Whether students can request extensions | + +### 25.3 Extension Request + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Requesting student | +| `assignment_id` | Many2one | Target assignment | +| `reason` | Text | Justification | +| `requested_date` | Datetime | Requested new deadline | +| `status` | Selection | `pending`, `approved`, `rejected` | +| `approved_by` | Many2one | Approving teacher | +| `response_note` | Text | Teacher response | --- @@ -1429,11 +1527,463 @@ Traditional course assignments where students submit files and teachers grade th --- -# Part IX -- Technical Specifications +# Part IX -- Courseware and Content Delivery -## 36. Data Models +This part covers the Moodle-style structured course delivery system: chapter-based content organization, material management, and AI-powered course content generation. -### 36.1 Existing Models (from `ielts-be-v0`) +--- + +## 36. Course Chapters + +### 36.1 Overview + +Courses are divided into chapters (modules). Teachers create chapters with scheduled start dates, content materials, and lock/unlock controls. Students progress through chapters sequentially or as unlocked by the teacher. + +### 36.2 Data Model (`encoach.course.chapter`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Chapter title | +| `course_id` | Many2one | Parent course (`op.course`) | +| `sequence` | Integer | Display order | +| `description` | Text | Chapter description | +| `start_date` | Datetime | Scheduled start date | +| `end_date` | Datetime | Optional end date | +| `unlock_mode` | Selection | `auto_date` (unlock when start_date reached), `manual` (teacher clicks), `prerequisite` (previous chapter completed) | +| `is_unlocked` | Boolean | Current unlock status | +| `topic_id` | Many2one | Optional link to `encoach.topic` (bridges to adaptive engine) | +| `material_ids` | One2many | Chapter materials | +| `assignment_ids` | Many2many | Linked assignments | +| `exam_ids` | Many2many | Linked exams/quizzes | +| `active` | Boolean | Soft-delete flag | + +### 36.3 Chapter Progress Model (`encoach.chapter.progress`) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `chapter_id` | Many2one | Chapter | +| `status` | Selection | `not_started`, `in_progress`, `completed` | +| `started_at` | Datetime | When student first accessed | +| `completed_at` | Datetime | When marked complete | +| `materials_completed` | Integer | Count of materials viewed/downloaded | +| `materials_total` | Integer | Total materials in chapter | + +### 36.4 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-CH-01 | Teacher creates chapters for a course with name, description, sequence | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-02 | Teacher sets chapter start date and unlock mode (auto/manual/prerequisite) | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-03 | Teacher reorders chapters via drag-and-drop | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-04 | Teacher manually unlocks/locks a chapter | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-05 | System auto-unlocks chapters when start_date is reached (cron job) | Backend | System | +| FR-CH-06 | Student sees unlocked chapters on course detail page | `/student/courses/:id` | Student | +| FR-CH-07 | Student views chapter content and materials | `/student/courses/:id/chapters/:chapterId` | Student | +| FR-CH-08 | System tracks per-student chapter progress | Backend | System | +| FR-CH-09 | Chapter completion notification sent to student | Backend | System | +| FR-CH-10 | Teacher views chapter progress per student | `/teacher/courses/:id/chapters` | Teacher | + +### 36.5 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/courses/{courseId}/chapters` | List chapters for course | +| `POST` | `/api/courses/{courseId}/chapters` | Create chapter | +| `GET` | `/api/chapters/{id}` | Get chapter detail with materials | +| `PATCH` | `/api/chapters/{id}` | Update chapter | +| `DELETE` | `/api/chapters/{id}` | Delete chapter | +| `POST` | `/api/chapters/{id}/unlock` | Manually unlock chapter | +| `POST` | `/api/chapters/{id}/lock` | Manually lock chapter | +| `PATCH` | `/api/courses/{courseId}/chapters/reorder` | Reorder chapters | +| `GET` | `/api/chapters/{id}/progress` | Get student progress for chapter | +| `POST` | `/api/chapters/{id}/progress/complete` | Mark chapter as completed | + +--- + +## 37. Chapter Materials + +### 37.1 Overview + +Each chapter contains materials: uploaded files (PDFs, documents), videos, audio, images, hyperlinks, and articles. Teachers control download permissions per material. + +### 37.2 Data Model (`encoach.chapter.material`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Material title | +| `chapter_id` | Many2one | Parent chapter | +| `type` | Selection | `pdf`, `document`, `video`, `audio`, `image`, `link`, `article` | +| `file` | Binary | Uploaded file (for pdf, document, video, audio, image) | +| `url` | Char | External URL (for link, article, or external video) | +| `description` | Text | Material description | +| `sequence` | Integer | Display order | +| `allow_download` | Boolean | Whether students can download the file | +| `is_book` | Boolean | Whether this material is a course book (multi-book support) | +| `book_chapters` | Text (JSON) | Book chapter structure (if following original book chapters) | +| `active` | Boolean | Soft-delete flag | + +### 37.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-MAT-01 | Teacher uploads materials (PDF, Word, video, audio, images) per chapter | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-02 | Teacher adds external links, articles, hyperlinks | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-03 | Teacher uploads books with chapter structure (follow original or custom) | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-04 | Teacher sets download enable/disable per material | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-05 | Teacher uploads teaching aids (video, audio, pictures, hyperlinks) | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-06 | Student views materials for unlocked chapters | `/student/courses/:id/chapters/:chapterId` | Student | +| FR-MAT-07 | Student downloads materials if download is enabled | `/student/courses/:id/chapters/:chapterId` | Student | +| FR-MAT-08 | System tracks which materials a student has viewed/downloaded | Backend | System | + +### 37.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/chapters/{chapterId}/materials` | List materials | +| `POST` | `/api/chapters/{chapterId}/materials` | Upload material (multipart) | +| `PATCH` | `/api/materials/{id}` | Update material metadata | +| `DELETE` | `/api/materials/{id}` | Delete material | +| `GET` | `/api/materials/{id}/download` | Download material file | +| `POST` | `/api/materials/{id}/viewed` | Mark material as viewed by student | +| `PATCH` | `/api/chapters/{chapterId}/materials/reorder` | Reorder materials | + +--- + +## 38. AI Workbench for Course Content + +### 38.1 Overview + +Teachers use the AI Workbench to generate course content automatically. The AI generates chapters, materials, exercises, and grading rubrics based on high-level requirements input by the teacher. + +### 38.2 AI Workbench Flow + +1. Teacher inputs: topic name, objectives, complexity level, target audience +2. AI generates: chapter structure with learning outcomes, reading content, exercises, multimedia suggestions +3. Teacher reviews generated content +4. Teacher can: modify, regenerate specific sections, add additional context +5. Teacher approves and publishes (follows approval workflow if configured) +6. AI can suggest additional materials based on selected student performance profiles + +### 38.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-WB-01 | Teacher opens AI Workbench from course page | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-02 | Teacher inputs high-level requirements (topic, objectives, complexity) | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-03 | AI generates course outline with chapters and learning outcomes | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-04 | AI generates reading content, exercises, and multimedia for each chapter | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-05 | AI generates grading rubrics based on assignment/exam complexity | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-06 | Teacher reviews and modifies AI-generated content | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-07 | Teacher can prompt AI to regenerate specific sections | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-08 | Teacher selects student profiles for AI to suggest additional materials based on performance | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-09 | Generated content follows approval workflow before publishing | Backend | System | + +### 38.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/workbench/generate-outline` | Generate course outline from requirements | +| `POST` | `/api/workbench/generate-chapter` | Generate content for a specific chapter | +| `POST` | `/api/workbench/generate-rubric` | Generate grading rubric | +| `POST` | `/api/workbench/regenerate` | Regenerate a specific section | +| `POST` | `/api/workbench/suggest-materials` | AI suggests materials based on student profiles | +| `POST` | `/api/workbench/publish` | Publish generated content to course chapters | + +--- + +# Part X -- Communication + +## 39. Discussion Boards + +### 39.1 Overview + +Per-class discussion boards enable student-to-student and student-to-teacher communication. Discussion boards can be attached to courses, chapters, or assignments. + +### 39.2 Data Models + +**`encoach.discussion.board`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Board title | +| `course_id` | Many2one | Associated course | +| `batch_id` | Many2one | Associated batch (optional) | +| `chapter_id` | Many2one | Associated chapter (optional) | +| `assignment_id` | Many2one | Associated assignment (optional) | +| `is_enabled` | Boolean | Whether teacher has enabled discussions | +| `allow_student_posts` | Boolean | Whether students can create new threads | +| `post_count` | Integer | Computed post count | + +**`encoach.discussion.post`** + +| Field | Type | Description | +|-------|------|-------------| +| `board_id` | Many2one | Parent board | +| `parent_id` | Many2one | Parent post (for replies, nested threads) | +| `author_id` | Many2one | Author user | +| `title` | Char | Post title (for root posts) | +| `content` | Text | Post content (supports markdown) | +| `attachment_ids` | Many2many | File attachments | +| `is_pinned` | Boolean | Pinned by teacher | +| `is_resolved` | Boolean | Marked as resolved (for Q&A) | +| `created_at` | Datetime | Post time | + +### 39.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-DISC-01 | Teacher enables/disables discussion board per course or chapter | `/teacher/courses/:id/discussions` | Teacher | +| FR-DISC-02 | Students create discussion threads | `/student/discussions` | Student | +| FR-DISC-03 | Students and teachers reply to threads (nested replies) | `/student/discussions`, `/teacher/courses/:id/discussions` | Both | +| FR-DISC-04 | Teacher pins important posts | `/teacher/courses/:id/discussions` | Teacher | +| FR-DISC-05 | Teacher marks posts as resolved | `/teacher/courses/:id/discussions` | Teacher | +| FR-DISC-06 | Students view other participants within the same class | `/student/discussions` | Student | +| FR-DISC-07 | File attachments on posts | Both pages | Both | + +### 39.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/discussion-boards` | List boards (filter: course_id, batch_id) | +| `POST` | `/api/discussion-boards` | Create board | +| `PATCH` | `/api/discussion-boards/{id}` | Update board settings | +| `GET` | `/api/discussion-boards/{id}/posts` | List posts for board (paginated) | +| `POST` | `/api/discussion-boards/{id}/posts` | Create post/reply | +| `PATCH` | `/api/posts/{id}` | Update post | +| `DELETE` | `/api/posts/{id}` | Delete post | +| `POST` | `/api/posts/{id}/pin` | Pin/unpin post | +| `POST` | `/api/posts/{id}/resolve` | Mark as resolved | + +--- + +## 40. Announcements + +### 40.1 Overview + +Teachers broadcast announcements to classes. System-wide announcements can be created by administrators. + +### 40.2 Data Model (`encoach.announcement`) + +| Field | Type | Description | +|-------|------|-------------| +| `title` | Char | Announcement title | +| `content` | Text | Announcement body (supports markdown) | +| `author_id` | Many2one | Author | +| `course_id` | Many2one | Target course (null = system-wide) | +| `batch_id` | Many2one | Target batch (null = all batches in course) | +| `priority` | Selection | `normal`, `important`, `urgent` | +| `is_published` | Boolean | Published status | +| `published_at` | Datetime | Publish time | +| `expires_at` | Datetime | Expiry time (optional) | +| `send_email` | Boolean | Also send via email | +| `attachment_ids` | Many2many | File attachments | + +### 40.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-ANN-01 | Teacher creates announcement for class/batch | `/teacher/announcements` | Teacher | +| FR-ANN-02 | Teacher sends announcement via platform and/or email | `/teacher/announcements` | Teacher | +| FR-ANN-03 | Admin creates system-wide announcements | `/admin/announcements` | Admin | +| FR-ANN-04 | Students view announcements on dashboard and dedicated page | `/student/announcements` | Student | +| FR-ANN-05 | Priority-based display (urgent announcements highlighted) | All dashboards | All | + +### 40.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/announcements` | List announcements (filter: course_id, priority) | +| `POST` | `/api/announcements` | Create announcement | +| `PATCH` | `/api/announcements/{id}` | Update announcement | +| `DELETE` | `/api/announcements/{id}` | Delete announcement | +| `POST` | `/api/announcements/{id}/publish` | Publish announcement | + +--- + +## 41. Messaging + +### 41.1 Overview + +Direct messaging between platform users. Teachers can message students individually. Students can message other students within the same class (if allowed). Platform can send emails through linked accounts. + +### 41.2 Data Model (`encoach.message`) + +| Field | Type | Description | +|-------|------|-------------| +| `sender_id` | Many2one | Sender user | +| `recipient_id` | Many2one | Recipient user | +| `subject` | Char | Message subject | +| `content` | Text | Message body | +| `is_read` | Boolean | Read status | +| `read_at` | Datetime | When read | +| `attachment_ids` | Many2many | File attachments | +| `send_email_copy` | Boolean | Also send copy via email | +| `created_at` | Datetime | Sent time | + +### 41.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-MSG-01 | Users send direct messages to other users | `/student/messages`, `/teacher/messages` | All | +| FR-MSG-02 | Inbox with read/unread filtering | `/student/messages` | All | +| FR-MSG-03 | Option to send email copy through the platform | Both pages | All | +| FR-MSG-04 | File attachments on messages | Both pages | All | +| FR-MSG-05 | Students see other participants within same class | `/student/messages` | Student | + +### 41.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/messages` | List messages (inbox, filter: unread) | +| `GET` | `/api/messages/sent` | List sent messages | +| `POST` | `/api/messages` | Send message | +| `GET` | `/api/messages/{id}` | Get message detail (marks as read) | +| `DELETE` | `/api/messages/{id}` | Delete message | +| `GET` | `/api/messages/unread-count` | Get unread message count | + +--- + +# Part XI -- Notifications and FAQ + +## 42. Notification Engine + +### 42.1 Overview + +Centralized notification system supporting both in-app and email notifications. Notifications are triggered by system events (deadlines, chapter unlocks, result releases, announcements) and can be configured by teachers and admins. + +### 42.2 Data Models + +**`encoach.notification`** + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one | Recipient user | +| `title` | Char | Notification title | +| `message` | Text | Notification body | +| `type` | Selection | `deadline`, `chapter_unlock`, `result_release`, `announcement`, `assignment`, `exam`, `message`, `system` | +| `action_url` | Char | URL to redirect to when clicked | +| `is_read` | Boolean | Read status | +| `read_at` | Datetime | When read | +| `channel` | Selection | `in_app`, `email`, `both` | +| `created_at` | Datetime | Created time | + +**`encoach.notification.rule`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Rule name | +| `event_type` | Selection | `assignment_due`, `exam_due`, `chapter_unlock`, `result_release`, `submission_graded`, `extension_response` | +| `days_before` | Integer | Days before event to send notification | +| `frequency` | Selection | `once`, `daily`, `custom` | +| `custom_intervals` | Text (JSON) | Custom reminder intervals (e.g., [7, 3, 1] days before) | +| `channel` | Selection | `in_app`, `email`, `both` | +| `entity_id` | Many2one | Entity scope | +| `active` | Boolean | Active flag | + +**`encoach.notification.preferences`** + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one | User | +| `email_enabled` | Boolean | Receive email notifications | +| `assignment_alerts` | Boolean | Assignment deadline alerts | +| `exam_alerts` | Boolean | Exam alerts | +| `chapter_alerts` | Boolean | Chapter unlock alerts | +| `announcement_alerts` | Boolean | Announcement alerts | +| `message_alerts` | Boolean | New message alerts | + +### 42.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-NOT-01 | In-app notification bell with unread count (existing NotificationDropdown enhanced) | All layouts | All | +| FR-NOT-02 | Email notifications for configured events | Backend | System | +| FR-NOT-03 | Admin configures notification rules (event type, timing, frequency) | `/admin/notification-rules` | Admin | +| FR-NOT-04 | Teacher sets reminder frequency for assignments and exams | Assignment/exam creation forms | Teacher | +| FR-NOT-05 | Students receive deadline alerts, chapter unlock alerts, result release alerts | Dashboard | Student | +| FR-NOT-06 | Users configure personal notification preferences | Profile pages | All | +| FR-NOT-07 | Notification action button redirects to relevant page | All layouts | All | + +### 42.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/notifications` | List notifications (paginated, filter: type, is_read) | +| `POST` | `/api/notifications/{id}/read` | Mark as read | +| `POST` | `/api/notifications/read-all` | Mark all as read | +| `GET` | `/api/notifications/unread-count` | Get unread count | +| `GET` | `/api/notification-rules` | List rules | +| `POST` | `/api/notification-rules` | Create rule | +| `PATCH` | `/api/notification-rules/{id}` | Update rule | +| `DELETE` | `/api/notification-rules/{id}` | Delete rule | +| `GET` | `/api/notification-preferences` | Get user preferences | +| `PATCH` | `/api/notification-preferences` | Update user preferences | + +--- + +## 43. FAQ System + +### 43.1 Overview + +Interactive FAQ system editable by super admin. FAQ items are organized by categories and filtered by target audience (student, entity, or both). Supports text, images, and video content. + +### 43.2 Data Models + +**`encoach.faq.category`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Category name | +| `sequence` | Integer | Display order | +| `icon` | Char | Icon identifier | +| `audience` | Selection | `student`, `entity`, `both` | +| `active` | Boolean | Active flag | + +**`encoach.faq.item`** + +| Field | Type | Description | +|-------|------|-------------| +| `question` | Char | Question text | +| `answer` | Text | Answer (supports markdown, embedded images/video) | +| `category_id` | Many2one | Parent category | +| `audience` | Selection | `student`, `entity`, `both` | +| `image` | Binary | Optional image | +| `video_url` | Char | Optional video URL | +| `sequence` | Integer | Display order | +| `active` | Boolean | Active flag | + +### 43.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-FAQ-01 | Super admin manages FAQ categories and items | `/admin/faq` | Admin | +| FR-FAQ-02 | Admin adds text, images, and video to FAQ answers | `/admin/faq` | Admin | +| FR-FAQ-03 | Admin sets audience filter per category/item (student, entity, both) | `/admin/faq` | Admin | +| FR-FAQ-04 | Students and entity users view FAQs filtered by their role | `/faq` | All | +| FR-FAQ-05 | Search bar to find FAQ items by keyword | `/faq` | All | +| FR-FAQ-06 | Interactive accordion-style display (click question to expand answer) | `/faq` | All | + +### 43.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/faq/categories` | List categories (filter: audience) | +| `POST` | `/api/faq/categories` | Create category | +| `PATCH` | `/api/faq/categories/{id}` | Update category | +| `DELETE` | `/api/faq/categories/{id}` | Delete category | +| `GET` | `/api/faq/items` | List items (filter: category_id, audience, search) | +| `POST` | `/api/faq/items` | Create item | +| `PATCH` | `/api/faq/items/{id}` | Update item | +| `DELETE` | `/api/faq/items/{id}` | Delete item | + +--- + +# Part XII -- Technical Specifications + +## 44. Data Models + +### 44.1 Existing Models (from `ielts-be-v0`) | Model | Module | Purpose | |-------|--------|---------| @@ -1461,7 +2011,7 @@ Traditional course assignments where students submit files and teachers grade th | `encoach.elai.avatar` | `encoach_ai_media` | ELAI avatar profiles | | `encoach.registration` | `encoach_registration` | Batch registration mixin | -### 36.2 New Models (Adaptive Learning Engine) +### 44.2 New Models (Adaptive Learning Engine) | Model | Module | Purpose | Key Fields | |-------|--------|---------|------------| @@ -1476,14 +2026,14 @@ Traditional course assignments where students submit files and teachers grade th | `encoach.resource.completion` | `encoach_adaptive` | Resource viewing tracking | `student_id`, `resource_id`, `viewed`, `time_spent_minutes`, `rating` | | `encoach.ai.content.cache` | `encoach_adaptive` | Cached AI-generated content | `topic_id`, `content_type`, `difficulty_level`, `content`, `model_used`, `review_status` | -### 36.3 New Models (SIS Integration) +### 44.3 New Models (SIS Integration) | Model | Module | Purpose | |-------|--------|---------| | `encoach.sis.sync` | `encoach_sis` | SIS sync job tracking | | `encoach.sis.mapping` | `encoach_sis` | Field mapping between SIS and EnCoach | -### 36.4 New Models (Branding) +### 44.4 New Models (Branding) | Model | Module | Purpose | |-------|--------|---------| @@ -1491,9 +2041,9 @@ Traditional course assignments where students submit files and teachers grade th --- -## 37. REST API Specification +## 45. REST API Specification -### 37.1 Existing Endpoints (81+) +### 45.1 Existing Endpoints (81+) All existing endpoints from the Odoo 19 backend remain. Key groups: @@ -1516,7 +2066,7 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | Storage | `/api/storage` | 2 | | Approvals | `/api/approval-workflows` | 3 | -### 37.2 New Endpoints (Adaptive Learning Engine, 40+) +### 45.2 New Endpoints (Adaptive Learning Engine, 40+) | Group | Method | Path | Description | |-------|--------|------|-------------| @@ -1568,7 +2118,7 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | | `GET` | `/api/analytics/subject` | Subject analytics | | | `GET` | `/api/analytics/content-gaps` | Content gap report | -### 37.3 New Endpoints (LMS API Bridge) +### 45.3 New Endpoints (LMS API Bridge) | Method | Path | Description | |--------|------|-------------| @@ -1581,7 +2131,7 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | `GET/POST` | `/api/attendance` | Attendance records | | `GET` | `/api/grades` | Gradebook | -### 37.4 New Endpoints (SIS Integration) +### 45.4 New Endpoints (SIS Integration) | Method | Path | Description | |--------|------|-------------| @@ -1590,7 +2140,7 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | `GET` | `/api/sis/mappings` | Field mappings | | `PATCH` | `/api/sis/mappings` | Update mappings | -### 37.5 New Endpoints (OpenEduCat Institutional LMS, 60+) +### 45.5 New Endpoints (OpenEduCat Institutional LMS, 60+) | Group | Method | Path | Description | |-------|--------|------|-------------| @@ -1642,9 +2192,70 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: --- -## 38. Frontend Page Inventory +### 45.6 New Endpoints (Courseware, Communication, Notifications, FAQ, 60+) -### 38.1 Auth Pages (3) +| Group | Method | Path | Description | +|-------|--------|------|-------------| +| **Chapters** | `GET` | `/api/courses/{courseId}/chapters` | List chapters | +| | `POST` | `/api/courses/{courseId}/chapters` | Create chapter | +| | `GET` | `/api/chapters/{id}` | Chapter detail | +| | `PATCH` | `/api/chapters/{id}` | Update chapter | +| | `DELETE` | `/api/chapters/{id}` | Delete chapter | +| | `POST` | `/api/chapters/{id}/unlock` | Unlock chapter | +| | `POST` | `/api/chapters/{id}/lock` | Lock chapter | +| | `PATCH` | `/api/courses/{courseId}/chapters/reorder` | Reorder | +| | `GET` | `/api/chapters/{id}/progress` | Progress | +| | `POST` | `/api/chapters/{id}/progress/complete` | Complete | +| **Materials** | `GET` | `/api/chapters/{chapterId}/materials` | List | +| | `POST` | `/api/chapters/{chapterId}/materials` | Upload | +| | `PATCH` | `/api/materials/{id}` | Update | +| | `DELETE` | `/api/materials/{id}` | Delete | +| | `GET` | `/api/materials/{id}/download` | Download | +| | `POST` | `/api/materials/{id}/viewed` | Mark viewed | +| **Workbench** | `POST` | `/api/workbench/generate-outline` | Generate outline | +| | `POST` | `/api/workbench/generate-chapter` | Generate chapter | +| | `POST` | `/api/workbench/generate-rubric` | Generate rubric | +| | `POST` | `/api/workbench/regenerate` | Regenerate section | +| | `POST` | `/api/workbench/suggest-materials` | Suggest materials | +| | `POST` | `/api/workbench/publish` | Publish content | +| **Discussions** | `GET/POST` | `/api/discussion-boards` | List/create boards | +| | `PATCH` | `/api/discussion-boards/{id}` | Update board | +| | `GET/POST` | `/api/discussion-boards/{id}/posts` | List/create posts | +| | `PATCH/DELETE` | `/api/posts/{id}` | Update/delete post | +| | `POST` | `/api/posts/{id}/pin` | Pin post | +| | `POST` | `/api/posts/{id}/resolve` | Resolve post | +| **Announcements** | `GET/POST` | `/api/announcements` | List/create | +| | `PATCH/DELETE` | `/api/announcements/{id}` | Update/delete | +| | `POST` | `/api/announcements/{id}/publish` | Publish | +| **Messages** | `GET` | `/api/messages` | Inbox | +| | `GET` | `/api/messages/sent` | Sent | +| | `POST` | `/api/messages` | Send | +| | `GET` | `/api/messages/{id}` | Detail | +| | `DELETE` | `/api/messages/{id}` | Delete | +| | `GET` | `/api/messages/unread-count` | Unread count | +| **Notifications** | `GET` | `/api/notifications` | List | +| | `POST` | `/api/notifications/{id}/read` | Mark read | +| | `POST` | `/api/notifications/read-all` | Read all | +| | `GET` | `/api/notifications/unread-count` | Count | +| | `GET/POST` | `/api/notification-rules` | Rules | +| | `PATCH/DELETE` | `/api/notification-rules/{id}` | Rule CRUD | +| | `GET/PATCH` | `/api/notification-preferences` | User prefs | +| **FAQ** | `GET/POST` | `/api/faq/categories` | Categories | +| | `PATCH/DELETE` | `/api/faq/categories/{id}` | Category CRUD | +| | `GET/POST` | `/api/faq/items` | Items | +| | `PATCH/DELETE` | `/api/faq/items/{id}` | Item CRUD | +| **Plagiarism** | `POST` | `/api/plagiarism/check` | Check text | +| | `GET` | `/api/plagiarism/report/{submissionId}` | Get report | +| | `GET` | `/api/plagiarism/report/{submissionId}/download` | Download PDF | +| **Exam Access** | `POST` | `/api/exam/{id}/generate-link` | Generate access link | +| | `GET` | `/api/exam/access/{token}` | Access via link | +| | `POST` | `/api/exam/official-login` | Official exam login | + +--- + +## 46. Frontend Page Inventory + +### 46.1 Auth Pages (3) | Route | Page | API Dependencies | |-------|------|-----------------| @@ -1652,7 +2263,7 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | `/register` | Register | `POST /api/register` | | `/forgot-password` | Forgot Password | `POST /api/reset/sendVerification` | -### 38.2 Student Pages (12+) +### 46.2 Student Pages (18+) | Route | Page | Key APIs | AI Components | |-------|------|----------|---------------| @@ -1670,8 +2281,13 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | `/student/timetable` | Timetable | `/api/timetable` | -- | | `/student/profile` | Profile | `/api/user` | -- | | `/student/subject-registration` | **NEW:** Subject Registration | `/api/subject-registrations/available`, `/api/subject-registrations` | -- | +| `/student/courses/:id/chapters/:chapterId` | **NEW:** Chapter View | `/api/chapters/{id}`, `/api/chapters/{chapterId}/materials` | -- | +| `/student/discussions` | **NEW:** Discussion Board | `/api/discussion-boards`, `/api/discussion-boards/{id}/posts` | -- | +| `/student/announcements` | **NEW:** Announcements | `/api/announcements` | -- | +| `/student/messages` | **NEW:** Messages | `/api/messages`, `/api/messages/unread-count` | -- | +| `/student/journey` | **NEW:** Student Journey | `/api/analytics/student`, `/api/proficiency` | -- | -### 38.3 Teacher Pages (10) +### 46.3 Teacher Pages (15+) | Route | Page | Key APIs | AI Components | |-------|------|----------|---------------| @@ -1685,15 +2301,24 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | `/teacher/students` | Students | `/api/users/list?type=student` | AiRiskBadge | | `/teacher/timetable` | Timetable | `/api/timetable` | -- | | `/teacher/profile` | Profile | `/api/user` | -- | +| `/teacher/courses/:id/chapters` | **NEW:** Course Chapters | `/api/courses/{courseId}/chapters` | -- | +| `/teacher/courses/:id/chapters/:chapterId` | **NEW:** Chapter Detail | `/api/chapters/{id}`, `/api/chapters/{chapterId}/materials` | -- | +| `/teacher/courses/:id/workbench` | **NEW:** AI Workbench | `/api/workbench/*` | AiCreationAssistant | +| `/teacher/courses/:id/discussions` | **NEW:** Discussion Board | `/api/discussion-boards`, `/api/discussion-boards/{id}/posts` | -- | +| `/teacher/announcements` | **NEW:** Announcements | `/api/announcements` | -- | -### 38.4 Public Pages (2) +### 46.4 Public Pages (4+) | Route | Page | Key APIs | AI Components | |-------|------|----------|---------------| | `/apply` | **NEW:** Admission Application | `/api/admissions`, `/api/admission-registers` | -- | | `/apply/status` | **NEW:** Application Status | `/api/admissions/{id}` | -- | +| `/exam/access/{token}` | **NEW:** Official Exam Access (Link) | `/api/exam/access/{token}` | -- | +| `/exam/official/{code}` | **NEW:** Official Exam Access (Landing) | `/api/exam/official-login` | -- | +| `/exam/login/{examId}` | **NEW:** Official Exam Login | `/api/exam/official-login` | -- | +| `/faq` | **NEW:** FAQ | `/api/faq/categories`, `/api/faq/items` | -- | -### 38.5 Admin Pages (38+) +### 46.5 Admin Pages (42+) | Route | Page | Key APIs | AI Components | |-------|------|----------|---------------| @@ -1736,10 +2361,13 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | `/admin/admission-register` | **NEW:** Admission Register | `/api/admission-registers` | -- | | `/admin/exam-sessions` | **NEW:** Institutional Exam Sessions | `/api/inst-exam-sessions`, `/api/inst-exams` | -- | | `/admin/marksheets` | **NEW:** Marksheet Manager | `/api/marksheets`, `/api/result-templates`, `/api/grade-config` | -- | +| `/admin/faq` | **NEW:** FAQ Manager | `/api/faq/categories`, `/api/faq/items` | -- | +| `/admin/notification-rules` | **NEW:** Notification Rules | `/api/notification-rules` | -- | +| `/admin/approval-config` | **NEW:** Approval Workflow Config | `/api/approval-workflows` | -- | --- -## 39. Non-Functional Requirements +## 47. Non-Functional Requirements | ID | Requirement | |----|-------------| @@ -1802,7 +2430,12 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | 30 | `openeducat_admission` | **OpenEduCat (port to v19)** | `op.admission`, `op.admission.register` | | 31 | `openeducat_facility` | **OpenEduCat (port to v19)** | `op.facility`, `op.facility.line` (dependency of classroom) | -**Total: 15 existing EnCoach + 8 new EnCoach + 8 OpenEduCat = 31 modules** +| 32 | `encoach_courseware` | **NEW** | Course chapters, chapter materials, chapter progress, AI workbench | +| 33 | `encoach_communication` | **NEW** | Discussion boards, posts, announcements, messaging | +| 34 | `encoach_notification` | **NEW** | Notification engine, notification rules, reminders, preferences | +| 35 | `encoach_faq` | **NEW** | FAQ categories and items, role-filtered | + +**Total: 15 existing EnCoach + 12 new EnCoach + 8 OpenEduCat = 35 modules** --- @@ -1821,6 +2454,14 @@ All existing endpoints from the Odoo 19 backend remain. Key groups: | **P3** | Spaced repetition, analytics dashboards | Progress optimization | | **P3** | Institutional exam sessions, marksheets, subject registration | Institutional assessment | | **P3** | Course assignment submissions (file upload, grading) | Homework workflow | +| **P2** | Courseware module (chapters, materials, progress tracking) | Structured course delivery | +| **P2** | Communication module (discussions, announcements, messaging) | Collaboration | +| **P3** | Notification engine (rules, email integration, reminders) | User engagement | +| **P3** | Enhanced approval workflows (timed stages, escalation, bypass) | Governance | +| **P3** | Plagiarism detection (GPTZero integration) | Academic integrity | +| **P3** | Official exam access modes (link, landing page, separate login) | Exam security | +| **P4** | FAQ system (admin-managed, role-filtered) | User support | +| **P4** | AI Workbench for course content generation | Content automation | | **P3** | SIS integration, whitelabeling | University integration | | **P4** | Content gap detection, FAISS tips per subject, batch optimizer | Operational efficiency | | **P4** | Payment system, subscription management | Commercial features | diff --git a/src/App.tsx b/src/App.tsx index c1eff7f..da6adce 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -79,6 +79,22 @@ import InstitutionalExamSessions from "@/pages/admin/InstitutionalExamSessions"; import MarksheetManager from "@/pages/admin/MarksheetManager"; import AdmissionApplication from "@/pages/AdmissionApplication"; import SubjectRegistrationPage from "@/pages/student/SubjectRegistrationPage"; +// Courseware pages +import CourseChapters from "@/pages/teacher/CourseChapters"; +import ChapterDetail from "@/pages/teacher/ChapterDetail"; +import AiWorkbench from "@/pages/teacher/AiWorkbench"; +import TeacherDiscussionBoard from "@/pages/teacher/TeacherDiscussionBoard"; +import TeacherAnnouncements from "@/pages/teacher/TeacherAnnouncements"; +import StudentChapterView from "@/pages/student/StudentChapterView"; +import StudentDiscussionBoard from "@/pages/student/StudentDiscussionBoard"; +import StudentAnnouncements from "@/pages/student/StudentAnnouncements"; +import StudentMessages from "@/pages/student/StudentMessages"; +import StudentJourney from "@/pages/student/StudentJourney"; +import FaqManager from "@/pages/admin/FaqManager"; +import NotificationRules from "@/pages/admin/NotificationRules"; +import ApprovalWorkflowConfig from "@/pages/admin/ApprovalWorkflowConfig"; +import OfficialExamAccess from "@/pages/OfficialExamAccess"; +import FaqPage from "@/pages/FaqPage"; import NotFound from "@/pages/NotFound"; import { queryClient } from "@/lib/query-client"; @@ -94,8 +110,12 @@ const App = () => ( } /> } /> } /> - {/* Public admission */} + {/* Public pages */} } /> + } /> + } /> + } /> + } /> {/* Student routes */} }> @@ -114,6 +134,11 @@ const App = () => ( } /> } /> } /> + } /> + } /> + } /> + } /> + } /> @@ -129,6 +154,11 @@ const App = () => ( } /> } /> } /> + } /> + } /> + } /> + } /> + } /> } /> @@ -183,6 +213,9 @@ const App = () => ( } /> } /> } /> + } /> + } /> + } /> diff --git a/src/components/AdminLmsLayout.tsx b/src/components/AdminLmsLayout.tsx index 58095d4..5e4eff3 100644 --- a/src/components/AdminLmsLayout.tsx +++ b/src/components/AdminLmsLayout.tsx @@ -27,6 +27,7 @@ import { Building2, History, CreditCard, Ticket, BookA, PenTool, Calendar, ChevronDown, HelpCircle, LucideIcon, Target, FolderOpen, CalendarDays, Landmark, UserPlus, ScrollText, Award, + HelpCircle as FaqIcon, Bell, Workflow, } from "lucide-react"; import React from "react"; @@ -87,6 +88,12 @@ const trainingItems: NavItem[] = [ { title: "Grammar", url: "/admin/training/grammar", icon: PenTool }, ]; +const configItems: NavItem[] = [ + { title: "FAQ Manager", url: "/admin/faq", icon: FaqIcon }, + { title: "Notification Rules", url: "/admin/notification-rules", icon: Bell }, + { title: "Approval Config", url: "/admin/approval-config", icon: Workflow }, +]; + const supportItems: NavItem[] = [ { title: "Payment Record", url: "/admin/payment-record", icon: CreditCard }, { title: "Tickets", url: "/admin/tickets", icon: Ticket }, @@ -139,6 +146,8 @@ const routeLabels: Record = { "academic-years": "Academic Years", departments: "Departments", admissions: "Admissions", "admission-register": "Admission Register", "exam-sessions": "Exam Sessions", marksheets: "Marksheets", + faq: "FAQ Manager", "notification-rules": "Notification Rules", + "approval-config": "Approval Config", }; function AppBreadcrumbs() { @@ -274,6 +283,7 @@ function AdminSidebar() { {showManagement && } {showReports && } + diff --git a/src/components/StudentLayout.tsx b/src/components/StudentLayout.tsx index 398e355..3fc64e3 100644 --- a/src/components/StudentLayout.tsx +++ b/src/components/StudentLayout.tsx @@ -2,6 +2,7 @@ import RoleLayout, { NavGroup } from "./RoleLayout"; import { LayoutDashboard, BookOpen, ClipboardList, BarChart3, CalendarCheck, Calendar, User, Target, GraduationCap, ListChecks, + MessageSquare, Megaphone, Mail, TrendingUp, } from "lucide-react"; const navGroups: NavGroup[] = [ @@ -26,6 +27,15 @@ const navGroups: NavGroup[] = [ { title: "Grades", url: "/student/grades", icon: BarChart3 }, { title: "Attendance", url: "/student/attendance", icon: CalendarCheck }, { title: "Timetable", url: "/student/timetable", icon: Calendar }, + { title: "My Journey", url: "/student/journey", icon: TrendingUp }, + ], + }, + { + label: "Communication", + items: [ + { title: "Discussions", url: "/student/discussions", icon: MessageSquare }, + { title: "Messages", url: "/student/messages", icon: Mail }, + { title: "Announcements", url: "/student/announcements", icon: Megaphone }, ], }, { diff --git a/src/components/TeacherLayout.tsx b/src/components/TeacherLayout.tsx index ac83aaf..caeccae 100644 --- a/src/components/TeacherLayout.tsx +++ b/src/components/TeacherLayout.tsx @@ -1,7 +1,8 @@ import RoleLayout, { NavGroup } from "./RoleLayout"; import { LayoutDashboard, BookOpen, ClipboardList, FileText, - CalendarCheck, Users, Calendar, User, + CalendarCheck, Users, Calendar, User, MessageSquare, + Megaphone, Wand2, } from "lucide-react"; const navGroups: NavGroup[] = [ @@ -21,6 +22,13 @@ const navGroups: NavGroup[] = [ { title: "Timetable", url: "/teacher/timetable", icon: Calendar }, ], }, + { + label: "Communication", + items: [ + { title: "Discussions", url: "/teacher/discussions", icon: MessageSquare }, + { title: "Announcements", url: "/teacher/announcements", icon: Megaphone }, + ], + }, { label: "Account", items: [ diff --git a/src/hooks/queries/index.ts b/src/hooks/queries/index.ts index 97da6a9..69c4b24 100644 --- a/src/hooks/queries/index.ts +++ b/src/hooks/queries/index.ts @@ -1,4 +1,8 @@ export * from "./keys"; +export * from "./useCourseware"; +export * from "./useCommunication"; +export * from "./useNotifications"; +export * from "./useFaq"; export * from "./useLms"; export * from "./useUsers"; export * from "./useExams"; diff --git a/src/hooks/queries/keys.ts b/src/hooks/queries/keys.ts index c677bf3..ccd9c33 100644 --- a/src/hooks/queries/keys.ts +++ b/src/hooks/queries/keys.ts @@ -153,4 +153,20 @@ export const queryKeys = { list: (params?: Record) => ["subject-registrations", "list", params] as const, available: (params?: Record) => ["subject-registrations", "available", params] as const, }, + chapters: (courseId: number) => ["chapters", "list", courseId] as const, + chapter: (id: number) => ["chapters", "detail", id] as const, + chapterMaterials: (chapterId: number) => ["chapter-materials", chapterId] as const, + chapterProgress: (chapterId: number) => ["chapter-progress", chapterId] as const, + discussionBoards: (params?: Record) => ["discussion-boards", params] as const, + posts: (boardId: number, params?: Record) => ["posts", boardId, params] as const, + announcements: (params?: Record) => ["announcements", params] as const, + messages: (params?: Record) => ["messages", params] as const, + sentMessages: (params?: Record) => ["messages", "sent", params] as const, + unreadMessages: ["messages", "unread-count"] as const, + notifications: (params?: Record) => ["notifications", params] as const, + unreadNotifications: ["notifications", "unread-count"] as const, + notificationRules: ["notification-rules"] as const, + notificationPreferences: ["notification-preferences"] as const, + faqCategories: (audience?: string) => ["faq", "categories", audience] as const, + faqItems: (params?: Record) => ["faq", "items", params] as const, }; diff --git a/src/hooks/queries/useCommunication.ts b/src/hooks/queries/useCommunication.ts new file mode 100644 index 0000000..1789d90 --- /dev/null +++ b/src/hooks/queries/useCommunication.ts @@ -0,0 +1,140 @@ +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; +import { queryKeys } from "./keys"; +import { communicationService } from "@/services/communication.service"; +import type { + DiscussionBoard, + PostCreateRequest, + AnnouncementCreateRequest, + MessageCreateRequest, +} from "@/types/communication"; +import type { PaginationParams } from "@/types"; + +export function useDiscussionBoards(params?: { course_id?: number; batch_id?: number }) { + return useQuery({ + queryKey: queryKeys.discussionBoards(params), + queryFn: () => communicationService.listDiscussionBoards(params), + }); +} + +export function usePosts(boardId: number, params?: PaginationParams) { + return useQuery({ + queryKey: queryKeys.posts(boardId, params), + queryFn: () => communicationService.listPosts(boardId, params), + enabled: !!boardId, + }); +} + +export function useAnnouncements(params?: { course_id?: number; priority?: string }) { + return useQuery({ + queryKey: queryKeys.announcements(params), + queryFn: () => communicationService.listAnnouncements(params), + }); +} + +export function useMessages(params?: { is_read?: boolean } & PaginationParams) { + return useQuery({ + queryKey: queryKeys.messages(params), + queryFn: () => communicationService.listMessages(params), + }); +} + +export function useSentMessages(params?: PaginationParams) { + return useQuery({ + queryKey: queryKeys.sentMessages(params), + queryFn: () => communicationService.listSentMessages(params), + }); +} + +export function useUnreadMessageCount() { + return useQuery({ + queryKey: queryKeys.unreadMessages, + queryFn: () => communicationService.getUnreadMessageCount(), + }); +} + +export function useCreateBoard() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ( + data: Partial & Pick, + ) => communicationService.createDiscussionBoard(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["discussion-boards"] }); + }, + }); +} + +export function useCreatePost() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ boardId, data }: { boardId: number; data: PostCreateRequest }) => + communicationService.createPost(boardId, data), + onSuccess: (_, { boardId }) => { + qc.invalidateQueries({ queryKey: ["posts", boardId] }); + qc.invalidateQueries({ queryKey: ["discussion-boards"] }); + }, + }); +} + +export function usePinPost() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, body }: { id: number; body?: { pinned?: boolean } }) => + communicationService.pinPost(id, body), + onSuccess: (post) => { + qc.invalidateQueries({ queryKey: ["posts", post.board_id] }); + }, + }); +} + +export function useResolvePost() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => communicationService.resolvePost(id), + onSuccess: (post) => { + qc.invalidateQueries({ queryKey: ["posts", post.board_id] }); + }, + }); +} + +export function useCreateAnnouncement() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: AnnouncementCreateRequest) => communicationService.createAnnouncement(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["announcements"] }); + }, + }); +} + +export function usePublishAnnouncement() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => communicationService.publishAnnouncement(id), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["announcements"] }); + }, + }); +} + +export function useSendMessage() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: MessageCreateRequest) => communicationService.sendMessage(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["messages"] }); + qc.invalidateQueries({ queryKey: queryKeys.unreadMessages }); + }, + }); +} + +export function useDeleteMessage() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => communicationService.deleteMessage(id), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["messages"] }); + qc.invalidateQueries({ queryKey: queryKeys.unreadMessages }); + }, + }); +} diff --git a/src/hooks/queries/useCourseware.ts b/src/hooks/queries/useCourseware.ts new file mode 100644 index 0000000..d52a6be --- /dev/null +++ b/src/hooks/queries/useCourseware.ts @@ -0,0 +1,204 @@ +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; +import { queryKeys } from "./keys"; +import { coursewareService } from "@/services/courseware.service"; +import type { + ChapterCreateRequest, + WorkbenchGenerateRequest, +} from "@/types/courseware"; + +export function useChapters(courseId: number) { + return useQuery({ + queryKey: queryKeys.chapters(courseId), + queryFn: () => coursewareService.listChapters(courseId), + enabled: !!courseId, + }); +} + +export function useChapter(id: number) { + return useQuery({ + queryKey: queryKeys.chapter(id), + queryFn: () => coursewareService.getChapter(id), + enabled: !!id, + }); +} + +export function useChapterMaterials(chapterId: number) { + return useQuery({ + queryKey: queryKeys.chapterMaterials(chapterId), + queryFn: () => coursewareService.listMaterials(chapterId), + enabled: !!chapterId, + }); +} + +export function useChapterProgress(chapterId: number) { + return useQuery({ + queryKey: queryKeys.chapterProgress(chapterId), + queryFn: () => coursewareService.getChapterProgress(chapterId), + enabled: !!chapterId, + }); +} + +export function useCreateChapter() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ courseId, data }: { courseId: number; data: ChapterCreateRequest }) => + coursewareService.createChapter(courseId, data), + onSuccess: (_, { courseId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapters(courseId) }); + }, + }); +} + +export function useUpdateChapter() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, data }: { id: number; data: Partial }) => + coursewareService.updateChapter(id, data), + onSuccess: (chapter) => { + qc.invalidateQueries({ queryKey: queryKeys.chapter(chapter.id) }); + qc.invalidateQueries({ queryKey: queryKeys.chapters(chapter.course_id) }); + }, + }); +} + +export function useDeleteChapter() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, courseId }: { id: number; courseId: number }) => + coursewareService.deleteChapter(id), + onSuccess: (_, { courseId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapters(courseId) }); + }, + }); +} + +export function useUnlockChapter() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, courseId }: { id: number; courseId: number }) => + coursewareService.unlockChapter(id), + onSuccess: (_, { id, courseId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapter(id) }); + qc.invalidateQueries({ queryKey: queryKeys.chapters(courseId) }); + }, + }); +} + +export function useLockChapter() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, courseId }: { id: number; courseId: number }) => + coursewareService.lockChapter(id), + onSuccess: (_, { id, courseId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapter(id) }); + qc.invalidateQueries({ queryKey: queryKeys.chapters(courseId) }); + }, + }); +} + +export function useReorderChapters() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ courseId, body }: { courseId: number; body: { ids: number[] } }) => + coursewareService.reorderChapters(courseId, body), + onSuccess: (_, { courseId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapters(courseId) }); + }, + }); +} + +export function useUploadMaterial() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ chapterId, formData }: { chapterId: number; formData: FormData }) => + coursewareService.uploadMaterial(chapterId, formData), + onSuccess: (_, { chapterId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapterMaterials(chapterId) }); + qc.invalidateQueries({ queryKey: queryKeys.chapterProgress(chapterId) }); + qc.invalidateQueries({ queryKey: queryKeys.chapter(chapterId) }); + }, + }); +} + +export function useDeleteMaterial() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, chapterId }: { id: number; chapterId: number }) => + coursewareService.deleteMaterial(id), + onSuccess: (_, { chapterId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapterMaterials(chapterId) }); + qc.invalidateQueries({ queryKey: queryKeys.chapterProgress(chapterId) }); + qc.invalidateQueries({ queryKey: queryKeys.chapter(chapterId) }); + }, + }); +} + +export function useMarkMaterialViewed() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, chapterId }: { id: number; chapterId: number }) => + coursewareService.markMaterialViewed(id), + onSuccess: (_, { chapterId }) => { + qc.invalidateQueries({ queryKey: queryKeys.chapterMaterials(chapterId) }); + qc.invalidateQueries({ queryKey: queryKeys.chapterProgress(chapterId) }); + }, + }); +} + +export function useCompleteChapter() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (chapterId: number) => coursewareService.markChapterComplete(chapterId), + onSuccess: (_, chapterId) => { + qc.invalidateQueries({ queryKey: queryKeys.chapterProgress(chapterId) }); + qc.invalidateQueries({ queryKey: queryKeys.chapter(chapterId) }); + }, + }); +} + +export function useGenerateOutline() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: WorkbenchGenerateRequest) => coursewareService.generateOutline(data), + onSuccess: (_, data) => { + qc.invalidateQueries({ queryKey: queryKeys.chapters(data.course_id) }); + qc.invalidateQueries({ queryKey: queryKeys.lms.course(data.course_id) }); + }, + }); +} + +export function useGenerateChapterContent() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: WorkbenchGenerateRequest) => coursewareService.generateChapterContent(data), + onSuccess: (_, data) => { + qc.invalidateQueries({ queryKey: queryKeys.chapters(data.course_id) }); + qc.invalidateQueries({ queryKey: queryKeys.lms.course(data.course_id) }); + }, + }); +} + +export function useGenerateRubric() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: WorkbenchGenerateRequest) => coursewareService.generateRubric(data), + onSuccess: (_, data) => { + qc.invalidateQueries({ queryKey: queryKeys.chapters(data.course_id) }); + qc.invalidateQueries({ queryKey: queryKeys.lms.course(data.course_id) }); + }, + }); +} + +export function usePublishWorkbench() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: Record) => coursewareService.publishWorkbench(data), + onSuccess: (_, data) => { + const courseId = data.course_id; + if (typeof courseId === "number") { + qc.invalidateQueries({ queryKey: queryKeys.chapters(courseId) }); + qc.invalidateQueries({ queryKey: queryKeys.lms.course(courseId) }); + } + }, + }); +} diff --git a/src/hooks/queries/useFaq.ts b/src/hooks/queries/useFaq.ts new file mode 100644 index 0000000..a6b02af --- /dev/null +++ b/src/hooks/queries/useFaq.ts @@ -0,0 +1,85 @@ +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; +import { queryKeys } from "./keys"; +import { faqService } from "@/services/faq.service"; +import type { FaqCategoryCreateRequest, FaqItemCreateRequest } from "@/types/faq"; + +export function useFaqCategories(audience?: string) { + return useQuery({ + queryKey: queryKeys.faqCategories(audience), + queryFn: () => faqService.listCategories(audience ? { audience } : undefined), + }); +} + +export function useFaqItems(params?: { category_id?: number; audience?: string; search?: string }) { + return useQuery({ + queryKey: queryKeys.faqItems(params), + queryFn: () => faqService.listItems(params), + }); +} + +export function useCreateFaqCategory() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: FaqCategoryCreateRequest) => faqService.createCategory(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["faq", "categories"] }); + }, + }); +} + +export function useUpdateFaqCategory() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, data }: { id: number; data: Partial }) => + faqService.updateCategory(id, data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["faq", "categories"] }); + qc.invalidateQueries({ queryKey: ["faq", "items"] }); + }, + }); +} + +export function useDeleteFaqCategory() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => faqService.deleteCategory(id), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["faq", "categories"] }); + qc.invalidateQueries({ queryKey: ["faq", "items"] }); + }, + }); +} + +export function useCreateFaqItem() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: FaqItemCreateRequest) => faqService.createItem(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["faq", "items"] }); + qc.invalidateQueries({ queryKey: ["faq", "categories"] }); + }, + }); +} + +export function useUpdateFaqItem() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ id, data }: { id: number; data: Partial }) => + faqService.updateItem(id, data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["faq", "items"] }); + qc.invalidateQueries({ queryKey: ["faq", "categories"] }); + }, + }); +} + +export function useDeleteFaqItem() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => faqService.deleteItem(id), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["faq", "items"] }); + qc.invalidateQueries({ queryKey: ["faq", "categories"] }); + }, + }); +} diff --git a/src/hooks/queries/useNotifications.ts b/src/hooks/queries/useNotifications.ts new file mode 100644 index 0000000..2fe2827 --- /dev/null +++ b/src/hooks/queries/useNotifications.ts @@ -0,0 +1,103 @@ +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; +import { queryKeys } from "./keys"; +import { notificationService } from "@/services/notification.service"; +import type { NotificationPreferences, NotificationRuleCreateRequest } from "@/types/notification"; +import type { PaginationParams } from "@/types"; + +export function useNotifications(params?: PaginationParams & { type?: string; is_read?: boolean }) { + return useQuery({ + queryKey: queryKeys.notifications(params), + queryFn: () => notificationService.listNotifications(params), + }); +} + +export function useUnreadNotificationCount() { + return useQuery({ + queryKey: queryKeys.unreadNotifications, + queryFn: () => notificationService.getUnreadNotificationCount(), + }); +} + +export function useNotificationRules() { + return useQuery({ + queryKey: queryKeys.notificationRules, + queryFn: () => notificationService.listNotificationRules(), + }); +} + +export function useNotificationPreferences() { + return useQuery({ + queryKey: queryKeys.notificationPreferences, + queryFn: () => notificationService.getNotificationPreferences(), + }); +} + +export function useMarkNotificationRead() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => notificationService.markNotificationRead(id), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["notifications"] }); + qc.invalidateQueries({ queryKey: queryKeys.unreadNotifications }); + }, + }); +} + +export function useMarkAllNotificationsRead() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: () => notificationService.markAllNotificationsRead(), + onSuccess: () => { + qc.invalidateQueries({ queryKey: ["notifications"] }); + qc.invalidateQueries({ queryKey: queryKeys.unreadNotifications }); + }, + }); +} + +export function useCreateNotificationRule() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: NotificationRuleCreateRequest) => + notificationService.createNotificationRule(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: queryKeys.notificationRules }); + }, + }); +} + +export function useUpdateNotificationRule() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: ({ + id, + data, + }: { + id: number; + data: Partial; + }) => notificationService.updateNotificationRule(id, data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: queryKeys.notificationRules }); + }, + }); +} + +export function useDeleteNotificationRule() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (id: number) => notificationService.deleteNotificationRule(id), + onSuccess: () => { + qc.invalidateQueries({ queryKey: queryKeys.notificationRules }); + }, + }); +} + +export function useUpdateNotificationPreferences() { + const qc = useQueryClient(); + return useMutation({ + mutationFn: (data: Partial) => + notificationService.updateNotificationPreferences(data), + onSuccess: () => { + qc.invalidateQueries({ queryKey: queryKeys.notificationPreferences }); + }, + }); +} diff --git a/src/pages/FaqPage.tsx b/src/pages/FaqPage.tsx new file mode 100644 index 0000000..a46c341 --- /dev/null +++ b/src/pages/FaqPage.tsx @@ -0,0 +1,96 @@ +import { useState } from "react"; +import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"; +import { Input } from "@/components/ui/input"; +import { Badge } from "@/components/ui/badge"; +import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui/accordion"; +import { Search, HelpCircle, Video } from "lucide-react"; +import { useFaqCategories, useFaqItems } from "@/hooks/queries"; + +export default function FaqPage() { + const [search, setSearch] = useState(""); + const { data: categories = [], isLoading: lc } = useFaqCategories(); + const { data: allItems = [], isLoading: li } = useFaqItems(search ? { search } : undefined); + + const filteredCategories = categories.filter(cat => + allItems.some(item => item.category_id === cat.id), + ); + + const getItemsForCategory = (catId: number) => + allItems.filter(item => item.category_id === catId); + + if (lc || li) return
; + + return ( +
+
+

Frequently Asked Questions

+

Find answers to common questions about EnCoach.

+
+ +
+ + setSearch(e.target.value)} + /> +
+ + {filteredCategories.length > 0 ? ( +
+ {filteredCategories.map(cat => { + const catItems = getItemsForCategory(cat.id); + if (catItems.length === 0) return null; + return ( + + +
+ + {cat.name} + {cat.item_count} questions +
+ + + + {catItems + .sort((a, b) => a.sequence - b.sequence) + .map(item => ( + + + {item.question} + + +
+

{item.answer}

+ {item.video_url && ( + + + )} +
+ + + ))} + + + + ); + })} +
+ ) : ( + + + +

{search ? "No questions match your search." : "No FAQ items available yet."}

+ + + )} +
+ ); +} diff --git a/src/pages/OfficialExamAccess.tsx b/src/pages/OfficialExamAccess.tsx new file mode 100644 index 0000000..8c43821 --- /dev/null +++ b/src/pages/OfficialExamAccess.tsx @@ -0,0 +1,87 @@ +import { useSearchParams, useNavigate } from "react-router-dom"; +import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card"; +import { Button } from "@/components/ui/button"; +import { Badge } from "@/components/ui/badge"; +import { Loader2, Clock, AlertCircle, ClipboardList } from "lucide-react"; +import { examsService } from "@/services/exams.service"; +import { useQuery } from "@tanstack/react-query"; + +export default function OfficialExamAccess() { + const [searchParams] = useSearchParams(); + const navigate = useNavigate(); + const token = searchParams.get("token"); + + const { data: examInfo, isLoading, error } = useQuery({ + queryKey: ["exam", "access", token], + queryFn: async () => { + const res = await fetch(`${import.meta.env.VITE_API_BASE_URL}/exam/access/${token}`); + if (!res.ok) throw new Error(res.status === 404 ? "Invalid or expired token" : "Failed to load exam"); + return res.json() as Promise<{ id: number; name: string; duration_minutes: number; start_time: string; module: string }>; + }, + enabled: !!token, + retry: false, + }); + + const handleStart = () => { + if (examInfo) { + navigate(`/exam/${examInfo.module}/${examInfo.id}?token=${token}`); + } + }; + + return ( +
+ + {!token ? ( + + +

No Access Token

+

Please use the link provided by your institution to access the exam.

+ + ) : isLoading ? ( + + +

Loading exam information...

+ + ) : error ? ( + + +

Access Denied

+

{(error as Error).message}

+ + ) : examInfo ? ( + <> + +
+ +
+ {examInfo.name} + Official Exam Access + + +
+
+ Duration +
+ + {examInfo.duration_minutes} minutes +
+
+
+ Start Time + {new Date(examInfo.start_time).toLocaleString()} +
+
+ Module + {examInfo.module} +
+
+ + + + ) : null} + +
+ ); +} diff --git a/src/pages/admin/ApprovalWorkflowConfig.tsx b/src/pages/admin/ApprovalWorkflowConfig.tsx new file mode 100644 index 0000000..4bb793e --- /dev/null +++ b/src/pages/admin/ApprovalWorkflowConfig.tsx @@ -0,0 +1,221 @@ +import { useState } from "react"; +import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card"; +import { Button } from "@/components/ui/button"; +import { Badge } from "@/components/ui/badge"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { Switch } from "@/components/ui/switch"; +import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"; +import { Plus, Trash2, Loader2, ChevronRight, Settings2, ArrowRight } from "lucide-react"; +import { approvalsService, type ApprovalWorkflow } from "@/services/approvals.service"; +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; +import { useToast } from "@/hooks/use-toast"; + +interface WorkflowStage { + order: number; + approver_id: number; + approver_name: string; + max_days?: number; + notification_email?: string; + auto_escalate?: boolean; +} + +export default function ApprovalWorkflowConfig() { + const { toast } = useToast(); + const qc = useQueryClient(); + + const { data: workflowsData, isLoading } = useQuery({ + queryKey: ["approvals", "list"], + queryFn: () => approvalsService.list(), + }); + const workflows = workflowsData?.results ?? []; + + const createWorkflow = useMutation({ + mutationFn: (data: Partial) => approvalsService.create(data), + onSuccess: () => qc.invalidateQueries({ queryKey: ["approvals"] }), + onError: () => toast({ title: "Error", description: "Failed to create workflow", variant: "destructive" }), + }); + + const updateWorkflow = useMutation({ + mutationFn: ({ id, data }: { id: number; data: Partial }) => approvalsService.update(id, data), + onSuccess: () => qc.invalidateQueries({ queryKey: ["approvals"] }), + onError: () => toast({ title: "Error", description: "Failed to update workflow", variant: "destructive" }), + }); + + const deleteWorkflow = useMutation({ + mutationFn: (id: number) => approvalsService.delete(id), + onSuccess: () => qc.invalidateQueries({ queryKey: ["approvals"] }), + onError: () => toast({ title: "Error", description: "Failed to delete workflow", variant: "destructive" }), + }); + + const [showCreate, setShowCreate] = useState(false); + const [wfName, setWfName] = useState(""); + const [stages, setStages] = useState([{ order: 1, approver_id: 0, approver_name: "", max_days: 3, auto_escalate: false }]); + const [bypassEnabled, setBypassEnabled] = useState(false); + + const resetForm = () => { + setWfName(""); + setStages([{ order: 1, approver_id: 0, approver_name: "", max_days: 3, auto_escalate: false }]); + setBypassEnabled(false); + }; + + const addStage = () => { + setStages(prev => [...prev, { order: prev.length + 1, approver_id: 0, approver_name: "", max_days: 3, auto_escalate: false }]); + }; + + const removeStage = (idx: number) => { + setStages(prev => prev.filter((_, i) => i !== idx).map((s, i) => ({ ...s, order: i + 1 }))); + }; + + const updateStage = (idx: number, field: keyof WorkflowStage, value: string | number | boolean) => { + setStages(prev => prev.map((s, i) => i === idx ? { ...s, [field]: value } : s)); + }; + + const handleCreate = () => { + createWorkflow.mutate( + { name: wfName, steps: stages.map(s => ({ order: s.order, approver_id: s.approver_id, approver_name: s.approver_name })), status: "draft" } as Partial, + { onSuccess: () => { toast({ title: "Workflow Created" }); setShowCreate(false); resetForm(); } }, + ); + }; + + const handleDelete = (id: number) => { + deleteWorkflow.mutate(id, { + onSuccess: () => toast({ title: "Workflow Deleted" }), + }); + }; + + const handleToggleStatus = (wf: ApprovalWorkflow) => { + const newStatus = wf.status === "active" ? "draft" : "active"; + updateWorkflow.mutate( + { id: wf.id, data: { status: newStatus } }, + { onSuccess: () => toast({ title: `Workflow ${newStatus === "active" ? "Activated" : "Deactivated"}` }) }, + ); + }; + + if (isLoading) return
; + + return ( +
+
+
+

Approval Workflows

+

Configure multi-stage approval workflows with escalation rules.

+
+ { setShowCreate(open); if (!open) resetForm(); }}> + + + + + Create Approval Workflow +
+
+ + setWfName(e.target.value)} /> +
+ +
+
+ + +
+ {stages.map((stage, idx) => ( + + +
+ Stage {stage.order} + {stages.length > 1 && ( + + )} +
+
+
+ + updateStage(idx, "approver_name", e.target.value)} placeholder="Name" /> +
+
+ + updateStage(idx, "approver_id", Number(e.target.value))} placeholder="ID" /> +
+
+ + updateStage(idx, "max_days", Number(e.target.value))} /> +
+
+ + updateStage(idx, "notification_email", e.target.value)} placeholder="email@..." /> +
+
+
+ updateStage(idx, "auto_escalate", v)} /> + +
+ + + ))} +
+ +
+ + +
+ + +
+ + +
+ +
+ {workflows.map(wf => ( + + +
+
+ +
+ {wf.name} + {wf.entity_name} +
+
+
+ {wf.status} + handleToggleStatus(wf)} /> + +
+
+ + +
+ {wf.steps.map((step, i) => ( +
+
+ {step.order} + {step.approver_name} +
+ {i < wf.steps.length - 1 && } +
+ ))} +
+

Created: {new Date(wf.created_at).toLocaleDateString()}

+ + + ))} + {workflows.length === 0 && ( + + + +

No approval workflows configured.

+ + + )} +
+
+ ); +} diff --git a/src/pages/admin/FaqManager.tsx b/src/pages/admin/FaqManager.tsx new file mode 100644 index 0000000..278f8d9 --- /dev/null +++ b/src/pages/admin/FaqManager.tsx @@ -0,0 +1,283 @@ +import { useState } from "react"; +import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"; +import { Button } from "@/components/ui/button"; +import { Badge } from "@/components/ui/badge"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { Textarea } from "@/components/ui/textarea"; +import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"; +import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"; +import { Plus, Trash2, Pencil, Loader2, HelpCircle, FolderOpen, GripVertical } from "lucide-react"; +import { useFaqCategories, useFaqItems, useCreateFaqCategory, useUpdateFaqCategory, useDeleteFaqCategory, useCreateFaqItem, useUpdateFaqItem, useDeleteFaqItem } from "@/hooks/queries"; +import { useToast } from "@/hooks/use-toast"; +import type { FaqAudience, FaqCategory, FaqItem } from "@/types/faq"; + +export default function FaqManager() { + const { toast } = useToast(); + const { data: categories = [], isLoading: lc } = useFaqCategories(); + const [selectedCatId, setSelectedCatId] = useState(null); + const { data: items = [], isLoading: li } = useFaqItems(selectedCatId ? { category_id: selectedCatId } : undefined); + const createCategory = useCreateFaqCategory(); + const updateCategory = useUpdateFaqCategory(); + const deleteCategory = useDeleteFaqCategory(); + const createItem = useCreateFaqItem(); + const updateItem = useUpdateFaqItem(); + const deleteItem = useDeleteFaqItem(); + + const [showAddCat, setShowAddCat] = useState(false); + const [catName, setCatName] = useState(""); + const [catAudience, setCatAudience] = useState("both"); + + const [showAddItem, setShowAddItem] = useState(false); + const [editingItem, setEditingItem] = useState(null); + const [itemQuestion, setItemQuestion] = useState(""); + const [itemAnswer, setItemAnswer] = useState(""); + const [itemAudience, setItemAudience] = useState("both"); + const [itemVideoUrl, setItemVideoUrl] = useState(""); + + const [editingCat, setEditingCat] = useState(null); + const [editCatName, setEditCatName] = useState(""); + + const resetItemForm = () => { setItemQuestion(""); setItemAnswer(""); setItemAudience("both"); setItemVideoUrl(""); setEditingItem(null); }; + + const handleCreateCategory = () => { + createCategory.mutate( + { name: catName, audience: catAudience }, + { + onSuccess: () => { toast({ title: "Category Created" }); setShowAddCat(false); setCatName(""); }, + onError: () => toast({ title: "Error", description: "Failed to create category", variant: "destructive" }), + }, + ); + }; + + const handleUpdateCategory = () => { + if (!editingCat) return; + updateCategory.mutate( + { id: editingCat.id, data: { name: editCatName } }, + { + onSuccess: () => { toast({ title: "Category Updated" }); setEditingCat(null); }, + onError: () => toast({ title: "Error", description: "Failed to update category", variant: "destructive" }), + }, + ); + }; + + const handleDeleteCategory = (id: number) => { + deleteCategory.mutate(id, { + onSuccess: () => { toast({ title: "Category Deleted" }); if (selectedCatId === id) setSelectedCatId(null); }, + onError: () => toast({ title: "Error", description: "Failed to delete category", variant: "destructive" }), + }); + }; + + const handleSaveItem = () => { + if (editingItem) { + updateItem.mutate( + { id: editingItem.id, data: { question: itemQuestion, answer: itemAnswer, audience: itemAudience, video_url: itemVideoUrl || undefined } }, + { + onSuccess: () => { toast({ title: "Item Updated" }); setShowAddItem(false); resetItemForm(); }, + onError: () => toast({ title: "Error", description: "Failed to update item", variant: "destructive" }), + }, + ); + } else if (selectedCatId) { + createItem.mutate( + { question: itemQuestion, answer: itemAnswer, category_id: selectedCatId, audience: itemAudience, video_url: itemVideoUrl || undefined }, + { + onSuccess: () => { toast({ title: "Item Created" }); setShowAddItem(false); resetItemForm(); }, + onError: () => toast({ title: "Error", description: "Failed to create item", variant: "destructive" }), + }, + ); + } + }; + + const handleDeleteItem = (id: number) => { + deleteItem.mutate(id, { + onSuccess: () => toast({ title: "Item Deleted" }), + onError: () => toast({ title: "Error", description: "Failed to delete item", variant: "destructive" }), + }); + }; + + const openEditItem = (item: FaqItem) => { + setEditingItem(item); + setItemQuestion(item.question); + setItemAnswer(item.answer); + setItemAudience(item.audience); + setItemVideoUrl(item.video_url ?? ""); + setShowAddItem(true); + }; + + if (lc) return
; + + return ( +
+
+
+

FAQ Manager

+

Manage FAQ categories and items.

+
+
+ +
+
+
+

Categories

+ + + + + + New Category +
+
+ + setCatName(e.target.value)} /> +
+
+ + +
+ +
+ + +
+ + {categories.map(cat => ( +
+ +
+ + +
+
+ ))} + {categories.length === 0 &&

No categories yet.

} +
+ +
+ {!selectedCatId ? ( + Select a category to manage its FAQ items. + ) : li ? ( +
+ ) : ( +
+
+

FAQ Items

+ +
+ {items + .sort((a, b) => a.sequence - b.sequence) + .map(item => ( + + +
+ +
+

{item.question}

+

{item.answer}

+
+ {item.audience} + {item.video_url && Video} +
+
+
+ + +
+
+ + + ))} + {items.length === 0 && ( + No items in this category. + )} +
+ )} +
+
+ + { if (!open) setEditingCat(null); }}> + + Edit Category +
+
+ + setEditCatName(e.target.value)} /> +
+ +
+ + + + { setShowAddItem(open); if (!open) resetItemForm(); }}> + + {editingItem ? "Edit FAQ Item" : "New FAQ Item"} +
+
+ + setItemQuestion(e.target.value)} /> +
+
+ +