01 / 03
실행 경로
| 환경 | 요청 흐름 | 저장 또는 실행 위치 |
|---|
| Windows 앱 | EXE 런처 → Node 로컬 서버 → WebView2 → 중앙 게이트웨이 | 로컬 화면·기기, 중앙 계정·광고 |
| 외부 웹 | HTTPS 사이트 → 고정 게이트웨이 → TAK5090 18791 | 브라우저 세션과 중앙 서비스 |
| 광고 콘텐츠 | 매장 manifest → 자산 다운로드 → 검증 → 적용 ACK | 브라우저 캐시와 중앙 배포 기록 |
| 생성·통번역 | 앱 → 허용된 계정·AI 중계 → 현재 AI 연결 | 현재 서버 가용량과 요청 상태 |
| 공식 콘텐츠 | Windows 전용 보기 또는 웹 공식 사이트 새 창 | OTT 자체 로그인·DRM 정책 |
Windows 패키지는 Node와 앱 파일을 포함하고 WebView2 Runtime이 필요하다. 기본 로컬 포트는 18791이며 미러베어의 18771과 구분한다. 별도 화면 선택과 전체화면을 지원한다. 외부 웹의 HTTPS 주소는 독립 클라우드로 AI·DB가 이전됐다는 뜻이 아니며 TAK5090 서비스와 인터넷 연결에 의존한다.
권한과 데이터 경계
공개 웹의 세션 쿠키는 HttpOnly·Secure·SameSite=Strict로 제한하고 변경 요청은 Origin과 CSRF를 확인한다. 게이트웨이는 고정 경로와 고정 로컬 서버만 중계한다. 임의 URL·포트 접근과 원격 Windows 프로그램 실행을 허용하지 않는다. 기존 Android native relay는 별도 경로로 보존한다.
본사 광고 권한과 점주 매장 범위를 서버에서 확인한다. 고객·사진의 로컬 저장 범위와 중앙 계정·광고 기록을 구분한다. 통합 관리자에서 제품을 선택할 수 있어도 운영 헤어베어/H.SET 회원·결제 DB 연동이 완료된 것은 아니다.
근거: server/server.mjs, desktop-native/README.md, sites/mirrorbear-connect/lib/motion-web.mts, mirrorbear-app/remote-gateway/server-motion-web.mjs, web/src/storage.ts.
02 / 03
광고 API와 데이터
| 경로 묶음 | 주요 기능 | 확인할 조건 |
|---|
| /api/motion/admin/ads-console | 본사·점주 현황과 역할별 데이터 | 로그인·역할·매장 범위 |
| /admin/ad-assets 및 /admin/ads-campaigns | 소재와 캠페인 생성·수정·삭제 | 파일 형식·크기·참조·revision |
| /admin/ad-contracts | 매장별 월 계약과 월분 생성 | 기간·지역·중복 계약·요금 스냅샷 |
| /admin/ad-settlements | 확정·지급 기록 | 정상 상태 전이·동시 중복 방지 |
| /admin/ad-deployments | 선택 매장별 편성표 게시 | 버전·자산 SHA-256·계약 범위 |
/media/manifest
/media/assets/{id} | 배포본과 인증된 자산 제공 | 대상 매장·버전·MIME·바이트·해시 |
/media/heartbeat
/media/ack | 기기 연결·콘텐츠 적용 상태 | 등록 기기·버전·최신 게시본 |
첫 행 이후 경로는 /api/motion 접두부 아래의 상대 경로다. 표의 소재·캠페인 경로는 구현 파일의 실제 HTTP 메서드와 전체 경로를 함께 확인한다. 요청 본문은 허용 항목만 받고 revision 충돌은 409로 돌려준다. CSV 내보내기와 화면 합계는 같은 월분 데이터를 기준으로 대조한다.
자산 검증과 관찰
다운로드 데이터는 MIME·바이트 크기·SHA-256을 확인하고 Blob URL로 표시한다. 편성표 전체의 해시도 검증한다. 관리자에서의 소재 미리보기와 기기의 광고 재생 보고를 구분한다. 원본 로고·가격·문구를 손상 없이 보여 주는 것은 자동 해시 검증 외에 시각 검수가 필요하다.
근거: server/ads-api.mjs, web/src/motionAdPlayback.ts, MotionAdConsole.tsx. 상세 스키마의 유일 기준은 현재 소스이며 이 문서는 API 전체 명세의 대체물이 아니다.
03 / 03
콘텐츠 OTA의 실제 범위
- 관리자가 매장별 캠페인을 게시하면 버전과 해시가 있는 편성표를 만든다.
- 기기는 약 30초 간격으로 확인하고 자산을 해시 주소 캐시에 먼저 준비한다.
- 모든 파일이 검증된 뒤 활성 편성표를 일괄 교체한다. 부분 다운로드를 새 정상 편성으로 표시하지 않는다.
- 적용 결과를 ACK로 보낸다. 관리자는 게시 버전·기기 적용 버전·최근 연결을 각각 읽는다.
- 연결 장애 시 마지막 검증 시각을 기준으로 저장본의 사용 여부를 판정한다. 현재 기준 15분 경과 후 다음 확인에서 만료본을 기본 화면으로 전환한다.
| 업데이트 종류 | 현재 상태 | 운영 시 주의 |
|---|
| 광고 콘텐츠 | 버전·해시·자산·ACK 구현 | 장기 캐시 정리와 현장 장애 시험 필요 |
| 외부 웹 | 서버의 최신 빌드로 제공 | 다운로드 EXE의 내장 웹과 다를 수 있음 |
| Windows 0.2.0 EXE | 고정 배포본·패키지 해시 검증 | 기존 파일을 같은 버전으로 덮어쓰지 않음 |
| 서명된 무인 바이너리 OTA | 완료하지 않음 | 서명·권한·서비스·롤백 정책과 실기 시험 필요 |
운영 인계와 장애 대응
관리자 복귀 수정은 광고 레일을 숨긴 채 유지하고 비활성 동안 미디어·타이머·노출 보고를 멈추는 방식이다. 외부·로컬 각 5회 왕복 표시를 확인했으나 원래의 영구 로딩 자체는 직접 포착하지 못했다. 이번 반영은 현재 웹이며 고정 0.2.0 EXE는 변경하지 않았다. 장애 기록에는 시각·화면·기기·게시/적용 버전을 남기고 비밀키·쿠키는 제외한다.
장기 장애 복구를 위해 마지막 정상 배포의 롤백, 오프라인 전환, 캐시 만료, 계정 해제, 디스크 부족을 현장 프로토콜로 시험한다. 네트워크·장비 장애가 다른 매장 권한의 데이터나 광고로 대체되는 동작은 허용하지 않는다.
근거: motionAdPlayback.ts, adPlaybackLogic.mjs, server/ads-api.mjs, desktop-native/RELEASE-0.2.0.md, verification/ads-20261104/public-web-verification.json. 무인 EXE 업데이트는 별도 미완료 범위다.