# 관리자 프로토타입 커버리지 구현 설계

감사에서 드러난 101개 미커버 · 31개 부분 커버 서피스를 프로토타입에 채워 넣기 위한 설계. 이 문서는 *무엇을 어떤 순서로, 어떤 규칙으로* 만드는지를 정한다. 화면별 상세 목록은 감사 문서에 있다.

- **감사 문서**: [2026-08-19-admin-coverage-audit.md](2026-08-19-admin-coverage-audit.md)
- **대상**: `admin/` (prototype.startview.co.kr/admin/)
- **기준**: `startview-platform-admin/apps/admin`
- **작성일**: 2026.08.19

## 확정된 선택

| 질문 | 선택 | 이유 |
| --- | --- | --- |
| 순서 | **패턴 먼저, 그다음 모듈** | 미커버 101개 중 약 60개가 6개 반복 패턴의 인스턴스. 패턴을 먼저 만들면 이후 모듈이 싸진다 |
| 완료 기준 | **현재 프로토타입과 같은 수준** (목 데이터로 상호작용) | 프로토타입이 클릭 가능한 하나의 산출물로 유지된다 |
| 파일 구조 | **데이터 분리, 렌더 파일은 단일 유지** | 파일의 대부분이 목 데이터. 위험 대비 이득이 가장 크다 |
| 범위 | **전부 포함** (SUPER_ADMIN · 플래그 모듈 · 고아 화면 · 성과 보고서) | 권한·플래그에 따라 달라지는 UI를 설계로 답해야 한다 |
| ux MCP | **페이즈 단위 게이트, 체크리스트 항목이 태스크가 된다** | 조용히 건너뛸 수 없게 만든다 |

---

## 1. 아키텍처

### 1.1 파일 구조

```
admin/
├── main.dc.html        ← 템플릿 + 컴포넌트 클래스만
├── data/
│   ├── tables.js       ← TABLES (목록 26종) + 컬럼 정의
│   ├── entities.js     ← CAMPAIGNS, PAYOUTS, BANNERS, 관리자 로스터, 픽스처
│   ├── settings.js     ← SETTINGS, FORM_SECTIONS
│   └── modules/*.js    ← 신규 모듈별 목 데이터 1파일
└── assets/ …
```

- 데이터 파일은 컴포넌트보다 먼저 로드되는 평범한 `<script src>` 전역이다. 커스텀 `sc-if`/`sc-for` 런타임을 건드리지 않으므로 로더가 새로 필요 없고, 배포는 그대로 `rsync`다.
- 기존 목 데이터 약 600줄을 먼저 밖으로 옮기면, 이후 모든 페이즈가 "한 파일에 300줄 추가"가 아니라 "데이터 파일 하나 + 템플릿 블록 하나"가 된다.

### 1.2 공용 렌더 프리미티브 3종

오늘의 만능 2종(테이블 1개, 파생 드로어 1개)을 다음으로 대체한다.

| 프리미티브 | 현재 | 이후 |
| --- | --- | --- |
| 목록 | 테이블 템플릿 1개, 페이징·선택 없음 | 테이블 템플릿 + 페이징·선택·일괄 액션 바·상태 세그먼트·필터 칩. 라우트별 config로 구동 |
| 상세 | `buildRowDetail` 이 컬럼에서 필드를 파생 | 선언된 섹션·관련 엔터티 목록·로그 블록·액션 바를 가진 상세 *템플릿*. 라우트별 config가 내용을 공급 |
| 다이얼로그 | 없음 (popover 2개) | 타입 4종: confirm · reason-input · value-input · side-drawer |

**핵심 변경**: 라우트의 깊이가 *파생*이 아니라 *선언된 config* 가 된다. `/reviewer` 는 자신의 세그먼트·필터 필드·일괄 액션·상세 섹션을 선언하고, 공용 템플릿이 그것을 렌더한다. 101개 서피스를 101개 맞춤 화면이 아니라 다룰 수 있게 만드는 것이 이 지점이다.

### 1.3 지키는 것

