From 7ebe33d920db682a66f373e038b5f21c2e98b07f Mon Sep 17 00:00:00 2001 From: JakkrapartXD Date: Wed, 24 Dec 2025 17:27:03 +0700 Subject: [PATCH] feat: Add ERD documentation and refactor API endpoint paths for student and instructor specific routes. --- docs/.DS_Store | Bin 6148 -> 6148 bytes docs/api-docs/ERD_README.md | 312 +++++++++++++++++++++++++++++++++ docs/api-docs/api_endpoints.md | 20 ++- 3 files changed, 325 insertions(+), 7 deletions(-) create mode 100644 docs/api-docs/ERD_README.md diff --git a/docs/.DS_Store b/docs/.DS_Store index 60a78faf8869363c11164cd2850e19c22200283a..afb5093fdb1e878d8bbf3c05915fadef6c3c81ca 100644 GIT binary patch delta 278 zcmZoMXfc=|#>B)qu~2NHo+2aD!~pA!7aABR8;Gz>>=&<3DlaZb%E?b+U|`shRFIQd zTw-8wjgg6&g_Vt+gPnt$BQ`iAzdX1kv81%vDX}OT#0$yK&q;!@6O+O+Q_JH8M4a>U zN)j{kQj5SEGE-84N@Bt@^HTE5o$^cbQi{QPgCPCJzu~2NHo+2aT!~knX#>qTPQkz+rnOQe0Fvl@%X6NAN04mum$o!po aGQWr}CnEy`!vP>>m~6u%y*Wl?2{Qm^ix2St diff --git a/docs/api-docs/ERD_README.md b/docs/api-docs/ERD_README.md new file mode 100644 index 00000000..7b318ce7 --- /dev/null +++ b/docs/api-docs/ERD_README.md @@ -0,0 +1,312 @@ +# Database Schema (ERD) Documentation + +## 📊 Entity-Relationship Diagram + +### Online Visualization + +View the interactive ERD diagram: +- **dbdiagram.io**: [dbdiagram.io](https://dbdiagram.io/d/e-lerning-6943c64be4bb1dd3a9896479) + +## 📋 Database Overview + +### Total Tables: **17** + +| Category | Tables | Count | +|----------|--------|-------| +| **Core** | users, categories, courses, chapters, lessons | 5 | +| **Content** | quizzes, questions, choices, lesson_attachments | 4 | +| **Progress** | enrollments, lesson_progress, quiz_attempts | 3 | +| **Communication** | announcements, announcement_attachments | 2 | +| **Commerce** (āļ­āļ™āļēāļ„āļ•) | orders, payments, withdrawals | 3 | + +--- + +## ðŸŽŊ Key Features + +### 1. **Multi-language Support** +- Uses `jsonb` fields for Thai/English content +- Fields: `title`, `content`, `description` + +### 2. **Video Progress Tracking** +- Track playback position per student +- Auto-complete at 90% watched +- Resume from last position + +### 3. **Lesson Prerequisites** +- Sequential learning control +- Quiz pass requirements +- Flexible ordering + +### 4. **File Attachments** +- Multiple files per lesson +- Support for PDF, DOCX, ZIP, images +- Sortable with descriptions + +### 5. **Quiz System** +- Multiple attempts with cooldown +- Score policies (HIGHEST/LATEST/FIRST/AVERAGE) +- Detailed attempt history + +--- + +## 📊 Main Entities + +### Users +- Roles: STUDENT, INSTRUCTOR, ADMIN +- Profile information +- Authentication data + +### Courses +- Multi-language titles and descriptions +- Categories and pricing +- Instructor ownership +- Approval workflow + +### Chapters & Lessons +- Hierarchical structure +- Sort ordering +- Multiple lesson types (video, pdf, text, quiz) +- Prerequisites support + +### Progress Tracking +- Enrollment status +- Lesson completion +- Video playback position +- Quiz attempts and scores + +--- + +## 🔗 Relationships + +``` +users (1) ──── (many) courses [instructor] +users (1) ──── (many) enrollments +users (1) ──── (many) lesson_progress +users (1) ──── (many) quiz_attempts + +courses (1) ──── (many) chapters +courses (1) ──── (many) enrollments +courses (1) ──── (many) announcements + +chapters (1) ──── (many) lessons + +lessons (1) ──── (many) lesson_attachments +lessons (1) ──── (many) lesson_progress +lessons (1) ──── (many) quizzes + +quizzes (1) ──── (many) questions +quizzes (1) ──── (many) quiz_attempts + +questions (1) ──── (many) choices +``` + +--- + +## ðŸŽĻ How to Visualize + +### Using dbdiagram.io + +1. **Open dbdiagram.io** + - Go to [https://dbdiagram.io/d](https://dbdiagram.io/d) + +2. **Import Schema** + - Click "Import" button (top right) + - Select "From DBML" + - Copy contents from [`ERD_v2_improved.txt`](./ERD_v2_improved.txt) + - Paste into the editor + - Click "Import" + +3. **View Diagram** + - Zoom in/out with mouse wheel + - Drag to pan + - Click tables to highlight relationships + - Export as PNG/PDF/SQL + +### Alternative Tools + +- **DBeaver**: Import SQL and generate ER diagram +- **MySQL Workbench**: Reverse engineer from database +- **pgAdmin**: PostgreSQL schema visualization +- **draw.io**: Manual diagram creation + +--- + +## 📝 Table Descriptions + +### Core Tables + +#### `users` +- User accounts and authentication +- Roles: STUDENT, INSTRUCTOR, ADMIN +- Profile information + +#### `categories` +- Course categorization +- Multi-language names + +#### `courses` +- Course information and metadata +- Pricing and approval status +- Instructor ownership + +#### `chapters` +- Course structure organization +- Sortable within courses + +#### `lessons` +- Learning content units +- Types: video, pdf, text, quiz +- Prerequisites and sequencing + +### Content Tables + +#### `quizzes` +- Assessment configuration +- Attempt limits and cooldown +- Passing score requirements + +#### `questions` +- Quiz questions +- Types: multiple_choice, true_false +- Point values + +#### `choices` +- Answer options for questions +- Correct answer marking + +#### `lesson_attachments` +- Supplementary files +- PDFs, documents, code samples +- Multi-language descriptions + +### Progress Tables + +#### `enrollments` +- Student course registrations +- Progress tracking +- Certificate issuance + +#### `lesson_progress` +- Lesson completion status +- Video playback position +- Watch history + +#### `quiz_attempts` +- Quiz submission records +- Scores and answers +- Attempt history + +### Communication Tables + +#### `announcements` +- Course announcements +- Pinning and scheduling +- Multi-language content + +#### `announcement_attachments` +- Announcement file attachments + +--- + +## 🔧 Database Constraints + +### Primary Keys +- All tables use auto-incrementing integer PKs + +### Foreign Keys +- Maintain referential integrity +- Cascade deletes where appropriate + +### Unique Constraints +- `(user_id, course_id)` in enrollments +- `(user_id, lesson_id)` in lesson_progress +- Email in users + +### Check Constraints (via notes) +- Progress percentages: 0-100 +- Scores: 0-100 +- Sort orders: >= 0 +- Prices: >= 0 + +### Indexes +- Single column indexes on FKs +- Composite indexes for common queries +- JSONB GIN indexes for multi-language fields + +--- + +## 🚀 Migration Notes + +### PostgreSQL Extensions Required +```sql +CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +CREATE EXTENSION IF NOT EXISTS "pg_trgm"; -- for text search +``` + +### JSONB Usage +```sql +-- Multi-language fields +title JSONB -- {"th": "...", "en": "..."} + +-- Query examples +WHERE title->>'th' LIKE '%Python%' +WHERE title @> '{"en": "Introduction"}' +``` + +### Soft Delete Pattern +```sql +-- Recommended for important tables +ALTER TABLE courses ADD COLUMN deleted_at TIMESTAMP; +CREATE INDEX idx_courses_deleted ON courses(deleted_at) WHERE deleted_at IS NULL; +``` + +--- + +## 📈 Performance Considerations + +### Indexes Created +- All foreign keys +- Composite indexes for (course_id, sort_order) +- User email for login +- Course status for filtering +- Last watched timestamp for recent videos + +### Query Optimization +- Use `SELECT` specific columns +- Implement pagination +- Cache course lists in Redis +- Use database views for complex queries + +--- + +## 🔗 Related Documentation + +- [API Endpoints](./api_endpoints.md) - REST API reference +- [Edge Cases](../edge_cases_quick_reference.md) - Special scenarios +- [Development Setup](../development_setup.md) - Environment configuration + +--- + +## 📊 Statistics + +- **Total Tables**: 17 +- **Total Relationships**: 20+ +- **Multi-language Fields**: 15+ +- **Indexed Columns**: 40+ +- **JSONB Fields**: 15+ + +--- + +## ðŸŽŊ Next Steps + +1. ✅ Review ERD schema +2. âģ Create PostgreSQL database +3. âģ Run migrations +4. âģ Seed initial data +5. âģ Implement API endpoints +6. âģ Test with sample data + +--- + +**Last Updated**: 2024-12-24 +**Version**: 2.0 (Improved) diff --git a/docs/api-docs/api_endpoints.md b/docs/api-docs/api_endpoints.md index 5bdb5252..f74fde7e 100644 --- a/docs/api-docs/api_endpoints.md +++ b/docs/api-docs/api_endpoints.md @@ -65,7 +65,7 @@ Authorization: Bearer ### Student Endpoints | Method | Endpoint | Auth | Description | |--------|----------|------|-------------| -| POST | `/courses/:courseId/enroll` | ðŸ‘Ļ‍🎓 Student | Enroll in course | +| POST | `/students/courses/:courseId/enroll` | ðŸ‘Ļ‍🎓 Student | Enroll in course | | GET | `/students/courses` | ðŸ‘Ļ‍🎓 Student | Get my enrolled courses | | GET | `/students/courses/:courseId/learn` | ðŸ‘Ļ‍🎓 Student | Get course learning page (with lock status) | | GET | `/students/courses/:courseId/lessons/:lessonId` | ðŸ‘Ļ‍🎓 Student | Get lesson content (checks prerequisites) | @@ -114,7 +114,7 @@ Authorization: Bearer | PUT | `/instructor/courses/:courseId/lessons/:lessonId/attachments/:attachmentId` | ðŸ‘Ļ‍ðŸŦ Instructor | Update attachment info | | DELETE | `/instructor/courses/:courseId/lessons/:lessonId/attachments/:attachmentId` | ðŸ‘Ļ‍ðŸŦ Instructor | Delete attachment | | PUT | `/instructor/courses/:courseId/lessons/:lessonId/attachments/reorder` | ðŸ‘Ļ‍ðŸŦ Instructor | Reorder attachments | -| GET | `/lessons/:lessonId/attachments/:attachmentId/download` | ✅ | Download attachment | +| GET | `/students/lessons/:lessonId/attachments/:attachmentId/download` | ðŸ‘Ļ‍🎓 Student | Download attachment | --- @@ -142,14 +142,20 @@ Authorization: Bearer ## 6. Announcements +### Student Endpoints | Method | Endpoint | Auth | Description | |--------|----------|------|-------------| -| GET | `/courses/:courseId/announcements` | ✅ | Get course announcements | -| GET | `/courses/:courseId/announcements/:announcementId` | ✅ | Get announcement details | +| GET | `/students/courses/:courseId/announcements` | ðŸ‘Ļ‍🎓 Student | Get course announcements | +| GET | `/students/courses/:courseId/announcements/:announcementId` | ðŸ‘Ļ‍🎓 Student | Get announcement details | +| GET | `/students/announcements/:announcementId/attachments/:attachmentId/download` | ðŸ‘Ļ‍🎓 Student | Download attachment | + +### Instructor Endpoints +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/instructor/courses/:courseId/announcements` | ðŸ‘Ļ‍ðŸŦ Instructor | List announcements | | POST | `/instructor/courses/:courseId/announcements` | ðŸ‘Ļ‍ðŸŦ Instructor | Create announcement | | PUT | `/instructor/courses/:courseId/announcements/:announcementId` | ðŸ‘Ļ‍ðŸŦ Instructor | Update announcement | | DELETE | `/instructor/courses/:courseId/announcements/:announcementId` | ðŸ‘Ļ‍ðŸŦ Instructor | Delete announcement | -| GET | `/announcements/:announcementId/attachments/:attachmentId/download` | ✅ | Download attachment | --- @@ -305,7 +311,7 @@ Authorization: Bearer --- -## Total Endpoints: **95+** +## Total Endpoints: **96+** - Authentication: 6 - User Management: 4 @@ -313,7 +319,7 @@ Authorization: Bearer - Courses: 14 (+2) - Chapters & Lessons: 16 - Quizzes: 10 -- Announcements: 6 +- Announcements: 7 (+1) - Reports: 11 - Orders & Payments: 7 (āļ­āļ™āļēāļ„āļ•) - Earnings & Withdrawals: 8 (āļ­āļ™āļēāļ„āļ•)