ai-server/CODING_CONVENTIONS.md

NLLB 번역 시스템 코딩 규칙

이 문서는 NLLB 번역 시스템 프로젝트의 코드 일관성과 품질을 유지하기 위한 코딩 규칙을 정의합니다.

1. 일반 원칙

• 언어: 모든 코드와 주석은 한국어로 작성하는 것을 원칙으로 합니다. 단, 외부 라이브러리 이름이나 기술 용어 등은 예외로 합니다.
• 인코딩: 모든 파일은 UTF-8로 인코딩합니다.
• 명령형: 커밋 메시지, 함수/메서드 설명 등은 명령형(~하기, ~함)으로 작성하여 명확성을 높입니다.

2. 코드 스타일

• 들여쓰기: 공백 4칸을 사용합니다.
• 최대 줄 길이: 한 줄은 120자를 넘지 않도록 합니다.
• 명명 규칙:
  • 변수: snake_case (예: translated_text)
  • 함수/메서드: snake_case (예: load_models)
  • 클래스: PascalCase (예: IntegratedTranslationSystem)
  • 상수: UPPER_SNAKE_CASE (예: NAS_MOUNT_POINT)
• 주석:
  • 복잡한 로직이나 중요한 결정 사항에 대해서는 #을 사용하여 간결한 주석을 작성합니다.
  • 파일의 목적과 전반적인 설명을 위해 파일 최상단에 """독스트링"""을 작성합니다.
• 타입 힌팅: 함수의 인자와 반환 값에는 타입 힌트를 명시하여 코드의 명확성을 높입니다. (예: def process_document(input_path: str) -> TranslationResult:)

3. Python 관련 규칙

• 임포트:
  1. 표준 라이브러리
  2. 서드파티 라이브러리
  3. 로컬 애플리케이션/라이브러리 순으로 그룹화하고, 각 그룹 사이에는 한 줄을 띄웁니다.
  • 예시:

    import asyncio
    import json
    from pathlib import Path
    
    from fastapi import FastAPI
    import torch
    
    from .integrated_translation_system import IntegratedTranslationSystem
    

• Docstrings: 모든 모듈, 함수, 클래스, 메서드에 대해 Google Python 스타일 가이드를 따르는 독스트링을 작성합니다.
• 오류 처리: try...except 블록을 사용하여 예상되는 오류를 명시적으로 처리하고, 오류 발생 시 로그를 남기거나 적절한 예외를 발생시킵니다.

4. FastAPI 관련 규칙

• 엔드포인트:
  • URL 경로는 소문자와 하이픈(-)을 사용합니다. (예: /system-status)
  • 응답 모델을 사용하여 API의 입출력 형식을 명확히 정의합니다.
• 비동기 처리: I/O 바운드 작업(파일 읽기/쓰기, 네트워크 요청 등)에는 async와 await를 적극적으로 사용하여 비동기 처리를 구현합니다.
• 백그라운드 작업: 시간이 오래 걸리는 작업(모델 로딩, 번역 등)은 BackgroundTasks를 사용하여 사용자 경험을 저해하지 않도록 합니다.

5. 프로젝트 구조

• config/: 설정 파일 (예: settings.json)
• data/: 원본 데이터 및 학습 데이터
• models/: 학습된 AI 모델 파일
• src/: 핵심 소스 코드
• tests/: 테스트 코드
• static/, templates/: FastAPI 웹 인터페이스 파일

6. 네트워크 설정

• Mac Mini IP: 192.168.1.122 (AI 번역 서버 호스트)
• DS1525+ NAS IP: 192.168.1.227 (문서 저장소)
• NAS 마운트 포인트: /Volumes/DS1525+
• 서버 포트: 8080 (FastAPI 웹 서비스)
• 대시보드 접속: http://192.168.1.122:8080/dashboard

6.1. API 키 인증

관리자용 API(/api/restart-models, /api/clear-cache 등)를 호출하려면 HTTP 요청 헤더에 API 키를 포함해야 합니다.

• 헤더 이름: X-API-KEY
• API 키 값: config/settings.json 파일의 security.api_key 값을 사용합니다.

cURL 예시:

curl -X POST http://192.168.1.122:20080/api/restart-models \
-H "X-API-KEY: nllb-secret-key-!@#$%"

7. 서버 운영 및 배포 (macOS)

이 서버는 24/7 무중단 운영을 위해 macOS의 launchd 서비스를 통해 관리됩니다. 이를 통해 시스템 재부팅 시 자동 시작 및 예기치 않은 종료 시 자동 재시작이 보장됩니다.

• 서비스 설정 파일: ~/Library/LaunchAgents/com.nllb-translation-system.app.plist

  • 이 파일은 서비스의 실행 방법, 로그 경로, 자동 재시작 여부 등을 정의합니다.

• 서비스 제어 명령어:

  • 시작: launchctl start com.nllb-translation-system.app
  • 중지: launchctl stop com.nllb-translation-system.app
  • 재시작 (설정 파일 수정 후):
    1. launchctl unload ~/Library/LaunchAgents/com.nllb-translation-system.app.plist
    2. launchctl load ~/Library/LaunchAgents/com.nllb-translation-system.app.plist

• 로그 확인:

  • 일반 로그: tail -f logs/service.log
  • 에러 로그: tail -f logs/service_error.log

• 주의: 개발 및 디버깅 시에는 launchd 서비스를 중지(launchctl stop ...)한 후, 터미널에서 직접 python src/fastapi_with_dashboard.py를 실행해야 포트 충돌이 발생하지 않습니다.