- 어휘: 프로토타입 현행 유지 (리뷰어 → **크리에이터**). 기존 앱의 표현을 역수입하지 않는다.
- 디자인 토큰: 기존 tone map · 간격 · 반경 유지. 신규 모듈이 기존에 맞춘다.
- 골든 스레드 데이터(보미 · 글로우드롭)는 페이즈 전반에서 일관되게 유지한다.

---

## 2. 페이즈

4개 스테이지 15개 페이즈. 각 페이즈는 독립적으로 배포 가능하고 독립적으로 리뷰 가능하다.

### 스테이지 P0 — 필수 (페이즈 0–8)

| # | 페이즈 | 산출물 |
| --- | --- | --- |
| 0 | 데이터 분리 | `data/*.js` 분리 + 목록당 40–60행으로 목 데이터 증량. 시각적 변화 없음 |
| 1 | **테이블 계약** | 페이지네이션 + 총 건수, 행 선택, 일괄 액션 바, 상태 세그먼트, 필터 모달 + 적용 필터 칩, 컬럼 정렬. 기존 26개 목록에 소급 적용 |
| 2 | **다이얼로그 계약 + 상태** | confirm / reason-input / value-input / side-drawer, 그리고 loading · error+retry · validation · success toast · disabled · no-results |
| 3 | **엔터티 상세 템플릿** | 회원 상세 + 기업 상세로 검증(섹션·관련 목록·로그·액션 바), 제네릭 드로어 대체 |
| 4 | 캠페인 상세 심화 | 운영 탭 5종, 상태 변경, 진행 스텝퍼, 취소·강제 완료·복사·보고서 액션 |
| 5 | 문의 | 3탭 셸, 문의 상세 + 답변 편집, 광고문의·비즈니스 상담 목록/상세/메모 |
| 6 | 돈이 움직이는 화면 | 지급 상태 탭 + 완료/실패 기록, 포인트 정산 신청, 입금 확인·환불 처리·반려, 브랜드존 결제 상세 |
| 7 | 브랜드 존의 빠진 절반 | 수요조사 목록·상세·폼·제안 목록·제안 상세, 수요 DB |
| 8 | 상품 + 성과 보고서 | 상품 등록/수정 + 미리보기, 성과 보고서 문서(광고주 대면) |

### 스테이지 P1 — 중요 (페이즈 9–11)

| # | 페이즈 | 산출물 |
| --- | --- | --- |
| 9 | 저작 폼 | 회원 수정, 기업 수정, 게시글 에디터 + 홈/카드 미리보기, 공지·FAQ 작성, 브랜드 등록/수정 + 포지션 조정기 |
| 10 | 잔여 상세 | 상품 상세, 게시판 상세, 공지·FAQ 상세, 협업 검수/정산 조치, 예약·영상 검수 모달군 (대부분 페이즈 2 다이얼로그 적용) |
| 11 | 권한 | 로그인, 관리자 관리 목록·상세·등록·로그, **역할별로 달라지는 사이드바** |

### 스테이지 P2 — 보조 (페이즈 12–13)

| # | 페이즈 | 산출물 |
| --- | --- | --- |
| 12 | 플래그 모듈 | 공동구매 2화면, 어필리에이트 2화면(선행 조건 차단 상태 포함), 플래그로 메뉴가 사라지는 상태 |
| 13 | 나머지 모듈 | 프롬프트 관리 4화면, 대시보드 애널리틱스 6도넛, 배너 폼, 비활성 게시글, 게시판 폼, 요금제·가이드 게시글 |

### 스테이지 P3 — 마감 (페이즈 14)

비회원 캠페인 목록, 페널티 정책, 샵바이 콜백, 순서 변경 모드, 이용월 선택, 잔여 빈 상태·확인 다이얼로그.

### 의존성

- 페이즈 1–3 은 새 내비게이션 항목을 만들지 않는다. 패턴 우선 선택의 대가로, 눈에 보이는 진척이 3페이즈 동안 없다.
- 페이즈 4–14 는 전부 페이즈 1–3 의 프리미티브에 의존한다.
- **페이즈 11(역할별 사이드바)은 페이즈 12–13의 선행 조건**이다. 플래그·SUPER_ADMIN 모듈이 조건부로 나타날 자리가 필요하다.

