release: v0.10.0

apps/site/research/showcase-duo-implementation-blueprint-2026-08-29.md

@@ -0,0 +1,216 @@
+# 두 쇼케이스 구현 청사진
+
+> **최종 정본 (H04 반영, 2026-08-29):** 이 문서는 구현과 사용자 게이트를 모두 통과한 최종 정보 구조, 진실성 계약, 화면 상태, 토큰, 성능 예산과 자동 게이트를 기록한다. 초기 9장 구성과 지도·통근 중심 설계는 폐기됐다.
+
+## 1. 공통 계약
+
+- `한남자리`와 `철판클럽`은 디자인 검증용 가상 브랜드다.
+- 실제 사무소, 실제 매물, 실제 매장, 실제 가격, 실제 주문, 실제 가맹 문의로 오인될 표현을 만들지 않는다.
+- 고지는 푸터 한 곳에 숨기지 않는다. 같은 진실 범위의 가장 가까운 의미 부모가 한 번 소유하고, 제한이 달라지는 카드·가격·매장 상태·제출 행동에서만 새로 표시한다.
+- 생성 이미지는 물성, 공간, 음식과 현장 분위기만 소유한다. 가격, 상태, 주소, 분석, 버튼과 표지는 실제 문서 객체가 소유한다.
+- 정적 데모의 계산은 실시간 인공지능이나 서버 전송으로 표현하지 않는다.
+- 화면이 실패해도 입력값과 확인된 사실은 남기고, 성공 상태를 가장하지 않는다.
+- 공개 경로와 운영 경로는 같은 브랜드 토큰을 공유하되 표현, 움직임, 정보 밀도 다이얼은 따로 둔다.
+
+## 2. 경로와 소유권
+
+| 제품 | 경로 | 주 임무 | 표현 / 움직임 / 밀도 |
+|---|---|---|---|
+| 한남자리 공개 | `/work/hannam-jari/` | 다섯 조건 입력, 예시 브리핑, 세 집 비교, 서류철, 사람 인계 | 7 / 4 / 5 |
+| 한남자리 관리자 | `/work/hannam-jari/admin/` | 표시 검수, 게시 방어선, 사람 검토, 감사 | 4 / 3 / 8 |
+| 철판클럽 공개 | `/work/griddle-club/` | 메뉴, 조합, 매장, 포장 행동 | 8 / 6 / 4 |
+| 철판클럽 가맹 | `/work/griddle-club/franchise/` | 운영 조건, 비용 미정, 문의 준비 | 5 / 3 / 6 |
+
+공유 저장소 수정 지점:
+
+- `apps/site/src/data/work.ts`: 두 쇼케이스와 하위 경로 등록
+- `apps/site/gate.config.json`: 네 경로 디자인 게이트 등록
+- `apps/site/tools/showcase-duo-e2e.mjs`: 결정적 기능과 실패 상태 검증
+- `apps/site/tools/design-gate.mjs`: 네 경로의 정적 계약과 실제 렌더를 320, 375, 390, 768, 1440에서 감사
+- `apps/site/tools/capture-showcase-duo.mjs`: 본 화면과 핵심 보조 화면 캡처
+- `apps/site/tools/verify.mjs`: 재귀 정적 검사, 실렌더 감사와 전용 시나리오 포함
+
+## 3. 한남자리 공개 화면
+
+### 밝은 Hero와 조건 도크
+
+- 제목은 `한남에서, 내 기준에 맞는 집부터.`다.
+- 서울 생활권의 생성 외관 이미지를 밝은 지면 위에 두고, 검정은 마지막 사람 인계 장면에서만 사용한다.
+- 의사결정 SSOT는 거래 형태·예산·최소 전용면적·입주 희망일·필요 주차 다섯 필드뿐이다.
+- 월세는 보증금과 월 납부액을 분리한다. 화면에 없는 통근·일조·좌표·조망은 추천 근거로 쓰지 않는다.
+- 입력 전송은 없고, 명시적으로 저장할 때만 다섯 필드를 현재 브라우저에 보관한다.
+
+### 예시 AI 브리핑과 세 집 비교
+
+- 분석 전에는 중립 상태를 유지한다. 실행 뒤 `조건과 맞는 점 / 조정이 필요한 점 / 중개사와 확인할 점` 세 묶음을 만든다.
+- 세 후보의 가격·면적·입주·주차를 동일한 입력과 비교하며, 선택 후보를 비교표·서류철·상담 인계에 동기화한다.
+- 모든 후보와 생성 사진의 가상·연출 범위는 가장 가까운 공통 부모에서 표시한다.
+
+### 탭형 검토 서류철과 사람 인계
+
+- 서류철은 기본·가격·권리·입지 확인·시설과 관리 다섯 탭이며 클릭과 방향키·Home 키를 지원한다.
+- 권리, 실제 이동 시간, 현장 상태, 입주 가능일처럼 근거가 없는 항목은 확인 필요로 남긴다.
+- 마지막 장면은 `AI가 좁히고, 공인중개사가 확인합니다.`라는 역할 분리를 보여준다.
+- 상담 흐름은 외부 전송 없는 모의 대화상자이며 닫기·바깥 클릭·Escape 뒤 선택 상태와 초점을 함께 복구한다.
+
+## 4. 한남자리 관리자
+
+### 첫 화면 구조
+
+- 일반적인 지표 카드 세 장과 차트로 시작하지 않는다.
+- 검수 대기열이 화면의 중심이고 우측 조사관이 선택 행의 전체 맥락을 가진다.
+- 표 열은 상태, 매물, 거래, 가격, 마지막 확인, 표시 검수, 분석 검토, 담당이다.
+- 검색, 상태 필터, 정렬, 키보드 행 선택과 빈 결과 초기화를 제공한다.
+
+### 이중 게시 게이트
+
+`쇼케이스 미리보기`는 다음 조건을 모두 통과할 때만 가능하다.
+
+- 상시 데모 표지
+- 개별 매물 예시 표지
+- 생성 이미지 출처와 증빙 불가 표지
+- 실제 연락 기능 비활성
+- 실제 주소와 등록번호 없음
+- 결정적 예시 분석 표지
+
+`실제 광고`는 다음이 모두 실제 자료가 아니므로 모든 fixture에서 차단한다.
+
+- 실제 등록 사무소 정보
+- 실제 중개의뢰 관계
+- 광고 동의
+- 거래 가능 상태
+- 실제 서류와 미디어 권리
+- 공인중개사 최종 승인
+
+가상 데이터로 실제 광고 게이트를 통과시키는 성공 상태는 구현하지 않는다.
+
+### 조사관 탭
+
+1. 기본
+2. 표시·광고
+3. 서류
+4. AI 분석
+5. 문의·일정
+6. 변경 이력
+
+표시 검수는 `통과`, `누락`, `충돌`, `오래됨`, `해당 없음`을 구분하고 법령, 행정 기준, 내부 운영 기준을 한 범주로 섞지 않는다. 누락 항목은 해당 필드로 이동한다.
+
+### 운영 상태
+
+- 대기열 없음과 필터 결과 없음은 서로 다른 상태다.
+- 권한상 볼 수 없음, 선택 행 계약 완료, 분석 실패·취소·오래됨을 제공한다.
+- 저장 실패는 낙관적 성공을 되돌리고 입력을 보존한다.
+- 버전 충돌은 다른 담당자의 버전과 현재 편집본을 덮어쓰지 않고 비교한다.
+- 실제 게시 요청은 중복 클릭, 권한, 객체 버전, 규칙 묶음, 감사 로그 쓰기 중 하나라도 실패하면 닫힌 상태를 유지한다.
+- 조사관과 대화상자는 닫기, 바깥 클릭, Escape가 패널과 선택 행 강조를 함께 해제한다.
+
+## 5. 철판클럽 공개 화면
+
+### 첫 화면과 메뉴
+
+- 제목은 `눌러 굽고, 바로 건넨다.`이다.
+- 일반 고객 행동인 메뉴와 매장 찾기가 가맹보다 높은 위계를 가진다.
+- 대표 두 메뉴는 큰 사진과 한국어 이름으로, 나머지는 세 열 편집 리듬으로 보여준다.
+- 모든 가격에 `화면 계산용 예시`를 가까이 붙인다.
+- 검증하지 않은 인기, 판매량, 순위 배지를 쓰지 않고 `대표`만 쓴다.
+- 품절, 매장 미제공, 준비 중을 색만이 아니라 문구와 행동 제한으로 표시한다.
+
+### 조합기
+
+- 단품·세트, 패티, 치즈, 양파, 피클, 소스, 곁들임, 음료와 받을 예시 매장을 선택한다.
+- 세트의 곁들임이나 음료가 비면 완료 상태가 되지 않는다.
+- 매장별 품절 재료가 있으면 조합은 보존하고 다른 매장 행동을 제공한다.
+- 매장이 닫혀도 조합을 지우지 않는다.
+- 가격 자료가 없으면 합계를 만들지 않는다.
+- 성공 행동은 주문이 아니라 `선택 내용 저장`이다.
+- 저장 결과는 현재 기기의 화면 상태이며 서버 전송으로 말하지 않는다.
+
+### 알레르기와 매장
+
+- 재료를 빼면 예시 알레르기 표시는 다시 계산한다.
+- 같은 철판과 도구의 교차 접촉 경고는 어떤 선택에서도 남긴다.
+- 매장은 `예시 매장`으로 표시하고 동네 범위만 제공한다.
+- 실제 도로명 주소, 전화번호, 거리와 위치 권한을 만들지 않는다.
+- 영업 중, 마지막 주문 임박, 종료, 임시 휴무, 확인 필요를 각각 다른 행동으로 연결한다.
+
+## 6. 철판클럽 가맹 화면
+
+- 첫 사진은 버거 접사보다 조리, 포장, 응대 동선이 보이는 운영 장면이다.
+- 브랜드 이유, 운영 방식, 희망 상권, 점포 상태, 개설 순서, 비용 상태, 교육과 품질, 문의 준비 순서로 읽힌다.
+- 검증하지 않은 최소 면적, 가맹비, 평균 매출, 회수 기간과 예상 수익을 만들지 않는다.
+- 비용 항목은 금액이 아닌 `미정`과 미정 이유를 보여주고 합계를 만들지 않는다.
+- 면적 입력은 ㎡와 평을 함께 보여주지만 적합 판정으로 표현하지 않는다.
+- 문의는 실제 이름과 연락처를 받지 않는 체험이다.
+- 성공 상태는 `문의 준비가 끝났어요`이며 실제 접수나 담당자 연락을 주장하지 않는다.
+- 실패 상태는 입력을 보존하고 다시 시도 행동을 제공한다.
+
+## 7. 토큰과 조판
+
+### 한남자리 공개
+
+- 바탕 `#EEECE5`
+- 검정 `#0F0F0E`
+- 어두운 면 금색 `#C6A15B`
+- 밝은 면 갈금 `#6F5420`
+- 금색 점유율 5% 이하, 선택·검토·확인 표시에만 사용
+- Pretendard 또는 SUIT 계열 한 패밀리
+
+### 한남자리 관리자
+
+- 밝은 중립 바탕, 흰 패널, zinc 계열 경계
+- 브랜드 검정과 갈금은 선택 행, 현재 탭, 방어선 상태에만 사용
+- 표 본문 13~14px, 일반 본문 15~16px, 지나치게 작은 보조문 금지
+- radius는 작은 제어 6~8px, 패널 10~12px 이내
+
+### 철판클럽
+
+- 바탕 `#F4F1E9`
+- 글자 `#211F1C`
+- 코발트 `#2147E7`
+- 코발트 점유율 8~10%, 행동과 포장 재료에 집중
+- 스테인리스, 치즈와 불빛은 사진만 소유
+- Pretendard Variable 한 패밀리
+
+## 8. 반응형과 접근성
+
+- 320, 390, 768, 1440에서 가로 넘침이 없어야 한다.
+- 모바일 주 행동은 최소 높이 44px이다.
+- 첫 제목은 320px에서도 두 줄 이내를 목표로 하되 한국어 어절을 강제로 쪼개지 않는다.
+- 고정 머리글과 하단 행동은 안전 영역을 포함한다.
+- 가로 표는 명시적 스크롤 용기와 표 설명을 가진다.
+- 현재 선택, 품절, 차단, 경고는 색과 함께 텍스트·아이콘·속성으로 표현한다.
+- 상태 변경은 `aria-live`, 폼 전체 실패는 `role=alert`로 알린다.
+- 감소 모션에서는 자동 이동, 부드러운 스크롤과 장식 변환을 끈다.
+- 자바스크립트가 없어도 제목, 핵심 사실, 예시 고지와 경로 설명은 남는다.
+
+## 9. 이미지와 성능 예산
+
+- 데스크톱 Hero 목표 180~240KB, 하드 상한 320KB
+- 모바일 Hero 목표 140~190KB, 하드 상한 240KB
+- 카드 목표 65~100KB, 하드 상한 130KB
+- 첫 화면 동일 출처 자산은 데스크톱 350KB, 모바일 260KB 이하를 목표로 한다.
+- Hero만 높은 우선순위를 사용하고 나머지는 지연 로딩한다.
+- 모든 이미지에 고정 크기, 반응형 크기 힌트, 대체 문구를 둔다.
+- 생성 이미지 픽셀의 글자와 로고는 자동 한자 검사로 잡히지 않으므로 별도 육안 감사한다.
+
+## 10. 자동 게이트 계약
+
+정적 게이트:
+
+- 모든 하위 HTML 재귀 검증
+- 모든 하위 CSS 재귀 스타일 검사
+- 자바스크립트 문법 검사
+- 한자 금지 검사
+- 상대 경로, CSS 변수, 한글 조판 무결성 검사
+
+실제 브라우저 게이트:
+
+- 네 경로 × 네 폭의 구조와 오버플로 감사
+- 한남자리 조건 분석, 단위 전환, 지도·목록 동기화, 상담 데모
+- 한남자리 관리자 검색·정렬·필터·탭·게시 차단·대화상자 해제
+- 철판클럽 메뉴, 조합기, 품절·영업 종료, 알레르기, 저장 성공·실패
+- 철판클럽 가맹 면적 환산, 비용 미정, 검토 복귀, demo 성공·실패
+- 키보드 순서, 접근성 자동 검사, 감소 모션, 자바스크립트 없음
+- 깨진 이미지, 콘솔 오류, 네트워크 실패, 누적 배치 이동과 최초 주요 표시 시간
+
+게이트의 자동 승인은 무조건 통과가 아니다. 검사 결과가 녹색일 때만 승인 기록을 남기고, 실패 시 관련 단계로 되돌아가 수정한다.