---
title: "작업보고 — 코치노트 AI RC2 spec06 프론트 UX (AI 코치 대화 UI·사용량·차감 연결)"
category: "workreport"
document_type: "작업보고"
source_status: "generated"
knowledge_group: "03_history"
priority: "High"
purpose: "코치노트 AI v1.0-rc2 6분할 중 마지막(6/6) 프론트 UX 구현 기록. 내부 엔진(spec01~05: 주입·가드레일·프롬프트·저장·플랜/사용량)을 사용자가 쓰는 멀티턴 'AI 코치 대화' 화면으로 연결. /coach 기본 서브탭=AI 코치 대화(멀티턴)·보조=AI 브리프(기존 보존). 응답 성공 직후에만 차감(실패 무차감)·정수 회 표시·storageGate OFF·연장은 결제 Phase 전용. build 통과 + MCP 5화면 검증. chat-proxy 미배포로 AI 실응답은 graceful 대기로 구현(배포 시 자동 연동)."
read_when: ["최신상태복구","코치노트AI","프론트UX","사용량표시·차감","RC2종료"]
updated: "2026-06-06"
work_timestamp: "20260606_180731"
context: "달록본레포CC (D:\\dallog\\dallog_git) — spec06 구현 스레드"
source_of_truth: "https://dallog-tools.hansbridge.co.kr/knowledge/"
---

# 작업보고 — 코치노트 AI RC2 spec06 프론트 UX

> RC2 6분할 중 **마지막(6/6)**. 내부 엔진을 사용자 경험으로 완성한 단계.
> 최종 기준 = 본레포 `docs/go_work` 원본 명세 + `decision_log_rc2`. 본 문서는 그 구현·검증 기록이다.

