# v0.3.x — UI IA Track Handover

> **Active handover** (2026-05-21~). 새 Claude Code 세션이 이 작업을
> 이어받는다면 `CLAUDE.md` → `docs/UI_IA.md` → 이 문서 순으로 읽으세요.
>
> **Branch**: `claude/explore-miro-integration-zKLEv` — 아직 main 미머지.
> 모든 작업물이 이 브랜치에 푸시됨.
>
> **Theme**: v0.3 Platform Skeleton 의 한 부속 트랙. 도메인 기능 추가
> 없음 — 모체 정돈(IA + 코드 중복 제거)만. `CLAUDE.md` rule #1 준수.

---

## 0. 한 줄 요약

JAMES 의 UI 표면(4 HTML 페이지 / 133 HTTP API / 17 admin 탭 / ~79
`data-action`)이 "중구난방"이라는 사용자 진단에서 출발. 1주 작업으로
**(a) IA 계약 확정 + (b) API↔UI 매핑 전수조사 + (c) Phase 2 코드
중복 3건 제거 + (d) 챗 세션 패널 사이드바 이동**까지 완료. 남은 큰
일은 **Phase 3 = `admin.js` Govern/Observe/Configure 삼분할**.

---

## 1. 작업 산출물 (이 브랜치 7 커밋)

순서: 최신 → 오래된. 모두 `claude/explore-miro-integration-zKLEv` 브랜치
에 푸시됨.

| 커밋 | 종류 | 한 줄 |
|---|---|---|
| `78db8de` | feat | 챗 세션 리스트를 사이드바 `data-mode="sessions"` 로 이동, 플로팅 `#session-panel` 제거 |
| `cad431d` | docs | UI_API_MAPPING 거짓 중복 정정 (`/admin/metrics` ↔ `/admin/performance/metrics/` 은 별개) + 로그인 콜러 3→4 정정 |
| `b829033` | refactor | `Auth.resetPasswordConfirm()` 추출 (chat + admin) |
| `be5609c` | refactor | `Auth.login()` 추출 (chat + admin + graph + workspace 4 콜러) |
| `9fe9275` | refactor | `LlmInstall` 컨트롤러 추출 (`/llm/install/` + `/admin/llm/install-progress` 폴링) |
| `539af37` | docs | `docs/UI_API_MAPPING.md` — 133 엔드포인트 ↔ UI 호출 매핑 + 고아/중복/충돌 분석 |
| `e5dab3d` | docs | `docs/UI_IA.md` — 5영역 IA 계약 (Ask / My Work / Govern / Observe / Configure) |

코드 변화 누계: 신규 모듈 3개(`auth.js`, `llm-install.js`, UI 사이드바
세션 패널), 콜러 합계 약 **-272 줄**. 동작 보존 (정적 검증만 — 브라우저
미검증).

---

## 2. 핵심 산출 문서 (반드시 먼저 읽기)

| 파일 | 역할 |
|---|---|
| `docs/UI_IA.md` | 5영역 IA **계약**. UI 의 형태가 수렴해야 할 곳. §3.2 의 17탭 재분배표가 Phase 3 의 입력. |
| `docs/UI_API_MAPPING.md` | 133 엔드포인트 ↔ UI 호출 **매핑 + 분석**. §3 고아 20개, §5 중복 5쌍(정정 후), §6 영역 충돌 7개, §9 액션 체크리스트. |

---

## 3. Phase 진행 상황

`docs/UI_API_MAPPING.md §9` 의 4 Phase 기준:

### Phase 1 — Cleanup (doc-only 부분만 완료)

- [x] `/admin/metrics` 거짓 deprecation 회피 (`cad431d`). 두 엔드포인트는
      별개 기능 (전자=trace 지연 histogram, 후자=자기평가 점수).
- [ ] `/history/sessions/rename/`, `/history/long-term/`, `/feedback/stats/`
      유지/삭제 결정 — **product call 필요**, 코드 손대지 말 것.
- [ ] 18개 WIP 엔드포인트 (`/code/*`, `/analyze/*`, `/screen/*`,
      `/admin/wiki/resolve-relations` 등) 로드맵 라인 작성 또는 삭제.
- [ ] `/admin/web-search-status` — 대시보드 카드 복원 또는 엔드포인트
      삭제 결정.

### Phase 2 — Deduplication ✅ **완료**

- [x] `firstRunInstall()` → `LlmInstall.start()` 공통 모듈 (`9fe9275`)
- [x] `/login/` HTTP → `Auth.login()` (`be5609c`) — 4 콜러
- [x] `/password/reset/confirm` → `Auth.resetPasswordConfirm()` (`b829033`)

Phase 2 의 누락 부분(있다면): 로그인 **모달 마크업 자체**는 4개 HTML
파일에 흩어진 채. 마크업 단일화는 IA Phase 3 와 묶어서 진행 권장.

### Phase 3 — IA migration ❌ **미착수** (가장 큰 작업)

- [ ] `admin.js` (45+ API 호출, 17 탭) 을 Govern / Observe / Configure
      **3 모듈로 분할**. UI_IA.md §3.2 의 17→(5+8+5) 재분배 표 참조.
