From f49db028ebda18af04ce57e4b92497b341c8b2b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?=
 <lightone2017@codebridge-x.com>
Date: Wed, 18 Mar 2026 14:12:25 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20[changes]=20=EA=B5=AC=EB=8F=85=EA=B4=80?=
 =?UTF-8?q?=EB=A6=AC=20=EB=82=B4=EB=B3=B4=EB=82=B4=EA=B8=B0=20stuck=20?=
 =?UTF-8?q?=EB=AC=B8=EC=A0=9C=20=EC=88=98=EC=A0=95=20=EC=9D=B4=EB=A0=A5=20?=
 =?UTF-8?q?=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 changes/20260318_subscription_export_fix.md | 79 +++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 changes/20260318_subscription_export_fix.md

diff --git a/changes/20260318_subscription_export_fix.md b/changes/20260318_subscription_export_fix.md
new file mode 100644
index 0000000..884c8b8
--- /dev/null
+++ b/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