kevin/baron-sso
1
0
Fork 0
forked from baron/baron-sso
Code Pull Requests Activity

Merge commit '9a4808f0e5d9810bd4d3361e98dd6fe4ec18b96e' into featur/tenantsign

Browse Source
This commit is contained in:
조찬영
2026-02-20 09:36:10 +09:00
parent e40dd8120e 9a4808f0e5
commit f8b8b262cb
18 changed files with 1267 additions and 399 deletions
Download Patch File Download Diff File Expand all files Collapse all files

337
.gitea/workflows/code_check.yml
View File

@@ -8,9 +8,36 @@ on:
branches:
- dev
workflow_dispatch:
inputs:
run_lint:
description: "Run linters for Go and Flutter"
required: true
type: boolean
default: true
run_backend_tests:
description: "Run backend Go tests"
required: true
type: boolean
default: true
run_userfront_tests:
description: "Run userfront Flutter tests"
required: true
type: boolean
default: true
run_adminfront_tests:
description: "Run adminfront Playwright tests"
required: true
type: boolean
default: true
run_devfront_tests:
description: "Run devfront Playwright tests"
required: true
type: boolean
default: true
jobs:
lint:
if: ${{ github.event_name != 'workflow_dispatch' || inputs.run_lint == true }}
runs-on: ubuntu-latest
steps:
- name: Checkout code
@@ -54,7 +81,7 @@ jobs:
backend-tests:
needs: lint
if: ${{ always() }}
if: ${{ always() && (github.event_name != 'workflow_dispatch' || inputs.run_backend_tests == true) }}
runs-on: ubuntu-latest
services:
redis:
@@ -83,12 +110,53 @@ jobs:
- name: Run backend tests
run: |
mkdir -p reports
set +e
cd backend
go test -v ./...
go test -v ./... 2>&1 | tee ../reports/backend-test.log
test_exit_code=${PIPESTATUS[0]}
cd ..
if [ "$test_exit_code" -ne 0 ]; then
{
echo "# Backend Test Failure Report"
echo
echo "- Workflow: \`${GITHUB_WORKFLOW:-Code Check}\`"
echo "- Job: \`backend-tests\`"
echo "- Exit Code: \`$test_exit_code\`"
echo
echo "## Command"
echo "\`go test -v ./...\`"
echo
echo "## Log Tail (last 200 lines)"
echo '```text'
tail -n 200 reports/backend-test.log
echo '```'
} > reports/backend-test-failure-report.md
fi
exit "$test_exit_code"
- name: Publish backend failure summary
if: ${{ failure() }}
run: |
if [ -f reports/backend-test-failure-report.md ]; then
cat reports/backend-test-failure-report.md >> "$GITHUB_STEP_SUMMARY"
fi
- name: Upload backend failure report artifact
if: ${{ failure() }}
uses: actions/upload-artifact@v4
with:
name: backend-test-failure-report
path: |
reports/backend-test-failure-report.md
reports/backend-test.log
if-no-files-found: ignore
userfront-tests:
needs: lint
if: ${{ always() }}
if: ${{ always() && (github.event_name != 'workflow_dispatch' || inputs.run_userfront_tests == true) }}
runs-on: ubuntu-latest
steps:
- name: Checkout code
@@ -100,12 +168,271 @@ jobs:
channel: "stable"
cache: true
- name: Ensure browser for Flutter web tests
run: |
has_runnable_browser=false
for candidate in google-chrome google-chrome-stable chromium chromium-browser; do
if command -v "$candidate" >/dev/null 2>&1 && "$candidate" --version >/dev/null 2>&1; then
has_runnable_browser=true
break
fi
done
if [ "$has_runnable_browser" = true ]; then
echo "Runnable Chrome/Chromium already installed."
exit 0
fi
if command -v sudo >/dev/null 2>&1; then
sudo apt-get update
sudo apt-get install -y chromium || sudo apt-get install -y chromium-browser
else
apt-get update
apt-get install -y chromium || apt-get install -y chromium-browser
fi
for candidate in google-chrome google-chrome-stable chromium chromium-browser; do
if command -v "$candidate" >/dev/null 2>&1 && "$candidate" --version >/dev/null 2>&1; then
echo "Installed browser: $candidate"
exit 0
fi
done
echo "No runnable Chrome/Chromium found after install."
exit 1
- name: Run userfront tests
run: |
cd userfront
if [ -d test ]; then
flutter test
# flutter test --platform chrome test/locale_storage_platform_test.dart
CHROME_BIN=""
for candidate in google-chrome google-chrome-stable chromium chromium-browser; do
if command -v "$candidate" >/dev/null 2>&1 && "$candidate" --version >/dev/null 2>&1; then
CHROME_BIN="$(command -v "$candidate")"
break
fi
done
if [ -z "$CHROME_BIN" ]; then
echo "Chrome/Chromium not found for web tests."
exit 1
fi
echo "Using browser: $CHROME_BIN"
export CHROME_EXECUTABLE="$CHROME_BIN"
mkdir -p ../reports
set +e
flutter test 2>&1 | tee ../reports/userfront-test-vm.log
vm_test_exit_code=${PIPESTATUS[0]}
web_test_exit_code=0
if [ "$vm_test_exit_code" -eq 0 ]; then
flutter test --platform chrome test/locale_storage_platform_test.dart 2>&1 | tee ../reports/userfront-test-web.log
web_test_exit_code=${PIPESTATUS[0]}
fi
set -e
if [ "$vm_test_exit_code" -ne 0 ] || [ "$web_test_exit_code" -ne 0 ]; then
{
echo "# Userfront Test Failure Report"
echo
echo "- Workflow: \`${GITHUB_WORKFLOW:-Code Check}\`"
echo "- Job: \`userfront-tests\`"
echo "- Browser: \`$CHROME_BIN\`"
echo "- VM Test Exit Code: \`$vm_test_exit_code\`"
echo "- Web Test Exit Code: \`$web_test_exit_code\`"
echo
echo "## Commands"
echo "1. \`flutter test\`"
echo "2. \`flutter test --platform chrome test/locale_storage_platform_test.dart\`"
echo
if [ -f ../reports/userfront-test-vm.log ]; then
echo "## VM Test Log Tail (last 200 lines)"
echo '```text'
tail -n 200 ../reports/userfront-test-vm.log
echo '```'
echo
fi
if [ -f ../reports/userfront-test-web.log ]; then
echo "## Web Test Log Tail (last 200 lines)"
echo '```text'
tail -n 200 ../reports/userfront-test-web.log
echo '```'
fi
} > ../reports/userfront-test-failure-report.md
exit 1
fi
else
echo "No userfront tests: skipping (test/ directory not found)."
fi
- name: Publish userfront failure summary
if: ${{ failure() }}
run: |
if [ -f reports/userfront-test-failure-report.md ]; then
cat reports/userfront-test-failure-report.md >> "$GITHUB_STEP_SUMMARY"
fi
- name: Upload userfront failure report artifact
if: ${{ failure() }}
uses: actions/upload-artifact@v4
with:
name: userfront-test-failure-report
path: |
reports/userfront-test-failure-report.md
reports/userfront-test-vm.log
reports/userfront-test-web.log
if-no-files-found: ignore
adminfront-tests:
needs: lint
if: ${{ always() && (github.event_name != 'workflow_dispatch' || inputs.run_adminfront_tests == true) }}
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
cache-dependency-path: adminfront/package-lock.json
- name: Install adminfront dependencies
run: |
cd adminfront
npm ci
- name: Provision browsers for adminfront tests
run: |
cd adminfront
npx playwright install --with-deps
- name: Run adminfront tests
run: |
mkdir -p reports
set +e
cd adminfront
npm test 2>&1 | tee ../reports/adminfront-test.log
test_exit_code=${PIPESTATUS[0]}
cd ..
set -e
if [ "$test_exit_code" -ne 0 ]; then
{
echo "# Adminfront Test Failure Report"
echo
echo "- Workflow: \`${GITHUB_WORKFLOW:-Code Check}\`"
echo "- Job: \`adminfront-tests\`"
echo "- Exit Code: \`$test_exit_code\`"
echo
echo "## Commands"
echo "1. \`cd adminfront\`"
echo "2. \`npm ci\`"
echo "3. \`npx playwright install --with-deps\`"
echo "4. \`npm test\`"
echo
echo "## Log Tail (last 200 lines)"
echo '```text'
tail -n 200 reports/adminfront-test.log
echo '```'
} > reports/adminfront-test-failure-report.md
fi
exit "$test_exit_code"
- name: Publish adminfront failure summary
if: ${{ failure() }}
run: |
if [ -f reports/adminfront-test-failure-report.md ]; then
cat reports/adminfront-test-failure-report.md >> "$GITHUB_STEP_SUMMARY"
fi
- name: Upload adminfront failure report artifact
if: ${{ failure() }}
uses: actions/upload-artifact@v4
with:
name: adminfront-test-failure-report
path: |
reports/adminfront-test-failure-report.md
reports/adminfront-test.log
adminfront/playwright-report
adminfront/test-results
if-no-files-found: ignore
devfront-tests:
needs: lint
if: ${{ always() && (github.event_name != 'workflow_dispatch' || inputs.run_devfront_tests == true) }}
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
cache-dependency-path: devfront/package-lock.json
- name: Install devfront dependencies
run: |
cd devfront
npm ci
- name: Provision browsers for devfront tests
run: |
cd devfront
npx playwright install --with-deps
- name: Run devfront tests
run: |
mkdir -p reports
set +e
cd devfront
npm test 2>&1 | tee ../reports/devfront-test.log
test_exit_code=${PIPESTATUS[0]}
cd ..
set -e
if [ "$test_exit_code" -ne 0 ]; then
{
echo "# Devfront Test Failure Report"
echo
echo "- Workflow: \`${GITHUB_WORKFLOW:-Code Check}\`"
echo "- Job: \`devfront-tests\`"
echo "- Exit Code: \`$test_exit_code\`"
echo
echo "## Commands"
echo "1. \`cd devfront\`"
echo "2. \`npm ci\`"
echo "3. \`npx playwright install --with-deps\`"
echo "4. \`npm test\`"
echo
echo "## Log Tail (last 200 lines)"
echo '```text'
tail -n 200 reports/devfront-test.log
echo '```'
} > reports/devfront-test-failure-report.md
fi
exit "$test_exit_code"
- name: Publish devfront failure summary
if: ${{ failure() }}
run: |
if [ -f reports/devfront-test-failure-report.md ]; then
cat reports/devfront-test-failure-report.md >> "$GITHUB_STEP_SUMMARY"
fi
- name: Upload devfront failure report artifact
if: ${{ failure() }}
uses: actions/upload-artifact@v4
with:
name: devfront-test-failure-report
path: |
reports/devfront-test-failure-report.md
reports/devfront-test.log
devfront/playwright-report
devfront/test-results
if-no-files-found: ignore

