파트너 대시보드 집계 지표 및 스냅샷 통합

ADR-290 파트너 대시보드 집계 지표 및 스냅샷 통합

1. Metadata

• ADR ID: ADR-290
• Status: draft
• Date: 2026-03-11
• Owner: YSY

2. Domain Decision

1. 파트너 대시보드 지표는 현황 지표와 기간추이 지표로 분리한다.
2. 현황 지표의 기준 시점은 실시간이 아니라 전일 마감 스냅샷으로 고정한다.
3. 기간추이 지표는 partner_metrics_daily 테이블의 일 단위 스냅샷을 SoT로 사용한다.
4. partner_metrics_daily는 (partner_id, metric_date) 유니크 키를 강제한다.
5. 파트너 1명당 일자별 최대 1행만 허용한다.
6. 기간추이 지표는 절대값(stock)과 증감값(flow)을 함께 제공한다.

3. Product Decision

1. 현황 영역은 전일 기준으로 운영 중 슬롯 건수, 당일 시작 슬롯 건수, 예약 건수, 사용 완료 건수, 관심매장 등록 수를 제공한다.
2. 운영 중 슬롯 건수는 active_slot_count를 표시하며, 전일 마감 시점에도 열린 슬롯 row 수를 의미한다.
3. 당일 시작 슬롯 건수는 issued_slot_count를 표시하며, metric_date 구간에 start_at이 속한 슬롯 row 수를 의미한다.
4. 슬롯 건수와 수량을 혼용하지 않는다. 슬롯 건수는 count(slots.id), 수량은 sum(total_quantity) 또는 sum(remaining_quantity)를 뜻한다.
5. 쿠폰은 코드형 쿠폰 엔티티에만 사용하고 슬롯 수량이나 슬롯 건수를 지칭하는 용어로 사용하지 않는다.
6. 기간추이 영역은 기본 최근 7일을 제공하고 30일/90일 확장 옵션을 제공한다.
7. 기간추이에는 지표별 절대값과 전일 대비 증감값을 동시에 표시한다.
8. 집계 지연/누락 시 0으로 대체하지 않고 집계 지연 상태를 노출한다.
9. 관심매장 등록 수는 현황에서는 전일 기준 값, 추이에서는 일자별 절대값과 증감값으로 제공한다.

4. UX Decision

1. 대시보드는 현황 카드와 기간추이 차트를 분리 배치한다.
2. 현황 카드에는 기준: 전일(YYYY-MM-DD) 라벨을 명시한다.
3. 기간추이 차트는 절대값 라인과 증감값 막대를 동시 표시하는 혼합형을 기본으로 한다.
4. 차트는 최소 7일/30일/90일 범위 전환을 제공한다.
5. 데이터 누락 구간은 빈값/경고 배지로 표시하고 정상값처럼 렌더링하지 않는다.

5. Tech Decision

1. partner_metrics_daily 테이블을 추가하고 기본 키를 (partner_id, metric_date)로 고정한다.
2. 일별 집계 함수 refresh_partner_metrics_daily(p_metric_date date)를 제공한다.
3. 집계 함수는 insert ... on conflict ... do update로 멱등 구현한다.
4. 스케줄러는 pg_cron으로 하루 1회 실행한다.
5. 기본 실행 시각은 01:05(전일 데이터 확정 이후)로 고정한다.
6. 기간추이 증감값은 저장 컬럼 또는 조회 시 계산식 중 하나로 일관되게 구현한다.
7. 파트너명은 partners 조인으로 보강하고 집계 테이블에는 partner_id만 저장한다.

6. Ops Decision

1. 일별 집계 잡의 성공/실패/지연을 모니터링한다.
2. 특정 일자 재집계(재처리) 런북을 운영한다.
3. 월 단위 백필(backfill) 절차와 권한을 문서화한다.
4. 집계 테이블 행 수/용량 증가를 주기 점검한다.

7. Implementation Contract (Optional)

7.1 API Contract

• 파트너 대시보드 API는 p_partner_id, p_from, p_to를 입력으로 받는다.
• 현황 값은 전일(current_date - 1) 기준으로 반환한다.
• 기간추이 값은 partner_metrics_daily 기준으로 반환한다.

7.2 Data Contract

• partner_metrics_daily 기본 키는 (partner_id, metric_date)로 고정한다.
• metric_date는 Asia/Seoul 일 경계 기준으로 기록한다.
• active_slot_count는 status = 'issued'이면서 전일 마감 시점에도 열린 슬롯 row 수를 저장한다.
• issued_slot_count는 metric_date 구간에 start_at이 속한 슬롯 row 수를 저장한다.
• 슬롯 수량 지표를 추가할 때는 supply_quantity, remaining_quantity, redeemed_quantity처럼 수량임이 드러나는 이름을 사용한다.
• 코드형 쿠폰 지표는 coupon 접두어/접미어를 사용하고, 슬롯 수량 지표에는 coupon 용어를 사용하지 않는다.
• 기간추이 응답은 절대값 필드와 증감값 필드를 모두 포함한다.

7.3 Error/Observability Contract

• 집계 잡 실행 이벤트에 job_name, metric_date, updated_rows, duration_ms, status를 기록한다.
• 대시보드 응답에는 is_stale 또는 동등한 상태 필드를 포함한다.

7.4 Test/Acceptance Contract

• 파트너 1000명 기준 집계 실행 시 해당 일자 행이 약 1000행 생성되어야 한다.
• 동일 일자 재실행 시 중복 행이 생성되지 않아야 한다.
• 집계 지연 시 UI가 0을 정상값처럼 표기하지 않아야 한다.
• 기간추이에서 절대값과 증감값이 함께 노출되어야 한다.
• 기간추이 차트가 7일/30일/90일 전환에서 정상 동작해야 한다.

8. Validation

• Domain/Product/UX/Tech/Ops 결정이 충돌하지 않는다.
• 전일 기준 현황 정책과 일별 집계 정책이 정합하다.
• 절대값/증감값 동시 제공 정책이 API와 UI에서 일관되다.
• 슬롯 건수/수량/쿠폰 용어가 UI, ADR, DB contract에서 일관되다.

Buy me a coffee