[BE/Auth] 인증 후 동의 이력 API·Agreement Gate

[bottlenote-app]

목적

로그인은 신원 인증만 담당하고, 이용 자격 판정은 인증 이후의 독립된 Gate가 수행하는 구조로 전환한다. 필수 동의 충족 여부는 그 Gate 중 하나(AgreementGate)가 요청 시점에 판정한다.

기존 본문의 signupToken 전용 JWT, signup token 저장소, 가입 완료 후 소셜 로그인 재호출 방식은 폐기한다. 해당 방향의 bottle-note/bottle-note-api-server#689 는 병합 없이 닫혔다.

폐기된 원래 요구사항과 폐기 사유는 이 이슈의 아카이브 코멘트에 보존돼 있다.

아키텍처 원칙

책임을 넷으로 분리하고 서로 침범하지 않는다.

책임	정의	소유
Authentication	너는 누구인가	소셜 로그인 + 기존 JWT (변경 없음)
Evaluation	지금 이용 자격을 충족했는가	Agreement Evaluator (단일 판정 주체)
Enforcement	미충족일 때 무엇을 막는가	인증 이후 Gate 체인
Evidence	무엇을 근거로 판정했는가	append-only 동의 이력

핵심 규칙:

• 판정은 요청 시점에 한다. 토큰 발급 시점에 굳히지 않는다. 이미 발급된 JWT를 가진 사용자도 필수 동의 기준일이 오르면 즉시 게이트에 걸린다.
• 판정 주체는 하나다. 동의 상태 조회 API, 로그인 응답 힌트, 보호 API 차단이 모두 같은 Evaluator 결과를 쓴다.
• 동의 정책을 JWT 인증 필터에 결합하지 않는다. 필터는 신원 확립까지만 책임진다.
• 필수 동의만 차단 조건이다. 선택 동의 미동의는 해당 기능 비활성화로만 반영한다.
• Gate는 독립적이고 추가 가능하다. 다만 이번 범위는 AccountStateGate·AgreementGate 둘뿐이며, 요구가 없는 Gate를 미리 만들지 않는다.

요청 파이프라인

flowchart LR
    A[Social Login] --> B[기존 JWT 발급]
    B --> C[JwtAuthenticationFilter<br/>신원 확립만]
    C --> D[CustomUserContext 로딩]
    D --> E{AccountStateGate<br/>계정 생명주기}
    E -->|DELETED / SUSPENDED| X1[차단]
    E -->|통과| F{AgreementGate<br/>필수 동의}
    F -->|미충족| X2["403 AGREEMENT_REQUIRED<br/>(부족 목록은 조회 API로)"]
    F -->|충족| G[Controller]

Loading

신규 회원도 예외 없이 이 경로를 탄다. 로그인 응답은 단일 스키마이며 분기하지 않는다.

판정 로직 (Agreement Evaluator)

flowchart TD
    CFG[["설정<br/>필수 유형 목록<br/>유형별 기준일"]] --> J{유형별 대조}
    L[(user_agreements)] --> M["사용자 · 유형별<br/>최신 이벤트 1건"]
    M --> J
    J -->|해당 유형 이벤트 없음| W[WAITING_TO_AGREE]
    J -->|최신 이벤트가 REVOKE| W
    J -->|recorded_at &lt; 기준일| W
    J -->|모든 필수 유형 AGREE<br/>+ 기준일 이후| OK[ELIGIBLE]

Loading

-- 유형별 최신 이벤트 1건씩
SELECT agreement_type, action, recorded_at
FROM user_agreements
WHERE user_id = ?
  AND agreement_type IN ('TERMS_OF_SERVICE', 'PRIVACY_COLLECTION_USE')
-- 유형별 최신 1건만 남긴 뒤
-- 전부 action = AGREE 이고 recorded_at >= 유형별 기준일 이면 ELIGIBLE

판정 규칙:

1. 필수 유형 목록과 유형별 기준일은 설정(서버 구성)이 소유한다. 테이블에 두지 않는다. "무엇이 필수인가"는 시점에 따라 바뀌는 정책이고, 테이블은 "무엇에 동의했다"는 사실만 기록한다.
2. 유형별로 비교한다. 이용약관만 교체됐는데 개인정보 동의까지 재동의를 요구하면 안 된다.
3. 최신 이벤트의 action을 먼저 본다. REVOKE면 기준일과 무관하게 미충족.
4. 약관 교체 = 해당 유형의 기준일 상향. 별도 버전 문자열도, 문서 버전 관리 체계도 두지 않는다.
5. 기준일 오입력은 전 사용자 차단으로 이어진다. 설정 변경은 리뷰 대상으로 관리한다.

데이터 모델

테이블 하나만 추가한다. 문서 레지스트리를 별도 테이블로 만들지 않으며, users 테이블은 수정하지 않는다.

user_agreements                          -- append-only. UPDATE / DELETE 금지
  id                bigint        PK
  user_id           bigint        NOT NULL  -- FK -> users.id
  agreement_type    varchar(50)   NOT NULL  -- TERMS_OF_SERVICE | PRIVACY_COLLECTION_USE
  action            varchar(20)   NOT NULL  -- AGREE | REVOKE
  document_content  mediumtext    NOT NULL  -- 동의 시점 문서 원문 스냅샷
  recorded_at       datetime(6)   NOT NULL  -- 서버 기록 시각
  input_context     varchar(20)   NOT NULL  -- INDIVIDUAL | BULK
  client_ip         varchar(45)
  user_agent        varchar(512)

  KEY idx_user_agreements_user_type_recorded (user_id, agreement_type, recorded_at)
  CONSTRAINT fk_user_agreements_user_id FOREIGN KEY (user_id) REFERENCES users (id)

컬럼 근거

