# Board Source Generator Plan

## 1. 목표

테이블은 이미 생성되어 있다고 가정하고, 테이블명 기준으로 Java, MyBatis XML, Vue 초기 소스를 자동 생성하는 `Node.js CLI` 프로그램을 만든다.

이 생성기의 목적은 완성본을 만드는 것이 아니다.

- 반복적인 CRUD 초기 뼈대를 빠르게 만든다.
- 공통 규칙이 적용된 시작 파일을 자동 생성한다.
- 사람이 이후 업무 로직과 화면 상세를 이어서 개발할 수 있게 시간 절약을 돕는다.

즉 결과물은 "바로 운영 투입하는 완성본"이 아니라, "초기 공통 사항이 반영된 출발점"이다.

## 2. 생성 대상

생성 대상은 아래 파일들이다.

- Java Entity
- Java Service Interface
- Java Service Impl
- Java Dao
- Java Controller
- MyBatis Mapper XML
- Vue CRUD Page

1차 범위는 단일 테이블 CRUD 기준으로 제한한다.

## 3. 기준 템플릿 원칙

생성기의 기준은 현재 프로젝트 안에서 실제로 동작하는 샘플 소스이다.

- `src/main/java/com/samsung/sample/board/entity/SampleBoard.java`
- `src/main/java/com/samsung/sample/board/SampleBoardService.java`
- `src/main/java/com/samsung/sample/board/impl/SampleBoardServiceImpl.java`
- `src/main/java/com/samsung/sample/board/dao/SampleBoardDao.java`
- `src/main/java/com/samsung/sample/board/controller/SampleBoardController.java`
- `src/main/resources/sql/mybatis/postgresql/mapper-mybatis-sample-board.xml`
- `frontend/src/components/view/admin/pgBoard/SampleBoardPage.vue`

여기서 중요한 원칙은 아래와 같다.

- 샘플 템플릿은 단순 참고용 문서가 아니라 실제 실행 가능한 상태로 유지한다.
- 샘플 템플릿이 변경되면 이후 새로 generate 하는 소스에도 그 변경이 반영되어야 한다.
- 즉 생성기는 고정 문자열 하드코딩보다 "실행 가능한 샘플 템플릿 + 치환 규칙" 구조로 가는 것이 좋다.

## 4. 핵심 결정 사항

이번 계획에서는 아래 사항을 고정으로 본다.

- 생성기는 `Node.js CLI` 로 구현한다.
- DB 메타데이터를 읽어서 컬럼을 반영한다.
- 컬럼이 추가된 경우 다시 generate 해서 새 구조를 반영할 수 있어야 한다.
- 이미 사용자가 수정해서 업무 로직이 들어간 소스는 생성기가 병합 관리하지 않는다.
- 변경 반영이 필요하면 새로 생성한다.
- 생성 결과는 공통적인 초기 코드 자동화가 목적이며, 완성형 산출물이 아니다.

## 5. 생성기 방식

가장 적합한 방식은 `DB 메타데이터 조회 + 템플릿 렌더링 + 파일 생성` 구조이다.

이 방식의 장점은 아래와 같다.

- 실제 테이블 컬럼을 기준으로 생성하므로 신뢰도가 높다.
- 컬럼 추가 시 다시 generate 해서 반영할 수 있다.
- Java, XML, Vue를 같은 규칙으로 묶어 생성할 수 있다.
- 샘플 템플릿 변경 사항을 이후 생성물에 계속 반영할 수 있다.

반대로 아래 방식은 지양한다.

- 테이블명만 보고 컬럼을 추측하는 방식
- 생성 후 기존 파일 내용을 분석해서 자동 병합하는 방식
- LLM 출력 결과만을 신뢰하는 방식

특히 기존에 수정된 파일을 병합 관리하는 기능은 초기에 넣지 않는 것이 맞다.

이 기능은 복잡도가 높고 충돌 위험이 커서, 1차 생성기의 목적과 맞지 않는다.

## 6. 재생성 정책

재생성 정책은 이번 문서에서 매우 중요하다.

### 6.1 컬럼 추가 시 정책

