feat(item/user): 룰렛 기능 및 관리자 API 이관 통합

.dockerignore

@@ -8,6 +8,26 @@
 .gradle
 build
 **/build
+
+# Gradle 빌드 설정을 이미지 빌드 컨텍스트에서 뺀다.
+#
+# 이 파일의 값(병렬 실행, 힙 2g)은 CI 러너와 개발 PC 를 상대로 잡은 것이다.
+# 그런데 Dockerfile 의 빌드 스테이지는 컨텍스트 루트에서 ./gradlew bootJar 를
+# 돌리므로, 그냥 두면 그 값이 여기까지 따라 들어온다.
+#
+# 문제는 이 빌드 스테이지를 쓰는 곳이 어디냐다. CI 배포는 Dockerfile.ci 로
+# 미리 만든 jar 만 복사하니 Gradle 을 돌리지 않는다. 이 스테이지가 실제로
+# 도는 경로는 docker-compose.prod.yml 이 문서화한 두 번째 기동
+# ("CI 없이 급하게 올릴 때" up -d --build) 하나뿐이고, 그건 운영 EC2
+# (t3.large, 8GB) 위에서 돈다. compose 의 mem_limit 합이 7040m(6.88GiB)라
+# 여유가 1GB 남짓인데, 하필 장애 대응으로 그 경로를 탈 때 이미 떠 있는
+# 서비스 JVM 들과 메모리를 다투게 된다.
+#
+# CLAUDE.md 가 "운영 설정은 EC2 단일 호스트에 6개 JVM 이 함께 뜨는 전제로
+# 메모리 한도가 잡혀 있다"고 못박은 예산이 그것이다. 여기서는 Gradle 기본값
+# (보수적인 힙, 순차 실행)으로 빌드하게 둔다 - 이 경로에서 아껴야 할 것은
+# 빌드 시간이 아니라 메모리다.
+gradle.properties
 .idea
 .vscode
 .claude

.env.prod.example

@@ -62,6 +62,16 @@ DEFAULT_PROFILE_IMAGE_BASE_URL=https://srv.comatching.site/api/public/profile-im
 # 켜도 AuthorizationHeaderFilter 가 붙어 있어 로그인 쿠키가 있어야 열린다.
 # SWAGGER_PATH_PREFIX=
 
+# ---------- 모니터링 ----------
+# Grafana 관리자 비밀번호. SSH 터널(127.0.0.1:3001) 너머로만 닿지만
+# 익명 접근을 꺼둔 이상 계정은 있어야 한다.
+GRAFANA_ADMIN_PASSWORD=
+
+# 인프라 알림(서비스 다운·5xx·힙·디스크)의 디스코드 웹훅은 환경변수가
+# 아니라 monitoring/alertmanager/alertmanager.yml 에 넣는다 - Alertmanager 가
+# 설정 파일에서 환경변수를 확장하지 못한다. 그 파일은 .gitignore 에 있다.
+# DLT_ALERT_WEBHOOK_URL 과 반드시 다른 채널로 팔 것(아래 DLT 절 참고).
+
 # ---------- DLT 적재 알림 ----------
 # Discord 웹훅 URL(https://discord.com/api/webhooks/<id>/<token>) 또는 Slack.
 # 비우면 로그만 남는다. 이 URL 자체가 비밀값이다.

.github/workflows/claude-code-review.yml

