feat: Instance 크롤러 증분 크롤링 구현

[longfin]

배경

현재 flex-ax crawl은 매 실행마다 전체 데이터를 처음부터 크롤링한다. 데이터가 커질 경우 불필요한 API 호출과 시간이 소요되므로, Instance 크롤러에 증분(incremental) 크롤링을 도입한다.

크롤러별 현황

크롤러	증분 가능 여부	사유
Instance	✅ 가능	LAST_UPDATED_AT DESC 정렬 + 커서 페이지네이션 이미 구현
Template	❌ 불필요	단일 GET, 데이터 수십~수백 건으로 적음
Attendance	❌ 어려움	페이지네이션/정렬/날짜 필터 파라미터 없음

구현 계획

1. 크롤링 상태 저장 (.crawl-state.json)

• 크롤링 완료 시 마지막 크롤링 시각을 outputDir/.crawl-state.json에 저장
• 다음 크롤링 시 이 파일을 로드하여 증분 기준 시각으로 사용

// .crawl-state.json
{
  "lastCrawledAt": "2026-04-08T12:00:00Z",
  "lastDocumentKey": "doc-key-xxx"  // optional, 중단 복구용
}

2. Instance 크롤러 조기 중단 로직

• LAST_UPDATED_AT DESC로 정렬된 결과를 페이지네이션하면서 가져옴
• 각 문서의 lastUpdatedAt을 .crawl-state.json의 lastCrawledAt과 비교
• lastUpdatedAt < lastCrawledAt인 문서가 나오면 해당 페이지까지만 처리하고 중단
• overlap 마진: 동시 업데이트 누락 방지를 위해 1분 정도 여유를 둠

3. CLI 옵션 추가

• --full 플래그: 증분 상태를 무시하고 전체 크롤링 강제 실행
• 기본 동작: .crawl-state.json이 있으면 증분, 없으면 전체

4. Storage 변경

• 기존 파일 덮어쓰기 방식이라 upsert는 이미 동작함 → 변경 불필요

5. Report 개선

• 증분/전체 모드 구분 표시
• 스킵된(변경 없는) 문서 수 표시
• 증분 기준 시각 표시

변경 대상 파일

파일	변경 내용
apps/flex-cli/src/commands/crawl.ts	상태 로드/저장, --full 옵션 처리
apps/flex-cli/src/crawlers/instance.ts	lastUpdatedAt 비교 + 조기 중단 로직
apps/flex-cli/src/storage/index.ts	상태 파일 읽기/쓰기 메서드 추가
apps/flex-cli/src/config/index.ts	fullCrawl 옵션 추가
apps/flex-cli/src/types/	CrawlState 타입 정의

리스크 및 고려사항

• API가 서버 측 날짜 필터를 지원하지 않으므로 클라이언트 측에서 판단 → 첫 페이지(20건)는 무조건 요청됨
• 삭제된 문서는 감지 불가 (soft delete가 아닌 경우)
• Template, Attendance는 전체 크롤링 유지