- DB 컬럼이 추가되면 생성기를 다시 실행한다.
- 생성기는 현재 DB 메타데이터를 읽어 새 파일을 만든다.
- 새로 생성된 초기 소스를 기준으로 개발자가 필요한 변경을 다시 옮긴다.

즉 "기존 파일에 컬럼만 안전하게 끼워 넣는 병합 기능"은 1차에 넣지 않는다.

### 6.2 기존 수정 파일 정책

- 이미 사용 중이며 수정된 소스는 생성기가 추적하지 않는다.
- 생성기는 기존 수정 파일의 의미를 이해하거나 병합하지 않는다.
- 변경 반영이 필요하면 새 파일을 새로 생성한다.

이 정책을 명확히 해야 생성기의 역할이 단순해지고 안정적이다.

### 6.3 생성 결과 관리 정책

아래 두 방식 중 하나를 권장한다.

1. 별도 생성 경로에 새로 만든 뒤 비교 후 적용
2. 모듈명을 바꿔 신규 버전처럼 생성

예시:

- `sample/board_v2`
- `sample/board_v2`

즉 생성기는 "업데이트 도구"가 아니라 "초기 코드 새로 만들기 도구"로 정의한다.

## 7. Node.js CLI 로 하는 이유

`Node.js CLI` 로 고정하는 이유는 아래와 같다.

- Vue 파일 생성과 템플릿 처리에 가장 유리하다.
- Java, XML, Vue를 문자열 템플릿으로 다루기 쉽다.
- 빠르게 프로토타입을 만들기 좋다.
- CLI 사용 경험을 만들기 쉽다.
- 추후 npm script 또는 사내 툴 형태로 묶기 쉽다.

따라서 이번 생성기는 Java 기반이 아니라 `Node.js CLI` 로 결정한다.

## 8. 입력 값 설계

최소 입력은 테이블명이지만, 실제 사용을 위해 아래 입력을 권장한다.

- `--table`: DB 테이블명
- `--module`: 모듈 경로
- `--entity`: Entity 클래스명
- `--menu-name`: 화면 표시명
- `--output`: 출력 루트 또는 생성 그룹

예시:

```text
generate-board --table samples --module sample/board --entity SampleBoard --menu-name "Sample Board"
```

테이블명만 넣는 모드도 제공할 수 있다.

```text
generate-board --table sample_board
```

다만 테이블명만으로 클래스명과 모듈명을 완벽히 정할 수는 없으므로, 기본 추천값을 보여주고 확정 후 생성하는 흐름이 더 좋다.

## 9. DB 메타데이터 수집 범위

생성기는 최소한 아래 메타데이터를 읽어야 한다.

- 컬럼명
- DB 타입
- nullable 여부
- 기본키 여부
- 자동 증가 여부
- 컬럼 순서

PostgreSQL에서는 `information_schema.columns` 와 `pg_catalog` 정보를 사용하면 충분하다.

1차 지원 범위는 아래처럼 단순하게 가져간다.

- 단일 테이블
- 단일 PK
- PostgreSQL
- 일반 CRUD

## 10. 컬럼 매핑 규칙

DB 컬럼을 Java, XML, Vue에 일관되게 매핑해야 한다.

예시:

- `id` -> `Integer id`
- `title` -> `String title`
- `content` -> `String content`
- `author` -> `String author`
- `created_at` -> `Date createdAt`
- `updated_at` -> `Date updatedAt`

기본 규칙:

- snake_case -> camelCase
- PostgreSQL `varchar`, `text` -> `String`
- `int4` -> `Integer`
- `int8` -> `Long`
- `numeric` -> `BigDecimal`
- `timestamp` -> `Date`

현재 프로젝트 샘플과 맞추기 위해 1차는 `Date` 기준이 가장 안전하다.

## 11. 생성 대상 파일별 역할

### 11.1 Entity

- 컬럼 필드 선언
- `@Data` 사용
- 현재 프로젝트 import/스타일 유지

### 11.2 Service Interface

- CRUD 메서드 선언

기본 메서드:

- `getXxxList()`
- `getXxx(Integer id)`
- `createXxx(Xxx entity)`
- `updateXxx(Xxx entity)`
- `deleteXxx(Integer id)`

### 11.3 Service Impl

- DAO 위임
- 등록 후 재조회
- 수정 후 재조회

### 11.4 Dao

- MyBatis `SqlSession` 호출

### 11.5 Controller

- 현재 프로젝트의 `FormulaController` 유사 스타일 사용
- `@RestController`
- `@RequestMapping("/.../")`
- `@Log4j2`
- `main.do?method=...` 패턴 사용

### 11.6 MyBatis XML

- resultMap 생성
- 목록/상세/등록/수정/삭제 SQL 생성

### 11.7 Vue Page

- 목록/상세/등록/수정/삭제 초기 화면 생성
- axios 기반 API 연결
- 생성 시점의 컬럼 기준 입력 폼과 목록 컬럼 생성

## 12. 템플릿 전략

이번 생성기의 핵심은 템플릿을 실제 실행 가능한 샘플 코드로 유지하는 것이다.

즉 아래 원칙으로 간다.

- 샘플 파일은 실제 프로젝트 안에서 동작 가능해야 한다.
- 생성기는 그 샘플 구조를 공통 템플릿으로 활용한다.
- 샘플이 변경되면 이후 generate 결과도 같이 바뀌어야 한다.

구현 방식은 아래 구조가 좋다.

- 템플릿 원본 파일 보관
- 치환 포인트 정의
- 반복 구간은 템플릿 엔진으로 처리

템플릿 엔진은 아래 중 하나를 권장한다.

- Mustache
- Handlebars

이유는 아래와 같다.

- 필드 반복 생성이 쉽다.
- XML resultMap 반복 생성이 쉽다.
- Vue form/table 반복 생성이 쉽다.

## 13. 샘플 템플릿 운영 정책

샘플 템플릿은 향후 생성 품질을 좌우하므로 별도 규칙이 필요하다.

운영 원칙:

- 샘플 템플릿은 실제 실행 가능해야 한다.
- 샘플 템플릿은 프로젝트 표준 예제로 관리한다.
- 샘플 템플릿 수정은 곧 생성기 출력 규칙 변경과 연결된다.
- 생성기는 샘플 템플릿을 기준으로 치환/반복 렌더링한다.

즉 샘플 템플릿은 "문서 예제"가 아니라 "살아있는 기준 코드"이다.

## 14. 파일 생성 위치 정책

예시 모듈이 `sample/board` 라면 아래 경로를 생성한다.

- `src/main/java/com/samsung/sample/board/entity/SampleBoard.java`
- `src/main/java/com/samsung/sample/board/SampleBoardService.java`
- `src/main/java/com/samsung/sample/board/dao/SampleBoardDao.java`
- `src/main/java/com/samsung/sample/board/impl/SampleBoardServiceImpl.java`
- `src/main/java/com/samsung/sample/board/controller/SampleBoardController.java`
- `src/main/resources/sql/mybatis/postgresql/mapper-mybatis-sample-board.xml`
- `frontend/src/components/view/admin/pgBoard/SampleBoardPage.vue`

다만 현재 기본 동작은 실제 소스 위치에 직접 생성하는 것으로 한다.

- 기본 출력은 실제 소스 경로에 직접 생성한다.
- 기존 파일이 있으면 `--force` 없이는 덮어쓰지 않는다.
- 필요 시 `--output` 으로 별도 경로에 우회 생성할 수 있다.

## 15. 프로그램 구조 제안

추천 구조:

```text
tools/board-generator/
  src/
    cli/
    metadata/
    naming/
    generators/
    writers/
    validators/
    template-engine/
  templates/
    java/
    xml/
    vue/
  config/
    board-generator.yml
```

모듈 역할:

- `cli`: 명령행 입력 처리
- `metadata`: DB 메타데이터 조회
- `naming`: 이름 변환 규칙 처리
- `generators`: 파일별 렌더링
- `writers`: 파일 생성
- `validators`: 입력값 및 스키마 검증
- `template-engine`: 템플릿 치환 및 반복 처리

