ePA 주기 export 스케줄 API (v2)

ePA 주기 export 스케줄 API는 14일 주기 ePA 자동 export 스케줄을 설정/취소/조회하는 v2 endpoint 묶음입니다. 설정은 순수 스케줄 등록이며 즉시 전송을 수반하지 않습니다(즉시 전송은 ePA 전송 POST /epa).

핵심

• 순수 스케줄: POST .../epa/schedule 는 스케줄만 등록하고 즉시 전송하지 않습니다.
• 재설정 시 기존 폐기: 기존 ACTIVE 스케줄이 있으면 CANCELLED 처리 후 새로 설정됩니다.
• 다음 전송일: nextExportDate = 설정일 + 14일(사용자 timezone 로컬 자정). 말기엔 day82 컷·종료일 최종 export 정책에 따라 실제 발송과 다를 수 있는 "예정일" 입니다.
• 시각 표기: 모든 시각은 unix timestamp(ms, 13자리).

인증 정책 (v2 공통)

• 인증 채널은 Authorization: Bearer <accessToken> 한 줄(JwtAuthGuard).
• 신원은 access token payload(userId)로 확정합니다.

---

POST /v2/health-data/export/epa/schedule ⭐

14일 주기 ePA 자동 export 스케줄을 등록합니다.

• Path: POST /v2/health-data/export/epa/schedule
• 인증: User Access Token (JwtAuthGuard)
• Rate Limit: 60/분 (전역 default)
• 🔗 라이브 명세 (Swagger UI): dev

Request

Header	Value
Authorization	Bearer <accessToken> (필수)

Request Body — EpaExportRequestDto

필드	타입	필수	제약	설명
format	string	No	xml | pdf	export 포맷. 미지정 시 xml(ePA MIO Bundle)

{
  "format": "xml"
}

동작

1. JwtAuthGuard로 access token을 검증하고 payload에서 userId를 확정합니다.
2. 사용자의 현재(active) cycle 을 확인합니다 — 없으면 404(EXPORT_USER_INFO_NOT_FOUND).
3. 기존 ACTIVE 스케줄이 있으면 CANCELLED 처리합니다.
4. 14일 주기 스케줄을 새로 등록하고 nextExportDate(설정일 + 14일)를 계산합니다. 이 단계에서 즉시 전송은 하지 않습니다.
5. active=true + nextExportDate 를 반환합니다.

Response 200 OK — EpaScheduleResponseDto

{
  "active": true,
  "nextExportDate": 1750636800000
}

필드	타입	필수	설명
active	boolean	Yes	활성 주기 스케줄 존재 여부(설정 직후 항상 true)
nextExportDate	number | null	Yes	다음 자동 export 예정일(설정일 + 14일) unix timestamp(ms, 13자리)

Errors

HTTP	code	message	발생 조건
401	1000	Authentication token not found	Bearer access token 미제공 (JwtAuthGuard)
401	1000	Invalid or expired token	access token 만료/서명·검증 실패 (JwtAuthGuard)
401	1000	Invalid token: missing subject (user ID)	payload에 userId(sub) 없음
401	1000	User ID not found in request	guard 통과했으나 req.user.userId 부재 (컨트롤러)
404	21100	EXPORT_USER_INFO_NOT_FOUND	요청 사용자의 활성(active) cycle 없음

---

POST /v2/health-data/export/epa/schedule/cancel

사용자의 ACTIVE ePA 주기 스케줄을 취소(CANCELLED)합니다.

• Path: POST /v2/health-data/export/epa/schedule/cancel
• 인증: User Access Token (JwtAuthGuard)
• Rate Limit: 60/분 (전역 default)
• 🔗 라이브 명세 (Swagger UI): dev

Request

Header	Value
Authorization	Bearer <accessToken> (필수)

요청 본문 없음. 신원은 access token payload(userId)로 확정합니다.

Response 200 OK — CancelEpaScheduleResponseDto

{
  "cancelled": true
}

필드	타입	필수	설명
cancelled	boolean	Yes	취소된 활성 스케줄이 있었는지(없었으면 false)

Errors

HTTP	code	message	발생 조건
401	1000	Authentication token not found	Bearer access token 미제공 (JwtAuthGuard)
401	1000	Invalid or expired token	access token 만료/서명·검증 실패 (JwtAuthGuard)
401	1000	Invalid token: missing subject (user ID)	payload에 userId(sub) 없음
401	1000	User ID not found in request	guard 통과했으나 req.user.userId 부재 (컨트롤러)

---

GET /v2/health-data/export/epa/schedule

인증 사용자의 활성(ACTIVE) ePA 주기 스케줄을 조회합니다. 클라이언트는 주기 설정 전 이 값으로 "기존 설정 폐기" 안내·다음 전송일 표시에 사용합니다.

• Path: GET /v2/health-data/export/epa/schedule
• 인증: User Access Token (JwtAuthGuard)
• Rate Limit: 60/분 (전역 default)
• 🔗 라이브 명세 (Swagger UI): dev

Request

Header	Value
Authorization	Bearer <accessToken> (필수)

요청 본문/쿼리 없음.

Response 200 OK — EpaScheduleResponseDto

// 활성 있음
{
  "active": true,
  "nextExportDate": 1750636800000
}

// 활성 없음
{
  "active": false,
  "nextExportDate": null
}

필드	타입	필수	설명
active	boolean	Yes	활성 주기 스케줄 존재 여부
nextExportDate	number | null	No	다음 자동 export 예정일 unix timestamp(ms, 13자리). 활성 없으면 null

Errors

HTTP	code	message	발생 조건
401	1000	Authentication token not found	Bearer access token 미제공 (JwtAuthGuard)
401	1000	Invalid or expired token	access token 만료/서명·검증 실패 (JwtAuthGuard)
401	1000	Invalid token: missing subject (user ID)	payload에 userId(sub) 없음
401	1000	User ID not found in request	guard 통과했으나 req.user.userId 부재 (컨트롤러)
500	21000	(빈 값)	스케줄 조회 중 예상치 못한 서버 오류

---

다음 단계

• 즉시 전송: ePA 전송 (POST /epa).
• 최근 전송 결과 확인: 최신 export 기록 조회 (GET .../epa/latest).