# 네이밍 컨벤션 원칙

**작성일**: 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**: 상수

**예시**:
```python
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`

---

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

