koreafood
12c40c6004
Add Node.js CLI tool with Handlebars templates for generating standard CRUD artifacts: Java entity, service, DAO, controller, MyBatis mapper XML, and Vue frontend pages. Also generate the full SampleTableBoard CRUD reference implementation, update README with backend execution instructions, and add project plan documentation.
472 lines
14 KiB
Markdown
472 lines
14 KiB
Markdown
# 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 구현
|