docs: [CLAUDE.md] options JSON 컬럼 정책 필수 참조 규칙 추가

- 테이블 생성/수정 시 options-column-policy.md 참조 의무화
- 전용 컬럼 vs options JSON 분류 기준 요약 포함
- 필수 준수 사항 및 작업 전 체크리스트 추가
This commit is contained in:
김보곤
2026-03-02 17:06:50 +09:00
parent f8c4536331
commit a3c910d91b

View File

@@ -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 + 헬퍼 메서드 포함 확인
---
## 메뉴 관리 규칙 (필수)