Merge pull request 'docs: UUID 검증 정책 + 파라미터 계약 + 백엔드 원칙' (#1) from docs/uuid-validation-policy into main

This commit is contained in:
happybell80 2026-03-27 12:35:41 +09:00
commit 5db4187cf8

View File

@ -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