refactor(ui): split maestro components and lock execution order

Author: 파트라슈

docs/DEV_LOG_2026-02-28.md

@@ -28,6 +28,8 @@
 | 2026-02-28 01:25 | `e61fd42` | 승인/반려/롤백 실연결 통합 스모크 자동화 |
 | 2026-02-28 10:25 | `d6e3e0c` | 터치스크린용 승인/반려/UNDO 버튼 추가 |
 | 2026-02-28 15:00+ | (working tree) | `WP-006` 구현: `check:env` + `start:app` 런처 + 트러블슈팅 가이드 반영 |
+| 2026-02-28 17:00+ | (working tree) | `WP-007` 2차: 헤더/탭/레인/푸터/미리보기 모달 컴포넌트 분해 |
+| 2026-02-28 18:00+ | (working tree) | 착수 순서 고정 + 기존 기능 비손상/비오염 선언 문서화 |
 
 ## 3) 이번 구간 성과
 
@@ -60,7 +62,7 @@
 
 - 단계: MVP+ (핵심 플로우 + QA 자동화 + 터치 지원)
 - 파일 규모: 추적 파일 약 30개
-- 구조 리스크: `src/App.jsx` 1228 lines (단일 파일 집중도 높음)
+- 구조 리스크: `src/App.jsx` 691 lines (분해 진행 중, 추가 축소 필요)
 - 번들 상태: `vite build` 기준 JS 227.84 kB (gzip 71.34 kB)
 - 오픈 이슈: `KI-001` (`function bach` Hz 일부 환경 미노출)
 
@@ -74,9 +76,9 @@
 
 ## 6) 다음 단계
 
-1. `WP-006` 완료: 설치 단순화 1차(원클릭 실행형 런처 + preflight + 문서)
-2. 다음 우선순위: `WP-007` (`App.jsx` 모듈 분해, 컨텍스트/유지보수 최적화)
-3. 정식 회고 문서 완료: `docs/RETRO_WP-006.md`
+1. 다음 우선순위: `WP-007` 3차(게임/입력/WebSocket 로직 훅 분리)
+2. 다음 우선순위: 테스트 분해(`App.ui.test.jsx` 기능 단위 스위트화)
+3. 이후 `WP-008`(조건부 자동승인) -> `WP-009`(승인 이력 악보뷰) 순서 고정
 
 ## 7) 다음 회고에서 반드시 비교할 지표
 

docs/QA_AGENT.md

@@ -2,6 +2,18 @@
 
 기준일: 2026-02-27
 
+## 작업 원칙 선언 (2026-02-28)
+
+- QA 에이전트의 1순위 목적은 신규 기능 추가보다 기존 기능 비손상/비오염 보장이다.
+- 변경 시 아래 기능은 기본 보존 대상이며, 하나라도 회귀 시 실패로 처리한다.
+  - 승인/반려/롤백
+  - 온라인/목업 상태배지
+  - 키 타격음/주파수 시각화
+  - `function bach`(재생/일시정지/볼륨/채널 설정)
+  - 터치 입력 경로(버튼 승인/반려/UNDO)
+- 착수 순서는 `docs/WORK_PLAN.md` 0번 섹션 고정 순서를 따른다.
+- 고정 순서 외 변경이 필요하면 착수 전에 계획 문서를 먼저 갱신한다.
+
 ## 목적
 
 `Maestro`의 핵심 플로우(요청 수신, 인증, 브로드캐스트, 빌드 가능성)를 변경마다 반복 검증하여
@@ -74,4 +86,5 @@ npm run smoke:integration
 - `npm run qa` 성공
 - (CI) `qa-gate` 워크플로의 `qa` + `e2e` job 성공
 - WP 대상 수동 체크리스트 통과
+- 기능 보존 대상(선언 섹션) 회귀 0건
 - 실패 시 다음 단계 진행 금지, 원인 수정 후 재실행

docs/WORK_PLAN.md

@@ -2,6 +2,23 @@
 
 기준일: 2026-02-28
 