컬럼	역할
agreement_type	어느 항목의 동의인가. 판정이 유형별 최신 1건을 뽑으므로 필수. 유형 없이 원문만 있으면 종류를 텍스트에서 추측해야 한다
document_content	무엇에 동의했는가. 동의 시점 원문을 그대로 동결한다. 수집 목적·법적 근거·거부 시 처리·철회 시 처리는 이 원문 안에 포함된다
action	명시적 의사표시
user_id	누가. 계정 자체가 소셜로 검증된 신원이다. 소셜 공급자는 기록하지 않는다 — 한 사용자가 여러 공급자를 연동할 수 있어 하나를 고르면 오히려 왜곡된다. 탈퇴는 소프트 삭제(status = DELETED)라 users 행이 남으므로 조인이 계속 유효하다
input_context	어떻게. 개별 체크인지 전체 동의 한 번인지 구분
recorded_at	언제. 서버 기록 시각 단독. 클라이언트 동의 일자를 받지 않는다
client_ip / user_agent	동의 정황. 게이트웨이가 XFF를 실제 접속 주소로 채우므로 IP는 신뢰 가능하다

append-only

이 테이블은 UPDATE / DELETE 하지 않는다. 철회는 REVOKE 행 추가로 표현하며 기존 AGREE 행을 덮지 않는다.

행을 덮으면 "언제부터 언제까지 동의 상태였는가"가 사라진다. 3월에 동의하고 8월에 철회한 사용자의 행을 REVOKE로 덮으면 그 5개월간 데이터를 처리한 근거가 없어지고, 동의 후 철회한 사용자와 애초에 동의하지 않은 사용자를 구분할 수 없다. document_content도 함께 덮여 어느 원문에 동의했는지 사라진다.

현재 상태가 필요하면 (user_id, agreement_type, recorded_at) 인덱스로 유형별 최신 1건을 조회한다.

타입·인덱스

• document_content는 mediumtext. text(64KB)는 약관 HTML 원문에서 넘칠 수 있고, 저장 시 잘리면 증빙이 깨진다.
• 인덱스는 (user_id, agreement_type, recorded_at). 판정 쿼리가 유형별 최신 1건을 뽑기 때문이며, (user_id, recorded_at)으로는 유형 필터가 인덱스에 걸리지 않는다.

증빙 대응

입증 대상	위치
누가	user_id (계정 자체가 소셜로 검증된 신원)
무엇을	agreement_type, document_content
왜	document_content 원문에 포함 (수집 목적·법적 근거)
어떻게	action, input_context
언제	recorded_at
거부하면	document_content 원문에 포함
철회하면	document_content 원문에 포함

원문을 동결해 저장하므로 "동의 시점에 사용자에게 무엇을 고지했는가"가 행 자체로 입증된다.

users 테이블

• 수정하지 않는다. 판정은 user_agreements만 조회한다.
• users.status는 계정 생명주기 전용을 유지하며 WAITING_TO_AGREE 같은 값을 넣지 않는다. DELETED·SUSPENDED 같은 계정 상태와 정책 충족 상태는 직교하므로 같은 enum에 합치지 않는다.
• 동의 자격은 파생값이므로 컬럼으로 굳히지 않는다. Gate가 요청당 쿼리 1건을 추가하는데, 부담이 확인되면 캐시 컬럼이나 Redis를 나중에 얹을 수 있다. 파생값이라 사후 추가가 가능하므로 미리 하지 않는다.

API 계약

엔드포인트는 2개다. Gate는 엔드포인트가 아니다.

1. 동의 상태 조회

GET /api/v2/agreements/status — 일반 인증 필요, AgreementGate 면제

{
  "eligible": false,
  "items": [
    { "type": "TERMS_OF_SERVICE",       "required": true,  "agreed": false },
    { "type": "PRIVACY_COLLECTION_USE", "required": true,  "agreed": false },
    { "type": "MARKETING",              "required": false, "agreed": false }
  ]
}

FE가 로그인 흐름과 무관하게 언제든 조회할 수 있어야 한다. 문서 원문은 FE가 보유하므로 이 응답에 싣지 않는다.

2. 동의 제출

POST /api/v2/agreements — 일반 인증 필요, AgreementGate 면제

{
  "agreements": [
    {
      "type": "TERMS_OF_SERVICE",
      "action": "AGREE",
      "content": "제1조 (목적) 이 약관은 ...",
      "inputContext": "INDIVIDUAL"
    },
    {
      "type": "PRIVACY_COLLECTION_USE",
      "action": "AGREE",
      "content": "수집 항목: 이메일, 연령 ...",
      "inputContext": "INDIVIDUAL"
    }
  ]
}

• 최초 동의 / 기준일 상향에 따른 재동의 / 선택 동의 추가 / 철회의 단일 진입점이다.
• content는 사용자에게 실제로 표시된 원문이며 그대로 스냅샷 저장한다. recorded_at은 서버 시각으로 채우고 클라이언트 동의 일자를 받지 않는다.
• 멱등·재진입 가능해야 한다. 재시도 안전성을 별도 토큰 소진 메커니즘으로 달성하지 않는다.
• 응답은 조회 API와 동일 스키마(eligible 갱신)를 반환한다.

트레이드오프: 원문을 클라이언트 전송값으로 받아 저장한다. 서버가 문서를 소유하는 방식보다 증빙 강도가 낮다는 점을 인지하고 채택한 결정이다.

3. Gate 차단 응답

기존 응답 봉투를 그대로 쓴다. GlobalResponse나 Error를 수정하지 않는다. UserExceptionCode에 코드 한 줄을 추가하면 Error(ExceptionCode, HttpStatus, String) 구조상 키 코드가 자동으로 직렬화된다.

HTTP/1.1 403 Forbidden

{
  "success": false,
  "code": 403,
  "data": [],
  "errors": [
    { "code": "AGREEMENT_REQUIRED", "status": "FORBIDDEN", "message": "필수 약관 동의가 필요합니다." }
  ],
  "meta": { }
}

• 차단 응답에 부족 유형 목록을 싣지 않는다. GlobalResponse.error()가 data를 emptyList()로 고정하므로 목록을 실으려면 전역 응답 계약을 고쳐야 하는데 그럴 값어치가 없다. FE는 403을 받으면 동의 화면으로 전환하면서 조회 API를 호출한다.
• 즉 차단은 신호, 내용은 조회 API가 단일 출처다. 판정 주체가 하나라는 원칙은 유지된다.
• 구분은 errors[0].code로 한다. 이 프로젝트는 JwtExceptionType.EXPIRED_TOKEN도 403이므로 상태코드만으로는 401/권한없음/만료토큰과 구분되지 않는다.

