71 lines
4.2 KiB
Markdown
71 lines
4.2 KiB
Markdown
# 데이터 정합성 검증 관리
|
|
|
|
## 개요
|
|
|
|
adminfront의 `데이터 정합성` 메뉴는 Baron SSO backend DB read model의 이상 징후를 `super_admin` 전용으로 확인하는 관리 화면입니다.
|
|
|
|
Baron SSO의 신원/권한 SoT는 Ory Stack(Kratos, Keto, Hydra)입니다. 이 기능은 SoT를 직접 수정하지 않고, backend PostgreSQL read model에서 운영자가 확인해야 할 불일치만 리포트합니다.
|
|
|
|
## API
|
|
|
|
- Method: `GET`
|
|
- Path: `/api/v1/admin/integrity`
|
|
- 권한: `super_admin`
|
|
|
|
응답은 전체 상태, 검사 시각, 요약, 섹션별 검사 결과를 포함합니다.
|
|
|
|
### 유령 로그인 ID 대상 조회
|
|
|
|
- Method: `GET`
|
|
- Path: `/api/v1/admin/integrity/orphan-user-login-ids`
|
|
- 권한: `super_admin`
|
|
|
|
`user_login_ids`가 존재하지 않거나 soft-deleted 된 `users`, `tenants`를 참조하는 행을 반환합니다. 각 행은 `loginId`, `fieldKey`, 사용자/테넌트 식별 정보, `missing_user`, `deleted_user`, `missing_tenant`, `deleted_tenant` 중 하나 이상의 사유를 포함합니다.
|
|
|
|
### 유령 로그인 ID 삭제
|
|
|
|
- Method: `DELETE`
|
|
- Path: `/api/v1/admin/integrity/orphan-user-login-ids`
|
|
- 권한: `super_admin`
|
|
|
|
요청 본문은 `{ "ids": ["..."] }` 형식입니다. 서버는 삭제 직전에 같은 트랜잭션 안에서 대상 행이 여전히 유령 로그인 ID인지 재검증하고, 재검증을 통과한 `user_login_ids` 행만 삭제합니다. 정상화되었거나 존재하지 않는 ID는 `skippedIds`로 반환합니다.
|
|
|
|
## 검사 항목
|
|
|
|
### 테넌트 정합성
|
|
|
|
- `duplicate_tenant_slugs`: 삭제되지 않은 tenant의 `LOWER(TRIM(slug))` 기준 중복을 검사합니다.
|
|
- `orphan_tenant_parents`: `tenants.parent_id`가 존재하지 않거나 soft-deleted tenant를 참조하는지 검사합니다.
|
|
|
|
### 사용자 정합성
|
|
|
|
- `orphan_user_tenant_memberships`: `users.tenant_id`가 존재하지 않거나 soft-deleted tenant를 참조하는지 검사합니다.
|
|
- `orphan_user_login_id_tenants`: `user_login_ids.tenant_id`가 존재하지 않거나 soft-deleted tenant를 참조하는지 검사합니다.
|
|
- `orphan_user_login_id_users`: `user_login_ids.user_id`가 존재하지 않거나 soft-deleted user를 참조하는지 검사합니다.
|
|
|
|
## adminfront 동작
|
|
|
|
- `super_admin`은 사이드바의 `데이터 정합성` 메뉴에서 리포트를 볼 수 있습니다.
|
|
- `다시 검사` 실행 중에는 버튼이 비활성화되고 `검사 중` 상태가 표시됩니다. 요청이 끝나면 완료 또는 실패 상태 문구가 화면에 남습니다.
|
|
- `super_admin`은 같은 메뉴에서 유령 로그인 ID 대상을 확인하고, 체크박스로 선택한 뒤 확인 대화상자를 거쳐 삭제할 수 있습니다.
|
|
- `super_admin`은 adminfront 개요 화면 하단에서도 최종 검증 상태, 실패 건수, 검사 시각, 섹션별 상태 요약을 볼 수 있습니다.
|
|
- `tenant_admin` 등 non-super role은 화면 접근 시 권한 없음 메시지만 봅니다.
|
|
- 개요 화면의 전체 테넌트 수는 `fetchAllTenants()`로 실제 cursor pagination을 끝까지 수집한 리스트 수를 우선 사용합니다. 이로써 super가 보는 전체 테넌트 수와 리스트 기반 수치가 같은 소스에서 나오도록 맞춥니다.
|
|
- 개요 화면은 `super_admin`에게 전체 사용자 수(`totalUsers`)도 표시합니다. 이 값은 Kratos user projection 상태의 `projectedUsers` 기준입니다.
|
|
|
|
## 운영 주의
|
|
|
|
정합성 검증 리포트는 read-only입니다. 단, 유령 로그인 ID 삭제는 `super_admin`이 대상 행을 확인하고 선택한 경우에만 수행되는 명시적 maintenance action입니다.
|
|
|
|
삭제 작업의 기본 운영 순서는 다음과 같습니다.
|
|
|
|
1. `데이터 정합성` 메뉴에서 실패 항목과 유령 로그인 ID 대상 행을 확인합니다.
|
|
2. 사용자/테넌트가 실제로 복구 대상인지 먼저 판단합니다.
|
|
3. 복구 대상이 아니라 read model 잔여 데이터가 맞는 행만 선택합니다.
|
|
4. `선택 삭제` 실행 후 정합성 리포트가 다시 조회되어 실패 건수가 줄었는지 확인합니다.
|
|
|
|
이미 존재하는 orphan 사용자 소속 정리 경로는 다음과 같습니다.
|
|
|
|
- CLI: `backend/cmd/adminctl clear-orphan-user-tenant-memberships`
|
|
- SQL: `scripts/clear_orphan_user_tenant_memberships.sql`
|