docs: plan hotfix-006 dashboard copy and live fidelity

This commit is contained in:
2026-04-06 20:37:04 +09:00
parent 768f9fdc20
commit b47248b2be
4 changed files with 204 additions and 1 deletions

View File

@@ -17,6 +17,7 @@
## 활성 작업
- **SPRINT-015**: Master Dashboard v3 정보 구조 리디자인
- **HOTFIX-006**: 대시보드 문구 절제 + 실시간성 정합성 보정
## 이번 Sprint 핵심 요구사항
1. 메인 대시보드를 4자매 운영 관제의 대표 화면으로 재정의
@@ -35,5 +36,7 @@
- 구조 기준: `../ARCHITECTURE.md`
- 디자인 인덱스: `./design/index.md`
- Sprint 계획: `./sprints/SPRINT-015.md`
- 나랑 handoff: `./sprints/SPRINT-015-NARANG-HANDOFF.md`
- Sprint handoff: `./sprints/SPRINT-015-NARANG-HANDOFF.md`
- Hotfix 계획: `./hotfix/HOTFIX-006.md`
- Hotfix handoff: `./hotfix/HOTFIX-006-NARANG-HANDOFF.md`
- 배포 플로우: `./deploy/main-release-flow.md`

View File

@@ -204,6 +204,20 @@ User → Harang → Narang → Darang → Irang 흐름과, maker-checker loop, e
- mock 텍스트/숫자로 고정하지 말고 실제 데이터가 들어올 자리를 먼저 설계할 것
- 값이 없을 때는 `No recent activity`, `No active deployment`, `No harness rules yet`처럼 조용한 empty state 제공
- offline / missing / unavailable 상태는 숨기지 말고 명확히 드러낼 것
- websocket 연결 상태와 데이터 freshness를 같은 의미로 쓰지 말 것
- 각 섹션은 가능하면 아래 source 중 하나로 구분할 것
- `runtime live`
- `event mirrored`
- `polling snapshot`
- `doc derived`
- `empty / unavailable`
- 추정/합성값이면 사실처럼 단정하지 말고 neutral wording 사용
## 카피 원칙
- 설명문보다 라벨형 문구 우선
- 첫 화면 문구는 짧고 건조해야 함
- `~만들었어`, `~정리했어`, `~읽히게` 같은 메타 설명 금지
- 보드/패널 body는 원문 요약 또는 상태 문구 위주로 짧게 유지
## 인터랙션 원칙
- hover 없어도 핵심 정보가 읽혀야 함

View File

@@ -0,0 +1,44 @@
# HOTFIX-006 Narang Handoff
## repo / branch
- repo: `https://git.nabomhalang.co.kr/hanarang/hanarang-dashboard`
- branch: `feature/hotfix-006-dashboard-copy-live-fidelity`
## 읽을 문서
1. `.plans/hotfix/HOTFIX-006.md`
2. `.plans/design/ui/dashboard-design.md`
## 이번 수정 핵심
자기야 피드백은 명확해.
1. 문구가 너무 길고 쓸데없는 말이 많아
2. 실시간처럼 보이는데 실제론 아닌 부분이 있어
이 두 개를 바로 고쳐.
## 꼭 손볼 것
- 상단 headline / summary
- current focus 설명문
- operator meta
- pipeline node detail / fallback
- infra/meta card detail
- board 카드 body 문구
- `socket live`, `LIVE ON` 같은 라벨의 의미
## 절대 기준
- 설명문 쓰지 마
- UI 자기소개하지 마
- 실시간 아닌 걸 실시간처럼 포장하지 마
- source-of-truth 애매하면 neutral wording으로 낮춰
- 문구는 짧고 건조하게
## 구현 목표
- `ACTIVE PIPELINE`은 진짜 이벤트 기반이면 그렇게 보이고
- 아니면 `SNAPSHOT`, `DOC-DERIVED`, `NO ACTIVE HANDOFF`처럼 정직하게 보여
- `MISTAKE LOG & HARNESS`도 원문/출처/시각 중심으로 짧게 정리
- freshness 메타를 넣어서 stale 여부를 읽을 수 있게 해
## QA 전 체크
- 자기야가 봤을 때 `주구절절하다`는 느낌이 없어야 해
- `실시간인가? 아닌가?`가 헷갈리면 실패야
- build 통과는 기본

142
.plans/hotfix/HOTFIX-006.md Normal file
View File

