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

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

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

{
  "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:

{
  "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