4. 로그인 응답 힌트

기존 소셜 로그인 응답에 agreementRequired 불리언 필드 하나를 추가한다. 값은 Evaluator 결과를 쓰며 로그인 서비스가 따로 판정하지 않는다.

{
  "accessToken": "...",
  "isFirstLogin": true,
  "nickname": "...",
  "agreementRequired": true
}

• FE 라우팅용 힌트이며 집행 근거가 아니다. 로그인 시점의 스냅샷일 뿐이고, 실제 차단은 항상 Gate가 요청 시점에 한다. 이 값이 false여도 이후 요청에서 403이 날 수 있다.
• 없어도 기능은 동작한다. 신규 가입자가 홈에 진입했다가 403으로 튕기는 깜빡임을 없애는 용도다.
• 로그인 응답은 단일 스키마를 유지한다. 신규/기존 회원 분기, 다형 응답, oneOf를 만들지 않는다. 필드 하나가 늘 뿐이다.

AgreementGate 면제 범위

미충족 상태에서도 반드시 허용한다.

• 동의 상태 조회, 동의 제출
• 토큰 재발급, 로그아웃
• 계정 탈퇴, 개인정보 열람·삭제 등 정보주체 권리 행사 기능

탈퇴·로그아웃을 막으면 동의하지 않고는 서비스를 떠날 수 없게 된다. 동의 API 자체를 막으면 미충족 상태에서 영원히 빠져나올 수 없다.

면제는 전용 어노테이션으로 선언한다. 경로 목록을 Gate 안에 하드코딩하지 않는다. 기존 @SecurityPolicy에 속성을 얹지 않고 별도 어노테이션을 두는데, @SecurityPolicy는 인증 정책을 표현하는 것이고 이 아키텍처의 전제가 "동의 정책을 인증에 결합하지 않는다"이기 때문이다.

Gate 배치

인터셉터로 구현한다. 인증 필터 안에서 차단하지 않는다.

1. HandlerMethod에 접근되므로 면제 어노테이션을 직접 읽어 판정할 수 있다. 별도 경로 레지스트리가 필요 없다.
2. 차단 응답이 @RestControllerAdvice를 타므로 기존 GlobalResponse 형식을 그대로 쓴다. 필터에서 차단하면 JSON을 직접 직렬화해야 하고 기존 에러 포맷과 어긋난다.
3. 인증은 필터, 정책은 인터셉터로 계층이 갈려 관심사 분리가 구조에 드러난다.

구현 체크포인트

의존성 순서대로 진행한다. 각 체크포인트는 독립 커밋·독립 검증이 가능해야 한다.

CP1. 스키마 + Evaluator

• user_agreements 스키마 추가 (Flyway)
• append-only 규약 확립 (UPDATE / DELETE 경로 없음)
• 필수 유형 목록·유형별 기준일 설정 구조 추가
• 사용자·유형별 최신 이벤트 도출
• 판정: REVOKE 우선 → 유형별 recorded_at >= 기준일 → ELIGIBLE / WAITING_TO_AGREE
• 필수 유형만 판정 대상에 포함, 선택 유형 제외 검증
• 기준일 상향 시 기존 동의자가 자동으로 미충족이 되는지 검증

CP2. 동의 API 2종

• 상태 조회 API
• 동의 제출 API (AGREE / REVOKE 공용, 멱등)
• 철회가 기존 행을 덮지 않고 REVOKE 행으로 쌓이는지 검증
• recorded_at이 서버 시각으로만 채워지는지 검증
• 두 응답이 동일 스키마임을 검증

CP3. Gate 체인

• 인증 이후 인터셉터 단계에 AccountStateGate → AgreementGate 배치
• JWT 인증 필터에 동의 정책이 결합되지 않았음을 확인
• 403 AGREEMENT_REQUIRED 응답 계약 (기존 GlobalResponse 봉투 그대로, Error 수정 없음)
• 전용 면제 어노테이션으로 선언적 지정, 하드코딩 경로 목록 없음
• 미충족 사용자의 탈퇴·로그아웃·재발급 가능 검증
• 기존 발급 JWT 보유자가 기준일 상향 즉시 차단되는지 검증

CP4. 로그인 응답 및 잔재 제거

• 로그인 응답에 agreementRequired 필드 추가 (집행 근거 아님, FE 라우팅용)
• 로그인 응답이 단일 스키마임을 확인 (분기·다형 응답 없음)
• signupToken 관련 잔재가 코드·문서·OpenAPI에 남아 있지 않음 확인

완료 기준

• 신규·기존 회원 모두 소셜 로그인 직후 동일한 응답 형태로 JWT를 받는다
• 필수 동의 미충족 사용자는 보호 API에서 403 + errors[0].code === "AGREEMENT_REQUIRED" 를 받는다
• 미충족 사용자도 동의 조회·제출·로그아웃·탈퇴는 수행할 수 있다
• 동의 제출 후 재요청 시 별도 재로그인 없이 보호 API에 접근된다
• 동의 이력에 누가·무엇을·왜·어떻게·언제·거부하면·철회하면이 컬럼과 원문 스냅샷으로 입증된다
• 동의 이력이 append-only이며 철회가 REVOKE 행으로 쌓인다
• 기준일 상향 시 기존 동의자가 재동의 대상이 된다
• 선택 동의 미동의는 접근을 차단하지 않는다
• users 테이블이 수정되지 않으며 users.status가 동의 판정의 근거가 아니다

확정 사항 (재논의 불필요)

• 기존 회원도 새로 동의를 받는다. 소급 인정하지 않는다. 도입 시점 기준일을 배포일로 잡으면 그 이전 동의 기록이 없거나 기준일 이전이므로 전원이 자연스럽게 게이트에 걸린다. 별도 소급 로직·유예 로직을 만들지 않는다.
• 문서 레지스트리 테이블과 버전 관리 체계를 두지 않는다. 원문 스냅샷을 이력 행에 직접 저장하고, 교체는 기준일 상향으로 표현한다.
• 동의 이력은 append-only다.
• users 테이블은 수정하지 않는다.

