공지사항

v1.0.0-rc.20 릴리스 노트

기간 2026-08-27 ~ 09-10 · 커밋 9개 (release/v1.0.0-rc.19..release/v1.0.0-rc.20)

핵심은 모니터링 서버 연동 API 신설과 보안 검토 조치입니다. 마이그레이션 3건이 포함되므로 배포 시 alembic upgrade head가 필요합니다.

모니터링 서버가 서비스별 손익(수익)을 집계할 수 있도록 커서 기반 증분 피드를 추가했습니다. 언제 호출하든 "지난번 이후 바뀐 것만" 받아 갑니다.

엔드포인트	내용
`GET /api/v1/metrics/sync`	일자×서비스×요금제 매출/환불/실패 집계 + 구독 흐름(신규·취소·정지·만료·재개·변경·갱신)
`GET /api/v1/metrics/subscriptions`	현재 시점 구독 스냅샷(활성 구독수, MRR)
`GET /api/v1/metrics/payments`	결제 건별 피드
`GET /api/v1/metrics/subscription-list`	구독 건별 피드

커서 방식 — 응답의 next_cursor를 저장했다가 다음 호출에 그대로 전달. 지연 반영(30초)·재집계로 누락 없이 수렴하며, 중복 수신은 UPSERT로 흡수.
전용 키 스코프 — 서비스에 metrics_scope를 켠 키만 호출 가능. 일반 결제 API 키와 상호 배타(양방향 403)라 모니터링 키로 결제를 호출할 수 없습니다.
호출 정책 — 정시 4회(00·06·12·18 KST) + 수동 새로고침 버튼 상정. 분당 30회 한도.
어드민 → 서비스 상세에 "모니터링 전용 키" 카드 추가(스코프 on/off, 감사 로그 기록).

외부 AppSec 관점 검토(위험 1 · 경고 6)의 조치 결과입니다.

개인정보 마스킹 — 건별 피드의 고객 이메일을 기본 미노출로 바꾸고, 서비스별 키드 해시 user_ref(24자)로 대체. 원문이 필요하면 어드민에서 "이메일 원문 포함"을 별도로 켜야 하며 조회가 감사 로그에 남습니다.
커서 서명 — 커서에 HMAC 서명을 붙여 변조·손상 시 422. 환경(dev/운영) 간 커서 혼용도 차단.
접근 제한 — 모니터링 키는 허용 IP가 등록된 경우에만 원격 호출 가능(운영·스테이징에서는 IP 없이 스코프를 켤 수 없음).
의존성 정리 — 이미지에 불필요하던 django·requests를 샘플 전용 그룹으로 분리.
취약점 스캔 도입 — scripts/audit_deps.sh가 배포(stg.sh/prod.sh) 전과 GitHub Actions(변경 시 + 주 1회)에서 실행. 첫 실행에서 실제 취약점 10건을 발견해 cryptography 50.0.1 / starlette 1.6.0 / fastapi 0.141.1 / pydantic-settings 2.15.0 으로 상향했습니다. 배포 호스트에 uv가 없으면 Docker로 자동 대체 실행.

실 서비스명(real_service_name) 신설 — 등록용 서비스명(name)과 별개로 대외 제품명을 관리. 대시보드·정산·결제/구독 목록·내보내기가 실 서비스명 기준으로 표시·집계됩니다.
서비스명·서비스 구독명 수정 차단 — 등록 후 변경 불가(집계 기준이 흔들리지 않도록). 상세 화면의 기본 정보 카드는 한 줄 요약 형태로 재구성.

메일 환경 표기 — dev/stg/test에서 발송되는 메일 제목에 [DEV]·[STG] 태그와 안내 문구를 자동 부착(운영 메일은 변경 없음). 테스트 메일이 실제 안내로 오인되는 것을 방지.
운영에서 배포 버전 숨김 — environment=prod면 어드민 사이드바의 배포 공지(버전) 표기를 노출하지 않음.

alembic upgrade head — 추가 마이그레이션 3건(real_service_name, metrics_scope + 인덱스, metrics_pii_scope). 인덱스는 CONCURRENTLY라 서비스 중단 없음.
모니터링 서버에 전달할 키는 모니터링 전용 키로 신규 발급하고, 모니터링 서버의 아웃바운드 IP를 허용 목록에 등록.
의존성이 올라갔으므로 이미지 재빌드 필요(./stg.sh / ./prod.sh).

연동 문서 사용자 매뉴얼 22장 "모니터링 동기화 가이드", 13장 "서비스 API"(§13.1 키 스코프, §13.10 메트릭).