## 16. 생성 순서

권장 순서는 아래와 같다.

1. 입력 파라미터 수집
2. DB 메타데이터 조회
3. PK 및 컬럼 구조 검증
4. 이름 규칙 계산
5. 템플릿 렌더링
6. 신규 출력 경로 결정
7. 파일 생성
8. 생성 결과 요약 출력

## 17. 안전장치

반드시 넣을 기능:

- 기존 파일 자동 병합 금지
- 기본은 신규 생성
- 덮어쓰기 옵션은 제한적으로만 허용
- 생성 전 preview 출력
- 지원하지 않는 구조는 중단

예시:

- 복합 PK면 생성 중단
- PK가 없으면 생성 중단
- 테이블이 없으면 생성 중단

## 18. 검증 전략

생성기 자체의 검증은 아래 기준으로 진행한다.

### 백엔드 검증

- 생성된 Java 소스 컴파일 가능 여부 확인
- import 누락 여부 확인
- MyBatis XML 파싱 가능 여부 확인

### 프론트 검증

- Vue 문법 오류 확인
- axios URL 패턴 확인

### 템플릿 검증

- `samples` 테이블 기준으로 generate 했을 때 샘플 구조와 유사한 결과가 나오는지 확인
- 샘플 템플릿 변경 후 재생성 시 변경 내용이 반영되는지 확인

## 19. 구현 단계

### Step 1. 실행 가능한 샘플 템플릿 정리

- 현재 샘플 보드 소스를 템플릿 기준으로 분리
- 실행 가능한 상태 유지
- 치환 영역과 반복 영역 정의

### Step 2. PostgreSQL 메타데이터 조회기 작성

- 컬럼 목록 조회
- PK 조회
- 타입 매핑 정보 생성

### Step 3. Node.js 템플릿 렌더러 작성

- Java 템플릿 렌더링
- XML 템플릿 렌더링
- Vue 템플릿 렌더링

### Step 4. CLI 작성

- `generate-board --table ...` 형태 구현
- 기본값 추천
- preview 출력

### Step 5. 재생성 흐름 검증

- 컬럼 추가 후 다시 generate
- 새 생성본에 새 컬럼이 반영되는지 확인
- 기존 수정 파일을 건드리지 않는지 확인

## 20. MVP 범위

MVP는 아래 수준이면 충분하다.

입력:

- `table`
- `module`
- `entity`

출력:

- Entity
- Dao
- Service
- ServiceImpl
- Controller
- MyBatis XML
- Vue Page

단, 생성 결과는 공통 초기 코드 수준으로 제한한다.

포함되는 것:

- 기본 CRUD
- 기본 입력 폼
- 기본 목록 컬럼
- 기본 API 연결

포함하지 않는 것:

- 복잡한 비즈니스 로직
- 고급 화면 동작
- 권한별 세부 분기
- 기존 수정본 자동 병합

## 21. 최종 정리

현재 가장 적합한 방향은 아래와 같다.

1. 생성기는 `Node.js CLI` 로 구현한다.
2. PostgreSQL 메타데이터를 읽어 컬럼 기반으로 생성한다.
3. 실행 가능한 샘플 템플릿을 기준으로 Java/XML/Vue를 생성한다.
4. 컬럼이 추가되면 다시 generate 해서 새 구조를 반영한다.
5. 이미 수정된 기존 소스는 생성기가 관리하지 않는다.
6. 필요하면 새 경로 또는 새 모듈로 다시 생성한다.
7. 생성 결과는 완성본이 아니라 초기 공통 코드 자동화 산출물로 본다.

즉 이 생성기의 본질은 "운영 코드 수정기"가 아니라 "공통 초기 코드 부스터"이다.

## 22. 다음 작업 제안

다음 단계로는 아래 순서를 권장한다.

1. `board_spec.md` 작성
2. PostgreSQL 메타데이터 조회 SQL 작성
3. Node.js CLI 디렉터리 구조 생성
4. 템플릿 파일 분리
5. `samples` 기준 MVP 구현