45
README.md
View File

@@ -301,6 +301,51 @@ KETO_WRITE_URL = "http://keto:4467"
- **Flutter(User)**: `userfront/lib/i18n.dart`에서 `tr(key, fallback, params)` 사용. `locales/*.toml`을 `tools/i18n-scanner/gen-flutter-i18n.js`로 `userfront/lib/i18n_data.dart`에 사전 생성합니다.
- **검증**: `node tools/i18n-scanner/index.js`로 코드-키-로케일 동기화 상태를 점검합니다.
## 🧪 Code Check CI
워크플로우 파일: `.gitea/workflows/code_check.yml`
### 트리거
- `push` (`dev` 브랜치)
- `pull_request` (`dev` 대상)
- `workflow_dispatch` (수동 실행)
### workflow_dispatch 입력값
- `run_lint`: Go/Flutter lint 실행 여부
- `run_backend_tests`: backend 테스트 실행 여부
- `run_userfront_tests`: userfront 테스트 실행 여부
- `run_adminfront_tests`: adminfront 테스트 실행 여부
- `run_devfront_tests`: devfront 테스트 실행 여부
### 실행 잡
- `lint`
- `backend-tests`
- `userfront-tests`
- `adminfront-tests`
- `devfront-tests`
### 프런트 테스트 브라우저 프리비저닝 정책
- `userfront-tests`
- 실행 가능한 Chrome/Chromium을 탐지하고, 없으면 설치 후 테스트 실행
- `CHROME_EXECUTABLE` 지정 후 웹 테스트를 실행
- `adminfront-tests`, `devfront-tests`
- Playwright 기반 테스트
- `npx playwright install --with-deps`로 브라우저/OS 의존성을 사전 설치
### 실패 보고서 확인 방법
테스트가 실패하면 다음이 자동 생성됩니다.
- Job Summary: 실패 원인 요약(Markdown) 즉시 확인
- Artifact: 상세 로그/리포트 다운로드
- `backend-test-failure-report`
- `userfront-test-failure-report`
- `adminfront-test-failure-report`
- `devfront-test-failure-report`
### userfront의 `skipped` 테스트 안내
- `locale_storage_platform_test.dart`는 웹 전용 테스트(`kIsWeb`)를 포함합니다.
- 따라서 일반 `flutter test`(VM)에서는 일부 테스트가 `skipped` 되는 것이 정상입니다.
- 실제 웹 실행 검증은 별도 단계에서 수행합니다.
- `flutter test --platform chrome test/locale_storage_platform_test.dart`
### 로컬 개발 (Manual)
Docker 없이는 개발할 수 없지만 Backend 및 [user/admin/dev]Front 코드는 개발모드로 수정하며 개발가능.
백그라운드로 infra 및 ory stack이 구동중이라는 가정

88
docs/organization-chart-policy.md Normal file
View File

@@ -0,0 +1,88 @@
# Organization Chart Architecture & Implementation Policy (ADR)
## 1. Overview (개요)
본 문서는 Baron SSO 내 `adminfront`에서 사용될 **조직도(Organization Chart) 및 다중 테넌시(Multi-Tenancy) 대응 기능**에 대한 아키텍처 결정 사항(Architecture Decision Record)과 세부 구현 방향을 정의합니다.
이 정책은 기존 B2B 테넌트 모델(`Tenant`)과 사내 사용자 그룹 모델(`UserGroup`), 그리고 Ory Keto 기반의 권한 제어(ReBAC) 시스템 간의 일관성을 유지하면서, 복잡하고 다양한 형태의 고객사별 조직 구조(N-Depth)를 지원하기 위해 작성되었습니다.
---
## 2. Core Architectural Decisions (핵심 아키텍처 결정)
### 2.1 B2B Tenant vs. Internal UserGroup Hierarchy (테넌트 vs. 유저그룹 계층화)
조직의 계층(Hierarchy)을 표현하기 위해 `Tenant` 자체를 중첩(Nested)시킬 것인지, 아니면 단일 `Tenant` 내의 `UserGroup`을 중첩시킬 것인지에 대한 결정입니다.
* **Decision (결정):** 조직도는 **`UserGroup` 내부의 자기 참조(`parent_id`)를 통해 계층화**합니다.
* **Rationale (이유):**
* **관심사 분리 (Separation of Concerns):** `Tenant` 모델은 결제, 도메인 매핑, B2B 고객사(Company) 격리 등 무거운 비즈니스 로직을 담고 있습니다. "개발팀", "인사부"와 같은 단순한 사내 조직 단위까지 `Tenant` 테이블에 저장하면 시스템 복잡도가 기하급수적으로 증가합니다.
* **조회 성능 (Performance):** 특정 고객사(Company)의 전체 조직도를 그릴 때 `SELECT * FROM user_groups WHERE tenant_id = ?` 단일 쿼리로 모든 노드를 가져와 애플리케이션 메모리에서 트리를 구성할 수 있어 성능상 매우 유리합니다.
* **단일 진실 공급원 (SoT):** 회사(Company) 단위의 물리적 격리는 `Tenant`가, 논리적인 사내 부서/팀 구조는 `UserGroup`이 담당하도록 역할을 명확히 분리합니다.
### 2.2 Flexible N-Depth Organizational Structure (유연한 N-Depth 조직 구조)
고객사마다 조직 단계(부, 국, 실, 본부, 파트, 반, 셀 등)의 명칭과 깊이(Depth)가 다릅니다. 이를 하드코딩된 Enum으로 제한해서는 안 됩니다.
* **Decision (결정):** 조직의 단계나 명칭을 시스템(DB 스키마)에서 강제하지 않으며, **N-Depth 인접 목록(Adjacency List) 모델을 사용**합니다.
* **Implementation (구현):**
* `UserGroup` 모델에 `parent_id` (UUID, Nullable) 컬럼을 추가하여 부모-자식 관계를 형성합니다.
* 조직 타입(`unit_type`) 필드는 고정된 Enum(예: `TEAM`, `GROUP`) 대신, 고객사가 자유롭게 입력할 수 있는 **동적 문자열(`String`)**로 관리하거나, 계층의 상대적 깊이(Depth)만을 의미 단위로 사용합니다.
* 프론트엔드의 Checkbox Tree 컴포넌트는 재귀적(Recursive)으로 설계되어 데이터의 깊이에 상관없이 무한한 N-Depth를 렌더링할 수 있어야 합니다.
---
## 3. Data Structure & Schema Updates (데이터 구조 및 스키마 업데이트)
새로운 테이블을 추가하는 대신, 기존 모델을 확장하여 중복을 방지합니다.
### 3.1 `user_groups` 테이블 확장
조직 계층 및 부서 단위 표현을 위해 필드를 추가합니다.
* `id`, `tenant_id`, `name`, `description` (기존 유지)
* **`parent_id` (UUID, Nullable FK):** 상위 `UserGroup` 참조 (조직 트리 구성).
* **`unit_type` (String, Optional):** 조직 단위 명칭 (예: "본부", "실", "팀"). 시스템이 강제하지 않으며 프론트엔드 라벨링 용도로 사용됩니다.
### 3.2 `users` 테이블 확장 (직급 및 직무)
CSV에서 업로드되는 사용자의 인사 정보(직급, 직무 등)는 `User` 모델에 직접 저장합니다.
* **`position` (String):** 직급 (예: "수석", "책임", "사원").
* **`job_title` (String):** 직무 (예: "프론트엔드 개발", "기획").
* *(또는 기존에 존재하는 `Metadata` (JSONB) 필드를 활용하여 스키마 변경 없이 동적 속성으로 관리할 수도 있습니다.)*
---
## 4. ReBAC Integration Policy (Ory Keto 연동 정책)
DB의 `user_groups` 계층 트리는 Ory Keto의 관계 튜플(Tuple)과 동기화되어 권한 제어에 사용됩니다. (기존 통합 권한 정책 `tenant-usergroup-policy.md` 준수)
1. **조직 계층 동기화 (Hierarchy):**
* DB에서 A팀(`UserGroup`)이 B본부(`UserGroup`)의 하위로 설정되면, Keto에는 `UserGroup:<A팀_ID>#parent@UserGroup:<B본부_ID>` 튜플이 생성됩니다.
2. **소속원 매핑 (Membership):**
* 유저가 A팀에 속하면 `UserGroup:<A팀_ID>#members@User:<유저_ID>` 튜플이 생성됩니다.
3. **조직장 및 어드민 승격 (Leadership):**
* CSV 데이터 분석 또는 수동 지정을 통해 특정 유저가 A팀의 '조직장'으로 식별되면, `UserGroup:<A팀_ID>#owners@User:<유저_ID>` 튜플이 생성됩니다.
* 정책에 따라 `owners` 관계를 가진 유저는 해당 조직(UserGroup)과 그 하위 조직에 대한 `admins` 권한을 자동으로 상속받습니다.
---
## 5. Data Loading & CSV Upload Strategy (데이터 로딩 및 CSV 업로드 전략)
고정된 컬럼 구조는 다양한 회사의 조직도를 수용할 수 없으므로 유연한 파싱 로직이 필요합니다.
### 5.1 Flexible CSV Format (유연한 CSV 포맷)
* **경로 기반 방식 (Path-based):** 조직 계층을 슬래시(`/`) 등으로 구분하여 하나의 문자열로 전달받습니다.
* *예시 컬럼:* `[조직_경로, 직급, 이름, 직무, 이메일]`
* *데이터 예시:* `"개발본부/클라우드실/플랫폼팀", "수석", "홍길동", "백엔드 개발", "hong@example.com"`
* **동적 뎁스 방식 (Dynamic Depth):** 뒤에서부터 고정된 사용자 속성 열(직급, 직무, 이름, 이메일 등)을 식별하고, 그 앞의 모든 열을 동적인 계층 구조로 해석합니다.
### 5.2 Processing Flow (처리 흐름)
1. **Parsing & Validation:** 프론트엔드/백엔드에서 유연한 CSV 포맷을 파싱하고, `UserGroup` 계층 경로를 분석합니다.
2. **Tree Resolution:** 백엔드는 "개발본부 > 클라우드실 > 플랫폼팀" 경로를 DB에서 조회하거나 없으면 순차적으로 생성(`parent_id` 매핑)하여 `UserGroup` ID 트리를 완성합니다.
3. **User Upsert:** `User` 정보를 생성하거나 업데이트(`position`, `job_title` 갱신)합니다.
4. **Keto Synchronization:** DB 트랜잭션 완료 후, Background Worker가 변경된 조직 계층과 멤버십 정보를 기반으로 Ory Keto 튜플을 생성/삭제(Reconciliation)합니다.
---
## 6. Frontend Multi-Tenancy UI (프론트엔드 다중 테넌트 UI)
관리자가 여러 테넌트(Company)에 접근 권한이 있을 경우, 조직도를 명확히 구분하여 보여주어야 합니다.
* **Tabs Interface:** 화면 상단 또는 측면에 사용자가 접근 가능한 최상위 `Tenant` 목록을 탭(Tabs) 형태로 제공합니다.
* **Scoped Fetching:** 특정 탭(Tenant)을 선택할 때마다 해당 `tenant_id`를 파라미터로 백엔드 API를 호출하여, 격리된 해당 회사만의 `UserGroup` 트리를 렌더링합니다.
* **Checkbox Tree Component:** Radix UI와 TailwindCSS를 기반으로 개발되며, N-Depth 중첩을 지원하고 부모-자식 간의 반선택(Indeterminate) 상태를 재귀적으로 계산하는 독립적인(Reusable) 컴포넌트로 구현됩니다.

