Merge pull request #250 from JECT-Study/develop

release: develop → main

Author: tlarbals824

docs/spec/chat-reactions-replies-badge-api-improvement.md

@@ -0,0 +1,325 @@
+# 채팅방 API 개선안 — 선택지 배지 + 메시지 반응(이모지) + 답글
+
+> 기반: "채팅_ 투표진행중_채팅 상세_개선" 5-1 ~ 5-6 요구사항
+> 버전: 1.0
+> 대상: 회원 (투표 참여자)
+
+## 1. 요구사항 핵심 요약
+
+### 5-1 선택지 배지 (본인)
+- 채팅방 진입 시 **본인이 선택한 A/B 배지**가 Chat Input **위 영역**에 **상시 표시**
+- 본인 선택 변경 시 배지 정보 **실시간 반영**
+- A/B 선택지에 따라 시각적으로 다르게 표시
+
+### 5-2 ~ 5-4 이모지 반응 (👍 👎)
+- **자신의 메시지**에는 Context Menu 호출 불가 (서버도 방어)
+- 말풍선 **0.5초 길게 누르기** → Context Menu (배경 dim)
+  - 메뉴 항목: 👍 , 👎 , 답장
+- 반응
+  - 동일 이모지 복수 사용자 → **누적 카운트**
+  - 99개 이상 → `99+`
+  - **본인이 누른 이모지 다시 누르면 취소**
+- 메뉴 자동 닫힘: 반응 선택 또는 "답장" 선택 시
+- "답장" 선택 → 메뉴 닫히고 **텍스트 입력 키패드 즉시 오픈**
+
+### 5-5 ~ 5-6 답글 (Reply)
+- 메시지 길게 누르기 → 키패드 즉시 호출
+- 답글 작성 중 **원문 인용 박스** 상단 노출
+  - X 버튼 → 답글 작성 취소
+  - 인용 영역 선택 → 원문 메시지 위치로 스크롤 이동
+- **답글 메시지** 표시 규칙
+  - 메시지 상단에 **원문 내용을 회색 + 말줄임**으로 표시
+
+---
+
+## 2. 데이터 모델 변경
+
+### 2.1 ChatMessage 확장 (답글 지원)
+
+```sql
+ALTER TABLE chat_message
+    ADD COLUMN parent_message_id BIGINT NULL
+        REFERENCES chat_message(id) ON DELETE SET NULL;
+
+CREATE INDEX idx_chat_message_parent ON chat_message (parent_message_id);
+```
+
+- `parent_message_id` = 답글 대상 원문 메시지 ID (null = 일반 메시지)
+
+### 2.2 신규 테이블: chat_message_reaction
+
+```sql
+CREATE TABLE chat_message_reaction (
+    id          BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    message_id  BIGINT NOT NULL REFERENCES chat_message(id) ON DELETE CASCADE,
+    user_id     BIGINT NOT NULL REFERENCES users(id),
+    emoji       VARCHAR(20) NOT NULL,           -- THUMBS_UP | THUMBS_DOWN
+    created_at  TIMESTAMP NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMP NOT NULL DEFAULT now(),
+
+    CONSTRAINT uq_chat_reaction UNIQUE (message_id, user_id)
+);
+
+CREATE INDEX idx_chat_reaction_msg ON chat_message_reaction (message_id);
+CREATE INDEX idx_chat_reaction_user ON chat_message_reaction (user_id);
+```
+
+**특징**
+- 회원 전용 (anonymous 없음) — 채팅은 투표 참여 회원만 가능
+- 1인 1반응 (동일 메시지). 다른 이모지 선택 시 row update, null 전송 시 삭제
+
+### 2.3 신규 Enum (chat/domain)
+
+```java
+package com.ject.vs.chat.domain;
+
+public enum ChatReactionType {
+    THUMBS_UP,    // 👍
+    THUMBS_DOWN   // 👎
+}
+```
+
+---
+
+## 3. 기존 API 변경 사항
+
+### 3.1 GET `/api/chats/{voteId}` — 채팅방 헤더 (배지 정보 제공)
+
+**기존 응답에 추가**
+
+```json
+{
+  "voteId": 1,
+  "title": "...",
+  "status": "ONGOING",
+  "participantCount": 25,
+  "optionA": "...",
+  "optionB": "...",
+  "endAt": "...",
+  "myVoteOption": "A"          // ★ 신규: "A" | "B" | null
+}
+```
+
+**변경 대상**
+- `ChatRoomResult` 에 `VoteOptionCode myVoteOption` 추가
+- `ChatRoomResponse` 에 동일 필드 + `@Schema`
+- `ChatService.getChatRoom(...)` 시그니처 변경 또는 내부에서 userId 사용
+  - 현재 컨트롤러가 userId를 받지만 getChatRoom에 전달 안 함 → 수정 필요
+- 구현: `voteQueryUseCase.findSelectedOptionCode(voteId, userId).orElse(null)`
+
+**5-1 배지 대응**: 이 응답으로 진입 시점 배지 렌더링. 선택 변경은 3.4 참고.
+
+### 3.2 POST `/api/chats/{voteId}/messages` — 메시지 전송 (답글 지원)
+
+**Request 변경 (하위 호환)**
+
+```json
+{
+  "content": "이것도 좋은 선택 같아요",
+  "replyToMessageId": 1234     // optional. 없으면 일반 메시지
+}
+```
+
+**변경 대상**
+- `SendMessageRequest`
+- `SendMessageCommand`
+- `ChatService.sendMessage(...)`
+
+**서버 처리**
+- `replyToMessageId` 가 있으면:
+  - 동일 `voteId` 소속 메시지인지 검증 (아니면 404 또는 400)
+  - parent 메시지 내용 + 작성자 닉네임 스냅샷 준비 (preview 생성)
+- 저장 시 `ChatMessage.parentMessageId = replyToMessageId`
+
+**응답** (`MessageResponse`)
+- 새 메시지에도 `replyTo` 정보 포함 (아래 3.3 참고)
+
+### 3.3 GET `/api/chats/{voteId}/messages` — 메시지 목록 (reply + reaction 포함)
+
+**각 메시지 응답 확장**
+
+```json
+{
+  "messageId": 1280,
+  "content": "답글 내용입니다",
+  "sentAt": "...",
+  "senderNickname": "승부사",
+  "senderProfileIcon": "GREEN",
+  "senderVoteOption": "B",
+  "isMine": true,
+
+  "replyTo": {                       // ★ 신규 (답글인 경우에만)
+    "messageId": 1275,
+    "senderNickname": "원작성자",
+    "contentPreview": "원문 메시지 앞부분을 잘라서 보여줍니다..."
+  },
+
+  "reactions": {                     // ★ 신규
+    "THUMBS_UP": 14,
+    "THUMBS_DOWN": 2
+  },
+  "myReaction": "THUMBS_UP"          // ★ 신규 (내 반응, 없으면 null)
+}
+```
+
+**변경 대상**
+- `MessageResult` record
+- `MessageResponse` record + from()
+- `MessagePageResponse`
+- `ChatService.getMessages(...)` 내부 enrichment 로직 대폭 수정
+
+**Enrichment 구현 전략 (성능)**
+- 페이지 메시지 ID 목록 추출
+- parentMessageId 목록 별도 수집 → `chatMessageRepository.findAllById(...)` + User 정보
+- reaction: 
+  ```java
+  // ChatMessageReactionRepository
+  List<ReactionCount> countByMessageIds(List<Long> messageIds);
+  Optional<ChatReactionType> findMyReaction(Long messageId, Long userId);
+  ```
+- Map 으로 매핑 후 MessageResult 생성
+
+**contentPreview**
+- 부모 메시지의 **전체 내용**을 그대로 내려줍니다.
+- 말줄임(ellipsis) 처리는 프론트엔드에서 담당합니다. (뷰의 관심사)
+
+---
+
+## 4. 신규 API
+
+### 4.1 메시지 반응 추가/변경/취소
+
+**PUT** `/api/chats/{voteId}/messages/{messageId}/reactions`
+
+**Request**
+```json
+{ "emoji": "THUMBS_UP" }     // "THUMBS_UP" | "THUMBS_DOWN" | null
+```
+
+- `emoji` = 값 → 해당 반응 설정 (기존 반응이 있으면 교체)
+- `emoji` = `null` → 반응 취소
+
+**Response** (204 No Content 대신 200 추천)
+```json
+{
+  "messageId": 1280,
+  "reactions": {
+    "THUMBS_UP": 15,
+    "THUMBS_DOWN": 2
+  },
+  "myReaction": "THUMBS_UP"   // null 가능
+}
+```
+
+**에러**
+- `403` : 자신의 메시지에 반응 시도 (`ChatForbiddenException` 재사용 또는 신규)
+- `403` : 투표 참여자가 아님
+- `404` : 메시지 또는 voteId 불일치
+
+**구현 위치**
+- 신규: `ChatReactionCommandUseCase` (권장) 또는 `ChatCommandUseCase` 확장
+- `ChatService.react(...)`
+- `ChatMessageReactionRepository`
+
+**트랜잭션 후**
+- `ChatReactionUpdatedEvent` 발행 → 리스너에서 WS 브로드캐스트
+
+---
+
+## 5. WebSocket (STOMP) 변경
+
+### 5.1 기존 메시지 브로드캐스트 (`/topic/chat/{voteId}`)
+
+기존 `MessageResult` 페이로드를 **3.3** 확장 형태로 전송 (replyTo + reactions 포함, `myReaction`은 항상 `null`).
+
+### 5.2 반응 업데이트 브로드캐스트 (신규)
+
+같은 토픽으로 다음 형태 전송:
+
+```json
+{
+  "event": "REACTION_UPDATED",
+  "messageId": 1280,
+  "reactions": {
+    "THUMBS_UP": 15,
+    "THUMBS_DOWN": 2
+  }
+}
+```
+
+클라이언트는 수신 즉시 해당 메시지의 reaction counts 를 갱신.
+
+(개인 `myReaction`은 PUT 응답으로 이미 확정)
+
+### 5.3 배지 실시간 업데이트 (권장)
+
+**선택지 변경은 주로 Vote participate API에서 발생**하므로:
+
+- 클라이언트가 `POST/PUT` participate 성공 시 응답의 `selectedOptionId` → `A/B` 변환 후 **로컬 배지 즉시 갱신** (가장 단순하고 정확)
+- 다중 탭/기기 동기화가 중요해지면 별도 개인 채널 고려:
+  - `/user/topic/chat/{voteId}/my-option`
+  - `{ "myVoteOption": "B" }`
+
+현재 단계에서는 **헤더 + 클라이언트 상태 동기화**로 5-1 요구사항 충분히 만족 가능.
+
+---
+
+## 6. 아키텍처 / 코드 변경 포인트
+
+| 위치 | 변경 내용 |
+|------|----------|
+| `chat/domain/ChatMessage.java` | `parentMessageId` 필드 + getter |
+| `chat/domain/ChatMessageRepository.java` | `findAllById(...)` (기본 제공), parent 조회용 추가 메서드 필요시 |
+| `chat/domain/` 신규 | `ChatMessageReaction.java`, `ChatMessageReactionRepository.java`, `ChatReactionType.java` |
+| `chat/port/in/dto/` | `MessageResult` 대폭 확장, `SendMessageCommand`에 `replyToMessageId` 추가, 신규 `ReactMessageCommand` 등 |
+| `chat/port/ChatService.java` | sendMessage reply 처리 + getMessages 대형 enrichment 로직 추가 + react 메서드 |
+| `chat/adapter/web/ChatController.java` + `ChatDocs.java` | 신규 반응 엔드포인트, 기존에 userId 전달 수정 |
+| `chat/adapter/web/dto/` | `MessageResponse`, `SendMessageRequest` 업데이트 |
+| `chat/adapter/event/` | `ChatMessageEventListener` : replyTo 포함 브로드캐스트 |
+| `vote/port/in/VoteQueryUseCase.java` | 기존 `findSelectedOptionCode` 재사용 (변경 없음) |
+| 신규 이벤트 | `ChatReactionUpdatedEvent` (선택) |
+
+**메서드 네이밍 컨벤션 준수** (프로젝트 규칙)
+- `findAll...`, `findBy...`, `countBy...`, `existsBy...` 등 사용
+
+---
+
+## 7. 검증 / 엣지 케이스
+
+- 자신의 메시지에 반응 → 거부
+- 삭제된 parent에 답글 → `replyTo.contentPreview = "(삭제된 메시지)"` (id는 유지하여 스크롤 이동 지원)
+- replyTo 메시지가 다른 vote → 400
+- 반응 99+ → 서버는 정확한 숫자 반환, 클라이언트에서 `count > 99 ? "99+" : count`
+- 시스템 메시지 (senderId=0) → 반응/답글 불가
+- 투표 종료 후에도 과거 메시지 반응/조회는 허용? (기존 정책 유지. 별도 확인 필요)
+- 동시에 여러 반응 race → UNIQUE 제약 + upsert 로 처리
+
+---
+
+## 8. 구현 우선순위 추천
+
+1. **DB + 도메인** : ChatMessage parent + ChatMessageReaction 테이블/엔티티
+2. **메시지 전송 + 목록** : replyTo 기능 먼저 (5-5, 5-6)
+3. **채팅방 헤더** : myVoteOption 추가 (5-1)
+4. **반응 기능** : PUT API + 목록 enrichment + WS (5-2~5-4)
+5. **문서화 + 테스트** + 클라이언트 연동 확인
+6. **(선택)** 다중 기기 배지 동기화를 위한 WS 이벤트
+
+---
+
+## 9. OpenAPI / 문서 업데이트
+
+- `ChatDocs.java` 에 신규 Operation 추가
+- `swagger.json` 재생성 또는 수동 반영
+- 기존 `docs/spec/2026-04-26-chat-api-spec.md` 에 "v2 개선" 섹션 또는 별도 이 문서 링크
+
+---
+
+## 10. 클라이언트 협업 포인트
+
+- Context Menu / long-press 는 **클라이언트 전담**
+- 99+ formatting, 말줄임, X 버튼, 인용 박스 클릭 시 scroll-to-id → 클라이언트
+- 답글 작성 중 원문 quote box는 `replyTo` 데이터로 렌더
+- 배지 위치는 항상 Input 위 고정 (채팅방 진입 + myVoteOption 기준)
+
+이 개선안을 적용하면 5-1~5-6 요구사항을 모두 만족하면서 기존 채팅 API와 호환성을 유지할 수 있습니다.