From e3f9d7914f36b846d1fbf0a2d0bf36129f26675c Mon Sep 17 00:00:00 2001 From: nthanhtoan61 Date: Sat, 11 Apr 2026 14:39:25 +0700 Subject: [PATCH] env , readme --- .env.example | Bin 1204 -> 634 bytes README.md | 343 ++++++++++++++++++++++++++++----------------------- 2 files changed, 191 insertions(+), 152 deletions(-) diff --git a/.env.example b/.env.example index e9b420f17e1efbf9da0c0a96123ca4c031e73c69..b7a8a0f660ddb11889b0fac19ffcc9f2bb867140 100644 GIT binary patch delta 94 hcmdnO`HN*j)MOT>u+1?{ag3AQSd_f<7^nle7yui64A1}o literal 1204 zcma)*TW{Jx5QWdPf5l3DX{DyQ^b#pjR1qK)HK7PXt3DxO96${h*@l)s-{hOIU4r_M zXtnlUX3v>9GxPAbt8eP*M(293BgU~Jec`O{XGeO+Sv4bdxM`@VA+w|Jyc#RfhIy~0 zR+_U~Cv4&6^G{Y+r|~>Bw8`*Gf6hc#|<^oGi+H%uV7rHTbTl9zF-P0D|hAv7C+ThJS9}~V~-Ih97mSf)Dqr?(La?Ve5>UDEU85U!GE^UXUf9Lw+qwqa|wm+WZh@H{A z-$n8gwnC+$*Wpi;-}OcjOXc4X)h(vP^)0;Yv#Yvgr>}L>1jUN_48&@ATmS3NP*!?I zgs*!pMqxgD_3=cb~$%%@a2*mU!lMCc$-Z8-|ew? hj`d0cONC{tCHoOG +cd uldp-degree-mangement-system -### 2. Cài Đặt Dependencies - -```bash +# 2. Cài dependencies npm install + +# 3. Tạo file .env từ template +cp .env.example .env ``` -### 3. Cấu Hình Môi Trường +Chỉnh sửa `.env`: -Tạo file `.env` trong thư mục gốc với các cấu hình sau: +```env +PORT=3001 +HOST=0.0.0.0 +MONGODB_URI=mongodb://localhost:27017/uldp +SESSION_SECRET=your-session-secret -``` -PORT=3000 -MONGODB_URI=mongodb://localhost:27017/SIMS -BACKEND_URL=http://localhost:3000 -FRONTEND_URL=http://localhost:8080 -SESSION_SECRET=your_secret_key +# 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 ``` -## Hệ Thống Migration +--- -Hệ thống migration sử dụng cơ chế tracking để quản lý các migration đã chạy, tương tự Laravel. Tất cả các file migration được tự động phát hiện trong thư mục `scripts/` (trừ các file quản lý migration). - -### Các Lệnh Migration - -#### 1. Chạy Migrations Chưa Chạy - -Chạy tất cả các migrations chưa được thực thi (có tracking, tự động skip migrations đã chạy): - -```bash -npm run migrate -``` - -**Tính năng:** - -- Tự động phát hiện tất cả file migration trong thư mục `scripts/` -- Chỉ chạy các migrations chưa được thực thi -- Tự động skip migrations đã chạy -- Tracking migrations trong database với batch number -- Hiển thị bảng kết quả với trạng thái: DONE, SKIPPED, FAIL - -#### 2. Chạy Lại Tất Cả Migrations (Fresh) - -Xóa tất cả tracking và chạy lại tất cả migrations từ đầu: - -```bash -npm run migrate-fresh -``` - -**Lưu ý:** Lệnh này sẽ xóa tất cả records trong collection `migrations` và chạy lại tất cả migrations từ đầu. Sử dụng cẩn thận trong môi trường production. - -#### 3. Xem Trạng Thái Migrations - -Kiểm tra trạng thái của tất cả migrations: - -```bash -npm run migrate-status -``` - -**Hiển thị:** - -- Danh sách tất cả migrations -- Trạng thái: Ran hoặc Pending -- Batch number và thời gian chạy (nếu đã chạy) -- Tóm tắt: số lượng migrations đã chạy và chưa chạy - -#### 4. Rollback Migrations - -**Rollback một migration cụ thể:** - -```bash -npm run migrate-rollback -``` - -**Rollback batch cuối cùng:** - -```bash -npm run migrate-rollback --batch -``` - -**Ví dụ:** - -```bash -npm run migrate-rollback 2025_12_02_114125_home -npm run migrate-rollback --batch -``` - -#### 5. Tạo Migration Mới - -Tạo file migration mới với format timestamp tự động: - -```bash -npm run make-migration -``` - -**Ví dụ:** - -```bash -npm run make-migration create_users_table -``` - -File migration sẽ được tạo với format: `YYYY_MM_DD_HHMMSS_.js` - -**Template migration:** - -- Tự động kết nối database -- Có sẵn cấu trúc cơ bản -- Tự động disconnect sau khi hoàn thành - -### Quy Tắc Migration - -1. **Format tên file:** `YYYY_MM_DD_HHMMSS_migration_name.js` -2. **Tự động phát hiện:** Tất cả file `.js` trong thư mục `scripts/` (trừ các file quản lý) -3. **Tracking:** Migrations được track trong collection `migrations` của MongoDB -4. **Batch system:** Migrations được nhóm theo batch để dễ quản lý -5. **Thứ tự chạy:** Migrations được sắp xếp theo tên (alphabetical) để đảm bảo thứ tự nhất quán - -## Chạy Ứng Dụng - -### Chế Độ Phát Triển +## Chạy ứng dụng ```bash +# Development (nodemon) npm run dev -``` -Ứng dụng sẽ chạy trên `http://localhost:3000` - -### Chế Độ Sản Xuất - -```bash +# Production npm start ``` -## Cấu Trúc Thư Mục +Server chạy tại `http://localhost:3001` + +--- + +## Cấu trúc thư mục ``` -sims-cms/ -│ -├── config/ # Cấu hình ứng dụng +uldp-degree-mangement-system/ +├── config/ # Kết nối database +├── constants/ # Audit action enums ├── controllers/ # Logic xử lý -├── data/ # Dữ liệu JSON gốc -├── middleware/ # Các middleware -├── models/ # Mongoose models -├── public/ # Tài nguyên tĩnh -├── routes/ # Định nghĩa routes -├── scripts/ # Migration scripts -├── utils/ # Các hàm tiện ích -└── views/ # Giao diện EJS +│ ├── 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 ``` -## Các Lệnh Quan Trọng +--- -### Ứng Dụng +## Admin Panel -- `npm run dev`: Chạy ứng dụng ở chế độ phát triển (với nodemon) -- `npm start`: Chạy ứng dụng ở chế độ sản xuất +Truy cập: `http://localhost:3001/admin/dashboard` -### Migration +| Trang | URL | +|---|---| +| Dashboard | `/admin/dashboard` | +| Qualifications | `/admin/qualification` | +| Certificates | `/admin/certificate` | +| Departments | `/admin/department` | +| Levels | `/admin/level` | +| Audit Logs | `/admin/audit-logs` | -- `npm run migrate`: Chạy tất cả migrations chưa chạy -- `npm run migrate-fresh`: Chạy lại tất cả migrations từ đầu -- `npm run migrate-status`: Xem trạng thái tất cả migrations -- `npm run migrate-rollback `: Rollback một migration cụ thể -- `npm run migrate-rollback --batch`: Rollback batch cuối cùng -- `npm run make-migration `: Tạo migration file mới +--- + +## 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 |