본문으로 건너뛰기

Recon Service Implementation Plan

Status​

Implemented with follow-up backlog

  • docs/adr/ADR-001-document-driven-backend-change-workflow.md
  • docs/adr/ADR-002-recon-service-boundary.md
  • docs/specs/recon/2026-04-22-recon-service-migration.md
  • docs/reference/recon/middle-server-recon-inventory.md
  • docs/reference/recon/recon-service-v2-surface.md

Goal​

Introduce recon_service and recon_worker into servers_v2 without breaking existing bo/admin shooter and pushbullet workflows.

Preconditions​

  • admin_service remains the back-office entrypoint
  • wallet_service remains the single money writer
  • no production cutover proceeds without compatibility tests

Phase 1: Documentation and Compatibility Baseline​

  • Confirm and document all middle_server shooter/pushbullet APIs, background jobs, Redis keys, and top-info fields.
  • Classify /shooter/device/* as recon compatibility scope.
  • Freeze the compatibility route list consumed by bo/admin.
  • Add contract-test cases that capture the current response envelopes and header-refresh behavior.

Phase 2: Admin Edge Preparation​

  • Extract shared legacy-auth helpers from admin_service/app/api/routes/legacy_auth.py for reuse.
  • Add recon_service_url to admin_service settings.
  • Create admin_service/app/services/recon_client.py with timeout, retry, and circuit-breaker behavior.
  • Add admin_service/app/api/routes/legacy_recon.py.
  • Register compatibility routes in admin_service/app/api/routes/api.py.

Phase 3: Recon Service Surface​

  • Create recon_service app skeleton with health endpoint and internal route module layout.
  • Implement internal APIs for:
    • Pushbullet device list/add/delete
    • recharge template list/add/delete
    • phone whitelist list/add/delete
    • SMS list/get/reset/check
    • shooter device list/trust/delete
  • Keep stored field semantics compatible with old shooter data.

Phase 4: Worker Runtime​

  • Create recon_worker runtime structure.
  • Implement worker loops for:
    • Pushbullet init/listen
    • missing-SMS sync
    • Telegram ingestion
    • SMS ID sync
    • whitelist validation
    • template parsing
    • order matching
  • Add a dedicated retry/compensation loop after compatibility cutover. Current v2 recovery is the manual /shooter/sms/reset path rather than an autonomous worker loop.
  • Add freshness-based worker health state instead of plain liveness-only heartbeat.

Phase 5: Admin Top-Info Integration​

  • Add a recon_service internal top-info endpoint or equivalent stats endpoint.
  • Update admin_service top-info aggregation to include sms_need_check_cnt.
  • Trigger forced WS refreshes after meaningful recon state changes.

Phase 6: Approval Boundary Verification​

  • Keep /api/admin/shooter/sms/check as review-state persistence only.
  • Keep final approval flowing through admin_service and wallet_service.
  • Verify that matched order_id handling does not bypass wallet ownership.

Phase 7: Compose and Deployment​

  • Add recon_service and recon_worker to local compose.
  • Add healthchecks for both.
  • Make admin or dependent services wait on required healthy dependencies where appropriate.
  • Extend compose contract tests.

Test Plan​

  • Add admin_service compatibility tests for all preserved shooter/pushbullet routes.
  • Add recon_client tests.
  • Add recon_service route tests.
  • Add recon_worker health freshness tests.
  • Add top-info aggregation tests.
  • Add compose contract tests.

Risks​

  • legacy token/session behavior may drift if recon compatibility routes do not reuse the exact helper path
  • worker loops may appear healthy if only process heartbeat is tracked
  • unresolved /shooter/device/* scope can leave hidden front-end breakage
  • direct recon-to-wallet writes would violate the single money writer rule
  • shooter tables are not yet present in shared v2 migrations and must be introduced before local full-stack verification

Done Definition​

This plan was completed when:

  • compatibility routes are stable for bo/admin
  • hidden compatibility callers such as ShooterDevicesView are also covered
  • recon worker health reflects real loop freshness
  • top-info includes recon state
  • final approval still flows through wallet ownership
  • tests cover compatibility, health, and deployment contracts