180
docs/tenant-usergroup-policy.md
View File

@@ -1,68 +1,154 @@
# 유저 그룹 및 테넌트 통합 권한 정책 (Integrated Policy)
# 통합 테넌트 및 권한 아키텍처 정책 (Integrated Tenant & ReBAC Policy)
이 문서는 Baron SSO의 테넌트(Tenant)와 유저 그룹(User Group) 간의 관계 및 권한 상속에 관한 공식 정책을 정의합니다.
이 문서는 Baron SSO 시스템 내 B2C(개인)부터 B2B(단일기업), B2B2B(그룹사) 및 사내 조직도(`UserGroup`)에 이르는 모든 격리 공간과 권한 상속을 다루는 **다형성 테넌트(Polymorphic Tenant)**의 공식 정책을 정의합니다.
이 정책은 기존의 단순 `Tenant` 및 `UserGroup` 모델을 발전시켜, Ory Kratos(Identity), PostgreSQL(Business), Ory Keto(ReBAC) 3개의 분산 시스템 간 역할을 명확히 하고 데이터 정합성을 강제합니다.
---
## 1. 기본 원칙 (Core Axioms)
### 1.1 유저 그룹의 테넌트성 (User Group as a Tenant)
- **모든 테넌트가 유저 그룹은 아니지만, 모든 유저 그룹은 반드시 테넌트의 속성을 가집니다.**
- 유저 그룹은 "사용자들의 집합"인 동시에, 그 자체가 권한을 담고 다른 자원을 소유할 수 있는 **격리된 공간(Tenant)**으로 취급됩니다.
### 1.1 "모든 격리 공간은 테넌트이다" (Everything is a Tenant)
- 개인 워크스페이스, 기업 고객, 지주사, 그리고 사내의 특정 팀이나 본부(`UserGroup`) 등 **모든 종류의 격리 공간은 최상위 범용 단위인 `Tenant`로 취급**됩니다.
- 과거에 혼용되던 `UserGroup` 네임스페이스는 폐기되며, 격리 공간을 나타내는 Keto(ReBAC) 네임스페이스는 `Tenant` 하나로 단일화됩니다. 권한 상속 로직은 테넌트의 성격과 무관하게 동일하게 동작합니다.
### 1.2 권한 상속 로직의 단일화 (Unified Inheritance)
- 테넌트 간의 상속(Parent-Child Tenant)과 유저 그룹의 권한 전파(Group-Member)는 **기술적으로 동일한 ReBAC 로직**을 사용합니다.
- `UserGroup:members` 관계는 `Tenant:members`와 동일한 우선순위를 가지며, 시스템은 이를 구분 없이 하나의 상속 트리로 처리합니다.
### 1.2 "권한 주체와 자원의 분리" (Namespaces)
시스템의 완벽한 권한 통제를 위해, Keto에는 `Tenant` 외에도 다음과 같은 필수 네임스페이스가 존재합니다.
- **`Tenant`:** 격리된 공간 (회사, 부서, 개인)
- **`RelyingParty`:** 테넌트가 소유하는 자원/앱 (OIDC 클라이언트)
- **`System`:** 테넌트에 종속되지 않는 전역 권한 (Super Admin 등)
### 1.3 그룹장-어드민 연동 (Leader-Admin Mapping)
- 특정 유저 그룹에 명시적으로 **'그룹장(Group Leader)'**을 지정하면, 시스템은 해당 사용자를 해당 유저 그룹(테넌트)의 **'테넌트 어드민(Tenant Admin)'**으로 자동 격상합니다.
- 그룹장은 해당 그룹이 소유한 모든 하위 테넌트 및 리소스에 대해 완전한 제어권을 가집니다.
### 1.3 소유(Ownership)와 가시성(Visibility)의 분리
- 시스템의 모든 자원(예: RelyingParty, 앱)은 반드시 특정 `Tenant`가 소유(`manage`)합니다.
- 그러나 자원의 소유권과 **누가 접근할 수 있는가(가시성, `access`)는 별개**입니다. 내부망용 앱(Private)과 대국민 서비스(Public)를 동일한 기업(Tenant)이 동시에 소유하고 제어할 수 있습니다.
## 2. 권한 흐름도 (Mermaid)
### 1.4 단일 진실 공급원 분리 (Separation of SoT)
- **Kratos (Identity):** "누구인가?" (인증, 이메일, 패스워드 등 순수 식별 정보). 테넌트, 직급 등 관계형 데이터는 절대 보관하지 않습니다.
- **PostgreSQL (Business):** "어디에 속하며 조직 구조는 어떠한가?" (직급, 조직도, 테넌트 설정 등).
- **Keto (ReBAC):** "무엇을 할 수 있는가?" (권한 및 상속).
---
## 2. 하이브리드(다형성) 테넌트 아키텍처
데이터베이스의 `tenants` 테이블은 가장 가벼운 신분증(Identity) 역할을 수행하며, 세부 비즈니스 설정은 타입별로 별도의 테이블에 1:1 조인(Join)하여 관리합니다.
### 2.1 테넌트 유형 (Tenant Types)
| 타입 (Enum) | 설명 | 특징 및 1:1 조인 테이블 |
| :--- | :--- | :--- |
| `PERSONAL` | B2C 개인 워크스페이스 | 일반 사용자 가입 시 1:1로 생성. 조직도(UserGroup) 기능 비활성화. |
| `COMPANY` | B2B 일반 기업/법인 | 독립된 비즈니스. 사내 조직도를 가짐. 무거운 설정은 `company_settings`에 저장. |
| `COMPANY_GROUP`| B2B2B 지주사/그룹사 | 여러 `COMPANY`를 하위로 거느리며 최고 관리자 권한을 통합. `company_settings` 조인. |
| `USER_GROUP` | 사내 조직 (본부/팀 등) | `COMPANY` 내부에 속하는 조직. 사내 조직도 메타데이터는 `user_groups` 테이블에 저장. |
---
## 3. ReBAC 권한 상속 및 관계 튜플 (Keto Tuples)
이전에는 `UserGroup` 네임스페이스가 존재했으나, 이제 모든 권한 검증은 오직 `Tenant` 네임스페이스 내에서 처리됩니다.
### 3.1 조직장(Leader)과 어드민(Admin) 상속
특정 부서(테넌트)의 그룹장(`owners`)으로 임명되면, 해당 부서 및 그 하위 부서의 최고 관리자(`admins`) 권한을 자동으로 상속받습니다.
- **조직장 임명:** `Tenant:<조직ID>#owners@User:<유저ID>`
- **자동 상속 룰:** `Tenant:<조직ID>#admins@Tenant:<조직ID>#owners`
### 3.2 계층 간 권한 상속 (Hierarchy)
지주사(COMPANY_GROUP) $\rightarrow$ 법인(COMPANY) $\rightarrow$ 사내조직(USER_GROUP) 간의 상속은 모두 `parents` 튜플을 사용합니다.
- **계층 설정:** `Tenant:<하위ID>#parents@Tenant:<상위ID>`
- **자동 상속 룰:** 상위 테넌트의 `admins`는 하위 테넌트의 `manage` 및 `view` 권한을 모두 가집니다.
### 3.3 리소스 제어 및 RP Admin (Relying Party)
RP(앱)는 별도의 가상 테넌트를 만들지 않고 자원(Object) 자체의 다중 상속을 통해 권한을 제어합니다.
- **앱 관리 (Manage):**
- `RelyingParty:<앱ID>#parents@Tenant:<소유테넌트ID>` (앱 소유권 지정. 해당 테넌트의 최고 관리자가 앱을 관리할 수 있음)
- `RelyingParty:<앱ID>#admins@User:<유저ID>` (특정 유저를 **RP Admin**으로 직접 지정)
- **Private 앱 접근 (Access):** `RelyingParty:<앱ID>#access@Tenant:<소유테넌트ID>#members` (소유한 회사의 멤버만 접근)
- **Public 앱 접근 (Access):** `RelyingParty:<앱ID>#access@System:authenticated_users#members` (전역 인증 유저 누구나 접근)
---
## 4. 권한 흐름도 (Mermaid)
```mermaid
graph TD
%% Roles
Leader[Group Leader / 그룹장]
Member[Group Member / 멤버]
%% Entities (Polymorphic)
subgraph UG_T [User Group / Specialized Tenant]
UG_ID[Group: Hanmac 운영팀]
%% Types
subgraph COMPANY_GROUP [지주사 테넌트]
CG[Tenant: 한맥 그룹]
end
subgraph Child_T [Child Tenants / 하위 테넌트]
T1[Tenant: 한맥 엔지니어링]
T2[Tenant: 한맥 IT]
subgraph COMPANY [법인 테넌트]
C1[Tenant: 한맥 IT]
end
%% Policy Links
Leader -- "Explicitly Assigned" --> UG_ID
Leader -. "Automatically Becomes" .-> Admin[Tenant Admin]
Member -- "is member of" --> UG_ID
%% Inheritance (Identical Logic)
UG_ID -- "Inherits Access To" --> T1
UG_ID -- "Inherits Access To" --> T2
subgraph USER_GROUP [사내조직 테넌트]
UG1[Tenant: 개발본부]
UG2[Tenant: 클라우드팀]
end
%% Effective Access
Admin -- "Full Control" --> UG_ID
Member -- "Shared Access" --> T1
Member -- "Shared Access" --> T2
subgraph USERS [사용자]
CEO[User: 그룹 최고경영자]
DEV_L[User: 팀장]
DEV[User: 팀원]
RP_ADM[User: RP 전담 관리자]
end
subgraph RESOURCES [자원]
RP1[RelyingParty: 사내 인트라넷]
end
%% Hierarchy Tuples
C1 -- "parents" --> CG
UG1 -- "parents" --> C1
UG2 -- "parents" --> UG1
RP1 -- "parents" --> C1
%% Memberships
CEO -- "owners" --> CG
DEV_L -- "owners" --> UG2
DEV -- "members" --> UG2
%% RP Admin
RP_ADM -- "admins" --> RP1
%% Effective Admin Control (Inherited)
CEO -. "Inherits Admin Control" .-> C1
CEO -. "Inherits Admin Control" .-> UG1
CEO -. "Inherits Admin Control" .-> UG2
CEO -. "Inherits Manage" .-> RP1
DEV_L -. "Inherits Admin Control" .-> UG2
%% Styles
style UG_ID fill:#f9f,stroke:#333,stroke-width:2px
style Leader fill:#ff9,stroke:#333
style Admin fill:#ffd,stroke:#333,stroke-dasharray: 5 5
style CG fill:#dfd,stroke:#333
style C1 fill:#dfd,stroke:#333
style UG1 fill:#f9f,stroke:#333
style UG2 fill:#f9f,stroke:#333
style CEO fill:#ff9,stroke:#333
style DEV_L fill:#ff9,stroke:#333
style RP_ADM fill:#ff9,stroke:#333
style RP1 fill:#bbf,stroke:#333
```
## 3. 기술적 구현 가이드 (Implementation)
---
### 3.1 Keto Relationship Tuples
- **그룹장 임명:** `UserGroup:<ID>#owners@User:<UserID>`
- **어드민 자동 승격:** `Tenant:<ID>#admins@UserGroup:<ID>#owners` (그룹 소유자는 해당 테넌트의 어드민)
- **멤버십:** `UserGroup:<ID>#members@User:<UserID>`
## 5. 분산 시스템 정합성 강제 정책 (Data Consistency Check)
### 3.2 기대 효과
- **정책 단순화:** '어드민'과 '그룹장'을 별도로 관리할 필요가 없어 시스템 복잡도가 감소합니다.
- **책임 명확화:** 그룹의 장이 해당 자원의 최종 책임자가 되는 직관적인 거버넌스를 수립합니다.
- **일관된 UX:** 사용자는 자신이 관리하는 것이 '테넌트'인지 '그룹'인지 고민할 필요 없이 동일한 관리 도구를 사용합니다.
인증(Kratos), 비즈니스 로직(PG), 권한(Keto)이 어긋나지 않도록 다음의 안전 장치를 반드시 구현해야 합니다.
### 5.1 트랜잭셔널 아웃박스 패턴 (Transactional Outbox)
- **목적:** 백엔드 DB에는 저장되었으나, 일시적인 네트워크 장애로 인해 Keto(ReBAC)에 권한이 저장되지 않는 '부분 실패(Partial Failure)' 방지.
- **방식:** DB에 새로운 테넌트(`UserGroup` 등) 생성 시, 동일 DB 트랜잭션 내에서 `keto_outbox` 테이블에 튜플 이벤트를 함께 저장합니다. 이후 Background Worker가 이를 안전하게 Keto로 동기화(재시도 보장)합니다.
### 5.2 삭제 정책 연동 (Delete Cascade)
- **보안 원칙 (즉시 회수):** 백엔드에서 테넌트나 유저를 Soft Delete(`deleted_at`) 처리하는 즉시, Outbox를 통해 **Keto의 관련된 모든 튜플을 Hard Delete**하여 권한을 즉각적으로 회수합니다.
- **Kratos 계정 삭제:** 사용자가 계정을 영구 탈퇴할 경우, Kratos에서 데이터가 지워지기 직전에 백엔드로 Webhook을 전송하여 Keto 권한 및 로컬 `users` 테이블의 프로필 데이터를 먼저 비우도록 연동합니다.
### 5.3 Kratos-Backend 실시간 동기화 (Webhooks)
- Kratos에서의 회원 가입(`after_registration`) 및 정보 변경(`after_settings`) 발생 시, 즉시 Webhook을 발생시켜 Backend의 `users` 테이블(프로필 로컬 캐시)을 Upsert 합니다.
### 5.4 정기 대사 스크립트 (Reconciliation Cron Job)
- 매일 1회 이상 배치 작업을 돌려 분산 시스템 간 엣지 케이스 오류를 복구합니다.
- **검증 항목:**
1. Keto에 남아있는 고아 튜플(Orphaned Tuples) 검출 및 자동 삭제.
2. DB의 `user_groups` 멤버십에는 존재하나 Keto 튜플에서 누락된 권한 색출 및 복원.
3. Kratos와 Backend 간 유저 ID 매핑 상태 일치 여부 스캔.

