db-seed-data-plan

name	db-seed-data-plan
description	테스트·검증용 시드 데이터 설계 계획을 수립한다
argument-hint	스키마 정의 파일 경로 또는 테이블명
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

실행 모드

• 간단 모드(기본값): 절차 1(스키마 분석), 3(데이터 패턴 설계), 5(스크립트 사양)만 수행하고, 간결한 시드 데이터 계획을 반환한다.
• 상세 모드: 인자에 --detailed가 포함되면 6개 절차 전체를 수행하고, 검증 기준 및 환경별 설계를 포함한 종합 결과를 반환한다.

$ARGUMENTS에 --detailed가 포함되지 않은 경우 간단 모드로 실행한다.
간단 모드에서는 출력 포맷 중 해당 섹션만 출력한다.

목적

테스트, 개발, 스테이징 환경에서 사용할 시드 데이터 설계 계획을 수립한다.
외래키 제약 및 비즈니스 규칙을 만족하면서도, 엣지 케이스를 충분히 포함하는 현실적인 테스트 데이터 세트를 설계한다.
데이터 입력 순서와 의존 관계를 명확히 하고, 재현 가능한 시드 스크립트 사양을 정의한다.

입력

• 스키마 정의 파일 (테이블 구조 및 제약 정보)
• ORM 모델 정의 파일
• 비즈니스 로직 명세 (선택)
• 기존 시드 스크립트 (선택)
• 테스트 요구사항 및 시나리오 (선택)

절차

1. 스키마 구조 분석

1-1. 전체 테이블의 컬럼 정의, 제약 조건, 데이터 타입 파악
1-2. 테이블 간 외래키 의존 관계를 의존 그래프로 정리
1-3. NOT NULL / UNIQUE / CHECK 제약 목록화
1-4. ENUM 타입 또는 상태 컬럼의 허용 값 나열
1-5. 자동 생성 컬럼(AUTO_INCREMENT, SERIAL, UUID, 타임스탬프 등) 식별

2. 데이터 입력 순서 결정

2-1. 외래키 의존 관계 기반 위상 정렬 순서 결정
2-2. 순환 참조 발생 시 해결 전략 수립 (일시적 FK 비활성화 또는 NULL 후 업데이트)
2-3. 마스터 데이터(참조 테이블)와 트랜잭션 데이터 구분
2-4. 입력 단계를 정의 (Phase 1: 마스터 → Phase 2: 주요 엔티티 → Phase 3: 트랜잭션 → Phase 4: 연관 데이터)

3. 데이터 패턴 설계

3-1. 정상 케이스 데이터 세트 설계 (기본 CRUD 검증용)
3-2. 경계값 데이터 설계 (최소값, 최대값, 빈 문자열, 최대 길이 문자열 등)
3-3. 엣지 케이스 설계:

• NULL 허용 컬럼의 NULL 케이스
• 논리 삭제된 레코드
• 상태 전이 전체 패턴
• 날짜 경계 (연말/연초, 윤년, 타임존 경계) 3-4. 관계 검증 데이터 설계:
• 1:1 / 1:N / N:M 패턴
• 자식 레코드 없는 부모 레코드
• 고아 레코드 케이스 3-5. 성능 테스트용 데이터 규모 정의
  3-6. 국제화 테스트 데이터 설계 (다국어, 멀티바이트, 이모지 등)

4. 데이터 값 설계 방침

4-1. 실제 개인정보와 유사하지 않은 안전한 더미 데이터 방침 수립
4-2. UNIQUE 제약을 만족하기 위한 네이밍 규칙 정의 (test_user_001 등)
4-3. 날짜 데이터 기준일과 오프셋 전략 결정
4-4. 금액·수량 데이터의 현실적 범위 설정
4-5. Factory 패턴 활용 방침 정의
4-6. 랜덤 데이터와 고정 데이터의 사용 구분 정의

5. 시드 스크립트 사양 수립

5-1. 멱등성(여러 번 실행해도 동일 결과) 보장 설계
5-2. 환경별 데이터 세트 분리 설계 (dev / test / staging)
5-3. 데이터 초기화 절차 정의 (TRUNCATE 후 재입력 등)
5-4. 시드 데이터 버전 관리 방침 수립
5-5. 대량 데이터 입력 시 배치 처리 전략 설계
5-6. 실행 로그 및 검증 절차 정의

6. 검증 기준 수립

6-1. 시드 입력 후 정합성 체크 쿼리 설계
6-2. 외래키 제약 위반 탐지 쿼리 준비
6-3. 필수 데이터 존재 여부 확인 쿼리 준비
6-4. 기대 레코드 수 정의

출력 포맷

# 시드 데이터 설계 계획: [대상 스키마 / 프로젝트명]

## 설계 요약
| 항목 | 내용 |
|------|------|
| 대상 테이블 수 | N 개 |
| 총 레코드 수 (개발 환경) | 약 N 건 |
| 총 레코드 수 (성능 테스트) | 약 N 건 |
| 입력 단계 수 | N 단계 |
| 멱등성 | 보장 / 미보장 |

