데이터 정합성 검증 관리

개요

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 identity mirror 상태의 observed user count 기준입니다.

운영 주의

정합성 검증 리포트는 read-only입니다. 단, 유령 로그인 ID 삭제는 super_admin이 대상 행을 확인하고 선택한 경우에만 수행되는 명시적 maintenance action입니다.

삭제 작업의 기본 운영 순서는 다음과 같습니다.

데이터 정합성 메뉴에서 실패 항목과 유령 로그인 ID 대상 행을 확인합니다.
사용자/테넌트가 실제로 복구 대상인지 먼저 판단합니다.
복구 대상이 아니라 read model 잔여 데이터가 맞는 행만 선택합니다.
선택 삭제 실행 후 정합성 리포트가 다시 조회되어 실패 건수가 줄었는지 확인합니다.

이미 존재하는 orphan 사용자 소속 정리 경로는 다음과 같습니다.

CLI: backend/cmd/adminctl clear-orphan-user-tenant-memberships
SQL: scripts/clear_orphan_user_tenant_memberships.sql

4.2 KiB Raw Blame History