152
docs/test-plan.md
View File

@@ -5,128 +5,38 @@
- 멀티 서비스(Backend/Ory Stack/Front) 연동 품질 확보
- 릴리즈 기준과 장애 분석 기준의 표준화
## 2) 범위
### 포함
- Backend (Go Fiber)
- UserFront (Flutter Web/App)
- AdminFront / DevFront (React)
- Ory Stack (Kratos/Hydra/Keto/Oathkeeper)
- Gateway/네트워크 구성 (baron_net, ory-net, public_net)
- DB (PostgreSQL, ClickHouse, Redis)
## 2) 현재 기준 스냅샷
- 기준 시각: 2026-02-19 16:32:09 KST
- 기준 커밋: `85998bd`
- Backend 전체 statement coverage: **24.7%**
- 테스트 인벤토리 수량:
- Backend(Go): **104개**
- UserFront(Flutter): **47개**
- AdminFront/DevFront(Playwright): **4개**
### 제외(별도 계획)
- 외부 IDP 벤더의 장애 대응 (Descope 등)
- 프로덕션 데이터 복구 시나리오(백업/DR)
### Backend 패키지별 커버리지
- `cmd/server`: 2.6%
- `internal/handler`: 25.0%
- `internal/idp`: 16.6%
- `internal/middleware`: 59.6%
- `internal/response`: 91.7%
- `internal/service`: 32.7%
- `internal/utils`: 24.5%
- `internal/validator`: 89.3%
## 3) 원칙
- **Shift-left**: 개발 단계에서 최대한 조기 검증
- **단계적 신뢰**: Unit → Integration → E2E 순으로 신뢰도 상승
- **환경 분리**: 로컬/스테이징/프로덕션 구성 차이를 문서로 명시
- **결정적 테스트**: 시간/랜덤/외부 의존성 최소화
- **Idempotent**: 반복 실행 시 동일 결과 보장
- **보안 우선**: 민감정보(PII/Token)는 테스트 로그에 노출 금지
- **실패 우선 기록**: 실패 로그/재현 절차를 우선 확보
## 3) 하위 문서 (전수 목록)
- Backend 테스트 전수 목록: `docs/test-plan/backend-test-inventory.md`
- UserFront 테스트 전수 목록: `docs/test-plan/userfront-test-inventory.md`
- AdminFront/DevFront E2E 전수 목록: `docs/test-plan/web-e2e-test-inventory.md`
## 4) 테스트 레이어 및 목표
### 4.1 Unit Test
- Backend: 비즈니스 로직, 유효성 검증, Mapper/Adapter
- Frontend: 유틸/상태관리/컴포넌트 로직
- 목표: 빠른 피드백(수초~수분)
## 4) 실행 커맨드
- Backend 전체 테스트: `cd backend && go test ./...`
- Backend 커버리지: `cd backend && go test ./... -coverprofile=coverage.out && go tool cover -func=coverage.out`
- UserFront 테스트: `cd userfront && flutter test`
- AdminFront E2E: `cd adminfront && npm test`
- DevFront E2E: `cd devfront && npm test`
### 4.2 Integration Test
- Backend + DB(Postgres/ClickHouse/Redis)
- Backend + Ory Admin API (Kratos/Hydra/Keto)
- 목표: 네트워크/스토리지 연동 검증
### 4.3 Contract Test
- Backend ↔ Frontend API 스키마/응답 계약 검증
- OIDC/OpenID Connect 표준 응답 형식 검증
### 4.4 E2E Test (Happy/Edge Path)
- 로그인 플로우(Password / Magic Link / SMS / QR)
- Consent 플로우 (Hydra login/consent)
- 토큰 발급/재발급/로그아웃/세션 만료
- 목표: 핵심 사용자 여정의 회귀 방지
### 4.5 Smoke Test
- 배포 직후 필수 엔드포인트 헬스체크
- `GET /health`, Ory readiness, UserFront 정적 리소스
### 4.6 Regression / Non-functional
- 성능: 로그인/토큰 발급 지연, 대량 감사 로그 적재
- 보안: 인증 우회, 권한 상승, 세션 고정 공격
- 관측성: 핵심 로그/메트릭 누락 여부
## 5) 환경 전략
- 로컬: `make up-all` 또는 `docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml up -d`
- 스테이징: 프로덕션과 동일한 네트워크/도메인 구성
- 프로덕션: 최소한의 smoke/관측성 점검
## 6) 테스트 데이터 정책
- 표준 시드 사용자/테넌트/클라이언트 세트 정의
- PII 마스킹 규칙(이메일/전화번호/토큰)
- 재현용 고정 데이터와 랜덤 데이터 분리
- 테스트 종료 후 클린업 규칙 정의
## 7) 자동화 및 CI/CD 기준 (현행)
- **현재 상태**: 레포에 CI/CD 워크플로우 정의가 없음. 테스트는 로컬/수동 실행 기준으로 운영.
- **CI 변수 활용**: AdminFront/DevFront Playwright 설정은 `CI` 환경 변수에 따라 재시도/워커 수를 조정함.
- **수동 실행 기준**:
- Backend: `go test ./...` (위치: `backend/`)
- UserFront: `flutter test` (위치: `userfront/`)
- AdminFront: `npm test` (Playwright, 위치: `adminfront/`, baseURL `http://localhost:5173`)
- DevFront: `npm test` (Playwright, 위치: `devfront/`, baseURL `http://localhost:5174`)
### 7.1 수동 게이트 제안(현행 기준)
- PR/머지 전 최소 기준: Backend Unit + 해당 Front 테스트(변경 범위)
- 배포 전 최소 기준: Smoke + 핵심 E2E(로그인/Consent)
## 8) 핵심 플로우 테스트 시나리오
### 인증/세션
- Password 로그인 성공/실패/락/재시도
- Magic Link 발송/검증/만료
- SMS 코드 발송/검증/재시도 제한
- QR 승인/거절/타임아웃
- 로그아웃 시 세션/쿠키/토큰 무효화
### 원격 링크 로그인(verify-only)
- Desktop에서 링크 요청 → Mobile에서 링크 클릭(verifyOnly) → Desktop Poll로 세션 발급
- Mobile 단말에 세션 생성/로그인이 발생하지 않는지 확인
- Audit/로그인 이력에 Desktop 세션 ID만 기록되는지 확인
- 인증수단 표기(SMS/Email)가 요청 수단과 일치하는지 확인
- 코드/링크 만료 시 승인 실패 및 재요청 안내
### OIDC/Hydra
- Login Challenge 처리
- Consent 승인/거절
- Token/Refresh Token 발급
- Redirect URI 검증
### 권한/정책(Keto)
- 권한 부여/회수 시 접근 제어 확인
- 관리자/일반 사용자 분리
### 네트워크/프록시
- `baron_net`와 `ory-net` 경계 준수
- Frontend에서 Ory 내부 Admin 포트 접근 불가
## 9) 관측성/장애 대응 테스트
- 에러 로그 구조(필수 필드 포함) 확인
- Audit Log 누락/중복 체크
- 실패 시 재시도 정책 검증
## 10) 책임 및 운영 프로세스
- 각 영역별 오너 지정(Backend/Front/Ory)
- 실패 시 triage 기준: 재현 가능 여부 → 영향도 → 우선순위
- 테스트 케이스/기대 결과는 이슈/PR에 링크
## 11) 유지보수 원칙
- 신규 기능은 반드시 관련 테스트 추가
- 회귀 버그 발생 시 재현 테스트를 우선 추가
- 불안정 테스트는 원인 분석 후 격리 또는 개선
## 12) 체크리스트 (릴리즈 전)
- Smoke 통과
- 핵심 E2E 통과
- 보안 관련 회귀 없음
- 장애/모니터링 대시보드 정상
## 5) 유지 원칙
- 신규 기능은 관련 테스트를 반드시 추가합니다.
- 회귀 이슈는 재현 테스트를 먼저 추가하고 수정합니다.
- 본 문서의 수치/목록은 `origin/dev` 기준으로 주기적으로 갱신합니다.

