물리 장치 이벤트 로그 클라이언트 가이드

대상 독자: 키오스크/CCU/카드단말 등 장치 클라이언트 개발자, 그리고 장치를 인증·수신하는 서비스(키오스크 API, 디바이스 게이트웨이) 개발자. 기존 audit 자동 캡처 체계(Prisma extension + Mutation 자동 래핑, ADR-0007 참고)는 core-svc의 GraphQL mutation과 DB 쓰기를 기준으로 동작한다. 물리 장치가 보내는 이벤트는 이 경로를 그대로 타지 않는 경우가 많아 — 화면 진입처럼 DB 쓰기가 없는 사용자 행위, 카드단말 불량처럼 core-svc mutation이 아닌 이벤트 — 별도 계약이 필요하다. 이 계약의 구체적 구현이 subscription-svc의 reportDeviceEvents다(§2).

1. 이벤트 분류 2종

분류	category	설명	예시
사용자 행위 이벤트	`BEHAVIOR`	게스트가 장치를 조작한 행위. 고볼륨	`kiosk.screen.entered`, `kiosk.checkin.started`, `kiosk.checkin.completed`, `kiosk.payment.attempted`, `kiosk.payment.failed`
장치 상태/헬스 이벤트	`DEVICE_HEALTH`	장치 자체의 상태 변화, 장애	`device.card_reader.fault`, `device.printer.paper_out`, `ccu.connection.lost`, `ccu.door.opened`

category와 severity(INFO/WARN/ERROR/CRITICAL)는 별도 분류 필드로 둔다 — actionType=EVENT 하나로 뭉뚱그리지 않는다. 화면 진입처럼 고볼륨인 BEHAVIOR 이벤트는 보존기간과 기본 조회 노출 정책(예: 기본 조회에서 제외, 별도 조회에서만 노출)을 DEVICE_HEALTH와 분리할 수 있어야 하기 때문이다.

2. 수집 경로 & 신뢰 경계 원칙

장치는 audit-svc에 직접 쓰지 않는다. 수신 서비스는 apps/subscription-svc에 신설하는 GraphQL 배치 mutation reportDeviceEvents 다 — 같은 서비스가 이미 publishAccommodationNotification으로 업장 알림을 처리하고 있고, 장치 인증 접근 제어(isKioskSelf/isCcuSelf, apps/subscription-svc/src/graphql/helpers/accessControl.ts)도 거기 갖춰져 있으므로 새 서비스를 만들지 않고 그 위에 얹는다. 용도 구분: publishAccommodationNotification은 프런트/키오스크 화면에 실시간으로 보여줄 알림(pubsub 구독 대상)이고, reportDeviceEvents는 화면에 보여주지 않는 이벤트 로그(audit 파이프라인 적재 전용)다. 알림이 필요 없는 화면 진입·장치 헬스 이벤트를 알림 mutation에 얹지 않는다. 호출 흐름:

키오스크/CCU가 게이트웨이를 경유해 장치 인증 컨텍스트(context.extra.user.kioskId 또는 .ccuId)를 갖고 reportDeviceEvents를 호출한다.
resolver가 isKioskSelf/isCcuSelf로 요청의 deviceId가 인증된 장치 본인인지 검증한다 — requestAdultAuthentication(apps/subscription-svc/src/graphql/resolver/notification.ts:223)이 쓰는 것과 동일한 패턴: isKioskSelf(context.extra, { kioskId })가 거짓이면 즉시 거부.
accommodationId는 요청 바디 값을 그대로 믿지 않는다. requestAdultAuthentication이 kioskAccommodationId !== accommodationId일 때 KIOSK_ACCOMMODATION_MISMATCH로 거부하듯, subscription-svc가 인증된 장치의 등록 정보(context.extra.user.accommodationId)에서 조회한 값과 요청값을 대조해 불일치 시 거부한다.
subscription-svc가 actorType/contextId 등을 enrich한 뒤 기존 audit 파이프라인(publishAuditLogBatch)으로 발행한다.

accommodationId, kioskId 등 장치 신원에 관한 값은 장치가 주장하는 값을 신뢰하지 않는다. resolver가 인증 컨텍스트에서 서버 측이 직접 조회해 채운다.
장치가 보낸 페이로드의 accommodationId/kioskId 필드는 참고용으로만 취급하고, 서버가 조회한 값과 다르면 요청을 거부한다.

3. 클라이언트 전송 계약

장치가 이벤트를 보낼 때 요청에 실어야 하는 필드:

