LinkOStar

데이터 모델

주요 엔티티와 그 관계를 정리합니다. 엔티티 컬럼 단위 풀스펙은 OpenAPI의 component schema 섹션을 참조하세요 — 코드 변경 시 자동 동기화됩니다.

핵심 관계 한눈에

Tenant (= Supplier)
  ├── SupplierBundle ── ProvisioningStep × N
  │        │           ── ManagedApp × N
  │        │           ── BundleDevice × N
  │        └─ 발급 ──▶ HubClaimCode ── (claim) ──▶ HubInstance
  │                                                  │
  │                                                  ├── HubInstalledApp × N
  │                                                  ├── HubProvisioningRun × N  (step 진행 상태)
  │                                                  ├── HubTelemetry × N
  │                                                  ├── HubLog × N
  │                                                  └── HubAuthToken (1:1, refresh로 access만 갱신)
  │
  └── ConsentSetting × N      DataPipeline × N      Persona / Access × N

엔티티 요약

Tenant

LinkOStar에서 가장 위의 격리 단위. Supplier 1개 = Tenant 1개. 모든 리소스는 tenant_uuid를 컬럼으로 들고 있고, API 호출엔 X-Tenant-UUID 헤더로 scope을 지정합니다.

SupplierBundle (= 출시 패키지)

Supplier가 hub claim 시점에 자동으로 적용할 셋을 묶은 것. 다음 자식을 가집니다.

  • ProvisioningStep: 사용자 onboarding 위저드 단계. type별 config (TEXT_INPUT, EXTERNAL_LIST_PICK, CONFIRM, INFO, CUSTOM).
  • ManagedApp: hub에 자동 설치/관리할 supplier 앱.
  • BundleDevice: bundle 적용 시 함께 등록할 device 정의 (auto_provision 가능).
  • agentChannel: 해당 bundle이 고정할 hub-agent 채널 (stable/beta/canary).

상태머신: DRAFT → PUBLISHED → ARCHIVED. DRAFT 만 mutation 허용.

HubClaimCode

Supplier가 발급하는 일회성/제한 사용 코드. supplier_uuid + bundle_uuid를 들고 있어서 claim 시점에 자동으로 expand 됩니다. 상태:

  • PENDING — 발급됨, 아직 hub가 사용 안함
  • USED — 하나 이상의 hub가 사용함
  • EXPIRED — 발급 24시간 등 정책 만료
  • REVOKED — 운영자가 수동 무효화

HubInstance

물리 hub(보통 Pi)를 가리키는 엔티티. 핵심 컬럼:

  • hub_uuid (PK), tenant_uuid, supplier_uuid, bundle_uuid
  • device_instance_id: hub-agent가 보내는 식별자 (보통 MAC 기반 해시)
  • hub_identifier: 사용자에게 보일 별칭 (claim 시 입력)
  • hub_type: OPEN / CLOSED
  • mac_address

HubAuthToken

Hub 당 1행. access_token + refresh_token 을 들고 있고, refresh는 access만 갱신합니다. Hub bearer 가 도착하면 이 행에 byte 단위 비교로 매칭.

HubProvisioningRun

Bundle이 claim 시점에 expand 되며 만들어지는 행. step별 진행 상태:

  • PENDING — 아직 진행 안 됨
  • SUBMITTED — 사용자가 입력 완료, submittedValue 저장됨
  • SKIPPED — 사용자가 건너뜀
  • FAILED — 검증 실패

HubTelemetry / HubLog

Hub-agent가 60s 주기로 보내는 telemetry는 hub_telemetry.payload_json에 JSON 그대로 저장. 로그도 동일 패턴 (hub_log). 시계열 인덱스 (hub_uuid, received_at).

UUID 표기

모든 UUID 컬럼은 DB에서 BINARY(16). API에서는 표준 hyphen 포함 string ( e02bf423-22fc-4862-a8f8-bbf23ae9eccd ) 으로 직렬화됩니다. 통합 측에서는 그대로 string 으로 다루세요.

시각 표기

모든 timestamp 은 UTC 기준 ISO-8601 (2026-06-04T12:34:56.789Z). DB 내부는 timestamp(3).