IF-03 조회 서비스 (JBNU FacOS 테스트베드)

JBNU 의 FacOS 테스트베드다. IF-03 데이터 소비 규약에 따라 저장된 제조 데이터를 조회·스냅샷·내보내기 한다. 모든 데이터 API 는 접근 토큰(Authorization: Bearer <토큰>)이 필요하다. 권한(현장, 데이터셋 × 목적)은 토큰에 담겨 있다.

문서내용
아키텍처시스템 구성, 데이터 흐름, 시각 정렬(시간 지연 계산), 저장, 조회 서비스 — 이 페이지 아래
SDK 매뉴얼파이썬 SDK databahn 설치·사용법·예제
API 명세엔드포인트, 요청·응답 필드, 오류 코드, 규약 대응
대화형 API브라우저에서 직접 호출 (Swagger UI). 기계용 명세: /openapi.json
SDK 내려받기wheel 패키지, Foxglove 이미지 변환 확장(.foxe)
/healthz서비스·카탈로그 자동 동기화 상태

SDK 설치

pip install "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
from databahn import Fabric
fab = Fabric("https://if03.data-bahn.com", api_key="<접근 토큰>")
b = fab.read(dataset_id="plab-testbed-cell01", start="2026-11-16T17:53:00+09:00",
             end="2026-11-16T17:54:00+09:00", purpose="analysis")

시스템 아키텍처와 구현 내용

SO-ARM101 로봇팔(리더·팔로우)과 카메라 두 대에서 나오는 제조 데이터를 시간 동기화·정합 규약(TS-01~06) 에 맞춰 정렬·기록하고, IF-03 데이터 소비 규약 에 맞춰 조회·내보내기까지 제공하는 테스트베드다. 목적은 두 규약의 구조를 실제 장치와 실제 데이터로 검증하는 것이다.

so101 테스트베드 아키텍처

1. 데이터가 흐르는 순서

  1. 장치 드라이버(LeRobot, OpenCV)로 팔과 카메라를 읽는다.
  2. 수집기가 리더암 관절을 읽어 팔로우암에 명령을 보내고(원격 조종), 받은 순간의 컴퓨터 시각(ts_gateway)과 채널별 번호(seq)를 시각 헤더에 담아 protobuf 메시지로 MQTT 에 발행한다.
  3. MQTT 브로커가 메시지를 셀 로거에 전달한다. QoS1·지속 세션이라 셀 로거가 잠시 늦어도 잃지 않는다.
  4. 동기 에이전트가 1분마다 NTP 로 컴퓨터 시계가 표준시와 얼마나 다른지 재서 같은 브로커로 보낸다. 시계를 고치지는 않는다.
  5. 셀 로거가 메시지를 받은 시각(ts_ingest)을 찍고, 옆의 시간 지연 계산기(사이드카)에 시각 헤더와 시계 오차 측정값을 넘긴다. 계산기는 장치 지연을 빼 실제 사건 시각을 추정하고, 그 추정이 얼마나 틀릴 수 있는지(불확도)와 등급을 돌려준다. 셀 로거는 그 결과로 MCAP 파일에 기록하고, 같은 결과를 붙여 정렬 스트림(aligned/<채널>)으로 곧바로 다시 발행한다. 모델의 실시간 입력은 이 스트림이다.
  6. 파일이 닫히면(10분 경계, 30초 무입력, 2 GB, 종료) 업로더가 중앙 패브릭의 수집 경로에 올린다. 덮어쓰지 않고, SHA-256 으로 확인한다.
  7. 서버의 조회 서비스가 30초마다 수집 경로를 처리한다: 파일을 검사·색인해 저장소와 카탈로그(PostgreSQL)에 등록하고, 실패한 파일은 격리해 사유를 돌려준다.
  8. 소비자는 Python SDK, Foxglove(MCAP 내보내기), REST API 로 데이터를 쓴다. 녹화 후 조회까지 최대 약 11분.
  9. IF-20(그림 오른쪽, 같은 EKS)은 모델을 다룬다. 학습 Job 이 스냅샷으로 학습해 MLflow 에 학습 이력을 남기고 IF-20 에 등록하면, IF-20 이 서명해 Triton 으로 배포하고 추론을 받는다. 참조 전달 추론은 IF-20 이 호출자 대신 IF-03 에서 읽는다. MLflow 는 인증 모드라 쓰기는 학습 Job 과 IF-20 만 할 수 있다. 자세한 것은 docs/if20-phase1-design.md, API 는 API 명세 10장.