111
docs/test-plan/backend-test-inventory.md Normal file
View File

@@ -0,0 +1,111 @@
# Backend 테스트 전수 목록
- 범위: `backend/cmd/server`, `backend/internal/**`
- 기준: `func Test...` 패턴으로 수집한 단위/통합 테스트
| 파일 | 테스트 | 역할 |
|---|---|---|
| `backend/cmd/server/error_handler_test.go:23` | `TestNewErrorHandler_ProductionMasksServerError` | 오류/예외/거부 경로 검증 |
| `backend/cmd/server/error_handler_test.go:48` | `TestNewErrorHandler_ProductionPassesClientError` | 오류/예외/거부 경로 검증 |
| `backend/cmd/server/error_handler_test.go:73` | `TestNewErrorHandler_DevelopmentReturnsOriginalServerError` | 오류/예외/거부 경로 검증 |
| `backend/cmd/server/error_handler_test.go:98` | `TestNewErrorHandler_MapsUnauthorizedCode` | 오류/예외/거부 경로 검증 |
| `backend/internal/handler/api_key_handler_test.go:19` | `TestApiKeyHandler_CreateApiKey` | 핵심 CRUD/서비스 동작 검증 |
| `backend/internal/handler/api_key_handler_test.go:41` | `TestApiKeyHandler_Validation` | 유효성/정책/유틸 검증 |
| `backend/internal/handler/auth_handler_async_test.go:198` | `TestSignup_AsyncDB_Isolation` | 복구/격리/회복 탄력성 검증 |
| `backend/internal/handler/auth_handler_client_test.go:16` | `TestRevokeLinkedRp_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_client_test.go:56` | `TestListRpHistory_Aggregation` | Hydra/RP 연동 검증 |
| `backend/internal/handler/auth_handler_consent_test.go:134` | `TestAcceptConsentRequest_Normal` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_consent_test.go:26` | `TestGetConsentRequest_Normal` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_consent_test.go:71` | `TestGetConsentRequest_Skip_AutoAccept` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_link_test.go:24` | `TestEnchantedLinkFlow_Email_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_link_test.go:94` | `TestEnchantedLinkFlow_Sms_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_linked_test.go:26` | `TestListLinkedRps_PriorityAndAggregation` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_login_test.go:114` | `TestPasswordLogin_OIDC_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_login_test.go:201` | `TestPasswordLogin_OIDC_InactiveClient` | 오류/예외/거부 경로 검증 |
| `backend/internal/handler/auth_handler_login_test.go:255` | `TestPasswordLogin_NoOIDC_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_oidc_test.go:106` | `TestAcceptOidcLoginRequest_TokenFallbackToCookie` | 복구/격리/회복 탄력성 검증 |
| `backend/internal/handler/auth_handler_oidc_test.go:21` | `TestAcceptOidcLoginRequest_CookieOnly` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_otp_test.go:14` | `TestHandleKratosCourierRelay_Email` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_otp_test.go:43` | `TestVerifySignupCode_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_otp_test.go:85` | `TestVerifySignupCode_Invalid` | 오류/예외/거부 경로 검증 |
| `backend/internal/handler/auth_handler_qr_test.go:107` | `TestScanQRLogin_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_qr_test.go:150` | `TestResolveConsentSubjects_TokenAndCookie` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_qr_test.go:57` | `TestQRLoginFlow_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/auth_handler_test.go:20` | `TestCompletePasswordReset_MissingLoginID` | 오류/예외/거부 경로 검증 |
| `backend/internal/handler/auth_handler_test.go:50` | `TestCompletePasswordReset_InvalidPasswordPolicy` | 오류/예외/거부 경로 검증 |
| `backend/internal/handler/auth_handler_test.go:80` | `TestCompletePasswordReset_NilIDPProvider` | 인증/OIDC 플로우 검증 |
| `backend/internal/handler/dev_handler_test.go:103` | `TestCreateClient_Success` | Hydra/RP 연동 검증 |
| `backend/internal/handler/dev_handler_test.go:15` | `TestListClients_Success` | Hydra/RP 연동 검증 |
| `backend/internal/handler/dev_handler_test.go:49` | `TestGetClient_Success` | Hydra/RP 연동 검증 |
| `backend/internal/handler/dev_handler_test.go:83` | `TestGetClient_NotFound` | 오류/예외/거부 경로 검증 |
| `backend/internal/handler/password_policy_test.go:57` | `TestGeneratePasswordUsesNonAlphanumericRequirement` | 유효성/정책/유틸 검증 |
| `backend/internal/handler/tenant_handler_test.go:101` | `TestTenantHandler_ApproveTenant` | 핵심 CRUD/서비스 동작 검증 |
| `backend/internal/handler/tenant_handler_test.go:73` | `TestTenantHandler_CreateTenant` | 핵심 CRUD/서비스 동작 검증 |
| `backend/internal/handler/user_group_handler_test.go:109` | `TestUserGroupHandler_AddMember` | 권한/관계 모델 검증 |
| `backend/internal/handler/user_group_handler_test.go:128` | `TestUserGroupHandler_AssignRole` | 권한/관계 모델 검증 |
| `backend/internal/handler/user_group_handler_test.go:71` | `TestUserGroupHandler_List` | 권한/관계 모델 검증 |
| `backend/internal/handler/user_group_handler_test.go:91` | `TestUserGroupHandler_Create` | 권한/관계 모델 검증 |
| `backend/internal/idp/factory_test.go:123` | `TestChainedProviderMetadataUnion` | 회귀 방지 기본 동작 검증 |
| `backend/internal/idp/factory_test.go:139` | `TestChainedProviderUpdateUserPasswordFallback` | 복구/격리/회복 탄력성 검증 |
| `backend/internal/idp/factory_test.go:152` | `TestChainedProviderUpdateUserPasswordAllFail` | 인증/OIDC 플로우 검증 |
| `backend/internal/middleware/audit_middleware_test.go:42` | `TestAuditMiddleware` | 회귀 방지 기본 동작 검증 |
| `backend/internal/middleware/error_code_enricher_test.go:22` | `TestErrorCodeEnricher_AddsCodeToLegacyErrorResponse` | 오류/예외/거부 경로 검증 |
| `backend/internal/middleware/error_code_enricher_test.go:50` | `TestErrorCodeEnricher_DoesNotOverrideExistingCode` | 오류/예외/거부 경로 검증 |
| `backend/internal/middleware/error_code_enricher_test.go:72` | `TestErrorCodeEnricher_IgnoreSuccessPayload` | 오류/예외/거부 경로 검증 |
| `backend/internal/middleware/rbac_test.go:115` | `TestRequireKetoPermission_Success` | 권한/관계 모델 검증 |
| `backend/internal/middleware/rbac_test.go:138` | `TestRequireTenantMatch_SuperAdmin` | 권한/관계 모델 검증 |
| `backend/internal/middleware/rbac_test.go:160` | `TestRequireTenantMatch_Forbidden` | 오류/예외/거부 경로 검증 |
| `backend/internal/middleware/rbac_test.go:184` | `TestRequireRole_Unauthorized` | 오류/예외/거부 경로 검증 |
| `backend/internal/middleware/rbac_test.go:69` | `TestRequireRole_Success` | 권한/관계 모델 검증 |
| `backend/internal/middleware/rbac_test.go:92` | `TestRequireRole_Forbidden` | 오류/예외/거부 경로 검증 |
| `backend/internal/response/error_response_test.go:22` | `TestErrorWithDetailsResponseShape` | 오류/예외/거부 경로 검증 |
| `backend/internal/response/error_response_test.go:61` | `TestStatusCodeMapping` | 회귀 방지 기본 동작 검증 |
| `backend/internal/service/hydra_admin_service_test.go:102` | `TestHydraAdminService_GetConsentRequest` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/hydra_admin_service_test.go:124` | `TestHydraAdminService_PatchClientStatus` | Hydra/RP 연동 검증 |
| `backend/internal/service/hydra_admin_service_test.go:13` | `TestHydraAdminService_ListClients` | Hydra/RP 연동 검증 |
| `backend/internal/service/hydra_admin_service_test.go:148` | `TestHydraAdminService_UpdateClient` | Hydra/RP 연동 검증 |
| `backend/internal/service/hydra_admin_service_test.go:165` | `TestHydraAdminService_ListConsentSessions` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/hydra_admin_service_test.go:183` | `TestHydraAdminService_RevokeConsentSessions` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/hydra_admin_service_test.go:198` | `TestHydraAdminService_RejectConsentRequest` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/hydra_admin_service_test.go:215` | `TestHydraAdminService_RejectLoginRequest` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/hydra_admin_service_test.go:232` | `TestHydraAdminService_GetLoginRequest` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/hydra_admin_service_test.go:249` | `TestHydraAdminService_AcceptConsentRequest` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/hydra_admin_service_test.go:267` | `TestHydraAdminService_AcceptLoginRequest` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/hydra_admin_service_test.go:294` | `TestHydraAdminService_ErrorHandling` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/hydra_admin_service_test.go:319` | `TestHydraAdminService_NotFound` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/hydra_admin_service_test.go:39` | `TestHydraAdminService_GetClient` | Hydra/RP 연동 검증 |
| `backend/internal/service/hydra_admin_service_test.go:60` | `TestHydraAdminService_CreateClient` | Hydra/RP 연동 검증 |
| `backend/internal/service/hydra_admin_service_test.go:86` | `TestHydraAdminService_DeleteClient` | Hydra/RP 연동 검증 |
| `backend/internal/service/keto_service_test.go:101` | `TestKetoService_ErrorHandling` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/keto_service_test.go:123` | `TestKetoService_CheckPermission_Forbidden` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/keto_service_test.go:12` | `TestKetoService_CheckPermission` | 권한/관계 모델 검증 |
| `backend/internal/service/keto_service_test.go:137` | `TestKetoService_CreateRelation_Retry` | 복구/격리/회복 탄력성 검증 |
| `backend/internal/service/keto_service_test.go:34` | `TestKetoService_CreateRelation` | 권한/관계 모델 검증 |
| `backend/internal/service/keto_service_test.go:58` | `TestKetoService_DeleteRelation` | 권한/관계 모델 검증 |
| `backend/internal/service/keto_service_test.go:79` | `TestKetoService_ListRelations` | 권한/관계 모델 검증 |
| `backend/internal/service/ory_service_test.go:125` | `TestFindIdentityID_QueryEncoding` | 회귀 방지 기본 동작 검증 |
| `backend/internal/service/ory_service_test.go:38` | `TestUpdateUserPassword_Success` | 인증/OIDC 플로우 검증 |
| `backend/internal/service/ory_service_test.go:78` | `TestUpdateUserPassword_NotFound` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/ory_service_test.go:98` | `TestUpdateUserPassword_ServerError` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/relying_party_service_test.go:133` | `TestRelyingPartyService_Create_HydraFail` | Hydra/RP 연동 검증 |
| `backend/internal/service/relying_party_service_test.go:152` | `TestRelyingPartyService_Create_KetoFail_Rollback` | 복구/격리/회복 탄력성 검증 |
| `backend/internal/service/relying_party_service_test.go:190` | `TestRelyingPartyService_Get_Success` | Hydra/RP 연동 검증 |
| `backend/internal/service/relying_party_service_test.go:221` | `TestRelyingPartyService_Update_Success` | Hydra/RP 연동 검증 |
| `backend/internal/service/relying_party_service_test.go:250` | `TestRelyingPartyService_Delete_Success` | Hydra/RP 연동 검증 |
| `backend/internal/service/relying_party_service_test.go:85` | `TestRelyingPartyService_Create_Success` | Hydra/RP 연동 검증 |
| `backend/internal/service/tenant_service_test.go:126` | `TestTenantService_RegisterTenant_AddsDomainsAsVerified` | 핵심 CRUD/서비스 동작 검증 |
| `backend/internal/service/tenant_service_test.go:156` | `TestTenantService_RequestRegistration_AddsDomainAsUnverified` | 핵심 CRUD/서비스 동작 검증 |
| `backend/internal/service/tenant_service_test.go:187` | `TestTenantService_RequestRegistration_RejectsDomainMismatch` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/tenant_service_test.go:208` | `TestTenantService_ApproveTenant_AssignsAdminRelationWhenUserExists` | 권한/관계 모델 검증 |
| `backend/internal/service/tenant_service_test.go:240` | `TestTenantService_ApproveTenant_DoesNotAssignWhenUserMissing` | 오류/예외/거부 경로 검증 |
| `backend/internal/service/user_group_service_test.go:103` | `TestUserGroupService_Create` | 권한/관계 모델 검증 |
| `backend/internal/service/user_group_service_test.go:124` | `TestUserGroupService_AddMember` | 권한/관계 모델 검증 |
| `backend/internal/service/user_group_service_test.go:138` | `TestUserGroupService_AssignRoleToTenant` | 권한/관계 모델 검증 |
| `backend/internal/service/user_group_service_test.go:154` | `TestUserGroupService_ListRoles` | 권한/관계 모델 검증 |
| `backend/internal/service/user_group_service_test.go:188` | `TestUserGroupService_Get_WithKratosFallback` | 복구/격리/회복 탄력성 검증 |
| `backend/internal/utils/masking_test.go:9` | `TestMaskSensitiveJSON` | 유효성/정책/유틸 검증 |
| `backend/internal/utils/slug_test.go:15` | `TestValidateSlug_ReservedKeywords` | 유효성/정책/유틸 검증 |
| `backend/internal/utils/slug_test.go:38` | `TestValidateSlug_LengthRules` | 유효성/정책/유틸 검증 |
| `backend/internal/utils/slug_test.go:60` | `TestValidateSlug_FormatRules` | 유효성/정책/유틸 검증 |
| `backend/internal/utils/slug_test.go:8` | `TestValidateSlug_Valid` | 유효성/정책/유틸 검증 |
| `backend/internal/validator/schema_validator_test.go:65` | `TestValidateIDPCompatibility` | 유효성/정책/유틸 검증 |

