forked from baron/baron-sso
95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
# Issue #281: locale_storage 리팩터링 계획
|
|
|
|
## 목적
|
|
- `locale_storage` 관련 로직에서 정책 지식(키, fallback, migration)을 한 곳으로 모아 변경 비용을 줄입니다.
|
|
- 테스트를 내부 구현 의존(`webStorage`)에서 파사드 의존(`LocaleStorage`) 중심으로 바꿔 회귀 위험을 낮춥니다.
|
|
- 테스트 강제 훅(`forceMemoryStorageForTests`, `forceSessionStorageForTests`)의 진입점을 단일화합니다.
|
|
|
|
## 현재 문제 요약
|
|
1. 저장 정책 지식이 여러 파일에 분산되어 있습니다.
|
|
2. 테스트가 구현 세부사항에 결합되어 정책 변경 시 함께 깨질 가능성이 큽니다.
|
|
3. 플랫폼별 훅 wiring이 반복되어 확장 시 누락 가능성이 있습니다.
|
|
|
|
## 변경 범위
|
|
- 대상 파일
|
|
- `userfront/lib/core/i18n/locale_storage.dart`
|
|
- `userfront/lib/core/i18n/locale_storage_stub.dart`
|
|
- `userfront/lib/core/i18n/locale_storage_web.dart`
|
|
- `userfront/test/locale_storage_platform_test.dart`
|
|
- `userfront/test/helpers/web_storage.dart`
|
|
- `userfront/test/helpers/web_storage_stub.dart`
|
|
- `userfront/test/helpers/web_storage_web.dart`
|
|
|
|
## 리팩터링 단계
|
|
### 1) 저장 정책 공통화
|
|
- 저장 키 상수(`locale`, legacy `baron_locale`)와 migration 로직을 공통 모듈로 이동합니다.
|
|
- fallback 순서(local -> session -> memory)를 공통 정책 함수로 추출합니다.
|
|
- `locale_storage_web.dart`는 정책 모듈 호출 위주로 단순화합니다.
|
|
|
|
### 2) 테스트 결합도 축소
|
|
- 테스트 assertion의 중심을 `LocaleStorage` API로 이동합니다.
|
|
- `webStorage` 직접 검증은 최소화하고, 필요한 경우 정책 모듈의 관찰 포인트를 제한적으로 제공합니다.
|
|
|
|
### 3) 테스트 훅 단일 진입
|
|
- `LocaleStorage` 파사드에서만 테스트 훅을 제어하도록 정리합니다.
|
|
- 플랫폼 구현은 훅 내부 세부 정책을 직접 노출하지 않도록 인터페이스를 정돈합니다.
|
|
|
|
### 4) 회귀 테스트 보강
|
|
- legacy key migration(`baron_locale -> locale`) 회귀 테스트를 명시적으로 유지합니다.
|
|
- storage access 실패/비가용 상황에서 fallback 순서를 검증하는 테스트를 추가합니다.
|
|
|
|
## 완료 기준(DoD)
|
|
- 정책 변경 시 수정 포인트가 공통 모듈 중심으로 줄어듭니다.
|
|
- 기존 locale 저장/조회 동작과 migration 동작이 유지됩니다.
|
|
- VM 기반 테스트가 안정적으로 통과하며 fallback/migration 회귀 케이스가 포함됩니다.
|
|
|
|
## 구현 시 주의사항
|
|
- 외부에서 사용하는 public API 시그니처는 가능한 유지합니다.
|
|
- 테스트 편의를 위한 훅은 운영 코드 경로에 영향이 없도록 격리합니다.
|
|
- 리팩터링 중간 단계에서도 테스트가 통과하도록 작은 단위로 나눠 적용합니다.
|
|
|
|
## 롤백 기준
|
|
- locale 저장/복구가 실패하거나, 웹 환경에서 fallback 동작이 달라지는 경우 즉시 이전 커밋 단위로 되돌립니다.
|
|
- migration 동작이 깨지는 경우 해당 단계만 우선 revert하고 정책 모듈 분리부터 재진행합니다.
|
|
|
|
## 구현 결과 (2026-02-20)
|
|
### 반영된 코드 변경
|
|
- 공통 계약/디버그 상태 타입 추가
|
|
- `userfront/lib/core/i18n/locale_storage_backend.dart`
|
|
- 저장 정책 상수/판단 로직 분리
|
|
- `userfront/lib/core/i18n/locale_storage_policy.dart`
|
|
- 파사드 단일 테스트 진입점 정리
|
|
- `userfront/lib/core/i18n/locale_storage.dart`
|
|
- `setTestModeForTests`, `clearForTests`, `seedLegacyForTests`, `debugStateForTests` 추가
|
|
- 기존 `forceMemoryStorageForTests`, `forceSessionStorageForTests` 호환 유지
|
|
- 플랫폼 구현 리팩터링
|
|
- `userfront/lib/core/i18n/locale_storage_web.dart`
|
|
- `userfront/lib/core/i18n/locale_storage_stub.dart`
|
|
- fallback 순서(local -> session -> memory) 유지
|
|
- legacy migration 시 legacy key(`baron_locale`)를 local/session/memory 전체에서 정리
|
|
- 테스트 정리
|
|
- `userfront/test/locale_storage_platform_test.dart`를 `LocaleStorage` API 중심 검증으로 전환
|
|
- 삭제: `userfront/test/helpers/web_storage.dart`
|
|
- 삭제: `userfront/test/helpers/web_storage_stub.dart`
|
|
- 삭제: `userfront/test/helpers/web_storage_web.dart`
|
|
|
|
### CI/워크플로우 반영
|
|
- 파일: `.gitea/workflows/code_check.yml`
|
|
- `workflow_dispatch.inputs` 복원
|
|
- `run_lint`
|
|
- `run_backend_tests`
|
|
- `run_userfront_tests`
|
|
- 각 job 실행 조건 복원
|
|
- lint: `inputs.run_lint`
|
|
- backend-tests: `inputs.run_backend_tests`
|
|
- userfront-tests: `inputs.run_userfront_tests`
|
|
- userfront-tests 정책 정리
|
|
- `flutter test` 단일 실행으로 운영
|
|
- `locale_storage` 정책 검증은 VM 테스트(`locale_storage_platform_test.dart`)로 통합
|
|
- 브라우저 설치/`--platform chrome` 단계 제거
|
|
|
|
### 검증 결과
|
|
- `cd userfront && flutter analyze --no-fatal-warnings --no-fatal-infos` 통과
|
|
- `cd userfront && flutter test` 통과
|
|
- `cd userfront && flutter test test/locale_storage_platform_test.dart` 통과
|