# UI Production Readiness

이 문서는 APP/Web/PC 화면을 `최소 시연 수준`으로 낮춰 만드는 것이 아니라, 구현하는 화면은 가능한 범위에서 production-level UI 품질로 올리기 위한 기준이다.

`docs/10-product/MVP_SCOPE.md`는 기능 범위와 대표 검수 흐름을 정한다. 이 문서는 UI 품질 목표와 미흡한 부분을 추적한다. 즉, 7월 10일 범위가 Must/Should/Later로 나뉘더라도 Must 또는 Should로 구현하는 화면은 임시 UI가 아니라 실제 현장 사용자가 반복 사용해도 어색하지 않은 수준을 목표로 한다.

## Principle

- 기능 범위는 단계적으로 자르되, 구현된 화면의 UI 품질은 낮추지 않는다.
- mock API first라도 화면 상태, density, empty/error/loading, permission, offline/retry copy는 production 상황을 상정한다.
- Figma pixel sync는 출발점이다. Figma에 design system이 충분히 정리되지 않은 부분은 repo의 token/component 기준으로 보완한다.
- placeholder는 숨기지 않는다. 미완성 영역은 화면, UX index, PR, test graph에서 명시한다.
- production-level UI는 backend, store release, 외부 provider 연동 완료를 뜻하지 않는다.

## Production-level UI Definition

| 기준 | 완료 조건 |
|---|---|
| Visual parity | Figma의 layout, density, hierarchy, status color, icon 사용이 화면 목적과 일치한다. 의도적 차이는 PR에 이유를 남긴다. |
| Responsive device fit | 375dp 기준 고정 폭을 그대로 쓰지 않고, Android/iOS device width와 font scale 변화에서도 깨지지 않는다. |
| State completeness | 기본, loading, empty, error, permission denied, success, disabled, conflict 가능 상태 중 해당되는 상태가 표현된다. |
| Role clarity | 배출자, 배차담당자, 운전자, 처리자 간 정보/CTA가 섞이지 않고 현재 role이 화면에서 분명하다. |
| Interaction polish | tap target, pressed/disabled state, modal/sheet/back hierarchy, keyboard, scroll position이 자연스럽다. |
| Testability | 주요 interactive element는 stable `testID`, accessibility role/label, Maestro 또는 agent-device evidence를 가진다. |
| Component reuse | 두 화면 이상 반복되는 header, bottom tab, card, badge, filter, list row, modal/sheet는 shared component 후보로 관리한다. |
| Copy quality | visible copy는 Figma/요구사항 기준 한국어를 사용하고, 임시 개발자 문구나 설명형 help text를 노출하지 않는다. 사용자가 보는 문장에는 `mock`, `backend`, `provider`, `test`, `badge`, `route`, `contract`, `API 계약`, `handoff` 같은 구현 용어를 그대로 쓰지 않는다. |
| Performance posture | 긴 list, chat, 이미지/첨부, camera/OCR flow는 화면 단계에서 virtualization, asset size, loading strategy를 고려한다. |

## Quality Gates

화면 PR은 아래 gate 중 해당되는 항목을 통과해야 production-level UI 후보로 본다.

| Gate | APP | Web/PC |
|---|---|---|
| Static type | `pnpm --filter @zerro/mobile check` | app별 TypeScript check |
| Lint/static | `pnpm --filter @zerro/mobile lint` 또는 package gate | app별 lint/static gate |
| Unit/domain | mock selector, status 계산, mutation branch | service/model/schema unit test |
| Coverage | contracts/mocks/domain branch 변경 시 coverage 확인 또는 gap 기록 | unit coverage report 또는 gap 기록 |
| E2E | 관련 Maestro flow 또는 명시적 backlog | Playwright + AI Computer Use |
| Real surface | `agent-device` selector snapshot 또는 조작 로그 + clean app screenshot | browser screenshot 또는 Playwright trace |
| Design evidence | Figma node, red-box overlay 없는 app screenshot, 차이 기록 | Figma node, browser screenshot, 차이 기록 |
| Coverage graph | `apps/mobile/e2e/TEST_COVERAGE_GRAPH.md` 갱신 | Web/PC coverage 문서 또는 PR checklist |

## Current UI Gap Snapshot

2026-07-06 기준 snapshot이다. `mock-covered` 또는 `provider-pending-covered`는 APP 사용자가 보는 surface가 있다는 뜻이며, 실제 backend/provider/realtime contract가 닫혔다는 뜻이 아니다.

