엄살 서비스의 FastAPI 서버리스 백엔드(API Gateway, Lambda, RDS for PostgreSQL 17, DynamoDB, S3 · ap-southeast-2)다. 문서 진입점은 색인, 현재 구현 범위는 SPEC, 에이전트 작업 규칙은 AGENTS, 협업 절차는 CONTRIBUTING을 따른다.
필요 도구: Git, GitHub CLI(gh auth login), uv 0.12.3, Python 3.12, make.
make setup # 잠금 의존성 설치 + 이 clone의 Git hook 연결
python3 tools/ai_workflow.py doctor # 원격·도구 버전·GitHub 인증 확인
make api # http://127.0.0.1:8000/health, /api/health/live, /api/health/readyDocker Desktop이 켜져 있어야 한다. DB는 127.0.0.1:5434에만 열리고 합성 데이터만 넣는다.
make db-up # PostgreSQL 17 컨테이너 시작(healthy까지 대기)
make db-migrate # Alembic 마이그레이션 적용
make db-test # 실제 DB 통합 테스트(마이그레이션을 적용했다 되돌림). CI는 같은 테스트를 PostgreSQL 서비스로 항상 실행
DATABASE_URL=postgresql://umsal:umsal_local@127.0.0.1:5434/umsal_backend make api
make db-down # 컨테이너 중지(데이터 볼륨은 유지)만료된 멱등 기록·초대 정리: DATABASE_URL=... uv run python -m umsal_backend.maintenance. 주기 실행 IaC는 infra/aws/jobs.yaml에 있다. 예약된 녹음 정리 작업은 접수된 한 건 삭제를 처리한다.
make가 없는 Windows에서는 docker compose up -d --wait db, uv run alembic upgrade head처럼 Makefile의 명령을 직접 실행하고 DATABASE_URL(통합 테스트는 TEST_DATABASE_URL)을 환경 변수로 지정한다. POSTGRES_PORT·POSTGRES_USER·POSTGRES_PASSWORD를 바꿨다면 make db-migrate LOCAL_DATABASE_URL=...처럼 같은 값을 넘긴다. Alembic·SQLAlchemy는 개발 의존성이라 Lambda zip에 들어가지 않는다. DATABASE_URL이 없으면 API는 DB에 접속하지 않고 ready의 checks.aurora는 not_configured다. 새 마이그레이션은 uv run alembic revision -m "설명"으로 만들고 SQL을 직접 쓴다. 운영 RDS 적용 전에는 uv run alembic upgrade head --sql로 SQL을 검토한다.
Python 테스트는 실제 PostgreSQL이 필요하다. 먼저 make db-up으로 로컬 DB를 띄운다. DB가 없으면 make python-check는 건너뛰지 않고 실패한다. 테스트는 그 로컬 DB에 마이그레이션을 적용하고 테이블을 비우므로, 손으로 넣어 둔 합성 데이터는 지워진다. CI는 자체 PostgreSQL 서비스로 같은 테스트를 실행한다.
make verify-fast # 전체 tracked tree 정책 검사 + Ruff·포맷·pytest(coverage 80%)
make verify-security # pip-audit (네트워크 필요)
make verify # 위 검사 전체 = CI와 같은 suitePR 검사·자동 병합 구조는 검증 하네스를 따른다.
업무 API 계약 원본은 contracts/openapi.yaml이고 결정 기록은 API 계약 정합성 문서에 있다.
AWS 배포 절차와 확인 기록은 백엔드 API AWS 배포를 따른다.
현재 main에는 Cognito 인증·가족/동의·업로드/finalize·작업/녹음 조회·화자 확인·권한별 결과 조회·전경 통화가 구현되어 있다. 분석은 기존 stub-1 합성 대역과 실제 CPU cpu-1/cpu-2를 구분한다. 새 원음 키는 내부 사용자별로 분리하며 기존 키의 재발급·finalize도 유지한다. 복원 당시의 배포 소스/설정은 운영 코드·설정 복원 기록, 현재 API별 구현/목표 차이는 계약 안내를 따른다. 녹음 한 건 삭제는 요청 시 조회 차단, 기존 예약 작업의 원음·결과 소거, 로그인 후 상태 조회를 연결한다. 자동 보관 만료·백업 만료 확인·주간 집계·제품 자동 알림은 후속 범위다.
CPU 분석은 동의한 통화의 WAV·MP3·M4A를 모노 화자 분리와 화자 확인 후 처리한다. 입력 범위·모델 리비전·활성화 절차는 CPU 분석을 따른다. CPU 워커는 분석 큐에 맞춰 0~1대로 자동 기동하며, 처리 후 60초간 새 작업이 없으면 종료한다.
활성 가족 간 전경 WebRTC 음성 통화 API와 AWS coturn 릴레이 구성을 추가했다. 수락·거절·중복 통화 방지·세션 소유·유지 신호·종료를 처리한다. 최대 30분, 미디어 저장 없음. 구성과 배포 절차·실기기 한계는 통화 설명서를 따른다.