Backend

FastAPI API와 Canonical PostgreSQL 데이터·업무 규칙을 소유합니다. Python 3.12 이상과 uv를 사용하며 의존성은 pyproject.toml과 uv.lock에서 관리합니다.

실행

저장소 루트에서 다음을 실행합니다.

cd backend
uv sync
uv run uvicorn app.main:app --reload --port 8005

최초 설정 시 backend/envs/.env.example을 같은 폴더의 .env로 복사하고, DATABASE_URL에 준비된 로컬 개발 DB를 지정합니다. 실제 .env는 Git에서 제외하며 설정 예시만 추적합니다. 앱·Alembic·운영 CLI는 실행 위치와 관계없이 이 파일을 읽고, 프로세스에 주입된 환경변수가 파일보다 우선합니다.

서버 기본 API prefix는 /procedure-hub, 위 실행 명령의 health 주소는 http://127.0.0.1:8005/procedure-hub/health입니다. 실행 전 사용할 앱 포트의 점유를 확인합니다.

DB schema는 alembic/에서 관리합니다. 로컬 DB dump는 저장소 밖에서 보관하며, 서버 시작은 초기 데이터를 적재하지 않습니다.

폴더 역할

위치	책임
app/modules/	도메인·애플리케이션·저장소 구현
app/router/	외부 공개 compatibility API
app/core/	설정·DB·트랜잭션 등 공통 기반
envs/	로컬 환경 파일과 공유 설정 예시
alembic/	DB schema migration
scripts/	release·조회·검토 운영 CLI
tests/	도메인·API·저장소 회귀 검증
tests/integration/	기존 시술·번역 데이터가 필요한 DB 통합 검증

검증

backend/에서 실행합니다.

uv run ruff check app tests scripts
DATABASE_URL=sqlite+aiosqlite:///:memory: uv run pytest --ignore=tests/integration

CI도 같은 범위의 테스트를 실행하고, 별도로 빈 PostgreSQL의 Alembic schema를 검증합니다. tests/integration/은 기존 시술·번역 데이터와 일부 고정 데이터 건수를 전제로 하므로 CI에서 실행하지 않습니다. 필요한 데이터를 갖춘 별도 테스트 DB를 명시해 DATABASE_URL=... uv run pytest tests/integration으로 실행합니다. 일부 검증은 데이터를 수정하므로 개발·운영 DB를 지정하지 않습니다.

release 게시·검토· rollback CLI는 일반 검증 명령이 아니며, 실행 원장과 배포 가이드의 해당 절차를 따릅니다.

API 계약 · 도메인 메서드 계약 · 문서 지도