| 영역 | 현재 상태 | 남은 production/backend 보강 |
|---|---|---|
| 배출자 APP shell | 홈, 알림, 더보기, 채팅 preview/detail evidence가 `mock-covered` 상태다 | backend read-state, push provider, 고객센터 provider, realtime/upload provider는 후속 decision |
| 배출자 배출 신청/현황 | wizard validation/state, history/detail, cancel pending, 반입 확인서 viewer surface가 mock/provider-pending으로 닫혔다 | 실제 저장, 올바로 연동, cancel backend mutation, PDF/file provider는 후속 backend/provider 계약 |
| 배차담당자 APP | 홈, 배차하기, 예외/empty/conflict, 공통 chat/notification shell, responsive evidence가 확보됐다 | 실제 cancel/reassign/concurrency API, drag/drop board, realtime conflict resolution은 후속 backend 계약 |
| 운전자 APP | 홈, 배차 확인, 오늘 일정, route/proof/OCR/dropoff, 배차표와 provider-pending/offline/retry surface가 닫혔다 | 실제 GPS/map/phone/upload/OCR provider와 offline persistence는 후속 decision |
| 처리자 APP | 계근/OCR, 입고 예정/상세, conflict/replay/idempotency mock UX, 처리 실적 projection이 구현됐다 | 실제 backend conflict envelope, idempotency persistence, upload parsing, 처리 실적 history API는 후속 계약 |
| 공통 채팅 | emitter/dispatcher/processor room/list/detail, lifecycle card, `@kesha-antonov/react-native-chat` room surface, attachment action sheet, bundled image/video preview surface가 있다. Backend read-state persistence와 APP room list/detail/read/send runtime binding은 연결됐다. Figma `356:989` 기준 room 본문에는 visible read-state summary나 explicit load-more CTA를 두지 않는다 | file picker/upload provider, APP foreground realtime native transport, OS push provider를 정한다. 운전자 APP은 Figma `314:2804` 기준 chat surface 대상이 아니다 |
| 공통 알림 | role별 filter, read-state/badge projection, lifecycle notification proof, category별 detail route가 있다 | 실제 push provider, server read-state persistence, notification deep link 저장은 후속 backend/provider 계약 |
| APP safe area / density | role shell과 핵심 child surface의 clean responsive evidence가 확보됐다 | 특정 child surface에서 narrow/wide/font-scale 회귀가 발견되면 targeted follow-up으로 확장한다 |
| Web/PC | Next.js mock API 기반 작업이 병행 중이다 | current source 기준으로 남은 interaction을 재확인하고 Playwright + AI Computer Use evidence를 남긴다 |
| UX index | local HTML은 review artifact이고 tracked 상태는 coverage graph가 맡는다 | 새 screen/route/CTA마다 HTML, screenshot, coverage graph 의미가 함께 바뀌는지 확인한다 |

## Documentation Rules

- `docs/10-product/MVP_SCOPE.md`는 기능 scope와 대표 검수 흐름 문서다. UI 품질 목표를 낮추는 문서가 아니다.
- production-level UI 목표가 바뀌면 이 문서를 먼저 갱신한다.
- 화면 구현 범위가 바뀌면 `docs/10-product/MVP_SCOPE.md`, `docs/20-contracts/API_CONTRACT.md`, `docs/10-product/RBAC_MATRIX.md` 중 영향 문서를 같이 확인한다.
- APP 화면 구현 시 `apps/mobile/DESIGN.md`, `docs/40-mobile/WORKING_AGREEMENT.md`, `apps/mobile/e2e/TEST_COVERAGE_GRAPH.md`를 함께 확인한다.
- APP의 UX index, Figma 비교, PR, 보고용 screenshot은 red box/E-label overlay가 없는 clean capture를 사용한다. `agent-device` overlay screenshot은 selector/debug proof로만 분리한다.
- Web/PC 화면 구현 시 `docs/50-web/WORKING_AGREEMENT.md`와 role별 Playwright/Computer Use evidence를 함께 확인한다.

## 7월 10일 Target Reframe

기존 7월 10일 초기 화면 산출물 표현은 다음처럼 해석한다.

| 이전 해석 | 새 기준 |
|---|---|
| 7월 10일까지 최소 시연 화면만 만든다 | 7월 10일까지 가능한 화면은 production-level UI 후보로 만든다 |
| backend가 없으므로 UI도 임시여도 된다 | backend가 없을수록 UI state와 mock contract를 더 명확히 만든다 |
| placeholder는 화면 밖에 둔다 | placeholder는 숨기지 않고 disabled reason, empty state, UX index로 표시한다 |
| 검수 happy path만 맞으면 된다 | happy path와 함께 error/empty/permission/conflict 후보를 화면 계약에 남긴다 |

따라서 7월 10일 산출물은 `완성품`이 아니라 `production UI 방향으로 설계된 mock-first product surface`다.