@@ -0,0 +1,70 @@
+# PR 이 열리거나 갱신될 때 Claude 가 자동으로 코드 리뷰를 남긴다.
+#
+# 리뷰 기준은 CLAUDE.md 가 가리키는 docs/code-review-guidelines.md 한 곳에서
+# 관리한다 - 프롬프트에 기준을 복붙해 두면 워크플로와 문서가 따로 논다.
+#
+# 수동 호출(코멘트에 @claude)은 claude.yml 이 담당한다.
+name: Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+# 같은 PR 에 연속으로 푸시하면 이전 리뷰는 취소한다. synchronize 가 푸시마다
+# 발화하므로, 없으면 커밋 3개를 연달아 밀 때 리뷰를 3번 돌린다.
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      # 액션의 기본 GitHub App 인증에 필요하다.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          # API 크레딧이 아니라 Claude 구독으로 돌린다.
+          # 토큰은 `claude setup-token` 으로 만든다.
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
+          plugins: "code-review@claude-code-plugins"
+          # 두 번째 문단이 없으면 리뷰가 조용히 증발한다. 실제로 겪은 실패:
+          # 모델이 리뷰를 백그라운드 서브에이전트에 넘기고 "완료 알림을
+          # 기다리겠다"며 턴을 끝냈는데, Actions 헤드리스 실행에는 그 알림을
+          # 받을 루프가 없어 프로세스가 그대로 죽었다. 코멘트 0개로 초록불.
+          prompt: |
+            /code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}
+
+            리뷰는 이 턴 안에서 끝낸다. 서브에이전트를 백그라운드로 띄우고
+            완료 알림을 기다리지 마라 - Actions 에는 알림을 받을 루프가 없어
+            프로세스가 그대로 죽는다.
+
+            이 자동 리뷰는 diff 에 나온 코드만 본다. common-module 등
+            diff 밖의 다른 서비스로 건너가 소비 코드를 찾아 읽는 하위 호환성
+            분석은 하지 마라 - 시간이 몇 배로 늘어난다. diff 가
+            common-module 의 DTO, 서비스 간 내부 API, Kafka 이벤트 스키마를
+            건드린다면, 그 분석 대신 코멘트에 "cross-service 영향 확인이
+            필요합니다 - `@claude` 로 수동 리뷰를 요청하세요" 한 줄만 남겨라.
+          # allowedTools 는 화이트리스트다. 목록에 없는 도구는 permissionMode
+          # default + 비대화형 조합에서 그대로 거부된다.
+          # - Skill: 없으면 /code-review 스킬 본체가 로드되지 못한다. 모델은
+          #   거부당한 뒤 프롬프트에 실린 요약만 보고 즉흥적으로 움직인다.
+          # - Bash/Read/Glob/Grep: 스킬이 diff 를 읽고 코드를 뒤지는 데 쓴다.
+          # - Agent: 스킬이 리뷰어를 병렬로 나눌 때 쓴다. 백그라운드 전환은
+          #   위 프롬프트가 막는다.
+          # - mcp__github_inline_comment__*: 액션은 --allowedTools 가 이름을
+          #   대야만 인라인 코멘트용 MCP 서버를 띄운다. 스킬 frontmatter 에
+          #   같은 도구가 적혀 있어도 이 줄은 남겨야 한다.
+          # --max-turns: 리뷰 한 건이 파일 읽기·검색·코멘트로 10~20턴을 쓴다.
+          # 상한이 낮으면 리뷰를 끝내기 전에 잘리고, 없으면 폭주할 때 멈출
+          # 지점이 없다. 실행 1회당 상한이지 하루 총량이 아니다.
+          claude_args: '--allowedTools "Skill,Bash,Read,Glob,Grep,Agent,mcp__github_inline_comment__create_inline_comment" --max-turns 30'

.github/workflows/claude.yml

@@ -0,0 +1,40 @@
+# PR·이슈 코멘트에서 Claude 를 직접 부른다. 자동 리뷰(claude-code-review.yml)와
+# 달리 사람이 명시적으로 부를 때만 돈다.
+#
+#   @claude ChatRoomPresenceTracker 가 동시성 안전한지 봐줘
+#   @claude 이 테스트 깨지는 원인 찾아줘
+#
+# common-module/내부 API/Kafka 스키마처럼 서비스 경계를 넘는 변경의 하위
+# 호환성 분석은 여기서 한다. claude-code-review.yml 은 diff 만 보는 얕은
+# 리뷰라 그 분석을 하지 않고, 대신 이 워크플로를 부르라는 코멘트만 남긴다.
+#
+#   @claude 이 PR 의 common-module 변경이 다른 서비스에 미치는 영향 봐줘
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  claude:
+    # 러너가 관계없는 코멘트마다 뜨는 것을 막는다. 액션 자체도 트리거
+    # 문구를 다시 확인한다.
+    if: contains(github.event.comment.body, '@claude')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      # PR 의 CI 결과를 읽게 한다.
+      actions: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

.github/workflows/deploy.yml

@@ -24,6 +24,15 @@ name: deploy
 on:
   push:
     branches: [main]
+    # 문서·부하테스트 도구만 바뀐 머지에 6개 컨테이너를 전부 재기동할 이유가
+    # 없다. 런타임이 읽지 않는 경로는 배포를 건너뛴다.
+    # 주의: 여기 걸린 경로는 EC2 의 git clone 에도 다음 "진짜 배포" 때까지
+    # 반영되지 않는다 - 서버가 읽는 파일(compose, 설정)은 절대 넣지 말 것.
+    paths-ignore:
+      - 'docs/**'
+      - 'tools/**'
+      - '**.md'
+      - '.gitignore'
   # 코드 변경 없이 다시 배포하고 싶을 때 수동 실행
   workflow_dispatch:
 
