init claude overview project

CLAUDE.md

@@ -0,0 +1,137 @@
+# 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.