eapim-admin/CLAUDE.md

# CLAUDE.md

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

## Project Overview

eLink EMS (eLink Management System) is an enterprise API management platform consisting of three main applications:
- **eapim-admin**: Management console for configuration, monitoring, and statistics
- **eapim-online**: API gateway for real-time transaction processing
- **eapim-portal**: Developer portal for API consumers (Spring Boot-based)

This directory (`eapim-admin`) contains the management console, built with Spring 5.3 and a hybrid ORM approach (JPA + iBATIS).

## Build & Development Commands

### Building the Application

```bash
# Standard WAR build for Tomcat
gradle war

# Build without tests
gradle build -x test

# WebLogic deployment (uses weblogic-web.xml)
gradle build -x test -Pprofile=weblogic

# Clean and rebuild
gradle clean build
```

### Running Tests

```bash
# Run all tests
gradle test

# Run specific test class
gradle test --tests "com.example.ClassName"
```

### Development Tasks

```bash
# Assemble classes without packaging
gradle classes

# Generate QueryDSL Q-classes and other annotations
gradle compileJava

# View dependency tree
gradle dependencies

# List all available tasks
gradle tasks --all
```

## Architecture & Module Dependencies

### Multi-Module Structure

eapim-admin references modules from the sibling `eapim-online` directory via settings.gradle:

```
eapim-admin (root project)
├── elink-online-core            # Core interfaces and domain models
├── elink-online-core-jpa        # JPA entities and repositories
├── elink-online-transformer     # Message transformation logic
├── elink-online-common          # Shared utilities
├── elink-online-emsclient       # EMS client communication
├── elink-portal-common          # Portal shared components (JPA entities)
└── kjb-safedb                   # Custom encryption library
```

All module projects are located in `../eapim-online/` and `../` relative to this directory.

### Hybrid ORM Approach

This application uses **both JPA and iBATIS**:
- **JPA/Hibernate**: Modern data access via `elink-portal-common` (Spring Data repositories)
- **iBATIS**: Legacy SQL mapping for existing code (will be migrated over time)

When working with data access:
- New features should use JPA with Spring Data repositories
- Legacy iBATIS mappers are in `src/main/resources/sql/` and configured via Spring XML

### Code Generation

The build process generates:
- **QueryDSL Q-classes**: Type-safe query classes
- **Lombok**: Getters/setters/builders via annotation processing
- **MapStruct**: Object mappers between DTOs and entities

#### Dual Q-Class Generation (Gradle + Eclipse)

This project uses **both Gradle and Eclipse annotation processors**, which means Q-classes are generated in **two locations**:

1. **`build/generated/java/`** - Generated by Gradle when running `gradle compileJava` or `gradle build`
2. **`WebContent/generated/`** - Generated by Eclipse APT when building in Eclipse IDE

**This is expected behavior and intentional.** Both directories are in `.gitignore` and should NOT be committed.

#### Working with Generated Code

- **Gradle builds**: Q-classes in `build/generated/java/` are automatically on the classpath
- **Eclipse IDE**: Q-classes in `WebContent/generated/` are automatically on the classpath
- **After pulling updates**: Run `gradle compileJava` or refresh Eclipse project to regenerate Q-classes
- **IDE errors on Q-classes**: Regenerate by running `gradle clean compileJava` or Eclipse → Project → Clean

The duplication causes no issues since:
- Both tools generate identical Q-classes from the same JPA entities
- Both output directories are gitignored
- Each tool uses its own generated classes (no classpath conflicts)

## Local Development Setup

### Required Environment Variables (Tomcat)

```
-Deai.datasource.type=DEV
-Dinst.Name=apimsSvr11
-Deai.tableowner=ems
-Deai.systemmode=D
-Dfile.encoding=utf-8
-DLOGBACK_LOG_LEVEL=info
```

### Database Configuration

The application supports:
- **Oracle**: Production database
- **PostgreSQL**: Alternative production DB
- **H2**: In-memory database for tests

Database connection is configured via `eai.datasource.type` system property (DEV/STG/PROD).

### SafeDB Encryption Library

The `kjb-safedb` module provides three operational modes:
- **REAL**: Uses actual SafeDB native library
- **FAKE**: Development mode using SHA-256/AES-256 (no SafeDB installation required)
- **NONE**: Bypass encryption (for testing only)

In development, use FAKE mode if SafeDB is not installed locally.

## Key Features & Functionality

The admin console manages all aspects of the eLink platform:

| Feature | Description |
|---------|-------------|
| User Management | User accounts and authorization |
| Transaction Logs | View online/batch/bulk transaction history |
| Statistics & Dashboard | Real-time monitoring and metrics |
| Interface Management | API interface configuration |
| Layout Management | Message layout definitions |
| Transformation Rules | Message transformation logic |
| Adapter Configuration | Protocol adapters (HTTP, TCP, etc.) |
| Routing Rules | Request routing and load balancing |
| Batch Processing | Batch interface and adapter management |
| Scheduler | Quartz-based job scheduling |

## Deployment Targets

The application can be deployed to:
- **Tomcat** (default, development)
- **WebLogic 14.1.2** (production, requires `-Pprofile=weblogic`)
- **JEUS** (supported)
- **JBoss/WildFly** (supported with descriptors)

### WebLogic-Specific Build

When building for WebLogic, use the `weblogic` profile which replaces `web.xml` with `weblogic-web.xml` to address DefaultServlet issues:

```bash
gradle build -x test -Pprofile=weblogic
```

## Technology Stack

- **Java 8**: Enforced via Gradle toolchain
- **Spring Framework 5.3.27**: Core framework
- **Spring Data JPA 2.5.2**: Repository abstraction
- **Hibernate 5.4.33**: ORM implementation
- **QueryDSL 5.0.0**: Type-safe queries
- **iBATIS 2.3.4**: Legacy SQL mapping
- **Quartz 2.2.1**: Job scheduling
- **Apache POI 3.17**: Excel export functionality
- **Jackson 2.13.1**: JSON processing
- **Logback 1.2.10**: Logging framework/ㅊ
- **AWS SDK 2.20.142**: S3 integration
- **Kubernetes Client 18.0.1**: K8s management

## Project Conventions

### Package Structure

```
com.eactive.ems/
├── controller/         # Spring MVC controllers
├── service/           # Business logic
├── dao/               # iBATIS DAOs (legacy)
├── repository/        # JPA repositories (via elink-portal-common)
├── model/             # DTOs and view models
└── config/            # Spring configuration classes
```

### Spring Configuration

The application uses:
- **XML-based configuration**: Legacy Spring XML in `WebContent/WEB-INF/`
- **Java-based configuration**: Modern `@Configuration` classes
- **Component scanning**: Enabled for annotated components

### Logging

- Uses **SLF4J** with **Logback** implementation
- Log level controlled via `LOGBACK_LOG_LEVEL` system property
- All `log4j` dependencies are excluded (configurations in build.gradle)

## IDE Setup

### Eclipse

```bash
gradle eclipse
```

This generates:
- `.project` and `.classpath` files
- Eclipse WTP configuration (context path: `/monitoring`)
- UTF-8 encoding settings
- Annotation processor configuration for QueryDSL/Lombok

### IntelliJ IDEA

```bash
gradle idea
```

Alternatively, use "Import Gradle Project" directly in IntelliJ.

## Testing

Tests use:
- **JUnit 5 (Jupiter)**: Test framework
- **Spring Boot Test 2.6.15**: Integration testing utilities
- **H2 Database**: In-memory database for tests
- **Mockito**: Mocking framework (via Spring Boot Test)

Test resources are in `src/test/resources` with H2-compatible configurations.