아직 정책 결정이 필요한 항목

법무·운영·제품 확인이 선행돼야 한다. 근거가 필요하면 개인정보보호위원회·국가법령정보센터 등 공식 출처를 사용한다. #361은 산출물·결정 기록 없이 닫혀 있어 근거로 쓸 수 없다.

아래 항목은 구현 착수를 막지 않는다. 필수 2종(TERMS_OF_SERVICE, PRIVACY_COLLECTION_USE)은 확정됐고, 유형 목록과 기준일이 설정 기반이라 나머지는 값 채우기와 후속 작업으로 처리된다.

• 동의 항목 매트릭스 — 제3자 제공 / 마케팅의 추가와 필수·선택 구분. 설정에 유형을 더하면 되므로 배포 전까지 확정하면 된다
• 기준일 값과 상향 판단 기준 — 도입 시점 기준일은 배포 시 설정값. 어떤 약관 변경이 재동의를 유발하는지는 운영 기준
• 미충족 방치 상한 — 동의하지 않고 로그인만 반복하는 계정의 처리. 후속 배치 작업
• 필수 항목 철회 가능 여부 — 우선 AGREE만 열고 REVOKE 노출은 결정 후
• 동의 이전 개인정보 수집 범위 — 계정 생성 시점에 저장할 최소 항목
• 미성년자·연령 기준, 보유기간·파기 기준

후속 영향

• [FE/Auth] 소셜 신규가입 동의 화면 및 가입 완료 흐름 연동 #363(FE)은 재정의가 필요하다. 현재 SIGNUP_REQUIRED 상태 수신, signupToken 보관, 가입 완료 후 소셜 로그인 재호출을 전제로 작성돼 있으며 이 전제가 모두 사라진다. 새 FE 계약은 (1) 로그인은 항상 정상 세션으로 진입, (2) 동의 필요 여부는 로그인 응답 힌트 또는 상태 조회 API로 확인, (3) 동의 제출 시 표시한 원문을 함께 전송, (4) 403 AGREEMENT_REQUIRED를 동의 화면 전환 신호로 처리하는 형태다.
• 배포 순서: FE가 동의 화면을 처리할 수 있는 상태로 먼저 배포돼야 한다. Gate가 먼저 켜지면 전 사용자가 처리 불가능한 403을 받는다.
• 남은 정책 결정 항목은 구현 착수를 막지 않는다. 배포 전까지 설정값으로 채우면 된다.

관련

• 폐기된 원래 요구사항과 사유: 이 이슈의 아카이브 코멘트
• 데이터 모델 확정 근거: 이 이슈의 스키마 코멘트
• 정책/계약 이슈: 기획: 신규가입 동의·개인정보 처리 기준 및 구현 계약 확정 #361 (closed, 산출물 없음)
• FE 연동 이슈: [FE/Auth] 소셜 신규가입 동의 화면 및 가입 완료 흐름 연동 #363 (재정의 필요)
• 폐기된 구현: feat: 신규 소셜 가입 대기 및 동의 완료 흐름 추가 bottle-note-api-server#689 (closed, 미병합)

[Whale0928]

폐기된 기존 요구사항 (아카이브)

아래는 이 이슈의 원래 본문이다. 기록 보존을 위해 코멘트로 옮긴다. 더 이상 유효하지 않으며 구현 근거로 사용하지 않는다.

폐기 사유

1. 가입 시점에만 동작한다. 로그인 응답에서 분기하는 구조는 최초 가입 순간밖에 잡지 못한다. 필수 문서의 새 버전이 발행됐을 때 이미 유효한 JWT를 가진 기존 회원을 재동의시킬 방법이 없다. 문서 교체에 따른 재동의를 원리적으로 지원하지 못한다.
2. 인증 체계가 둘로 늘어난다. 서명 키·검증 경로·소진 관리가 별도로 필요한 두 번째 토큰 종류(signupToken)가 생기고 그만큼 공격면과 유지 비용이 늘어난다. 얻는 것은 "가입 미완료자에게 access token을 주지 않는다" 하나인데, 이는 인증 이후 접근 차단으로 동일하게 달성된다.
3. 로그인 응답 계약이 오염된다. 하나의 200 응답에 두 개의 스키마가 공존하고 판별자가 없어 클라이언트와 API 문서 계약이 모두 불안정해진다.
4. 완료 후 재로그인이 불필요하다. 신원은 이미 검증됐는데 소셜 왕복을 한 번 더 요구할 근거가 없다.
5. 동의 전 개인정보를 먼저 저장한다. SIGNUP_PENDING 사용자 행을 먼저 만들고 그 다음에 개인정보 수집·이용 동의를 받는 순서였다.
6. 문서 버전이 검증 불가능한 자유 문자열이었다. 서버가 문서를 소유하지 않아 동의 이력의 기준값이 존재하지 않았다. 선행 정책 이슈 #361이 산출물·결정 기록 없이 닫힌 상태에서 저장 API부터 구현한 결과다.

해당 방향의 구현 PR bottle-note/bottle-note-api-server#689 는 병합 없이 닫혔다. 대체 아키텍처는 이 이슈의 본문을 참조한다.

---

원래 본문 전문

목적

소셜 로그인 성공 시 기존 회원은 즉시 로그인하고, 최초 회원은 동의 완료 전까지 일반 인증 토큰을 발급하지 않는 가입 대기 흐름으로 분리한다.

변경 범위

1. Apple/Kakao 소셜 로그인 응답 분기

• 기존 ACTIVE 회원은 현재와 같이 access token·refresh token을 발급하고 로그인 완료 상태를 반환한다.
• 최초 회원은 SIGNUP_PENDING 상태로 생성 또는 유지하고, 일반 인증 토큰 및 refresh cookie는 발급하지 않는다.
• 최초 회원 응답에는 가입 필요 상태값과 단기 signupToken을 포함한다.
• signupToken은 가입 완료 API 전용으로, 사용자 식별자·소셜 공급자·만료·일회성 식별자를 검증할 수 있어야 한다. 기존 로그인 JWT와 검증 경로를 분리한다.

2. 공통 가입 완료 엔드포인트

POST /api/v2/auth/signup

