# Auth DB Design

## Goal

현재 조직도 업무 데이터와 로그인 데이터를 분리한다.

분리 원칙:
- 업무 데이터는 기존 `public.members`, `seat_maps`, `seat_positions` 중심으로 유지
- 인증/권한 데이터는 별도 `auth` 스키마로 분리
- 로그인 사용자는 필요할 때만 `members.id` 와 연결

이 방식이면 비밀번호, 세션, 감사로그를 업무 데이터와 분리해서 관리할 수 있고,
엑셀 임포트로 `members` 가 갱신돼도 인증 체계가 직접 흔들리지 않는다.

## Scope

이번 설계의 대상:
- 사용자 계정
- 비밀번호 해시
- 세션
- 역할과 권한
- 로그인 감사로그
- 사용자와 조직 구성원 연결

이번 설계에서 제외:
- SSO 연동
- OAuth/OpenID Connect
- MFA
- 비밀번호 재설정 메일 발송

## Recommended Structure

권장 구조는 "같은 PostgreSQL, 다른 스키마" 이다.

- 업무 스키마: `public`
- 인증 스키마: `auth`

초기 운영에서는 DB 인스턴스를 분리하지 않아도 된다.
대신 아래 원칙은 바로 적용한다.

- 애플리케이션 계정도 가능하면 읽기/쓰기 범위를 분리
- 인증 관련 쿼리는 `auth.*` 만 접근
- 업무 API 는 `public.*` 중심으로 접근

## Core Tables

### `auth.users`

로그인 가능한 계정의 기준 테이블.

주요 컬럼:
- `id BIGSERIAL PRIMARY KEY`
- `username TEXT NOT NULL UNIQUE`
- `password_hash TEXT NOT NULL`
- `display_name TEXT NOT NULL`
- `email TEXT`
- `status TEXT NOT NULL DEFAULT 'active'`
- `member_id INTEGER NULL REFERENCES public.members(id) ON DELETE SET NULL`
- `last_login_at TIMESTAMPTZ`
- `password_changed_at TIMESTAMPTZ`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
- `updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`

상태값 권장:
- `active`
- `locked`
- `disabled`

원칙:
- `username` 는 로그인 식별자
- `member_id` 는 선택 연결
- 구성원이 퇴사하거나 엑셀에서 빠져도 계정 자체는 바로 삭제하지 않음

### `auth.roles`

권한 묶음 정의.

주요 컬럼:
- `id BIGSERIAL PRIMARY KEY`
- `code TEXT NOT NULL UNIQUE`
- `name TEXT NOT NULL`
- `description TEXT`

초기 권장 역할:
- `super_admin`
- `org_admin`
- `viewer`

### `auth.user_roles`

사용자와 역할의 다대다 연결.

주요 컬럼:
- `user_id BIGINT NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE`
- `role_id BIGINT NOT NULL REFERENCES auth.roles(id) ON DELETE CASCADE`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
- `PRIMARY KEY (user_id, role_id)`

### `auth.permissions`

세분화된 권한 코드 정의.

주요 컬럼:
- `id BIGSERIAL PRIMARY KEY`
- `code TEXT NOT NULL UNIQUE`
- `name TEXT NOT NULL`
- `description TEXT`

초기 권장 권한:
- `member.read`
- `member.write`
- `member.import`
- `seatmap.read`
- `seatmap.write`
- `photo.upload`
- `admin.user.manage`

### `auth.role_permissions`

역할과 권한의 다대다 연결.

주요 컬럼:
- `role_id BIGINT NOT NULL REFERENCES auth.roles(id) ON DELETE CASCADE`
- `permission_id BIGINT NOT NULL REFERENCES auth.permissions(id) ON DELETE CASCADE`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
- `PRIMARY KEY (role_id, permission_id)`

### `auth.sessions`

서버 세션 저장 테이블.

주요 컬럼:
- `id UUID PRIMARY KEY`
- `user_id BIGINT NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE`
- `refresh_token_hash TEXT`
- `issued_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
- `expires_at TIMESTAMPTZ NOT NULL`
- `revoked_at TIMESTAMPTZ`
- `ip_address INET`
- `user_agent TEXT`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`

원칙:
- 브라우저 쿠키에는 세션 식별자만 저장
- 토큰 자체를 평문으로 DB에 저장하지 않음
- 만료와 강제 로그아웃을 DB에서 통제 가능하게 함

### `auth.login_audit_logs`

로그인 시도와 결과 기록.

