diff --git a/CLAUDE.md b/CLAUDE.md index c0a5c3a..123e5e9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -440,6 +440,38 @@ cd /home/webservice/api && php artisan migrate --force - API: 백엔드/데이터베이스 담당 (마이그레이션, 모델 정의, API) - 단일 DB를 두 프로젝트가 공유하므로 마이그레이션은 한 곳에서만 관리 +### 테이블 생성/수정 시 options JSON 컬럼 정책 (필수) + +> **경고: 테이블 생성/수정, 마이그레이션 작성, 모델 생성 시 반드시 아래 정책 문서를 먼저 읽고 준수하세요!** +> **정책 문서**: `/home/aweso/sam/docs/standards/options-column-policy.md` + +**핵심 원칙**: FK/조인키만 전용 컬럼, 나머지 속성은 `options` JSON에 저장 + +| 전용 컬럼 (일반 컬럼) | options JSON | +|---|---| +| FK/조인키 (다른 테이블 참조) | 테넌트별로 다를 수 있는 확장 속성 | +| WHERE/ORDER BY 자주 사용 필드 | 선택적(nullable) 부가 정보 | +| UNIQUE 제약 필드 | 구조가 유동적인 데이터 | +| INDEX 필요한 고빈도 조회 필드 | 드롭다운 선택지 목록 | +| 집계(SUM/AVG) 대상 | 이력/스냅샷성 데이터 | + +**필수 준수 사항**: + +``` +✅ 모든 비즈니스 테이블에 $table->json('options')->nullable() 포함 +✅ 모델 cast: 'options' => 'array' (❌ 'json' 금지) +✅ 모델에 getOption() / setOption() 헬퍼 메서드 추가 +✅ options 키 3개 이상 시 OPTION_* 상수 정의 +✅ options 수정 시 setOption() 사용 (전체 덮어쓰기 금지) +✅ API 응답 노출 시 accessor + $appends 추가 +``` + +**작업 전 체크리스트**: +- [ ] 정책 문서(`docs/standards/options-column-policy.md`) 읽기 +- [ ] 새 필드가 전용 컬럼인지 options인지 판단 (판단 흐름도 참고) +- [ ] 마이그레이션에 `options` JSON 컬럼 포함 확인 +- [ ] 모델에 `'options' => 'array'` cast + 헬퍼 메서드 포함 확인 + --- ## 메뉴 관리 규칙 (필수)