Vendor telemetry adapter interface, stub, and disabled scheduler skeleton

[tkdgusqkr]

Scope

Vendor telemetry 폴링 워커의 사전 준비 단계. 실제 vendor API 문서가 도착하기 전에 인터페이스 + stub 구현 + scheduler 골격을 백엔드에 깔아둔다. vendor 문서 도착 시 stub 자리에 실 구현체만 끼워 넣으면 동작.

Included:

• vendor 신규 패키지 (com.thundercrew.opsapi.vendor):
  • VendorTelemetryFeed — 인터페이스. `pullRecent(Instant since): VendorTelemetryFetchResult` (정규화된 우리 `TelemetryIngestRequest` 리스트 + 다음 호출에 쓸 cursor).
  • StubVendorTelemetryFeed — 빈 결과 반환 + 호출 횟수 카운터. 기본 구현체.
  • VendorTelemetryAdapter — 받은 결과를 우리 `TelemetryIngestionService` 로 흘려보내는 orchestrator. 실패는 `device_api_sync_runs` 에 기록.
  • VendorTelemetryPollingScheduler — `@ConditionalOnProperty` 로 기본 비활성. property 활성 시 fixed delay polling.
• 설정 (application.properties):
  • `thundercrew.vendor-telemetry.enabled=false` (기본 false — 운영자가 명시적으로 켜야 함).
  • `thundercrew.vendor-telemetry.poll-interval-ms=60000` (기본 1분).
  • `thundercrew.vendor-telemetry.feed-implementation=stub` (기본 stub — 실 구현체 추가 시 `real` 같은 값으로 바꿈).
• 통합 테스트:
  • StubVendorTelemetryFeed 가 빈 결과를 반환하면 ingestion 이 호출되지 않는다.
  • 의도적으로 1건 결과를 만들고 adapter 가 `TelemetryIngestionService.ingest` 를 호출 → `bike_current_states` 가 갱신되는지.
  • 스케줄러는 property 활성/비활성 시 빈 빌드에서도 ApplicationContext 가 로드되는지.

Excluded:

• 실제 vendor REST/MQTT 호출 코드 (Slice F-2, vendor 문서 도착 시).
• vendor 인증 (API key / OAuth / mTLS) 설정.
• vendor specific payload 변환 (Slice F-2).

Acceptance criteria

• 백엔드 부팅 시 기본 설정에서 vendor scheduler 가 비활성 (테스트에서 ApplicationContext 가 깨지지 않음).
• property 활성 시 stub 이 1분 주기로 호출되며 `pullRecent` 가 빈 결과를 반환.
• adapter 가 vendor 결과를 받아 `TelemetryIngestionService.ingest` 로 흘려보내는 경로가 단위 테스트로 검증된다.
• ArchUnit / 기존 통합 테스트 회귀 없음.
• `./gradlew test` / `./gradlew build` 통과.

Trace

• Root project-start: Project start: thundercrew-domain MVP clever-change-control#45
• Change-control issue: pending
• Builds on (merged): 텔레메트리 ingest 도메인 (기존 `POST /api/v1/telemetry/device-events`).

Concurrent work gate

Decision: allowed-with-non-overlap
Evidence:

• Open target issues: none.
• Open target PRs: none.
• Active branches: dev, main.
  Reason: backend-only 신규 vendor 패키지. 다른 도메인 영향 없음.

[tkdgusqkr]

PR opened: #145 (branch: cc-126-vendor-telemetry-adapter-stub → dev). Linked change-control issue: EVNSolution/clever-change-control#126.