sonamu 0.7.53 → 0.8.0

package/src/skills/project/requirements.md

@@ -0,0 +1,160 @@
+# 프로젝트 요구사항 명세
+
+> 이 문서는 프로젝트 생성 시 AI에게 제공한 요구사항을 기록합니다.
+> AI는 개발 과정 내내 이 문서를 참고하여 일관된 구현을 유지합니다.
+
+## 프로젝트 개요
+
+<!-- 프로젝트명, 목적, 주요 기능 개요 -->
+
+## 핵심 기능
+
+<!--
+예시 (게시판):
+- 사용자 인증 및 권한 관리
+- 게시판 CRUD
+- 파일 업로드/다운로드
+- 통계 대시보드
+
+예시 (의료 실험자료 분석):
+- 피험자 정보 관리
+- 실험 데이터 수집 및 검증
+- 통계 분석 및 차트 생성
+- 프로토콜 버전 관리
+- IRB 승인 문서 관리
+
+예시 (커머스):
+- 상품 카탈로그 관리
+- 장바구니 및 주문 처리
+- 결제 연동 (PG사)
+- 재고 관리
+- 배송 추적
+
+예시 (AI Agent):
+- 대화 세션 관리
+- 프롬프트 템플릿 관리
+- 모델 선택 및 파라미터 설정
+- 대화 히스토리 저장
+- 사용량 추적 및 과금
+
+예시 (의사 소통 도구):
+- 다양한 메시지 타입 (텍스트, 이미지, 파일, 음성)
+- 채널/그룹 관리
+- 실시간 알림
+- 읽음 상태 관리
+- 검색 및 아카이브
+-->
+
+## 사용자 역할
+
+<!--
+예시 (게시판):
+- **관리자**: 전체 시스템 관리, 사용자 관리
+- **일반 사용자**: 게시글 작성, 댓글 작성
+- **게스트**: 조회만 가능
+
+예시 (의료 실험자료):
+- **연구책임자**: 프로토콜 승인, 전체 데이터 접근
+- **연구원**: 데이터 입력, 분석
+- **모니터**: 데이터 검증, 감사
+
+예시 (커머스):
+- **고객**: 상품 구매, 주문 조회
+- **판매자**: 상품 등록, 주문 관리
+- **관리자**: 전체 시스템 관리
+
+예시 (AI Agent):
+- **개발자**: 프롬프트 템플릿 관리
+- **사용자**: 대화 세션 생성 및 사용
+- **관리자**: 사용량 모니터링, 과금 관리
+
+예시 (의사 소통 도구):
+- **의사**: 환자 케이스 공유, 자문 요청
+- **전문의**: 자문 응답, 의견 제공
+- **관리자**: 채널 관리, 권한 설정
+-->
+
+## 주요 엔티티
+
+<!--
+예시 (게시판):
+- User: 사용자 정보
+- Post: 게시글
+- Comment: 댓글
+- File: 첨부파일
+
+예시 (의료 실험자료):
+- Subject: 피험자 정보
+- Protocol: 실험 프로토콜
+- DataPoint: 실험 데이터 포인트
+- Analysis: 분석 결과
+- Consent: 동의서
+
+예시 (커머스):
+- Product: 상품
+- Order: 주문
+- OrderItem: 주문 항목
+- Payment: 결제
+- Inventory: 재고
+
+예시 (AI Agent):
+- Session: 대화 세션
+- Message: 메시지
+- PromptTemplate: 프롬프트 템플릿
+- Model: AI 모델 설정
+- Usage: 사용량 기록
+
+예시 (의사 소통 도구):
+- Channel: 채널
+- Message: 메시지 (다형성: TextMessage, ImageMessage, FileMessage)
+- Member: 멤버
+- ReadStatus: 읽음 상태
+- Notification: 알림
+-->
+
+## 비즈니스 규칙
+
+<!--
+예시 (게시판):
+- 게시글은 작성자만 수정/삭제 가능
+- 관리자는 모든 게시글 수정/삭제 가능
+- 댓글은 24시간 이내에만 수정 가능
+- 첨부파일은 최대 10MB까지
+
+예시 (의료 실험자료):
+- 피험자 동의 없이는 데이터 수집 불가
+- 프로토콜 변경시 IRB 재승인 필요
+- 데이터 입력 후 24시간 내 검증 필수
+- 개인식별정보는 암호화 저장
+
+예시 (커머스):
+- 재고 부족시 주문 불가
+- 결제 완료 전 재고 예약 (10분)
+- 주문 취소는 배송 전까지만 가능
+- 환불은 구매일로부터 7일 이내
+
+예시 (AI Agent):
+- 무료 플랜: 일일 100회 제한
+- 프롬프트 최대 길이: 4000 토큰
+- 세션 타임아웃: 30분
+- 대화 히스토리: 최근 10회까지 컨텍스트 포함
+
+예시 (의사 소통 도구):
+- 메시지 수정은 10분 이내만 가능
+- 파일 첨부 최대 50MB
+- 채널 멤버만 메시지 조회 가능
+- 의료 정보 포함 메시지는 자동 암호화
+-->
+
+## 기술 스택
+
+<!--
+예시:
+- Backend: Sonamu + PostgreSQL
+- Frontend: React + TanStack Router
+- Auth: better-auth
+-->
+
+## 추가 요구사항
+
+<!-- 기타 특별한 요구사항이나 제약사항 -->

