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