1. 로컬라이제이션 규칙
- 모든 노출 문자열은 공통 i18n 딕셔너리(
dictionary.home.*, dictionary.common.*)에서 가져온다.
- 신규/기존 사용자 라벨, Agent 툴팁, 상담 패널 라벨, learn more 액션 등 사용자에게 보이는 문구는 하드코딩하지 않는다.
- 언어가 바뀌면 현재 열려 있는 툴팁과 상담 창을 닫고, 새 언어 리소스를 기반으로 다시 표시한다.
2. Agent 버튼 동작 규칙
- Agent 버튼은 다음 상태 기계를 따른다.
- 상담 창이 열려 있으면 버튼 입력을 무시해 중복 세션을 방지한다.
- 상담 창이 닫혀 있고 툴팁만 열려 있으면 툴팁만 닫는다.
- 그 외에는 툴팁을 열고 3글자 단위·24ms 간격으로 안내 문구를 스트리밍한다.
- 툴팁이 한 번이라도 열리면 “첫 방문자” 플래그를 false로 바꿔 이후 Agent 버튼 발광이 멈춘다.
- 툴팁 내 액션을 통해 상담을 시작할 때는 툴팁을 닫고, 상담 세션 초기화가 가능한 상태인지 확인한 뒤 상담 창을 연다. 준비되지 않았을 경우에도 UI는 예외 없이 유지되어야 한다.
- 현재는 안내 문구를 3글자씩 잘라내는 타이머 기반 스트리밍으로 흉내 내지만, Backend API가 연결되면 반드시 SSE(서버 전송 이벤트) 기반 메시지 스트리밍으로 교체해야 한다. 타이머 로직은 임시 구현임을 주석과 문서로 명확히 남긴다.
3. 라우팅 규칙
/onboarding/agreements, /login으로 이동하는 CTA는 클라이언트 내비게이션을 시도하되, 실패 시 브라우저 기본 이동 방식으로 자동 폴백해야 한다.- 신규 사용자 CTA는 추가 파라미터 없이 약관 페이지에 진입해 게스트 플로우를 시작한다. 게스트 여부 판별은 해당 페이지가 처리한다.
- 기존 사용자 CTA는
/login 한 경로만 사용하며, OAuth 관련 매개변수는 로그인 화면에서만 관리한다.
4. 상태 및 리소스 관리
- Agent 발광 조건: 상담 창이 닫혀 있고, 안내 문구가 스트리밍 중이거나 아직 한 번도 눌러보지 않은 사용자에게만 발광 효과를 준다.
- 안내 문구 스트리밍에 사용한 타이머 핸들은 툴팁이 닫히거나 언어가 바뀌거나 화면을 떠날 때 즉시 정리한다. 누락 시 동일 문구가 중첩 출력된다.
- 상담 창 초기 메시지는 창을 열 때만 생성하며, 창이 닫히면 즉시 삭제한다. 언어 전환 시에도 삭제해 이전 언어 텍스트가 남지 않게 한다.
5. 오류 및 예외 처리
- 상담 세션 초기화가 준비되지 않은 상태에서는 초기화 함수를 호출하지 않는다. 이때도 상담 창 UI는 열리지만, 실제 백엔드 연결이 없음을 감안해 에러 없이 대기 상태를 유지해야 한다.
- 툴팁 스트리밍 중 언어 변경이나 화면 이탈이 발생할 수 있으므로, 종료 루틴 하나만으로 모든 타이머를 정리하도록 구현한다.
6. 검증 포인트
- 언어 전환 → Agent 버튼 → 툴팁 → 상담 창까지 전체 플로우를 실행했을 때 모든 문자열이 동일 언어로 유지되는지 확인한다.
- 뒤로 가기/앞으로 가기 내비게이션으로 루트 화면에 복귀했을 때 첫 방문자 플래그가 유지돼 재방문자는 Agent 발광이 꺼져 있는지 확인한다.
- 툴팁 오버레이를 클릭하거나 닫기 제스처를 수행했을 때 스트리밍이 즉시 중단되는지 확인한다.