yunchan/vignette
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

세션 평가·라이브코치·교수자 분석 라운드 마감 + 문서 정리 + 코드품질 리팩터

Browse source 
- 누적 작업트리 커밋: 회기 평가 복구·durable 저장, 라이브 코치 이력/근거, 교수자 학생분석, 음성 비언어 메타, PII 마스킹, 운영 티켓/헬스 등
- 문서: 완료 기록 docs/archive/ 냉동 보관, docs/ 단일 인덱스(docs/README.md)+통합 TODO(docs/TODO.md)로 정리
- 리팩터(행위 보존): Stage enum SSOT(taxonomy 소유·state_machine re-export), store recent/masked_turns 중복 제거, speaker_ko_label 단일 헬퍼, _list_sessions N+1 제거(state/turns 배치 + 턴평가 하이드레이션 배치)
- 검증: 백엔드 pytest 352 passed, _list_sessions E2E chromium-single-run 2 passed
This commit is contained in:
Yun Chan 2026-07-02 02:50:36 +09:00
parent 7c41c3ce79
commit 778e8526d4
108 changed files with 6457 additions and 455 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/design-concepts/prompts/learner-history-archive-redesign-2026-06-28.md
View file

@ -1,60 +0,0 @@
# 학습자 기록/아카이브 화면 재설계 지침 — 2026-06-28
대상 화면: `/learn/history`
## 문제 정의
- 기존 회기 목록은 표처럼 보이지만 실제 사용자는 표 비교보다 `이어하기`, `리뷰`, `기록 열람`, `다시 연습` 중 하나를 선택해야 한다.
- 진행 중 회기, 리뷰 가능한 회기, 종료 기록이 한 목록에 섞여 있어 기록 페이지가 보관함인지 분석 화면인지 불명확했다.
- 현재 세션 API에는 학습자 회기 `archived_at`, 숨김, 복원 endpoint가 없다. 따라서 실제 아카이브 기능을 완료된 기능처럼 표시하지 않는다.
## UX 근거
- NN/g data-table 기준: 표는 검색, 비교, 행 상세 확인, 행 작업이 명확해야 한다. 이 화면은 비교보다 행 작업이 중심이므로 카드형 기록 리스트가 더 적합하다. 참고: https://www.nngroup.com/articles/data-tables/
- NN/g information scent 기준: 사용자가 클릭 후 무엇을 얻게 되는지 예측 가능해야 한다. `기록`, `리뷰`, `이어하기`를 상태별로 분리한다. 참고: https://www.nngroup.com/articles/information-scent/
- Material Design data table/list 기준: 작은 화면에서는 행 액션과 필터를 명확히 유지해야 한다. 참고: https://m3.material.io/components/data-tables/overview
- Apple HIG tables 기준: 테이블은 탐색과 선택을 돕되, 편집/행 액션은 명확한 컨트롤로 드러내야 한다. 참고: https://developer.apple.com/design/human-interface-guidelines/tables
## 적용 원칙
1. 기록 페이지는 `진행 중`, `리뷰 필요`, `보관됨` 세 상태를 기본 분류로 둔다.
2. `보관됨`은 현재 단계에서 `종료됐고 리뷰 큐에 없는 읽기 전용 기록`을 뜻한다.
3. 실제 archive 저장/복원/숨김은 API와 보존 정책이 생긴 뒤에만 노출한다.
4. 회기 행은 표 헤더 대신 카드로 보여준다. 한 행에는 상태, 내담자, 단계, 턴 수, 시작 시각, 주 행동, 보조 행동만 남긴다.
5. 검색은 내담자 코드/이름, 단계, 상태 라벨을 대상으로 한다.
## 화면 구조
- Header: `회기 기록을 찾고 정리합니다.`
- Overview filter cards: `전체`, `진행 중`, `리뷰 필요`, `보관됨`
- Main workbench:
- 기록 목록 제목과 현재 필터 결과 수
- 검색 입력
- 상태 필터 버튼
- 카드형 회기 목록
- Side rail:
- 아카이브 기준: 진행 중/리뷰 필요/보관됨의 의미
- 페르소나별 진행 정도
## Figma 이관 단위
Figma 파일 키가 생기면 다음 컴포넌트 단위로 옮긴다.
- `HistoryTaskCard`: 상태 요약 필터 카드
- `HistorySearchToolbar`: 검색 입력 + 상태 필터
- `SessionRecordCard`: 회기 기록 카드
- `ArchiveRulePanel`: 아카이브 기준 패널
- `PersonaProgressPanel`: 기존 페르소나별 진행 패널
제품 폰트는 `apps/web/src/styles/tokens.css`의 `--font-sans` 기준, 즉 Pretendard 계열을 사용한다.
## 이미지 생성 프롬프트
PNG 래스터 UI mockup only, no SVG, no vector wireframe. A dark clinical learning dashboard for an AI counseling simulation platform. Design the learner session history/archive page as a responsive set showing desktop, tablet, and mobile in one image. Use a calm dark teal surface, warm muted paper-tint highlights, Pretendard-like Korean UI typography, compact professional spacing, and no marketing hero. Layout: top header "회기 기록을 찾고 정리합니다.", four status filter cards "전체 / 진행 중 / 리뷰 필요 / 보관됨", a main session records workbench with search and segmented filters, card-based session rows with status dot, persona code, persona name, stage progress bar, date, primary action, and secondary retry action. Right rail shows archive rules and persona progress. Avoid table grid clutter, avoid bright white panels, avoid decorative gradient blobs, avoid fake stock imagery. The image should feel like a usable product screen, not a poster.
## 후속 기능
- `app.sessions` 또는 별도 preference 테이블에 학습자별 archive/hidden 상태 추가
- `POST /sessions/{id}/archive`, `POST /sessions/{id}/restore` 또는 PATCH endpoint 추가
- 보관/숨김이 교수자 검토, 연구/감사 보존, 공유 링크와 충돌하지 않는지 정책 확정
- 아카이브 상태를 dashboard counts와 `/learn/history` 필터에 반영

