From de4d319aeec9504453636a7d57eda6c2274cf79d Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Tue, 19 Aug 2025 09:09:03 +0900
Subject: [PATCH] =?UTF-8?q?=EC=8B=9C=ED=80=80=EC=8A=A4=20=EB=8B=A4?=
 =?UTF-8?q?=EC=9D=B4=EC=96=B4=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

- 아이템 장착 플로우
- 이메일 발송 플로우
- 재인증 플로우
- mermaid 형식으로 서비스 간 통신 흐름 시각화
---
 .../250819_gmail_item_implementation_plan.md  | 92 ++++++++++++++++++-
 1 file changed, 91 insertions(+), 1 deletion(-)

diff --git a/plans/250819_gmail_item_implementation_plan.md b/plans/250819_gmail_item_implementation_plan.md
index c587ade..cbe9d0a 100644
--- a/plans/250819_gmail_item_implementation_plan.md
+++ b/plans/250819_gmail_item_implementation_plan.md
@@ -103,7 +103,97 @@ PostgreSQL (gmail_tokens 테이블)
 
 ---
 
-## 4. API 설계
+## 4. 시퀀스 다이어그램
+
+### 아이템 장착 플로우
+```mermaid
+sequenceDiagram
+    participant User as 사용자
+    participant Front as 프론트엔드
+    participant Gateway as Gateway(8100)
+    participant Monitor as robeing-monitor(9024)
+    participant RB as rb8001
+    participant DB as PostgreSQL
+
+    User->>Front: Gmail 아이템 장착 클릭
+    Front->>Gateway: POST /api/items/gmail/:userId/equip
+    Gateway->>Gateway: JWT 토큰 검증
+    Gateway->>Monitor: 장착 요청 전달
+    Monitor->>DB: robeing_stats 조회 (레벨 체크)
+    DB-->>Monitor: 레벨 정보
+    alt 레벨 < 5
+        Monitor-->>Front: INSUFFICIENT_LEVEL
+    else 레벨 >= 5
+        Monitor->>DB: gmail_tokens 업데이트
+        Note over DB: is_equipped=true<br/>equipped_to=robeing_id
+        Monitor->>DB: gmail_audit_logs 기록
+        Monitor-->>RB: 장착 완료 알림
+        Monitor-->>Front: 장착 성공
+    end
+```
+
+### 이메일 발송 플로우
+```mermaid
+sequenceDiagram
+    participant User as 사용자  
+    participant Front as 프론트엔드
+    participant RB as rb8001
+    participant Monitor as robeing-monitor(9024)
+    participant Skill as skill-email(8501)
+    participant DB as PostgreSQL
+    participant Gmail as Gmail API
+
+    User->>Front: "이메일 보내줘" 요청
+    Front->>RB: 메시지 전달
+    RB->>Monitor: Gmail 아이템 장착 확인
+    Monitor->>DB: gmail_tokens 조회
+    DB-->>Monitor: 장착 상태 & 토큰 정보
+    
+    alt 아이템 미장착
+        Monitor-->>RB: ITEM_NOT_EQUIPPED
+        RB-->>Front: "Gmail 아이템을 먼저 장착해주세요"
+    else 아이템 장착됨
+        Monitor-->>RB: 장착 확인
+        RB->>Skill: 이메일 발송 요청
+        Skill->>DB: 토큰 조회
+        DB-->>Skill: access_token
+        Skill->>Gmail: API 호출
+        Gmail-->>Skill: 발송 결과
+        Skill-->>RB: 성공/실패
+        RB-->>Front: 결과 메시지
+    end
+```
+
+### 재인증 플로우
+```mermaid
+sequenceDiagram
+    participant User as 사용자
+    participant Front as 프론트엔드
+    participant Monitor as robeing-monitor(9024)
+    participant Auth as auth-server(9000)
+    participant Google as Google OAuth
+    participant DB as PostgreSQL
+
+    Note over Front: 토큰 만료 상태 표시
+    User->>Front: 재인증 버튼 클릭
+    Front->>Monitor: POST /api/items/gmail/:userId/reauth
+    Monitor->>Auth: OAuth URL 요청
+    Auth->>Auth: state 생성
+    Auth-->>Monitor: OAuth URL
+    Monitor-->>Front: 리다이렉트 URL
+    Front->>Google: OAuth 페이지로 이동
+    User->>Google: 로그인 & 권한 승인
+    Google->>Auth: 인증 코드 콜백
+    Auth->>Google: 토큰 교환
+    Google-->>Auth: access_token, refresh_token
+    Auth->>DB: gmail_tokens 업데이트
+    Auth-->>Front: 인증 완료
+    Front->>Front: 아이템 상태 갱신
+```
+
+---
+
+## 5. API 설계
 
 ### robeing-monitor (9024) 엔드포인트