- [ ] `/admin/cr/` lifecycle hand-off 링크 (My Work → Govern → Observe).
      UI_IA.md §3.3 의 3 워크플로우 중 핵심.
- [ ] 읽기/쓰기 영역 분리 룰 적용: 7개 영역 충돌 엔드포인트 각각
      (`/admin/entities`, `/admin/character/`, `/admin/persona`, `/admin/cr/`,
      `/admin/graph/relation`, `/admin/proposals/`, `/admin/patches`).
- [ ] `Configure → LLM` 화면 배선 — `/admin/llm/selections`,
      `/admin/llm/select` (POST/DELETE) 가 백엔드만 있고 UI 없음 (mapping
      doc §8 의 "반쪽 구현" 항목).

### Phase 4 — Naming (deferred)

API 엔드포인트 `<area>` prefix 정렬, `data-action` 대량 rename. v0.4
후보로 보류.

---

## 4. 진행 중 작업의 검증 부채 ⚠️

**원격 컨테이너 환경 = 브라우저 미접근.** Phase 2 + 챗 사이드바 작업은
`node --check` 정적 검증만 통과. 다음 세션에서 사용자가 띄워 다음 6개
**골든 패스**를 확인해야 함:

1. 상단 헤더 💬 클릭 → 사이드바가 `sessions` 모드로 열리고 리스트 로드
2. 다시 💬 클릭 → `upload` 모드로 복귀 (토글 의미 보존)
3. 리스트의 과거 세션 클릭 → 그 세션의 대화 turn 로드, 활성 하이라이트 이동
4. 사이드바 "+ 새 대화" → 새 SID 생성, 환영 화면 + 리스트 갱신
5. 세션 항목의 ✏️ 이름변경 / 🗑️ 삭제 정상 작동
6. 페이지 새로고침 → 마지막 사이드바 모드 복원 (localStorage `james_sidebar_mode`)

추가 회귀 점검 (Phase 2 결과):

7. 4 페이지 로그인 (chat / admin / graph / workspace) 모두 정상 — admin 은
   role check 통과, graph 는 bootstrap, workspace 는 reloadData
8. admin first-run wizard 모델 설치 → 모달 안 진행률 + 완료 자동 닫기
9. chat 페이지 `mode-install-btn` 모델 설치 → 버튼 % 갱신 + GB 표시
10. 비밀번호 재설정 모달 (chat / admin 양쪽) 정상

**브라우저 검증 전까지 main 머지 금지.**

---

## 5. 의사결정 / 규약 (이미 확정된 것)

이 트랙 진행 중 내려진 결정. 다음 세션은 재논의 없이 따르세요.

| # | 결정 | 의미 |
|---|---|---|
| D1 | IA 5영역: **Ask / My Work / Govern / Observe / Configure** | UI_IA.md §2. 모든 화면은 정확히 한 영역에 속함. |
| D2 | `admin.html` 단일 17 탭 페이지를 **3 페이지로 분할** (Govern / Observe / Configure) | UI_IA.md §3.2. Phase 3 의 헤드라인 작업. |
| D3 | `data-action` 명명: `<area>:<noun>:<verb>` (예: `govern:cr:approve`) | UI_IA.md §4.1. 마이그레이션은 alias map 으로 점진적. |
| D4 | **API endpoint rename 은 v0.4 candidate** | UI_IA.md §4.3. Phase 3 시점에는 기존 119+ 엔드포인트 그대로 호출. |
| D5 | 모달 markup 자체의 단일화는 Phase 3 작업 (로그인 모달 4개, forgot-password 2개) | Phase 2 에서 HTTP wrapper 만 추출, markup 은 페이지별로 유지. |
| D6 | `/admin/metrics` ≠ `/admin/performance/metrics/` (정정 후) | 둘 다 라이브, deprecate 금지. UI_API_MAPPING.md §5 correction box. |
| D7 | 챗 세션 리스트는 **사이드바 `data-mode="sessions"`** 로 이동, 플로팅 `#session-panel` 제거 | `78db8de`. `#session-list` / `#session-count-badge` ID 보존. |
| D8 | 영역 충돌 엔드포인트의 **읽기/쓰기 분리 룰**: 읽기는 어느 영역에서나 보이게, 쓰기는 해당 영역의 액션 버튼이 deep-link 로 정확한 영역으로 보냄 | UI_API_MAPPING.md §6. 7개 엔드포인트 적용 대상. |

---

## 6. 미세 회귀 / 부채 (인식해두기)

Phase 2 작업으로 생긴 작은 i18n 부채. 차후 수습 대상:

- `Auth.login()` 의 유효성 검사 메시지는 하드코드 한국어. admin.js
  doAdminLogin 의 원래 `t('auth.password_required')` 호출은 사라짐 — 영문
  사용자 입장에서 "아이디와 비밀번호를 입력하세요." 가 보임. 영향 적음,
  수습은 Auth.* 가 i18n 키를 옵션으로 받게 하거나 콜러에서 pre-validate.