2. 셀 — 로컬 (수집에서 데이터 레이크까지)

구성 요소 하는 일 구현 요점
장치 리더암·팔로우암 (Feetech STS3215 서보 6개씩), 손목·탑 카메라 (UVC) 관절 위치·명령·온도·전압, JPEG 640×480 30 fps 영상
장치 드라이버 팔·카메라 입출력 팔: LeRobot SOLeader/SOFollower (Feetech 서보 버스, USB 시리얼, 60 Hz, 보정은 lerobot-calibrate). 카메라: OpenCV (macOS AVFoundation)
수집기 collector 장치 읽기, 원격 조종, 메시지 발행 모든 메시지에 시각 헤더(TS-03): 채널 ID, seq, ts_gateway, 시각 근거, 시계 동기 상태, 프로파일 버전. 관절은 읽기 요청 직전 시각도 함께 기록. 작업자가 입력한 작업 시작·끝(에피소드)도 발행. 장치가 끊기면 안전하게 멈춘다
MQTT 브로커 셀 단위 메시지 전달 Mosquitto(로컬), QoS1, 지속 세션. 시각을 만들지 않는다
동기 에이전트 sync_agent 컴퓨터 시계 오차 측정 (TS-05) 1분마다 NTP 측정 → ntp_state(오프셋, 오차 한계, 상태) 발행. 시계를 고치지 않는다 (3.4)
셀 로거 cell_logger 받기·기록·정렬 스트림 받은 시각 ts_ingest 기록, 시각 계산은 계산기에 묻는다. 계산 결과를 붙여 곧바로 정렬 스트림 발행(재정렬 버퍼·파일 닫기를 기다리지 않음). 2초 재정렬 버퍼로 추정 시각 순서로 쓰고, 10분 파일·묶음별(arm·cam·context·sync) 분리, manifest 작성. 카탈로그에는 쓰지 않는다
시간 지연 계산기 align_sidecar 장치 지연을 빼 실제 시각·불확도·등급 계산 (3장) 셀 로거 옆 별도 프로세스(사이드카). 로컬 소켓으로 메시지마다 요청·응답. 채널 프로파일, 채널별 seq, 시계 상태를 가진다. 계산은 정렬 엔진(align_engine, 버전을 기록마다 남김)
업로더 uploader 수집 경로에 올리기 닫힌 파일만, 조건부 쓰기(If-None-Match)로 덮어쓰기 금지, 업로드 전후 SHA-256 대조, 64 MB 넘으면 멀티파트, MCAP 먼저·manifest 마지막. 수집 결과를 받아 로컬 파일을 통과(uploaded/)·격리(rejected/)로 나눈다
재정렬 도구 fabric.realign 계산 근거가 바뀐 구간을 다시 계산 (3.6) 관리자가 수동으로 실행. 셀 로거와 같은 정렬 엔진. 결과를 업로더가 수집 경로에 올린다

채널 시각 프로파일(TS-02)은 채널마다 시각 기준점, 사건 시점, 지연 모델(d, b), 최소 식별 간격, 기대 등급을 적은 파일이다. 계산기는 이 프로파일로 계산하고, 조회 서비스는 같은 프로파일로 품질을 판단한다. 프로파일 사본은 MCAP 안과 S3 _sync/ 에 함께 남긴다.

3. 시각 정렬 — 시간 지연 계산기

3.1 무엇을 계산하나

장치는 자기 시각을 보내지 않는다. 컴퓨터가 데이터를 받은 시각만 안다. 그런데 데이터는 장치에서 컴퓨터까지 오는 데 시간이 걸리므로, 받은 시각은 실제로 측정·촬영한 시각보다 늦다. 계산기는 이 지연을 빼서 실제 시각을 추정하고, 그 추정이 얼마나 틀릴 수 있는지(불확도)를 함께 낸다.