{
  "signupToken": "신규 사용자 임시 인증 토큰",
  "agreements": [
    {
      "type": "TERMS_OF_SERVICE",
      "version": "2026-08-01"
    },
    {
      "type": "PRIVACY_COLLECTION_USE",
      "version": "2026-08-01"
    }
  ]
}

• Apple/Kakao 공통 엔드포인트로 처리한다.
• 토큰 서명·만료·용도·가입 대기 상태를 검증한다.
• 동의 이력에 사용자 식별자, 동의 유형, 문서 버전, AGREE, 서버 기록 시각을 저장한다.
• 동의 이력 저장과 SIGNUP_PENDING → ACTIVE 전환은 하나의 트랜잭션으로 처리한다.
• 이미 활성화됐거나 소진된 signupToken은 재사용할 수 없게 한다. 가입 완료 요청은 재시도 시 안전하게 처리한다.
• 가입 완료 후 일반 로그인 토큰을 발급하지 않으며, 클라이언트는 기존 Apple/Kakao 로그인 흐름으로 다시 로그인한다.

완료 기준

• 기존 Apple/Kakao 회원은 소셜 로그인 직후 기존 로그인 응답과 토큰을 받는다.
• 최초 회원은 가입 필요 상태·signupToken만 받고 일반 인증 토큰/refresh cookie를 받지 않는다.
• 공통 가입 API가 제공한 payload를 검증하고 동의 이력과 활성화 전환을 저장한다.
• 동의 시각은 서버 기록 시각으로 저장된다. 제공 payload에는 클라이언트 동의 일자를 별도로 받지 않는다.
• 가입 완료 후 재로그인 시 ACTIVE 회원으로 정상 토큰이 발급된다.
• 가입 대기 사용자는 일반 인증이 필요한 API에 접근할 수 없다.

관련

• 정책/계약 이슈: 기획: 신규가입 동의·개인정보 처리 기준 및 구현 계약 확정 #361 (closed)
• FE 가입 동의 흐름 구현은 별도 이슈로 분리한다.

[Whale0928]

데이터 모델 확정 — user_agreements 단일 테이블 (최신)

이 코멘트가 데이터 모델의 최신 기준이다. 아래 내용은 본문의 구현 가이드 (1/2) — 동의 테이블 + 동의 등록·조회 API와 일치한다. 로그인 수단 정보는 동의 이력에 저장하지 않는다.

문서 레지스트리(agreement_documents)를 별도 테이블로 만들지 않는다. 동의 시점 문서 원문을 이력 행에 스냅샷으로 저장하고, users 테이블은 수정하지 않는다.