필드	필수	설명
`eventId`	✅	장치가 생성하는 ULID/UUID. 오프라인 재전송 시 서버 측 멱등 키로 쓰인다
`occurredAt`	✅	장치 로컬 시각(ISO 8601). 서버는 수신 시각을 `receivedAt`으로 별도 기록하고 둘의 차이(클럭 스큐)를 모니터링한다
`eventType`	✅	이벤트 카탈로그에 등록된 안정적인 점(dot) 표기 이름 (예: `kiosk.screen.entered`)
`category`	✅	`BEHAVIOR` \| `DEVICE_HEALTH`
`severity`	✅ (기본값 `INFO`)	`INFO` \| `WARN` \| `ERROR` \| `CRITICAL`
`deviceId`	✅	장치 고유 식별자 (예: kioskId)
`sessionId`	선택	게스트 세션/체크인 플로우 식별자
`resourceRefs`	선택	알고 있는 대상 리소스 참조 (`reservationId`, `roomId` 등)
`payload`	선택	이벤트별 최소 필드만. 10KB 이내 권장, 초과 시 `rejected(PAYLOAD_TOO_LARGE)`로 명시 거부(절단 아님 — ADR-0007 §2.4 참고)

금지 필드 (payload에 절대 포함 금지)

카드번호/트랙데이터, 비밀번호, 인증 토큰 원문, 주민등록번호 등. 서버 측 캡처 계층도 재귀 마스킹(libs/audit/src/extension/mask.ts)을 거치지만, 클라이언트가 애초에 보내지 않는 것이 원칙이다 — 마스킹은 마지막 방어선이지 전송 허용 기준이 아니다.

배치 전송 API — `reportDeviceEvents`

오프라인 버퍼 플러시를 위해 단건이 아닌 배열 + 부분 성공 응답 형태를 기본으로 제공한다. subscription-svc의 GraphQL mutation이다.

type Mutation {
  reportDeviceEvents(input: ReportDeviceEventsInput!): ReportDeviceEventsResult!
}

input ReportDeviceEventsInput {
  kioskId: String   # kioskId, ccuId 중 정확히 하나만 제공 — isKioskSelf/isCcuSelf 검증 대상
  ccuId: String
  accommodationId: String!  # 서버가 인증 컨텍스트와 대조, 불일치 시 거부
  events: [DeviceEventInput!]!
}

input DeviceEventInput {
  eventId: String!
  occurredAt: DateTime!
  eventType: String!
  category: DeviceEventCategory!   # BEHAVIOR | DEVICE_HEALTH
  severity: DeviceEventSeverity! = INFO
  deviceId: String!
  sessionId: String
  resourceRefs: JSON
  payload: JSON
}

type ReportDeviceEventsResult {
  accepted: [String!]!      # eventId 목록
  duplicated: [String!]!    # 이미 처리된 eventId — 클라이언트는 accepted와 동일하게 버퍼에서 제거
  rejected: [RejectedDeviceEvent!]!
}

type RejectedDeviceEvent {
  eventId: String!
  reason: String!
}

4. 오프라인/재시도 시맨틱

로컬 버퍼: 장치는 네트워크 단절 시 이벤트를 로컬에 버퍼링한다. 버퍼는 상한(건수)과 보존 시간을 둔다.
재시도: 지수 백오프 + jitter로 재전송한다.
전달 보장: at-least-once를 전제한다 — 서버가 eventId 기준 dedup을 책임지므로 클라이언트는 중복 전송을 두려워하지 않아도 된다.
전송 우선순위: 버퍼가 가득 찼거나 네트워크가 간헐적일 때 우선순위 순서로 플러시한다.
1. 결제/보안 관련 이벤트 (kiosk.payment.*, device.card_reader.*)
2. 장치 헬스 이벤트
3. 화면 이동 등 저우선순위 BEHAVIOR 이벤트
버퍼 초과 시 드롭 정책: 오래된 BEHAVIOR 이벤트부터 드롭한다. DEVICE_HEALTH와 결제 관련 이벤트는 최대한 보존한다.

5. actorType 매핑 (확정)

이벤트 주체	actorType
키오스크 상 게스트 행위 (체크인, 결제 등)	`KIOSK`
장치 자체 상태 변화 (카드단말 불량, 용지 부족 등)	`DEVICE`

AuditActorType(libs/audit/src/context/audit-context.ts)에 DEVICE를 추가한다. reportDeviceEvents는 이벤트별 category를 보고 enrich 단계에서 BEHAVIOR → KIOSK, DEVICE_HEALTH → DEVICE로 매핑해 채운다.