계산 순서 (메시지마다):

  1. 검사 — 등록된 채널인지, 프로파일 판이 맞는지, seq 가 빠지거나 겹치지 않았는지, 받은 시각이 뒤집히지 않았는지 본다. 문제가 있으면 진단 코드를 붙인다 (3.5).
  2. 실제 시각 추정 — 실제 시각 = 받은 시각(ts_gateway) − d. d 는 그 채널의 평균 장치 지연으로, 미리 실측해 채널 프로파일에 적어 둔 값이다.
  3. 불확도 — 불확도 = b + 시계 오차. b 는 지연이 평균에서 벗어날 수 있는 최대 폭(실측), 시계 오차는 그 시점의 컴퓨터 시계가 표준시와 다를 수 있는 폭이다 (동기 에이전트 측정값, 3.4).
  4. 등급 — 불확도로 정한다: 1 ms 이하 Tier-2, 100 ms 이하 Tier-3, 그보다 크면 Tier-4. 시각을 추정할 수 없으면 Tier-U.

예 (컴퓨터 시계 오차가 17 ms 인 때):

받은 시각 d 실제 시각 추정 b 불확도 등급
팔로우 관절 12:00:00.1000 0.6 ms 12:00:00.0994 5 ms 5 + 17 = 22 ms Tier-3
손목 카메라 프레임 12:00:00.1000 36 ms 12:00:00.0640 31 ms 31 + 17 = 48 ms Tier-3

같은 순간에 받았어도 카메라 프레임은 실제로 36 ms 먼저 찍힌 것으로 기록되고, 두 시각은 각각 ±22 ms, ±48 ms 범위 안에서만 믿을 수 있다.

3.2 셀 로거와 계산기 (사이드카)

셀 로거 ── 시각 헤더(채널, seq, ts_gateway, 프로파일 판) + ts_ingest ──▶ 시간 지연 계산기
        ◀── 실제 시각 추정, 불확도, 등급, 진단 코드, 채널 기본값 ──────
셀 로거 ── 시계 오차 측정값(ntp_state, 시계 튐) ──▶ 시간 지연 계산기 (시계 상태 갱신)
셀 로거 ── 쓰기 직전: 이 메시지가 시계 튐 근처인가? ──▶ 시간 지연 계산기
셀 로거 ── 계산 결과를 붙여 곧바로 ──▶ 정렬 스트림 aligned/<채널> (3.8)

3.3 채널별 지연 모델 (프로파일 0.2.0)

채널 시각 기준점 d b 불확도 (시계 약 17 ms) 등급 측정 방법
팔로우 관절 상태 모터 읽기 요청·응답 0.6 ms 5 ms 약 22 ms Tier-3 요청 직전·응답 직후 시각의 중간을 측정 순간으로, 텔레오퍼레이션 중 왕복 시간 실측
리더 관절 상태 〃 0.6 ms 6 ms 약 23 ms Tier-3 〃
팔로우 명령 모터 쓰기 0.1 ms 3 ms 약 20 ms Tier-3 〃
모터 온도·전압 (1 Hz) 모터 읽기 1.1 ms 4 ms 약 21 ms Tier-3 〃
손목 카메라 프레임 수신 → 노출 중앙 36 ms 31 ms 약 48 ms Tier-3 팔을 움직이며 영상 변화량과 엔코더 이동량의 상호상관이 최대인 지연 (부트스트랩 95% 구간 + 프레임 지터 + 롤링 셔터)
탑 카메라 〃 40 ms 35 ms 약 52 ms Tier-3 〃
작업자 콘솔 사람 입력 — — — Tier-U 사람 반응 지연은 잴 수 없어 추정하지 않는다

3.4 시계 오차 — 동기 에이전트가 하는 일

동기 에이전트는 컴퓨터 시계를 고치지 않는다 (시계 맞추기는 운영체제의 일이다). 1분마다 NTP 서버와 비교해 "지금 이 컴퓨터 시계가 표준시와 얼마나 다를 수 있는지"를 재서 ntp_state 로 MQTT 에 발행할 뿐이다. 셀 로거가 이것을 받아 계산기에 넘기고, 계산기는 메시지마다 그 시점의 시계 오차를 불확도에 더한다 (3.1 의 3단계). 측정값 자체는 _sync 파일에 근거로 남는다.

시계에 문제가 생기면 이렇게 된다:

