From 17e2589112c7304e3b6f7582b97d720425ea6fae Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Wed, 20 Aug 2025 11:17:47 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EC=9D=B8=EC=A6=9D=20=EB=B0=8F=20?=
 =?UTF-8?q?=EB=A1=9C=EA=B7=B8=EC=9D=B8=20=EC=8B=9C=EC=8A=A4=ED=85=9C=20?=
 =?UTF-8?q?=EC=8B=9C=ED=80=80=EC=8A=A4=20=EB=8B=A4=EC=9D=B4=EC=96=B4?=
 =?UTF-8?q?=EA=B7=B8=EB=9E=A8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Google OAuth 로그인 플로우 (신규/기존 사용자)
- Slack OAuth 로그인 플로우
- JWT 토큰 검증 프로세스
- UUID 생성 규칙 및 사용자 관리
- 프론트엔드 상태 관리
- 보안 고려사항 정리

위치: /300_architecture/sequences/auth_login_sequences.md
---
 .../sequences/auth_login_sequences.md         | 298 ++++++++++++++++++
 1 file changed, 298 insertions(+)
 create mode 100644 300_architecture/sequences/auth_login_sequences.md

diff --git a/300_architecture/sequences/auth_login_sequences.md b/300_architecture/sequences/auth_login_sequences.md
new file mode 100644
index 0000000..c1381ee
--- /dev/null
+++ b/300_architecture/sequences/auth_login_sequences.md
@@ -0,0 +1,298 @@
+# 인증 및 로그인 시스템 시퀀스 다이어그램
+
+## 작성일: 2025-08-20
+## 작성자: Claude (51123 서버 관리자)
+## 상태: 초안
+
+---
+
+## 목차
+1. [Google OAuth 로그인](#1-google-oauth-로그인)
+2. [Slack OAuth 로그인](#2-slack-oauth-로그인)
+3. [JWT 토큰 검증](#3-jwt-토큰-검증)
+4. [사용자 생성 및 UUID 관리](#4-사용자-생성-및-uuid-관리)
+
+---
+
+## 1. Google OAuth 로그인
+
+### 1.1 신규 사용자 로그인 플로우
+
+```mermaid
+sequenceDiagram
+    participant User as 사용자
+    participant Front as 프론트엔드
+    participant Auth as auth-server(9000)
+    participant Redis as Redis
+    participant Google as Google OAuth
+    participant DB as PostgreSQL
+
+    User->>Front: 로그인 버튼 클릭
+    Front->>Front: window.location.href 변경
+    Front->>Auth: GET /auth/gmail/login
+    
+    Auth->>Auth: state 생성 (랜덤)
+    Auth->>Auth: OAuth URL 생성
+    Note over Auth: scopes: openid, email, profile
+    Auth-->>Front: 302 Redirect to Google
+    
+    Front->>Google: 브라우저 리다이렉트
+    User->>Google: Google 계정 로그인
+    User->>Google: 권한 승인
+    
+    Google->>Auth: GET /auth/gmail/callback
+    Note over Auth: code, state 파라미터
+    
+    Auth->>Google: POST /oauth2/token
+    Note over Auth: 인증 코드 → 액세스 토큰
+    Google-->>Auth: access_token, refresh_token
+    
+    Auth->>Google: GET /oauth2/v2/userinfo
+    Google-->>Auth: email, name, picture
+    
+    Auth->>DB: SELECT * FROM users WHERE email=?
+    DB-->>Auth: 사용자 없음
+    
+    Auth->>Auth: UUID 생성 (uuid.uuid4())
+    Auth->>DB: INSERT INTO users
+    Note over DB: id(UUID), email, name, picture
+    
+    Auth->>Auth: JWT 토큰 생성
+    Note over Auth: user_id, email, exp
+    
+    Auth->>Redis: 임시 코드 저장 (60초 TTL)
+    Note over Redis: code → JWT token
+    
+    Auth-->>Front: 302 Redirect
+    Note over Auth: /#auth={code}
+    
+    Front->>Front: Fragment URL 파싱
+    Front->>Auth: POST /auth/verify
+    Note over Front: {code: "임시코드"}
+    
+    Auth->>Redis: GET 및 DEL (atomic)
+    Redis-->>Auth: JWT token
+    
+    Auth-->>Front: {token: "JWT", user: {...}}
+    Front->>Front: localStorage 저장
+    Front->>Front: 상태 업데이트 & 새로고침
+```
+
+### 1.2 기존 사용자 로그인 플로우
+
+```mermaid
+sequenceDiagram
+    participant User as 사용자
+    participant Front as 프론트엔드  
+    participant Auth as auth-server(9000)
+    participant Redis as Redis
+    participant Google as Google OAuth
+    participant DB as PostgreSQL
+
+    User->>Front: 로그인 버튼 클릭
+    Front->>Auth: GET /auth/gmail/login
+    
+    Note over Auth,Google: OAuth 플로우 (1.1과 동일)
+    
+    Auth->>DB: SELECT * FROM users WHERE email=?
+    DB-->>Auth: 사용자 정보 (기존 UUID)
+    
+    Auth->>DB: UPDATE users SET last_login=NOW()
+    
+    Auth->>Auth: JWT 토큰 생성
+    Note over Auth: 기존 user_id(UUID) 사용
+    
+    Note over Auth,Front: 토큰 전달 (1.1과 동일)
+```
+
+---
+
+## 2. Slack OAuth 로그인
+
+### 2.1 Slack 워크스페이스 연동
+
+```mermaid
+sequenceDiagram
+    participant User as 사용자
+    participant Slack as Slack App
+    participant Auth as auth-server(9000)
+    participant DB as PostgreSQL
+    participant SlackAPI as Slack API
+
+    User->>Slack: /robing-login 명령
+    Slack->>Auth: POST /auth/slack/command
+    Note over Auth: user_id, team_id, response_url
+    
+    Auth->>Auth: OAuth URL 생성
+    Auth-->>Slack: 로그인 링크 메시지
+    
+    User->>Slack: 링크 클릭
+    Slack->>Auth: GET /auth/slack/login
+    
+    Auth->>Auth: state 생성 (user_id 포함)
+    Auth-->>Slack: 302 Redirect to Slack OAuth
+    
+    User->>SlackAPI: Slack 권한 승인
+    SlackAPI->>Auth: GET /auth/slack/callback
+    
+    Auth->>SlackAPI: POST /oauth.v2.access
+    SlackAPI-->>Auth: access_token, user info
+    
+    Auth->>DB: SELECT * FROM users WHERE email=?
+    alt 신규 사용자
+        Auth->>Auth: UUID 생성
+        Auth->>DB: INSERT INTO users
+    else 기존 사용자
+        Auth->>DB: UPDATE users
+    end
+    
+    Auth->>DB: INSERT INTO slack_users
+    Note over DB: slack_user_id, user_id(UUID), team_id
+    
+    Auth-->>Slack: 로그인 성공 메시지
+```
+
+---
+
+## 3. JWT 토큰 검증
+
+### 3.1 API 요청 시 토큰 검증
+
+```mermaid
+sequenceDiagram
+    participant Front as 프론트엔드
+    participant Gateway as Gateway(8100)
+    participant Auth as auth-server(9000)
+    participant Service as 로빙 서비스
+
+    Front->>Gateway: API 요청
+    Note over Gateway: Authorization: Bearer {JWT}
+    
+    Gateway->>Gateway: JWT 서명 검증
+    Gateway->>Gateway: 만료 시간 확인
+    
+    alt 토큰 유효
+        Gateway->>Gateway: user_id 추출
+        Gateway->>Service: 요청 전달
+        Note over Service: X-User-Id: {UUID}
+        Service-->>Gateway: 응답
+        Gateway-->>Front: 응답
+    else 토큰 만료/무효
+        Gateway-->>Front: 401 Unauthorized
+        Front->>Front: 로그인 페이지로
+    end
+```
+
+---
+
+## 4. 사용자 생성 및 UUID 관리
+
+### 4.1 UUID 생성 규칙
+
+```mermaid
+flowchart TD
+    A[사용자 로그인/가입] --> B{사용자 타입}
+    
+    B -->|OAuth 로그인| C[이메일로 DB 조회]
+    C --> D{기존 사용자?}
+    D -->|Yes| E[기존 UUID 사용]
+    D -->|No| F[uuid.uuid4() 생성]
+    
+    B -->|테스트 사용자| G[수동 UUID 할당]
+    G --> H[하드코딩 UUID<br/>aaaaaaaa-aaaa...]
+    
+    B -->|시스템 사용자| I[예약 UUID 사용]
+    
+    F --> J[DB 저장]
+    E --> K[JWT 토큰 생성]
+    H --> J
+    J --> K
+```
+
+### 4.2 사용자 테이블 구조
+
+```sql
+-- users 테이블
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    name VARCHAR(255),
+    username VARCHAR(50) UNIQUE,  -- happybell80, test_user 등
+    picture TEXT,
+    oauth_provider VARCHAR(50),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    last_login TIMESTAMP
+);
+
+-- 예시 데이터
+-- 테스트 사용자 (하드코딩 UUID)
+INSERT INTO users VALUES 
+    ('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', 'goeun2dc@gmail.com', '김종태', 'happybell80'),
+    ('bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb', '0914eagle@gmail.com', '전희재', 'eagle0914'),
+    ('dddddddd-dddd-dddd-dddd-dddddddddddd', 'test@example.com', 'Test User', 'test_user');
+
+-- 실제 사용자 (자동 생성 UUID)
+-- OAuth 로그인 시 uuid.uuid4()로 생성
+```
+
+---
+
+## 5. 로그인 상태 관리
+
+### 5.1 프론트엔드 상태 관리
+
+```mermaid
+stateDiagram-v2
+    [*] --> 비로그인
+    
+    비로그인 --> 로그인중: 로그인 버튼 클릭
+    로그인중 --> OAuth인증: OAuth 리다이렉트
+    OAuth인증 --> 코드교환: 콜백 수신
+    코드교환 --> 토큰저장: JWT 수신
+    토큰저장 --> 로그인완료: localStorage 저장
+    
+    로그인완료 --> 비로그인: 로그아웃
+    로그인완료 --> 토큰갱신: 토큰 만료
+    토큰갱신 --> 로그인완료: 갱신 성공
+    토큰갱신 --> 비로그인: 갱신 실패
+```
+
+---
+
+## 6. 보안 고려사항
+
+### 6.1 토큰 보안
+
+1. **JWT 토큰**
+   - HttpOnly 쿠키 사용 권장 (현재는 localStorage)
+   - 짧은 만료 시간 (현재 24시간)
+   - 서명 검증 필수
+
+2. **임시 코드**
+   - Redis 60초 TTL
+   - 1회용 (atomic getdel)
+   - Fragment URL로 서버 로그 방지
+
+3. **OAuth state**
+   - CSRF 방지
+   - 랜덤 생성
+   - 세션별 유니크
+
+### 6.2 사용자 식별
+
+```yaml
+식별 체계:
+  Primary Key: UUID (36자)
+  Unique Keys:
+    - email (OAuth provider에서 제공)
+    - username (사용자 정의, optional)
+  
+관계:
+  - users.id (UUID) ← gmail_tokens.user_id
+  - users.id (UUID) ← slack_users.user_id
+  - users.id (UUID) ← robeing_assignments.user_id
+```
+
+---
+
+## 문서 끝
\ No newline at end of file