6. 서버측 수신 서비스 체크리스트 (`subscription-svc` · `reportDeviceEvents`)

장치 신원 검증 — resolver가 인증 이전에 kioskId/ccuId가 정확히 1개만 제공됐는지 확인한다. 둘 다 없거나 둘 다 있으면 INVALID_DEVICE_IDENTITY로 즉시 거부.
장치 인증 — isKioskSelf/isCcuSelf(accessControl.ts)로 요청의 kioskId/ccuId가 인증 컨텍스트(context.extra.user)의 장치 본인인지 검증. 불일치 시 KIOSK_AUTH_REQUIRED 등으로 즉시 거부.
accommodationId 대조 — 인증된 장치의 등록 accommodationId와 요청의 accommodationId를 대조, 불일치 시 KIOSK_ACCOMMODATION_MISMATCH로 거부(requestAdultAuthentication과 동일 패턴).
스키마 검증 — eventId/occurredAt/eventType/category 필수 필드와 eventType 카탈로그 존재 여부를 확인.
eventId 멱등 — 이미 처리된 eventId는 accepted가 아니라 duplicated로 응답하고 재처리하지 않는다.
Enrich — accommodationId(§2)/actorType(§5)/contextId를 서버가 직접 채운다. 장치가 보낸 값은 무시하거나 대조용으로만 쓴다.
Audit 파이프라인 발행 — publishAuditLogBatch(@vpms-cluster/audit)를 호출한다. ADR-0007의 outbox 전환은 이 호출의 내부 구현만 바뀌므로 reportDeviceEvents 쪽 코드 변경은 없다.

7. 이벤트 예시

예시 1 — 화면 진입 배치 (BEHAVIOR)

reportDeviceEvents mutation 호출 변수:

{
  "input": {
    "kioskId": "kiosk-gangnam-01",
    "accommodationId": "acc-01J7X1...",
    "events": [
      {
        "eventId": "01J8X9K3QZ7R2M4N5P6Q7R8S9T",
        "occurredAt": "2026-07-10T09:15:32.104+09:00",
        "eventType": "kiosk.screen.entered",
        "category": "BEHAVIOR",
        "deviceId": "kiosk-gangnam-01",
        "sessionId": "sess-01J8X9K3QZ",
        "payload": { "screenName": "checkin-guest-info" }
      },
      {
        "eventId": "01J8X9K3R18F3N5P6Q7R8S9T0U",
        "occurredAt": "2026-07-10T09:16:01.552+09:00",
        "eventType": "kiosk.checkin.started",
        "category": "BEHAVIOR",
        "deviceId": "kiosk-gangnam-01",
        "sessionId": "sess-01J8X9K3QZ",
        "resourceRefs": { "reservationId": "01J7Y2..." },
        "payload": {}
      }
    ]
  }
}

예시 2 — 카드단말 불량 (DEVICE_HEALTH)

{
  "input": {
    "kioskId": "kiosk-gangnam-01",
    "accommodationId": "acc-01J7X1...",
    "events": [
      {
        "eventId": "01J8X9M5V2W4X6Y8Z0A1B2C3D4",
        "occurredAt": "2026-07-10T09:20:11.884+09:00",
        "eventType": "device.card_reader.fault",
        "category": "DEVICE_HEALTH",
        "severity": "ERROR",
        "deviceId": "kiosk-gangnam-01",
        "payload": {
          "faultCode": "READER_TIMEOUT",
          "reader": "MSR-206"
        }
      }
    ]
  }
}

주의: 두 예시 모두 카드번호/트랙데이터를 포함하지 않는다. 카드단말 불량 페이로드는 장애 코드와 리더 식별자만 담고, 실제 카드 데이터는 절대 포함하지 않는다(§3 금지 필드 참고).

​1. 이벤트 분류 2종

​2. 수집 경로 & 신뢰 경계 원칙

​3. 클라이언트 전송 계약

​금지 필드 (payload에 절대 포함 금지)

​배치 전송 API — reportDeviceEvents

​4. 오프라인/재시도 시맨틱

​5. actorType 매핑 (확정)

​6. 서버측 수신 서비스 체크리스트 (subscription-svc · reportDeviceEvents)

​7. 이벤트 예시

​예시 1 — 화면 진입 배치 (BEHAVIOR)

​예시 2 — 카드단말 불량 (DEVICE_HEALTH)