package/src/skills/sonamu/SKILL.md

@@ -85,6 +85,166 @@ pnpm test:watch
 
 ---
 
+## 프로젝트 문서 체계
+
+### CRITICAL: 작업 시작 전 필수 확인
+
+**프로젝트 작업을 시작하기 전에 반드시 `skills/project/` 하위의 모든 문서를 읽으세요.**
+
+```
+skills/project/
+├── requirements.md      # 요구사항 정의
+├── architecture.md      # 엔티티 설계 + 시스템 아키텍처
+└── business-logic.md    # 사용자 권한별 비즈니스 로직
+```
+
+### 문서 작성 시점
+
+#### 1. requirements.md
+**언제:** 사용자로부터 요구사항을 받았을 때
+**내용:**
+- 프로젝트 목표 및 배경
+- 기능 요구사항 (FR)
+- 비기능 요구사항 (NFR)
+- 제약사항 및 전제조건
+
+**예시:**
+```markdown
+# 요구사항 정의
+
+## 프로젝트 목표
+온라인 병원 예약 시스템
+
+## 기능 요구사항
+1. 환자가 의사를 검색하고 예약할 수 있어야 함
+2. 의사가 진료 일정을 관리할 수 있어야 함
+...
+
+## 사용자 유형
+- 관리자: 시스템 전체 관리
+- 의사: 진료 일정, 환자 기록 관리
+- 환자: 예약, 진료 내역 조회
+- 병원: 의사 관리, 통계 확인
+```
+
+#### 2. architecture.md
+**언제:** 엔티티를 설계하거나 시스템 아키텍처를 논의할 때
+**내용:**
+- Entity 구조 및 관계 설계
+- 데이터베이스 스키마
+- API 엔드포인트 설계
+- 시스템 컴포넌트 구조
+
+**예시:**
+```markdown
+# 시스템 아키텍처
+
+## 엔티티 설계
+
+### User (사용자)
+- id: number (PK)
+- username: string
+- email: string
+- role: enum (admin, doctor, patient, hospital)
+
+### Doctor (의사)
+- id: number (PK)
+- user_id: number (FK → User)
+- specialty: string
+- hospital_id: number (FK → Hospital)
+
+### Appointment (예약)
+- id: number (PK)
+- patient_id: number (FK → User)
+- doctor_id: number (FK → Doctor)
+- appointment_date: datetime
+- status: enum (pending, confirmed, cancelled)
+
+## 관계
+- User ← Doctor (BelongsToOne)
+- User ← Appointment.patient (BelongsToOne)
+- Doctor ← Appointment.doctor (BelongsToOne)
+```
+
+#### 3. business-logic.md
+**언제:** 사용자 권한별 비즈니스 로직을 정의할 때
+**내용:**
+- 각 사용자 유형(role)별 권한
+- 비즈니스 규칙 및 제약사항
+- 상태 전이 규칙
+- 검증 로직
+
+**예시:**
+```markdown
+# 비즈니스 로직
+
+## 사용자 권한
+
+### 관리자 (admin)
+- 모든 데이터 CRUD 가능
+- 사용자 role 변경 가능
+- 시스템 설정 관리
+
+### 의사 (doctor)
+- 자신의 일정 관리 (CRUD)
+- 예약 확인/취소
+- 환자 진료 기록 조회/작성
+- 다른 의사 데이터 조회 불가
+
+### 환자 (patient)
+- 의사 검색 및 조회
+- 예약 생성/조회/취소 (자신의 예약만)
+- 자신의 진료 기록 조회
+- 다른 환자 데이터 접근 불가
+
+### 병원 (hospital)
+- 소속 의사 관리
+- 병원 통계 조회
+- 소속 의사의 예약 현황 조회
+
+## 예약 상태 전이
+pending → confirmed (의사 확인)
+pending → cancelled (환자/의사 취소)
+confirmed → cancelled (환자/의사 취소, 24시간 전까지만)
+
+## 비즈니스 규칙
+1. 예약은 진료 24시간 전까지만 취소 가능
+2. 의사는 동시에 2개 이상 예약 불가
+3. 환자는 같은 의사에게 1주일에 1번만 예약 가능
+```
+
+### 문서 업데이트 규칙
+
+**CRITICAL: 설계 변경 시 즉시 문서 업데이트**
+
+1. **대화 중 설계가 변경되면:**
+   - 해당 문서를 즉시 업데이트
+   - 변경 이유와 컨텍스트를 기록
+
+2. **변경 기록 형식:**
+   ```markdown
+   ## 변경 이력
+
+   ### 2026-02-10: Appointment 상태 필드 추가
+   **변경 내용:** status 필드 추가 (pending, confirmed, cancelled)
+   **이유:** 예약 취소 기능 추가 요청
+   **영향:** Appointment 엔티티, API 응답 구조 변경
+   ```
+
+3. **문서 일관성 유지:**
+   - Entity 변경 → architecture.md 업데이트
+   - 권한 규칙 변경 → business-logic.md 업데이트
+   - 요구사항 추가/변경 → requirements.md 업데이트
+
+### Compacting 후에도 안전
+
+**문서가 파일로 영속화되어 있어서:**
+- 대화가 압축(compacting)되어도 프로젝트 맥락 유지
+- 언제든 문서를 다시 읽어 일관성 있게 작업 가능
+- 설계 결정의 히스토리 추적 가능
+
+---
+
 ## Skills 목록
 
 | Skill | 파일 | 용도 |
