hrms-api-org/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is **bma-ehr-organization** - an HRMS (Human Resource Management System) API backend for a Thai healthcare organization. It manages personnel data, organizational structure, positions, and employee profiles for an Electronic Health Record (EHR) system.

- **Type**: RESTful API backend with WebSocket support
- **Language**: TypeScript/Node.js
- **Database**: MySQL with TypeORM
- **API Framework**: TSOA (TypeScript OpenAPI) with auto-generated routes and Swagger docs

## Common Commands

### Development
```bash
npm run dev          # Start development server with hot-reload (nodemon)
npm run build        # Build for production (runs tsoa spec-and-routes && tsc)
npm start            # Run production build (node ./dist/app.js)
npm run format       # Format code with Prettier
npm run check        # Type check without emitting (tsc --noEmit)
```

### Database Migrations

**CRITICAL**: After generating any migration, you MUST run the cleanup script to remove FK/idx lines:

```bash
# Generate new migration (include descriptive name)
npm run migration:generate src/migration/update_table_0811202s

# CLEANUP: Remove FK_/idx_ lines from generated migration
node scripts/clean-migration-fk-idx.js

# Run migrations
npm run migration:run
```

The cleanup script replaces lines containing `FK_` or `idx_` with `// removed FK_/idx_ auto-cleanup`. This is required because TypeORM generates foreign key and index constraints that must be manually removed.

### Local GitHub Actions Testing
```bash
# Test release workflow locally using act
act workflow_dispatch -W .github/workflows/release.yaml \
  --input IMAGE_VER=latest \
  -s DOCKER_USER=admin \
  -s DOCKER_PASS=FPTadmin2357 \
  -s SSH_PASSWORD=FPTadmin2357
```

## Architecture

### Application Entry Point
`src/app.ts` - Initializes the application:
1. Database connection (TypeORM MySQL)
2. In-memory caches (LogMemoryStore, OrgStructureCache with 30min TTL)
3. WebSocket server for real-time updates
4. Express middleware and TSOA routes
5. Cronjobs (scheduled tasks)
6. RabbitMQ message queue consumer

### Controllers (`src/controllers/`)
Handle HTTP requests. Main controllers include:
- `OrganizationController` - Organizational structure management
- `CommandController` - Workflow and command processing
- `ProfileSalaryController` - Salary and tenure management
- Controllers for positions, employees, auth, etc.

Cronjob logic is embedded in controllers (not separate services).

### Services (`src/services/`)
Business logic and external integrations:
- `OrganizationService.ts` - Core organizational logic
- `rabbitmq.ts` - RabbitMQ consumer for async processing
- `webSocket.ts` - Real-time updates to clients

### Entities (`src/entities/`)
TypeORM database models for MySQL. Key entities:
- Organization hierarchy (OrgRoot, OrgChild1-4)
- Position management (Position, PosType, PosLevel, PosExecutive)
- Employee profiles and related data
- Command/Workflow entities

### Middlewares (`src/middlewares/`)
- `auth.ts` - Keycloak Bearer token authentication
- `authWebService.ts` - API key authentication (`X-API-Key` header)
- `role.ts` - Role-based authorization
- `logs.ts` - Request logging
- `error.ts` - Global error handling
- `user.ts` - User context extraction

### TSOA Configuration
`src/routes.ts` is auto-generated by TSOA from controller decorators. Regenerated by `npm run build`.

- Swagger docs available at `/api-docs`
- Dual authentication: Keycloak bearer tokens and API keys
- API tags organized by domain (Organization, Position, Employee, etc.)

## Scheduled Cronjobs

All times in Bangkok timezone (UTC+7):

| Schedule | Task | Controller |
|----------|------|------------|
| `0 0 3 * * *` | Daily revision processing | `OrganizationController.cronjobRevision()` |
| `0 0 2 * * *` | Daily command processing | `CommandController.cronjobCommand()` |
| `0 0 1 10 *` | Monthly retirement status update (10th of month) | `CommandController.cronjobUpdateRetirementStatus()` |
| `0 0 0 * * *` | Daily tenure updates | `ProfileSalaryController` (multiple tenure methods) |

## External Dependencies

- **Keycloak** - Authentication and authorization
- **RabbitMQ** - Message queue for async operations
- **WebSocket** (Socket.IO) - Real-time updates
- **Elasticsearch** - Logging
- **Redis** - Caching layer
- **TypeORM** - Database ORM

## Code Style

- **Prettier**: 2 spaces, 100 char width, trailing commas
- **TypeScript**: Strict mode enabled
- **Comments**: Mixed Thai and English
- **Date handling**: Custom `DateSerializer` for local timezone serialization

## Important Notes

1. **Migration cleanup is mandatory** - TypeORM generates FK and index constraints that break the migration system. Always run `node scripts/clean-migration-fk-idx.js` after `migration:generate`.

2. **Organization caching** - `OrgStructureCache` provides in-memory caching of org structure (30 min TTL) for performance.

3. **Graceful shutdown** - Application handles SIGTERM/SIGINT to close database connections, caches, and HTTP server properly.

4. **Dual auth system** - Most endpoints use Keycloak bearer tokens, but some web service endpoints use `X-API-Key` header authentication.

5. **Thai localization** - The system is primarily for Thai users; documentation and some content is in Thai, but code is in English.