DOCS/book/300_architecture/guidelines/naming_conventions.md

네이밍 컨벤션 원칙

작성일: 2025-12-06 목적: 코드 일관성 유지, 가독성 향상

---

파일명

Python

• router: {기능}_endpoint.py (예: message_endpoint.py)
• service: {도메인}_{기능}.py (예: coldmail_filter.py)
• state: {도메인}_repository.py (예: conversation_repository.py)
• utils: {기능}_extractor.py, {기능}_helper.py (예: json_extractor.py)

참고: DOCS/book/300_architecture/311_FastAPI_구조_원칙.md:53-63

디렉토리

• router/: HTTP 엔드포인트
• services/: 비즈니스 로직
• state/: DB 접근 (Repository 패턴)
• utils/: 공통 유틸리티 함수
• models/: ORM 모델
• schemas/: Pydantic 모델

참고: DOCS/book/300_architecture/311_FastAPI_구조_원칙.md:27-51

---

변수명

Python

• snake_case: 변수, 함수, 모듈
• PascalCase: 클래스
• UPPER_CASE: 상수

예시:

user_id = "uuid"  # 변수
def get_user_info():  # 함수
    pass
class UserService:  # 클래스
    pass
MAX_RETRIES = 3  # 상수

---

API 엔드포인트

경로 규칙

• kebab-case: URL 경로 (예: /api/intent-review/queue)
• RESTful: 리소스 중심 (예: /api/events/{event_id})

참고: rb8001/app/router/intent_review_endpoint.py:33

---

데이터베이스

테이블명

• snake_case: 소문자, 언더스코어 (예: conversation_log)
• 복수형: 컬렉션 의미 (예: users, conversations)

컬럼명

• snake_case: 소문자, 언더스코어 (예: user_id, created_at)
• UUID: id 또는 {entity}_id (예: user_id)

참고: DOCS/book/300_architecture/database/tables.md

---

환경변수

명명 규칙

• UPPER_SNAKE_CASE: 대문자, 언더스코어
• 명확한 의미: DATABASE_URL, JWT_SECRET_KEY

참고: 각 서비스 README.md

---

서비스명

컨테이너명

• kebab-case: 소문자, 하이픈 사용
• 실제 이름은 각 서비스 README 참조

서비스 ID

• 소문자: 일관된 형식 유지
• 실제 ID는 각 서비스 README 참조

참고: AGENTS.md:78-81

---

업데이트: 컨벤션 변경 시 즉시 반영