54
docs/test-plan/userfront-test-inventory.md Normal file
View File

@@ -0,0 +1,54 @@
# UserFront 테스트 전수 목록
- 범위: `userfront/test/*.dart`
- 기준: `test(...)`, `testWidgets(...)` 케이스 전수
| 파일 | 테스트 | 역할 |
|---|---|---|
| `userfront/test/dashboard_providers_test.dart` | `AuthTimelineNotifier는 다음 커서를 사용해 추가 로드한다` | 대시보드 타임라인 상태관리 검증 |
| `userfront/test/dashboard_providers_test.dart` | `AuthTimelineNotifier는 실패 시 오류 메시지를 보관한다` | 대시보드 타임라인 상태관리 검증 |
| `userfront/test/dashboard_providers_test.dart` | `AuthTimelineNotifier는 초기 페이지를 로드한다` | 대시보드 타임라인 상태관리 검증 |
| `userfront/test/dashboard_providers_test.dart` | `AuthTimelineNotifier는 커서가 없으면 추가 로드를 하지 않는다` | 대시보드 타임라인 상태관리 검증 |
| `userfront/test/error_screen_test.dart` | `개발환경은 원문 메시지를 노출한다` | 에러 노출 정책 검증 |
| `userfront/test/error_screen_test.dart` | `프로덕션은 ORY 코드를 bypass 처리한다` | 핵심 동작 회귀 방지 검증 |
| `userfront/test/error_screen_test.dart` | `프로덕션은 whitelist 메시지를 노출한다` | 에러 노출 정책 검증 |
| `userfront/test/error_screen_test.dart` | `프로덕션은 비허용 에러를 unknown_error로 처리한다` | 에러 노출 정책 검증 |
| `userfront/test/locale_registry_test.dart` | `extractSupportedLocaleCodesFromAssets excludes template and invalid` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_registry_test.dart` | `fallback locale prefers en when available` | fallback/복구 경로 검증 |
| `userfront/test/locale_registry_test.dart` | `fallback locale uses first sorted code when en is absent` | fallback/복구 경로 검증 |
| `userfront/test/locale_storage_platform_test.dart` | `legacy key에서 locale로 마이그레이션 (웹)` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_storage_platform_test.dart` | `localStorage write/read (웹)` | 브라우저 스토리지 저장/복원 정책 검증 |
| `userfront/test/locale_storage_platform_test.dart` | `localStorage 접근이 차단되면 sessionStorage로 fallback (웹)` | fallback/복구 경로 검증 |
| `userfront/test/locale_storage_platform_test.dart` | `localStorage 접근이 차단되면 메모리 fallback (웹)` | fallback/복구 경로 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath applies locale` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath keeps unknown 2-letter prefix as path` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath preserves fragment` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath preserves query parameters` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath preserves raw query order and duplicates` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath preserves redirect_url parameter` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildLocalizedPath replaces existing locale` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildSigninRedirectPath keeps path without query` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildSigninRedirectPath preserves full raw query` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `buildSigninRedirectPath preserves redirect_url and redirect_uri` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `extractLocaleFromPath picks locale when present` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `extractLocaleFromPath returns null when missing` | fallback/복구 경로 검증 |
| `userfront/test/locale_utils_test.dart` | `normalizeLocaleCode falls back to default` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `normalizeLocaleCode handles supported locales` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `stripLocalePath keeps path without locale` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/locale_utils_test.dart` | `stripLocalePath removes locale segment` | i18n 로케일 해석/정규화 규칙 검증 |
| `userfront/test/login_challenge_resolver_test.dart` | `URI query가 비어 있으면 raw search에서 복구` | fallback/복구 경로 검증 |
| `userfront/test/login_challenge_resolver_test.dart` | `raw search도 비어 있으면 raw href에서 복구` | fallback/복구 경로 검증 |
| `userfront/test/login_challenge_resolver_test.dart` | `widget 값이 없으면 URI query에서 복구` | fallback/복구 경로 검증 |
| `userfront/test/login_challenge_resolver_test.dart` | `widget 값이 있으면 최우선으로 사용` | 핵심 동작 회귀 방지 검증 |
| `userfront/test/login_challenge_resolver_test.dart` | `값이 전부 없으면 missing` | fallback/복구 경로 검증 |
| `userfront/test/oidc_redirect_guard_test.dart` | `http/https 절대 URL만 허용` | 핵심 동작 회귀 방지 검증 |
| `userfront/test/oidc_redirect_guard_test.dart` | `빈 문자열과 파싱 실패를 차단` | 핵심 동작 회귀 방지 검증 |
| `userfront/test/password_login_flow_policy_test.dart` | `OIDC challenge가 없고 jwt가 있으면 로컬 로그인 완료로 진행한다` | 로그인 분기/라우팅 규칙 검증 |
| `userfront/test/password_login_flow_policy_test.dart` | `OIDC challenge가 있고 redirectTo가 없으면 accept를 시도한다` | 로그인 분기/라우팅 규칙 검증 |
| `userfront/test/password_login_flow_policy_test.dart` | `redirectTo/jwt 모두 없으면 invalid로 처리한다` | 로그인 분기/라우팅 규칙 검증 |
| `userfront/test/password_login_flow_policy_test.dart` | `redirectTo가 있으면 OIDC redirect를 우선한다` | 로그인 분기/라우팅 규칙 검증 |
| `userfront/test/router_redirect_widget_test.dart` | `/login: login_challenge와 redirect_uri를 전달` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/router_redirect_widget_test.dart` | `로그인 상태: profile 접근 시 signin으로 리다이렉트하지 않음` | 로그인 분기/라우팅 규칙 검증 |
| `userfront/test/router_redirect_widget_test.dart` | `비로그인: redirect_uri/login_challenge가 signin으로 전달` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/router_redirect_widget_test.dart` | `비로그인: redirect_uri가 없으면 redirect_url을 전달` | 리다이렉트/쿼리 보존 규칙 검증 |
| `userfront/test/widget_test.dart` | `BaronSSOApp builds` | 기본 앱 렌더링 스모크 검증 |