@@ -93,17 +253,18 @@ pnpm test:watch
 | 프로젝트 생성 | `create-sonamu.md` | create-sonamu CLI 옵션 |
 | 프로젝트 초기화 | `project-init.md` | 프로젝트 생성 여부 확인, 대화 흐름 |
 | 프로젝트 설정 | `config.md` | .env, sonamu.config.ts 설정 |
-| 데이터베이스 | `database.md` | DB 설정, 포트 충돌 해결 |
+| 데이터베이스 | `database.md` | DB 설정, 포트 충돌 해결, 3-Tier 구조 |
 | Entity 검증 | `entity-validation-checklist.md` | Entity 생성 단계별 체크리스트 |
 | Entity 기본 | `entity-basic.md` | Entity JSON 구조, 필드 타입 |
-| Entity 관계 | `entity-relations.md` | BelongsToOne, HasMany, ManyToMany |
+| Entity 관계 | `entity-relations.md` | BelongsToOne, HasMany, ManyToMany, FK 코드 패턴 |
 | Subset | `subset.md` | 조회 필드 범위 정의 |
 | Model | `model.md` | BaseModelClass, CRUD 패턴 |
 | API | `api.md` | @api 데코레이터 |
 | Puri | `puri.md` | SQL 쿼리 빌더 |
 | i18n | `i18n.md` | 다국어 지원, SD 함수 |
 | Upsert | `upsert.md` | 관계 데이터 저장 |
-| Testing | `testing.md` | Vitest 테스트 (test/testAs) |
+| Testing | `testing.md` | Vitest 테스트 (test/testAs), Fixture 생성 팁 |
+| **Fixture CLI** | `fixture-cli.md` | **fixture gen/fetch/explore 명령어, 3-Tier DB 활용** |
 | Migration | `migration.md` | DB 스키마 마이그레이션, PK 타입 변경 |
 | Auth Migration | `auth-migration.md` | better-auth 등 외부 인증 통합 시 User.id 타입 변경 |
 | Frontend | `frontend.md` | Service, TanStack Query |
