Cockple · dbalsk · Mar 7, 2026 · Mar 8, 2026 · Mar 8, 2026 · Mar 9, 2026
diff --git a/.github/ISSUE_TEMPLATE/기능-구현.md b/.github/ISSUE_TEMPLATE/기능-구현.md
@@ -1,7 +1,7 @@
 ---
 name: 기능 구현
 about: '기능 설명 및 구현 '
-title: "[FEAT]"
+title: "[FEAT] "
 labels: "\U0001F6E0️ FEAT"
 assignees: ''
 

diff --git a/.github/ISSUE_TEMPLATE/기능-수정.md b/.github/ISSUE_TEMPLATE/기능-수정.md
@@ -1,7 +1,7 @@
 ---
 name: 기능 수정
 about: 리팩토링 목적이 아닌 기능 수정
-title: "[FIX} "
+title: "[FIX] "
 labels: "\U0001F527 FIX"
 assignees: ''
 

diff --git a/.github/ISSUE_TEMPLATE/기타-수정.md b/.github/ISSUE_TEMPLATE/기타-수정.md
@@ -1,7 +1,7 @@
 ---
 name: 기타 수정
 about: '작은 부분 수정 '
-title: "[CHORE]"
+title: "[CHORE] "
 labels: "\U0001F3B5 CHORE"
 assignees: ''
 

diff --git a/.github/ISSUE_TEMPLATE/문서-작업-.md b/.github/ISSUE_TEMPLATE/문서-작업-.md
@@ -1,7 +1,7 @@
 ---
 name: '문서 작업 '
 about: 문서작업 내용
-title: ''
+title: '[Docs] '
 labels: "\U0001F4DC DOC"
 assignees: ''
 

diff --git a/.github/ISSUE_TEMPLATE/오류수정.md b/.github/ISSUE_TEMPLATE/오류수정.md
@@ -1,7 +1,7 @@
 ---
 name: 오류수정
 about: '오류 설명 및 수정 '
-title: "[DEBUG]"
+title: "[DEBUG] "
 labels: "\U0001F577️ BUG"
 assignees: ''
 

diff --git a/.github/ISSUE_TEMPLATE/테스트-작성.md b/.github/ISSUE_TEMPLATE/테스트-작성.md
@@ -0,0 +1,12 @@
+---
+name: '테스트 작성'
+about: 테스트 코드 작성
+title: '[Test] '
+labels: "🧪 TEST"
+assignees: ''
+
+---
+
+## 🔑 테스트 내용
+
+<br>
diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md
@@ -0,0 +1,28 @@
+# WORKFLOWS GUIDE
+
+Apply root `AGENTS.md` first. This file only applies to `.github/workflows/*` edits.
+
+## OVERVIEW
+This directory drives CI on pull requests and CD on pushes to `develop` and `main`.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| PR build/test | `ci.yml` | writes `application.yml`, creates Firebase key, runs `./gradlew build` |
+| Image build + deploy | `cd.yml` | builds on push, tags by branch, then copies compose/nginx/scripts to server |
+
+## CONVENTIONS
+- `develop` and `main` are the only workflow branches here.
+- `ci.yml` chooses `APPLICATION` vs `APPLICATION_STAGING` by `github.base_ref`.
+- `cd.yml` chooses Docker tag `latest` for `main`, `staging` otherwise.
+- Deploy step assumes `/home/ubuntu/cockple` and hands off to `scripts/deploy.sh`.
+
+## ANTI-PATTERNS
+- Do not hardcode secrets into workflow YAML.
+- Do not change copied deploy assets in `cd.yml` without matching script/compose expectations.
+- Do not make `main` and `develop` diverge silently; branch-specific behavior is intentionally small and explicit.
+
+## COMMANDS
+```bash
+./gradlew.bat build
+```
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -27,6 +27,7 @@ jobs:
           else
             echo "DOCKER_TAG=staging" >> $GITHUB_OUTPUT
           fi
+
 
       - name: Build with Gradle
         run: |
@@ -71,7 +72,7 @@ jobs:
           envs: >-
             DB_PASSWORD,GCS_BUCKET,
             KAKAO_CLIENT_ID,KAKAO_CLIENT_SECRET,KAKAO_REDIRECT_URI_PROD,KAKAO_REDIRECT_URI_STAGING,KAKAO_ADMIN_KEY,
-            JWT_SECRET_KEY
+            JWT_SECRET_KEY,FIREBASE_SERVICE_ACCOUNT_KEY
           script: |
             chmod +x /home/ubuntu/cockple/scripts/deploy.sh
             bash /home/ubuntu/cockple/scripts/deploy.sh \