@@ -0,0 +1,142 @@
# HOTFIX-006: 대시보드 문구 절제 + 실시간성 정합성 보정
## 목표
Master Dashboard v3에서 주구절절한 설명형 문구를 운영 대시보드다운 짧은 문장으로 정리하고, `실시간처럼 보이지만 실제로는 폴링/요약/문서 기반인 정보`를 정확한 source-of-truth 기준으로 다시 맞춘다.
## 왜 이걸 고치나
현재 메인 대시보드는 레이아웃은 좋아졌는데 두 가지 문제가 남아 있어.
1. **문구가 길다**
- 상단 Headline / Summary
- OperatorMeta
- pipeline/detail/fallback 문장
- harness/qa 보드 설명
이런 부분이 대시보드보다 설명문처럼 읽혀.
2. **실시간성 표현이 과하다**
- `socket live`는 웹소켓 연결 상태일 뿐, 모든 카드/보드가 실시간 원본 반영이라는 뜻은 아니야.
- `ACTIVE PIPELINE`, `MISTAKE LOG & HARNESS`, 일부 infra/meta는 최근 activity / QA 문서 / polling snapshot을 조합해 만든 값이 섞여 있어.
- 따라서 `실시간 반영`처럼 보이는 문구와 라벨은 정정해야 해.
## 범위
- 대시보드 메인(`/`) 문구 전반 절제
- source-of-truth 명시 정리
- 실시간 / 폴링 / 문서기반 / 추정치 상태 구분
- 필요 시 백엔드 dashboard ops 응답에 freshness/source 메타 추가
- 프론트에서 misleading wording 제거
## 태스크
### TASK-078: 대시보드 카피를 운영형 짧은 문구로 전면 정리
- **담당:** 나랑이
- **상태:** pending
- **주요 파일:**
- `frontend/app/page.tsx`
- `frontend/components/dashboard/ActivePipeline.tsx`
- **설명:**
- 문장형 설명을 줄이고 짧은 운영 문구로 교체
- 섹션 제목/보조 문구/fallback/empty state를 모두 다시 본다
- **문구 기준:**
- 길게 설명하지 말 것
- 1문장보다 라벨형/상태형 표현 우선
- `~읽히게 만들었어`, `~정리했어` 같은 메타 설명 금지
- **완료 기준:**
- 첫 화면 문구가 대시보드 UI 문장처럼 짧고 건조함
- 자기소개/설계 설명 문장이 제거됨
### TASK-079: source-of-truth 기준표 정리
- **담당:** 나랑이
- **상태:** pending
- **주요 파일:**
- `backend/src/dashboard/dashboard.service.ts`
- 필요 시 dashboard DTO/타입 정의
- `.plans/design/ui/dashboard-design.md`
- **설명:** 각 섹션 값이 어디서 왔는지 명확히 구분한다.
- **최소 구분:**
- runtime live
- websocket event mirrored
- polling snapshot
- repo/qa doc derived
- fallback/empty
- **완료 기준:**
- 주요 카드/보드/파이프라인 값에 원본 기준을 설명할 수 있음
- 합성값을 실시간 원본처럼 표시하지 않음
### TASK-080: `LIVE` 표현 정합성 보정
- **담당:** 나랑이
- **상태:** pending
- **주요 파일:**
- `frontend/app/page.tsx`
- `frontend/lib/useSocket.ts`
- **설명:**
- 현재 `socket live`는 websocket 연결 상태만 뜻하므로 표현을 더 정확히 바꾼다.
- 예: `SOCKET ON`, `EVENT STREAM ON`, `SNAPSHOT`, `STALE`, `SYNCED 12s AGO` 같은 운영형 라벨로 정리
- **완료 기준:**
- websocket 연결 여부와 데이터 최신성이 혼동되지 않음
- LIVE ON/OFF 하나만 보고 전체가 실시간이라고 오해되지 않음
### TASK-081: `ACTIVE PIPELINE` 실데이터/추정치 경계 보정
- **담당:** 나랑이
- **상태:** pending
- **주요 파일:**
- `backend/src/dashboard/dashboard.service.ts`
- `frontend/components/dashboard/ActivePipeline.tsx`
- **설명:**
- 노드 상태/active task/focus가 최근 activity 기반 추론이면 그 사실을 숨기지 말 것
- 명시적 handoff/event가 없으면 억지 문장 대신 짧은 neutral fallback 사용
- **완료 기준:**
- `ACTIVE PIPELINE`이 추정치를 확정 사실처럼 말하지 않음
- 이벤트 없음/불충분 상태가 자연스럽게 보임
### TASK-082: `MISTAKE LOG & HARNESS` / 보드 카드 원문성 보강
- **담당:** 나랑이
- **상태:** pending
- **주요 파일:**
- `backend/src/dashboard/dashboard.service.ts`
- `frontend/app/page.tsx`
- **설명:**
- `관리자 harness 편집 로그에서 직접 가져온 기록이야.` 같은 설명형 body 제거
- 가능하면 원문 제목/원문 요약/출처/시각만 짧게 노출
- **완료 기준:**
- 보드 카드 문구가 덜 소설 같고 더 기록물처럼 읽힘
- source 라벨/시각이 더 명확함
### TASK-083: freshness 메타 추가 및 노출
- **담당:** 나랑이
- **상태:** pending
- **주요 파일:**
- `backend/src/dashboard/dashboard.controller.ts`
- `backend/src/dashboard/dashboard.service.ts`
- `frontend/app/page.tsx`
- **설명:** dashboard ops 응답에 최소 freshness 메타를 추가한다.
- **예시:**
- generatedAt
- activityLatestAt
- sistersLatestAt
- qaDocLatestAt
- **완료 기준:**
- UI에서 `last sync`, `activity lag`, `runtime lag` 같은 판단이 가능함
- stale 상태를 눈치채기 쉬움
## 문구 톤 기준 예시
### 금지
- "지금 어디가 움직이고 있는지, 첫 화면에서 바로 읽히게 만들었어."
- "장식보다 handoff 판단이 먼저 읽히게 정리했어."
- "현재 오너 기준은 ... 최근 handoff와 phase를 같이 보고 있어."
- "관리자 harness 편집 로그에서 직접 가져온 기록이야."
### 권장
- `MASTER DASHBOARD`
- `CURRENT FOCUS`
- `SOCKET ON`
- `SNAPSHOT`
- `NO ACTIVE HANDOFF`
- `NO RECENT QA`
- `LAST EVENT 2m AGO`
- `DOC-DERIVED`
## 완료 기준
- 문구가 짧고 운영 대시보드답게 바뀜
- 실시간/폴링/문서유도 값이 구분됨
- misleading `live` 표현이 제거됨
- 자기야가 봤을 때 `실시간 아닌데 실시간처럼 보인다`는 느낌이 사라짐