# JSON 예시 사용 안내

## 전체 Start가 아닌 parameters 발췌

이 폴더의 개별 요청 예시는 **한 시나리오의 `parameters` 객체 내용만** 담는다. 전체 Start body나 `scenarios` 배열 항목이 아니다. 기존 Web backend가 보유한 해당 시나리오 설정에 선택한 필드만 반영하고, 기존 전체 Start를 구성한다. 이 파일을 그대로 HTTP body로 전송하지 않는다.

| 전체 Start 위치 | 처리 |
| --- | --- |
| `cameraId`, `rtspUrl`, `startWallTimeMs`, `rtpClockRate` | 기존 등록 정보·입력·시간 anchor 유지. 예시에 실제 URI/인증정보 없음 |
| `recServerId`, `recCameraId` | 현재 사용 중인 선택 항목 유지 |
| `scenarios` | FIRE/FALL/INTRUSION/LOITERING/FIGHT/CROWD의 기존 6개 snapshot 유지 |
| `scenarios[].scenarioCode`, `enabled` | 해당 시나리오와 기존 On/Off 유지 |
| `scenarios[].rois` | 기존 ROI 유지. 예시가 없다고 생략·빈 배열로 바꾸지 않음 |
| FIGHT 항목의 `parameters` | `CURRENT/FIGHT_...` 예시의 변경분을 반영 |
| FALL 항목의 `parameters` | 현행 marker 또는 **지원 반영 후에만** 예정 예시의 변경분을 반영 |

현행 Start parser는 `rois` 생략/null을 빈 배열로 정규화할 수 있다. 따라서 ROI를 사용하는 기존 요청에서 이 문서를 이유로 ROI를 생략하면 안 된다. 여섯 시나리오를 두 시나리오로 줄이거나 매 반복 Start마다 새 시간 anchor를 만들지 않는다. 실제 URI/anchor/ROI 변경은 여전히 정상 반영해야 한다.

## 현재 지원 예시

| 파일 | 목적·주의 |
| --- | --- |
| [FIGHT_parameters_minimal.json](CURRENT/FIGHT_parameters_minimal.json) | 새 UI 두 값을 명시적으로 2/1.0으로 전송. 숨긴 contact와 공통값은 유지 |
| [FIGHT_parameters_common_explicit.json](CURRENT/FIGHT_parameters_common_explicit.json) | 사용자가 **직접 선택한 경우에만** 사람0.35·관절0.10·cooldown10도 전송 |
| [FALL_parameters_marker_only.json](CURRENT/FALL_parameters_marker_only.json) | 현재 FALL v1 marker. 공통값 초기화가 아님 |
| [FALL_parameters_common_explicit.json](CURRENT/FALL_parameters_common_explicit.json) | 현행 FALL 공통값의 명시 변경 예. 새 각도 필드는 없음 |

`min_samples=2`, `window_seconds=1.0`은 최초 기본과 같은 **명시 변경**이다. 저장값을 그대로 유지하려면 사용자가 바꾸지 않은 필드를 임의로 기본값으로 채우지 않는다. `contact_min_samples`는 예시에 없으며 Web이 저장값을 추측하여 추가하지 않는다. 공통 score와 cooldown도 FIGHT/FALL 사이에서 자동 복제하지 않는다.

## 미지원 예정 예시: 지금 전송 금지

| 파일 | 목적 |
| --- | --- |
| [FALL_parameters_defaults.json](PLANNED_DO_NOT_SEND/FALL_parameters_defaults.json) | 구현 후 새 세 판정값을 50/50/140으로 명시 복귀하는 안. 기존 common reset 명령과 다름 |
| [FALL_parameters_upper_bounds.json](PLANNED_DO_NOT_SEND/FALL_parameters_upper_bounds.json) | 합의된 허용 상한 60/60/160 예. 추천 튜닝값이 아님 |
| [FALL_parameters_partial_leg.json](PLANNED_DO_NOT_SEND/FALL_parameters_partial_leg.json) | 다리 기준만55로 변경하고 나머지 저장값을 유지하는 확장안 |

**현행 FALL v1은 위 세 파일을 모두 `FALL_R2_FIELDS_INVALID`로 거부한다.** `schema_version=1`은 확장 시에도 보존하는 제안이므로 버전1 숫자만으로 이 세 필드 지원 여부를 판별할 수 없다. AI 담당자의 구현·검증·반영 확인 전 UI 전송을 활성화하지 않는다. 자동 재시도하면서 필드를 삭제해 성공으로 위장하지 않는다.

## 데이터형과 오류

- UI 문자열을 그대로 보내지 않는다. 빈 문자열, null, bool, 범위 밖 숫자는 정상 하한 보정이 아니다.
- FIGHT 관측 수는 JSON 정수다. `2`는 허용, Python parser에서 float가 되는 `2.0`은 현행 검증기에서 거부된다. Web에서는 정수 검증 후 직렬화한다.
- NaN/Infinity는 유효한 JSON 숫자가 아니다. 직렬화 과정에서 null로 바뀌어도 유효값이 되지 않는다.
- 새 블록 내부 오타·알 수 없는 키는 거부한다. 구형 바깥 optional 필드를 무시하는 정책과 구별한다.
- 값 생략과 초기화는 다르다. 신규 초기화 버튼은 만들지 않는다. 기존 초기화의 범위는 각 계약 문서를 따른다.
- 아래 [검증 사례](validation_cases.json)는 테스트용 자료이지 Start body가 아니다. 잘못된 값이 일부러 포함돼 있지만 JSON 문법은 모두 정상이다.

출처: [Start parser](/workspace/contextra-analytics-runtime-lifecycle-refactor/app/secure_control.py), [FIGHT 계약](../FIGHT_R5_WEB_CONFIG_DRAFT.ko.md), [FALL 제안](../FALL_R2_WEB_CONFIG_PROPOSAL.ko.md).