## 목차
- [0. 문서 정보](#0-문서-정보)
- [용어 병기 (개발어휘 / 한국어)](#용어-병기-개발어휘--한국어)
- [1. 작업 배경](#1-작업-배경)
- [2. 적용 기준](#2-적용-기준)
- [3. 구현 범위](#3-구현-범위)
- [4. 수정·신규 파일](#4-수정신규-파일)
- [5. SQL 적용 여부](#5-sql-적용-여부)
- [6. 빌드 결과](#6-빌드-결과)
- [7. MCP 브라우징 / 기능 검증 결과 (스크린샷)](#7-mcp-브라우징--기능-검증-결과-스크린샷)
- [8. 명세 대비 구현 완료 여부](#8-명세-대비-구현-완료-여부)
- [9. 미구현 / 보류 / 축소 의심 항목](#9-미구현--보류--축소-의심-항목)
- [10. 발견된 이슈](#10-발견된-이슈)
- [11. 후속 작업](#11-후속-작업)
- [12. 최종 판단](#12-최종-판단)
- [13. 작업자 메모 + 결정로그 5요소](#13-작업자-메모--결정로그-5요소)

---

## 0. 문서 정보
- **작성일:** 2026-06-06
- **담당 작업 단위:** spec_rc2_06_frontend_ux (프론트 UX / AI 코치 대화 UI·사용량 표시·턴캡·소진·OWNER 패널 연결)
- **관련 명세서:** `spec_rc2_06_frontend_ux.md`, `spec_rc2_05a_plan_admin_v0.2_260606.md`(§5 표시 워딩·§7 OWNER·§A-3/A-7), `spec_rc2_00_master_index.md`(A절 준수원칙)
- **관련 결정로그:** decision_log_rc2 #7(사용량 상시 노출)·#16(턴 비율 차감)·#4(연장=결제 Phase)
- **관련 스레드:** spec06 구현 스레드. 인계받은 핸드오프 = `handoff_spec05_to_spec06.md`
- **작성 목적:** spec06 담당분을 달록KB에서 추적 가능한 정식 작업보고로 자산화

---

## 용어 병기 (개발어휘 / 한국어)
| 개발어휘 | 한국어 의역 |
|---|---|
| thread | 대화방(세션 식별자) |
| multi-turn / streaming | 멀티턴 대화 / 실시간 응답 |
| consumeTurn | 턴(회) 차감 |
| entitlement | 사용권·잔여 코칭 회 |
| turn cap | 턴캡(한 대화 최대 회) |
| extension(연장) | 캡 초과 강행 턴(할증) |
| billing phase | 결제 Phase(베타/결제) |
| injection / snapshot | 운동기록 주입 / 운동기록 요약본 |
| memory profile | 메모리 프로필(직접 입력 코치 카드) |
| storageGate | 저장 활성화 게이트 |
| system prompt | 시스템 지시문(고정·캐싱 대상) |
| MCP browsing test | MCP 브라우징 테스트(실화면 검증) |
| graceful degradation | 우아한 대기(서버 미가동 시 오류 안내·무차감) |

---

## 1. 작업 배경
코치노트는 기존에 **일회성 "AI 브리프"**(시각 카드 + 수동 메모)만 있었고, 실제 대화형 코치는 없었다. RC2 spec01~05가 내부 엔진(주입·가드레일·프롬프트·저장·플랜/사용량 helper)을 모두 깔아둔 상태였고, spec06의 임무는 그 엔진을 **사용자가 실제로 쓰는 멀티턴 "AI 코치 대화" 화면으로 연결**하는 것이었다.

**사용자 의도·정서(축소 금지):**
> 사용자는 토큰을 사지 않는다. "내 운동 여정을 기억하는 AI 코치 경험"을 산다.

따라서 화면은 내부 기술 단위(token·cost·context)를 노출하지 않고 **경험 단위("AI 코칭 N회", "이 대화 12/20회")**로만 보여준다. 사용량을 숨겨 소진 후 결제를 유도하지 않고, 실시간으로 잔여·소진을 보여주는 **친절한 제공자 정책**(decision_log #7)을 구현한다.

**이번 스레드 착수 시 사용자 컨펌 3건(예정보고 승인):**
1. 채팅 배치 = **서브탭 공존**(신규 AI 코치 대화를 기본·주력, 기존 브리프는 보존·보조). 브리프 구조는 크게 안 뜯되 "브리프/메모리 UX 재설계 필요"를 기록.
2. 백엔드 = 마이그레이션 적용 완료, **chat-proxy 미배포** → AI 실응답은 graceful 대기로 구현.
3. OWNER 판별 = **DB `is_unlimited`** 기준(이메일 하드코딩 금지).

---

## 2. 적용 기준
- **적용 명세:** spec_rc2_06_frontend_ux + spec_rc2_05a(§5·§7·§A-3·§A-7)
- **적용 결정로그:** #7(사용량 상시 노출·친절한 제공자 정책), #16(방→턴 비율 차감 번복), #4(연장=결제 Phase)
- **적용 사용자 지침:** 서브탭 공존·OWNER=is_unlimited·graceful 대기(위 §1)
- **지켜야 한 금지사항(spec06 §10):** 결제 PG 연결 금지 / system prompt·주입·원가·플랜 계산 수정 금지 / storageGate 강제 ON 금지 / 자동 메모리 구현 금지(Phase2) / beta·vip 제공량 임의 결정 금지 / 토큰·원가 일반 노출 금지

---

## 3. 구현 범위
| 구분 | 구현 내용 | 관련 파일 | 상태 |
|---|---|---|---|
| 오케스트레이션 | 입력→확장조회→주입→조립→스트리밍→**성공시 차감·로그** 상태머신 | `hooks/useCoachChat.ts` | 완료 |
| 사용량 상시 노출 | "AI 코칭 N회 남음" + "이 대화 N/캡회" 게이지 | `components/coach/CoachUsageBadge.tsx` | 완료 |
| 턴캡 UX | 캡 도달 경고 모달(차단X)·플랜 분기·할증 고지·베타 예고 | `components/coach/TurnCapModal.tsx` | 완료 |
| 소진 UX | 무료/유료 분기·예고 톤·플랜 이동 | `components/coach/ExhaustNotice.tsx` | 완료 |
| OWNER 패널 | 오늘/주/보름/달/누적 사용 회 + 발생 원가 | `components/coach/OwnerUsagePanel.tsx` | 완료 |
| 메모리 프로필 편집 | 목표·주의통증·운동/코칭 선호 직접 입력(게이트 OFF 대응) | `components/coach/MemoryProfileEditor.tsx` | 완료 |
| 플랜 쇼핑 | 히든 컨테이너·tier1~3 카드·베타 예고 | `components/coach/PlanShopPanel.tsx` | 완료 |
| 메인 대화 화면 | 메시지·입력·사이드·모달 통합 | `components/coach/CoachChatPanel.tsx` | 완료 |
| 서브탭 통합 | AI 코치 대화(기본)/AI 브리프(보존) 전환 | `pages/CoachNotes.tsx`(수정) | 완료 |
| 스타일 | `.coach-chat-*`·`.coach-subtab*` 토큰 기반 클래스 | `index.css`(수정) | 완료 |

**연결한 spec01~05 (호출만 — 재설계 0):**
| spec | 사용 helper | 연결 방식 |
|---|---|---|
| 01 | `streamCoachChat`·`logCoachRequest`·`calculateEstimatedCost` | 스트리밍 + 매 턴 원가 로그(성공/실패 모두, 차감은 성공만) |
| 02 | `buildInjectionBlock`·`resolveExpansionRequest`·`confirmExpansion` | 매 턴 14일+여정 주입, 반자동 확장조회 사용자 확인 배너 |
| 03 | `assembleCoachChat`(FIXED_SYSTEM_PROMPT)·`buildMemoryProfileCard` | 캐싱 경계 유지 조립. 프롬프트 무수정 |
| 04 | `getMemoryProfile`/`saveMemoryProfile`·`storageGate` | 메모리 편집 UI. 게이트 OFF면 "준비 중" 안내 |
| 05 | `getEntitlement`·`consumeTurn`·`getUsageSummary`·`fetchPurchasablePlans`·`changePlan`·`billingPhase` | 사용량 표시 + 성공시에만 차감 + 플랜/소진/캡 분기 |

---

## 4. 수정·신규 파일
| 파일 | 변경 내용 | 비고 |
|---|---|---|
| `src/hooks/useCoachChat.ts` | 신규 — 채팅 상태머신·오케스트레이션 | 차감·로그 규약의 단일 지점 |
| `src/components/coach/CoachChatPanel.tsx` | 신규 — 메인 대화 화면 | 훅 소유·자식에 분배 |
| `src/components/coach/CoachUsageBadge.tsx` | 신규 — 사용량 상시 노출 | 축소 금지 UI |
| `src/components/coach/TurnCapModal.tsx` | 신규 — 캡 도달 모달 | 플랜 분기 |
| `src/components/coach/ExhaustNotice.tsx` | 신규 — 소진 안내 | 예고 톤 |
| `src/components/coach/OwnerUsagePanel.tsx` | 신규 — OWNER 분석 | getUsageSummary |
| `src/components/coach/MemoryProfileEditor.tsx` | 신규 — 메모리 편집 | 게이트 OFF 안내 |
| `src/components/coach/PlanShopPanel.tsx` | 신규 — 플랜 쇼핑 | 히든 컨테이너 |
| `src/pages/CoachNotes.tsx` | 수정 — 서브탭 + 채팅 마운트 | **기존 브리프 100% 보존(외과적)** |
| `src/index.css` | 수정 — `.coach-chat-*` 등 클래스 | 기존 토큰 재사용·인라인 0 |

> spec01~05 산출물(coachChat lib·chat-proxy·마이그레이션)은 이번 단계에서 **무수정**.
> (RC2 전체는 본레포 PR#36으로 main 머지 완료.)

---

## 5. SQL 적용 여부
- **N/A** — spec06은 SQL 변경 없음. 사용량·플랜 테이블/RPC는 spec05 마이그레이션(`2026-06-07_coachchat_plan_billing.sql`)에서 이미 적용 완료(MCP 검증 시 RPC 라이브 동작 확인). spec06은 그 RPC를 **호출만** 한다.

---

## 6. 빌드 결과
- **`npm run build`(tsc + vite build) 통과.**
- 오류 여부: TypeScript 오류 0. (청크 500kB 경고는 본 작업과 무관한 기존 사항.)
- 해결 내용: 작성 중 `React.KeyboardEvent` 네임스페이스 미임포트 위험을 `type KeyboardEvent` 임포트로 사전 교체. 스트리밍 실패 고착 버그 수정(§10) 후 재빌드 통과.

---

## 7. MCP 브라우징 / 기능 검증 결과 (스크린샷)
로컬 dev(`localhost:5181`) + 마스터 계정(`mster`) 실세션(= 무료 플랜) 기준. **콘솔 오류 0.**

### 7-1. 데스크탑 기본 화면 — 사용량 상시 노출
![데스크탑 코치 대화 기본 화면 — AI 코칭 30회 남음·이 대화 0/10회·메모리 카드·게이트 OFF 안내](pacelog-archive/pages/02-workreport/assets-20260606_180731_spec06/coach-01-desktop-chat.png)
"AI 코칭 30회 남음 (무료 체험)"과 "이 대화 0 / 10회" 게이지가 상단에 상시 노출(축소 금지). 우측 사이드에 플랜 요약 + 내 코치 메모리(목표·주의통증·운동/코칭 선호) + storageGate OFF 안내("저장 기능은 … 완비되면 켜져요. 지금 입력은 임시로만 유지돼요"). getEntitlement RPC 라이브 동작 = 마이그레이션 적용 확인.

### 7-2. 대화 진행 + 응답 실패 — graceful 무차감
![대화 진행 후 응답 실패 — 친절한 오류 배너·잔여 30회 불변](pacelog-archive/pages/02-workreport/assets-20260606_180731_spec06/coach-02-chat-graceful-error.png)
사용자 메시지("오늘 러닝 5km… 무릎 시큰… 내일도?") 렌더 → chat-proxy 미배포 → 친절한 한국어 오류 배너. **잔여 "AI 코칭 30회 남음" 불변 = 응답 실패 무차감 검증(consumeTurn 미호출).**

### 7-3. 플랜 쇼핑(히든 컨테이너) — 베타 예고 톤
![플랜 쇼핑 모달 — 1/2/3단계 가격·회·코칭권·턴캡, 준비 중 비활성](pacelog-archive/pages/02-workreport/assets-20260606_180731_spec06/coach-03-plan-shop.png)
"정식 버전 결제는 준비 중… 예정 플랜 미리 보기"(베타 예고). 1단계 4,900원/월 600회/코칭권 30개/한 대화 20회, 2단계 7,900원/900회/30개/30회, 3단계 11,900원/1,350회/45개/30회 — 05a §2.1 확정표와 **정확 일치**. 버튼 "준비 중" 비활성(결제 미연동).

### 7-4. 브리프 탭 보존
![AI 브리프 서브탭 — 기존 일회성 브리프 UI 그대로 보존](pacelog-archive/pages/02-workreport/assets-20260606_180731_spec06/coach-04-brief-tab-preserved.png)
서브탭 전환 시 기존 "✦ AI 브리프"·"AI 텍스트 브리프"·수동 노트 UI 그대로 동작. 외과적 변경으로 100% 보존.

### 7-5. 모바일 단일 컬럼
![모바일 코치 대화 — 단일 컬럼·하단 탭바·깨짐 없음](pacelog-archive/pages/02-workreport/assets-20260606_180731_spec06/coach-05-mobile-chat.png)
모바일(390×844)에서 단일 컬럼 + 하단 탭바. 데스크탑 우선·모바일 fallback, 깨짐 없음.

### 7-6. 검증 판정표
| 검증 항목 | 결과 | 근거 | 비고 |
|---|---|---|---|
| 데스크탑 기본 화면 | PASS | 7-1 | 사용량 상시 노출·게이트 OFF |
| 대화 + 응답 실패 무차감 | PASS | 7-2 | 잔여 불변 |
| 플랜 쇼핑(히든·예고) | PASS | 7-3 | 확정표 일치 |
| 브리프 탭 보존 | PASS | 7-4 | 기존 UI |
| 모바일 단일 컬럼 | PASS | 7-5 | 깨짐 없음 |
| 사용량 RPC 라이브 | PASS | 7-1 | 실데이터 |

---

## 8. 명세 대비 구현 완료 여부
spec06 §11 검증 항목 + 05a 표시 워딩 대조.

| 명세 요구사항 | 구현 여부 | 근거 | 비고 |
|---|---|---|---|
| AI 코칭 잔여량 표시("N회 남음") | PASS | 7-1 | 토큰·원가·소수 미노출(정수 회) |
| 대화방 턴 사용량("이 대화 N/캡회") | PASS | 7-1 | coach_thread_usage/consumeTurn 기반 |
| 턴캡 도달 모달(차단X) | PASS(코드) | TurnCapModal | 라이브 트리거는 프록시 배포 후 |
| 소진 UX(무료/유료·예고) | PASS(코드) | ExhaustNotice·billingPhase | 베타 예고 톤 분기 |
| OWNER 사용량·원가 | PASS(코드) | OwnerUsagePanel·getUsageSummary | 라이브는 owner 플랜 시드 후 |
| 채팅 흐름 연결(성공시 차감) | PASS(코드)/실패경로 라이브 | useCoachChat | 성공 차감은 chat-proxy 배포 후 라이브 |
| 응답 실패 무차감 | PASS(라이브) | 7-2 | 잔여 30회 불변 |
| Memory Profile UI(수동) | PASS | MemoryProfileEditor | 자동 메모리 금지 준수 |
| Conversation UX(새 대화 등) | PASS | 새 대화·인메모리 | storageGate OFF 강제저장 안 함 |
| 디자인(데스크탑 우선·기존 토큰) | PASS | 7-1·7-5 | 모바일 fallback |
| 모바일 깨짐 없음 | PASS | 7-5 | — |

> **PASS(코드)** = 코드·타입·실패경로로 검증, 라이브 끝까지(실응답·성공차감·캡 도달)는 chat-proxy 배포 후 확인 가능.

---

## 9. 미구현 / 보류 / 축소 의심 항목
정직 고지 — 축소가 아니라 **의존성·명세 금지로 인한 경계**다.

| 항목 | 상태 | 이유 | 후속 필요 |
|---|---|---|---|
| AI 실응답·성공 차감·캡 도달 라이브 | 보류(라이브) | chat-proxy 미배포(운영 작업) | 프록시 배포 + 모델 키 후 라이브 검증 |
| OWNER 화면 라이브 | 보류(라이브) | 테스트 계정이 무료 플랜 | owner 플랜 SQL 시드 후 확인 |
| 자동 메모리 | 미구현(의도) | 명세상 Phase2 금지 | Phase2 후보 |
| 대화 저장·보관함 풀가동 | 보류(의도) | storageGate OFF(개인정보 5종 미완) | 보호장치 완비 후 활성화 |
| BETA/VIP 제공량·기간 표시 | 보류(의도) | 미확정(이월 ⓐⓑ) | 원가 시뮬레이션 후 |
| 결제 PG 실연동 | 미구현(의도) | 수익화 Phase | Phase3 |
| 브리프/메모리 UX 재설계 | 미착수(지시) | 이번은 보존만(사장님 지시) | 후속 개편 |

---

## 10. 발견된 이슈
- **스트리밍 실패 시 화면 고착 버그** — MCP 검증으로 포착·수정.
  - 증상: chat-proxy 미배포 상태 전송 시 "코치가 기록을 살펴보는 중…"에서 영구 고착.
  - 원인: `streamCoachChat`의 초기 `fetch`가 연결 거부 시 throw하는데 훅이 try/catch로 감싸지 않아 상태가 `streaming`에 멈춤.
  - 해결: `useCoachChat.dispatch`의 스트리밍 호출을 try/catch로 감싸고, 네트워크 실패를 친절한 한국어 안내("지금은 AI 응답 서버에 연결할 수 없어요. … 코칭 횟수는 차감되지 않아요")로 처리. **무차감 규약 유지**(consumeTurn 미호출).
  - 판단 기준: "응답 실패 무차감"은 RC2 핵심 규약이므로, 실패 경로에서 차감·UX 멈춤 둘 다 없어야 한다.

---

## 11. 후속 작업
1. (운영) chat-proxy 배포 + 모델 키(Gemini 2.5 Flash-Lite 또는 OpenAI 폴백) → AI 실응답·성공 차감·캡 도달 라이브 검증.
2. (운영) owner 플랜 시드(`coach_subscription.plan_type='owner'`) → OWNER 화면 활성.
3. (법무·후속) storageGate 5종 보호장치 완비 → 저장 활성화(코드 변경 + 재배포). 그 전 약관 "파기" 표현 금지.
4. (제품) 브리프/메모리 UX 재설계(사장님 지시 방향) — 개인메모=다이어리화 / 코칭가이드 항목 축소+유저메모리 통합 / 장기 AI 자동 업데이트+직접 수정.
5. (의사결정) BETA/VIP 확정·결제 Phase 전환.

---

## 12. 최종 판단
- **이 작업 단위는 완료로 볼 수 있는가:** 예 — spec06 코드 구현·빌드·UI 검증 완료. 단 "AI 실응답 라이브"는 chat-proxy 배포(운영)에 의존.
- **Phase0 종료에 영향을 주는가:** spec06으로 Phase0(채팅 켜기)의 **코드 측면은 종료**. 라이브 "켜기"는 chat-proxy 배포가 마지막 조각.
- **사용자 확인이 필요한가:** chat-proxy 배포·owner 시드·storageGate 활성화·BETA/VIP 확정은 사용자/운영 결정 필요.

---

## 13. 작업자 메모 + 결정로그 5요소

**작업자 메모:** spec06은 "엔진을 경험으로 바꾸는" 단계라, 가장 큰 리스크는 내부 단위(토큰·원가)를 무심코 노출하는 것이었다. 모든 표시를 정수 "회"로 통일하고, 실패 무차감을 훅의 단일 지점에서 강제해 "거짓말하지 않는 사용량"(05a §5 정신)을 지켰다.

**결정로그 #A — 채팅 UI 배치(서브탭 공존, 대화 기본)**
- **선택된 안:** /coach에 서브탭 추가, **AI 코치 대화를 기본·주력**, 기존 AI 브리프는 보조 탭으로 보존.
- **배제된 안:** ① 브리프 전면 대체(기존 가치 상실) ② 별도 라우트 /coach/chat(진입 동선 분산).
- **선택 이유:** 외과적 변경으로 기존 브리프 100% 보존 + 신규 대화를 자연히 먼저 쓰게 함.
- **사용자 의견·정서:** "신규 AI 코치 대화를 기본 진입/주력, 브리프는 보존용/보조. 브리프 구조 크게 뜯지 말되 '브리프/메모리 UX 재설계 필요'를 명확히 남겨라."
- **재검토 조건:** 브리프/메모리 UX 재설계 착수 시 서브탭 구조·진입 동선 재검토.

**결정로그 #B — OWNER 판별(DB is_unlimited)**
- **선택된 안:** `getEntitlement().is_unlimited`(plan_type='owner')로 OWNER 화면 분기.
- **배제된 안:** 이메일 하드코딩(기존 Layout의 OWNER_EMAIL 방식).
- **선택 이유:** 하드코딩 제거·명세 정합. 단 owner 플랜 SQL 시드 1회 필요.
- **사용자 의견·정서:** "하드코딩 이메일 판별 안 함. coach_plan_catalog/entitlement/subscription 기준 is_unlimited로 분기."
- **재검토 조건:** 다중 운영자·위임 운영 도입 시 판별 기준 재설계.