forked from UKSOURCE/cms.hailearning.edu.vn
225 lines
5.2 KiB
Markdown
225 lines
5.2 KiB
Markdown
# ULDP Degree Management System
|
|
|
|
Backend quản lý văn bằng và chứng chỉ cho ULDP, cung cấp admin panel và public API để xác minh văn bằng.
|
|
|
|
---
|
|
|
|
## Yêu cầu hệ thống
|
|
|
|
- Node.js v16+
|
|
- MongoDB v4.4+
|
|
- npm v8+
|
|
|
|
---
|
|
|
|
## Cài đặt
|
|
|
|
```bash
|
|
# 1. Clone
|
|
git clone <repo-url>
|
|
cd uldp-degree-mangement-system
|
|
|
|
# 2. Cài dependencies
|
|
npm install
|
|
|
|
# 3. Tạo file .env từ template
|
|
cp .env.example .env
|
|
```
|
|
|
|
Chỉnh sửa `.env`:
|
|
|
|
```env
|
|
PORT=3001
|
|
HOST=0.0.0.0
|
|
MONGODB_URI=mongodb://localhost:27017/uldp
|
|
SESSION_SECRET=your-session-secret
|
|
|
|
# API key cho public verification endpoints
|
|
API_KEY=your-api-key-here
|
|
|
|
# Secret để ký URL tài liệu (HMAC-SHA256)
|
|
FILE_SIGN_SECRET=your-file-sign-secret
|
|
|
|
FRONTEND_URL=https://your-frontend-domain.com
|
|
```
|
|
|
|
---
|
|
|
|
## Chạy ứng dụng
|
|
|
|
```bash
|
|
# Development (nodemon)
|
|
npm run dev
|
|
|
|
# Production
|
|
npm start
|
|
```
|
|
|
|
Server chạy tại `http://localhost:3001`
|
|
|
|
---
|
|
|
|
## Cấu trúc thư mục
|
|
|
|
```
|
|
uldp-degree-mangement-system/
|
|
├── config/ # Kết nối database
|
|
├── constants/ # Audit action enums
|
|
├── controllers/ # Logic xử lý
|
|
│ ├── qualificationController.js
|
|
│ ├── certificateController.js
|
|
│ ├── departmentController.js
|
|
│ ├── levelController.js
|
|
│ ├── dashboardController.js
|
|
│ └── auditLogController.js
|
|
├── middleware/
|
|
│ ├── apiKey.js # Xác thực API key (header X-API-Key)
|
|
│ ├── auth.js # Session auth cho admin
|
|
│ └── upload.js # Multer upload config
|
|
├── models/
|
|
│ ├── qualification.js
|
|
│ ├── certificate.js
|
|
│ ├── department.js
|
|
│ ├── level.js
|
|
│ └── auditLog.js
|
|
├── private/uploads/ # File tài liệu (không public)
|
|
├── public/ # Static assets
|
|
├── routes/
|
|
│ ├── admin.js # Admin panel routes
|
|
│ ├── auth.js # Login/logout
|
|
│ └── index.js # Public API routes
|
|
├── utils/
|
|
│ └── signedUrl.js # Tạo và xác minh signed URLs
|
|
└── views/ # EJS templates
|
|
```
|
|
|
|
---
|
|
|
|
## Admin Panel
|
|
|
|
Truy cập: `http://localhost:3001/admin/dashboard`
|
|
|
|
| Trang | URL |
|
|
|---|---|
|
|
| Dashboard | `/admin/dashboard` |
|
|
| Qualifications | `/admin/qualification` |
|
|
| Certificates | `/admin/certificate` |
|
|
| Departments | `/admin/department` |
|
|
| Levels | `/admin/level` |
|
|
| Audit Logs | `/admin/audit-logs` |
|
|
|
|
---
|
|
|
|
## Public API
|
|
|
|
### Authentication
|
|
|
|
API key gửi qua header (bắt buộc):
|
|
|
|
```
|
|
X-API-Key: your-api-key
|
|
```
|
|
|
|
Fallback: `?api_key=your-api-key` (query param, không khuyến khích)
|
|
|
|
---
|
|
|
|
### Verify Degree (Qualification)
|
|
|
|
```
|
|
GET /api/verify-degree/{qualification_number}
|
|
X-API-Key: your-api-key
|
|
```
|
|
|
|
**Response 200:**
|
|
```json
|
|
{
|
|
"full_name": "Nguyen Van A",
|
|
"program_name": "Doctor of Philosophy in Business Management",
|
|
"degree_id": "PHD-2024-001",
|
|
"passport_number": "P12345678",
|
|
"address": "123 Main Street",
|
|
"degree_image": ["https://host/secure-files/doc.jpg?token=xxx&expires=1712345678"],
|
|
"topic_name": "Research Topic Title",
|
|
"topic_short_desc": "Abstract..."
|
|
}
|
|
```
|
|
|
|
> `topic_name` có mặt → frontend hiển thị PhD view. Vắng mặt → MBA/Master view.
|
|
|
|
---
|
|
|
|
### Verify Certificate
|
|
|
|
```
|
|
GET /api/verify-certificate/{certification_number}
|
|
X-API-Key: your-api-key
|
|
```
|
|
|
|
**Response 200:**
|
|
```json
|
|
{
|
|
"full_name": "Tran Thi B",
|
|
"certification_title": "Master of Business Administration",
|
|
"certificate_id": "MBA-2024-001",
|
|
"passport_number": "P98765432",
|
|
"address": "456 Lake Road",
|
|
"certificate_image": ["https://host/secure-files/cert.jpg?token=xxx&expires=1712345678"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### HTTP Status Codes
|
|
|
|
| Status | Ý nghĩa |
|
|
|---|---|
|
|
| `200` | Tìm thấy — trả về dữ liệu |
|
|
| `401` | API key không hợp lệ |
|
|
| `404` | Không tìm thấy hoặc đã bị thu hồi |
|
|
| `500` | Lỗi server |
|
|
|
|
---
|
|
|
|
### Document URLs (Signed)
|
|
|
|
File tài liệu được serve qua signed URL, hết hạn sau **15 phút**:
|
|
|
|
```
|
|
GET /secure-files/{filename}?token={hmac_token}&expires={unix_timestamp}
|
|
```
|
|
|
|
- Không có API key trong URL
|
|
- Token được ký bằng `HMAC-SHA256(FILE_SIGN_SECRET, filename:expires)`
|
|
- Mỗi lần gọi verify API → nhận URL mới với token mới
|
|
|
|
---
|
|
|
|
## Phân biệt Qualification vs Certificate
|
|
|
|
| | Qualification | Certificate |
|
|
|---|---|---|
|
|
| Lookup bằng | `qualification_number` | `certification_number` |
|
|
| Endpoint | `/api/verify-degree/:id` | `/api/verify-certificate/:id` |
|
|
| Field tên | `program_name` | `certification_title` |
|
|
| Field ID | `degree_id` | `certificate_id` |
|
|
| Field ảnh | `degree_image` | `certificate_image` |
|
|
| PhD fields | `topic_name`, `topic_short_desc` | — |
|
|
|
|
---
|
|
|
|
## Bảng màu (Design System)
|
|
|
|
| Token | Hex | Dùng cho |
|
|
|---|---|---|
|
|
| Primary | `#0a2347` | Buttons, sidebar, headings |
|
|
| Primary Light | `#1a3a6b` | Hover, gradients |
|
|
| Accent | `#bc9f69` | Active border, highlights |
|
|
| Success | `#1a7a4a` | Active status |
|
|
| Danger | `#c0392b` | Revoked, delete |
|
|
| Warning | `#d97706` | Warning states |
|
|
| Info | `#0e7490` | Certificate badges |
|
|
| Background | `#f0f2f7` | Page background |
|
|
| Text Main | `#1e293b` | Body text |
|
|
| Text Muted | `#64748b` | Secondary text |
|