devops/encoach_frontend_new_v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: integrate client requirements (courseware, communication, notifications, FAQ, enhanced approvals)

Browse Source 
Add 4 new Odoo modules coverage:
- encoach_courseware: chapters, materials, chapter progress, AI workbench
- encoach_communication: discussion boards, announcements, messaging
- encoach_notification: notification engine, rules, preferences
- encoach_faq: FAQ categories and items, role-filtered

Frontend changes:
- 4 new type files (courseware, communication, notification, faq)
- 5 new service files (courseware, communication, notification, faq, plagiarism)
- 4 new hook files (useCourseware, useCommunication, useNotifications, useFaq)
- 15 new page components (teacher: chapters, chapter detail, AI workbench,
  discussions, announcements; student: chapter view, discussions, announcements,
  messages, journey; admin: FAQ manager, notification rules, approval config;
  public: official exam access, FAQ page)
- Updated App.tsx routing with all new pages
- Updated TeacherLayout, StudentLayout, AdminLmsLayout sidebars

SRS updates:
- ENCOACH_UNIFIED_SRS.md: added Parts IX-XI (Courseware, Communication,
  Notifications/FAQ), enhanced exam management (exercise vs exam, official
  access modes), enhanced approval workflows (timed stages, escalation,
  bypass), enhanced assignments (late submissions, extensions), plagiarism
  detection. Total modules: 35
- ENCOACH_ODOO19_BACKEND_SRS.md v2.0: added sections 26-31, updated module
  inventory to 35, updated endpoint count to 280+, added enhanced assignment
  models with late submission/extension support

Made-with: Cursor
This commit is contained in:
Talal Sharabi
2026-03-27 00:20:30 +04:00
parent 19d7e01be1
commit 5980451ea8
38 changed files with 4849 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

709
docs/ENCOACH_UNIFIED_SRS.md
View File

@@ -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 |