74
docs/design-concepts/prompts/learner-home-dashboard-redesign-2026-06-27.md
View file

@ -1,74 +0,0 @@
# 학습자 홈 대시보드 재설계 지침
작성일: 2026-06-27
## 목적
`/learn`은 내담자 선택 화면이 아니라 학습자 개인 대시보드다. 첫 화면은 사용자가 오늘 무엇을 해야 하는지 즉시 판단하게 해야 한다. 새 회기 시작은 `/learn/practice`, 기록 탐색은 `/learn/history`로 분리한다.
## 참고한 UX 원칙
- 사용자 필요를 먼저 정의한다. 홈의 사용자 필요는 "오늘 이어갈 회기/리뷰/다음 연습을 결정한다"이다.
참고: <https://www.gov.uk/service-manual/user-research/start-by-learning-user-needs>
- 세부 정보는 필요할 때 펼친다. 홈에는 모든 기록을 나열하지 않고 최근/리뷰/학습 인사이트만 요약한다.
참고: <https://www.nngroup.com/articles/progressive-disclosure/>
- 다음 행동의 정보 향을 분명히 한다. 버튼은 `이어하기`를 1순위로 두고, `학습 대상 보기`, `기록 보기`는 보조 행동으로 낮춘다.
참고: <https://www.nngroup.com/articles/information-scent/>
- 화면 크기마다 정보 구조를 바꾼다. 데스크톱은 회기 리캡 + AI 코치 2열, 태블릿/모바일은 세로 흐름으로 전환한다.
참고: <https://m3.material.io/foundations/adaptive-design/overview>
## 현재 화면 진단
캡처:
- `docs/design-verification/learner-home-redesign/current-desktop.png`
- `docs/design-verification/learner-home-redesign/current-tablet.png`
- `docs/design-verification/learner-home-redesign/current-mobile.png`
문제:
- 홈의 핵심 행동이 `이어하기`, `학습 대상 보기`, `회기 기록 보기`, 최근 회기 행 버튼으로 분산돼 있었다.
- "진행 중인 회기를 먼저 마무리"라는 메시지는 있었지만, 내담자의 마지막 반응과 학습자 마지막 발화가 시선 흐름의 중심에 오지 않았다.
- 오른쪽 `다음 행동` 카드가 숫자 묶음처럼 보이고, AI 코치와 분리돼 실제 결정을 돕지 못했다.
- 모바일에서는 카드가 보고서처럼 길게 쌓여 첫 화면의 과업이 약해졌다.
## 생성 이미지 결과
생성 방식: built-in `image_gen` 도구. 결과는 PNG 래스터 이미지이며 SVG/벡터가 아니다.
- 채택 후보 A: `docs/design-concepts/generated/11-learner-dashboard-redesign-concept-b.png`
- 채택 후보 B: `docs/design-concepts/generated/12-learner-dashboard-redesign-concept-b-alt.png`
- 폐기: `docs/design-concepts/generated/10-learner-dashboard-redesign-concept-a.png`
이유: 상담실 배경 이미지로 생성돼 홈 UI 레이아웃 지침으로는 부적합하다. 배경 무드 참고 이상의 의미를 주지 않는다.
## 적용 지침
- 홈 첫 블록은 `오늘 이어갈 회기`다.
- 회기 리캡에는 내담자 아바타, 페르소나명, 단계, 감정/표정 힌트, 상담 진행률, 마지막 내담자 반응, 내 마지막 반응을 배치한다.
- `AI 코치`는 별도 카드가 아니라 홈의 결정 패널이다. 코치 문장, 짧은 체크 힌트, 진행/리뷰 카운트, `이어하기` CTA를 한 패널에 묶는다.
- `이어하기`는 채워진 1순위 버튼으로 한 번만 강하게 보인다. 보조 행동은 `학습 대상 보기`, `기록 보기` 텍스트 버튼 수준으로 낮춘다.
- 지표 카드는 회기 리캡 아래로 내린다. 지표가 홈을 지배하면 사용자가 보고서로 인식한다.
- 모바일은 `회기 리캡 -> AI 코치 -> 2x2 지표 -> 최근 회기 -> 인사이트` 순서를 유지한다.
- 모든 패널은 다크 테마 토큰 위에서 통일한다. 흰 섹션, 떠 있는 메모, 패턴 보드 직접 삽입은 금지한다.
## 구현 반영
- `apps/web/src/pages/LearnerHome.tsx`
- `/learn` 대시보드 히어로를 `회기 리캡 + AI 코치` 구조로 재배치했다.
- 독립 `다음 행동` 카드를 제거하고 AI 코치 패널은 단일 `이어하기` CTA 중심으로 정리했다.
- 라포/탐색/개입/정리 단계 기반 상담 진행 바를 추가했다.
- 모바일 중복 CTA를 제거하고 지표를 2x2로 유지했다.
## 2026-06-28 시안 정합 보정
- AI 코치 패널은 시안처럼 `코칭 문장 + 3개 체크 힌트 + 단일 이어하기 CTA`만 남긴다.
- 진행/리뷰 숫자와 보조 이동은 코치 패널에서 빼고, 상단 상태 또는 메트릭/좌측 내비게이션에서 처리한다.
- 하단은 시안 구조에 맞춰 `리뷰 대기`, `다음 연습 추천`, `최근 기록` 3분할로 구성한다.
- 최근 피드백 전문은 홈에서 길게 펼치지 않는다. 홈에서는 가장 최근 피드백 1건만 요약하고, 자세한 내용은 리뷰 화면으로 넘긴다.
- 태블릿과 모바일은 3분할을 세로 스택으로 전환한다.
검증 캡처:
- `docs/design-verification/learner-home-redesign/final-desktop.png`
- `docs/design-verification/learner-home-redesign/final-tablet.png`
- `docs/design-verification/learner-home-redesign/final-mobile.png`

