Skip to content

T
trainee-schedule
Commit dd266982 authored by Đoàn Vũ Bình Dương's avatar Đoàn Vũ Bình Dương
Browse files
Options

Merge branch 'ref/warning' into 'develop' 

refactor: warning - API description.md

See merge request !4
parents 448f03b2 790d2b2e
Hide whitespace changes
Inline Side-by-side
Showing with 305 additions and 456 deletions
API_DESCRIPTION.md
View file @ dd266982
......@@ -6,31 +6,112 @@ http://localhost:3001/api/v1.0
```
## Authentication
Currently disabled for development. All endpoints are accessible without authentication.
Hệ thống sử dụng JWT (JSON Web Token) để xác thực người dùng. Token có thể được truyền qua hai cách:
1. **HttpOnly Cookie**: Tên cookie là `access_token` và `refresh_token` (Khuyên dùng vì tính bảo mật cao).
2. **Authorization Header**: Sử dụng định dạng `Authorization: Bearer <your_access_token>`.
**Roles:** `admin`, `mentor`, `student`.
## Response Format
Tất cả các API thành công đều trả về định dạng sau:
```json
{
"success": true,
"data": {},
"message": "Success",
"timestamp": "2026-04-10T20:00:00.000Z"
"status": "success",
"message": "Thành công",
"message_en": "Success",
"responseData": {},
"timeStamp": "2026-04-13 13:00:00",
"violations": null
}
```
## Error Response Format
Khi có lỗi xảy ra, API sẽ trả về lỗi với mã trạng thái HTTP phù hợp:
```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Error description",
"details": {}
},
"timestamp": "2026-04-10T20:00:00.000Z"
"status": "fail",
"message": "Thông báo lỗi tiếng Việt",
"message_en": "Error message in English",
"responseData": null,
"timeStamp": "2026-04-13 13:00:00",
"violations": [
{
"code": 401,
"message": "Chi tiết lỗi",
"action": null
}
]
}
```
---
# AUTH API
## 1. Login
**Endpoint:** `POST /auth/login`
**Description:** Đăng nhập vào hệ thống.
**Request Body:**
```json
{
"email": "user@example.com",
"password": "yourpassword",
"device_info": {},
"ip_address": "127.0.0.1",
"user_agent": "Mozilla/5.0..."
}
```
**Response:** Trả về thông tin User, Session và thiết lập Cookies.
## 2. Register
**Endpoint:** `POST /auth/register`
**Description:** Đăng ký tài khoản mới (Chế độ công khai hoặc qua Admin tùy cấu hình).
**Request Body:**
```json
{
"email": "newuser@example.com",
"username": "newuser",
"password": "securepassword",
"first_name": "Nguyen",
"last_name": "Van A",
"roles": ["student"]
}
```
## 3. Profile
**Endpoint:** `GET /auth/profile`
**Description:** Lấy thông tin người dùng hiện tại đang đăng nhập.
**Security:** Yêu cầu đăng nhập.
## 4. Refresh Token
**Endpoint:** `POST /auth/refresh`
**Description:** Làm mới Access Token bằng Refresh Token (thường lấy từ Cookie).
## 5. Logout
**Endpoint:** `POST /auth/logout`
**Description:** Đăng xuất và xóa các session/cookies.
---
# USER API
## 1. Get All Users
**Endpoint:** `GET /user`
**Security:** Yêu cầu quyền Admin.
**Query Parameters:** `page`, `pageSize`, `sortField`, `sortOrder`, `search`.
## 2. Get User by ID
**Endpoint:** `GET /user/{id}`
## 3. Create User
**Endpoint:** `POST /user`
## 4. Update User
**Endpoint:** `PUT /user/{id}`
## 5. Delete User
**Endpoint:** `DELETE /user/{id}`
---
# STUDENTS API
......@@ -48,22 +129,18 @@ Currently disabled for development. All endpoints are accessible without authent
| pageSize | number | No | 10 | Số lượng item mỗi trang |
| status | string | No | - | Lọc theo trạng thái (active, inactive, completed) |
| courseId | string | No | - | Lọc theo ID khóa học |
| semester | string | No | - | Lọc theo kỳ học (VD: "2024-1") |
| search | string | No | - | Tìm kiếm theo họ tên hoặc email |
| semester | string | No | - | Lọc theo kỳ học |
**Request Example:**
```bash
GET /students?page=1&pageSize=10&status=active&search=nguyen
```
| sortField | string | No | createdAt | Trường sắp xếp |
| sortOrder | string | No | desc | Thứ tự (asc/desc) |
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"count": 50,
"page": 1,
"pageSize": 10,
"rows": [
{
"_id": "64f1a2b3c4d5e6f7g8h9i0j",
......@@ -71,7 +148,6 @@ GET /students?page=1&pageSize=10&status=active&search=nguyen
"email": "nguyenvana@example.com",
"phone": "0123456789",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Lập trình Node.js",
"semester": "2024-1",
"status": "active",
"startDate": "2024-01-15T00:00:00.000Z",
......@@ -80,8 +156,11 @@ GET /students?page=1&pageSize=10&status=active&search=nguyen
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
]
}
],
"page": 1,
"pageSize": 10
},
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -93,27 +172,24 @@ GET /students?page=1&pageSize=10&status=active&search=nguyen
**Description:** Lấy thông tin chi tiết một học viên
**Security:** Yêu cầu đăng nhập.
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của học viên |
**Request Example:**
```bash
GET /students/64f1a2b3c4d5e6f7g8h9i0j
```
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0j",
"fullName": "Nguyễn Văn A",
"email": "nguyenvana@example.com",
"phone": "0123456789",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Lập trình Node.js",
"semester": "2024-1",
"status": "active",
"startDate": "2024-01-15T00:00:00.000Z",
......@@ -121,7 +197,8 @@ GET /students/64f1a2b3c4d5e6f7g8h9i0j
"scheduleIds": ["64f1a2b3c4d5e6f7g8h9i0l"],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
},
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -133,6 +210,8 @@ GET /students/64f1a2b3c4d5e6f7g8h9i0j
**Description:** Tạo mới một học viên
**Security:** Yêu cầu đăng nhập (Admin/Mentor).
**Request Headers:**
```
Content-Type: application/json
......@@ -145,34 +224,23 @@ Content-Type: application/json
"email": "nguyenvanb@example.com",
"phone": "0987654321",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Lập trình Node.js",
"semester": "2024-1",
"startDate": "2024-01-15T00:00:00.000Z",
"endDate": "2024-06-15T00:00:00.000Z"
}
```
**Validation Rules:**
- `fullName`: Bắt buộc, max 100 ký tự
- `email`: Bắt buộc, định dạng email hợp lệ, unique
- `phone`: Bắt buộc, 10-11 số
- `courseId`: Bắt buộc, tồn tại trong courses collection
- `courseName`: Bắt buộc
- `semester`: Bắt buộc
- `startDate`: Bắt buộc, định dạng Date
- `endDate`: Bắt buộc, phải sau startDate
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Student created successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0m",
"fullName": "Nguyễn Văn B",
"email": "nguyenvanb@example.com",
"phone": "0987654321",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Lập trình Node.js",
"semester": "2024-1",
"status": "active",
"startDate": "2024-01-15T00:00:00.000Z",
......@@ -181,7 +249,7 @@ Content-Type: application/json
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
},
"message": "Student created successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -193,16 +261,13 @@ Content-Type: application/json
**Description:** Cập nhật thông tin học viên
**Security:** Yêu cầu đăng nhập.
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của học viên |
**Request Headers:**
```
Content-Type: application/json
```
**Request Body:**
```json
{
......@@ -210,7 +275,6 @@ Content-Type: application/json
"email": "nguyenvanb.updated@example.com",
"phone": "0987654321",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Lập trình Node.js Advanced",
"semester": "2024-2",
"status": "active"
}
......@@ -219,14 +283,14 @@ Content-Type: application/json
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Student updated successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0m",
"fullName": "Nguyễn Văn B Updated",
"email": "nguyenvanb.updated@example.com",
"phone": "0987654321",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Lập trình Node.js Advanced",
"semester": "2024-2",
"status": "active",
"startDate": "2024-01-15T00:00:00.000Z",
......@@ -235,7 +299,7 @@ Content-Type: application/json
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-11T10:00:00.000Z"
},
"message": "Student updated successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -247,21 +311,15 @@ Content-Type: application/json
**Description:** Xóa một học viên
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của học viên |
**Request Example:**
```bash
DELETE /students/64f1a2b3c4d5e6f7g8h9i0j
```
**Security:** Yêu cầu quyền Admin.
**Response Example:**
```json
{
"success": true,
"message": "Student deleted successfully"
"status": "success",
"message": "Student deleted successfully",
"responseData": "Successfully deleted student",
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -281,29 +339,25 @@ DELETE /students/64f1a2b3c4d5e6f7g8h9i0j
| page | number | No | 1 | Số trang |
| pageSize | number | No | 10 | Số lượng item mỗi trang |
| status | string | No | - | Lọc theo trạng thái (active, inactive, completed) |
| instructor | string | No | - | Lọc theo tên giảng viên |
| mentor | string | No | - | Lọc theo tên mentor |
| search | string | No | - | Tìm kiếm theo tên hoặc mã khóa học |
**Request Example:**
```bash
GET /courses?page=1&pageSize=10&status=active&search=nodejs
```
| sortField | string | No | createdAt | Trường sắp xếp |
| sortOrder | string | No | desc | Thứ tự (asc/desc) |
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"count": 25,
"page": 1,
"pageSize": 10,
"rows": [
{
"_id": "64f1a2b3c4d5e6f7g8h9i0k",
"code": "NODEJS101",
"name": "Lập trình Node.js",
"description": "Khóa học lập trình Node.js từ cơ bản đến nâng cao",
"instructor": "Nguyễn Văn C",
"mentor": "Nguyễn Văn C",
"duration": 12,
"maxStudents": 30,
"status": "active",
......@@ -311,61 +365,51 @@ GET /courses?page=1&pageSize=10&status=active&search=nodejs
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
]
}
],
"page": 1,
"pageSize": 10
},
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 2. Get Course by ID
**Endpoint:** `GET /courses/{id}`
**Description:** Lấy thông tin chi tiết một khóa học
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của khóa học |
**Request Example:**
```bash
GET /courses/64f1a2b3c4d5e6f7g8h9i0k
```
**Security:** Yêu cầu đăng nhập.
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0k",
"code": "NODEJS101",
"name": "Lập trình Node.js",
"description": "Khóa học lập trình Node.js từ cơ bản đến nâng cao",
"instructor": "Nguyễn Văn C",
"mentor": "Nguyễn Văn C",
"duration": 12,
"maxStudents": 30,
"status": "active",
"scheduleIds": ["64f1a2b3c4d5e6f7g8h9i0l"],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
},
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 3. Create Course
**Endpoint:** `POST /courses`
**Description:** Tạo mới một khóa học
**Request Headers:**
```
Content-Type: application/json
```
**Security:** Yêu cầu quyền Admin/Mentor.
**Request Body:**
```json
......@@ -373,117 +417,66 @@ Content-Type: application/json
"code": "REACT102",
"name": "Lập trình React",
"description": "Khóa học React từ cơ bản đến nâng cao",
"instructor": "Nguyễn Văn D",
"mentor": "Nguyễn Văn D",
"duration": 10,
"maxStudents": 25,
"status": "active"
}
```
**Validation Rules:**
- `code`: Bắt buộc, unique
- `name`: Bắt buộc, max 200 ký tự
- `description`: Không bắt buộc
- `instructor`: Bắt buộc
- `duration`: Bắt buộc, số > 0
- `maxStudents`: Bắt buộc, số > 0
- `status`: Bắt buộc, enum ['active', 'inactive', 'completed']
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Course created successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0n",
"code": "REACT102",
"name": "Lập trình React",
"description": "Khóa học React từ cơ bản đến nâng cao",
"instructor": "Nguyễn Văn D",
"duration": 10,
"maxStudents": 25,
"status": "active",
"scheduleIds": [],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
"createdAt": "2024-01-10T10:00:00.000Z"
},
"message": "Course created successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 4. Update Course
**Endpoint:** `PUT /courses/{id}`
**Description:** Cập nhật thông tin khóa học
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của khóa học |
**Request Headers:**
```
Content-Type: application/json
```
**Request Body:**
```json
{
"name": "Lập trình React Advanced",
"description": "Khóa học React nâng cao",
"instructor": "Nguyễn Văn D Updated",
"duration": 12,
"maxStudents": 30,
"status": "active"
}
```
**Security:** Yêu cầu quyền Admin/Mentor.
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Course updated successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0n",
"code": "REACT102",
"name": "Lập trình React Advanced",
"description": "Khóa học React nâng cao",
"instructor": "Nguyễn Văn D Updated",
"duration": 12,
"maxStudents": 30,
"status": "active",
"scheduleIds": [],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-11T10:00:00.000Z"
"status": "active"
},
"message": "Course updated successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 5. Delete Course
**Endpoint:** `DELETE /courses/{id}`
**Description:** Xóa một khóa học
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của khóa học |
**Request Example:**
```bash
DELETE /courses/64f1a2b3c4d5e6f7g8h9i0k
```
**Security:** Yêu cầu quyền Admin.
**Response Example:**
```json
{
"success": true,
"message": "Course deleted successfully"
"status": "success",
"message": "Course deleted successfully",
"responseData": "Successfully deleted course",
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -504,22 +497,19 @@ DELETE /courses/64f1a2b3c4d5e6f7g8h9i0k
| pageSize | number | No | 10 | Số lượng item mỗi trang |
| courseId | string | No | - | Lọc theo ID khóa học |
| status | string | No | - | Lọc theo trạng thái (scheduled, completed, cancelled) |
| date | string | No | - | Lọc theo ngày (YYYY-MM-DD) |
| search | string | No | - | Tìm kiếm theo tiêu đề hoặc địa điểm |
**Request Example:**
```bash
GET /schedules?page=1&pageSize=10&courseId=64f1a2b3c4d5e6f7g8h9i0k&status=scheduled
```
| mentor | string | No | - | Lọc theo mentor |
| dayOfWeek | string | No | - | Lọc theo thứ trong tuần |
| semester | string | No | - | Lọc theo học kỳ |
| sortField | string | No | dayOfWeek | Trường sắp xếp |
| sortOrder | string | No | asc | Thứ tự (asc/desc) |
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"count": 40,
"page": 1,
"pageSize": 10,
"rows": [
{
"_id": "64f1a2b3c4d5e6f7g8h9i0l",
......@@ -534,34 +524,28 @@ GET /schedules?page=1&pageSize=10&courseId=64f1a2b3c4d5e6f7g8h9i0k&status=schedu
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
]
}
],
"page": 1,
"pageSize": 10
},
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 2. Get Schedule by ID
**Endpoint:** `GET /schedules/{id}`
**Description:** Lấy thông tin chi tiết một lịch học
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của lịch học |
**Request Example:**
```bash
GET /schedules/64f1a2b3c4d5e6f7g8h9i0l
```
**Security:** Yêu cầu đăng nhập.
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0l",
"title": "Buổi 1 - Giới thiệu Node.js",
"description": "Giới thiệu tổng quan về Node.js",
......@@ -573,22 +557,18 @@ GET /schedules/64f1a2b3c4d5e6f7g8h9i0l
"studentIds": ["64f1a2b3c4d5e6f7g8h9i0j"],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
},
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 3. Create Schedule
**Endpoint:** `POST /schedules`
**Description:** Tạo mới một lịch học
**Request Headers:**
```
Content-Type: application/json
```
**Security:** Yêu cầu quyền Admin/Mentor.
**Request Body:**
```json
......@@ -603,108 +583,57 @@ Content-Type: application/json
}
```
**Validation Rules:**
- `title`: Bắt buộc, max 200 ký tự
- `description`: Không bắt buộc
- `courseId`: Bắt buộc, tồn tại trong courses collection
- `date`: Bắt buộc, định dạng Date
- `duration`: Bắt buộc, số > 0 (phút)
- `location`: Bắt buộc
- `status`: Bắt buộc, enum ['scheduled', 'completed', 'cancelled']
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Schedule created successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0o",
"title": "Buổi 2 - Node.js Modules",
"description": "Tìm hiểu về Node.js modules",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"date": "2024-01-17T09:00:00.000Z",
"duration": 120,
"location": "Phòng A102",
"status": "scheduled",
"studentIds": [],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
"createdAt": "2024-01-10T10:00:00.000Z"
},
"message": "Schedule created successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 4. Update Schedule
**Endpoint:** `PUT /schedules/{id}`
**Description:** Cập nhật thông tin lịch học
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của lịch học |
**Request Headers:**
```
Content-Type: application/json
```
**Request Body:**
```json
{
"title": "Buổi 2 - Node.js Modules Updated",
"description": "Tìm hiểu sâu về Node.js modules",
"location": "Phòng A103",
"status": "scheduled"
}
```
**Security:** Yêu cầu quyền Admin/Mentor.
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Schedule updated successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0o",
"title": "Buổi 2 - Node.js Modules Updated",
"description": "Tìm hiểu sâu về Node.js modules",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"date": "2024-01-17T09:00:00.000Z",
"duration": 120,
"location": "Phòng A103",
"status": "scheduled",
"studentIds": [],
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-11T10:00:00.000Z"
"status": "scheduled"
},
"message": "Schedule updated successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 5. Delete Schedule
**Endpoint:** `DELETE /schedules/{id}`
**Description:** Xóa một lịch học
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của lịch học |
**Request Example:**
```bash
DELETE /schedules/64f1a2b3c4d5e6f7g8h9i0l
```
**Security:** Yêu cầu quyền Admin.
**Response Example:**
```json
{
"success": true,
"message": "Schedule deleted successfully"
"status": "success",
"message": "Schedule deleted successfully",
"responseData": "Successfully deleted schedule",
"timeStamp": "2026-04-13 13:00:00"
}
```
......@@ -725,22 +654,18 @@ DELETE /schedules/64f1a2b3c4d5e6f7g8h9i0l
| pageSize | number | No | 10 | Số lượng item mỗi trang |
| studentId | string | No | - | Lọc theo ID học viên |
| scheduleId | string | No | - | Lọc theo ID lịch học |
| courseId | string | No | - | Lọc theo ID khóa học |
| status | string | No | - | Lọc theo trạng thái (confirmed, cancelled, completed) |
| search | string | No | - | Tìm kiếm theo ghi chú |
**Request Example:**
```bash
GET /bookings?page=1&pageSize=10&status=confirmed&studentId=64f1a2b3c4d5e6f7g8h9i0j
```
| sortField | string | No | bookingDate | Trường sắp xếp |
| sortOrder | string | No | desc | Thứ tự (asc/desc) |
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"count": 30,
"page": 1,
"pageSize": 10,
"rows": [
{
"_id": "64f1a2b3c4d5e6f7g8h9i0p",
......@@ -752,58 +677,44 @@ GET /bookings?page=1&pageSize=10&status=confirmed&studentId=64f1a2b3c4d5e6f7g8h9
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
]
}
],
"page": 1,
"pageSize": 10
},
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 2. Get Booking by ID
**Endpoint:** `GET /bookings/{id}`
**Description:** Lấy thông tin chi tiết một đăng ký
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của đăng ký |
**Request Example:**
```bash
GET /bookings/64f1a2b3c4d5e6f7g8h9i0p
```
**Security:** Yêu cầu đăng nhập.
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Thành công",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0p",
"studentId": "64f1a2b3c4d5e6f7g8h9i0j",
"scheduleId": "64f1a2b3c4d5e6f7g8h9i0l",
"bookingDate": "2024-01-12T10:00:00.000Z",
"status": "confirmed",
"notes": "Học viên đã xác nhận tham gia",
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
}
"status": "confirmed"
},
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 3. Create Booking
**Endpoint:** `POST /bookings`
**Description:** Tạo mới một đăng ký
**Request Headers:**
```
Content-Type: application/json
```
**Security:** Yêu cầu quyền Admin/Mentor/Student.
**Request Body:**
```json
......@@ -815,105 +726,110 @@ Content-Type: application/json
}
```
**Validation Rules:**
- `studentId`: Bắt buộc, tồn tại trong students collection
- `scheduleId`: Bắt buộc, tồn tại trong schedules collection
- `status`: Bắt buộc, enum ['confirmed', 'cancelled', 'completed']
- `notes`: Không bắt buộc, max 500 ký tự
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Booking created successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0q",
"studentId": "64f1a2b3c4d5e6f7g8h9i0j",
"scheduleId": "64f1a2b3c4d5e6f7g8h9i0l",
"bookingDate": "2024-01-12T10:00:00.000Z",
"status": "confirmed",
"notes": "Đăng ký tham gia buổi học",
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-10T10:00:00.000Z"
"status": "confirmed"
},
"message": "Booking created successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 4. Update Booking
**Endpoint:** `PUT /bookings/{id}`
**Description:** Cập nhật thông tin đăng ký
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của đăng ký |
**Request Headers:**
```
Content-Type: application/json
```
**Request Body:**
```json
{
"status": "completed",
"notes": "Học viên đã hoàn thành buổi học"
}
```
**Security:** Yêu cầu quyền Admin/Mentor/Student.
**Response Example:**
```json
{
"success": true,
"data": {
"status": "success",
"message": "Booking updated successfully",
"responseData": {
"_id": "64f1a2b3c4d5e6f7g8h9i0q",
"studentId": "64f1a2b3c4d5e6f7g8h9i0j",
"scheduleId": "64f1a2b3c4d5e6f7g8h9i0l",
"bookingDate": "2024-01-12T10:00:00.000Z",
"status": "completed",
"notes": "Học viên đã hoàn thành buổi học",
"createdAt": "2024-01-10T10:00:00.000Z",
"updatedAt": "2024-01-11T10:00:00.000Z"
"status": "completed"
},
"message": "Booking updated successfully"
"timeStamp": "2026-04-13 13:00:00"
}
```
---
## 5. Delete Booking
**Endpoint:** `DELETE /bookings/{id}`
**Description:** Xóa một đăng ký
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | ID của đăng ký |
**Request Example:**
```bash
DELETE /bookings/64f1a2b3c4d5e6f7g8h9i0p
```
**Security:** Yêu cầu quyền Admin.
**Response Example:**
```json
{
"success": true,
"message": "Booking deleted successfully"
"status": "success",
"message": "Booking deleted successfully",
"responseData": "Successfully deleted booking",
"timeStamp": "2026-04-13 13:00:00"
}
```
---
# TERMS API
## 1. Get All Terms
**Endpoint:** `GET /terms`
**Security:** Yêu cầu quyền Admin.
**Query Parameters:** `page`, `pageSize`, `sortField`, `sortOrder`, `search`, `year`.
## 2. Get Term by ID
**Endpoint:** `GET /terms/{id}`
## 3. Create Term
**Endpoint:** `POST /terms`
## 4. Update Term
**Endpoint:** `PUT /terms/{id}`
## 5. Delete Term
**Endpoint:** `DELETE /terms/{id}`
---
# LOGS API
## 1. Get All Logs
**Endpoint:** `GET /logs/getAllWithinTimeRange`
**Security:** Yêu cầu quyền Admin.
**Description:** Lọc log hệ thống theo thời gian, loại log, etc.
---
# DATA MODELS
## Student Model
## User Model (Mongoose)
```typescript
interface IUser {
_id: string;
email: string;
username: string;
first_name?: string;
last_name?: string;
phone?: string;
address?: string;
avatar?: string;
status: "active" | "inactive" | "locked";
roles: string[];
last_login?: Date;
}
```
## Student Model (Mongoose)
```typescript
interface IStudent {
_id: string;
......@@ -921,70 +837,39 @@ interface IStudent {
email: string;
phone: string;
courseId: string;
courseName: string;
semester: string;
status: 'active' | 'inactive' | 'completed';
startDate: Date;
endDate: Date;
scheduleIds: string[];
createdAt: Date;
updatedAt: Date;
createdBy?: string;
updatedBy?: string;
}
```
## Course Model
## Term Model (Mongoose)
```typescript
interface ICourse {
interface ITerm {
_id: string;
code: string;
name: string;
description: string;
instructor: string;
duration: number;
maxStudents: number;
description?: string;
startDate: Date;
endDate: Date;
status: 'active' | 'inactive' | 'completed';
scheduleIds: string[];
createdAt: Date;
updatedAt: Date;
createdBy?: string;
updatedBy?: string;
courseIds: string[];
}
```
## Schedule Model
## Course Model
```typescript
interface ISchedule {
interface ICourse {
_id: string;
title: string;
code: string;
name: string;
description: string;
courseId: string;
date: Date;
mentor: string;
duration: number;
location: string;
status: 'scheduled' | 'completed' | 'cancelled';
studentIds: string[];
createdAt: Date;
updatedAt: Date;
createdBy?: string;
updatedBy?: string;
}
```
## Booking Model
```typescript
interface IBooking {
_id: string;
studentId: string;
scheduleId: string;
bookingDate: Date;
status: 'confirmed' | 'cancelled' | 'completed';
notes: string;
createdAt: Date;
updatedAt: Date;
createdBy?: string;
updatedBy?: string;
maxStudents: number;
status: 'active' | 'inactive' | 'completed';
scheduleIds: string[];
}
```
......@@ -995,6 +880,8 @@ interface IBooking {
| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| VALIDATION_ERROR | 400 | Request validation failed |
| UNAUTHORIZED | 401 | Missing or invalid token |
| FORBIDDEN | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource not found |
| DUPLICATE_KEY | 409 | Duplicate resource (e.g., email already exists) |
| INTERNAL_ERROR | 500 | Internal server error |
......@@ -1005,44 +892,7 @@ interface IBooking {
## Swagger UI
Interactive API documentation available at: `http://localhost:3001/api-docs`
## Example cURL Commands
### Get All Students
```bash
curl -X GET "http://localhost:3001/api/v1.0/students?page=1&pageSize=10"
```
### Create Student
```bash
curl -X POST "http://localhost:3001/api/v1.0/students" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Test Student",
"email": "test@example.com",
"phone": "0123456789",
"courseId": "64f1a2b3c4d5e6f7g8h9i0k",
"courseName": "Test Course",
"semester": "2024-1",
"startDate": "2024-01-15T00:00:00.000Z",
"endDate": "2024-06-15T00:00:00.000Z"
}'
```
### Update Student
```bash
curl -X PUT "http://localhost:3001/api/v1.0/students/64f1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Updated Student Name",
"status": "active"
}'
```
### Delete Student
```bash
curl -X DELETE "http://localhost:3001/api/v1.0/students/64f1a2b3c4d5e6f7g8h9i0j"
```
(Provides fully up-to-date and executable schemas tested against real code).
---
......@@ -1050,8 +900,10 @@ curl -X DELETE "http://localhost:3001/api/v1.0/students/64f1a2b3c4d5e6f7g8h9i0j"
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2026-04-10 | Initial API contract for Phase 1 - Students, Courses, Schedules, Bookings CRUD APIs |
| 1.0.0 | 2026-04-10 | Initial API contract |
| 1.1.0 | 2026-04-13 | Updated Response format (ResponseDTO), added JWT Auth, User, and Term APIs. |
---
*Last Updated: 2026-04-10*
*Last Updated: 2026-04-13*
src/models/Course.ts
View file @ dd266982
......@@ -125,7 +125,6 @@ CourseSchema.virtual('availableSlots').get(function (this: ICourse) {
});
// Index for better query performance
CourseSchema.index({ code: 1 });
CourseSchema.index({ status: 1 });
CourseSchema.index({ instructor: 1 });
CourseSchema.index({ name: 'text' });
......
src/models/Term.ts
View file @ dd266982
......@@ -79,7 +79,6 @@ const TermSchema: Schema = new Schema({
});
// Index for better query performance
TermSchema.index({ name: 1 }, { unique: true });
TermSchema.index({ status: 1 });
TermSchema.index({ startDate: 1, endDate: 1 });
TermSchema.index({ name: 'text' });
......
src/models/mongodb/UserSession.ts
View file @ dd266982
......@@ -53,7 +53,6 @@ const UserSessionSchemaEntity: Schema = new Schema(
// TTL index to automatically remove expired sessions
UserSessionSchemaEntity.index({ refresh_expires_at: 1 }, { expireAfterSeconds: 0 });
UserSessionSchemaEntity.index({ session_token: 1 });
UserSessionSchemaEntity.index({ user: 1 });
export const UserSession = mongoose.models.UserSession || mongoose.model<IUserSession>('UserSession', UserSessionSchemaEntity);
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment