작성일: 2026년 3월 19일 진행 단계: Phase 4 (상세 설계서) 완료 · Phase 5 (개발 환경 구성) 완료 이전 일지: Day 2 참고 (Phase 1~3 완료)

✅ 오늘의 성과 요약

항목 상태
Phase 4 — API 엔드포인트 전체 명세 ✅ 완료
Phase 4 — DB 테이블 DDL + 인덱스 전략 ✅ 완료
Phase 4 — QStash 스케줄러 상세 동작 ✅ 완료
Phase 4 — FastAPI 서비스 레이어 핵심 로직 ✅ 완료
Phase 5 — 로컬 개발 환경 세팅 ✅ 완료
Phase 5 — 보안 파일 분류 및 .gitignore 설정 ✅ 완료
Phase 5 — 환경변수 전체 정의 ✅ 완료
Phase 5 — Dockerfile + docker-compose 작성 ✅ 완료
Phase 5 — GitHub Actions CI/CD 구성 ✅ 완료
Phase 5 — GitHub 첫 푸시 완료 ✅ 완료
Phase 5 — CI/CD 테스트 통과 ✅ 완료

1. Phase 4 — 상세 설계서

API 엔드포인트 전체 명세

도메인별 엔드포인트 목록

도메인 엔드포인트 수 주요 기능
Auth 5개 회원가입, 로그인, 소셜 로그인, 토큰 갱신, 로그아웃
Medications 5개 약 목록 조회, 등록, 수정, 삭제, 일시중지
Schedules 1개 오늘 복용 스케줄 조회 (홈 화면)
Dose Logs 4개 복용 완료, 건너뜀, 기록 조회, 통계
Notifications 3개 기기 토큰 등록, QStash Webhook 수신, 알림 로그

공통 에러 코드

코드 HTTP 의미
AUTH_REQUIRED 401 토큰 없음 또는 만료
FORBIDDEN 403 권한 없음
NOT_FOUND 404 리소스 없음
VALIDATION_ERROR 422 입력값 오류
SERVER_ERROR 500 서버 내부 오류

주요 API 명세 예시 — 오늘 복용 스케줄 조회

// GET /v1/schedules/today
// Response 200
{
  "date": "2026-03-19",
  "total": 3,
  "done": 1,
  "rate": 33,
  "items": [
    {
      "schedule_id": "uuid",
      "medication_name": "Metformin 500mg",
      "scheduled_time": "08:00",
      "color_tag": "#1D9E75",
      "status": "done",
      "taken_at": "2026-03-19T08:12:00Z"
    }
  ]
}

DB 테이블 상세 정의 + 인덱스 전략

6개 테이블 DDL 확정

테이블 주요 제약 조건 인덱스
users email UNIQUE, soft delete —
medications user_id FK, soft delete (user_id) WHERE deleted_at IS NULL
schedules medication_id FK (medication_id)
dose_logs UNIQUE(schedule_id, log_date) (user_id, log_date DESC)
notification_logs schedule_id + user_id FK (user_id, sent_at DESC)
device_tokens token UNIQUE (user_id)