## 테이블 의존 관계 그래프

Phase 1 (마스터 데이터): categories (의존 없음) roles (의존 없음)

Phase 2 (주요 엔티티): users → roles products → categories

Phase 3 (트랜잭션 데이터): orders → users order_items → orders, products

Phase 4 (연관 데이터): reviews → users, products

## 테이블별 데이터 설계

### `users` 테이블
| # | 목적 | name | email | role_id | status | deleted_at |
|---|------|------|-------|---------|--------|------------|
| 1 | 정상: 관리자 | 테스트관리자 | [e-mail] | 1 | active | NULL |
| 2 | 정상: 일반 | 테스트사용자 | [e-mail] | 2 | active | NULL |
| 3 | 엣지: 정지 | 정지사용자 | [e-mail] | 2 | suspended | NULL |
| 4 | 엣지: 논리삭제 | 삭제사용자 | [e-mail] | 2 | active | 2024-01-01 |
| 5 | 경계값: 최대길이 | 가...(255자) | [e-mail] | 2 | active | NULL |
| 6 | 국제화: 이모지 | 😊사용자 | [e-mail] | 2 | active | NULL |

### `orders` 테이블
| # | 목적 | user_id | total | status | created_at |
|---|------|---------|-------|--------|------------|
| 1 | 정상 | 2 | 1500 | completed | 기준일 |
| 2 | 엣지: 0원 | 2 | 0 | completed | 기준일-1일 |
| 3 | 엣지: 미완료 | 2 | 3000 | pending | 기준일 |
| 4 | 엣지: 취소 | 3 | 500 | cancelled | 기준일-7일 |

## 데이터 패턴 커버리지 표
| 패턴 | 대상 테이블 | 레코드 | 목적 |
|------|--------------|--------|------|
| NULL 값 | users | #6 | NULL 허용 동작 확인 |
| 논리 삭제 | users | #4 | 삭제 필터 검증 |
| 상태 전이 | orders | #1-#4 | 전체 상태 패턴 검증 |
| 경계값 | users | #5 | VARCHAR 최대 길이 확인 |
| 고아 데이터 | - | - | FK 제약으로 방지 |

## 데이터 값 설계 방침
| 항목 | 방침 |
|------|------|
| 이메일 | `*@test.local` 도메인 사용 |
| 전화번호 | 테스트 전용 번호 형식 사용 |
| 주소 | 명확한 더미 주소 사용 |
| 날짜 | 기준일 `2024-06-01` 기준 상대값 |
| 금액 | 100~100000 범위 |

## 입력 스크립트 사양

### 멱등성 구현 방식
```sql
-- UPSERT 패턴(PostgreSQL)
INSERT INTO users (id, name, email) VALUES (1, '테스트관리자', '[e-mail]')
ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, email = EXCLUDED.email;

-- REPLACE 패턴(MySQL)
REPLACE INTO users (id, name, email) VALUES (1, '테스트관리자', '[e-mail]');

환경별 데이터 세트

환경	데이터 규모	특징
dev	최소 (5~10건/테이블)	기본 동작 검증
test	중간 (10~20건/테이블)	엣지 케이스 포함
staging	대규모 (1000건 이상)	성능 검증 포함

입력 후 검증 쿼리

-- 테이블별 건수 확인
SELECT 'users' AS table_name, COUNT(*) FROM users
UNION ALL
SELECT 'orders', COUNT(*) FROM orders;

-- FK 무결성 확인
SELECT o.id
FROM orders o
LEFT JOIN users u ON o.user_id = u.id
WHERE u.id IS NULL;

-- 필수 마스터 데이터 존재 확인
SELECT * FROM roles
WHERE id NOT IN (SELECT DISTINCT role_id FROM users);

## 안전 수칙

- **실제 SQL을 실행하지 말 것** — 본 작업은 설계 계획 수립만 수행  
- **운영 데이터베이스에 접속하지 말 것**  
- **실존 개인정보를 사용하지 말 것** — 모든 데이터는 명확한 더미 데이터여야 함  
- **실존 이메일·도메인 사용 금지** — `@test.local` 등 사용  
- **실존 전화번호 사용 금지** — 테스트 전용 형식 사용  
- **운영 데이터 복제 금지** — 개인정보 유출 위험  
- **비밀번호 하드코딩 금지** — 해시값 사용  
- **신용카드 등 민감정보 포함 금지**

---

## 종료 조건

- 전체 테이블 의존 관계가 정리되었을 것  
- 입력 순서가 위상 정렬로 정의되었을 것  
- 정상·경계·엣지 케이스 데이터가 설계되었을 것  
- 데이터 값 설계 방침이 명확히 정의되었을 것  
- 멱등성을 보장하는 스크립트 사양이 수립되었을 것  
- 환경별 데이터 세트가 분리 설계되었을 것  
- 입력 후 검증 쿼리가 준비되었을 것  
- 개인정보와 유사하지 않은 더미 데이터 정책이 확인되었을 것