@@ -120,13 +281,17 @@ pnpm test:watch
 | 프로젝트 설정 | config |
 | Sonamu 로컬 개발 설정 | config |
 | DB 설정/포트 충돌 | database, config |
+| **3-Tier DB 구조 이해** | **database, fixture-cli** |
 | Entity/속성 정의 | entity-basic |
 | 관계 설정 | entity-relations |
+| **BelongsToOne FK 코드 사용** | **entity-relations** |
 | API 응답 필드 구성 | subset |
 | 데이터 조회/저장 로직 | model, puri |
 | API 엔드포인트 | api |
 | 관계 데이터 배치 저장 | upsert |
 | 테스트 작성 | testing |
+| **Fixture 데이터 생성/관리** | **fixture-cli** |
+| **테스트 데이터 생성 팁** | **testing (Fixture 데이터 생성 팁), fixture-cli (실전 팁)** |
 | DB 스키마 변경 | migration |
 | PK 타입 변경 (better-auth 등) | auth-migration |
 | 프론트엔드 개발 | frontend |

package/src/skills/sonamu/api.md

@@ -262,3 +262,105 @@ describe("E. Business Logic", () => {
   });
 });
 ```
+
+---
+
+## 컨벤션과 베스트 프랙티스
+
+### 에러 메시지 패턴
+
+일관된 에러 메시지를 위해 `this.modelName`과 `SD()` 함수를 사용합니다.
+
+**BAD: 하드코딩된 모델명**
+```typescript
+// findById
+if (!rows[0]) {
+  throw new NotFoundException(SD("error.entityNotFound")("Department", id));
+}
+
+// findMany
+throw new BadRequestException(SD("error.unknownSearchField")(params.search));
+```
+
+**GOOD: this.modelName 사용**
+```typescript
+// findById - 모델명 자동 인식
+if (!rows[0]) {
+  throw new NotFoundException(SD("notFound")(this.modelName, id));
+}
+
+// findMany - 짧고 명확한 키
+throw new BadRequestException(SD("search.invalidField")(params.search));
+```
+
+**장점:**
+- DRY 원칙 준수: 모델명 한 곳에서 관리
+- 리팩토링 안전: 모델명 변경 시 에러 메시지 자동 반영
+- 짧은 i18n 키: `notFound`, `search.invalidField`가 더 간결
+
+### satisfies 키워드
+
+TypeScript의 satisfies 키워드로 타입 추론을 유지하면서 타입 체크합니다.
+
+**BAD: 타입 추론 상실**
+```typescript
+const params: RoleListParams = {
+  num: 24,
+  page: 1,
+  search: "id" as const,
+  orderBy: "id-desc" as const,
+  ...rawParams,
+};
+```
+
+**GOOD: satisfies로 타입 체크 + 추론 유지**
+```typescript
+const params = {
+  num: 24,
+  page: 1,
+  search: "id" as const,
+  orderBy: "id-desc" as const,
+  ...rawParams,
+} satisfies RoleListParams;
+```
+
+**장점:**
+- 컴파일 타임 검증: params가 RoleListParams 타입을 만족하는지 확인
+- 타입 추론 유지: params의 실제 타입이 좁혀진 상태로 유지됨
+- IDE 지원 향상: 자동완성과 타입 체크가 더 정확
+
+### debug 옵션
+
+executeSubsetQuery의 debug 옵션은 기본값이 false이므로 명시할 필요 없습니다.
+
+**BAD: 불필요한 debug: false**
+```typescript
+return this.executeSubsetQuery({
+  subset,
+  qb,
+  params,
+  enhancers,
+  debug: false,  // 기본값이므로 불필요
+});
+```
+
+**GOOD: 기본값 활용**
+```typescript
+return this.executeSubsetQuery({
+  subset,
+  qb,
+  params,
+  enhancers,
+});
+```
+
+**debug: true를 사용하는 경우:**
+```typescript
+// 디버깅 시에만 명시
+return this.executeSubsetQuery({
+  subset,
+  qb,
+  params,
+  debug: true,  // SQL 쿼리 로그 출력
+});
+```

package/src/skills/sonamu/database.md

@@ -12,11 +12,230 @@ cd packages/api
 pnpm docker:up
 ```
 
