# 구독관리 내보내기 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