+## 0) 착수 순서 고정 + 비손상/비오염 선언 (2026-02-28)
+
+선언:
+
+- 지금부터 작업 착수 순서는 아래 순서로 고정한다.
+- 기존 핵심 기능(승인/반려/롤백/상태배지/`function bach`/터치 입력)은 손상 또는 동작 오염 없이 유지한다.
+- 기능 수정 시 변경 범위를 최소화하고, 영향 없는 영역은 수정하지 않는다.
+- 회귀 징후가 발견되면 즉시 다음 단계 진행을 중단하고 원인 수정 후 동일 게이트를 재통과한다.
+
+고정 착수 순서:
+
+1. `WP-007` 3차: 게임/입력/WebSocket 로직 훅 분리
+2. 테스트 분해: `App.ui.test.jsx` 기능 단위 스위트 분리
+3. 설치 경로 운영 안정화: `start:app` 오류 메시지/가이드 고도화
+4. `WP-008` 조건부 자동승인 기능 설계/리스크 검토/안전장치 적용
+5. `WP-009` 승인 이력(악보 컨셉) 설계/구현/회귀 검증
+
 ## 1) 현재 상태 요약
 
 - 현재 단계: MVP (핵심 데모 흐름 동작)
@@ -23,17 +40,18 @@
 - `WP-004` 완료: 기본 바인딩(`HOST=127.0.0.1`) + Origin 화이트리스트 CORS 반영
 - `WP-005` 완료: 서버/UI/E2E + CI 게이트 + 통합 스모크(`npm run smoke:integration`) 반영
 - `WP-006` 완료: `check:env` preflight + `start:app` 원클릭 런처 + 가이드 반영
-- `WP-007` 진행중: 1차 모듈 분해(상수/저장소/오디오/YouTube 유틸 분리) 완료
+- `WP-007` 진행중: 1차(상수/유틸 분리) + 2차(UI 컴포넌트 분해) 완료
 - QA 에이전트 설정 완료: `npm run qa` + 회귀 테스트 스위트 + QA 가이드 추가
 - `function bach` 1차 완료: 상단 미니 플레이어, 채널 URL 저장, 재생/일시정지/볼륨, 주파수(Hz) 시각화 반영
 - 터치 입력 대응 완료: 레인 승인/반려 버튼 + 터치 롤백 버튼 + UI 회귀 테스트 반영
 - 오픈 이슈 분리 추적: [`docs/KNOWN_ISSUES.md`](./KNOWN_ISSUES.md) (`KI-001`: `function bach` Hz 미노출 환경 조사)
 
 ## 1-2) 다음 작업 포인트 (즉시 실행)
 
-1. 컨텍스트/유지보수 최적화: `WP-007` 2차(UI 컴포넌트 분해) 진행
-2. 설치 경로 운영 안정화: `start:app` 사용 데이터 기반 오류 메시지/가이드 고도화
-3. 문서 최신화: 현재 상태/작업순서를 README/USER_GUIDE/WORK_PLAN에 지속 동기화
+1. 컨텍스트/유지보수 최적화: `WP-007` 3차(게임/입력/WebSocket 로직 훅 분리) 진행
+2. 테스트 분해: `App.ui.test.jsx`를 기능 단위 스위트로 분리
+3. 설치 경로 운영 안정화: `start:app` 사용 데이터 기반 오류 메시지/가이드 고도화
+4. 이후 `WP-008`/`WP-009`는 0번 섹션의 고정 순서대로만 착수
 
 ## 1-3) 즉시 실행 결과 (2026-02-28)
 
@@ -51,7 +69,7 @@
   - 여전히 `.env` 설정과 환경오류 대응(포트/경로) 가이드는 지속 개선 필요
 - 코드/컨텍스트 규모
   - 전체 추적 파일 수: 약 30개
-  - `src/App.jsx`: 1228 lines (단일 파일 집중도 높음)
+  - `src/App.jsx`: 691 lines (분해 진행 중, 추가 축소 필요)
   - UI 상태/이펙트 훅 수가 많아(30+), 변경 시 회귀 영향 범위가 넓음
 - 런타임/번들
   - `vite build` 기준 JS 번들 약 228 kB (gzip 71 kB)로 현재 성능 병목은 크지 않음