CREATE TABLE `user_agreements` (
  `id`               bigint       NOT NULL AUTO_INCREMENT COMMENT '동의 이력 ID',
  `user_id`          bigint       NOT NULL COMMENT '사용자 ID',
  `agreement_type`   varchar(50)  NOT NULL COMMENT '동의 유형',
  `action`           varchar(20)  NOT NULL COMMENT '동의 의사표시 (AGREE/REVOKE)',
  `document_content` mediumtext   NOT NULL COMMENT '동의 시점 문서 원문 스냅샷',
  `recorded_at`      datetime(6)  NOT NULL COMMENT '서버 기록 시각',
  `input_context`    varchar(20)  NOT NULL COMMENT '선택 맥락 (INDIVIDUAL/BULK)',
  `client_ip`        varchar(45)  DEFAULT NULL COMMENT '동의 요청 IP',
  `user_agent`       varchar(512) DEFAULT NULL COMMENT '동의 요청 User-Agent',
  PRIMARY KEY (`id`),
  KEY `idx_user_agreements_user_type_recorded` (`user_id`, `agreement_type`, `recorded_at`),
  CONSTRAINT `fk_user_agreements_user_id` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='사용자 약관·개인정보 동의 이력';

컬럼 근거

컬럼	역할
user_id	동의 주체. JWT 인증 후 CustomUserContext.getId()에서 얻으며 요청 본문으로 받지 않는다
agreement_type	어느 항목의 동의인지 식별하고 유형별 최신 이벤트를 판정한다
action	명시적 의사표시. 철회는 기존 행 수정이 아니라 REVOKE 행 추가로 기록한다
document_content	사용자에게 표시된 동의 시점 원문 스냅샷. 수집 목적·법적 근거·거부·철회 효과를 원문으로 보존한다
recorded_at	서버 기록 시각. 클라이언트 동의 시각은 받지 않는다
input_context	개별 선택인지 전체 동의인지 구분한다
client_ip / user_agent	동의 요청 정황을 기록하는 선택 정보다

동의 주체는 인증된 user_id로 식별하며, 로그인 수단 정보는 동의 이력에 별도로 저장하지 않는다.

append-only

• 기존 동의 행은 UPDATE/DELETE하지 않는다.
• 철회는 REVOKE 행을 추가한다.
• UserAgreement는 정적 팩토리로만 생성하고 setter·상태 변경 메서드를 두지 않는다.
• 도메인 포트는 저장과 사용자·유형별 최신 이벤트 조회만 노출한다.

@DomainRepository
public interface UserAgreementRepository {
  void saveAll(List<UserAgreement> agreements);
  List<UserAgreement> findLatestByUserIdAndTypes(Long userId, Set<AgreementType> types);
}

판정 로직

필수 유형 목록과 유형별 기준일은 서버 설정이 소유한다. 문서 교체와 재동의 강제는 해당 유형의 effective-from 상향으로 표현한다.

1. 해당 유형 이벤트 없음 → 미충족
2. 최신 이벤트가 REVOKE → 미충족
3. 최신 이벤트의 recorded_at이 기준일 이전 → 미충족
4. 모든 필수 유형이 AGREE이고 기준일 이후 → ELIGIBLE

선택 유형은 현재 동의 여부만 응답하고 전체 eligible 판정에는 반영하지 않는다. 판정은 AgreementEvaluator 하나가 소유하며 상태 조회 API·로그인 힌트·AgreementGate가 같은 결과를 사용한다.

users 테이블

• 수정하지 않는다.
• users.status는 계정 생명주기 전용으로 유지한다.
• WAITING_TO_AGREE 같은 동의 상태를 사용자 상태 enum에 추가하지 않는다.
• 동의 충족 여부는 user_agreements와 정책 설정에서 요청 시점에 계산하는 파생값이다.

구현 기준

• migration은 bottle-note/environment-variables의 V7__add_user_agreements.sql로 추가한다. 폐기된 V6 migration은 재사용하지 않는다.
• 포트와 JPA 구현을 분리한다.
• 테스트는 Mockito를 사용하지 않고 bottlenote-test-support의 InMemoryUserAgreementRepository로 상태와 결과를 검증한다.
• Gate 인터셉터와 로그인 응답 힌트는 구현 가이드 2/2의 별도 PR 범위다.

[Whale0928]

구현 가이드 (1/2) — 동의 테이블 + 동의 등록·조회 API

BE PR 1의 범위다. Gate 인터셉터는 이 PR에 포함하지 않는다(가이드 2/2 참조). 이 PR만 머지되면 동의를 기록·조회할 수 있고, 아직 아무것도 차단하지 않는다. 그래서 단독으로 안전하게 배포된다.

선행 — 스키마 PR (별도 저장소)

bottle-note/environment-variables에 별도 PR을 먼저 올린다. 이 저장소 소스 트리에는 db/migration이 없고 서브모듈이 원본이다.

• 경로: storage/db/migration/V7__add_user_agreements.sql
• 버전은 V7이다. V6는 열려 있는 PR API Application Deploy Time Improvement #6(V6__add_agent_key_auth.sql)이 점유 중이다. 폐기된 PR #7의 V6__add_signup_pending_agreements.sql을 되살리지 않는다.
• 브랜치는 반드시 origin/main에서 딴다. 서브모듈 워킹트리가 폐기된 커밋(c8d0a7c)에 detached HEAD로 남아 있을 수 있다. 그 상태에서 브랜치를 만들면 폐기된 V6가 딸려 들어간다.

CREATE TABLE `user_agreements` (
  `id`               bigint       NOT NULL AUTO_INCREMENT COMMENT '동의 이력 ID',
  `user_id`          bigint       NOT NULL COMMENT '사용자 ID',
  `agreement_type`   varchar(50)  NOT NULL COMMENT '동의 유형',
  `action`           varchar(20)  NOT NULL COMMENT '동의 의사표시 (AGREE/REVOKE)',
  `document_content` mediumtext   NOT NULL COMMENT '동의 시점 문서 원문 스냅샷',
  `recorded_at`      datetime(6)  NOT NULL COMMENT '서버 기록 시각',
  `input_context`    varchar(20)  NOT NULL COMMENT '선택 맥락 (INDIVIDUAL/BULK)',
  `client_ip`        varchar(45)  DEFAULT NULL COMMENT '동의 요청 IP',
  `user_agent`       varchar(512) DEFAULT NULL COMMENT '동의 요청 User-Agent',
  PRIMARY KEY (`id`),
  KEY `idx_user_agreements_user_type_recorded` (`user_id`, `agreement_type`, `recorded_at`),
  CONSTRAINT `fk_user_agreements_user_id` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='사용자 약관·개인정보 동의 이력';

스키마 PR 머지 후 이 저장소에서 서브모듈 포인터를 갱신해야 반영된다. ddl-auto가 validate이므로 포인터 갱신 없이 엔티티만 추가하면 기동 시 실패한다.

파일 배치

레이어 표준 2·4를 따른다. 도메인 레포지토리(포트)와 JPA 구현을 분리한다.

bottlenote-mono/src/main/java/app/bottlenote/user/
  constant/    AgreementType.java          (TERMS_OF_SERVICE, PRIVACY_COLLECTION_USE)
               AgreementAction.java        (AGREE, REVOKE)
               AgreementInputContext.java  (INDIVIDUAL, BULK)
  domain/      UserAgreement.java          (@Entity)
               UserAgreementRepository.java(@DomainRepository, 순수 인터페이스)
  repository/  JpaUserAgreementRepository.java (@JpaRepositoryImpl)
  service/     AgreementEvaluator.java
               AgreementService.java
  dto/request/ AgreementSubmitRequest.java
  dto/response/AgreementStatusResponse.java
  config/      AgreementPolicyProperties.java (@ConfigurationProperties)
  exception/   UserExceptionCode.java 에 코드 추가

bottlenote-product-api/src/main/java/app/bottlenote/user/
  controller/  AgreementController.java
  controller/docs/ AgreementApiDocs.java

@DomainRepository / @JpaRepositoryImpl은 app.bottlenote.common.annotation에 이미 있다.

도메인

UserAgreement는 BaseTimeEntity를 상속하지 않는다. recorded_at이 이 테이블의 시각 필드이고, 생성 시각을 따로 둘 이유가 없다. 정적 팩토리로만 생성하고 수정 메서드를 만들지 않는다 — append-only이므로 setter나 상태 변경 메서드가 존재하면 안 된다.

포트 시그니처에 Spring Data 타입(Page, Pageable, Sort)을 노출하지 않는다(레이어 표준 3).

@DomainRepository
public interface UserAgreementRepository {
  void saveAll(List<UserAgreement> agreements);
  List<UserAgreement> findLatestByUserIdAndTypes(Long userId, Set<AgreementType> types);
}

findLatestByUserIdAndTypes는 유형별 최신 1건씩을 반환한다. 단순 조회가 아니므로 @Query JPQL 또는 QueryDSL로 구현한다.

정책 설정

필수 유형 목록과 유형별 기준일은 설정이 소유한다. 테이블에 두지 않는다.

agreement:
  policies:
    TERMS_OF_SERVICE:
      required: true
      effective-from: 2026-08-01T00:00:00
    PRIVACY_COLLECTION_USE:
      required: true
      effective-from: 2026-08-01T00:00:00

effective-from을 올리는 것이 곧 재동의 강제다. 오입력하면 전 사용자가 차단되므로 설정 변경은 리뷰 대상이다.

Evaluator

판정 주체는 이것 하나다. 조회 API, 로그인 힌트, Gate가 전부 이 결과를 쓴다. 서비스마다 판정 로직을 복제하지 않는다.

// 유형별 최신 이벤트 1건씩 → 아래 순서로 판정
// 1. 해당 유형 이벤트 없음        -> 미충족
// 2. 최신 이벤트가 REVOKE         -> 미충족 (기준일 무관)
// 3. recorded_at < 기준일          -> 미충족
// 4. 필수 유형 전부 통과           -> ELIGIBLE

필수 유형만 판정 대상이다. 선택 유형은 agreed 여부만 응답에 싣고 eligible에 반영하지 않는다.

API

두 엔드포인트 모두 일반 인증이 필요하다. @SecurityPolicy(auth = REQUIRED_AUTH).

조회 GET /api/v2/agreements/status

{
  "eligible": false,
  "items": [
    { "type": "TERMS_OF_SERVICE",       "required": true, "agreed": false },
    { "type": "PRIVACY_COLLECTION_USE", "required": true, "agreed": false }
  ]
}

제출 POST /api/v2/agreements

{
  "agreements": [
    { "type": "TERMS_OF_SERVICE",       "action": "AGREE", "content": "제1조 (목적) ...", "inputContext": "INDIVIDUAL" },
    { "type": "PRIVACY_COLLECTION_USE", "action": "AGREE", "content": "수집 항목: ...",   "inputContext": "INDIVIDUAL" }
  ]
}

• 응답은 조회 API와 동일 스키마를 반환한다(eligible 갱신). 두 엔드포인트가 같은 DTO를 쓴다. Gate 차단 응답은 기존 GlobalResponse 에러 봉투를 쓰므로 이 DTO와 무관하다(가이드 2/2 참조).
• userId는 CustomUserContext.getId()에서 가져온다. 요청 본문으로 받지 않는다.
• recorded_at은 서버 시각으로 채운다. 클라이언트 동의 일자를 받지 않는다.
• client_ip는 X-Forwarded-For에서 얻는다. 게이트웨이가 실제 접속 주소로 다시 채우므로 신뢰 가능하다.
• 멱등이어야 한다. 같은 요청을 두 번 보내면 이벤트 2건이 쌓이되 판정 결과는 같고 오류가 나지 않는다. 별도 토큰 소진 메커니즘을 만들지 않는다.
• 트랜잭션은 Service가 소유한다(레이어 표준 9). Controller는 도메인 VO를 직접 생성하지 않는다.

예외

UserExceptionCode에 추가한다. 도메인이 예외를 소유한다(레이어 표준 14).

INVALID_AGREEMENT_TYPE   400  알 수 없는 동의 유형입니다.
AGREEMENT_CONTENT_EMPTY  400  동의 문서 원문은 비어 있을 수 없습니다.

테스트

• Mockito 금지. InMemoryUserAgreementRepository Fake를 bottlenote-test-support의 user.fixture에 만든다(레이어 표준 10). 기존 FakeOauthRepository가 참고 대상이다.
• Evaluator 단위 테스트를 우선한다: 이벤트 없음 / REVOKE 최신 / 기준일 이전 / 정상 / 선택 유형 미동의 5케이스.
• 통합 테스트는 IntegrationTestSupport 상속, MockMvcTester 사용.
• RestDocs·OpenAPI 문서 테스트를 함께 갱신한다.
• @Tag("unit") / @Tag("integration") 부착.

이 PR에 넣지 말 것

• Gate 인터셉터, 면제 어노테이션, 403 차단 (PR 2)
• 로그인 응답의 동의 필요 힌트 (PR 2)
• users 테이블 변경 — 이 기능은 users를 수정하지 않는다
• signupToken 관련 잔재 제거 (PR 2)

완료 조건

• 스키마 PR 머지 및 서브모듈 포인터 갱신
• 동의 제출 후 조회 API의 eligible이 true로 바뀐다
• REVOKE 제출 시 기존 AGREE 행이 남고 최신 판정만 미충족으로 바뀐다
• 기준일을 올리면 기존 동의자가 미충족이 된다
• 선택 유형 미동의가 eligible에 영향을 주지 않는다
• ./gradlew build, unit_test, integration_test, check_rule_test 통과

[Whale0928]

구현 가이드 (2/2) — Gate 인터셉터 구현 및 등록

BE PR 2의 범위다. PR 1(동의 테이블 + 등록·조회 API)이 머지된 뒤에 착수한다. 이 PR이 실제로 차단을 켜므로, FE가 403을 처리할 수 있는 상태로 먼저 배포된 뒤에 머지해야 한다. 순서가 뒤바뀌면 전 사용자가 처리 불가능한 403을 받는다.

파일 배치

bottlenote-mono/src/main/java/app/bottlenote/user/
  annotation/  AgreementExempt.java        (전용 면제 어노테이션)
  service/     AgreementGateInterceptor.java
  exception/   UserExceptionCode.java 에 AGREEMENT_REQUIRED 추가

bottlenote-mono/src/main/java/app/bottlenote/global/config/
  WebConfig.java  ← addInterceptors 오버라이드 추가

AgreementEvaluator는 PR 1에서 만든 것을 그대로 주입해 쓴다. 판정 로직을 인터셉터에 복제하지 않는다.

면제 어노테이션

기존 @SecurityPolicy(global/annotation/SecurityPolicy.java)에 속성을 얹지 않는다. @SecurityPolicy는 인증 정책을 표현하고, 이 아키텍처의 전제가 "동의 정책을 인증에 결합하지 않는다"이기 때문이다.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface AgreementExempt {}

인터셉터

필터가 아니라 인터셉터다. 인증 필터 안에서 차단하지 않는다.

• HandlerMethod에 접근되므로 면제 어노테이션을 직접 읽는다. 별도 경로 레지스트리가 필요 없다.
• 차단 예외가 GlobalExceptionHandler(global/exception/handler/)를 타므로 기존 GlobalResponse 형식을 그대로 쓴다. 필터에서 차단하면 JSON을 직접 직렬화해야 하고 기존 에러 포맷과 어긋난다.
• 인증은 필터, 정책은 인터셉터로 계층이 갈린다.

동작 순서:

1. handler가 HandlerMethod가 아니면 통과 (정적 리소스 등)
2. 메서드 또는 클래스에 @AgreementExempt 가 있으면 통과
3. 인증 주체가 없거나 익명이면 통과 (인증은 이미 필터가 처리했다)
4. CustomUserContext.getId() 로 AgreementEvaluator 판정
5. 미충족이면 예외를 던진다 (응답을 직접 쓰지 않는다)

3번이 중요하다. 미인증 요청을 여기서 401로 만들지 않는다. 인증 실패는 이미 필터 계층의 책임이고, 여기서 겹치면 401과 403이 섞인다.

WebConfig 등록

WebConfig는 이미 WebMvcConfigurer를 구현하고 있고 인터셉터가 아직 하나도 없다. addInterceptors를 오버라이드해 등록한다.

@Override
public void addInterceptors(InterceptorRegistry registry) {
  registry.addInterceptor(agreementGateInterceptor);
}

excludePathPatterns로 면제 경로를 나열하지 않는다. 면제는 어노테이션이 표현한다.

차단 응답 계약

기존 응답 봉투를 그대로 쓴다. GlobalResponse나 Error를 수정하지 않는다.

UserExceptionCode에 한 줄 추가하면 끝이다. Error 레코드가 (ExceptionCode code, HttpStatus status, String message)이고 ExceptionCode가 enum이라 키 코드가 자동으로 직렬화된다.

AGREEMENT_REQUIRED(HttpStatus.FORBIDDEN, "필수 약관 동의가 필요합니다."),

HTTP/1.1 403 Forbidden

{
  "success": false,
  "code": 403,
  "data": [],
  "errors": [
    { "code": "AGREEMENT_REQUIRED", "status": "FORBIDDEN", "message": "필수 약관 동의가 필요합니다." }
  ],
  "meta": { }
}

차단 응답에 부족 유형 목록을 싣지 않는다. GlobalResponse.error()는 data를 emptyList()로 고정하므로 목록을 실으려면 전역 응답 계약을 고쳐야 하는데, 그럴 값어치가 없다. FE는 403을 받으면 동의 화면으로 전환하면서 조회 API를 호출한다. 동의 화면이 진입 경로와 무관하게 항상 최신 상태를 조회하게 되므로 다른 기기에서 이미 동의한 경우도 자연히 처리된다.

즉 차단은 신호, 내용은 조회 API가 단일 출처다. 판정 주체가 하나라는 원칙은 그대로 유지된다.

401(인증 실패), 일반 403(권한 없음), 계정 정지와 구별은 errors[0].code로 한다. 참고로 이 프로젝트는 JwtExceptionType.EXPIRED_TOKEN도 403이므로 상태코드만으로는 구분되지 않는다. FE 문서에 명시했다.

면제 대상

@AgreementExempt를 붙여야 하는 곳. 빠뜨리면 사용자가 미충족 상태에서 영원히 빠져나오지 못한다.

• 동의 상태 조회, 동의 제출 (PR 1에서 만든 두 엔드포인트)
• 토큰 재발급, 로그아웃
• 계정 탈퇴, 개인정보 열람·삭제 등 정보주체 권리 행사 기능

탈퇴·로그아웃을 막으면 동의하지 않고는 서비스를 떠날 수 없게 된다. 이건 협상 대상이 아니다.

로그인 응답 힌트

기존 소셜 로그인 응답에 agreementRequired 불리언 필드 하나를 추가한다. 필드명을 임의로 바꾸지 않는다 — FE 스펙이 이 이름으로 나가 있다.

{
  "accessToken": "...",
  "isFirstLogin": true,
  "nickname": "...",
  "agreementRequired": true
}

• 값은 AgreementEvaluator 결과를 쓴다. 로그인 서비스에서 따로 판정하지 않는다.
• FE 라우팅용이며 집행 근거가 아니다. 실제 차단은 항상 인터셉터가 요청 시점에 한다. 이 값이 false여도 이후 요청에서 403이 날 수 있다.
• 로그인 응답은 단일 스키마를 유지한다. 신규/기존 회원 분기, 다형 응답, oneOf를 만들지 않는다. 필드 하나가 늘 뿐이다.

signupToken 잔재 제거

폐기된 구현의 흔적이 남아 있으면 이 PR에서 정리한다. 코드, RestDocs, OpenAPI 문서 전부 확인한다.

테스트

• Mockito 금지. PR 1에서 만든 InMemoryUserAgreementRepository Fake를 재사용한다.
• 인터셉터 단위 테스트: 면제 어노테이션 있음 / 없음+충족 / 없음+미충족 / 미인증 4케이스.
• 통합 테스트가 핵심이다. 이미 발급된 JWT를 가진 사용자가 기준일 상향 직후 403을 받는지 반드시 검증한다. 이게 이 아키텍처를 채택한 이유다.
• 미충족 사용자의 탈퇴·로그아웃·재발급·동의 제출이 되는지 검증한다.
• 폐기된 PR에서 OpenApiDocsIntegrationTest(공통 응답 형식 2건)와 UserCommandIntegrationTest(탈퇴 회원 재탈퇴)가 깨졌다. 응답 형식과 탈퇴 경로를 건드리므로 이 셋을 특히 확인한다.

완료 조건

• 미충족 사용자가 보호 API에서 403 + errors[0].code === "AGREEMENT_REQUIRED" 를 받는다
• 차단 응답이 기존 GlobalResponse 봉투 그대로이며 GlobalResponse·Error가 수정되지 않았다
• 미충족 사용자도 동의 조회·제출·로그아웃·탈퇴가 된다
• 동의 제출 후 재요청 시 재로그인 없이 보호 API에 접근된다
• 기존 발급 JWT 보유자가 기준일 상향 즉시 차단된다
• 면제 경로가 어노테이션으로만 지정되고 하드코딩 목록이 없다
• 로그인 응답이 단일 스키마다
• ./gradlew build, unit_test, integration_test, check_rule_test 통과

배포 순서

1. PR 1 머지·배포 (차단 없음, 안전)
2. FE 동의 화면 배포
3. PR 2 머지·배포 (차단 시작)
4. 기준일 설정값 확정 — 이 값을 넣는 순간 전 사용자가 재동의 대상이 된다