Skip to content

README.ko.md

Latest commit

 

History

History
206 lines (145 loc) · 7.45 KB

README.ko.md

File metadata and controls

206 lines (145 loc) · 7.45 KB
Raw

Essay Feedback Writer Project - backend

언어 선택 / Language Selection:

한국어  ｜  English 

Requirements

  • Docker
  • uv - Python 패키지 및 환경 관리 (Poetry 대체)

로컬 개발

  • Docker Compose로 스택을 시작하세요:
docker compose up -d
  • 이제 브라우저에서 아래 URL로 접속하여 상호작용할 수 있습니다:

프론트엔드, Docker로 빌드된 경로 기반 처리: http://localhost:5173

백엔드, OpenAPI 기반 JSON 웹 API: http://localhost:8000

자동화된 Swagger UI 문서(백엔드 OpenAPI에서 제공): http://localhost:8000/docs +API docs

Adminer, 데이터베이스 웹 관리: http://localhost:8080 +API docs

Traefik UI, 프록시가 처리하는 경로를 확인: http://localhost:8090 +API docs

로그를 확인하려면:

docker compose logs

특정 서비스의 로그를 확인하려면 서비스 이름을 추가하세요, 예를 들어:

docker compose logs backend

일반적인 워크플로우

의존성은 uv로 관리됩니다.

./backend/ 폴더에서 모든 의존성을 설치하려면:

$ uv sync

가상 환경 내에서 명령어를 실행하려면:

$ uv run pytest
$ uv run ruff check --fix

편집기가 올바른 Python 가상 환경을 사용하고 있는지 확인하세요.

주요 백엔드 디렉터리

  • SQLAlchemy 모델: ./backend/app/models.py
  • API 엔드포인트: ./backend/app/api/routes/ (4개 라우터: user, ielts, ksat, shared)
  • CRUD 작업: ./backend/app/crud/ (엔티티별 모듈)
  • Pydantic 스키마: ./backend/app/schemas/
  • 멀티 에이전트 채점: ./backend/app/agents/ (swarm, aggregator, builder, loader)
  • 루브릭 설정: ./backend/app/agents/configs/ (도메인별 YAML 루브릭)

pre-commit 설정

  1. pre-commit을 설치하세요
apt install -y pre-commit
  1. pre-commit을 적용하세요
pre-commit install

백엔드 테스트

$ docker compose -f docker-compose.yaml -f docker-compose.override.yaml -f docker-compose.test.yaml up

위 명령어를 실행하면 개발(dev) 또는 운영(prod) 환경의 데이터베이스와 격리된 테스트 전용 데이터베이스(test DB)가 실행됩니다.

테스트 진행 시 데이터 분리를 위해 test DB 를 사용하는 것을 권장합니다.

테스트를 실행하려면 아래 명령어를 사용하세요:

$ docker compose backend bash # backend container 대화형 세션 시작
$ bash ./scripts/test.sh

테스트는 Pytest로 실행되며, ./backend/app/tests/에서 테스트를 수정하거나 추가할 수 있습니다.

GitHub Actions를 사용하면 테스트가 자동으로 실행됩니다.

테스트 커버리지

테스트를 실행하면 htmlcov/index.html 파일이 생성됩니다. 이 파일을 브라우저에서 열어 테스트의 커버리지를 확인할 수 있습니다.

마이그레이션

로컬 개발 중에 앱 디렉터리가 컨테이너 내부에서 볼륨으로 마운트되므로 alembic 명령어로 마이그레이션을 실행할 수 있습니다. 마이그레이션 코드는 앱 디렉터리에 저장되어 Git 리포지토리에 추가할 수 있습니다.

모델을 변경할 때마다 "revision"을 생성하고 해당 revision으로 데이터베이스를 "upgrade"해야 합니다. 이렇게 해야 데이터베이스 테이블이 업데이트됩니다. 그렇지 않으면 애플리케이션에 오류가 발생할 수 있습니다.

  • 백엔드 컨테이너에서 대화형 세션을 시작하려면:
$ docker compose exec backend bash

  • Alembic은 ./backend/app/models.py에서 SQLModel 모델을 자동으로 가져오도록 구성되어 있습니다.

  • 모델을 변경한 후(예: 열 추가) 컨테이너 내부에서 revision을 생성하려면 예를 들어:

$ alembic revision --autogenerate -m "Add column last_name to User model"

  • Alembic 디렉터리에서 생성된 파일을 Git 리포지토리에 커밋합니다.

  • revision을 생성한 후, 데이터베이스에서 마이그레이션을 실행하려면:

$ alembic upgrade head

VSCode 디버깅 (Docker)

Docker 컨테이너 내부에서 실행 중인 백엔드를 debugpy와 VSCode의 attach 디버거를 사용하여 디버깅할 수 있습니다.

사전 준비

  • VSCode에 Python Debugger extension 설치
  • 백엔드 컨테이너에 debugpy 설치 (dev 의존성으로 포함되어 있음)

실행 중인 컨테이너에 debugpy가 아직 설치되지 않은 경우:

docker-compose exec backend pip install debugpy

서버 디버깅

  1. .env 파일에서 DEBUG=true로 설정
  2. 백엔드를 재시작: 
    docker-compose up -d backend
  3. 디버거가 연결될 때까지 서버가 대기합니다
  4. VSCode에서 브레이크포인트를 설정한 후 F5를 누르고 **"Attach to Docker Backend"**를 선택

pytest 디버깅

  1. .env에서 DEBUG=false(또는 미설정)로 설정하여 서버가 5678 포트를 점유하지 않도록 합니다
  2. 컨테이너 내부에서 debugpy와 함께 pytest를 실행: 
    docker-compose exec backend python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m pytest app/tests/api/routes/test_ielts.py -v
  3. 테스트 파일에서 브레이크포인트를 설정한 후 F5를 누르고 **"Debug Pytest in Docker"**를 선택

VSCode launch.json

.vscode/launch.json 파일에 다음 내용이 포함되어야 합니다:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Docker Backend",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}/backend", "remoteRoot": "/app" }
      ]
    },
    {
      "name": "Debug Pytest in Docker",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}/backend", "remoteRoot": "/app" }
      ]
    }
  ]
}

이메일 템플릿

이메일 템플릿은 ./backend/app/email-templates/에 있습니다. 여기에는 build와 src라는 두 개의 디렉터리가 있습니다. src 디렉터리에는 최종 이메일 템플릿을 만들 때 사용하는 소스 파일이 있고, build 디렉터리에는 애플리케이션에서 사용하는 최종 이메일 템플릿이 있습니다.

계속하기 전에 MJML extension을 VS Code에 설치했는지 확인하세요.

MJML extension을 설치한 후, src 디렉터리에서 새 이메일 템플릿을 생성할 수 있습니다. 새 이메일 템플릿을 생성한 후 .mjml 파일을 열고 Ctrl+Shift+P로 명령 팔레트를 열고 MJML: Export to HTML을 검색하여 실행하세요. 이렇게 하면 .mjml 파일이 .html 파일로 변환되고, 이제 이를 build 디렉터리에 저장할 수 있습니다.