주요 컬럼:
- `id BIGSERIAL PRIMARY KEY`
- `username TEXT NOT NULL`
- `user_id BIGINT NULL REFERENCES auth.users(id) ON DELETE SET NULL`
- `success BOOLEAN NOT NULL`
- `failure_reason TEXT`
- `ip_address INET`
- `user_agent TEXT`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`

용도:
- 로그인 실패 추적
- 계정 잠금 기준 판단
- 보안 감사 대응

## Relationship To Current `members`

핵심은 `auth.users.member_id -> public.members.id` 연결이다.

의미:
- 로그인 계정과 조직도 인원을 분리한다
- 로그인하지 않는 구성원은 `members` 에만 있어도 된다
- 외부 관리자 계정은 `member_id` 없이 운영할 수 있다

권장 규칙:
- 일반 사내 사용자는 `employee_id` 기준으로 계정-구성원 연결
- 엑셀 동기화 시 `members.id` 유지가 중요하므로 이미 반영한 비교 기반 동기화 방식을 유지
- `member_id` 연결이 끊긴 계정은 자동 삭제하지 말고 관리자 검토 대상으로 둔다

## Login Flow

### 1. 로그인 요청

입력:
- `username`
- `password`

처리:
- `auth.users` 에서 `username` 조회
- `status != active` 이면 거부
- `password_hash` 검증
- 성공 시 `auth.sessions` 생성
- `auth.login_audit_logs` 기록

응답 권장:
- 사용자 기본 정보
- 역할 목록
- 권한 목록
- 세션 만료 시각

### 2. 인증 확인

각 보호 API 요청 시:
- 세션 쿠키 또는 Bearer 토큰 확인
- `auth.sessions` 조회
- 만료/폐기 여부 확인
- 사용자 상태와 역할 재검증

### 3. 로그아웃

처리:
- 현재 세션의 `revoked_at` 업데이트
- 클라이언트 쿠키 제거

## Authorization Model

초기에는 RBAC 기반으로 충분하다.

권장 역할별 범위:

`super_admin`
- 사용자 관리
- 권한 관리
- 조직도/사진/자리배치 전체 수정

`org_admin`
- 조직도 조회/수정
- 엑셀 임포트
- 사진 업로드
- 자리배치 수정

`viewer`
- 조직도 조회
- 자리배치 조회

API 보호 예시:
- `GET /api/members`: `member.read`
- `POST /api/members/import`: `member.import`
- `POST /api/uploads/profile-photo`: `photo.upload`
- `PUT /api/seat-maps/{seat_map_id}/layout`: `seatmap.write`
- 사용자 관리 API: `admin.user.manage`

## Password Policy

비밀번호는 평문 저장 금지.

권장:
- `Argon2id` 우선
- 대안으로 `bcrypt`

추가 원칙:
- 첫 구현부터 해시 알고리즘 버전 정보 포함
- 비밀번호 변경 시 `password_changed_at` 갱신
- 실패 횟수 기반 잠금은 앱 로직 또는 별도 컬럼으로 확장 가능

## Migration Plan

### Phase 1

인증 스키마와 기본 테이블만 추가.

작업:
- `CREATE SCHEMA IF NOT EXISTS auth`
- `auth.users`
- `auth.roles`
- `auth.user_roles`
- `auth.permissions`
- `auth.role_permissions`
- `auth.sessions`
- `auth.login_audit_logs`

이 단계에서는 기존 `/api/mock-login` 유지 가능.

### Phase 2

관리자 1명 이상을 수동 생성하고 실제 로그인 API 추가.

권장 추가 API:
- `POST /api/auth/login`
- `POST /api/auth/logout`
- `GET /api/auth/me`

### Phase 3

기존 프론트엔드의 mock 로그인 제거.

변경 대상:
- [frontend/public/app.js](../frontend/public/app.js)
- [backend/app/main.py](../backend/app/main.py)
- [backend/app/config.py](../backend/app/config.py)

### Phase 4

권한 기반으로 API 보호 적용.

우선순위:
1. 쓰기 API 보호
2. 업로드 API 보호
3. 읽기 API 권한 정리

## Recommended SQL Skeleton

```sql
CREATE SCHEMA IF NOT EXISTS auth;

CREATE TABLE IF NOT EXISTS auth.users (
    id BIGSERIAL PRIMARY KEY,
    username TEXT NOT NULL UNIQUE,
    password_hash TEXT NOT NULL,
    display_name TEXT NOT NULL,
    email TEXT,
    status TEXT NOT NULL DEFAULT 'active',
    member_id INTEGER NULL REFERENCES public.members(id) ON DELETE SET NULL,
    last_login_at TIMESTAMPTZ,
    password_changed_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS auth.roles (
    id BIGSERIAL PRIMARY KEY,
    code TEXT NOT NULL UNIQUE,
    name TEXT NOT NULL,
    description TEXT
);

CREATE TABLE IF NOT EXISTS auth.user_roles (
    user_id BIGINT NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    role_id BIGINT NOT NULL REFERENCES auth.roles(id) ON DELETE CASCADE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    PRIMARY KEY (user_id, role_id)
);

CREATE TABLE IF NOT EXISTS auth.sessions (
    id UUID PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    refresh_token_hash TEXT,
    issued_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    expires_at TIMESTAMPTZ NOT NULL,
    revoked_at TIMESTAMPTZ,
    ip_address INET,
    user_agent TEXT,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

## Operational Notes

- 엑셀 임포트는 계속 `public.members` 기준으로 처리
- 로그인 계정 생성은 엑셀 업로드와 분리
- 프로필 사진은 현재처럼 파일 저장 + `members.photo_url` 참조 유지 가능
- 감사로그와 세션은 삭제보다 보존 기간 정책으로 관리

## Decision

현재 프로젝트의 권장안은 아래 한 줄로 정리된다.

"로그인 DB는 `auth` 스키마로 분리하고, 업무 DB는 `public` 에 유지하며, 두 영역은 `auth.users.member_id` 로만 연결한다."