11
docs/test-plan/web-e2e-test-inventory.md Normal file
View File

@@ -0,0 +1,11 @@
# AdminFront/DevFront E2E 테스트 전수 목록
- 범위: `adminfront/tests/*.spec.ts`, `devfront/tests/*.spec.ts`
- 기준: Playwright `test(...)` 케이스 전수
| 파일 | 테스트 | 역할 |
|---|---|---|
| `adminfront/tests/example.spec.ts:3` | `has title` | 초기 페이지 렌더링 스모크 검증 |
| `adminfront/tests/user-management.spec.ts:26` | `user create and delete flow` | 관리자 사용자 생성/삭제 E2E 검증 |
| `devfront/tests/clients.spec.ts:3` | `clients page loads correctly` | DevFront 클라이언트 페이지 접근 스모크 검증 |
| `devfront/tests/example.spec.ts:3` | `has title` | 초기 페이지 렌더링 스모크 검증 |

92
docs/trouble-shooting/issue-281-locale-storage-refactor-plan.md Normal file
View File

@@ -0,0 +1,92 @@
# 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 동작이 유지됩니다.
- 웹 테스트가 안정적으로 통과하며 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 --platform chrome test/locale_storage_platform_test.dart`
### 검증 결과
- `cd userfront && flutter analyze --no-fatal-warnings --no-fatal-infos` 통과
- `cd userfront && flutter test` 통과
- `cd userfront && CHROME_EXECUTABLE=<browser> flutter test --platform chrome test/locale_storage_platform_test.dart` 통과

56
userfront/lib/core/i18n/locale_storage.dart
View File

@@ -1,11 +1,59 @@
import 'package:flutter/foundation.dart';
import 'locale_storage_backend.dart';
import 'locale_storage_stub.dart'
if (dart.library.js_interop) 'locale_storage_web.dart';
abstract class LocaleStorage {
static bool _forceMemory = false;
static bool _forceSession = false;
static void _syncTestMode() {
if (_forceMemory) {
localeStorage.setTestMode(LocaleStorageTestMode.memoryOnly);
return;
}
if (_forceSession) {
localeStorage.setTestMode(LocaleStorageTestMode.sessionOnly);
return;
}
localeStorage.setTestMode(LocaleStorageTestMode.normal);
}
static String? read() => localeStorage.read();
static void write(String locale) => localeStorage.write(locale);
static void forceMemoryStorageForTests(bool value) =>
localeStorage.forceMemoryStorageForTests(value);
static void forceSessionStorageForTests(bool value) =>
localeStorage.forceSessionStorageForTests(value);
@visibleForTesting
static void setTestModeForTests(LocaleStorageTestMode mode) {
_forceMemory = mode == LocaleStorageTestMode.memoryOnly;
_forceSession = mode == LocaleStorageTestMode.sessionOnly;
_syncTestMode();
}
@visibleForTesting
static void clearForTests() {
localeStorage.clearForTests();
_forceMemory = false;
_forceSession = false;
}
@visibleForTesting
static void seedLegacyForTests(String locale) {
localeStorage.seedLegacyForTests(locale);
}
@visibleForTesting
static LocaleStorageDebugState debugStateForTests() {
return localeStorage.debugStateForTests();
}
static void forceMemoryStorageForTests(bool value) {
_forceMemory = value;
_syncTestMode();
}
static void forceSessionStorageForTests(bool value) {
_forceSession = value;
_syncTestMode();
}
}

38
userfront/lib/core/i18n/locale_storage_backend.dart Normal file
View File

@@ -0,0 +1,38 @@
import 'package:flutter/foundation.dart';
enum LocaleStorageTestMode { normal, sessionOnly, memoryOnly }
@immutable
class LocaleStorageDebugState {
const LocaleStorageDebugState({
required this.mode,
this.localCurrent,
this.localLegacy,
this.sessionCurrent,
this.sessionLegacy,
this.memoryCurrent,
this.memoryLegacy,
});
final LocaleStorageTestMode mode;
final String? localCurrent;
final String? localLegacy;
final String? sessionCurrent;
final String? sessionLegacy;
final String? memoryCurrent;
final String? memoryLegacy;
}
abstract interface class LocaleStorageBackend {
String? read();
void write(String locale);
void setTestMode(LocaleStorageTestMode mode);
void clearForTests();
void seedLegacyForTests(String locale);
LocaleStorageDebugState debugStateForTests();
}

13
userfront/lib/core/i18n/locale_storage_policy.dart Normal file
View File

@@ -0,0 +1,13 @@
class LocaleStoragePolicy {
static const currentKey = 'locale';
static const legacyKey = 'baron_locale';
static bool hasValue(String? value) => value != null && value.isNotEmpty;
static bool shouldMigrateLegacy({
required String? current,
required String? legacy,
}) {
return !hasValue(current) && hasValue(legacy);
}
}

58
userfront/lib/core/i18n/locale_storage_stub.dart
View File

@@ -1,19 +1,59 @@
class LocaleStorageImpl {
String? _locale;
import 'locale_storage_backend.dart';
import 'locale_storage_policy.dart';
String? read() => _locale;
class LocaleStorageImpl implements LocaleStorageBackend {
final Map<String, String> _memory = {};
LocaleStorageTestMode _mode = LocaleStorageTestMode.normal;
@override
String? read() {
final current = _memory[LocaleStoragePolicy.currentKey];
if (LocaleStoragePolicy.hasValue(current)) {
return current;
}
final legacy = _memory[LocaleStoragePolicy.legacyKey];
if (LocaleStoragePolicy.shouldMigrateLegacy(
current: current,
legacy: legacy,
)) {
_memory[LocaleStoragePolicy.currentKey] = legacy!;
_memory.remove(LocaleStoragePolicy.legacyKey);
return legacy;
}
return null;
}
@override
void write(String locale) {
_locale = locale;
_memory[LocaleStoragePolicy.currentKey] = locale;
}
void forceMemoryStorageForTests(bool value) {
// Stub
@override
void setTestMode(LocaleStorageTestMode mode) {
_mode = mode;
}
void forceSessionStorageForTests(bool value) {
// Stub
@override
void clearForTests() {
_memory.clear();
_mode = LocaleStorageTestMode.normal;
}
@override
void seedLegacyForTests(String locale) {
_memory[LocaleStoragePolicy.legacyKey] = locale;
}
@override
LocaleStorageDebugState debugStateForTests() {
return LocaleStorageDebugState(
mode: _mode,
memoryCurrent: _memory[LocaleStoragePolicy.currentKey],
memoryLegacy: _memory[LocaleStoragePolicy.legacyKey],
);
}
}
final localeStorage = LocaleStorageImpl();
final LocaleStorageBackend localeStorage = LocaleStorageImpl();

246
userfront/lib/core/i18n/locale_storage_web.dart
View File

@@ -1,120 +1,200 @@
// ignore_for_file: avoid_web_libraries_in_flutter
import 'package:web/web.dart' as web;
import 'package:flutter/foundation.dart';
class LocaleStorageImpl {
static const _key = 'locale';
static const _legacyKey = 'baron_locale';
import 'locale_storage_backend.dart';
import 'locale_storage_policy.dart';
enum _StorageTarget { local, session, memory }
class LocaleStorageImpl implements LocaleStorageBackend {
static final Map<String, String> _memory = {};
static bool _forceMemory = false;
static bool _forceSession = false;
static LocaleStorageTestMode _mode = LocaleStorageTestMode.normal;
@visibleForTesting
void forceMemoryStorageForTests(bool value) {
_forceMemory = value;
if (!value) {
_memory.clear();
List<_StorageTarget> _fallbackTargets() {
switch (_mode) {
case LocaleStorageTestMode.normal:
return [
_StorageTarget.local,
_StorageTarget.session,
_StorageTarget.memory,
];
case LocaleStorageTestMode.sessionOnly:
return [_StorageTarget.session, _StorageTarget.memory];
case LocaleStorageTestMode.memoryOnly:
return [_StorageTarget.memory];
}
}
@visibleForTesting
void forceSessionStorageForTests(bool value) {
_forceSession = value;
String? _safeReadLocal(String key) {
try {
return web.window.localStorage.getItem(key);
} catch (_) {
return null;
}
}
String? _read(String key) {
if (!_forceMemory && !_forceSession) {
try {
return web.window.localStorage.getItem(key);
} catch (_) {
// localStorage 접근이 차단된 경우 sessionStorage로 fallback.
try {
return web.window.sessionStorage.getItem(key);
} catch (_) {
// sessionStorage도 차단된 경우 메모리 fallback 사용.
}
}
String? _safeReadSession(String key) {
try {
return web.window.sessionStorage.getItem(key);
} catch (_) {
return null;
}
if (!_forceMemory) {
try {
return web.window.sessionStorage.getItem(key);
} catch (_) {
// sessionStorage도 차단된 경우 메모리 fallback 사용.
}
}
return _memory[key];
}
void _write(String key, String value) {
if (!_forceMemory && !_forceSession) {
try {
web.window.localStorage.setItem(key, value);
return;
} catch (_) {
// localStorage 접근이 차단된 경우 sessionStorage로 fallback.
try {
web.window.sessionStorage.setItem(key, value);
return;
} catch (_) {
// sessionStorage도 차단된 경우 메모리 fallback 사용.
}
}
bool _safeWriteLocal(String key, String value) {
try {
web.window.localStorage.setItem(key, value);
return true;
} catch (_) {
return false;
}
if (!_forceMemory) {
try {
web.window.sessionStorage.setItem(key, value);
return;
} catch (_) {
// sessionStorage도 차단된 경우 메모리 fallback 사용.
}
}
_memory[key] = value;
}
void _remove(String key) {
if (!_forceMemory && !_forceSession) {
try {
web.window.localStorage.removeItem(key);
return;
} catch (_) {
// localStorage 접근이 차단된 경우 sessionStorage로 fallback.
try {
web.window.sessionStorage.removeItem(key);
return;
} catch (_) {
// sessionStorage도 차단된 경우 메모리 fallback 사용.
}
bool _safeWriteSession(String key, String value) {
try {
web.window.sessionStorage.setItem(key, value);
return true;
} catch (_) {
return false;
}
}
bool _safeRemoveLocal(String key) {
try {
web.window.localStorage.removeItem(key);
return true;
} catch (_) {
return false;
}
}
bool _safeRemoveSession(String key) {
try {
web.window.sessionStorage.removeItem(key);
return true;
} catch (_) {
return false;
}
}
void _safeClearLocal() {
try {
web.window.localStorage.clear();
} catch (_) {
// 스토리지 접근이 차단된 경우는 테스트 정리에서 무시합니다.
}
}
void _safeClearSession() {
try {
web.window.sessionStorage.clear();
} catch (_) {
// 스토리지 접근이 차단된 경우는 테스트 정리에서 무시합니다.
}
}
String? _readFromTarget(_StorageTarget target, String key) {
switch (target) {
case _StorageTarget.local:
return _safeReadLocal(key);
case _StorageTarget.session:
return _safeReadSession(key);
case _StorageTarget.memory:
return _memory[key];
}
}
bool _writeToTarget(_StorageTarget target, String key, String value) {
switch (target) {
case _StorageTarget.local:
return _safeWriteLocal(key, value);
case _StorageTarget.session:
return _safeWriteSession(key, value);
case _StorageTarget.memory:
_memory[key] = value;
return true;
}
}
String? _readByKey(String key) {
for (final target in _fallbackTargets()) {
final value = _readFromTarget(target, key);
if (value != null) {
return value;
}
}
if (!_forceMemory) {
try {
web.window.sessionStorage.removeItem(key);
return null;
}
void _writeByKey(String key, String value) {
for (final target in _fallbackTargets()) {
if (_writeToTarget(target, key, value)) {
return;
} catch (_) {
// sessionStorage도 차단된 경우 메모리 fallback 사용.
}
}
}
void _removeEverywhere(String key) {
_safeRemoveLocal(key);
_safeRemoveSession(key);
_memory.remove(key);
}
@override
String? read() {
final current = _read(_key);
if (current != null && current.isNotEmpty) {
final current = _readByKey(LocaleStoragePolicy.currentKey);
if (LocaleStoragePolicy.hasValue(current)) {
return current;
}
final legacy = _read(_legacyKey);
if (legacy != null && legacy.isNotEmpty) {
_write(_key, legacy);
_remove(_legacyKey);
final legacy = _readByKey(LocaleStoragePolicy.legacyKey);
if (LocaleStoragePolicy.shouldMigrateLegacy(
current: current,
legacy: legacy,
)) {
_writeByKey(LocaleStoragePolicy.currentKey, legacy!);
_removeEverywhere(LocaleStoragePolicy.legacyKey);
return legacy;
}
return null;
}
@override
void write(String locale) {
_write(_key, locale);
_writeByKey(LocaleStoragePolicy.currentKey, locale);
}
@override
void setTestMode(LocaleStorageTestMode mode) {
_mode = mode;
}
@override
void clearForTests() {
_safeClearLocal();
_safeClearSession();
_memory.clear();
_mode = LocaleStorageTestMode.normal;
}
@override
void seedLegacyForTests(String locale) {
_writeByKey(LocaleStoragePolicy.legacyKey, locale);
}
@override
LocaleStorageDebugState debugStateForTests() {
return LocaleStorageDebugState(
mode: _mode,
localCurrent: _safeReadLocal(LocaleStoragePolicy.currentKey),
localLegacy: _safeReadLocal(LocaleStoragePolicy.legacyKey),
sessionCurrent: _safeReadSession(LocaleStoragePolicy.currentKey),
sessionLegacy: _safeReadSession(LocaleStoragePolicy.legacyKey),
memoryCurrent: _memory[LocaleStoragePolicy.currentKey],
memoryLegacy: _memory[LocaleStoragePolicy.legacyKey],
);
}
}
final localeStorage = LocaleStorageImpl();
final LocaleStorageBackend localeStorage = LocaleStorageImpl();

5
userfront/test/helpers/web_storage.dart
View File

@@ -1,5 +0,0 @@
import 'web_storage_stub.dart'
if (dart.library.html) 'web_storage_web.dart';
export 'web_storage_stub.dart'
if (dart.library.html) 'web_storage_web.dart';

21
userfront/test/helpers/web_storage_stub.dart
View File

@@ -1,21 +0,0 @@
class WebStorage {
bool get isWeb => false;
String? get(String key) => null;
void set(String key, String value) {}
String? getSession(String key) => null;
void setSession(String key, String value) {}
void removeSession(String key) {}
void clearSession() {}
void remove(String key) {}
void clear() {}
}
final webStorage = WebStorage();

37
userfront/test/helpers/web_storage_web.dart
View File

@@ -1,37 +0,0 @@
// ignore_for_file: avoid_web_libraries_in_flutter
import 'package:web/web.dart' as web;
class WebStorage {
bool get isWeb => true;
String? get(String key) => web.window.localStorage.getItem(key);
void set(String key, String value) {
web.window.localStorage.setItem(key, value);
}
String? getSession(String key) => web.window.sessionStorage.getItem(key);
void setSession(String key, String value) {
web.window.sessionStorage.setItem(key, value);
}
void removeSession(String key) {
web.window.sessionStorage.removeItem(key);
}
void clearSession() {
web.window.sessionStorage.clear();
}
void remove(String key) {
web.window.localStorage.removeItem(key);
}
void clear() {
web.window.localStorage.clear();
}
}
final webStorage = WebStorage();

122
userfront/test/locale_storage_platform_test.dart
View File

@@ -1,87 +1,75 @@
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:userfront/core/i18n/locale_storage.dart';
import 'helpers/web_storage.dart';
import 'package:userfront/core/i18n/locale_storage_backend.dart';
void main() {
setUp(() {
LocaleStorage.forceMemoryStorageForTests(false);
LocaleStorage.forceSessionStorageForTests(false);
if (webStorage.isWeb) {
webStorage.clear();
webStorage.clearSession();
}
LocaleStorage.setTestModeForTests(LocaleStorageTestMode.normal);
LocaleStorage.clearForTests();
});
tearDown(() {
LocaleStorage.forceMemoryStorageForTests(false);
LocaleStorage.forceSessionStorageForTests(false);
if (webStorage.isWeb) {
webStorage.clear();
webStorage.clearSession();
}
LocaleStorage.setTestModeForTests(LocaleStorageTestMode.normal);
LocaleStorage.clearForTests();
});
test(
'localStorage write/read (웹)',
() {
if (!webStorage.isWeb) {
return;
}
test('localStorage write/read (웹)', () {
if (!kIsWeb) {
return;
}
LocaleStorage.write('ko');
expect(webStorage.get('locale'), 'ko');
expect(LocaleStorage.read(), 'ko');
},
skip: !webStorage.isWeb,
);
LocaleStorage.write('ko');
expect(LocaleStorage.read(), 'ko');
test(
'legacy key에서 locale로 마이그레이션 (웹)',
() {
if (!webStorage.isWeb) {
return;
}
final state = LocaleStorage.debugStateForTests();
expect(state.localCurrent, 'ko');
expect(state.sessionCurrent, isNull);
expect(state.memoryCurrent, isNull);
}, skip: !kIsWeb);
webStorage.set('baron_locale', 'en');
expect(LocaleStorage.read(), 'en');
expect(webStorage.get('locale'), 'en');
expect(webStorage.get('baron_locale'), isNull);
},
skip: !webStorage.isWeb,
);
test('legacy key에서 locale로 마이그레이션 (웹)', () {
if (!kIsWeb) {
return;
}
test(
'localStorage 접근이 차단되면 메모리 fallback (웹)',
() {
if (!webStorage.isWeb) {
return;
}
LocaleStorage.seedLegacyForTests('en');
expect(LocaleStorage.read(), 'en');
LocaleStorage.forceMemoryStorageForTests(true);
final state = LocaleStorage.debugStateForTests();
expect(state.localCurrent, 'en');
expect(state.localLegacy, isNull);
}, skip: !kIsWeb);
LocaleStorage.write('en');
expect(webStorage.get('locale'), isNull);
expect(webStorage.getSession('locale'), isNull);
expect(LocaleStorage.read(), 'en');
},
skip: !webStorage.isWeb,
);
test('localStorage 접근이 차단되면 메모리 fallback (웹)', () {
if (!kIsWeb) {
return;
}
test(
'localStorage 접근이 차단되면 sessionStorage로 fallback (웹)',
() {
if (!webStorage.isWeb) {
return;
}
LocaleStorage.forceMemoryStorageForTests(true);
LocaleStorage.forceSessionStorageForTests(true);
LocaleStorage.write('en');
expect(LocaleStorage.read(), 'en');
LocaleStorage.write('ko');
expect(webStorage.get('locale'), isNull);
expect(webStorage.getSession('locale'), 'ko');
expect(LocaleStorage.read(), 'ko');
},
skip: !webStorage.isWeb,
);
final state = LocaleStorage.debugStateForTests();
expect(state.localCurrent, isNull);
expect(state.sessionCurrent, isNull);
expect(state.memoryCurrent, 'en');
}, skip: !kIsWeb);
test('localStorage 접근이 차단되면 sessionStorage로 fallback (웹)', () {
if (!kIsWeb) {
return;
}
LocaleStorage.forceSessionStorageForTests(true);
LocaleStorage.write('ko');
expect(LocaleStorage.read(), 'ko');
final state = LocaleStorage.debugStateForTests();
expect(state.localCurrent, isNull);
expect(state.sessionCurrent, 'ko');
expect(state.memoryCurrent, isNull);
}, skip: !kIsWeb);
}