아키텍처

LinkOStar는 IoT hub의 연결성·셋업·관제를 supplier-agnostic 하게 제공합니다. Supplier는 자기 비즈니스 로직(예: 디바이스 모델, 알람 정책)을 자기 BFF/앱에 두고, LinkOStar는 raw resource 만 노출합니다.

컴포넌트 한눈에

┌────────────────────────────────────────────────────────────────────────┐
│                     LinkOStar (공유 플랫폼)                            │
│                                                                        │
│   ┌─────────────────┐   ┌────────────────┐   ┌─────────────────┐       │
│   │  Web Console    │   │  Mobile App    │   │  Backend API     │      │
│   │  (Next.js)      │   │  (Flutter)     │   │  (Spring Boot)   │      │
│   │  /tenant/**     │   │  /app/**       │   │                  │      │
│   └────────┬────────┘   └────────┬───────┘   └────────┬─────────┘      │
│            │                     │                    │                 │
│            └─────────────────────┴────────── REST ────┤                 │
│                                                       │                 │
│                                              ┌────────┴────────┐        │
│                                              │  MySQL +        │        │
│                                              │  (later) MQTT   │        │
│                                              └────────┬────────┘        │
│                                                       │                 │
│                                          ┌────────────┘                 │
│   ┌─────────────────────┐                │                              │
│   │  Hub-Agent (Pi)     │◀── /v1/** ────┘                              │
│   │  Go binary +        │                                                │
│   │  systemd            │                                                │
│   └────────┬────────────┘                                                │
│            │ BLE                                                         │
│            │ MQTT (선택)                                                 │
│            ▼                                                             │
│   ┌─────────────────────┐                                                │
│   │  Bluetooth devices  │                                                │
│   │  (예: 비콘, 센서)    │                                                │
│   └─────────────────────┘                                                │
└─────────────────────────────────┬──────────────────────────────────────┘
                                  │ X-API-Key + X-Tenant-UUID
                                  │ JWT (sdx-oauth)
                                  ▼
                  ┌──────────────────────────────┐
                  │  Supplier BFF (예: EDS BFF)  │
                  │  자기 비즈니스 집계/매핑       │
                  └───────────┬──────────────────┘
                              │
                              ▼
                  ┌──────────────────────────────┐
                  │  Supplier UI (운영자 콘솔)   │
                  │  / End-user 앱               │
                  └──────────────────────────────┘

주요 흐름

1. Hub Claim (최초 boot)

1. Supplier 가 web 콘솔에서 HubClaimCode 발급 (또는 installer가 자동 발급).
2. Installer가 SD에 OS 이미지 + boot config (linkostar-config.json: claim_code, supplier_uuid, backend_url) 굽기.
3. Pi 부팅 → hub-agent → bootconfig 발견 → POST /v1/hubs/claim
4. Backend가 claim_code 검증 + HubInstance 생성/재사용 + HubAuthToken 발급 + BundleClaimExpansion 실행.
5. Hub-agent가 응답으로 hub_uuid + accessToken + refreshToken 받아 state.json에 저장.

2. Telemetry 수집 (정상 운영)

1. Hub-agent의 reconciler가 60s 주기로 POST /v1/hubs/{uuid}/telemetry.
2. Backend가 hub_telemetry 행 INSERT.
3. Supplier UI/Web 콘솔에서 GET /tenant/hub-monitoring/{uuid}/telemetry 로 조회.

3. BLE 셋업 (Mobile)

1. Pi 부팅 → hub-agent가 BLE GATT advertise (LinkOStar service UUID).
2. Mobile app이 BLE scan → 매칭 → connect.
3. WiFi scan / 자격 주입 → hub WAN 연결 → telemetry 첫 성공.
4. ConnectivityMonitor 가 healthy 판정 → BLE 광고 OFF.
5. 이후 telemetry 실패가 N회 연속이면 광고 자동 재ON (재셋업 가능).

4. Supplier Step Wizard

1. Supplier가 web에서 ProvisioningStep 정의 (BUILDER UI).
2. Claim 시점에 BundleClaimExpansionService가 step → HubProvisioningRun으로 expand.
3. End-user가 web/mobile에서 단계 진행 → POST /tenant/hubs/{uuid}/provisioning/steps/{stepId}/submit.

책임 경계 (Supplier가 만들어야 할 것)