Skip to content

CLAUDE.md

Latest commit

 

History

History
123 lines (97 loc) · 5.85 KB

CLAUDE.md

File metadata and controls

123 lines (97 loc) · 5.85 KB

Git 커밋 금지

  • 에이전트는 절대로 git commit을 실행하지 않는다
  • git add, git commit, git push 등 git 변경 명령어를 자동으로 실행하지 말 것
  • 커밋은 반드시 사용자가 직접 수행한다

코딩 스타일

변수명 규칙

  • 변수명만 보고 무엇을 의미하는지 바로 알 수 있어야 한다
  • key, value, config, cached, trimmed 같은 common한 변수명 금지
  • 역할과 맥락이 드러나는 구체적인 이름 사용
  • 예시:
    • key → configKey, value → configValue 또는 dbValue/cachedValue
    • config → latestVersionConfig, minimumVersionConfig
    • trimmed → trimmedVersion
    • VERSION_PATTERN → SEMVER_FORMAT_PATTERN

RomRom-BE 프로젝트 컨벤션

전체 API 컨벤션

Response 원칙

  • 프로젝트 전체적으로 Entity 객체를 DTO로 변환하지 않고 DB 값 그대로 Response에 담아서 전송
  • 별도의 data class 변환 없이 JPA Entity를 직접 응답에 포함하는 것이 기본 원칙
  • 일부 예외 케이스를 제외하면 Entity → DTO 매핑 없이 직접 반환

Admin API 컨벤션

DTO 규칙

  • Admin 관련 Controller는 **하나의 Request(AdminRequest)와 하나의 Response(AdminResponse)**로 통일
  • 도메인별로 별도 DTO를 만들지 않는다 (AdminReportRequest, AdminAnnouncementResponse 등 금지)
  • 새로운 필드가 필요하면 AdminRequest/AdminResponse에 추가

Response 구조

  • 전체 원칙과 동일하게 Entity 객체를 그대로 Response에 포함
  • 목록 조회 시 Page 정보(totalPages, totalElements, currentPage)는 Response에 포함
  • success, message 같은 처리 결과 필드는 사용하지 않는다 — HTTP 상태 코드(200 OK, 4xx, 5xx)로 성공/실패를 판단하고, 에러는 @ControllerAdvice + CustomException으로 처리

API 엔드포인트 패턴

  • action 파라미터 사용 금지 — 기능별로 별도 URL 엔드포인트를 분리
  • 모든 Admin API는 POST + multipart/form-data (@ModelAttribute) 형식으로 통일
  • 예: POST /api/admin/reports/item-list, POST /api/admin/announcements/create

Admin Service 위치

  • Admin 관련 Service는 RomRom-Application 모듈(com.romrom.application.service)에 위치
  • 도메인 모듈(RomRom-Domain-*)에 Admin Service를 두지 않는다

모듈별 Entity/Repository 위치 규칙

RomRom-Common 모듈

  • Entity: com.romrom.common.entity.postgres.* 또는 com.romrom.common.entity.mongo.*
  • Repository: com.romrom.common.repository.*
  • 도메인별 서브패키지(systemconfig/, member/ 등)를 Common 내에 만들지 않는다
  • 예: SystemConfig.java → common/entity/postgres/, SystemConfigRepository.java → common/repository/

다른 도메인 모듈 (RomRom-Domain-*)

  • 각 도메인 모듈 내에 자체 entity/repository 패키지를 유지한다
  • Common 모듈의 규칙을 도메인 모듈에 적용하지 않는다

API 문서화 (Swagger Docs) 컨벤션

필수 규칙: API 변경 시 Docs 인터페이스 동시 수정

  • API 동작이 변경되면 반드시 해당 *ControllerDocs.java 인터페이스도 함께 수정해야 한다
  • 각 Controller는 *ControllerDocs 인터페이스를 구현하며, Swagger 어노테이션은 Docs 인터페이스에 작성
  • 예: ItemController → ItemControllerDocs, MemberController → MemberControllerDocs

@ApiChangeLog 추가

  • API 동작 변경 시 @ApiChangeLogs 배열 최상단에 새 @ApiChangeLog 항목 추가
  • 필수 필드: date (YYYY.MM.DD), author (Author enum), issueNumber, description
  • description은 변경된 동작을 간결하게 서술 (예: "UGC 필터링 적용으로 400 에러 응답 추가")

@Operation description 업데이트

  • 에러 응답 추가/변경 시 description에 해당 에러 케이스 설명 추가
  • 새로운 필드 추가 시 필드 설명 및 예시 JSON 업데이트
  • 동작 방식 변경 시 (차단 → 경고 등) description에 반영

WebSocket 문서

  • WebSocket 관련 변경은 ChatWebSocketControllerDocs의 @Operation description에 반영
  • 페이로드 필드 추가/변경 시 "주요 필드" 목록과 예시 JSON 모두 업데이트

서버 초기화 로직

  • 서버 기동 시 초기화 로직 추가는 SystemConfigService.onApplicationReady() 에서 추가
  • Admin 계정 초기화는 RomRomInitiation (ApplicationRunner)에서 별도 관리

Flyway 마이그레이션 컨벤션

필수 규칙: 테이블 존재 여부 체크

  • 모든 SQL문은 반드시 테이블 존재 여부를 확인한 후 실행해야 한다
  • ALTER TABLE, UPDATE, INSERT, DELETE 등 테이블을 대상으로 하는 모든 SQL문은 IF EXISTS 체크로 감싸야 한다
  • 테이블이 존재하지 않을 경우 RAISE NOTICE로 알림 처리

마이그레이션 파일 구조

  • 경로: RomRom-Web/src/main/resources/db/migration/
  • 네이밍: V{버전}__설명.sql (예: V1_4_9__add_report_status_column.sql)
  • 모든 마이그레이션은 DO $$ BEGIN ... EXCEPTION WHEN OTHERS THEN RAISE WARNING ... END $$; 블록으로 감싸서 멱등성 보장
  • 기존 마이그레이션 파일들을 참고하여 동일한 패턴 준수

예시 패턴

DO $$
BEGIN
    -- 컬럼 추가
    IF EXISTS (
        SELECT 1 FROM information_schema.tables WHERE table_name = '테이블명'
    ) AND NOT EXISTS (
        SELECT 1 FROM information_schema.columns WHERE table_name = '테이블명' AND column_name = '컬럼명'
    ) THEN
        ALTER TABLE 테이블명 ADD COLUMN 컬럼명 타입;
    END IF;

    -- 데이터 업데이트
    IF EXISTS (
        SELECT 1 FROM information_schema.tables WHERE table_name = '테이블명'
    ) THEN
        UPDATE 테이블명 SET ...;
    END IF;

EXCEPTION
    WHEN OTHERS THEN
        RAISE WARNING '오류 발생: %', SQLERRM;
END $$;