@tipp/ui 2.8.0 → 2.10.0

package/src/app/roleplay/utils/report-parse.ts

@@ -0,0 +1,443 @@
+// 롤플레잉 평가 리포트(reportData) 제네릭 파서.
+//
+// 보고서 타입(reportType)은 계속 추가되며 그때마다 프론트를 수정할 수 없다.
+// 따라서 프레임워크명 분기 없이 reportData 의 "키 패턴"만으로 해석한다.
+//
+// 입력 형태(프레임워크 공통, outputSchema 실측):
+//   reportData = { output_text: { todayDate, summary, {name}_items:[{...}], skills:[{...}],
+//                                 comprehensive_analysis? }, ai_traininglog_id }
+//   - {name}_items[0] 안에 모든 단계가 `${step}_score|_basis|_issue|_improve|_example|_quality` 평면 필드로 존재
+//   - 단계 라벨은 guideline.value[i].title (길이 일치 가드, 없으면 키 humanize 폴백)
+
+/* ───────────────────────── 출력 타입 ───────────────────────── */
+
+const QUALITIES = ['충족', '부분충족', '미흡'] as const;
+export type RpQuality = (typeof QUALITIES)[number];
+
+export interface RpReportStep {
+  key: string; // 단계 prefix (예: 'own', 'nurturing_org')
+  label: string; // displayMeta.steps.displayName → guideline 제목 → humanize 된 키
+  initial: string | null; // displayMeta.steps.initial. 없으면 null → session-utils stepCode 휴리스틱 폴백
+  description: string | null; // displayMeta.steps.description → guideline 단계 설명
+  idealExample: string | null; // guideline 모범 예시(있을 때)
+  score: number | null;
+  maxScore: number | null; // 신버전 리포트만 제공(구버전은 null) → 있으면 score/maxScore 표시
+  quality: RpQuality | null; // 표준 등급(충족/부분충족/미흡)일 때만. 색·정규화 비율 산출용
+  qualityLabel: string | null; // 원문 등급 문자열 그대로(예: 'X 매우 미흡'). 표시용
+  basis: string | null;
+  issue: string | null;
+  improve: string | null;
+  example: string | null; // reportData 의 단계별 예시 스크립트
+}
+
+export interface RpReportAnalysisItem {
+  title: string;
+  detail: string;
+}
+
+export interface RpReportSkill {
+  title: string;
+  description: string;
+  example: string;
+}
+
+export interface RpReport {
+  frameworkTitle: string | null; // displayMeta.title — 프레임워크 제목(지표와 별개). 없으면 null
+  frameworkDescription: string | null; // displayMeta.description — 프레임워크 설명문. 없으면 null
+  todayDate: string | null;
+  totalScore: number | null;
+  comment: string | null;
+  deduction: { score: number; basis: string } | null;
+  strengths: RpReportAnalysisItem[];
+  improvements: RpReportAnalysisItem[];
+  steps: RpReportStep[];
+  skills: RpReportSkill[];
+}
+
+/* ───────────────────────── displayMeta (framework 표시 메타) ───────────────────────── */
+
+// framework.displayMeta = { title?, description?, steps:[{order,key,initial,displayName,maxValue,description}] }
+// title/description은 프레임워크 자체(지표와 별개). steps는 지표별 표시 메타.
+// 없거나 형식 불일치면 폴백(기존 동작).
+export interface RpDisplayMetaStep {
+  order: number;
+  key: string; // = outputSchema {prefix}_score 의 prefix
+  initial: string;
+  displayName: string;
+  maxValue: number;
+  description: string;
+}
+
+export interface RpDisplayMeta {
+  title?: string;
+  description?: string;
+  steps: RpDisplayMetaStep[];
+}
+
+/* ───────────────────────── 원시 헬퍼 ───────────────────────── */
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// Array.isArray 는 any[] 로 좁혀 unsafe 접근을 유발한다. unknown[] 로 좁히는 가드.
+function isUnknownArray(v: unknown): v is unknown[] {
+  return Array.isArray(v);
+}
+
+function asString(v: unknown): string | null {
+  if (typeof v !== 'string') return null;
+  const t = v.trim();
+  return t.length > 0 ? t : null;
+}
+
+function asNumber(v: unknown): number | null {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+function asQuality(v: unknown): RpQuality | null {
+  const t = asString(v);
+  if (t === null) return null;
+  return QUALITIES.find((q) => q === t) ?? null;
+}
+
+// guideline 의 example 은 string | string[] 모두 가능. '-' 플레이스홀더는 무시.
+function asGuidelineText(v: unknown): string | null {
+  if (isUnknownArray(v)) {
+    const parts = v
+      .map(asString)
+      .filter((s): s is string => s !== null && s !== '-');
+    return parts.length > 0 ? parts.join('\n') : null;
+  }
+  const t = asString(v);
+  return t !== null && t !== '-' ? t : null;
+}
+
+function humanize(key: string): string {
+  return key
+    .split('_')
+    .filter((p) => p.length > 0)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join(' ');
+}
+
+/* ───────────────────────── 단계 추출 ───────────────────────── */
+
+// ⚠ 순서 중요: 더 긴/구체 suffix를 먼저 둬야 한다.
+// 예) 'action_max_score' 는 '_score'보다 '_max_score' 가 먼저 매칭돼야
+//     prefix='action_max'(오인) 가 아니라 prefix='action', suffix='max_score' 로 잡힌다.
+const STEP_SUFFIXES = [
+  'max_score',
+  'maxscore',
+  'max',
+  'score',
+  'basis',
+  'issue',
+  'improve',
+  'example',
+  'quality',
+] as const;
+type StepSuffix = (typeof STEP_SUFFIXES)[number];
+
+function splitStepKey(
+  key: string
+): { prefix: string; suffix: StepSuffix } | null {
+  for (const suffix of STEP_SUFFIXES) {
+    const tail = `_${suffix}`;
+    if (key.endsWith(tail) && key.length > tail.length) {
+      return { prefix: key.slice(0, -tail.length), suffix };
+    }
+  }
+  return null;
+}
+
+interface GuidelineEntry {
+  title: string | null;
+  description: string | null;
+  example: string | null;
+}
+
+// guideline = { value: [{title, example, description}], version }. 미작성/길이불일치면 빈 배열 취급(=폴백).
+function readGuidelineEntries(guideline: unknown): GuidelineEntry[] {
+  if (!isObject(guideline) || !isUnknownArray(guideline.value)) return [];
+  const entries: GuidelineEntry[] = guideline.value.map((v) => {
+    if (!isObject(v)) return { title: null, description: null, example: null };
+    const title = asString(v.title);
+    return {
+      title: title === '-' ? null : title,
+      description: asGuidelineText(v.description),
+      example: asGuidelineText(v.example),
+    };
+  });
+  // 전부 플레이스홀더면 라벨 소스로 쓰지 않는다.
+  if (entries.every((e) => e.title === null)) return [];
+  return entries;
+}
+
+// reportData item 객체에서 prefix→(suffix→값) 맵과 첫 등장 순서(order)를 만든다.
+function buildFieldsMap(itemObj: Record<string, unknown>): {
+  order: string[];
+  fields: Map<string, Map<StepSuffix, unknown>>;
+} {
+  const order: string[] = [];
+  const fields = new Map<string, Map<StepSuffix, unknown>>();
+
+  for (const [key, value] of Object.entries(itemObj)) {
+    const split = splitStepKey(key);
+    if (!split) continue;
+    if (!fields.has(split.prefix)) {
+      fields.set(split.prefix, new Map());
+      order.push(split.prefix);
+    }
+    fields.get(split.prefix)?.set(split.suffix, value);
+  }
+
+  return { order, fields };
+}
+
+// 단일 단계(step) 조립. 라벨/이니셜/설명/만점은 호출부(displayMeta 또는 폴백)가 결정해 주입.
+function buildStep(
+  key: string,
+  f: Map<StepSuffix, unknown>,
+  meta: {
+    label: string;
+    initial: string | null;
+    description: string | null;
+    idealExample: string | null;
+    maxScoreFallback: number | null; // reportData 에 max 가 없을 때 쓸 만점(displayMeta.maxValue)
+  }
+): RpReportStep {
+  const qualityRaw = f.get('quality');
+  return {
+    key,
+    label: meta.label,
+    initial: meta.initial,
+    description: meta.description,
+    idealExample: meta.idealExample,
+    score: asNumber(f.get('score')),
+    // reportData 의 실제 만점이 우선, 없으면 displayMeta.maxValue 폴백.
+    maxScore:
+      asNumber(f.get('max_score') ?? f.get('maxscore') ?? f.get('max')) ??
+      meta.maxScoreFallback,
+    quality: asQuality(qualityRaw),
+    qualityLabel: asString(qualityRaw),
+    basis: asString(f.get('basis')),
+    issue: asString(f.get('issue')),
+    improve: asString(f.get('improve')),
+    example: asString(f.get('example')),
+  };
+}
+
+function extractSteps(
+  itemObj: Record<string, unknown>,
+  guideline: unknown,
+  displaySteps: RpDisplayMetaStep[]
+): RpReportStep[] {
+  const { order, fields } = buildFieldsMap(itemObj);
+  const entries = readGuidelineEntries(guideline);
+
+  // ── displayMeta.steps 우선: order 정렬된 steps 를 key 로 reportData 필드에 매칭.
+  if (displaySteps.length > 0) {
+    // guideline 의 단계 설명/모범예시 보강은 길이 일치 시에만 인덱스 매핑(기존 가드와 동일 정신).
+    const useGuideline = entries.length === displaySteps.length;
+    return displaySteps.map((ds, i) => {
+      const f = fields.get(ds.key) ?? new Map<StepSuffix, unknown>();
+      const entry = useGuideline ? entries[i] : null;
+      // 지표 설명: displayMeta.steps.description 우선, 없으면 guideline.
+      const dsDescription =
+        ds.description.trim().length > 0 ? ds.description : null;
+      return buildStep(ds.key, f, {
+        label: ds.displayName,
+        initial: ds.initial.trim().length > 0 ? ds.initial : null,
+        description: dsDescription ?? entry?.description ?? null,
+        idealExample: entry?.example ?? null,
+        maxScoreFallback: ds.maxValue > 0 ? ds.maxValue : null,
+      });
+    });
+  }
+
+  // ── 폴백: reportData 키 등장 순서 + guideline 길이일치 인덱스 매칭 + humanize.
+  const useGuideline = entries.length === order.length;
+  return order.map((prefix, i) => {
+    const f = fields.get(prefix) ?? new Map<StepSuffix, unknown>();
+    const entry = useGuideline ? entries[i] : null;
+    return buildStep(prefix, f, {
+      label: entry?.title ?? humanize(prefix),
+      initial: null,
+      description: entry?.description ?? null,
+      idealExample: entry?.example ?? null,
+      maxScoreFallback: null,
+    });
+  });
+}
+
+// framework.displayMeta(unknown) 를 견고하게 정규화.
+// title/description(프레임워크 자체)과 steps(지표 배열)는 독립 — steps 가 비어도 title/description 은 살린다.
+function readDisplayMeta(raw: unknown): {
+  title: string | null;
+  description: string | null;
+  steps: RpDisplayMetaStep[];
+} {
+  if (!isObject(raw)) return { title: null, description: null, steps: [] };
+
+  const steps: RpDisplayMetaStep[] = [];
+  if (isUnknownArray(raw.steps)) {
+    for (const s of raw.steps) {
+      if (!isObject(s)) continue;
+      const key = asString(s.key);
+      if (key === null) continue; // key 없는 항목은 매칭 불가 → 제외
+      steps.push({
+        order: asNumber(s.order) ?? steps.length,
+        key,
+        initial: asString(s.initial) ?? '',
+        displayName: asString(s.displayName) ?? humanize(key),
+        maxValue: asNumber(s.maxValue) ?? 0,
+        description: asString(s.description) ?? '',
+      });
+    }
+    steps.sort((a, b) => a.order - b.order);
+  }
+
+  return {
+    title: asString(raw.title),
+    description: asString(raw.description),
+    steps,
+  };
+}
+
+/* ───────────────────────── 강점/개선점 (numbered-pair 평탄화) ───────────────────────── */
+
+// 객체에서 `${titleBase}${n}` / `${detailBase}${n}` 쌍을 n=1.. 순으로 수집.
+function flattenNumberedPairs(
+  obj: Record<string, unknown>,
+  titleBase: string,
+  detailBase: string
+): RpReportAnalysisItem[] {
+  const out: RpReportAnalysisItem[] = [];
+  for (let n = 1; ; n += 1) {
+    const title = asString(obj[`${titleBase}${n}`]);
+    if (title === null) break;
+    out.push({ title, detail: asString(obj[`${detailBase}${n}`]) ?? '' });
+  }
+  return out;
+}
+
+// 후보 (titleBase, detailBase) 쌍을 순서대로 시도, 첫 매치를 사용. (구·신 스키마 모두 대응)
+const ANALYSIS_PAIR_CANDIDATES: readonly (readonly [string, string])[] = [
+  ['title', 'detail'],
+  ['improvement_title', 'improvement_action'],
+  ['issue_title', 'issue_detail'],
+];
+
+function flattenAnalysis(source: unknown): RpReportAnalysisItem[] {
+  if (!isUnknownArray(source)) return [];
+  const out: RpReportAnalysisItem[] = [];
+  for (const obj of source) {
+    if (!isObject(obj)) continue;
+    for (const [titleBase, detailBase] of ANALYSIS_PAIR_CANDIDATES) {
+      const items = flattenNumberedPairs(obj, titleBase, detailBase);
+      if (items.length > 0) {
+        out.push(...items);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/* ───────────────────────── skills 평탄화 ───────────────────────── */
+
+function flattenSkills(source: unknown): RpReportSkill[] {
+  if (!isUnknownArray(source)) return [];
+  const out: RpReportSkill[] = [];
+  for (const obj of source) {
+    if (!isObject(obj)) continue;
+    for (let n = 1; ; n += 1) {
+      const title = asString(obj[`skill${n}`]);
+      if (title === null) break;
+      out.push({
+        title,
+        description: asString(obj[`description${n}`]) ?? '',
+        example: asString(obj[`example${n}`]) ?? '',
+      });
+    }
+  }
+  return out;
+}
+
+/* ───────────────────────── 종합/감점 ───────────────────────── */
+
+function readDeduction(
+  summary: Record<string, unknown> | null
+): { score: number; basis: string } | null {
+  if (!summary || !isObject(summary.deduction)) return null;
+  const score = asNumber(summary.deduction.score);
+  const basis = asString(summary.deduction.basis);
+  if (score === null || basis === null) return null;
+  return { score, basis };
+}
+
+/* ───────────────────────── 메인 파서 ───────────────────────── */
+
+// airflow 가 output_text 를 dict 로 정규화해 저장하므로(ai_traininglog_request_clova.py),
+// 래퍼는 객체. 래퍼가 없으면(일부 프레임워크) reportData 자체를 루트로 사용.
+function unwrapOutputText(reportData: unknown): Record<string, unknown> {
+  if (!isObject(reportData)) return {};
+  return isObject(reportData.output_text) ? reportData.output_text : reportData;
+}
+
+function findItemsArray(
+  root: Record<string, unknown>
+): Record<string, unknown> | null {
+  for (const [key, value] of Object.entries(root)) {
+    if (!key.endsWith('_items') || !isUnknownArray(value)) continue;
+    const first = value[0];
+    if (isObject(first)) return first;
+  }
+  return null;
+}
+
+export function parseReportData(
+  reportData: unknown,
+  guideline: unknown,
+  displayMeta?: unknown
+): RpReport {
+  const root = unwrapOutputText(reportData);
+  const meta = readDisplayMeta(displayMeta);
+
+  const summary = isObject(root.summary) ? root.summary : null;
+  const comprehensive = isObject(root.comprehensive_analysis)
+    ? root.comprehensive_analysis
+    : null;
+
+  // 종합 코멘트: 신(comprehensive_analysis) → 구(summary) 순.
+  const comment =
+    asString(comprehensive?.comment) ??
+    asString(summary?.comment) ??
+    asString(summary?.basis);
+
+  // 강점: comprehensive_analysis.strengths(신) → summary.good_point(구)
+  const strengths = flattenAnalysis(
+    comprehensive?.strengths ?? summary?.good_point
+  );
+  // 개선점: comprehensive_analysis.improvements(신) → summary.improvement(구)
+  const improvements = flattenAnalysis(
+    comprehensive?.improvements ?? summary?.improvement
+  );
+
+  const itemObj = findItemsArray(root);
+  const steps = itemObj ? extractSteps(itemObj, guideline, meta.steps) : [];
+
+  return {
+    frameworkTitle: meta.title,
+    frameworkDescription: meta.description,
+    todayDate: asString(root.todayDate),
+    totalScore: asNumber(summary?.total_score),
+    comment,
+    deduction: readDeduction(summary),
+    strengths,
+    improvements,
+    steps,
+    skills: flattenSkills(root.skills),
+  };
+}

package/src/app/roleplay/utils/session-utils.ts

@@ -0,0 +1,215 @@
+// 롤플레잉 세션 상세 순수 유틸 함수 모음.
+// 원본: website/src/modules/customer/roleplay/pages/RpSessionDetail/RpSessionDetail.tsx
+// 'use client' 없음 — 순수 함수, 클라이언트 전용 아님.
+
+import { format } from 'date-fns';
+import type { RpSessionScriptLine } from '../types';
+import type { RpQuality, RpReportStep } from './report-parse';
+
+/* ───────────────────────── 타입 ───────────────────────── */
+
+export interface SpeechShare { userPct: number; partnerPct: number }
+
+export type QColor = 'green' | 'amber' | 'red' | 'gray';
+
+/* ───────────────────────── 색 변수 ───────────────────────── */
+
+export const COLOR_VARS: Record<QColor, { fg: string; bg: string; border: string }> = {
+  green: {
+    fg: 'var(--green-11)',
+    bg: 'var(--green-a3)',
+    border: 'var(--green-a6)',
+  },
+  amber: {
+    fg: 'var(--amber-11)',
+    bg: 'var(--amber-a3)',
+    border: 'var(--amber-a6)',
+  },
+  red: { fg: 'var(--red-11)', bg: 'var(--red-a3)', border: 'var(--red-a6)' },
+  gray: { fg: 'var(--gray-9)', bg: 'var(--gray-a3)', border: 'var(--gray-5)' },
+};
+
+/* ───────────────────────── 등급 색 ───────────────────────── */
+
+export function qualityColor(quality: RpQuality | null): QColor {
+  switch (quality) {
+    case '충족':
+      return 'green';
+    case '부분충족':
+      return 'amber';
+    case '미흡':
+      return 'red';
+    default:
+      return 'gray';
+  }
+}
+
+export const QUALITY_RATIO: Record<RpQuality, number> = {
+  충족: 1,
+  부분충족: 0.6,
+  미흡: 0.3,
+} as const;
+
+export function qualityRatio(quality: RpQuality | null): number | null {
+  return quality === null ? null : QUALITY_RATIO[quality];
+}
+
+// 표준 등급이 아닌 자유 등급 문자열에서 색만 키워드로 추정(비율은 산출하지 않음).
+export function gradeColorFromLabel(label: string | null): QColor {
+  if (!label) return 'gray';
+  if (
+    label.includes('미흡') ||
+    label.includes('부족') ||
+    label.includes('미달')
+  )
+    return 'red';
+  if (label.includes('부분') || label.includes('보통')) return 'amber';
+  if (
+    label.includes('충족') ||
+    label.includes('우수') ||
+    label.includes('충분')
+  )
+    return 'green';
+  return 'gray';
+}
+
+/* ───────────────────────── 단계(Step) 헬퍼 ───────────────────────── */
+
+// 단계 색: 표준 등급 우선, 없으면 라벨 키워드 추정.
+export function stepColor(step: RpReportStep): QColor {
+  return step.quality !== null
+    ? qualityColor(step.quality)
+    : gradeColorFromLabel(step.qualityLabel);
+}
+
+export function stepVars(step: RpReportStep): { fg: string; bg: string; border: string } {
+  return COLOR_VARS[stepColor(step)];
+}
+
+// progress/radar 정규화 비율(0~1). score/maxScore 우선, 없으면 표준 등급 비율, 둘 다 없으면 null.
+export function stepRatio(step: RpReportStep): number | null {
+  if (step.maxScore !== null && step.maxScore > 0 && step.score !== null) {
+    return Math.max(0, Math.min(1, step.score / step.maxScore));
+  }
+  return qualityRatio(step.quality);
+}
+
+// 점수 텍스트: max 있으면 'score/max', 없으면 'score', score 없으면 null.
+export function stepScoreText(step: RpReportStep): string | null {
+  if (step.score === null) return null;
+  return step.maxScore !== null
+    ? `${step.score}/${step.maxScore}`
+    : `${step.score}`;
+}
+
+// 표시할 등급 라벨(자유 문자열 포함). 없으면 null.
+export function stepGradeLabel(step: RpReportStep): string | null {
+  return step.qualityLabel;
+}
+
+// 단계에 표시할 평가 정보가 하나라도 있는지(점수 또는 등급).
+export function hasStepSignal(step: RpReportStep): boolean {
+  return step.score !== null || step.qualityLabel !== null;
+}
+
+// radar 축/요약 라벨용 짧은 코드.
+// displayMeta.steps.initial 이 지정돼 있으면 최우선(이니셜 충돌 해소).
+// 없으면 기존 휴리스틱: acronym 프레임워크는 선두 글자, 아니면 키 약식.
+const LETTER_RE = /[A-Za-z]/;
+
+export function stepCode(step: RpReportStep): string {
+  if (step.initial !== null && step.initial.trim().length > 0) {
+    return step.initial.trim();
+  }
+  const label = step.label.trim();
+  const first = label.charAt(0);
+  const second = label.charAt(1);
+  // "O — Opening" / "O - Opening" / "O Opening" 형태
+  if (
+    LETTER_RE.test(first) &&
+    (second === ' ' || second === '—' || second === '-')
+  ) {
+    return first.toUpperCase();
+  }
+  // "[I] Introduction" 형태
+  if (first === '[' && LETTER_RE.test(second) && label.charAt(2) === ']') {
+    return second.toUpperCase();
+  }
+  return step.key.split('_')[0].slice(0, 4).toUpperCase();
+}
+
+/* ───────────────────────── 포맷 유틸 ───────────────────────── */
+
+export function formatDuration(seconds: number | null): string {
+  if (seconds === null) return '—';
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${m}분 ${String(s).padStart(2, '0')}초`;
+}
+
+export function formatDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return format(d, 'M/d HH:mm');
+}
+
+export function formatTimestamp(ms: number): string {
+  const total = Math.floor(ms / 1000);
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return `${m}:${String(s).padStart(2, '0')}`;
+}
+
+/* ───────────────────────── 미디어 싱크 ───────────────────────── */
+
+// 미디어 길이와 STT 길이가 이 비율 이내로 가까우면 싱크(클릭 seek/재생 하이라이트) 활성.
+export const SYNC_TOLERANCE = 0.05;
+
+export function isLengthClose(mediaSec: number | null, sttSec: number): boolean {
+  if (!mediaSec || mediaSec <= 0 || sttSec <= 0) {
+    return false;
+  }
+  return (
+    Math.abs(mediaSec - sttSec) / Math.max(mediaSec, sttSec) <= SYNC_TOLERANCE
+  );
+}
+
+/* ───────────────────────── 발화량 ───────────────────────── */
+
+// 내 발화량이 이 비율을 넘으면 과다 발화로 간주(빨간 막대 + 주의 문구).
+export const SPEECH_OVERTALK_THRESHOLD = 40;
+
+// 화자별 발화량 비율. 기준은 공백·개행 제거 글자 수(실제 말한 양에 근접, 공백 패턴 왜곡 방지).
+// 발화 글자가 전혀 없으면 null → 미표시.
+export function computeSpeechShare(lines: RpSessionScriptLine[]): SpeechShare | null {
+  let userChars = 0;
+  let partnerChars = 0;
+  for (const line of lines) {
+    const count = line.text.replace(/\s/g, '').length;
+    if (line.speaker === 'user') {
+      userChars += count;
+    } else {
+      partnerChars += count;
+    }
+  }
+  const total = userChars + partnerChars;
+  if (total === 0) {
+    return null;
+  }
+  const userPct = Math.round((userChars / total) * 100);
+  return { userPct, partnerPct: 100 - userPct };
+}
+
+/* ───────────────────────── 세션 상태 ───────────────────────── */
+
+const STATUS_LABEL: Record<string, string> = {
+  complete: '분석 완료',
+  completed: '분석 완료',
+  analyzing: 'AI 분석 중',
+  partial: '일부 산출물 없음',
+};
+
+export function statusLabelOf(status: string | null): string {
+  if (!status) return '세션';
+  return STATUS_LABEL[status] ?? status;
+}