본문으로 건너뛰기

JunkBox apps/sipmon-api 가이드

업무 개요​

  • 술자리에서 마신 잔을 기록해 누적 순수 알코올량과 마시는 속도를 개인 기준과 비교해 보여주는 앱임.
  • 핵심 개념은 음주 세션(사용자당 진행 중 세션은 하나), 잔 기록, 주류와 분류, 순수 알코올 g, 개인 비교 기준(시간당 g/h와 누적 g)임.
  • 기본 흐름은 세션 시작, 주류를 골라 잔 기록 추가, 대시보드에서 속도와 누적량 확인, 세션 종료 순서임. 종료한 세션은 기록 메뉴에서 조회·정정함.
  • 수치는 사용자가 정한 기준 대비 지표이며 안전도나 취기를 예측하지 않음.

1. 역할과 책임 경계​

  • apps/sipmon-api는 사용자별 음주 세션·주류 목록·개인 비교 기준을 소유하는 FastAPI 앱임. apps/sipmon-ui 빌드 자산과 shared-ui 자산을 제공하며, 웹 셸은 web.py와 templates/sipmon.html이 렌더링함.
  • 개발 API는 127.0.0.1:18011, UI는 Vite 15011을 사용함. just sipmon-backend, just sipmon-frontend, sipmon:dev-all 작업을 제공함. /health는 헬스 체크임.
  • SIPMON_BASE_URL 기본값은 https://sipmon.sleepzz.xyz임. 운영 Compose의 junkbox-sipmon은 컨테이너 내부 포트 8080을 사용하고 Cloudflare Tunnel은 http://junkbox-sipmon:8080으로 연결함. GitHub Actions 배포 정책은 build·deploy·배포 시 자동 기동을 활성화하고 unless-stopped로 재시작함. SIPMON_DATABASE_URL은 앱 전용 SQLite를 가리킴.

2. 인증과 권한​

  • /api/sipmon 라우터는 Hub JWT Cookie/Header의 require_module("SIPMON")을 적용하고, 소유자 user_id로 모든 도메인 행을 제한함.
  • 웹 페이지는 Hub 로그인으로 required_module=SIPMON과 원래 URL을 전달함. Hub 로그인 복귀 경로는 SipMon 개발 UI 15011 또는 설정된 운영 URL의 /dashboard임. 권한 없음은 Hub 로그인 거부 흐름으로 복귀함.
  • 웹 진입 경로는 /dashboard, /setup, /settings, /settings/categories, /settings/drinks, /sessions, /sessions/{session_id}임.
    • SSR 셸의 브랜드는 JunkBox SipMon이고 설명은 Portal의 SipMon 메뉴 설명을 조회함.
    • 새 화면은 SipMon | JunkBox SipMon 제목과 앱 favicon을 제공하고 web manifest를 연결하지 않아 Android Chrome의 설치에서 이름 입력이 가능한 진입을 사용함.
    • 기존 설치 앱용 PWA manifest URL과 서비스 워커 URL을 유지하며 오프라인 캐시·동기화는 제공하지 않음.

3. 데이터​

  • tb_sipmon_user_setting_m은 사용자별 시간당 기준 hourly_limit_g와 누적 기준 total_limit_g, 기본 목록 초기화 시각을 저장함.
  • tb_sipmon_category_m은 사용자별 분류명·아이콘 키·표시 순서를 저장함. tb_sipmon_drink_m은 분류 FK, 주류명, 한 잔 mL, 도수 %, 즐겨찾기, 표시 순서와 revision을 저장함. 삭제는 deleted_at 논리 삭제임.
  • tb_sipmon_session_n은 시작·종료 시각, 두 개인 기준의 세션 시점 스냅샷, 시작 요청 키·fingerprint, 종료 요청 키, revision, deleted_at을 저장함. ended_at IS NULL 부분 고유 인덱스로 사용자별 진행 중 세션 하나를 강제함. 세션 삭제는 종료된 세션에서만 허용하고, 연결된 활성 잔 기록과 세션의 deleted_at을 한 트랜잭션에서 설정함. 목록·상세·현재 세션은 삭제된 세션을 제외하며, 같은 삭제 요청의 반복은 동일 결과를 반환함.
  • tb_sipmon_record_n은 세션 FK, 주류 FK, 주류·분류명 및 아이콘 스냅샷, mL·도수·잔 수·순수 알코올 g, 기록 시각, 요청 키·fingerprint, revision, deleted_at을 저장함. 과거 주류가 삭제·변경되어도 음주 기록의 스냅샷은 유지함. 잔 기록 취소·삭제도 논리 삭제이며 요청 키는 재사용하지 않음.
  • 순수 알코올 g는 mL × 도수(%) × 잔 수 × 0.00789를 Python Decimal로 계산해 문자열로 보존함. 평균 음주 속도는 경과 30분 이후에 계산하고, 두 게이지는 세션 스냅샷의 개인 기준 대비 지표임. 안전도·취기를 예측하지 않음. 업무 시각은 KST 기준임.

