Project

General

Profile

Feature #1498

open
수황 수황

[T13] FastAPI 애플리케이션 골격 구축 (backend/)

Feature #1498: [T13] FastAPI 애플리케이션 골격 구축 (backend/)

Added by 수아 황 11 days ago. Updated 11 days ago.

Status:
New
Priority:
Normal
Assignee:
Start date:
11/09/2026
Due date:
11/10/2026 (7 days late)
% Done:

0%

Estimated time:

Description

목표 및 사용자 시나리오:
후속 Backend 개발자가 공통 구조와 실행·검증 절차를 기반으로 기능 API를 확장할 수 있도록 backend/ FastAPI 애플리케이션 골격을 구축한다.

범위:

  • app/main.py: 애플리케이션 생성 및 lifespan 시작·종료 처리
  • app/core/config.py: APP_ENV, APP_VERSION 설정
  • routers, services, repositories, schemas 패키지 구조
  • /health, /version 및 향후 /api/v1 라우터 확장 지점
  • /openapi.json, /docs 제공
  • pytest smoke 테스트 및 backend/README.md 실행·구조·확장 안내
  • PoC와 동일 버전의 fastapi, uvicorn 사용 및 의존성 파일 정리

비범위:

  • PostgreSQL 연결·세션 수명주기 및 /health/db: T14
  • 기능 API 구현: T15~T18
  • CI 변경: T28 담당과 협의 필요
  • 기존 PoC, 운영 파일 변경 및 불필요한 프레임워크 확대

담당자:
황수아 (Redmine: 수아 황). 스프레드시트의 담당 확정 여부는 별도 확인 필요.

선행조건:

  • Backend 개발환경 가이드에 따른 로컬 설치·실행 검증
  • T06 API 계약 확정 여부 확인. 현재 골격은 T06 확정 전 계약 내용과 무관한 범위로 작성됨.
  • 공지에 따른 스프레드시트 신청 및 PM/PL 담당 확정 확인

관련 화면/API/DB:

  • /health, /version, /openapi.json, /docs
  • /api/v1은 확장 지점만 구성하며 미구현 기능 경로는 404
  • DB 연결은 T14 범위. 개발환경의 DB 검증은 읽기 전용 비밀번호 미설정으로 HOLD.

완료조건(테스트·증빙 포함):

  • backend/ 패키지 구조 및 설정·라우터·lifespan 구성
  • uvicorn 실제 기동 및 /health, /version, /openapi.json, /docs 정상 응답
  • pytest smoke 통과 및 README 실행 안내
  • PR에 Redmine 번호, 테스트 결과 및 CI 적용 범위 명시
  • CI 통과 여부와 backend 테스트 포함 여부를 구분하고, 리뷰·Merge 및 필요한 Staging 확인 후 종료

현재 결과 / 검증 근거:
아래는 2026-11-06 전달된 로컬 작업 기록 기준이며, 이번 일감 등록 과정에서 테스트를 재실행한 결과는 아님.

  • 개발환경: 저장소 main 8a52022(PR #7 반영), .venv 및 의존성 설치, 초기 pytest 6 passed
  • T13: task/t13-backend-skeleton 브랜치에 backend/ 골격 17개 파일 작성
  • pytest 7 passed: 시작·종료, /health, /version, /openapi.json, /docs, 미구현 /api/v1의 404, 설정 기본값
  • uvicorn 실제 기동: /health 200, /version 200, /docs 200, OpenAPI 경로 2개
  • /api/v1/me 404 확인
  • 아직 커밋·push·PR 생성 전. 기존 CI에는 backend 테스트가 포함되지 않아 전체 완료나 CI 검증 완료로 판단하지 않음.
  • 개발환경 검증 시 기존 포트 충돌로 18080 사용. 작업 기록상 PoC 서버는 종료됨.

예상 일정:
PM 확정 필요. 완료일·추정시간 미정.

브랜치 / PR / Merge SHA:

  • 브랜치: task/t13-backend-skeleton
  • PR: 미생성 / Merge SHA: 없음

Staging 검증 결과:
미수행. DB 비밀번호 등 민감정보는 본 일감이나 저장소에 기록하지 않음.

다음 행동:
담당 확정 및 T06 상태 확인 → 로컬 변경 검토·커밋 → Redmine 번호를 포함한 PR 생성 → T28과 CI 적용 범위 협의 → 리뷰 및 필요한 Staging 검증.
등록 상태는 New / 0%로 두며, 담당 확정 후 실제 착수 상태를 반영한다.

참고:


Add

Subtasks


Add

Related issues

길문 Updated by 길래 문 11 days ago Actions #1

  • Due date set to 11/10/2026
  • Start date set to 11/09/2026

상이 Updated by 상재 이 11 days ago Actions #2

[T06 API 계약 검토 중 발견 — T13 담당 황수아님 확인 부탁드립니다] (작성: 이상재, T06 #1529)

h3. 경로 접두사 불일치

  • T13 Backend 골격(main, PR #14)은 앱 안에서 @API_V1_PREFIX = "/api/v1"@ 을 씁니다 (backend/app/core/config.py).
  • Staging Nginx는 @/api/@ 를 떼고 FastAPI로 넘깁니다 (poc/staging/README.md, PR #18).
  • 그대로 배포하면 외부 @/api/v1/auth/login@ 요청이 앱에 @/v1/auth/login@ 으로 도착해 404 가 납니다. @/api/health@, @/api/version@ 은 앱 경로가 @/health@, @/version@ 이라 문제없습니다.

h3. 해결안 (둘 중 하나)

앱 접두사를 @/v1@ 로 변경 (Nginx 그대로)

Nginx가 @/api/v1/@ 은 떼지 않고 그대로 넘기도록 변경 (앱 그대로)

API 계약(T06)의 외부 주소 @/api/v1/...@ 는 어느 쪽이든 바뀌지 않습니다.

Also available in: PDF Atom