@@ -60,7 +69,7 @@ jobs:
       # bootJar(실행 가능)와 별개로 jar 태스크가 -plain.jar 를 만들 수 있어,
       # 아래 이미지 잡에서 실행 가능한 쪽을 골라낸다.
       - name: jar 빌드
-        run: ./gradlew bootJar --no-daemon
+        run: ./gradlew bootJar
 
       - name: jar 보관
         uses: actions/upload-artifact@v4
@@ -172,11 +181,13 @@ jobs:
             # --no-build: EC2 에서 소스를 빌드하지 않는다. 이미지는 이미 만들어져 있다.
             docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --no-build
 
-            # 배포마다 서비스 6개의 이미지가 새로 쌓인다. prune -f 는 태그
-            # 없는 것만 지우는데, 옛 커밋 SHA 이미지는 태그가 붙어 있어 그대로
-            # 남는다. -a 로 "컨테이너가 쓰지 않는 것"까지 대상에 넣되, 72시간은
-            # 남겨 최근 버전으로 되돌릴 여지를 둔다.
-            docker image prune -af --filter "until=72h"
+            # 배포마다 서비스 6개의 이미지(~3GB 세트)가 새로 쌓인다. prune -f 는
+            # 태그 없는 것만 지우는데, 옛 커밋 SHA 이미지는 태그가 붙어 있어
+            # 그대로 남는다. -a 로 "컨테이너가 쓰지 않는 것"을 전부 지운다.
+            # 예전엔 until=72h 로 롤백 여지를 뒀지만, 머지가 잦은 날 세대가
+            # 쌓여 29GB 디스크가 가득 차 배포 자체가 죽었다(2026-08-26).
+            # 롤백은 GHCR 에 남아 있는 이미지를 다시 pull 하면 된다.
+            docker image prune -af
 
       - name: 상태 확인
         uses: appleboy/ssh-action@v1

.github/workflows/test.yml

@@ -5,9 +5,23 @@
 # 사라진 게 아니라 시점이 앞당겨진 것이다 - main 에 머지된 뒤 배포를
 # 붙잡고 있는 대신, PR 을 보고 있는 동안 백그라운드로 돌아간다.
 #
+# 잡이 둘로 나뉜 이유:
+#   단위 테스트  IO 가 붙지 않는다. 도커도 브로커도 필요 없어서 빠르다.
+#                고쳐야 할 게 있으면 여기서 가장 먼저 알게 된다.
+#   통합 테스트  EmbeddedKafka 로 브로커를, Testcontainers 로 MySQL 을
+#                실제로 띄운다. 느린 대신 목으로는 볼 수 없는 것을 본다
+#                (재시도 소진 후 DLT 이동, 네이티브 MySQL 쿼리의 실제 결과).
+#
+# 둘 사이에 needs 를 걸지 않았다. 동시에 돌아야 전체 대기 시간이 느린
+# 쪽 하나로 수렴한다. 순서를 세우면 두 시간이 더해진다.
+#
+# 어느 쪽을 나누는지는 @Tag("integration") 이 정한다. 태스크 정의는
+# 루트 build.gradle 에 있다.
+#
 # 이 검증이 실제로 게이트가 되려면 브랜치 보호가 필요하다:
 #   Settings > Branches > main > Require status checks to pass
-#   에서 "테스트" 체크를 필수로 지정한다. 없으면 빨간 PR 도 머지된다.
+#   에서 "단위 테스트"와 "통합 테스트"를 둘 다 필수로 지정한다.
+#   없으면 빨간 PR 도 머지된다.
 # ============================================================
 name: test
 
@@ -22,8 +36,8 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  test:
-    name: 테스트
+  unit:
+    name: 단위 테스트
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -37,17 +51,46 @@ jobs:
 
       - run: chmod +x gradlew
 
