TelosysTools/README.md

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회)

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. 생성

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 되므로 직접 삭제 또는 이동 필요.