# Milestone: 일별 Usage 비용/ROI 리포트 MVP

## 위치

- Roadmap: [ROADMAP.md](../../../../ROADMAP.md)
- Phase: [PHASE.md](../../../../phase/operational-observability-provider-management/PHASE.md)

## 목표

이미 수집되는 OpenAI-compatible token usage metric을 바탕으로, 운영자가 일별로 누가 어디서 token을 얼마나 썼고 그 사용량을 클라우드 모델 가격 기준으로 환산하면 어느 정도 비용이었는지 빠르게 볼 수 있게 한다.
1차 목표는 request-level ledger나 상세 실행 로그가 아니라 daily/monthly rollup과 cloud-equivalent cost/avoided-cost 관점의 ROI 판단이다.
클라우드 가격은 런타임이 자동으로 최신값을 가져오지 않고, 운영자가 기준 모델, 단가, 기준일을 명시한 baseline으로 관리한다.
사용자 한 명이 여러 앱/통합을 운영하는 일반 API usage 구조를 전제로, 같은 `principal_ref` 아래 여러 `token_ref`를 발급하고 `token_ref`별 사용량을 분해해 볼 수 있어야 한다.

## 상태

[완료]

## 승격 조건

- 없음: urgent 운영 니즈가 daily token usage, 사용 위치별 breakdown, cloud-equivalent cost, ROI 판단용 rollup으로 좁혀졌고 request-level ledger와 qualification report는 후속으로 유지한다.

## 구현 잠금

- 상태: 해제
- SDD: 불필요
- SDD 사유: 기존 OpenAI-compatible usage metric과 Grafana/query 문서를 얇게 확장하는 작은 리포트 Milestone이다. 새 API/proto/runtime wire, 저장소 schema, 권한 모델, request-level ledger를 확정하지 않는다.
- 결정 필요: 없음

## 범위

- 일별/월별 token usage rollup query와 dashboard/report 기준
- `principal_ref`, `principal_alias`, `token_ref`, `model_group`, `endpoint`, `response_mode`, `token_type` 기준 breakdown
- 같은 `principal_ref` 아래 여러 앱/통합 token이 있을 때 사용자 합산과 token/app별 분해를 함께 보는 기준
- 운영자가 관리하는 cloud price baseline 기준
- input/output/cached/reasoning token type별 cloud-equivalent cost 산식
- IOP/local/provider 사용량을 cloud baseline으로 환산한 avoided-cost 또는 ROI 판단용 요약
- Grafana query 또는 문서화된 조회 절차를 1차 표면으로 사용

## 기능

### Epic: [usage-roi] Daily Usage Cost and ROI

운영자가 현재 필요한 수준의 비용/ROI 판단을 request-level ledger 없이 빠르게 볼 수 있는 usage rollup capability를 묶는다.

- [x] [daily-rollup] `iop_openai_usage_tokens_total` 기준 일별/월별 token rollup query가 principal/token/model/endpoint/token_type별로 정리되어 있다.
- [x] [multi-token-principal] 한 `principal_ref`에 여러 앱/통합별 `token_ref`를 발급하고, 사용자 합산과 token/app별 breakdown을 동시에 볼 수 있는 전제가 코드/계약/운영 skill 기준으로 확인되어 있다.
- [x] [usage-origin] "어디서 얼만큼 사용했는지"를 `principal_alias`, `token_ref`, `model_group`, `endpoint`, `response_mode` 기준으로 볼 수 있는 breakdown이 정리되어 있다.
- [x] [price-baseline] cloud-equivalent cost 계산에 사용할 price baseline 필드가 정리되어 있다. 최소 필드는 cloud provider/model, token type, price per token 또는 per 1M tokens, currency, effective date다.
- [x] [cost-formula] token type별 사용량에 price baseline을 곱해 daily/monthly cloud-equivalent cost를 계산하는 산식과 query/report 예시가 정리되어 있다.
- [x] [roi-summary] IOP/local/provider 사용량을 cloud baseline으로 환산한 avoided-cost 또는 ROI 판단용 summary가 정리되어 있다. 실제 billing, chargeback, infra cost accounting은 후속 범위로 둔다.
- [x] [grafana-report] Grafana dashboard/query 또는 문서 표면에서 daily usage, usage origin, cloud-equivalent cost, ROI summary를 확인하는 절차가 정리되어 있다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-07-10
- 완료 근거:
  - [openai-usage-grafana.md](../../../../../docs/openai-usage-grafana.md)에 principal/token/model/endpoint/response_mode/token_type 기준 daily/monthly rollup, usage origin breakdown, Grafana report 절차를 정리했다.
  - [openai-usage-grafana.md](../../../../../docs/openai-usage-grafana.md)에 operator-managed cloud price baseline 필드, token type별 cost 산식, cloud-equivalent avoided-cost ROI summary 기준을 정리했다.
  - multi-token principal 전제는 `apps/edge/internal/openai/identity_metering_test.go`, `packages/go/config/config_test.go`, `agent-contract/inner/edge-config-runtime-refresh.md`, `agent-ops/skills/project/openai-usage-token-issue/SKILL.md`의 현재 변경으로 확인했다.
  - Spec sync: [openai-compatible-surface.md](../../../../../agent-spec/input/openai-compatible-surface.md)에 daily/monthly rollup, usage origin, cloud-equivalent cost, avoided-cost ROI 문서 표면을 반영했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-07-10 종료 검토에서 기능 Task, 구현 잠금, SDD gate, code/spec evidence, local 검증이 충족되어 완료 archive로 이동했다.

## 범위 제외

- request-level ledger 저장소, 요청별 상세 감사/디버깅 조회
- prompt/response/reasoning preview 저장, redaction, retention 정책
- Control Plane 또는 Client usage dashboard 구현
- live cloud pricing API 연동 또는 최신 가격 자동 동기화
- 실제 결제, chargeback, 조직별 비용 배부, full infra cost accounting
- 사용자별 token 제한 warn/reject enforcement
- provider/device/model qualification report

## 작업 컨텍스트

- 관련 경로: `docs/openai-usage-grafana.md`, `apps/edge/internal/openai/usage_metrics.go`, `apps/edge/internal/openai/usage_metrics_test.go`, [openai-compatible-api.md](../../../../../agent-contract/outer/openai-compatible-api.md)
- 표준선(선택): source metric은 기존 `iop_openai_usage_tokens_total`과 `iop_openai_requests_total`을 우선 사용한다.
- 표준선(선택): `principal_ref`는 사용자/테넌트 참조값이고, `token_ref`는 앱/통합/용도별 API token 식별자다. 같은 `principal_ref`에 여러 `token_ref`를 허용한다.
- 표준선(선택): cloud price baseline은 운영자가 명시한 정적 기준값이며, 가격 기준일과 모델명을 함께 표시한다.
- 표준선(선택): ROI는 1차에서 "cloud equivalent avoided cost" 수준으로 표현하고, 실제 인프라 비용과 billing-grade ROI는 후속으로 둔다.
- 선행 작업: 사용자별 OpenAI-compatible 토큰 측정 MVP
- 후속 작업: 요청 실행 로그와 Usage Ledger 기반, 사용자별 token 제한 enforcement, 운영 리포트
- 확인 필요: 없음
