Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
1c3b821
chore: 동시 접속 100명 기준 커넥션 풀/스레드 풀 설정 적용 (#140)
tnals0924 Jul 24, 2026
a5aaa10
Merge pull request #141 from billilge/chore/#140
tnals0924 Jul 24, 2026
acaf715
fix: 납부자 목록 조회 정렬 순서와 불일치하는 인덱스 수정 (#142)
tnals0924 Jul 24, 2026
5d02fad
Merge pull request #143 from billilge/fix/#142
tnals0924 Jul 24, 2026
cab1b5c
fix: 푸시 발송을 알림 저장 트랜잭션 밖으로 분리 (#144)
tnals0924 Aug 17, 2026
ce1a92e
chore: 알림 전용 비동기 실행기와 예외 핸들러 설정 (#144)
tnals0924 Aug 17, 2026
2dd3d4f
feat: 아웃박스 기반 푸시 발송 재시도 (#146)
tnals0924 Aug 17, 2026
1a600d2
chore: 푸시 아웃박스 보관 정책 및 정리 스케줄러 (#147)
tnals0924 Aug 17, 2026
644f746
refactor: 알림 발송 구조 개선, 아웃박스 재시도 및 보관 정책 - #145
tnals0924 Aug 17, 2026
1f54af0
fix: 푸시 유효 시간을 10분으로 단축 (#148)
tnals0924 Aug 17, 2026
da4a161
Merge pull request #149 from billilge/fix/#148
tnals0924 Aug 17, 2026
7c95288
fix: 납부자 목록 조회의 filesort 제거 - #142
tnals0924 Aug 17, 2026
bbc2c3c
chore: dev 프로파일의 SQL 콘솔 출력 제거 - #151
tnals0924 Aug 17, 2026
a89803d
Merge pull request #152 from billilge/chore/#151
tnals0924 Aug 17, 2026
be4f51c
Merge pull request #150 from billilge/fix/#142-filesort
tnals0924 Aug 17, 2026
21fbb3a
chore: 로그 출력을 비동기 appender 로 분리 - #153
tnals0924 Aug 17, 2026
c8c4bb1
Merge pull request #154 from billilge/chore/#153
tnals0924 Aug 17, 2026
aec699e
deploy: CD 배포를 CapRover에서 Coolify로 마이그레이션 - #155
tnals0924 Sep 21, 2026
ebd79ad
Merge pull request #156 from billilge/deploy/#155
tnals0924 Oct 6, 2026
9b78344
docs: README 작성 및 다이어그램 이미지 추가
tnals0924 Oct 15, 2026
8087dab
docs: README 누적 대여 이용 건수 갱신
tnals0924 Oct 15, 2026
4d5146d
refactor: 파일 저장소를 MinIO에서 Cloudflare R2로 교체
tnals0924 Nov 11, 2026
d98240d
Merge pull request #157 from billilge/refactor/r2-storage
tnals0924 Nov 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions .github/workflows/ci-cd_dev.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,8 @@ jobs:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- name: Deploy to CapRover
uses: caprover/deploy-from-github@v1.1.2
with:
server: ${{ secrets.CAPROVER_SERVER }}
app: ${{ secrets.CAPROVER_DEV_APP_NAME }}
token: ${{ secrets.CAPROVER_DEV_APP_TOKEN }}
image: ${{ env.DOCKER_IMAGE }}:latest
- name: Trigger Coolify deploy
run: |
curl --fail --show-error --silent --request GET \
"${{ secrets.COOLIFY_URL }}/api/v1/deploy?uuid=${{ secrets.COOLIFY_DEV_RESOURCE_UUID }}&force=true" \
--header "Authorization: Bearer ${{ secrets.COOLIFY_API_TOKEN }}"
12 changes: 5 additions & 7 deletions .github/workflows/ci-cd_prod.yml
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,8 @@ jobs:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- name: Deploy to CapRover
uses: caprover/deploy-from-github@v1.1.2
with:
server: ${{ secrets.CAPROVER_SERVER }}
app: ${{ secrets.CAPROVER_PROD_APP_NAME }}
token: ${{ secrets.CAPROVER_PROD_APP_TOKEN }}
image: ${{ env.DOCKER_IMAGE }}:latest
- name: Trigger Coolify deploy
run: |
curl --fail --show-error --silent --request GET \
"${{ secrets.COOLIFY_URL }}/api/v1/deploy?uuid=${{ secrets.COOLIFY_PROD_RESOURCE_UUID }}&force=true" \
--header "Authorization: Bearer ${{ secrets.COOLIFY_API_TOKEN }}"
64 changes: 57 additions & 7 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
- **JPA + QueryDSL** (MySQL)
- **Spring Security** (JWT + Google OAuth2)
- **Firebase Cloud Messaging** (푸시 알림)
- **AWS S3** (이미지 업로드)
- **Cloudflare R2** (이미지 업로드, AWS SDK v2 S3 호환 API)
- **Apache POI** (Excel 생성)

## 빌드 & 실행
Expand Down Expand Up @@ -72,13 +72,63 @@ domain/{name}/
## 서비스 의존성

```
ItemService → ItemRepository, S3Service
MemberService → MemberRepository, TokenProvider, PayerService
NotificationService → NotificationRepository, FCMService, MemberService
PayerService → PayerRepository, MemberRepository, ExcelGenerator
RentalService → RentalRepository, NotificationService
ItemService → ItemRepository, FileStorageService(R2Service)
MemberService → MemberRepository, TokenProvider, PayerService
NotificationService → NotificationRepository, NotificationPushOutboxService
NotificationPushOutboxService → NotificationPushOutboxRepository
PushNotificationSender → FCMService, MemberService, NotificationPushOutboxService
PayerService → PayerRepository, MemberRepository, ExcelGenerator
RentalService → RentalRepository, ApplicationEventPublisher
```

### 알림 발송 구조

`RentalService`가 이벤트를 발행하면 `NotificationEventHandler`가 커밋 이후 비동기로 받아 처리한다.

```
RentalService → 이벤트 발행
└ NotificationEventHandler (@Async + AFTER_COMMIT, 트랜잭션 없음)
├ NotificationService.createNotification() # 알림 + 아웃박스 저장 (한 트랜잭션, 즉시 커밋)
└ PushNotificationSender.dispatch() # 트랜잭션 밖에서 FCM 호출

PushRetryScheduler (@Scheduled, 30초 간격)
└ PushNotificationSender.dispatch() # 미발송 건 재시도 (같은 경로)
```

- **푸시 발송은 트랜잭션 밖에서 수행한다** — 네트워크 I/O가 DB 커넥션을 점유하지 않도록, 그리고 푸시 실패가 저장된 알림을 롤백시키지 않도록 분리
- **`PushNotificationSender`는 예외를 전파하지 않는다** — 한 수신자의 실패가 다른 수신자에게 영향을 주면 안 됨
- **FCM 실패는 `PushResult`로 구분한다** — `InvalidToken`(토큰 제거) / `Retryable`(재시도 대상) / `Permanent`(재시도 무의미)
- **`@Async`는 알림 전용 실행기(`notificationTaskExecutor`)를 사용한다** — `AsyncConfig`에 정의

### 푸시 재시도 (아웃박스)

발송 대상을 `notification_push_outbox`에 **수신자 단위 row**로 남긴다. 알림과 같은 트랜잭션에서 저장되므로 프로세스가 재시작돼도 발송 대상이 남는다.

```
PENDING ─┬─ 발송 성공 ──────────────→ SENT
├─ Retryable 실패 ─ 백오프 → PENDING (재시도 횟수 소진 시 FAILED)
├─ InvalidToken/Permanent → FAILED
└─ 생성 후 1시간 경과 ─────→ EXPIRED
```

- **유효 시간(TTL)은 10분** — 사용자 알림은 지금 과방에 갈지를 결정하는 정보고, 관리자 알림도 학생이 기다리는 상태에서 처리해야 하는 일이라 둘 다 실시간성이 중요하다. 지나면 `EXPIRED`로 포기하며, 인앱 알림은 이미 저장돼 있으므로 정보가 사라지는 것은 아니다
- **백오프는 `30초 → 2분 → 5분`, 최대 3회** — 누적 7분 30초로 유효 시간 안에 들어온다
- **다음 재시도 시각이 TTL을 넘기면 예약하지 않고 즉시 포기한다** — 어차피 만료될 시도를 기다리지 않는다
- **즉시 발송과 재시도가 같은 경로를 탄다** — 새 row의 `nextRetryAt`은 60초 뒤로 잡혀, 즉시 시도와 폴러가 겹치지 않는다
- **메시지 본문은 저장하지 않는다** — 연결된 `Notification`의 status와 formatValues로 재구성
- 인스턴스를 여러 대로 늘리면 조회에 잠금(`FOR UPDATE SKIP LOCKED`)이나 ShedLock이 필요하다

**보관 정책** — `PushOutboxPurgeScheduler`가 매일 새벽 4시(KST)에 정리한다.

| 상태 | 보존 기간 |
|---|---|
| `SENT` | 7일 |
| `FAILED`, `EXPIRED` | 30일 (실패 원인 확인용) |
| `PENDING` | 삭제하지 않음 |

- **배치(500건)로 나눠 삭제하고 배치마다 트랜잭션을 끊는다** — 락 구간을 짧게 유지
- **한 회 처리량 상한(20배치)에 도달하면 경고 로그를 남긴다** — 남은 건이 있다는 사실이 묻히지 않도록

## 대여 상태 머신

```
Expand Down Expand Up @@ -173,7 +223,7 @@ global/
├── exception/ # ApiException, ErrorCode, GlobalExceptionHandler
├── external/
│ ├── fcm/ # FCMConfig, FCMService
│ └── s3/ # S3Config, S3Service
│ └── r2/ # R2Config, R2Service (FileStorageService 구현체)
├── logging/ # LoggingFilter
├── security/
│ ├── jwt/ # TokenProvider, TokenAuthenticationFilter
Expand Down
Loading
Loading