From 5c17544c87dd96d5106b5b666f5e4f6894f03175 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Wed, 27 Aug 2025 15:55:14 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20UUID=20vs=20username=20=ED=98=BC?=
 =?UTF-8?q?=EC=9A=A9=20=EB=AC=B8=EC=A0=9C=20-=20CRITICAL=20=EC=8B=9C?=
 =?UTF-8?q?=EC=8A=A4=ED=85=9C=20ID=20=EC=B2=B4=EA=B3=84=20=ED=98=BC?=
 =?UTF-8?q?=EB=9E=80=20=EB=AC=B8=EC=84=9C=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../250827_UUID_username_혼용_CRITICAL.md   | 200 ++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 troubleshooting/250827_UUID_username_혼용_CRITICAL.md

diff --git a/troubleshooting/250827_UUID_username_혼용_CRITICAL.md b/troubleshooting/250827_UUID_username_혼용_CRITICAL.md
new file mode 100644
index 0000000..c47d248
--- /dev/null
+++ b/troubleshooting/250827_UUID_username_혼용_CRITICAL.md
@@ -0,0 +1,200 @@
+# UUID vs Username 혼용 - CRITICAL 시스템 전체 ID 체계 혼란
+
+## 작성일: 2025-08-27
+## 작성자: 51123 서버 관리자
+## 상태: 🔴 CRITICAL - 즉시 해결 필요
+## 영향 범위: 전체 시스템 (Auth, Gateway, Frontend, rb8001, DB)
+## 위험 수준: 매우 높음
+
+---
+
+## 1. 문제 요약
+
+### 🚨 핵심 문제
+**시스템 전체가 UUID와 username을 구분하지 못해 데이터 무결성 파괴**
+- JWT `sub` 클레임에 UUID 대신 username 저장
+- Frontend가 하드코딩된 문자열 사용 ('test_user', 'default_user')
+- DB에 UUID 대신 username/slack_id 저장되어 외래키 제약 위반
+
+### 실제 사례
+- User: happybell80
+- UUID: 1e16e9d5-59f3-54da-a661-8abeabff4230
+- JWT sub: "happybell80" (UUID 아님)
+- ChromaDB user_id: "happybell80" (UUID 아님)
+- conversation_logs: user_id NULL (UUID 타입이라 username 저장 실패)
+
+---
+
+## 2. 영향 분석
+
+### 2.1 auth-server (51123)
+```python
+# /home/admin/auth-server/app/providers/gmail.py:208-209
+jwt_token = create_access_token(data={
+    "sub": username,  # 🔴 UUID 대신 username
+    "email": user_email,
+    "name": user_name,
+    "username": username,
+})
+```
+**문제**: JWT 표준에서 `sub`는 unique identifier여야 하는데 username 사용
+
+### 2.2 robeing-gateway (51123)
+```python
+# /home/admin/robeing-gateway/app/main.py:58
+username = payload.get("sub") or payload.get("username")
+# username을 user_id처럼 사용
+```
+**문제**: username을 UUID로 변환 시도하지만 실패 시 그대로 전달
+
+### 2.3 rb8001 (51124)
+```python
+# auth.py:36
+user_id = payload.get("sub")  # username을 user_id로 착각
+# ChromaDB에 username으로 저장
+metadata={"user_id": user_id}  # 실제로는 username
+```
+**문제**: ChromaDB에서 사용자 구분 불가능 (UUID가 아닌 username)
+
+### 2.4 Frontend
+```typescript
+// robeing-api.ts:31, 157, 223, 262, 308, 354, 402, 448, 495
+userId: string = 'test_user'  // 하드코딩
+localStorage.getItem('user_id') || 'default_user'  // 폴백
+```
+**문제**: 실제 UUID 대신 임의 문자열 사용
+
+### 2.5 Database
+```sql
+-- conversation_logs 테이블
+user_id UUID  -- UUID 타입 요구
+slack_user_id VARCHAR(100)  -- username이 여기 저장됨
+
+-- 실제 데이터
+user_id: NULL  -- UUID 아니라서 저장 실패
+slack_user_id: 'happybell80'  -- 우회 저장
+```
+
+---
+
+## 3. 근본 원인
+
+### 3.1 설계 문제
+- user_id, username, slack_id 개념 미구분
+- UUID 사용 표준 부재
+- 타입 검증 없는 문자열 전달
+
+### 3.2 구현 문제
+- auth-server: JWT `sub`에 username 사용
+- Gateway: username → UUID 변환 실패 시 방치
+- Frontend: localStorage에 UUID 저장 안함
+- rb8001: JWT `sub`를 무조건 user_id로 간주
+
+---
+
+## 4. 해결 방안
+
+### 4.1 긴급 조치 (Phase 1)
+
+#### auth-server 수정
+```python
+# gmail.py:208 수정 필요
+jwt_token = create_access_token(data={
+    "sub": str(user.id),  # UUID 사용
+    "username": username,  # username은 별도 필드
+    "email": user_email,
+    "name": user_name,
+})
+```
+
+#### Gateway username → UUID 매핑
+```python
+# 이미 구현되어 있음 (get_user_by_username)
+# 하지만 JWT sub가 UUID면 불필요
+```
+
+### 4.2 중기 개선 (Phase 2)
+
+#### Frontend localStorage 정리
+```typescript
+// JWT 디코딩 후
+const payload = jwt_decode(token);
+localStorage.setItem('user_id', payload.sub);  // UUID
+localStorage.setItem('username', payload.username);
+```
+
+#### rb8001 JWT 처리 수정
+```python
+# auth.py 수정
+user_uuid = payload.get("sub")  # UUID
+username = payload.get("username")  # username
+```
+
+### 4.3 장기 개선 (Phase 3)
+- 전체 시스템 ID 타입 표준화
+- UUID 전용 타입 클래스 생성
+- 타입 검증 미들웨어 추가
+
+---
+
+## 5. 테스트 시나리오
+
+### 5.1 현재 상태 확인
+```bash
+# JWT payload 확인
+curl -X POST http://localhost:9000/auth/gmail/login
+
+# DB 확인
+SELECT id, username FROM users WHERE username='happybell80';
+# UUID: 1e16e9d5-59f3-54da-a661-8abeabff4230
+
+# conversation_logs 확인  
+SELECT user_id, slack_user_id FROM conversation_logs;
+# user_id: NULL, slack_user_id: 'happybell80'
+```
+
+### 5.2 수정 후 검증
+- JWT `sub` 필드가 UUID 형식 (36자)
+- conversation_logs.user_id에 UUID 저장
+- ChromaDB metadata.user_id가 UUID
+
+---
+
+## 6. 영향도 및 우선순위
+
+| 컴포넌트 | 영향도 | 우선순위 | 담당 |
+|---------|-------|---------|-----|
+| auth-server JWT | 🔴 극심 | 1 | 로컬 개발자 |
+| Frontend localStorage | 🔴 극심 | 2 | 로컬 개발자 |
+| rb8001 JWT 처리 | 🟡 높음 | 3 | 로컬 개발자 |
+| Gateway 매핑 | 🟢 중간 | 4 | 이미 구현됨 |
+
+---
+
+## 7. 관련 문서
+
+- [ID 체계 정리 (250826)](./250826_id_체계_정리_및_conversation_logs_문제_해결.md)
+- [JWT 인증 구현 (250827)](./250827_JWT_인증_구현_COMPLETED.md)
+- [Slack ID 표준화 (250826)](./250826_slack_id_column_standardization.md)
+
+---
+
+## 8. 결론
+
+**현재 시스템은 UUID와 username을 구분하지 못해 데이터 무결성이 깨진 상태**
+
+### 즉시 필요한 조치
+1. auth-server: JWT `sub`에 UUID 사용
+2. Frontend: localStorage에 UUID 저장
+3. rb8001: UUID와 username 구분 처리
+
+### 예상 작업 시간
+- auth-server 수정: 30분
+- Frontend 수정: 1시간  
+- rb8001 수정: 30분
+- 테스트 및 검증: 1시간
+- **총 예상: 3시간**
+
+---
+
+*작성 완료: 2025-08-27 15:45*
\ No newline at end of file