@@ -86,3 +87,4 @@ jobs:
           KAKAO_REDIRECT_URI_STAGING: ${{ secrets.KAKAO_REDIRECT_URI_STAGING }}
           KAKAO_ADMIN_KEY: ${{ secrets.KAKAO_ADMIN_KEY }}
           JWT_SECRET_KEY: ${{ secrets.JWT_SECRET_KEY }}
+          FIREBASE_SERVICE_ACCOUNT_KEY: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_KEY }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -31,6 +31,11 @@ jobs:
             echo "${{ secrets.APPLICATION_STAGING }}" > src/main/resources/application.yml
           fi
 
+      - name: Create Firebase Key File
+        run: |
+          mkdir -p src/main/resources/firebase
+          echo '${{ secrets.FIREBASE_SERVICE_ACCOUNT_KEY }}' > src/main/resources/firebase/cockple-1a83e-firebase-adminsdk-fbsvc-212ce01565.json
+
       - name: Grant execute permission for Gradle
         run: chmod +x gradlew
 

diff --git a/.gitignore b/.gitignore
@@ -47,4 +47,11 @@ application-dev.yml
 terraform/.terraform/
 terraform/terraform.tfstate
 terraform/terraform.tfstate.backup
-terraform/terraform.tfvars
+terraform/terraform.tfvars
+
+### firebase ###
+src/main/resources/firebase/*.json
+
+### Claude / OMC ###
+.claude/
+.omc/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,84 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-03-23 20:04 KST
+**Commit:** 5af1ffe6
+**Branch:** develop
+
+## OVERVIEW
+Cockple_BE is a single-module Spring Boot 3.5.9 backend for the Cockple badminton platform. Core stack: Java 17, JPA + QueryDSL, MySQL, Redis, JWT/Kakao OAuth, WebSocket chat, Firebase FCM, Flyway, Docker Compose, and Terraform-managed GCP/Cloudflare infra.
+
+Nearest `AGENTS.md` wins. Read this file first, then the closest child file for the area you are changing.
+
+## STRUCTURE
+```text
+./
+├── .github/workflows/                         # CI/CD entrypoint
+├── scripts/                                   # deploy and SSH tunnel helpers
+├── terraform/                                 # GCP + Cloudflare infra
+├── nginx/                                     # reverse proxy for prod/staging apps
+├── src/main/java/umc/cockple/demo/domain/     # business slices
+├── src/main/java/umc/cockple/demo/global/     # cross-cutting infra
+├── src/main/resources/                        # Spring profiles + Flyway
+├── src/main/generated/                        # generated QueryDSL Q-types
+└── src/test/java/umc/cockple/demo/            # integration/service tests + fixtures
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| App bootstrap | `src/main/java/umc/cockple/demo/Application.java` | Enables JPA auditing and caching |
+| Runtime config | `src/main/resources/application*.yml` | `local` is default; `staging` and `prod` override DB/Redis |
+| Security/websocket ingress | `src/main/java/umc/cockple/demo/global/config/` | JWT, CORS, WebSocket handler registration |
+| Business APIs | `src/main/java/umc/cockple/demo/domain/` | Vertical slices by feature |
+| Exercise hotspot | `src/main/java/umc/cockple/demo/domain/exercise/` | Largest converter/query/test surface |
+| Chat hotspot | `src/main/java/umc/cockple/demo/domain/chat/` | REST + WebSocket + cache/event flow |
+| Shared infra | `src/main/java/umc/cockple/demo/global/` | response, exception, jwt, oauth2, config |
+| Test conventions | `src/test/java/umc/cockple/demo/` | shared fixtures + integration base live here |
+| Local stack | `docker-compose.yml`, `nginx/`, `scripts/` | prod/staging services share one compose file |
+| CI/CD | `.github/workflows/` | PR builds on `develop`/`main`; push deploys by branch |
+| Infra changes | `terraform/` | GCP compute/network/storage + Cloudflare |
+
+## CONVENTIONS
+- Domain code is organized as feature slices, not horizontal layers across the repo.
+- Controllers usually return `BaseResponse` or `ResponseEntity<BaseResponse<...>>`.
+- Error codes are per-domain enums and use a documented `1xx/2xx/3xx/4xx` meaning split.
+- `application.yml` enforces `ddl-auto: validate`; schema changes belong in Flyway under `src/main/resources/db/migration/`.
+- QueryDSL generated sources are wired through Gradle; handwritten code lives under `src/main/java`, generated code under `src/main/generated` or `build/generated/...`.
+- Tests split into integration (`MockMvc` + Testcontainers profile) and service/unit (`MockitoExtension`) styles.
+
+## ANTI-PATTERNS (THIS PROJECT)
+- Do not edit generated QueryDSL Q-types.
+- Do not widen security whitelist or CORS origins casually; both are explicit in `SecurityConfig` and `WebSocketConfig`.
+- Do not rely on JPA auto-DDL for schema work; startup uses validation only.
+- Do not scatter test fixtures inside feature test packages; shared fixtures already live under `src/test/java/umc/cockple/demo/support/fixture/`.
+- Do not assume everything under `global/` is generic; JWT/OAuth code is coupled to member/auth flows.
+
+## UNIQUE STYLES
+- `domain/chat` has extra realtime sublayers: `handler/`, `interceptor/`, `events/`, `service/websocket/`.
+- `domain/exercise` is the densest slice: large converter, query service, command internals, and the biggest integration tests.
+- `domain/party` and `domain/notification` use events/notification wiring more than simpler slices like `bookmark` or `terms`.
+
+## COMMANDS
+```bash
+./gradlew.bat build
+./gradlew.bat test
+./gradlew.bat bootRun
+docker compose config --services
+bash scripts/tunnel.sh <GCP_IP>
+```
+
+## CHILD GUIDES
+- `.github/workflows/AGENTS.md`
+- `scripts/AGENTS.md`
+- `terraform/AGENTS.md`
+- `src/main/java/umc/cockple/demo/domain/AGENTS.md`
+- `src/main/java/umc/cockple/demo/domain/chat/AGENTS.md`
+- `src/main/java/umc/cockple/demo/domain/exercise/AGENTS.md`
+- `src/main/java/umc/cockple/demo/global/AGENTS.md`
+- `src/main/java/umc/cockple/demo/global/config/AGENTS.md`
+- `src/test/java/umc/cockple/demo/AGENTS.md`
+
+## NOTES
+- CI writes `src/main/resources/application.yml` from GitHub secrets before building.
+- CD copies only `docker-compose.yml`, `init-db.sql`, `nginx/`, and `scripts/` to the server; deploy behavior lives in both workflow and shell script.
+- Local profile expects MySQL on `3307` and Redis on `6380`; `scripts/tunnel.sh` exposes those ports through SSH forwarding.
diff --git a/build.gradle b/build.gradle
@@ -95,6 +95,13 @@ dependencies {
     // redis
     implementation 'org.springframework.boot:spring-boot-starter-data-redis'
     implementation 'io.lettuce:lettuce-core'
+
+    // firebase
+    implementation 'com.google.firebase:firebase-admin:9.7.1'
+
+    // flyway
+    implementation 'org.flywaydb:flyway-core'
+    implementation 'org.flywaydb:flyway-mysql'
 }
 
 tasks.named('test') {

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -13,7 +13,7 @@ services:
     command:
       - --character-set-server=utf8mb4
       - --collation-server=utf8mb4_unicode_ci
-      - --innodb-buffer-pool-size=256M
+      - --innodb-buffer-pool-size=512M
     volumes:
       - mysql-data:/var/lib/mysql
       - ./init-db.sql:/docker-entrypoint-initdb.d/init-db.sql:ro
@@ -22,8 +22,8 @@ services:
       interval: 10s
       timeout: 5s
       retries: 5
-    mem_limit: 512m
-    memswap_limit: 768m
+    mem_limit: 1g
+    memswap_limit: 1536m
 
   redis:
     image: redis:7-alpine
@@ -63,6 +63,7 @@ services:
       KAKAO_REDIRECT_URI: ${KAKAO_REDIRECT_URI_PROD}
       KAKAO_ADMIN_KEY: ${KAKAO_ADMIN_KEY}
       JWT_SECRET_KEY: ${JWT_SECRET_KEY}
+      FIREBASE_SERVICE_ACCOUNT_KEY: ${FIREBASE_SERVICE_ACCOUNT_KEY}
     depends_on:
       mysql:
         condition: service_healthy
@@ -85,6 +86,7 @@ services:
       KAKAO_REDIRECT_URI: ${KAKAO_REDIRECT_URI_STAGING}
       KAKAO_ADMIN_KEY: ${KAKAO_ADMIN_KEY}
       JWT_SECRET_KEY: ${JWT_SECRET_KEY}
+      FIREBASE_SERVICE_ACCOUNT_KEY: ${FIREBASE_SERVICE_ACCOUNT_KEY}
     depends_on:
       mysql:
         condition: service_healthy

diff --git a/nginx/conf.d/prod.conf b/nginx/conf.d/prod.conf
@@ -10,14 +10,17 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
+
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
     }
 
     location / {
         proxy_pass http://cockple-app:8080;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
     }
 }
diff --git a/nginx/conf.d/staging.conf b/nginx/conf.d/staging.conf
@@ -11,6 +11,9 @@ server {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
+
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
     }
 
     location / {

diff --git a/nginx/nginx.conf b/nginx/nginx.conf
@@ -21,5 +21,9 @@ http {
     keepalive_timeout 65;
     client_max_body_size 30M;
 
+    gzip on;
+    gzip_types application/json application/javascript text/plain text/css;
+    gzip_min_length 256;
+
     include /etc/nginx/conf.d/*.conf;
 }
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
@@ -0,0 +1,28 @@
+# SCRIPTS GUIDE
+
+Apply root `AGENTS.md` first. This file only applies to `scripts/*`.
+
+## OVERVIEW
+Shell scripts handle server deployment and local SSH tunneling into the remote stack.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Branch-aware deploy | `deploy.sh` | writes `.env`, pulls image tag, restarts one app service |
+| Remote DB/Redis access | `tunnel.sh` | forwards MySQL to `3307`, Redis to `6380` |
+
+## CONVENTIONS
+- `deploy.sh` treats `main` as `cockple-app:latest`; any other branch path becomes `cockple-app-staging:staging`.
+- Deploy always starts `mysql`, `redis`, and `nginx` before replacing the app container.
+- Health checks are part of the script, not just Docker Compose.
+
+## ANTI-PATTERNS
+- Do not change forwarded local ports without matching `application-local.yml`.
+- Do not add new required env vars in scripts without updating workflow `envs` and compose.
+- Do not bypass the health-check loop when changing deploy behavior.
+
+## COMMANDS
+```bash
+bash scripts/deploy.sh <docker_repo> <branch>
+bash scripts/tunnel.sh <GCP_IP>
+```
diff --git a/scripts/deploy.sh b/scripts/deploy.sh
@@ -22,7 +22,9 @@ KAKAO_REDIRECT_URI_PROD=${KAKAO_REDIRECT_URI_PROD}
 KAKAO_REDIRECT_URI_STAGING=${KAKAO_REDIRECT_URI_STAGING}
 KAKAO_ADMIN_KEY=${KAKAO_ADMIN_KEY}
 JWT_SECRET_KEY=${JWT_SECRET_KEY}
+FIREBASE_SERVICE_ACCOUNT_KEY=${FIREBASE_SERVICE_ACCOUNT_KEY}
 EOF
+echo "${FIREBASE_SERVICE_ACCOUNT_KEY}" > /home/ubuntu/cockple/firebase-service-account.json
 
 echo "=== 배포 전 상태 ==="
 sudo docker ps

diff --git a/src/main/java/umc/cockple/demo/domain/AGENTS.md b/src/main/java/umc/cockple/demo/domain/AGENTS.md
@@ -0,0 +1,32 @@
+# DOMAIN GUIDE
+
+Apply root `AGENTS.md` first. This file covers feature slices under `domain/`.
+
+## OVERVIEW
+Business logic is organized by feature slice, usually with `controller`, `converter`, `domain`, `dto`, `enums`, `exception`, `repository`, and `service` subpackages.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Member/account flows | `member/` | auth-adjacent domain code |
+| Party lifecycle | `party/` | joins, invitations, roles, events |
+| Exercise lifecycle | `exercise/` | largest slice; read child guide |
+| Chat realtime flows | `chat/` | read child guide |
+| Notifications | `notification/` | FCM-backed notifications |
+| Simpler slices | `bookmark/`, `contest/`, `file/`, `terms/` | mostly standard pattern |
+
+## CONVENTIONS
+- Domain-specific errors live in each slice’s `exception/*ErrorCode.java`.
+- Controllers expose `/api/...` endpoints and use global response wrappers.
+- Shared enums/base entities come from `global/`; slice-specific rules stay here.
+- `party/` and `chat/` add `events/`; `party/` also has `utils/`.
+- QueryDSL generated code mirrors entity packages elsewhere; do not mix handwritten logic into generated folders.
+
+## ANTI-PATTERNS
+- Do not move business rules into `global/` just because multiple slices depend on them.
+- Do not bypass slice error codes with ad hoc strings or generic exceptions.
+- Do not edit generated Q-types to “fix” repository behavior.
+
+## CHILD GUIDES
+- `chat/AGENTS.md`
+- `exercise/AGENTS.md`
diff --git a/src/main/java/umc/cockple/demo/domain/bookmark/converter/BookmarkConverter.java b/src/main/java/umc/cockple/demo/domain/bookmark/converter/BookmarkConverter.java
@@ -7,7 +7,6 @@
 import umc.cockple.demo.domain.bookmark.dto.GetAllExerciseBookmarksResponseDTO;
 import umc.cockple.demo.domain.bookmark.dto.GetAllPartyBookmarkResponseDTO;
 import umc.cockple.demo.domain.exercise.domain.Exercise;
-import umc.cockple.demo.domain.image.service.ImageService;
 import umc.cockple.demo.domain.party.domain.Party;
 import umc.cockple.demo.domain.party.domain.PartyLevel;
 import umc.cockple.demo.domain.party.enums.ActivityTime;