superport_v2/doc/error_message_guide.md

오류 메시지 가이드

목적

• API에서 전달되는 오류 메시지와 필드 상세 정보를 사용자에게 명확하게 전달하여 재시도 가이드를 제공한다.
• 화면별 토스트 · 다이얼로그 문구를 통일해 SRP 원칙을 유지하고, 번역/UX 협업 비용을 줄인다.

작성 원칙

• API 우선: Failure.describe()가 반환한 메시지를 그대로 노출한다. 자체 문구는 메시지가 비어 있을 때에만 사용한다.
• 콘텍스트 보강: 필드 오류가 존재하면 필드명: 메시지 형식으로 추가 설명을 붙이고, 중복 문구는 제거한다.
• 톤 & 매너: 짧고 직설적인 한국어 문장을 사용한다. 사용자 액션(재시도·확인 요청 등)은 문장 말미에 배치한다.
• 민감 정보 보호: 서버에서 전달된 토큰/쿼리/내부 식별자는 노출하지 않는다.

UI 표현 규칙

• 토스트(ScaffoldMessenger): 치명도가 낮은 검증·권한 오류는 토스트로 표시한다. 제목 없이 본문 한 줄을 유지한다.
• 다이얼로그: 저장/제출 계열 실패로 추가 입력이 필요한 경우 다이얼로그를 사용하고, 본문 첫 줄에 Failure.describe() 결과를 배치한다.
• 배지/배너: 기능 플래그로 비활성화된 경우 상세 카드 상단에 ShadBadge.outline 으로 안내한다.
• 모바일 카드: 상태 전이 버튼이 비활성화되면 동일 메시지를 본문 하단에 Text 로 노출한다.

테스트 체크리스트

• test/features/inventory/inbound_page_test.dart — 상신 실패 시 서버 메시지가 토스트로 노출되는지 검증.
• test/features/reporting/reporting_page_test.dart — 창고 목록 실패 후 재시도 동작 및 메시지 유지 확인.
• 필요 시 추가 화면 테스트에서 Failure.describe() 값을 매칭하도록 InventoryTestStubConfig를 활용한다.

협업 프로세스

1. 신규 또는 수정 메시지는 UX 리뷰어와 공유하여 표현 톤을 확정한다.
2. 합의된 문구를 본 가이드에 추가하고 PR 설명에 링크한다.
3. 번역이 필요한 경우 doc/localization_queue.md에 티켓을 생성한다.