-      # matching-service 는 Testcontainers(MySQL)를, 카프카 IT 는
-      # EmbeddedKafka 를 쓴다. 둘 다 ubuntu-latest 러너에서 돈다.
-      - name: 테스트
-        run: ./gradlew test --no-daemon
+      # --no-daemon 을 쓰지 않는다. 데몬을 끄면 setup-gradle 이 이어주는
+      # 빌드 캐시와 설정 캐시를 제대로 못 쓴다(Gradle 공식 권고사항이기도 하다).
+      - name: 단위 테스트
+        run: ./gradlew test
 
       # 실패했을 때만이 아니라 항상 올린다. 통과했지만 오래 걸린 테스트를
       # 찾아볼 때도 리포트가 필요하다.
       - name: 테스트 리포트 보관
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: test-reports
-          path: '*/build/reports/tests/**'
+          name: test-reports-unit
+          path: '*/build/reports/tests/test/**'
+          retention-days: 7
+
+  integration:
+    name: 통합 테스트
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - uses: gradle/actions/setup-gradle@v4
+
+      - run: chmod +x gradlew
+
+      # matching-service 는 Testcontainers(MySQL)를, 카프카 IT 는
+      # EmbeddedKafka 를 쓴다. 둘 다 ubuntu-latest 러너에 이미 있는
+      # 도커/JVM 으로 돈다 - 별도 서비스 컨테이너 선언이 필요 없다.
+      - name: 통합 테스트
+        run: ./gradlew integrationTest
+
+      - name: 테스트 리포트 보관
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-reports-integration
+          path: '*/build/reports/tests/integrationTest/**'
           retention-days: 7

.gitignore

@@ -47,7 +47,8 @@ bin/
 .claudeignore
 .claude
 .mcp.json
-CLAUDE.md
+# CLAUDE.md 는 추적한다. 개인 메모가 아니라 팀이 공유하는 프로젝트 규칙이고,
+# PR 리뷰 액션이 매 실행마다 읽어 docs/code-review-guidelines.md 로 간다.
 scripts
 .idea
 docker-compose.yml
@@ -56,6 +57,15 @@ docker-compose.yml
 /database
 /docs/*
 !/docs/perf-log.md
+# 설계 문서(spec)는 추적한다. /docs/* 가 디렉터리째 막고 있어서 하위 파일만
+# 되살릴 수 없다 - 상위 디렉터리를 먼저 열어줘야 한다.
+!/docs/superpowers/
+# 플러그인이 남기는 상태 파일은 그 안에서도 제외한다.
+/docs/superpowers/**/.omc/
+
+# Alertmanager 실제 설정은 디스코드 웹훅 URL 을 담고 있어 EC2 에만 둔다.
+# 예제(alertmanager.example.yml)만 추적한다 - .env.prod 와 같은 패턴.
+/monitoring/alertmanager/alertmanager.yml
 application-docker.yml
 application-secret.yml
 serviceAccountKey.json
@@ -86,3 +96,5 @@ _workspace
 id_rsa
 id_ed25519
 comatching-ec2
+/AGENTS.md
+

CLAUDE.md

@@ -0,0 +1,30 @@
+# COMAtching Backend
+
+Spring 기반 MSA. 서비스는 gateway / user / matching / chat / item / notification 6개이며
+`common-module` 을 공유한다. 서비스 간 통신은 내부 REST(`/api/internal/**`)와 Kafka 이벤트.
+
+## 코드 리뷰
+
+리뷰 기준은 [docs/code-review-guidelines.md](docs/code-review-guidelines.md) 에 있다.
+코드 리뷰를 할 때는 그 문서를 먼저 읽고 거기 적힌 페르소나·언어·관점을 따른다.
+요약하면:
+
+- **리뷰 코멘트는 한국어로 작성한다.**
+- Spring MSA 실무 경험이 있는 Senior Back-end Engineer 관점으로 본다.
+- "동작한다"는 이유만으로 승인하지 않고, 미래의 변경에 얼마나 버티는지를 본다.
+- 문제를 지적할 때는 "왜 문제인지"와 "어떻게 개선할지"를 함께 쓴다.
+
+이 저장소 특유의 주의점:
+
+- **서비스 경계를 넘는 변경은 하위 호환성을 특히 주의해서 본다** —
+  `common-module` 의 DTO, 서비스 간 내부 API, Kafka 이벤트 스키마는
+  배포 순서가 어긋나는 순간 깨진다.
+  - **단, PR 자동 리뷰(`claude-code-review.yml`)는 diff 에 나온 코드만 보고
+    끝낸다.** 다른 서비스로 건너가 소비 코드를 찾아 읽는 하위 호환성
+    분석은 턴·시간을 크게 늘린다 — diff 가 `common-module`/내부 API/Kafka
+    스키마를 건드리면 자동 리뷰는 코멘트에 "cross-service 영향 확인 필요"
+    한 줄만 남기고, 실제 분석은 PR 코멘트에 `@claude` 로 명시적으로
+    요청했을 때(`claude.yml`)만 수행한다.
+- 운영 설정(`docker-compose.prod.yml`, `application-aws.yml`)은 EC2 단일 호스트에
+  6개 JVM 이 함께 뜨는 전제로 메모리 한도가 잡혀 있다. 한도를 건드리는 변경은
+  전체 예산과 함께 본다.