baron-sso/docs/employee_id_login_db_design.md

커스텀 필드 기반 로그인 ID 연동 - DB 설계 문서

1. 개요

본 문서는 사용자(User) 정보에 범용 로그인 ID(login_id)를 추가하고, 이를 테넌트별 설정에 따라 커스텀 필드와 동기화하기 위한 데이터베이스(DB) 관점의 설계 변경 사항을 명세합니다.

2. DB 스키마 변경 사항

2.1. 대상 테이블: users

현재 백엔드(PostgreSQL)의 users 테이블에 login_id 컬럼을 추가합니다.

컬럼명	타입	제약 조건	설명
login_id	VARCHAR(255)	NULL 허용	범용 로그인 식별자 (사번, 학번 등)

인덱스(Index) 설정

단순 unique가 아닌, 테넌트 내 고유성을 보장하기 위해 tenant_id와 조합된 복합 유니크 인덱스를 생성합니다.

• 인덱스명: idx_tenant_login_id
• 구성 컬럼: (tenant_id, login_id)
• 효과:
  • 서로 다른 테넌트 간에는 동일한 login_id가 존재할 수 있습니다.
  • 동일 테넌트 내에서는 중복된 login_id를 가질 수 없습니다.

2.2. 대상 테이블: tenants

tenants 테이블의 config (JSONB) 컬럼에 매핑 설정을 추가합니다.

• 설정 키: loginIdField
• 설명: 사용자의 metadata (커스텀 필드) 중 어떤 필드의 값을 login_id로 동기화할지 결정하는 필드 키 이름입니다.
• 예시: "loginIdField": "emp_no"

3. 데이터 흐름 및 동기화

3.1. 사용자 생성/수정 (Sync Flow)

1. 사용자 생성/수정 시 전달된 metadata와 테넌트의 config.loginIdField를 확인합니다.
2. metadata 내에 해당 키의 값이 존재하면, 그 값을 users.login_id 컬럼에 저장합니다.
3. 동시에 Ory Kratos의 traits.id 필드에도 해당 값을 업데이트하여 Kratos를 통한 로그인을 가능하게 합니다.

3.2. 대량 업로드 (Bulk Import)

1. CSV/Excel 파일의 컬럼 중 테넌트에서 지정한 커스텀 필드 컬럼(예: 사번)을 파싱합니다.
2. 위의 동기화 로직과 동일하게 login_id 컬럼과 Kratos Traits를 업데이트합니다.

4. GORM 모델 반영 (Go)

type User struct {
    ID       string  `gorm:"primaryKey;type:uuid"`
    Email    string  `gorm:"uniqueIndex;not null"`
    LoginID  string  `gorm:"column:login_id;uniqueIndex:idx_tenant_login_id"`
    TenantID *string `gorm:"column:tenant_id;type:uuid;uniqueIndex:idx_tenant_login_id"`
    // ... 기타 필드
}