---

## 3. 모든 페이즈가 동일하게 수행하는 루프

계획 문서는 이 루프를 한 번만 기술하고, 각 페이즈는 입력만 지정한다.

### 3.1 ux 게이트 (페이즈 시작)

1. `get_guidance("<이 페이즈가 만드는 것> + <운영자가 겪는 문제>")`
2. `get_checklist("<컴포넌트 또는 페이지>")` — 이미 존재하는 관련 체크리스트: Admin Panel, User Management, Single Item Detail, Empty State, Multi-step form, Search Results, Settings, Login, Notifications, Table, Tabs
3. **충족되지 않은 체크리스트 항목은 전부 그 페이즈의 명시적 태스크가 된다.** 의도적으로 건너뛰는 항목은 이유와 함께 "건너뜀"으로 기록한다 — 게이트를 조용히 무력화할 수 없게 한다.
4. 자명하지 않은 설계 결정은 `get_law` 로 근거를 인용한다.

**페이즈 1이 이미 확보한 근거** (2026.08.19 조회): Cognitive Load · Chunking · Selective Attention. Table 체크리스트 항목 — 헤더, 행 스타일, 간격, 검색, 액션, 필터·정렬, 반응형, 페이지네이션. Tabs 체크리스트 항목 — 라벨, 콘텐츠 영역, 스타일, 항목 순서, 상태(기본·활성·호버). ux MCP 가 도중에 불가하면 페이즈는 기록된 근거로 진행한다.

### 3.2 화면별 완료 기준

- 실제 해시 라우트로 도달 가능하고, 내비게이션 또는 부모 화면에서 도달 가능하다
- 검색 / 필터 / 탭 / 선택 상태가 목 데이터에 대해 실제로 동작한다
- 행이 상세를 연다. 다이얼로그가 열리고, 동작하고, 닫힌다
- 빈 상태가 있다. 한국어 문구가 프로토타입의 기존 어투를 따른다
- 목록과 상세가 1440에서 렌더되고 가로 스크롤이 생기지 않는다

### 3.3 검증 (완료 선언 전)

브라우저에서 프로토타입을 띄우고 해당 페이즈의 플로우를 걷는다. 새 화면을 스크린샷으로 남기고 콘솔이 깨끗한지 확인한다. "코드가 맞아 보인다"로 페이즈를 닫지 않는다.

### 3.4 배포

커밋(AI 어트리뷰션 없음) → `admin/` rsync → 라이브 확인.

---

## 4. 위험

| 위험 | 완화 |
| --- | --- |
| 페이즈 1–3 이 기존 26개 목록을 소급 수정한다 — 회귀 시 오늘 동작하는 화면이 깨진다 | 페이즈 0의 동일 렌더 확인 + 페이즈마다 손대지 않은 목록 3개를 직접 걸어본다 |
| 목 데이터 양: 페이징이 의미를 가지려면 목록당 8행으로는 부족하다 | 페이즈 0에서 기존 시드로부터 목록당 40–60행 생성. 골든 스레드 레코드는 고정 유지 |
| 선언형 상세 템플릿이 제2의 `buildRowDetail` — 제네릭하고 얕은 것 — 이 될 수 있다 | 페이즈 3에서 가장 두꺼운 두 엔터티(회원·기업)로 먼저 검증한다. 표현하지 못하면 다른 모듈이 채택하기 전에 탈출구를 만든다 |
| ux MCP 가 중간에 끊긴다 | 각 페이즈가 참조한 가이던스를 계획 문서에 기록한다. 페이즈는 기록된 근거로 진행 가능하다 |

---

## 5. 범위 밖

- 리뷰 레이어 / 코멘트 시스템 변경
- 프로토타입을 기존 앱의 정확한 필드 목록에 일치시키는 작업 — 감사는 커버리지 지도이지 필드 명세가 아니다
- 기존 풀스택 어드민 코드 변경. 이 계획은 프로토타입만 건드린다