@@ -106,6 +124,7 @@
 - `README`에서 현재 단계와 다음 작업이 한눈에 확인되어야 함
 - 설치 단순화 목표(`단일 실행 명령`)가 실제 환경(macOS/Windows)에서 재현되어야 함
 - 구조 분해 후에도 기존 승인/반려/롤백/`function bach` 기능이 동일 동작해야 함
+- 고정 순서 외 작업 선착수 금지(예외 시 계획문서 선반영 + 승인)
 
 ## 5) 실행 방식 검토 (Single vs Multi-agent)
 
@@ -121,6 +140,49 @@
   - 공통 파일(`maestro-server.js`, `src/App.jsx`, `README.md`) 동시 수정 작업은 분리하지 않음
   - 병렬 작업이 필요하면 파일 경계를 명확히 나눈 뒤 통합
 
+## 5-1) 멀티에이전트 적용 범위 분석 + 단계별 계획 (2026-02-28)
+
+계획 수립 범위:
+
+- 현재 시점부터 `WP-009` 완료 + 안정화 게이트 통과 시점까지 계획을 고정한다.
+- `WP-010` 이후는 `WP-009` 결과(성능/운영 데이터) 확인 후 별도 수립한다.
+
+단계별 실행 모델:
+
+| 단계 | 범위 | 권장 방식 | 이유 |
+|---|---|---|---|
+| Stage 0 | `WP-007` 3차 훅 분리 | 단일에이전트 | `src/App.jsx`/입력/소켓 상태가 강결합, 충돌 위험이 가장 큼 |
+| Stage 1 | 테스트 분해 + `start:app` 안정화 | 2에이전트 병렬 가능 | 테스트/운영 가이드는 파일 경계 분리가 쉬움 |
+| Stage 2 | `WP-008` 조건부 자동승인 설계/구현 | 3에이전트 병렬 가능 | 서버 규칙/프론트 UI/QA를 파일 경계로 분리 가능 |
+| Stage 3 | `WP-009` 승인 이력(악보뷰) 설계/구현 | 3에이전트 병렬 가능 | 이력 저장/API/UI 렌더링을 독립 트랙으로 분리 가능 |
+| Stage 4 | 통합/회귀/릴리즈 문서화 | 단일에이전트 | 최종 통합 판단과 회귀 차단은 단일 의사결정이 안전 |
+
+에이전트 역할 분리(권장):
+
+1. Core Agent
+   - 담당: 승인 규칙/조건부 자동승인 정책, 서버 이벤트, 훅/도메인 로직
+   - 주요 파일: `maestro-server.js`, `hooks/*`, `src/hooks/*`, `src/features/*`
+2. UI Agent
+   - 담당: 악보 이력 시각화, 상호작용 UX, 접근성/반응형 유지
+   - 주요 파일: `src/components/maestro/*`, `src/App.jsx`, `src/index.css`
+3. QA Agent
+   - 담당: 회귀 테스트 분해/보강, 통합 스모크, E2E 시나리오
+   - 주요 파일: `tests/*`, `src/App.ui.test.jsx`, `scripts/smoke-agent-integration.sh`, `docs/QA_AGENT.md`
+
+통합 순서(고정):
+
+1. Stage 0 완료 + `npm run qa` 통과
+2. Stage 1 병렬 완료 후 통합 + `npm run qa`
+3. Stage 2 병렬 완료 후 통합 + `npm run qa` + `npm run smoke:integration`
+4. Stage 3 병렬 완료 후 통합 + `npm run qa` + `npm run smoke:integration` + `npm run test:e2e`
+5. Stage 4에서 문서/운영가이드 동기화 후 main 반영
+
+리스크 및 차단 규칙:
+
+- `src/App.jsx`/`maestro-server.js` 동시 병렬 수정은 금지(충돌/회귀 확률 높음)
+- 자동승인(`WP-008`)은 기본값 `OFF`로 시작하고, 명시 조건 충족 시에만 활성화
+- 회귀 1건이라도 발생 시 다음 단계 진행 중단, 원인 수정 후 동일 게이트 재통과
+
 ## 6) 추가 기능 계획: `function bach`
 
 목표: 효과음과 별개로 대시보드에서 유튜브 기반 배경음악(BGM)을 재생/제어.