docs: [changes] 구독관리 내보내기 stuck 문제 수정 이력 추가

changes/20260318_subscription_export_fix.md

@@ -0,0 +1,79 @@
+# 구독관리 내보내기 stuck 문제 수정
+
+**날짜:** 2026-03-18
+**작업자:** Claude Code
+
+---
+
+## 변경 개요
+
+구독관리 페이지에서 "자료 내보내기" 버튼 클릭 시 `DataExport` 레코드가 `pending` 상태로 영원히 남아 후속 요청이 차단되는 문제를 수정했다.
+
+### 원인
+
+- `SubscriptionService::createExport()`에서 `DataExport` 레코드를 `pending` 상태로 생성
+- 실제 처리를 담당하는 `ProcessDataExport` Job이 TODO로 주석 처리되어 미구현
+- 레코드가 `pending`에서 변경되지 않아 중복 요청 차단 로직에 걸림
+
+### 해결
+
+- 비동기 Job 패턴 → 동기 처리로 전환 (`ExportService::store()` 사용)
+- 5분 이상 stuck된 `pending`/`processing` export 자동 만료 처리 추가
+- 파일 다운로드 엔드포인트 추가
+
+---
+
+## 수정된 파일
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `api/app/Services/SubscriptionService.php` | `createExport()` 동기 처리 전환, 자동 만료 로직 추가, `getSubscriptionExportData()` 추가 |
+| `api/app/Http/Controllers/Api/V1/SubscriptionController.php` | `ExportService` DI 추가, `exportDownload()` 메서드 추가 |
+| `api/routes/api/v1/finance.php` | `GET /export/{id}/download` 라우트 추가 |
+
+---
+
+## 상세 변경 사항
+
+### 1. 동기 처리 전환
+
+기존 비동기 패턴(Job 미구현)에서 `ExportService::store()`를 사용한 동기 처리로 전환했다. 구독 데이터는 소규모이므로 동기 처리가 적합하다.
+
+```
+기존: POST /export → DataExport(pending) 생성 → Job 미실행 → 영원히 pending
+수정: POST /export → DataExport 생성 → 즉시 Excel 생성 → completed 마킹
+```
+
+### 2. 자동 만료 처리
+
+`createExport()` 호출 시 5분 이상된 `pending`/`processing` 상태의 내보내기를 자동으로 `failed`로 변경한다. 예외 상황에서 stuck된 레코드가 후속 요청을 영구 차단하는 문제를 방지한다.
+
+### 3. 다운로드 엔드포인트
+
+| Method | Path | 설명 |
+|--------|------|------|
+| `GET` | `/api/v1/subscriptions/export/{id}/download` | 생성된 Excel 파일 다운로드 |
+
+### 4. DB 정리
+
+stuck된 `DataExport` 레코드 1건 (ID: 1, tenant: 287, 2026-01-05 생성) → `failed`로 변경 완료
+
+---
+
+## 테스트 체크리스트
+
+- [x] stuck된 pending 레코드 정리 완료
+- [x] Pint 포맷팅 적용
+- [ ] 개발서버에서 내보내기 버튼 동작 확인
+- [ ] 생성된 Excel 파일 다운로드 확인
+
+---
+
+## 관련 문서
+
+- `api/app/Models/Tenants/DataExport.php` — 내보내기 상태 모델
+- `api/app/Services/ExportService.php` — 범용 Excel 내보내기 서비스
+
+---
+
+**최종 업데이트**: 2026-03-18