# Telosys JPA Starter (config-driven entity & repository generator)

DB 스키마 → JPA **엔티티 + 레포지토리** 자동 생성기.
- 컬럼명 기반 `@Convert`/enum 매핑은 **설정 파일 한 개(`converters.csv`)** 로 관리
- DB 컬럼 코멘트는 필드 Javadoc 으로 자동 삽입
- 모든 출력 경로는 `telosys-tools.cfg` 의 4개 변수로 통제

새 프로젝트에 이 폴더를 풀고 **3개 파일 + cfg 의 4개 경로 변수** 만 채우면 됩니다.

```
TelosysTools/
├── telosys-tools.cfg                         ← ① 4개 패키지 경로 수정
├── databases.yaml                            ← ② DB 접속정보 수정 (커밋 금지)
├── lib/                                       ← ③ JDBC 드라이버 jar 넣기
├── models/                                    (자동 생성됨)
└── templates/
    ├── jpa-entities/                           Base/Concrete 엔티티 생성 bundle
    │   ├── templates.cfg                       (출력 경로 규칙)
    │   ├── converters.csv                    ← ④ 컨버터 매핑 키 입력 (핵심)
    │   ├── include/                            (수정 불필요)
    │   └── main-java/
    │       ├── XxxBase_java.vm                 @MappedSuperclass 부모 생성
    │       └── XxxConcrete_java.vm             @Entity 자식 생성
    └── jpa-repositories/                       Base/Concrete 레포지토리 생성 bundle
        ├── templates.cfg
        ├── include/
        └── main-java/
            ├── XxxRepositoryBase_java.vm       @NoRepositoryBean 부모 인터페이스 생성
            └── XxxRepositoryConcrete_java.vm   @Repository 자식 인터페이스 생성
```

## 생성 구조 (Base / Concrete 상속)

### 엔티티 — `jpa-entities` bundle
각 테이블마다 2개 클래스 생성:
- `<Entity>Base.java` — `@MappedSuperclass`, **DB와 항상 1:1** (매번 재생성, 절대 수정 금지). 모든 컬럼·`@Convert` 매핑·DB 컬럼 코멘트(Javadoc)가 여기.
- `<Entity>.java` — `@Entity extends <Entity>Base`, **커스텀 영역** (없을 때만 1회 생성 → 재생성해도 보존). 비즈니스 로직·예외 매핑(`@Convert(attributeName=...)`, `@AttributeOverride`) 은 여기.

```
${ENTITY_BASE_PKG}/<Entity>Base.java         (재생성됨, 손대지 마세요)
${ENTITY_CONCRETE_PKG}/<Entity>.java         (커스텀, 보존됨)
```

### 레포지토리 — `jpa-repositories` bundle
각 테이블마다 2개 인터페이스 생성:
- `<Entity>JpaRepositoryBase.java` — `@NoRepositoryBean`, `JpaRepository<E,PK> + JpaSpecificationExecutor<E>` 상속 (매번 재생성, 수정 금지). 주요 컬럼 코멘트 Javadoc 포함.
- `<Entity>JpaRepository.java` — `@Repository extends <Entity>JpaRepositoryBase`, **커스텀 쿼리 영역** (없을 때만 1회 생성 → 재생성해도 보존). 모든 커스텀 메소드 / `@Query` 는 여기.

```
${REPO_BASE_PKG}/<Entity>JpaRepositoryBase.java   (재생성됨, 손대지 마세요)
${REPO_CONCRETE_PKG}/<Entity>JpaRepository.java   (커스텀 쿼리, 보존됨)
```

## 0. Telosys CLI 설치 (PC당 1회)
```bash
mkdir -p ~/tools/telosys && cd ~/tools/telosys
curl -sL -o t.zip https://github.com/telosys-tools-bricks/telosys-cli/releases/download/4.3.0-001/telosys-cli-4.3.0-001.zip
unzip -o t.zip && chmod +x tt
# 실행 별칭: alias tt='~/tools/telosys/tt'
```

## 1. 새 프로젝트에 풀기
이 zip 을 프로젝트 루트에서 풀면 `TelosysTools/` 가 생깁니다.

## 2. 파일 채우기
- `telosys-tools.cfg` : **4개 경로 변수** 수정
    - `ProjectVariable.ENTITY_BASE_PKG`       (예: `com.daewoong.platform.file.infrastructure.entity`)
    - `ProjectVariable.ENTITY_CONCRETE_PKG`   (예: `com.daewoong.platform.file.infrastructure.entity.concrete`)
    - `ProjectVariable.REPO_BASE_PKG`         (예: `com.daewoong.platform.file.infrastructure.persistence`)
    - `ProjectVariable.REPO_CONCRETE_PKG`     (예: `com.daewoong.platform.file.infrastructure.persistence.concrete`)
- `databases.yaml`    : `HOST/DBNAME/USER/PASSWORD` 수정
- `lib/`              : DB용 JDBC 드라이버 jar 넣기
- `templates/jpa-entities/converters.csv` : `컬럼명 ; enumFQN ; 컨버터FQN` 입력

## 3. 생성
```bash
cd <project-root>
~/tools/telosys/tt
telosys> h .                       # home = 프로젝트 루트
telosys> cdb db                    # DB 연결 확인
telosys> nm mymodel db             # DB에서 모델 추출 (한 번만 — .entity 는 손으로 관리)
telosys> m mymodel
telosys> b jpa-entities            # 엔티티 bundle 선택
telosys> gen * *                   # → y  (전 엔티티 Base/Concrete 생성)
telosys> b jpa-repositories        # 레포지토리 bundle 선택
telosys> gen * *                   # → y  (전 레포지토리 Base/Concrete 생성)
```

## 동작 원리
- **컬럼 매핑** : `converters.csv` 의 컬럼명과 일치하는 Base 필드는 `@Convert(converter=...) private <enum> ...` 로 생성. 매핑 없는 컬럼은 표준 타입.
- **컬럼 코멘트** : DB 의 column comment 가 있으면 자동으로 `/** comment */` Javadoc 으로 Base 필드에 삽입. 레포지토리 Base 의 클래스 Javadoc 에도 컬럼별 요약이 들어감.
- **개별 예외** : 특정 테이블만 다르게 → 그 `.entity` 컬럼에 `#javaType(...) #converter(...)` 태그로 override.
- **새 컨버터 추가** = `converters.csv` 한 줄. 템플릿·엔티티 무수정.
- **PK 타입** : Base 의 키 attribute 에서 자동 추출 (`@Id` 컬럼의 Java 타입). 단일 키 가정.
- **DB 스키마 변경 시** 재생성 → Base 만 갱신 (새 컬럼·코멘트 반영), Concrete 의 커스텀은 보존.

## 주의
- `.entity` 모델 파일은 한 번 추출 후 **손으로 관리하는 소스** 입니다 (DB 재추출이 덮어쓰지 않음). git 에 커밋해 관리하세요.
- `databases.yaml` 은 비밀번호 때문에 `.gitignore` 에 추가 권장.
- `ENTITY_CONCRETE_PKG` / `REPO_CONCRETE_PKG` 는 `ENTITY_BASE_PKG` / `REPO_BASE_PKG` 의 서브패키지가 아니어도 됩니다 — 프로젝트 구조에 맞게 자유롭게 지정 가능.
- **이전 버전에서 마이그레이션** : 자식 엔티티 위치가 `template` → `concrete` 로 변경됐습니다. 기존 `*.template/` 폴더는 다음 재생성 시 orphan 되므로 직접 삭제 또는 이동 필요.