Files
clean-architecture-frontend…/PRODUCT.md
DongHyeonka 332bfee9b8 fix(docs): 지운 템플릿 기능의 경로를 문서 검사가 요구하지 않는다
문제
CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능
폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세
폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과
FE-GATE-005의 documentation-readiness "passes the documents as they are"가
"starter-experience.md names paths that do not exist"로 실패한다(리뷰
14-R1). 그 문서가 안내한 드릴(test:sample-removal
--feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를
적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다.
PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿
문서를 고치면 동기화마다 그 줄이 충돌한다.

고른 방법
- 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그
  기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그
  경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트
  폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라
  feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴
  채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는
  폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다.
- tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용
  기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다.
- 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소
  사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의
  verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로
  지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의
  잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히
  실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에
  더했다.
- PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙),
  docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더,
  generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다.
- 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또
  좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가
  없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c)
  FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새
  unit 테스트가 merge 단계에서 본다.

위험·한계
- 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit
  시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다.
- 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다.
  알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다.
- RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/template-feature-removal-documents.test.ts
  tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts
  tests/unit/documentation-readiness.test.ts, corepack pnpm
  verify:documentation, corepack pnpm test:sample-removal --
  --feature=platform-examples-feature

Refs: 1105/14-01
2026-11-06 02:59:02 +09:00

57 lines
4.7 KiB
Markdown

# Product
<!-- impeccable:product-schema 1 -->
## Platform
web
## Users
- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 예제 화면(홈, 플랫폼 구성, UI 구성요소, 화면 상태, 인증 연동, Reference feature)은 이 사람이 실행 구조와 공통 동작을 확인하는 용도입니다.
- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 합니다.
## Product Purpose
도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둡니다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것입니다.
## Positioning
화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트입니다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않습니다.
## Operating Context
- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다.
- 파생 서비스는 운영 중인 desktop 서버에 배포됩니다.
- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다.
## Capabilities and Constraints
- 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다.
- 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(`tokens/primitive.css`, `semantic.css`, `component.css`).
- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다.
- 참조 기능(`src/features/reference-feature/`)은 `test:sample-removal`로 지울 수 있습니다. 예제 화면 3개(`/examples/ui`, `states`, `auth`)도 기능 `platform-examples-feature`라서 같은 드릴(`test:sample-removal -- --feature=platform-examples-feature`)로 지울 수 있습니다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이고 제거 드릴이 없습니다. 그래서 예제 화면 3개에만 넣은 디자인은 예제를 지운 파생 서비스에서 함께 사라지고, 홈과 플랫폼 구성 화면에 넣은 디자인은 남습니다.
- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다.
## Brand Commitments
브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자입니다.
## Evidence on Hand
- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다.
- 예제 문구는 템플릿 기능 설명뿐입니다(`src/presentation/i18n/catalog.ts`).
- 현재 화면 기록: `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/`, Storybook(`src/presentation/design-system/design-system.stories.tsx`).
## Product Principles
1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다.
2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다.
3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복제하지 않습니다.
4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다.
5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다.
## Accessibility & Inclusion
WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킵니다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있습니다(`docs/accessibility/manual-checklist.md`).