상황 계산기의 판단 데이터에 일어나는 일
정상 (최근 3분 안에 측정) locked — 실측 오차 한계 사용 (1 ms 단위로 올림) 불확도 = b + 실측 오차. 보통 Tier-3
시계 오차가 커짐 locked — 큰 오차 그대로 반영 불확도가 커진다. 100 ms 를 넘으면 Tier-4 로 내려간다
측정이 끊김 (10분까지) holdover — 마지막 값 + 드리프트(50 ppm × 경과 시간) 시간이 갈수록 불확도가 커진다, TIM-5031
10분 넘게 측정 없음 unlocked — 시계를 믿을 수 없음 Tier-U (기본 조회에서 빠짐), TIM-5031
시계가 갑자기 바뀜 (step) 그 전후 1초는 시각을 믿을 수 없음 그 구간 Tier-U, TIM-4231 (셀 로거가 쓰기 직전에 한 번 더 확인)

시계 튐은 수집기·동기 에이전트가 "실시간 시계 − 단조 시계"가 1 ms 넘게 바뀌는지로 잡는다. 두 시계를 읽는 사이에 다른 스레드가 끼어들면 가짜 튐이 생기므로(2026-11-18 실기에서 2분에 한 쌍, 그때마다 모든 채널 2초가 Tier-U), 단조 → 실시간 → 단조로 읽어 끼어든 측정은 다시 재고, 바뀐 값이 다음 틱에도 남아 있을 때만 튐으로 확정한다. 확정은 한 틱 늦지만 튐 시각은 처음 본 때로 남긴다.

동기 에이전트가 첫 측정을 보내기 전에는 설정값(10 ms)을 쓴다.

3.5 검사와 진단 코드

코드 뜻 처리
TIM-4011 프로파일이 등록되지 않은 채널, 또는 프로파일 판 불일치 Tier-U
TIM-4091 / TIM-4092 seq 중복 / 건너뜀 (메시지 누락) 중복은 버리고, 건너뜀은 기록·알림
TIM-4221 수집기 시각이 셀 로거 수신 시각보다 늦음 (역전) Tier-U
TIM-4241 지연 미적용 (지연 모델 없음, 또는 계산기 응답 없음) Tier-U → 재정렬로 복구 가능
TIM-4231, TIM-5031 시계 튐, 시계 측정 끊김 3.4

진단 코드는 메시지마다 _align 채널에 남고, 같은 문제가 이어지면 10초 단위로 묶어 알린다.

왜 Tier-3 인가. Tier-2 는 불확도 1 ms 이하다. 지금은 컴퓨터 시계 오차(Wi-Fi NTP 10~20 ms)와 관절의 흔들림 폭(USB 왕복 3~6 ms)이 각각 그보다 크다. 하드웨어 시각 동기(PTP)와 장치 자체 타임스탬프가 있어야 Tier-2 가 된다. Tier-3 는 "수십 ms 안에서 채널끼리 비교 가능"을 뜻하며, 관절 궤적과 영상 프레임을 맞추는 데는 충분하다. 두 사건의 선후는 시각 차가 두 불확도의 합보다 클 때만 판단한다.

3.6 재정렬 도구 — 언제 어떻게

자동으로 돌지 않는다. 정렬 근거가 나중에 바뀌었을 때 관리자가 로컬에서 실행한다.

언제 예
지연 모델이 없던 채널에 모델이 생겼을 때 새 카메라를 붙여 먼저 기록하고(Tier-U, TIM-4241), 지연을 잰 뒤 정렬
지연 모델 값을 고쳤을 때 카메라 지연을 다시 재서 d·b 가 바뀜
계산기가 멈춰 미정렬로 기록된 구간 3.2
uv run python -m fabric.realign plan  --channels <채널>... --profiles profiles/channels   # 대상 파일·메시지 수 확인
uv run python -m fabric.realign apply --channels <채널>... --profiles profiles/channels   # 재정렬본 생성 → 수집 경로 → 수집 검사 → 카탈로그

3.7 정렬 엔진과 버전

계산기(3.1)와 재정렬 도구(3.6)의 시각 계산은 정렬 엔진 한 곳(so101_testbed.align_engine)에 있다. 둘이 같은 코드를 쓰므로 같은 근거로 계산하면 결과가 같다.

항목 내용
지금 버전 1.0.0 (semver)
남기는 곳 채널 메타데이터 align_engine_version(그 채널의 모든 기록), _align 레코드, 재정렬본의 fos.correction, 정렬 스트림, 카탈로그 file_channels
버전을 올리는 때 같은 입력에 다른 결과를 내는 수정 (계산식, 등급 경계, 반올림). 고정 입력·출력 시험이 깨지면 올려야 한다는 뜻이다
버전 이전 파일 2026-11-18 이전 기록은 계산식이 같아 1.0.0 으로 본다