4. API와 화면 진입​

  • GET /bootstrap, POST /initialize, PUT /settings는 초기 목록과 비교 기준을 관리함. 분류·주류는 GET/POST /categories, GET/POST /drinks, PUT/DELETE /categories/{key}, PUT/DELETE /drinks/{key}로 관리함. 사용 중인 분류 삭제는 거절함.
  • POST /sessions는 요청 키로 시작하며 GET /sessions/current는 현재 세션을, GET /sessions?offset=은 종료된 세션 20개씩과 각 세션의 경과 초·누적 순수 알코올량·30분 이후 평균 속도를, GET /sessions/{key}는 상세를 반환함.
    • POST /sessions/{key}/end는 종료 요청 키와 revision을 사용함.
    • POST /sessions/{key}/resume은 소유자의 종료 세션을 revision으로 확인하고 진행 중인 다른 세션이 없을 때 ended_at과 종료 요청 키를 비워 다시 진행 중 상태로 만듦. 기존 시작 시각·잔 기록·개인 기준 스냅샷은 유지함.
    • 같은 revision의 재개 요청이 이미 적용된 상태에서는 현재 세션을 반환하며, 소유권·revision·진행 중 세션 충돌은 거절함.
  • POST /sessions/{key}/records는 잔 기록 요청 키·주류 revision·세션 revision을 확인함.
    • PUT/DELETE /records/{key}는 잔 기록 수정·취소에 사용함.
    • 종료 세션의 잔 추가는 correction 표시와 세션 종료 시각을 사용하며 이후 잔 기록 수정 API로 시각을 정정함.
    • PUT /sessions/{key}/times는 진행 중 세션의 시작 시각 또는 종료 세션의 시작·종료 시각을 정정함.
    • offset 포함 시각을 KST로 변환하고, 현재·종료 상태 일치, 현재 시각 및 활성 잔 기록의 시간 범위를 검사함.
    • DELETE /sessions/{key}?revision=은 종료 세션 전체 삭제임.
    • GET /record-requests/{request_id}는 응답 유실 뒤 기록 요청 결과를 확인함.
  • 쓰기 API는 BEGIN IMMEDIATE로 SQLite 쓰기를 직렬화하고 성공 응답 전에 commit함. 실패 시 rollback함. 사용자 소유권, revision, 시간 범위, 요청 키 fingerprint를 검사하며 중복 재시도로 잔 기록을 중복 생성하지 않음.

5. 검증​

  • 로컬 비컨테이너 실행과 운영 컨테이너는 동일한 호스트 파일 /sorc001/junkbox/db/sipmon.sqlite3을 사용함. 컨테이너에는 /sorc001/junkbox/db:/app/db를 마운트하고 SIPMON_DATABASE_URL=sqlite+aiosqlite:////app/db/sipmon.sqlite3을 설정함. 로컬 비컨테이너 기본 DSN은 sqlite+aiosqlite:////sorc001/junkbox/db/sipmon.sqlite3임. 자동 테스트는 별도 임시 SQLite를 사용함.
  • 앱 lifespan은 스키마를 자동 생성·마이그레이션하지 않고 설정 테이블과 세션의 deleted_at 컬럼 존재를 확인함. 신규 설치 스키마는 ai-outputs/sipmon/schema.sql, 기존 세션 테이블의 deleted_at 추가용 수동 SQL은 ai-outputs/sipmon/session-delete-migration.sql에 있음. 앱 기동 전에 스키마를 적용해야 함.
  • API 검증은 uv run --no-sync python -m unittest discover -s apps/sipmon-api/tests -q를 사용함. SQLite 임시 DB에서 소유권, revision, 중복 요청, 시간 경계, 삭제와 rollback을 확인함.