From 575c1a8ad208917b0150f83958a5794c5be791e5 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Fri, 27 Mar 2026 12:28:02 +0900 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20UUID=20=EA=B2=80=EC=A6=9D?= =?UTF-8?q?=20=EC=A0=95=EC=B1=85(=EC=86=8C=EB=B9=84=EC=9E=90=20UUID,=20?= =?UTF-8?q?=ED=8F=B4=EB=B0=B1,=20=EC=98=88=EC=95=BD=EC=96=B4)=20=EB=B0=8F?= =?UTF-8?q?=20coding-principles=20SSOT=20=EB=A7=81=ED=81=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Pydantic은 UUID4가 아닌 버전 무관 UUID 수용 - auth-server UUID4 생성 정책과 소비자 검증 정책 분리 명시 - email_integration/robeing-monitor UUID5 폴백은 장애 시만, 거부 금지 - system/external_service는 user_id 금지, actor 필드 사용 - 상위 SSOT: 0_VALUE coding-principles.md 링크 Made-with: Cursor --- .../uuid_conversion_system.md | 33 +++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/book/300_architecture/uuid_conversion_system.md b/book/300_architecture/uuid_conversion_system.md index c3f408b..4d9a1e0 100644 --- a/book/300_architecture/uuid_conversion_system.md +++ b/book/300_architecture/uuid_conversion_system.md @@ -1,8 +1,10 @@ # UUID 변환 시스템 아키텍처 -## 작성일: 2025-08-21 (수정: 2025-08-28) +## 작성일: 2025-08-21 (수정: 2026-03-27) ## 작성자: Claude (51123 서버 관리자) +**상위 SSOT**: [coding-principles.md — 식별자·검증 계약](../../../../0_VALUE/20_Governance/coding-principles.md) (워크스페이스 기준 상대 경로) + --- ## 1. 개요 @@ -243,7 +245,34 @@ FOREIGN KEY (user_id) REFERENCES user(id); ## 7. UUID 유효성 검증 -### 7.1 검증 함수 +### 7.1 검증 정책 (생성 vs 소비) + +- **Pydantic·소비자 검증** + API·도메인 모델에서 사용자 식별자를 받을 때는 **`UUID4`가 아니라 `UUID`(버전 무관)** 를 사용한다. Slack 매핑·기타 경로에서 올 수 있는 UUID5 등도 RFC 4122 준수 유효 식별자이므로, 소비자(rb8001 등)는 **버전으로 거부하지 않는다.** + +- **생성 정책과 검증 정책의 분리** + **auth-server**가 신규 사용자에 대해 **UUID4** 를 쏘는 것은 **생성(발급) 정책**이다. 이는 소비자 측 **검증 정책**(임의 버전 UUID 허용)과 **별도 축**으로 둔다. 생성은 한 서비스에 국한하고, 검증은 전 구간에서 동일한 완화된 규칙을 쓴다. + +- **레거시 UUID5 폴백** + `email_integration.py`, `robeing-monitor` 등에서 쓰는 **UUID5 폴백**은 **auth-server 장애 시에만** 동작하는 **탈출 해치**에 해당한다. 이때 생성되는 값도 **유효한 UUID** 이므로, 소비자가 「UUID4만 허용」 등으로 **거부하면 안 된다.** + +- **예약어와 `user_id`** + 문자열 예약어 **`system`**, **`external_service`** 는 **`user_id`에 넣지 않는다.** 시스템/외부 주체 구분은 **별도 `actor`(또는 동등한) 필드**로 표현한다. `user_id`는 항상 UUID(문자열 표현 포함) 계약을 유지한다. + +### 7.2 Pydantic 예시 (버전 무관 UUID) + +```python +from uuid import UUID + +from pydantic import BaseModel, Field + + +class UserScopedRequest(BaseModel): + """소비자 검증: UUID4 전용이 아닌 표준 UUID 수용.""" + user_id: UUID = Field(..., description="RFC 4122 UUID, 버전 무관") +``` + +### 7.3 검증 함수 ```python import re