forked from baron/baron-sso
73 lines
2.0 KiB
Markdown
73 lines
2.0 KiB
Markdown
# UserFront Error Handling Policy
|
|
|
|
## 1. 목적
|
|
- UserFront의 `/error` 화면에서 에러 코드 노출 정책을 일관되게 유지합니다.
|
|
- Ory에서 전달되는 표준 에러 코드는 별도 bypass 규칙으로 처리합니다.
|
|
- 내부 코드와 번역 리소스의 누락을 자동 검증합니다.
|
|
|
|
## 2. 처리 원칙
|
|
1. 프로덕션에서 에러 분기 기준은 `error` 문자열이 아니라 `code`입니다.
|
|
2. `ORY error code`는 bypass 규칙으로 처리합니다.
|
|
3. ORY 코드 외 항목은 내부 whitelist를 기준으로 노출합니다.
|
|
4. whitelist/bypass에 없는 코드는 `unknown_error`로 처리합니다.
|
|
|
|
## 3. 코드 분류
|
|
기준 파일: `userfront/lib/core/constants/error_whitelist.dart`
|
|
|
|
### 3.1 Internal whitelist
|
|
- `settings_disabled`
|
|
- `invalid_session`
|
|
- `verification_required`
|
|
- `recovery_expired`
|
|
- `recovery_invalid`
|
|
- `rate_limited`
|
|
- `not_found`
|
|
- `bad_request`
|
|
- `password_or_email_mismatch`
|
|
|
|
### 3.2 ORY bypass
|
|
- `access_denied`
|
|
- `consent_required`
|
|
- `interaction_required`
|
|
- `invalid_client`
|
|
- `invalid_grant`
|
|
- `invalid_request`
|
|
- `invalid_scope`
|
|
- `login_required`
|
|
- `request_forbidden`
|
|
- `server_error`
|
|
- `temporarily_unavailable`
|
|
- `unauthorized_client`
|
|
- `unsupported_response_type`
|
|
|
|
## 4. i18n 키 구조
|
|
- 내부 whitelist: `msg.userfront.error.whitelist.{code}`
|
|
- ORY bypass: `msg.userfront.error.ory.{code}`
|
|
|
|
리소스는 아래 파일 모두에 키가 있어야 합니다.
|
|
- `locales/template.toml`
|
|
- `locales/ko.toml`
|
|
- `locales/en.toml`
|
|
- `userfront/assets/translations/template.toml`
|
|
- `userfront/assets/translations/ko.toml`
|
|
- `userfront/assets/translations/en.toml`
|
|
|
|
## 5. 검증
|
|
키 누락 검증 스크립트:
|
|
|
|
```bash
|
|
./scripts/verify_userfront_error_i18n.sh
|
|
```
|
|
|
|
화면 동작 테스트:
|
|
|
|
```bash
|
|
cd userfront
|
|
flutter test test/error_screen_test.dart
|
|
```
|
|
|
|
## 6. 관련 이슈
|
|
- `#164` `[UserFront] 에러 노출 whitelist 정의 및 적용`
|
|
- `#259` `백엔드 i18n/에러 메시지 fallback 정책 재정리 및 반영 계획 수립`
|
|
- `#260` `[Backend] 에러 응답 code 통일 구현 계획 (phase rollout)`
|