hrms-api-backend/README.md

BMA.EHR - HRMS API Backend

ระบบบริหารจัดการทรัพยากรบุคคล (Human Resource Management System) พัฒนาด้วยสถาปัตยกรรม Microservices บน .NET

---

Tech Stack

Category	Technology
Framework	.NET 6.0 / 7.0 / 8.0
Architecture	Clean Architecture, DDD, CQRS
Database	MySQL (Entity Framework Core)
Authentication	JWT + Keycloak
Message Queue	RabbitMQ
Object Storage	MinIO
Background Jobs	Hangfire
Logging	Serilog + Elasticsearch
Error Tracking	Sentry
API Documentation	Swagger / OpenAPI
Containerization	Docker
Testing	xUnit, k6 (Load Testing)

---

โครงสร้างโปรเจกต์ (Project Structure)

BMA.EHR.Solution.sln
├── src/                                    # Core Libraries
│   ├── BMA.EHR.Domain/                     # Domain layer (Entities, Business Rules)
│   ├── BMA.EHR.Application/                # Application layer (Use Cases, Interfaces)
│   └── BMA.EHR.Infrastructure/             # Infrastructure layer (Data Access, External Services)
│
└── Service/                                # Microservices
    ├── BMA.EHR.Command.Service/             # Command/CQRS API Gateway
    ├── BMA.EHR.MetaData.Service/            # ข้อมูลอ้างอิง (คำนำหน้า, หมู่เลือด, ศาสนา ฯลฯ)
    ├── BMA.EHR.Placement.Service/           # การบริจาค/สั่งย้าย/แต่งตั้ง
    ├── BMA.EHR.OrganizationEmployee.Service/ # โครงสร้างองค์กรและบุคลากร
    ├── BMA.EHR.Discipline.Service/          # การ discipline บุคลากร
    ├── BMA.EHR.Retirement.Service/          # การเกษียณอายุราชการ
    ├── BMA.EHR.Report.Service/              # รายงาน
    ├── BMA.EHR.Insignia/                    # เครื่องราชอิสริยาภรณ์
    ├── BMA.EHR.Leave/                       # ระบบลา
    └── BMA.EHR.CheckInConsumer/             # ลงเวลาปฏิบัติงาน

---

โมดูลหลัก (Key Modules)

การบริหารทรัพยากรบุคคล

• Placement Service - สั่งย้าย, แต่งตั้ง, เลื่อนตำแหน่ง, โอนย้ายบุคลากร
• Organization Employee Service - จัดการโครงสร้างองค์กร, ตำแหน่ง, ข้อมูลบุคลากร
• Leave Service - การลางาน, การอนุมัติ, วันหยุดนักขัตฤกษ์, ยอดวันลาคงเหลือ
• Discipline Service - การดำเนินการ discipline, การสืบสวน, เอกสารที่เกี่ยวข้อง
• Retirement Service - การเกษียณอายุ, เอกสาร, สิทธิประโยชน์
• Insignia Service - เครื่องราชอิสริยาภรณ์และรางวัล
• CheckIn Consumer - ติดตามการลงเวลาปฏิบัติงาน

ระบบสนับสนุน

• Metadata Service - ข้อมูลอ้างอิง (คำนำหน้าชื่อ, หมู่เลือด, ศาสนา, ระดับการศึกษา ฯลฯ)
• Report Service - สร้างรายงาน PDF/Excel
• Command Service - API Gateway สำหรับ CQRS command operations

ฟีเจอร์เด่น

• Real-time Notifications - แจ้งเตือนผ่าน WebSocket
• Background Processing - งานที่กำหนดเวลาผ่าน Hangfire
• Event-Driven Communication - สื่อสารระหว่าง services ผ่าน RabbitMQ
• Document Generation - สร้างเอกสาร PDF/Excel
• Audit Trail - บันทึกประวัติการเปลี่ยนแปลงข้อมูลทั้งหมด

---

API Endpoints

API ใช้ versioning และสามารถดูรายละเอียดได้ผ่าน Swagger UI:

/api/v1/placement       # การบริจาค/สั่งย้าย/แต่งตั้ง
/api/v1/leave           # ระบบลา
/api/v1/discipline      # การ discipline
/api/v1/organization    # โครงสร้างองค์กร
/api/v1/metadata        # ข้อมูลอ้างอิง
/api/v1/retirement      # การเกษียณอายุ
/api/v1/insignia        # เครื่องราชอิสริยาภรณ์
/api/v1/reports         # รายงาน

---

Getting Started

Prerequisites

• .NET SDK 6.0 / 7.0 / 8.0
• MySQL Server
• Keycloak (Authentication Server)
• RabbitMQ
• MinIO (Object Storage)
• Docker (สำหรับ deployment)

Configuration

แต่ละ service มีไฟล์ appsettings.json สำหรับ config ดังนี้:

• JWT Authentication - เชื่อมต่อกับ Keycloak
• Database Connection - MySQL connection string
• RabbitMQ - Message queue connection
• MinIO - File storage endpoint
• Elasticsearch - Logging endpoint
• Mail Server - สำหรับส่งอีเมล

Build & Run

# Restore dependencies
dotnet restore

# Build solution
dotnet build

# Run specific service
dotnet run --project Service/BMA.EHR.Command.Service

Docker

# Build Docker image
docker build -t bma-ehr-service .

# Run container
docker run -d -p 5000:80 bma-ehr-service

---

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Swagger    │     │   Client     │     │   WebSocket  │
│   UI         │     │   Apps       │     │   Clients    │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
                   ┌────────▼────────┐
                   │  API Gateway    │
                   │  (Keycloak JWT) │
                   └────────┬────────┘
                            │
       ┌────────────────────┼────────────────────┐
       │                    │                    │
┌──────▼──────┐   ┌────────▼──────┐   ┌────────▼──────┐
│  Placement  │   │    Leave      │   │  Discipline   │
│  Service    │   │    Service    │   │  Service      │
└──────┬──────┘   └────────┬──────┘   └────────┬──────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
              ┌─────────────▼──────────────┐
              │       MySQL Database       │
              │    (Entity Framework)      │
              └────────────────────────────┘

              ┌────────────────────────────┐
              │   RabbitMQ / MinIO /       │
              │   Elasticsearch / Hangfire │
              └────────────────────────────┘

---

Dependencies ที่สำคัญ

Package	หน้าที่
Entity Framework Core	ORM สำหรับ MySQL
Serilog	Structured Logging
Swashbuckle	API Documentation
Hangfire	Background Job Processing
EPPlus	สร้าง/อ่านไฟล์ Excel
iTextSharp	สร้างไฟล์ PDF
RabbitMQ.Client	Message Queue
NEST	Elasticsearch Client
ThaiBahtText	แปลงตัวเลขเป็นหน่วยบาทไทย
NodaTime	Date/Time Handling
Sentry	Error Tracking

---

Testing

# Run unit tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run load tests (k6)
k6 run tests/load/*.js

---