+## 3-Tier DB 구조
+
+Sonamu는 3단계 데이터베이스 구조를 사용합니다. 각 DB의 역할과 데이터 흐름을 이해하는 것이 중요합니다.
+
+```
+production/development master (실제 DB)
+          ↓ (fixture fetch)
+     project_fixture (fixture DB)
+          ↓ (fixture sync)
+       project_test (test DB)
+```
+
+### DB별 역할
+
+| DB | 용도 | 데이터 출처 | 명령어 |
+|----|------|-----------|--------|
+| `project` | 운영/개발 실제 DB | 실제 사용자 데이터 | 직접 생성 |
+| `project_fixture` | 테스트용 참조 데이터 저장소 | production에서 fetch 또는 gen으로 생성 | `pnpm sonamu fixture gen/fetch` |
+| `project_test` | 테스트 실행 환경 | fixture에서 sync | `pnpm sonamu fixture sync` |
+
+### 데이터 흐름
+
+**1. fixture fetch (실제 데이터 가져오기)**
+```bash
+pnpm sonamu fixture fetch --include User --limit 10
+```
+- production/development master → fixture DB
+- 실제 운영 데이터를 테스트용으로 복사
+- 관련 데이터(FK)도 함께 가져옴
+
+**2. fixture gen (더미 데이터 생성)**
+```bash
+pnpm sonamu fixture gen --include Department --count 5
+```
+- fixture DB 내부에서 faker 기반 생성
+- 참조 관계(FK) 자동 해결
+- 한국어 데이터 생성 지원
+
+**3. fixture sync (테스트 DB 동기화)**
+```bash
+pnpm sonamu fixture sync
+```
+- fixture DB → test DB
+- 테스트 실행 전 최신 상태로 동기화
+- 각 테스트는 트랜잭션으로 격리되어 자동 롤백
+
+### 주의사항
+
+**CRITICAL: sourceDb vs targetDb 혼동 방지**
+
+- `fixture gen`: sourceDb=fixture, targetDb=fixture (fixture 내부에서 생성)
+- `fixture fetch`: sourceDb=production, targetDb=fixture (production → fixture)
+- 잘못 설정하면 FK 참조 오류 발생
+
+**예시 (올바른 설정)**:
+```typescript
+// fixture gen: fixture DB 내에서 참조 및 저장
+const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
+const generator = new FixtureGenerator(fixtureDb, fixtureDb, "fixture", EntityManager);
+
+// fixture fetch: production → fixture DB
+const sourceDb = DB.getDB("r"); // production_master
+const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
+const generator = new FixtureGenerator(sourceDb, fixtureDb, "fixture", EntityManager);
+```
+
+**참고**: Fixture CLI 명령어 상세 사용법은 `fixture-cli.md` 참조
+
+---
+
 ## Seed Data 관리
 
 테스트를 위한 기본 데이터(seed data)는 dump 파일에 추가하여 관리한다.
 