102
docs/design-concepts/prompts/vignette-dark-ui-refresh-2026-06-28.md
View file

@ -1,102 +0,0 @@
# Vignette dark UI refresh prompts — 2026-06-28
목적: 기존 `03-session-responsive.png`가 다크 스테이지와 라이트 패널을 섞어 보여서, 현재 구현된 dark active UI와 맞는 디자인 컨셉 이미지를 다시 생성했다. 추가로 회기 리뷰와 학습자 홈도 같은 제품 언어로 보정했다.
## 근거
- 실제 구현 기준: `apps/web/src/pages/Session.tsx`, `apps/web/src/pages/session/session.css`, `apps/web/src/styles/tokens.css`
- 최신 검증 캡처: `docs/design-verification/full-pages/03-session-active-desktop.png`, `03-session-active-tablet.png`, `03-session-active-mobile.png`
- 디자인 SSOT: `docs/DESIGN_CONCEPT.md`, `docs/dev_dashboard.html`
- UX 원칙: 상태 가시성, progressive disclosure, 한 화면 한 의도, 대비 기준
- Nielsen Norman Group, 10 Usability Heuristics: https://www.nngroup.com/articles/ten-usability-heuristics/
- Nielsen Norman Group, Progressive Disclosure: https://www.nngroup.com/articles/progressive-disclosure/
- Material Design dark theme guidance: https://m2.material.io/design/color/dark-theme.html
- WCAG contrast guidance: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
## 산출물
- `docs/design-concepts/generated/03-session-responsive-v2-dark-unified.png`
- `docs/design-concepts/generated/04-session-review-responsive-v2-dark-unified.png`
- `docs/design-concepts/generated/02-learner-home-responsive-v2-dark-unified.png`
## 공통 프롬프트 규칙
- 운영 기본은 dark 화면이다. active UI에 off-white, beige, light card를 섞지 않는다.
- 기본 팔레트: app `#0E1714`, panel `#17231F`, input `#22302C`, stage `#0E1614`, hairline `#2A363C`, accent `#6FB3A4`, clay `#CC8F77`.
- 진짜 기능명만 쓴다. 장식용 hero, marketing copy, 가짜 과장 차트는 금지한다.
- 학습자는 지금 해야 할 한 가지 행동을 즉시 알아야 한다.
- 실시간 피드백은 중앙 과업을 가로막지 않는 주변 신호로 둔다.
- 주요 한글 라벨은 읽히게 하고, 작은 본문은 UI 질감 수준이면 된다.
## 03-session-responsive v2 prompt
```text
Use case: ui-mockup
Asset type: responsive product UI concept sheet for Vignette live counseling session, 16:9 wide raster image.
Primary request: Create a polished product UI concept sheet showing the live counseling session screen in desktop, tablet, and mobile mockups on one wide canvas. This is not a landing page. It must feel like a real immersive clinical training application currently in use.
Reference behavior from the current app: live counseling session has a left client-context column, a phase tracker, a central dark client stage with a semi-realistic client avatar bust and a breathing voice orb, a real-time transcript, a text fallback composer, a live-signal rail, client observation meters, safety status, and a bottom control bar with mic state, pause, screen mode segmented control, and session end.
Required layout:
- Desktop mockup: three-region layout. Left narrow rail contains “내담자 컨텍스트” and “회기 진행”. Center has dark client stage on top, “실시간 자막” transcript below, and “학습자 발화를 입력하세요.” composer. Right rail has “라이브 신호”, “관찰 신호”, and “안전 점검”. Bottom control bar shows “마이크 꺼짐”, segmented control “몰입 / 상태 신호 / 코칭”, “일시정지”, and “회기 종료”.
- Tablet mockup: top compact context strip, stage and transcript stacked, controls at bottom.
- Mobile mockup: compact vertical flow with context chips, avatar stage, transcript, input, and thumb-friendly controls.
Visual style:
- Unified dark theme only. Use #0E1714 app background, #17231F panels, #22302C inputs, #0E1614 stage, #2A363C hairlines.
- Sage teal accent #6FB3A4 for active state and focus, terracotta #CC8F77 only for learner/client voice warmth, muted amber only for safety attention.
- No off-white or beige panels anywhere in the active session UI. No light theme mixed into the image.
- Quiet clinical training room, not a sci-fi dashboard. Subtle paper/noise texture may exist inside dark surfaces only.
- Typography feels like Pretendard: Korean UI, strong weight hierarchy, compact labels, tabular timer.
- Corners are modest: 6-12 px, not bubbly. Hairline borders, very soft shadows.
UX principles to embody:
- One screen, one intent: listening and responding to the client.
- Visibility of system status: phase, mic state, live signal, safety state are readable at a glance.
- Progressive disclosure: real-time feedback is quiet and peripheral, not intrusive.
- Strong contrast for important text; no low-contrast tiny labels for primary controls.
Text hints: “라이브 상담 세션”, “내담자 컨텍스트”, “회기 진행”, “라포”, “실시간 자막”, “라이브 신호”, “관찰 신호”, “안전 점검”, “학습자 발화를 입력하세요.”, “마이크 꺼짐”, “상태 신호”, “코칭”, “회기 종료”.
Avoid: mixed light/dark theme, white cards, beige side panels, bright dashboards, neon glow, sci-fi HUD, giant decorative hero, stock photo background, marketing copy, emoji, red-heavy warnings, score fireworks, radar charts, nested cards, cartoon icons, watermark, browser chrome.
```
## 04-session-review v2 prompt
```text
Use case: ui-mockup
Asset type: responsive product UI concept sheet for Vignette session review, 16:9 wide raster image.
Primary request: Create a polished product UI concept sheet showing the completed session review screen in desktop, tablet, and mobile mockups on one wide canvas. This is a reflective clinical education workbench, not a score dashboard and not a marketing page.
Reference behavior from the current app and source: session review includes session headline metadata, audio replay, PDF export, emotion balance timeline, phase flow, annotated transcript, technique labels, supervisor comments, good moments, growth points, next utterance suggestion, and case conceptualization worksheet.
Visual style:
- Unified dark theme only. Use #0E1714 app background, #17231F panels, #22302C nested surfaces, #2A363C dividers, #6FB3A4 sage teal accents.
- Use muted slate-blue for AI/supervisor notes, muted amber only for watch items, terracotta sparingly for client-side warmth.
- No off-white or beige panels anywhere. No bright white review cards.
- Calm, dense but readable clinical training record.
Text hints: “회기 리뷰”, “감정 밸런스 타임라인”, “회기 흐름”, “세션 트랜스크립트”, “좋았던 순간”, “다음 회기 개선점”, “슈퍼바이저 코멘트”, “오디오 다시 듣기”, “PDF 내보내기”, “사례개념화 워크시트”, “근거 보기”, “다음 발화 제안”.
Avoid: mixed light/dark theme, white cards, beige paper background, score fireworks, gamified badges, radar charts, dense red warnings, decorative hero illustration, stock-photo desk, emoji, cartoon icons, browser chrome, watermark.
```
## 02-learner-home v2 prompt
```text
Use case: ui-mockup
Asset type: responsive product UI concept sheet for Vignette learner home / practice dashboard, 16:9 wide raster image.
Primary request: Create a polished product UI concept sheet showing the learner home screen in desktop, tablet, and mobile mockups on one wide canvas. This is the first working screen after login: the learner chooses or continues a counseling practice session. It must be a real app workbench, not a landing page.
Reference behavior from the current app and source: learner home has persona selection, selected client preview, presenting problem, difficulty, counseling approach, voice/session info, start new session or continue action, active/review/total session stats, recent sessions, review-ready items, and AI coach recommendations.
Visual style:
- Unified dark theme only. Use #0E1714 app background, #17231F panels, #22302C cards/inputs, #2A363C hairlines, #6FB3A4 sage teal CTA and active states.
- Terracotta #CC8F77 only for client warmth or small persona initial. Amber only for “권장 액션”/review wait state.
- No light theme surfaces, no white cards, no beige sections.
- Dense but calm SaaS/education workbench. Prioritize scanning, comparison, and repeated action.
Text hints: “오늘의 회기를 준비합니다.”, “연습 대상”, “내담자 목록”, “서연(가명)”, “고2”, “우울/자살사고”, “주호소”, “난도”, “접근”, “음성”, “새 회기 시작”, “이어하기”, “기존 회기”, “리뷰 대기”, “다음 연습 추천”, “최근 기록”, “AI 코치”, “권장 액션”.
Avoid: mixed light/dark theme, bright white panels, beige cards, marketing hero, oversized illustration, empty decorative graph, gamified leaderboard, emoji, cartoon mascots, red-heavy alerts, browser chrome, watermark.
```