docs(architecture): UUID 검증 정책(소비자 UUID, 폴백, 예약어) 및 coding-principles SSOT 링크
- 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
This commit is contained in:
parent
bb72ac44ea
commit
575c1a8ad2
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user