- 같은 패턴이 `Auth.resetPasswordConfirm()` 에도 — admin 의 `t('auth.reset_fill_all')` 가
  하드코드로 대체됨.
- graph.js 의 로그인 에러 메시지가 영문 → 한국어로 미세 변경 (`'API key required (set on chat page or paste here)'` → `'API Key를 입력하세요.'`).
- 이상 3건 모두 Phase 3 에서 모달 마크업 통일하면서 같이 정리하면 자연스러움.

---

## 7. 다음 세션 추천 진입 순서

우선순위 순. 사용자 명시 지시가 없으면 (a)부터.

### (a) 브라우저 검증 + 미세 fix
- §4 의 골든 패스 10개 실행
- 회귀 발견 시 즉시 fix 커밋
- 이후 main PR 만들 수 있는 상태로 정리

### (b) Phase 1 미결정 항목 결정
사용자 product call 필요. AskUserQuestion 으로 다음을 결정:
- `/history/sessions/rename/`, `/history/long-term/`, `/feedback/stats/` 유지/삭제
- 18개 WIP 엔드포인트 (`/code/*`, `/analyze/*` 등) 로드맵 vs 삭제
- `/admin/web-search-status` 대시보드 카드 복원 vs 엔드포인트 삭제

### (c) Phase 3 PoC — `admin.js` 분할
가장 큰 일. 권장 진행 방식:
1. `admin.js` 의 45+ API 호출을 UI_IA.md §3.2 표대로 3 그룹으로 색인
2. 새 파일 3개: `frontend/static/govern.js`, `observe.js`, `configure.js`
3. 각 그룹의 함수를 이동, 공유 유틸은 `admin-common.js` (또는 `auth.js` 확장)
4. HTML 측: `admin.html` 의 17 탭을 3 페이지(`/govern`, `/observe`, `/configure`)로 분할 또는 한 페이지 안에서 영역 sub-tab 으로 재배치 (선택 결정 필요)
5. 백엔드 라우팅 — Phase 3 에서는 **URL 안 바꾸기** (D4). 그냥 새 HTML 페이지에서 기존 API 호출.

PoC 단위: Govern 분할만 먼저 (5탭: users, patches, proposals, cr, features).
검증 후 Observe / Configure 진행.

### (d) `Configure → LLM` 화면 배선
`/admin/llm/selections` + `/admin/llm/select` POST/DELETE 가 백엔드만
존재. UI 가 생기면 task→model 매핑이 라이브로 가능. Phase 3 의 Configure
분할과 같이 묶어서 진행 가능.

### (e) 로그인 모달 마크업 통일
4 HTML 파일의 모달 markup (서로 다른 DOM ID, 다른 필드) 을 단일
컴포넌트로. JS 동적 삽입 또는 Web Components 검토. 비교적 큰 작업이라
Phase 3 와 묶어서.

---

## 8. 중요 파일 빠른 참조

```
docs/UI_IA.md                       — IA 5영역 계약
docs/UI_API_MAPPING.md              — 133 API ↔ UI 매핑 분석
docs/handovers/v0.3.x-ui-ia-track.md — 이 문서

frontend/static/auth.js             — Auth.login + Auth.resetPasswordConfirm (Phase 2)
frontend/static/llm-install.js      — LlmInstall.start (Phase 2)

frontend/static/chat.js             — 챗 페이지 로직 (사이드바 sessions 모드 통합 완료)
frontend/static/admin.js            — 73KB / 17탭 / 45+ API. Phase 3 의 분할 대상
frontend/static/graph.js, workspace.js  — 작은 페이지
frontend/static/i18n.js             — sidebar.mode_sessions 추가됨

frontend/index.html                 — 사이드바 + 헤더. data-mode="sessions" rail 신규
frontend/admin.html                 — 73KB. Phase 3 분할 대상
frontend/graph.html, workspace.html — 작은 페이지

server_llmwiki.py                   — 133 엔드포인트 정의. Phase 3 에서 URL 변경 금지 (D4)
```

---

## 9. 절대 하지 말 것

`CLAUDE.md` 상위 규칙 + 이 트랙 고유:

- ❌ `/admin/metrics` 또는 `/admin/performance/metrics/` 둘 중 하나
  deprecate (D6) — 별개 기능
- ❌ Phase 3 진입 전에 `admin.js` 일부만 무분별하게 옮기기 (반드시
  UI_IA.md §3.2 의 17→(5+8+5) 표를 따를 것)
- ❌ Phase 3 에서 API 엔드포인트 URL 변경 (D4)
- ❌ 도메인 특화 코드 추가 (CLAUDE.md rule #1)
- ❌ 브라우저 검증 없이 main 머지
- ❌ `#session-list` / `#session-count-badge` DOM ID 변경 (D7 호환성)

---

## 10. 한국어 한 줄 결론

UI 정돈은 **계약 + 매핑 + 중복 제거 + 사이드바 통합**까지 끝. 다음
세션의 진짜 일은 `admin.js` 삼분할(Phase 3) — 그 전에 브라우저로
이번 변경 검증부터.
