From 46baeaff919dd53f85d7bed8c41c45f10e9ef2f9 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Sat, 6 Dec 2025 13:28:46 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B0=9C=EB=B0=9C=20=EC=B0=B8=EC=A1=B0?= =?UTF-8?q?=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80=20(reference/)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - API 엔드포인트 정리 (api_endpoints.md) - 인프라 정보 정리 (infrastructure.md) - 환경변수 정리 (environment_variables.md) - 배포 파이프라인 정리 (deployment_pipelines.md) - 상수/설정값 정리 (constants.md) - 네이밍 컨벤션 정리 (naming_conventions.md) - 로깅 규칙 정리 (logging_rules.md) 목적: 개발 시 중복/오류 방지, 빠른 참조 모든 문서 100줄 이하 유지, 파일:줄번호 참조 사용 --- book/300_architecture/300_README.md | 10 ++ .../reference/api_endpoints.md | 116 ++++++++++++++++++ book/300_architecture/reference/constants.md | 100 +++++++++++++++ .../reference/deployment_pipelines.md | 99 +++++++++++++++ .../reference/environment_variables.md | 92 ++++++++++++++ .../reference/infrastructure.md | 96 +++++++++++++++ .../reference/logging_rules.md | 105 ++++++++++++++++ .../reference/naming_conventions.md | 94 ++++++++++++++ 8 files changed, 712 insertions(+) create mode 100644 book/300_architecture/reference/api_endpoints.md create mode 100644 book/300_architecture/reference/constants.md create mode 100644 book/300_architecture/reference/deployment_pipelines.md create mode 100644 book/300_architecture/reference/environment_variables.md create mode 100644 book/300_architecture/reference/infrastructure.md create mode 100644 book/300_architecture/reference/logging_rules.md create mode 100644 book/300_architecture/reference/naming_conventions.md diff --git a/book/300_architecture/300_README.md b/book/300_architecture/300_README.md index d92c78a..f802662 100644 --- a/book/300_architecture/300_README.md +++ b/book/300_architecture/300_README.md @@ -20,6 +20,16 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습 - 360_로빙_컨테이너_경량화_전략.md - 370_임베딩_서비스_분리_아키텍처.md +## 참조 문서 (reference/) +개발 시 빠른 참조를 위한 정리 문서: +- [API 엔드포인트](./reference/api_endpoints.md) +- [인프라](./reference/infrastructure.md) +- [환경변수](./reference/environment_variables.md) +- [배포 파이프라인](./reference/deployment_pipelines.md) +- [상수/설정값](./reference/constants.md) +- [네이밍 컨벤션](./reference/naming_conventions.md) +- [로깅 규칙](./reference/logging_rules.md) + ## 핵심 메시지 컨테이너는 몸, 기억은 영혼. 100개의 로빙이 1개의 스킬 서비스를 공유하는 효율적 아키텍처. diff --git a/book/300_architecture/reference/api_endpoints.md b/book/300_architecture/reference/api_endpoints.md new file mode 100644 index 0000000..2480dcc --- /dev/null +++ b/book/300_architecture/reference/api_endpoints.md @@ -0,0 +1,116 @@ +# API 엔드포인트 참조 + +**작성일**: 2025-12-06 +**목적**: 개발 시 API 엔드포인트 중복/오류 방지, 빠른 참조 + +--- + +## rb8001 (메인 서비스, 8001) + +### 메시지 처리 +| 엔드포인트 | 메서드 | 설명 | 인증 | +|-----------|--------|------|------| +| `/api/message` | POST | Gateway/Frontend 메시지 처리 | JWT 필수 | +| `/api/feedback/chat` | POST | 채팅 피드백 (좋아요/싫어요) | JWT 필수 | + +**참고**: `rb8001/app/router/message_endpoint.py:26`, `rb8001/main.py:85` + +### LLM +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/api/llm/generate` | POST | 텍스트 생성 | +| `/api/llm/summarize` | POST | 요약 | +| `/api/llm/complete` | POST | 완성 | +| `/api/llm/health` | GET | 헬스체크 | + +**참고**: `rb8001/app/router/llm_endpoint.py:28,55,93,124` + +### 감정 분석 +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/api/emotion/infer` | POST | 감정 추론 | +| `/api/emotion/timeseries` | GET | 시계열 데이터 | +| `/api/emotion/team-insight` | GET | 팀 인사이트 | +| `/api/emotion/process-message` | POST | 메시지 처리 | +| `/api/emotion/health` | GET | 헬스체크 | + +**참고**: `rb8001/app/router/emotion_endpoint.py:75,150,188,263,303` + +### 기억 온톨로지 +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/api/v1/memory/event` | POST | 사건 저장 | +| `/api/v1/memory/recall` | POST | 회상 | +| `/api/v1/memory/stats` | GET | 통계 | + +**참고**: `rb8001/app/router/memory_ontology.py:69,118,181` + +### Intent 리뷰 +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/api/intent-review/queue` | GET | 큐 조회 | +| `/api/intent-review/{item_id}/label` | PUT | 라벨 업데이트 | +| `/api/intent-review/stats` | GET | 통계 | + +**참고**: `rb8001/app/router/intent_review_endpoint.py:33,58,81` + +### IR Deck 평가 +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/api/ir-deck/upload` | POST | PDF 업로드 | +| `/api/ir-deck/evaluate` | POST | 평가 시작 | +| `/api/ir-deck/evaluation/{evaluation_id}` | GET | 평가 결과 | +| `/api/ir-deck/chat` | POST | 채팅 | +| `/api/ir-deck/feedback` | POST | 피드백 | + +**참고**: `rb8001/app/router/ir_deck.py:109,169,263,297,344` + +### Slack +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/slack/events` | POST | Slack 이벤트 | +| `/slack/slash` | POST | 슬래시 명령어 | +| `/slack/health` | GET | 헬스체크 | + +**참고**: `rb8001/app/router/slack_endpoint.py:33,70,117` + +--- + +## skill-* 서비스 + +| 서비스 | 포트 | 주요 엔드포인트 | 참고 | +|--------|------|----------------|------| +| skill-email | 8501 | `/health` | - | +| skill-news | 8505 | `/health` | `skill_news/README.md:30` | +| skill-slack | 8502 | `/health` | `skill-slack/README.md:23` | +| skill-rag-file | 8508 | `/healthz`, `/api/upload`, `/api/search` | `skill-rag-file/app/main.py:60` | +| skill-calendar | 8512 | `/health`, `/api/events` | `skill-calendar/README.md:23` | + +--- + +## robeing-monitor (9024) + +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/health` | GET | 헬스체크 | +| `/api/stats/{robeing_id}` | GET/PUT | 스탯 조회/업데이트 | +| `/api/monitor/robeings` | GET | 로빙 상태 | +| `/api/monitor/skills` | GET | 스킬 서비스 상태 | + +**참고**: `robeing-monitor/README.md:68`, `robeing-monitor/app/api/monitor.py` + +--- + +## Gateway (8100) + +| 엔드포인트 | 메서드 | 설명 | +|-----------|--------|------| +| `/gateway/slack/events` | POST | Slack 이벤트 프록시 | +| `/gateway/*` | * | 각 서비스 프록시 | + +**참고**: `AGENTS.md:88-92` + +--- + +**업데이트**: 서비스 추가/변경 시 즉시 반영 + diff --git a/book/300_architecture/reference/constants.md b/book/300_architecture/reference/constants.md new file mode 100644 index 0000000..99cf102 --- /dev/null +++ b/book/300_architecture/reference/constants.md @@ -0,0 +1,100 @@ +# 상수/설정값 참조 + +**작성일**: 2025-12-06 +**목적**: 코드 중복 방지, 일관성 유지 + +--- + +## 스킬 레벨 + +| 레벨 | 스킬 | 설명 | +|------|------|------| +| 1 | 기본 대화 | 기본 채팅 | +| 2 | 이메일 읽기 | Gmail 읽기 | +| 3 | Slack 대화 | Slack 연동 | +| 4 | 이메일 전송 | Gmail 전송 | +| 5 | 데일리 브리핑 | 뉴스 요약 | +| 7 | 일정 관리 | 캘린더 | +| 11 | 문서 작성/편집 | 문서 작업 | +| 13 | 데이터 분석/차트 | 분석 | +| 17 | 프로젝트 관리 | 프로젝트 | +| 19 | AI 인사이트/예측 | 인사이트 | +| 23 | 자동화 워크플로우 | 자동화 | + +**참고**: `DOCS/journey/troubleshooting/250830_skill_level_system_restructure.md:45-57` + +--- + +## 스킬 타입 + +| 타입 | 설명 | 사용 위치 | +|------|------|-----------| +| `EMAIL` | 이메일 스킬 | `rb8001/app/services/brain/decision_engine.py:76` | +| `NEWS` | 뉴스 스킬 | 동일 | +| `SLACK` | Slack 스킬 | 동일 | +| `LLM` | LLM 처리 | 동일 | +| `CALENDAR` | 캘린더 스킬 | 동일 | +| `TOOL` | 도구 스킬 | 동일 | + +**참고**: `rb8001/app/services/brain/decision_engine.py:76-108` + +--- + +## 감정 분류 + +| 감정 | 설명 | +|------|------| +| `fear` | 두려움 | +| `surprise` | 놀람 | +| `anger` | 분노 | +| `sadness` | 슬픔 | +| `neutral` | 중립 | +| `happiness` | 행복 | +| `disgust` | 혐오 | + +**참고**: `rb8001/app/services/emotion_classifier.py` + +--- + +## 스탯 요구사항 + +| 스킬 | Memory | React | Compute | Empathy | +|------|--------|-------|---------|---------| +| EMAIL | 10 | 5 | 5 | 5 | +| NEWS | - | 10 | 5 | - | +| SLACK | 15 | - | - | 10 | +| ANALYSIS | 15 | - | 20 | - | +| LLM | - | - | 15 | 10 | + +**참고**: `rb8001/app/services/brain/decision_engine.py:560-565` + +--- + +## HTTP 상태 코드 + +| 코드 | 의미 | 사용 예시 | +|------|------|-----------| +| 200 | 성공 | 정상 응답 | +| 401 | 인증 실패 | JWT 만료 | +| 403 | 권한 없음 | 레벨 부족 | +| 404 | 없음 | 리소스 없음 | +| 500 | 서버 오류 | 내부 에러 | + +--- + +## 로그 레벨 + +| 레벨 | 설명 | 사용 시점 | +|------|------|-----------| +| `DEBUG` | 디버그 정보 | 개발 중 | +| `INFO` | 일반 정보 | 정상 동작 | +| `WARNING` | 경고 | 예상 가능한 문제 | +| `ERROR` | 오류 | 처리 실패 | +| `CRITICAL` | 치명적 오류 | 시스템 중단 | + +**참고**: `rb8001/app/core/logger.py` + +--- + +**업데이트**: 상수 추가/변경 시 즉시 반영 + diff --git a/book/300_architecture/reference/deployment_pipelines.md b/book/300_architecture/reference/deployment_pipelines.md new file mode 100644 index 0000000..1330bf1 --- /dev/null +++ b/book/300_architecture/reference/deployment_pipelines.md @@ -0,0 +1,99 @@ +# 배포 파이프라인 참조 + +**작성일**: 2025-12-06 +**목적**: 배포 프로세스 빠른 참조 + +--- + +## 자동 배포 (Gitea Actions) + +### 배포 대상 서비스 +- rb8001 +- robeing-monitor +- skill_email +- skill_news +- skill-rag-file +- skill-publish +- skill-slack +- fluent-bit +- frontend-customer +- frontend-ir-valuation + +**참고**: `AGENTS.md:28-29` + +### 배포 플로우 +1. 로컬에서 코드 수정 +2. `git push origin main` +3. Gitea Actions 자동 실행 (51123 서버) +4. SSH로 51124 서버 접속 +5. `git pull origin main` +6. `docker compose down && docker compose up -d --build` +7. 헬스체크 확인 + +**참고**: `AGENTS.md:83-85` + +### 워크플로우 파일 위치 +- 경로: `.gitea/workflows/*.yml` +- 예시: `rb8001/.gitea/workflows/cicd.yml` + +--- + +## 수동 배포 + +### 배포 대상 서비스 +- skill-embedding +- skill-calendar + +**참고**: `AGENTS.md:29` + +### 배포 절차 +```bash +cd /home/admin/ivada_project/[서비스명] +git pull origin main +docker compose down && docker compose up -d --build +docker ps # 재시작 확인 +``` + +--- + +## 배포 검증 + +### 필수 확인 사항 +- [ ] `docker ps`로 컨테이너 실행 확인 +- [ ] 헬스체크 엔드포인트 응답 확인 +- [ ] 로그 확인 (`docker logs [컨테이너명] --tail 50`) + +**주의**: Actions 성공 메시지만 믿지 말고 실제 컨테이너 상태 확인 + +**참고**: `AGENTS.md:30-31` + +--- + +## SSH Secrets + +| Secret 이름 | 설명 | 사용 위치 | +|------------|------|-----------| +| `SSH_PRIVATE_KEY_51124` | 51124 서버 SSH 키 | Gitea Actions | +| `SSH_HOST_51124` | 192.168.219.52 | Gitea Actions | +| `SSH_USER_51124` | admin | Gitea Actions | + +**참고**: `DOCS/journey/plans/251206_skill_calendar_자동배포_구성.md` + +--- + +## 트러블슈팅 + +### Actions 캐시 문제 +- 증상: 워크플로우 수정이 반영되지 않음 +- 해결: `/root/.cache/act/` 삭제 +- 참고: `DOCS/journey/troubleshooting/250929_actions_cache_problem.md` + +### SSH 인증 실패 +- 증상: "Permission denied (publickey)" +- 해결: Gitea Secrets의 SSH 키 확인 +- 참고: `DOCS/journey/troubleshooting/250728_happybell80_nginx프록시및CI배포문제해결.md` + +--- + +**업데이트**: 배포 프로세스 변경 시 즉시 반영 + diff --git a/book/300_architecture/reference/environment_variables.md b/book/300_architecture/reference/environment_variables.md new file mode 100644 index 0000000..39692c7 --- /dev/null +++ b/book/300_architecture/reference/environment_variables.md @@ -0,0 +1,92 @@ +# 환경변수 참조 + +**작성일**: 2025-12-06 +**목적**: 환경변수 중복/오류 방지, 빠른 참조 + +--- + +## 공통 환경변수 + +| 변수명 | 필수 | 설명 | 예시 | +|--------|------|------|------| +| `SERVICE_NAME` | 예 | 서비스 이름 | `skill-slack` | +| `PORT` | 예 | 서비스 포트 | `8502` | +| `LOG_LEVEL` | 선택 | 로그 레벨 | `INFO` | +| `DATABASE_URL` | 예* | PostgreSQL 연결 문자열 | `postgresql://...` | +| `JWT_SECRET_KEY` | 예* | JWT 시크릿 키 | - | + +*일부 서비스만 필수 + +--- + +## rb8001 + +| 변수명 | 필수 | 설명 | 참고 | +|--------|------|------|------| +| `DATABASE_URL` | 예 | PostgreSQL 연결 | `rb8001/docker-compose.yml` | +| `JWT_SECRET_KEY` | 예 | JWT 인증 | `rb8001/app/auth.py` | +| `NEO4J_PASSWORD` | 선택 | Neo4j 비밀번호 | `rb8001/docker-compose.yml` | +| `TAVILY_API_KEY` | 선택 | Tavily API 키 | `rb8001/docker-compose.yml` | +| `USE_EMOTION_ANALYSIS` | 선택 | 감정 분석 활성화 | `true/false` | +| `GEMINI_API_KEY` | 선택 | Gemini API 키 | - | + +--- + +## skill-* 서비스 + +### skill-slack +| 변수명 | 필수 | 설명 | +|--------|------|------| +| `SERVICE_API_KEY` | 예 | 서비스 인증 키 | +| `SLACK_BOT_TOKEN` | 예 | Slack 봇 토큰 | +| `JWT_SECRET_KEY` | 예 | JWT 검증 | + +**참고**: `skill-slack/app/core/config.py`, `skill-slack/docker-compose.yml` + +### skill-rag-file +| 변수명 | 필수 | 설명 | +|--------|------|------| +| `DATABASE_URL` | 예 | PostgreSQL 연결 | +| `CHROMA_PORT` | 선택 | ChromaDB 포트 (기본: 8000) | + +**참고**: `skill-rag-file/docker-compose.yml:11` + +### skill-calendar +| 변수명 | 필수 | 설명 | +|--------|------|------| +| `DATABASE_URL` | 예 | PostgreSQL 연결 (51123) | + +**참고**: `skill-calendar/docker-compose.yml:14` + +### skill-news +| 변수명 | 필수 | 설명 | +|--------|------|------| +| `GEMINI_API_KEY` | 예 | Gemini API 키 | +| `DATABASE_URL` | 예 | PostgreSQL 연결 | + +**참고**: `skill_news/README.md:36-39` + +--- + +## robeing-monitor + +| 변수명 | 필수 | 설명 | +|--------|------|------| +| `DATABASE_URL` | 예 | PostgreSQL 연결 | +| `ROBEING_URLS` | 예 | 로빙 서비스 URL 목록 | +| `SKILL_URLS` | 예 | 스킬 서비스 URL 목록 | + +**참고**: `robeing-monitor/README.md:37-42` + +--- + +## 주의사항 + +- **민감 정보 하드코딩 금지**: API 키, 토큰, 비밀번호는 `.env` 파일에만 저장 +- **기본값 사용 금지**: 환경변수 미설정 시 명시적 에러 처리 +- **참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md` 섹션 12 + +--- + +**업데이트**: 환경변수 추가/변경 시 즉시 반영 + diff --git a/book/300_architecture/reference/infrastructure.md b/book/300_architecture/reference/infrastructure.md new file mode 100644 index 0000000..772a446 --- /dev/null +++ b/book/300_architecture/reference/infrastructure.md @@ -0,0 +1,96 @@ +# 인프라 참조 + +**작성일**: 2025-12-06 +**목적**: 서버/포트/네트워크 정보 빠른 참조 + +--- + +## 서버 구성 + +| 서버 | IP | 역할 | 주요 서비스 | +|------|-----|------|------------| +| 51123 | 192.168.219.45 | 메인 서버 | nginx, Gitea, auth-server, robeing-gateway, frontend-base, PostgreSQL | +| 51124 | 192.168.219.52 | 로빙/스킬 서버 | rb8001, robeing-monitor, skill-*, ChromaDB | + +**참고**: `AGENTS.md:78-81`, `DOCS/book/300_architecture/310_전체_시스템_구조_컨테이너와_마이크로서비스.md:27-30` + +--- + +## 포트 매핑 + +### 51123 서버 +| 서비스 | 포트 | 프로토콜 | 설명 | +|--------|------|----------|------| +| nginx | 80, 443 | HTTP/HTTPS | 웹 서버 | +| Gitea | 3000 | HTTP | Git 저장소 | +| robeing-gateway | 8100 | HTTP | API 게이트웨이 | +| frontend-base | 8000 | HTTP | 관리자 대시보드 | +| auth-server | 9000 | HTTP | 인증 서버 | +| PostgreSQL | 5432 | TCP | 데이터베이스 | +| Neo4j | 7687 | TCP | 그래프 DB | + +### 51124 서버 +| 서비스 | 포트 | 프로토콜 | 설명 | +|--------|------|----------|------| +| rb8001 | 8001 | HTTP | 메인 로빙 서비스 | +| robeing-monitor | 9024 | HTTP | 모니터링 서비스 | +| skill-email | 8501 | HTTP | 이메일 스킬 | +| skill-news | 8505 | HTTP | 뉴스 스킬 | +| skill-slack | 8502 | HTTP | Slack 스킬 | +| skill-rag-file | 8508 | HTTP | RAG 파일 스킬 | +| skill-calendar | 8512 | HTTP | 캘린더 스킬 | +| skill-embedding | 8511 | HTTP | 임베딩 스킬 | +| skill-publish | - | HTTP | 퍼블리싱 스킬 | +| ChromaDB | 8000 | HTTP | 벡터 DB | + +**참고**: `AGENTS.md:78-81`, 각 서비스 `docker-compose.yml` + +--- + +## 네트워크 플로우 + +### 배포 플로우 +``` +로컬 개발 → Gitea 푸시 → Actions (51123) → SSH (51124) → git pull → docker 재시작 +``` + +**참고**: `AGENTS.md:83-85` + +### Admin Dashboard 라우팅 +``` +사용자 → nginx (51123) → robeing-gateway (8100) → frontend-base (8000) +``` + +**참고**: `AGENTS.md:88-92` + +### API 프록시 +``` +Frontend → nginx (/gateway/) → Gateway (8100) → 각 서비스 +``` + +--- + +## SSH 접속 + +| 서버 | SSH 포트 | 사용자 | 용도 | +|------|----------|--------|------| +| 51124 | 51124 | admin | 배포 (Gitea Actions) | + +**참고**: `AGENTS.md:28-29`, Gitea Actions 워크플로우 + +--- + +## 데이터베이스 + +| DB | 서버 | 포트 | 데이터베이스명 | 사용자 | +|----|------|------|---------------|--------| +| PostgreSQL | 51123 | 5432 | main_db | robeings | +| Neo4j | 51123 | 7687 | - | neo4j | +| ChromaDB | 51124 | 8000 | - | - | + +**참고**: `DOCS/book/300_architecture/database/tables.md` + +--- + +**업데이트**: 서버/포트 변경 시 즉시 반영 + diff --git a/book/300_architecture/reference/logging_rules.md b/book/300_architecture/reference/logging_rules.md new file mode 100644 index 0000000..bddcdd7 --- /dev/null +++ b/book/300_architecture/reference/logging_rules.md @@ -0,0 +1,105 @@ +# 로깅 규칙 참조 + +**작성일**: 2025-12-06 +**목적**: 로그 일관성 유지, 디버깅 효율성 향상 + +--- + +## 로그 레벨 사용 규칙 + +| 레벨 | 사용 시점 | 예시 | +|------|-----------|------| +| `DEBUG` | 상세 디버깅 정보 | 변수 값, 함수 진입/종료 | +| `INFO` | 정상 동작 정보 | 요청 처리, 상태 변경 | +| `WARNING` | 예상 가능한 문제 | 재시도, 폴백 처리 | +| `ERROR` | 처리 실패 | 예외 발생, API 오류 | +| `CRITICAL` | 시스템 중단 | DB 연결 실패, 서비스 다운 | + +**참고**: `rb8001/app/core/logger.py` + +--- + +## 로그 포맷 + +### 구조화된 로그 +```python +logger.info(f"User {user_id} authenticated", extra={ + "user_id": user_id, + "action": "authenticate" +}) +``` + +### JSON 로깅 +- 형식: JSON (python-json-logger 사용) +- 필드: `time`, `level`, `module`, `msg` + +**참고**: `rb8001/app/core/logger.py` + +--- + +## 로그 위치 + +### 컨테이너 내부 +- 경로: `/code/logs/[서비스명].log` +- 예시: `/code/logs/rb8001.log` + +### 호스트 (백업) +- 경로: `/mnt/51123logs/[서비스명]/` +- 백업 시간: 매일 03:00 + +**참고**: `AGENTS.md:133-137` + +--- + +## 로그 확인 방법 + +### 실시간 로그 +```bash +docker logs [컨테이너명] --tail 100 +``` + +### 파일 로그 +```bash +tail -f /code/logs/[서비스명].log +``` + +### 에러 필터링 +```bash +docker logs [컨테이너명] | grep -iE "error|warn|fail" +``` + +**참고**: `AGENTS.md:133-137` + +--- + +## 로그 보관 + +### Docker JSON 로그 +- 위치: `/var/lib/docker/containers/*/json.log` +- 권한: sudo 필요 + +### OpenSearch +- 주소: http://192.168.219.45:9200 +- 인덱스: `dataprepper-static` (서비스 로그) +- 일별 인덱스: `dataprepper-YYYY.MM.DD` (fluent-bit 로그) + +**참고**: `AGENTS.md:137-142` + +--- + +## 로깅 모범 사례 + +### DO +- 요청/응답 로깅 (INFO) +- 에러 상세 정보 포함 (ERROR) +- 사용자 ID 포함 (개인정보 제외) + +### DON'T +- 민감 정보 로깅 (비밀번호, 토큰) +- 과도한 DEBUG 로그 (프로덕션) +- 중복 로그 (같은 정보 반복) + +--- + +**업데이트**: 로깅 규칙 변경 시 즉시 반영 + diff --git a/book/300_architecture/reference/naming_conventions.md b/book/300_architecture/reference/naming_conventions.md new file mode 100644 index 0000000..c084fc5 --- /dev/null +++ b/book/300_architecture/reference/naming_conventions.md @@ -0,0 +1,94 @@ +# 네이밍 컨벤션 참조 + +**작성일**: 2025-12-06 +**목적**: 코드 일관성 유지, 가독성 향상 + +--- + +## 파일명 + +### Python +- **router**: `{기능}_endpoint.py` (예: `message_endpoint.py`) +- **service**: `{도메인}_{기능}.py` (예: `coldmail_filter.py`) +- **state**: `{도메인}_repository.py` (예: `conversation_repository.py`) + +**참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md:53-63` + +### 디렉토리 +- `router/`: HTTP 엔드포인트 +- `services/`: 비즈니스 로직 +- `state/`: DB 접근 (Repository 패턴) +- `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` + +**참고**: `DOCS/book/300_architecture/reference/environment_variables.md` + +--- + +## 서비스명 + +### 컨테이너명 +- **kebab-case**: 소문자, 하이픈 (예: `skill-slack`, `robeing-monitor`) + +### 서비스 ID +- **소문자**: `rb8001`, `skill-email` + +**참고**: `AGENTS.md:78-81` + +--- + +**업데이트**: 컨벤션 변경 시 즉시 반영 +