적재 규격 회람 — 지표 코드가 종목을 넘나든다
분석 결과 적재 경로(POST /videos · POST /analyses)의 규격 초안을 8월 28일에 냈고, 오늘 그 초안을 에이전트 쪽 루브릭과 실제로 맞춰 봤다. 결과부터 적으면, 합의해야 할 항목이 하나 늘었고 그것이 나머지보다 먼저다.
정상호 님 확인 부탁드립니다. 규격 전문은 fastapi/docs/api-contract.md 3-1절에 있습니다.
무엇이 막고 있나
agent/rubrics/의 루브릭 5개(야구 투구 · 농구 점프슛 · 농구 레이업 · 축구 인사이드 패스 · 축구 인스텝 슛)가 참조하는 측정 지표는 11개다. 그중 5개가 여러 종목에서 같이 쓰인다.
| 지표 코드 | 쓰이는 종목 |
|---|---|
trunk_forward_lean_deg_at_impact | 축구 · 야구 · 농구 (전부) |
swing_elbow_angle_at_impact | 야구 · 농구 |
swing_knee_angle_at_impact | 농구 · 축구 |
plant_knee_angle_at_impact | 야구 · 축구 |
swing_shoulder_flexion_after_impact_deg | 야구 · 농구 |
그런데 백엔드의 metric_definition 테이블은 code가 기본키이고 sport_code를 단일 값으로 갖는다. 같은 코드를 두 종목으로 정의할 수 없다. 문서상의 제약이 아니라 실제로 넣어 보고 확인했다.
1) trunk_forward_lean_deg_at_impact / football -> 들어감
2) trunk_forward_lean_deg_at_impact / baseball -> UniqueViolation
duplicate key value violates unique constraint "metric_definition_pkey"
항목별 등급도 같다. 루브릭의 criteria.id 중 release_arm_extension과 follow_through가 각각 3개 루브릭에, 그 밖에 5개가 2개 루브릭에 겹친다.
이게 먼저인 이유: 지표 코드가 정해지기 전에는 metric_definition을 채울 수 없고, 비어 있으면 적재 요청이 외래키에서 전부 거부된다. 인증 방식이나 실패 보고 경로를 먼저 정해도 적재는 한 건도 안 들어간다.
선택지 셋
| 안 | 내용 | 대가 |
|---|---|---|
| A (제안) | metric_definition에서 sport_code를 없앤다. 지표는 물리량이고, 어느 종목에서 쓰는지는 루브릭이 안다 | 부록 D.3이 sport 외래키를 전제하므로 그 문서를 함께 고쳐야 한다 |
| B | 기본키를 (code, sport_code) 복합키로 | 값 테이블의 외래키가 두 컬럼이 되고, 제출할 때 종목을 항목마다 실어야 한다 |
| C | 코드에 종목 접두어를 붙인다 | 같은 물리량이 이름 3개가 된다. 값끼리 비교가 안 되므로 선수 벡터·유사도 검색(SFR-005)에 직접 해롭다. 루브릭도 전부 고쳐야 한다 |
A를 제안하는 이유는 데이터가 이미 그렇게 말하고 있어서다. 11개 중 5개가 공유되고 그중 하나는 전 종목 공통이다. 종목은 지표의 속성이 아니라 루브릭의 속성으로 보인다. 다만 부록 D를 건드리는 결정이라 혼자 정하지 않는다.
함께 정할 것 셋
지표 코드가 정리되면 나머지는 규격만 맞추면 된다.
- 서비스 인증 방식 — 에이전트는 사용자가 아니라서 사용자 토큰을 쥘 수 없다. 별도 자격증명이 필요한데 형태가 미정이다(5장 SEC-011).
- 실패 보고 경로 —
analysis_job의 상태 갱신을 별도 엔드포인트로 둘지, 결과 제출과 같은 자리에서 받을지. - 신뢰도(키포인트 품질)를 어디에 담나 — 지표 항목으로 넣을지 별도 필드로 둘지.
지표 코드 목록의 주인은 루브릭이 이미 이름을 갖고 있으니 에이전트가 정의하고 백엔드가 따라가는 형태가 자연스러워 보인다. 새 종목을 열 때 누가 먼저 넣느냐(시드 스크립트 · 마이그레이션 · API)만 정하면 된다.
곁들여 — 표기 하나
7장 칸반과 스프린트 1 로그에 “측정값 MySQL 적재” 라고 적혀 있는데, 이 프로젝트의 저장소는 PostgreSQL + pgvector다(부록 D). 오늘 pgvector 확장도 로컬에 설치해 동작을 확인했다. 표기를 바로잡아야 한다 — 담당하신 분이 고치는 편이 좋을 것 같아 여기 적어 둔다.
다음
합의 전에는 구현하지 않는다. 스키마(40a4991)와 규격 초안(73ceb99)까지는 올라가 있고, 엔드포인트는 위 네 가지가 정해진 뒤에 만든다.