# 오류 메시지 가이드

## 목적
- 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`에 티켓을 생성한다.
