From a3c910d91bc9713f42066772faafe4c16e8454ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Mon, 2 Mar 2026 17:06:50 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[CLAUDE.md]=20options=20JSON=20?= =?UTF-8?q?=EC=BB=AC=EB=9F=BC=20=EC=A0=95=EC=B1=85=20=ED=95=84=EC=88=98=20?= =?UTF-8?q?=EC=B0=B8=EC=A1=B0=20=EA=B7=9C=EC=B9=99=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 테이블 생성/수정 시 options-column-policy.md 참조 의무화 - 전용 컬럼 vs options JSON 분류 기준 요약 포함 - 필수 준수 사항 및 작업 전 체크리스트 추가 --- CLAUDE.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) 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 + 헬퍼 메서드 포함 확인 + --- ## 메뉴 관리 규칙 (필수)