본문으로 건너뛰기

Pack 1 운영 지표 (docgen · 사무실 기억 참조)

ADR 0012 S1 후속. Pack 1 회수 유형 + 한글 export + 사무실 기억 참조 기능의 운영 관측 지표 인벤토리.

집계 스크립트 → 테넌트별 tenantDoc.stats.* 네임스페이스 → 관리자 콘솔 대시보드 쿼리 경로.

1. 서류 생성 (docgen)​

1.1 원본 이벤트​

  • 컬렉션: tenants/{tid}/docgenEvents/*
  • Writer: writeDocgenEvent (apps/web/app/(workspace)/docs/_lib/docgen-event-writer.ts)
  • Zod 스키마: DocgenEventSchema (성공·실패 discriminator)
  • 기록 경로 3 종: 성공 · 실패 (failureReason) · kill switch

1.2 집계 스크립트​

  • 파일: scripts/aggregate-docgen-stats.ts
  • 윈도우: 최근 30일 롤링
  • 쓰기 경로: tenants/{tid}.stats.docgen.*
  • 실행: NODE_PATH=apps/web/node_modules npx tsx scripts/aggregate-docgen-stats.ts [--dry-run]

1.3 집계 필드​

필드단위의미
totalSuccess건수성공 누적
totalFailure건수실패 누적 (kill switch 포함)
avgElapsedMsms렌더 시간 평균
failureBreakdown{reason: count}failureReason 분포
kindBreakdown{kind: count}DocKind 별 사용
templateSource.{tenant, public}건수커스텀 vs 공용 템플릿 비율
lastAggregatedAtIsoISO-8601마지막 집계 시각

1.4 관측 목표​

지표경보 임계값원인 후보
failureBreakdown.template_invalid > totalSuccess * 0.055% 초과공용 템플릿 회귀 또는 tenant 업로드 파일 파손
failureBreakdown.render_failed > totalSuccess * 0.011% 초과docx-templates 버전 드리프트, placeholder 규약 변경
avgElapsedMs > 30003초 초과템플릿 크기 급증 또는 Storage 지연
templateSource.tenant / (tenant+public) > 0.550% 초과공용 템플릿 품질 부족 → tenant 커스텀 의존 과다

2. 사무실 기억 참조 (RelatedMemoriesPanel)​

2.1 원본 이벤트​

  • 컬렉션: tenants/{tid}/relatedMemoriesEvents/*
  • Writer: writeRelatedMemoriesEventAction (서버 측 tenantId·actorUid 덮어쓰기)
  • Zod 스키마: RelatedMemoriesEventSchema (discriminated union 3 종)

2.2 집계 스크립트​

  • 파일: scripts/aggregate-related-memories-stats.ts
  • 윈도우: 최근 30일 롤링
  • 쓰기 경로: tenants/{tid}.stats.relatedMemories.*

2.3 집계 필드​

필드단위의미
shownCount건수패널 카드 실제 렌더 횟수
clickedCount건수"이 기억 반영" CTA 클릭
cancelCount건수로딩 완료 전 Step 2 이탈
clickThroughRate비율clicked / shown
cancelRate비율cancel / (shown + cancel)
avgFetchMsmsfindRelatedMemoriesForDocGenAction 평균 응답
rankIndexHistogram{0..4: count}상단/하단 편향 관찰
lastAggregatedAtIsoISO-8601마지막 집계 시각

2.4 S3 말 C 캐시 재평가 임계값 (ADR 0012 R1 확정)​

3 조건 모두 충족 시 24h TTL 캐시 (경로 tenants/{tid}/relatedMemoriesCache/{caseHash}_{docType}) 도입:

  • clickThroughRate ≥ 0.40 (hit rate 검증)
  • 월 평균 weight 소비 ≥ 20/tenant (캐시 절감 가치 존재)
  • cancelRate ≥ 0.25 (낭비 방어 의미)

3. 시효 상태 (StatuteBadge)​

순수 함수 계산 → 텔레메트리 없음. 관측 필요 시 CaseSummaryCards 의 임박 배지 렌더 이벤트를 activityLog 에 기록하는 쪽이 단순.

현 상태: 별도 집계 없음. calculateStatuteOfLimitations 가 결정론적이라 사건 단위로 렌더 시 재계산.

4. 후속 작업​

자동 집계​

  • Cloud Scheduler + Cloud Functions 트리거로 aggregate-*.ts 하루 1회 실행
  • 대상: 모든 tenant, 30일 윈도우
  • 알림: 1.4 · 2.4 임계값 초과 시 Slack/이메일

관리자 콘솔 대시보드​

  • tenantDoc.stats.docgen / stats.relatedMemories 읽기 전용 카드
  • 테넌트별 드릴다운 → failureBreakdown · rankIndexHistogram 상세

BQ Export​

  • createdAt serverTimestamp 기반 파티셔닝
  • 장기 분석 (연간 리텐션, 템플릿 A/B) 은 BQ 경로