본문으로 건너뛰기

웹 프런트엔드 요구사항 문서화 가이드라인

본 가이드는 dha-sleep-web UI 요구사항을 Mobile 엔지니어와 QA 엔지니어가 재사용할 수 있도록 문서화하는 공통 규칙을 정의한다. 모든 문서는 한국어로 작성하며, 아래 항목을 반드시 준수한다.

1. 문서 위치와 구조​

  • 각 화면(또는 UX 플로우)마다 전용 디렉터리를 생성한다.
apps/dta-wi-doc/docs/application/dha-sleep-web/frontend/web/ux-flows/<screen-id>/
  requirements.md      # 기능 요구사항
  business-rules.md    # 비즈니스 규칙 및 상태 정책
  • <screen-id>는 실제 라우트 또는 도메인 개념을 분명히 드러내는 케밥 케이스를 사용한다. 예: initial-entry-screen, guest-onboarding.
  • 동일 화면에 대한 모든 참고 자료(추가 링크, 추후 FAQ 등)는 해당 디렉터리에만 배치한다.

2. 소스 기반 작성 원칙​

  1. 필수: 화면 요구사항은 반드시 실제 소스 코드(페이지·컴포넌트·훅 등)를 분석해 작성한다.
  2. 금지: 스크린샷이나 GUI 묘사 중심의 서술을 작성하지 않는다. “어떤 정보를 노출해야 하는지, 어떤 조건에서 어떤 기능이 작동하는지”만 기술한다.
  3. 근거 명시: 필요한 경우 소스 파일 경로나 데이터 계약(예: /onboarding/agreements, dictionary.home.*)을 텍스트로 언급해 추적 가능성을 확보한다.

3. Requirements 문서 구성​

requirements.md에는 다음 섹션을 기본으로 포함한다.

  1. Purpose & Scope: 화면 목적, 포함/제외 범위.
  2. Entry Conditions: 화면 진입 조건, 초기 상태, 선행 데이터 요구사항.
  3. Required Information: 사용자에게 반드시 보여야 하는 데이터·라벨·CTA와 해당 데이터 소스.
  4. Interaction Flows: 사용자 입력에 따른 분기(예: 언어 전환, Agent 버튼, 사용자 유형 선택). 플랫폼 중립적으로 설명하고, “3글자 단위 스트리밍”처럼 구현에 영향을 주는 동작도 포함한다.
  5. QA Checklist: QA가 기능을 검증할 수 있도록 Pass/Fail가 명확한 항목을 나열한다.

참고: 문단 중 “Agent 버튼”, “신규/기존 사용자 CTA”처럼 제품에서 이미 합의된 용어만 사용해 혼선을 막는다.

4. Business Rules 문서 구성​

business-rules.md는 기능 뒤에 있는 정책을 정의한다.

  • Localization Rules: 어떤 문자열이 어떤 i18n 리소스를 참조하는지, 언어 전환 시 따라야 할 동작.
  • State Machines & Flags: 예) Agent 버튼 발광 조건, 툴팁 스트리밍 상태, hasSeenAgentTooltip 활용 방식.
  • Routing Rules: 어떤 CTA가 어떤 경로로 이동하며 파라미터 처리 책임이 어디에 있는지.
  • Resource & Timer Management: 비동기 작업 정리, 메모리 누수 방지 규칙 등.
  • Error Handling / Fallbacks: 준비되지 않은 상담 세션, 내비게이션 실패 등 예외 케이스 대응.
  • Verification Points: QA가 시나리오별로 반드시 확인해야 할 정책 항목.

5. 용어 및 표현 규칙​

  • 독자는 모바일 개발자와 QA 엔지니어를 포함하므로 웹 전용 기술 용어(Next.js, App Router, useEffect 등)는 사용하지 않는다. 필요한 경우 “언어 리소스 로딩”, “클라이언트 내비게이션”처럼 플랫폼에 구애되지 않는 표현을 사용한다.
  • 에이전트 진입점은 항상 Agent 버튼으로 통일한다. 이외에도 제품 내 확정된 명칭(예: “신규 사용자 CTA”)을 일관되게 사용한다.
  • 문서 전반은 기능 설명 위주로 작성하며, UI 컴포넌트의 시각적 속성(색상, 폰트, 여백 등)은 다른 디자인 문서에 위임한다.

6. 작성 절차 요약​

  1. 화면 소스 코드를 탐색하고, 언어 리소스·서비스 호출·상태 변수를 파악한다.
  2. 기능 흐름을 도메인 언어로 정리한 뒤, Requirements/Business Rules 두 파일에 각각 배분한다.
  3. QA가 재현 가능한 체크리스트를 포함하고, 문서 전체를 한국어로 교정한다.
  4. 새로운 화면을 추가할 때는 동일한 디렉터리/파일 패턴을 복제해 일관성을 유지한다.

위 가이드를 준수하면 플랫폼에 구애받지 않는 요구사항 문서를 지속적으로 축적할 수 있으며, 모바일·QA 팀이 동일한 정보를 기반으로 개발/검증을 수행할 수 있다.