2025-11-12 23:28:16 +07:00
|
|
|
# hrms-api-org
|
|
|
|
|
|
|
|
|
|
ระบบ API สำหรับจัดการข้อมูลบุคลากรและโครงสร้างองค์กร (HRMS)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## ✨ Features
|
|
|
|
|
|
|
|
|
|
- **RESTful API** (Express)
|
|
|
|
|
- **ฐานข้อมูล MySQL** (TypeORM)
|
|
|
|
|
- **Cronjob อัตโนมัติ** (node-cron)
|
|
|
|
|
- **WebSocket** สำหรับ real-time
|
|
|
|
|
- **RabbitMQ integration**
|
|
|
|
|
- **Swagger UI** สำหรับ API docs
|
|
|
|
|
- รองรับการ **import/export ข้อมูล**
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🗂️ โครงสร้างโปรเจกต์หลัก
|
|
|
|
|
|
|
|
|
|
| Path | รายละเอียด |
|
|
|
|
|
| ----------------------------------- | ------------------------------------- |
|
|
|
|
|
| `src/controllers/` | API Controllers |
|
|
|
|
|
| `src/entities/` | Entity สำหรับ TypeORM |
|
|
|
|
|
| `src/services/` | Service logic (RabbitMQ, WebSocket) |
|
|
|
|
|
| `src/database/data-source.ts` | ตั้งค่าเชื่อมต่อฐานข้อมูล |
|
|
|
|
|
| `src/migration/` | ไฟล์ migration ของฐานข้อมูล |
|
|
|
|
|
| `static/` | ไฟล์ static และ config |
|
|
|
|
|
| `scripts/clean-migration-fk-idx.js` | สคริปต์ลบบรรทัด FK*/idx* ใน migration |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🚀 การใช้งานเบื้องต้น
|
|
|
|
|
|
|
|
|
|
1. **ติดตั้ง dependencies**
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm install
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
2. **สร้างไฟล์ `.env`**
|
|
|
|
|
|
|
|
|
|
- กำหนดค่าฐานข้อมูลและ API_KEY ตามต้องการ
|
|
|
|
|
|
|
|
|
|
3. **Build และ Start**
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run build
|
|
|
|
|
npm start
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
4. **ดู API docs**
|
|
|
|
|
- เปิดที่ `http://localhost:3000/api-docs`
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🛠️ คำสั่งที่สำคัญ (npm scripts)
|
|
|
|
|
|
|
|
|
|
- `npm run dev` : รันแบบ development (hot reload)
|
|
|
|
|
- `npm run build` : สร้างไฟล์สำหรับ production
|
|
|
|
|
- `npm run migration:generate` : สร้าง migration ใหม่ เช่น
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm run migration:generate src/migration/update_table_0811202s
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- `npm run migration:run` : รัน migration
|
|
|
|
|
- `node scripts/clean-migration-fk-idx.js` : ลบบรรทัดที่มี `FK_` หรือ `idx_` ใน migration อัตโนมัติ (ควรรันหลัง gen migration ทุกครั้ง)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🐳 การ Build/Deploy ด้วย act (local GitHub Actions)
|
|
|
|
|
|
|
|
|
|
หากต้องการ build และ deploy ด้วย workflow release (เช่น ทดสอบ pipeline บนเครื่อง)
|
|
|
|
|
ให้ใช้คำสั่งนี้:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
act workflow_dispatch -W .github/workflows/release.yaml --input IMAGE_VER=latest -s DOCKER_USER=admin -s DOCKER_PASS=FPTadmin2357 -s SSH_PASSWORD=FPTadmin2357
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**อธิบาย option ที่ใช้:**
|
|
|
|
|
|
|
|
|
|
- `-W .github/workflows/release.yaml` : ระบุ workflow ที่จะรัน
|
|
|
|
|
- `--input IMAGE_VER=latest` : กำหนด tag ของ docker image (เช่น latest)
|
|
|
|
|
- `-s DOCKER_USER=...` : กำหนด secret สำหรับ docker registry
|
|
|
|
|
- `-s DOCKER_PASS=...` : กำหนด secret สำหรับ docker registry
|
|
|
|
|
- `-s SSH_PASSWORD=...` : กำหนด secret สำหรับ ssh deploy
|
|
|
|
|
|
|
|
|
|
> ⚠️ **หมายเหตุ:** สำหรับ production ห้ามใช้รหัสผ่านจริงใน public repo หรือแชร์ credentials
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## ⚠️ หมายเหตุเกี่ยวกับ Migration
|
|
|
|
|
|
|
|
|
|
- หลังจากใช้ `npm run migration:generate` แล้ว **ต้องลบบรรทัดที่มี `FK_` หรือ `idx_` ออกจากไฟล์ migration ทุกครั้ง** (ทั้งในฟังก์ชัน up/down)
|
|
|
|
|
- สามารถใช้สคริปต์นี้ช่วยลบอัตโนมัติ:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
node scripts/clean-migration-fk-idx.js
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- สคริปต์นี้จะค้นหาและแทนที่บรรทัดที่มี `FK_` หรือ `idx_` ด้วย comment `// removed FK_/idx_ auto-cleanup` ในทุกไฟล์ migration
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 📄 License
|
|
|
|
|
|
|
|
|
|
Distributed under the ISC License.
|