-### 워크플로우
+### 전체 워크플로우 개요
+
+Seed data 관리는 2단계로 진행된다:
+
+| 단계 | 목적 | 대상 DB |
+|------|------|---------|
+| **Phase 1** | 개발/테스트용 seed 준비 | `project_test`, `project_fixture` |
+| **Phase 2** | 실제 DB에 seed 적용 | `project` (실제 DB) |
+
+---
+
+### Phase 1: 개발/테스트용 Seed 준비
+
+개발 중 테스트를 위한 더미 데이터를 준비하는 단계.
+
+#### 1-1. 초기 dump 생성 (테이블 구조만)
+
+```bash
+pnpm dump
+```
+
+이 시점에서 생성된 `database/scripts/dump.sql`은:
+- CREATE TABLE 구문
+- CREATE SEQUENCE 구문
+- ALTER TABLE ... PRIMARY KEY
+- ALTER TABLE ... FOREIGN KEY
+- **INSERT문은 없음** (아직 데이터가 없으므로)
+
+#### 1-2. dump 파일에 INSERT문 추가
+
+`database/scripts/dump.sql` 파일을 열고, **FK CONSTRAINT 전**에 INSERT문을 추가한다.
+
+**중요: FK 의존성 순서를 고려하여 작성**
+```sql
+-- 독립 테이블부터
+INSERT INTO public.institutions (id, created_at, name, code) VALUES
+  (1, '2024-01-01 00:00:00+09', '본원', 'HQ');
+
+-- 참조 테이블 (institutions를 참조)
+INSERT INTO public.departments (id, created_at, name, code, institution_id) VALUES
+  (1, '2024-01-01 00:00:00+09', '연구부', 'RND', 1);
+
+-- 시퀀스 값 설정 (INSERT 후)
+SELECT pg_catalog.setval('public.institutions_id_seq', 1, true);
+SELECT pg_catalog.setval('public.departments_id_seq', 1, true);
+```
+
+#### 1-3. test DB에 적용
+
+```bash
+pnpm seed
+```
+
+`database/scripts/seed.sh`가 실행되며:
+- `SOURCE_DB="${DATABASE_NAME}_test"` → dump.sql을 test DB에 적용
+
+#### 1-4. fixture DB에 동기화
+
+```bash
+pnpm sonamu fixture sync
+```
+
+test DB의 데이터를 fixture DB로 복사.
+
+---
+
+### Phase 2: 실제 DB에 Seed 적용
+
+**⚠️ CRITICAL WARNING:**
+- 이 단계는 실제 DB(`project`)에 데이터를 넣는다
+- 기존 데이터가 있다면 덮어쓰여질 수 있다
+- **반드시 사용자에게 확인 후 진행해야 한다**
+
+**Claude Code 규칙:**
+```
+실제 DB에 seed를 적용하기 전에:
+1. 사용자에게 "실제 데이터베이스(project)에 seed 데이터를 적용하시겠습니까?" 질문
+2. 사용자가 명시적으로 승인할 때만 진행
+3. 승인 없이 절대 실행하지 말것
+```
+
+#### 2-1. 현재 상태 확인
+
+```bash
+# test/fixture DB에 데이터가 들어가 있어야 함
+PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_test -c "SELECT COUNT(*) FROM users;"
+```
+
+#### 2-2. 최종 dump 생성
+
+```bash
+# test/fixture의 데이터가 포함된 dump 생성
+pnpm dump
+```
+
+이번 dump에는 **INSERT문이 포함**되어 있다 (1-2에서 추가한 데이터).
+
+#### 2-3. seed.sh 파일 수정
+
+`database/scripts/seed.sh`를 열고 FIXTURE_DB 변경:
+
+```bash
+# 변경 전 (개발/테스트 단계)
+FIXTURE_DB="${DATABASE_NAME}_fixture"
+
+# 변경 후 (실제 DB에 seed)
+FIXTURE_DB="${DATABASE_NAME}"
+```
+
+#### 2-4. 실제 DB에 seed 실행
+
+**⚠️ 사용자 승인 후에만 실행:**
+
+```bash
+pnpm seed
+```
+
+이제 실제 DB(`project`)에 seed 데이터가 적용된다.
+
+#### 2-5. 확인
+
+```bash
+# 실제 DB에서 데이터 확인
+PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project -c "SELECT * FROM departments LIMIT 5;"
+```
+
+#### 2-6. seed.sh 원복 (중요!)
+
+실제 DB seed 완료 후, seed.sh를 원래대로 되돌려야 다음 개발 시 test DB를 사용한다:
+
+```bash
+# database/scripts/seed.sh
+FIXTURE_DB="${DATABASE_NAME}_fixture"  # 원복
+```
+
+---
+
+### 요약: Phase 1 vs Phase 2
+
+| 항목 | Phase 1 (개발/테스트) | Phase 2 (실제 DB) |
+|------|---------------------|------------------|
+| **시점** | 개발 중 테스트 데이터 준비 | 개발 완료 후 실제 데이터 준비 |
+| **dump 횟수** | 1회 (테이블 구조) | 2회 (데이터 포함) |
+| **대상 DB** | `project_test` → `project_fixture` | `project` |
+| **seed.sh** | `FIXTURE_DB="${DATABASE_NAME}_fixture"` | `FIXTURE_DB="${DATABASE_NAME}"` |
+| **사용자 승인** | 불필요 | **반드시 필요** |
+
+---
+
+### 구 워크플로우 (Phase 1 간단 버전)
 
 ```bash
 # 1. test DB에 기본 데이터 직접 추가 (psql 또는 Sonamu UI 사용)