왜 남기나. 같은 구간의 판본이 바뀌었을 때, 그 차이가 근거(지연 모델·시계 측정값)가 바뀌어서인지 엔진을 고쳐서인지 가를 수 있어야 한다. 그래서 근거를 바꾸는 재정렬과 엔진을 바꾸는 재정렬을 한 번에 하지 않는다. 엔진에 결함이 있으면 그 엔진 버전으로 정렬한 구간만 engine_update 사유로 다시 계산한다 (사유는 정의돼 있고, 계산은 아직 없다).

3.8 정렬 스트림 — 모델의 실시간 입력

셀 로거는 메시지를 정렬한 즉시 정렬 결과를 붙여 브로커로 다시 발행한다. 2초 재정렬 버퍼나 파일 닫기(최대 10분)를 기다리지 않는다. 실시간 추론은 이 스트림을 입력으로 쓰고, 그 밖의 추론·학습은 조회 서비스로 받는다. 정렬 전 시각의 브로커 데이터는 모델 입력으로 쓰지 않는다 (학습과 추론이 같은 시간축을 쓰게 하기 위해서다).

항목 내용
토픽 aligned/<채널 ID> — 규약은 토픽 체계를 Fac 규약에 맡겨 아직 없다. 수집기 토픽(testbed/#)과 겹치지 않게 둔 테스트베드 제안값
내용 protobuf AlignedRecord: 채널 ID·seq, 정렬 시각, 정렬 여부·등급·불확도, 원래 시각(장치·수집기), 정렬 엔진 버전, 품질, 진단 코드, 수집기 메시지 원본
짝 맞추기 같은 메시지는 채널 ID·seq 로 브로커 구독·조회 결과와 맞춘다. 정렬 시각은 파일의 log_time 과 같은 값
미추정 Tier-U 도 발행하되 aligned = false. 소비자가 기본으로 뺀다. 중복(TIM-4091)은 발행하지 않는다
전달 QoS 0. 실시간 입력이라 늦은 재전송보다 최신값이 중요하다. 빠짐없는 기록은 파일·조회가 맡는다
지연 규약 제안 목표: 장치 → 발행 p95 100 ms. 셀 로거가 10초마다 수집기 시각 → 발행 지연 p95 를 로그에 남긴다

정렬 결과는 발행 시점의 근거로 계산하므로, 나중에 시계 튐 근거가 도착하거나 재정렬되면 조회 결과와 다를 수 있다. 차이는 등급의 불확도 안에 있고, 정렬 시각을 고정해야 하는 판단은 조회로 한다.

4. 저장 — MCAP 와 S3

4.1 MCAP 파일

항목 내용
메시지 시각 log_time = 정렬 시각, publish_time = 셀 로거 수신 시각
정렬 정보 채널마다 <채널>/_align 채널: 메시지별 seq, 불확도, 정렬 방식, 등급, 정렬 여부, 진단 코드 (TS-06). 채널 기본값과 같으면 생략
채널 메타데이터 판본, 프로파일 버전, 정렬 방식, 기본 등급·불확도, 시간 매핑, 정렬 엔진 버전
첨부 그 파일에 적용된 채널 프로파일
묶음 arm(관절 4채널), cam(카메라 2채널), context(에피소드 이벤트), sync(시계 근거·프로파일 변경·진단 요약)
파일 단위 UTC 10분 경계, 30초 무입력, 2 GB, 종료 시 닫음. 닫힌 뒤에는 바꾸지 않는다
manifest 파일마다 JSON: 크기, SHA-256, 구간, 채널별 메시지 수·시각 범위, 판본, 닫힌 이유

4.2 S3 키 구조

mcap/site=<현장>/area=<영역>/line=<라인>/cell=<셀>/date=<UTC 날짜>/<시작>-<끝>_<묶음>_cv<판본>.mcap  (+ .json manifest)
mcap/site=<현장>/area=<영역>/_sync/…        시계 근거, 적용 중인 채널 프로파일 사본
inbox/mcap/…                                수집 경로 (업로더가 올림, 조회 서비스가 검사 뒤 옮기고 지움)
quarantine/mcap/…                           검사에 실패한 파일 (버리지 않음)
ingest/results/mcap/….json                  수집 결과 (통과·격리, 사유) → 업로더가 읽는다

mcap/ 에는 조회 서비스가 검사를 통과시킨 파일만 들어간다. 카탈로그의 채널·구간 색인은 셀 로거 manifest 가 아니라 MCAP 에서 직접 뽑는다. 데이터 양은 관절 4채널 합쳐 1분에 약 1 MB, 카메라 2대 1분에 약 120 MB.

4.3 수집 — 조회 서비스가 검사·색인·격리

셀 로거는 닫힌 파일을 수집 경로(inbox/)에 올리기만 한다. 저장소(mcap/)와 카탈로그에는 쓰지 않는다. 조회 서비스가 30초마다 수집 경로를 처리하면서 파일 단위 검사를 하고, 통과한 파일만 저장소로 옮겨 카탈로그에 등록한다. 메시지 단위 시각 검사(3.5)는 셀 로거가, 파일 단위 검사는 조회 서비스가 맡는다.

검사 보는 것
전송 받은 파일의 SHA-256·크기가 셀 로거 manifest 와 같은가. 같은 경로에 다른 내용이 이미 있지 않은가 (닫힌 파일은 바뀌지 않는다)
형식 MCAP 를 끝까지 읽을 수 있는가 (청크 CRC), 요약 정보가 있는가 (정상 종료), 요약의 채널별 개수가 실제와 같은가
필수 메타데이터 기록 정보(현장·영역·라인·셀·묶음·판본)가 manifest·저장 경로와 맞는가. 데이터 채널마다 시간 매핑·판본·정렬 엔진 버전이 있는가
_align · _sync 채널 기본 정렬 정보가 없는 채널은 메시지마다 _align 이 있는가. 동기 근거 묶음에는 _sync 채널만 있는가
재정렬본 대체 대상이 파일 안 기록과 manifest 에서 같은가
색인 채널별 구간·개수를 파일에서 직접 뽑는다. 셀 로거 manifest 의 색인과 다르면 셀 로거 결함으로 본다
통과 → mcap/<경로> + 조회 서비스가 쓴 manifest → 카탈로그
실패 → quarantine/<경로> (버리지 않는다)
결과 → ingest/results/<경로>.json (통과·격리, 사유 코드) → 업로더가 읽어 로컬 파일을 uploaded/ 또는 rejected/ 로

5. 조회 서비스 — 서버 (AWS)

5.1 구성

조회 서비스는 하나의 Python 프로세스(FastAPI)다. 아래 모듈이 그 안에서 함께 돈다. 카탈로그 동기화와 내보내기는 별도 스레드로 돌고, 나머지는 요청마다 실행된다. 카탈로그 DB(PostgreSQL)만 별도 프로세스다.

모듈 하는 일
API · 인증 IF-03 엔드포인트. 인증 어댑터가 토큰에서 신원·현장·권한을 꺼내고(권한은 운영 커널이 정함, 지금은 고정 토큰 + 정책 파일), 모든 API 가 한 판정 함수(데이터셋 × 목적 → 보안 등급 → 위임 범위 → 현장 밖 내보내기)를 거친다. 보안 등급, 요청마다 감사 기록
수집 · 카탈로그 동기화 (스레드) 30초마다 수집 경로 처리: 전송 해시·MCAP 형식·필수 메타데이터·_align·_sync 검사, MCAP 에서 색인을 뽑아 등록, 실패는 격리하고 사유 회신. 저장소에 있는 manifest·프로파일 사본 적재(카탈로그 재구성용)는 증분(최근 2일 폴더)과 1시간마다 전체
저장소 캐시 조회에 필요한 MCAP 을 S3 에서 받아 SHA-256 확인 후 보관 (같은 파일을 다시 받지 않는다)
조회 엔진 판본 선택, 조회 원칙(5.2) 적용, 누락 구간·품질 요약, json·arrow 응답, 서명된 페이지 토큰으로 분할 전송
이벤트 · 연결키 작업자 입력을 에피소드 구간으로 묶고, 데이터가 어느 에피소드에 속하는지 불확도를 반영해 판정 (inside / ambiguous)
스냅샷 구간·채널의 당시 판본 파일 목록을 고정. 같은 ID 는 언제 읽어도 같은 데이터. 학습 모델 참조 기록
내보내기 작업 (스레드 풀) 비동기 작업. Parquet(학습용, 스냅샷 필수), MCAP(여러 원본을 한 파일로, Foxglove 재생)
문서 · SDK 배포 이 페이지, SDK 매뉴얼, API 명세, 대화형 API, SDK 패키지
데이터 사전 매핑 채널·규약 필드를 TTA 데이터 사전 항목에 잇는 매핑의 등록·조회·사용 중지(5.5). 카탈로그의 semantic_id 를 채운다. 사전 확인은 어댑터(지금은 연동 없음)
PostgreSQL 카탈로그 (별도 프로세스) 파일, 채널, 판본 대체 관계, 프로파일 이력, 데이터셋, 스냅샷, 내보내기, 수집 기록, 사전 매핑, 접근 기록. 권한은 DB 가 아니라 토큰(정책 파일)에 있다

5.2 조회 원칙

원칙 구현
시간축은 정렬 시각 하나 구간 [start, end)·정렬·채널 간 비교 모두 정렬 시각 기준. 원래 시각은 요청 시 참고 필드로만
최신 판본 재정렬본이 있으면 그 판본, 대체된 쌍은 제외. 분할 전송 중에도 첫 조각과 같은 판본 유지
미추정 제외 Tier-U 는 기본 제외, include_unaligned 로 포함. min_tier 로 등급 하한
만들지 않는다 보간·추정 없음. 대신 누락 구간(gaps), 누락 비율, 등급 분포, 불확도, 제외 수를 함께 준다
한도 값 조회 1시간, 이벤트 31일, 내보내기 제한 없음

5.3 API

기능 API
카탈로그 (데이터셋·채널·데이터 기간·지연 모델·판본·재정렬 알림) GET /v1/datasets, GET /v1/datasets/{id}
구간 조회 (시계열·영상·이벤트 레코드) POST /v1/query
이벤트 (에피소드 구간·점 이벤트) POST /v1/events
최신값 GET /v1/latest
영상 본문 GET /v1/content
스냅샷 POST /v1/snapshots, GET /v1/snapshots/{id}, GET /v1/datasets/{id}/snapshots, POST /v1/snapshots/{id}/references
내보내기 POST /v1/exports, GET /v1/exports/{id}, GET /v1/exports/{id}/files/{name}
데이터 사전 매핑 (채널·필드 ↔ TTA 사전 항목) POST /v1/dictionary/mappings, GET /v1/dictionary/mappings, GET /v1/dictionary/mappings/{id}, POST /v1/dictionary/mappings/{id}/deprecate

파이썬 SDK databahn 은 요청을 만들고, 분할 전송을 이어 받고, 일시 오류를 다시 시도하고, 결과를 numpy 배열로 바꾼다. 조회 원칙은 서버가 적용하므로 SDK 를 쓰든 API 를 직접 부르든 결과가 같다. 사용법은 SDK 매뉴얼, 필드는 API 명세.

5.4 인증·권한·접근 기록 — 운영 커널과의 경계

권한을 정하는 쪽은 전북대 운영 커널(FacOS, 정책 결정자 PDP)이고, 조회 서비스는 토큰에 담긴 권한대로 집행한다(정책 집행자 PEP). 데이터는 커널을 지나가지 않고, 조회 서비스는 요청마다 커널에 묻지 않는다. 커널과 맞닿는 곳은 토큰(인증 어댑터)과 감사 이벤트 두 곳뿐이다.

소비자 ── 토큰 요청 ──▶ 운영 커널 (신원·권한 정책)        ※ 합의 전: 관리자가 등록한 고정 토큰 + 정책 파일
소비자 ── 요청 + 토큰 ──▶ 조회 서비스
                          인증 어댑터: 토큰 → 신원·현장·권한·내보내기 승인·위임·만료
                          판정 (한 곳): 데이터셋 × 목적 → 보안 등급 → 위임 범위 → 현장 밖 내보내기
                          조회 원칙 적용 → 응답
                          접근 기록 (허가·거부 모두)  ─ ─ 감사 요약 이벤트 ─ ─▶ 운영 커널 (예정)
구성 구현
인증 어댑터 토큰에서 신원(sub), 현장(site_id), 권한(grants: 데이터셋 × 목적, 위임이면 구간), 현장 밖 내보내기 승인(export_scope), 원 요청자(act), 요청 ID(trace_id), 만료(exp)를 꺼낸다. 지금은 고정 토큰 → 정책 파일(tokens.json, 토큰은 해시만) 매핑. FacOS 토큰이 합의되면 어댑터만 바꾼다
판정 (한 곳) 모든 API 가 같은 함수 하나를 거친다. ① 데이터셋 × 목적 권한(없으면 DAT-4031, 데이터셋이 있는지도 알리지 않음) ② 보안 등급: restricted 는 토큰 현장 = 데이터셋 현장(DAT-4032) ③ 위임 토큰이면 요청 구간이 위임 범위 안 ④ 내보내기가 현장 밖이면 internal 은 승인 필요, restricted 는 불가. 내보낸 파일을 받을 때도 다시 판정하고, 나중에 도는 내보내기 작업은 요청자 신원으로 다시 판정한다
접근 기록 요청마다 한 행 (IF-03 Table 25 + 현장, 원 요청자, 판정 결과 allow·deny·error). 거부·형식 오류도 허가와 같은 동작 이름·대상·구간으로 남는다
감사 요약 이벤트 커널로 보내는 요약 이벤트(가칭 audit.data_access) — 형식·토픽 합의 전이라 아직 없다

합의를 기다리는 것 (그때까지 위 기본값으로 동작): 토큰에 권한을 담는 방식(K1), 정책 관리 위치(K2), 감사 이벤트 형식(K3), 위임 토큰(K5), 보안 등급 거부 코드(DAT-4031 로 통일할지), 서비스 간 인증 방식, 접근 기록 보존 기간.

데이터 접근 권한(grants)과 별개로 관리 권한(roles)이 있다. 지금은 dict_admin(사전 매핑 등록·사용 중지, 5.5) 하나이며, 정책 파일에서 계정마다 준다 (fabric.admin role <계정> dict_admin, 서버는 deploy_ec2.sh role).

5.5 데이터 사전 매핑 — 채널의 뜻을 표준 항목으로

과제 데이터 모델은 AAS(자산관리셸)를 틀로 하고, 데이터 항목의 뜻은 TTA 가 관리하는 데이터 사전의 항목 ID(semantic_id)로 나타낸다. 측정값은 AAS 에 복사하지 않고 링크로 IF-03 을 가리키므로, "이 채널은 사전의 어느 항목인가"를 잇는 일을 IF-03 이 맡는다. 사전 자체(항목의 이름·정의·단위)는 복제하지 않고 매핑만 관리한다.

TTA 데이터 사전 (외부, 항목 ID·정의)                    ※ 지금은 연동 없음 — 확인 어댑터 none
        ▲ 항목이 있나 확인 (어댑터: none | id_list | http 예정)
관리자(dict_admin) ── 매핑 등록·교체·사용 중지 ──▶ 사전 매핑 (dict_mappings)
                                                     │ 채널·tag·규약 필드 → 항목 ID·버전
소비자 ── 대상 기준 / 사전 기준 조회 ───────────────────┤
카탈로그 데이터셋 상세 ◀── semantic_id ──────────────────┤
IF-20 모델 입출력 semantic_id ◀── 같은 매핑 (같은 항목을 가진 설비에 모델을 붙일 수 있나) ┘
항목 내용
대상 채널, tag(채널 안 값 하나, <채널>#<tag> — 관절 6개가 한 채널에 있어 테스트베드가 더함), 규약 필드(ts_aligned 등), 데이터셋 정의 필드
레코드 매핑 ID, 대상, 사전 항목 ID·버전, 상태(활성·사용 중지), 등록 주체, 적용 시작. 테스트베드가 더한 것: 사전 확인 결과, 대체한 매핑, 사용 중지 시각·주체
규칙 대상마다 활성 매핑은 하나. 바꿀 때는 지금 매핑 ID 를 replaces 로 주고 새 버전을 등록한다 (이전 것은 사용 중지, 지우지 않음)
권한 등록·사용 중지는 dict_admin, 조회는 인증된 누구나. 단 채널·tag 매핑은 그 데이터셋 권한이 있어야 보인다 (권한 없는 데이터는 있는지도 알리지 않는다)
사전 확인 TTA 연동 전에는 확인하지 않고 unverified 로 등록한다. TTA 가 항목 ID 목록(파일)이나 조회 API 를 주면 어댑터만 바꾸고, 쌓인 매핑을 다시 확인한다 (사전에 없으면 지우지 않고 표시)

6. 검증

7. 한계와 다음 단계