\r\n * The codes are the AI Server API v0.1 set and match the {@code SCENARIO_TYPE}\r\n * seed in {@code V2__reference_data.sql}. A start request always carries all\r\n * six codes exactly once, so absence is never how a scenario is turned off —\r\n * {@code enabled} says that. A code with no stored row rides with\r\n * {@code enabled: false} and empty {@code rois}.\r\n *\r\n *
\r\n * 신뢰도를 포함한 모든 설정값은 {@code parameters} 안에 있다. 최상위에 {@code confidence}\r\n * 를 따로 두지 않는 이유는 파라미터 정의를 소유하는 쪽이 AI 서버이기 때문이다 - 그중 하나만\r\n * 끌어올려 두면 AI 가 목록을 바꿀 때마다 계약을 두 군데 고쳐야 한다. 고객사 config 전달용\r\n * {@code CameraConfigPayload.ScenarioPayload} 는 아직 최상위 {@code confidence} 를 갖는데,\r\n * 그쪽은 별개 계약이라 함께 바꾸지 않았다.\r\n *\r\n *
\r\n * {@code parameters} 에는 {@code ScenarioParameterCatalog} 가 정의한 항목만 담긴다. 카탈로그\r\n * 기본값 위에 저장된 {@code parameters_json} 의 같은 이름 값을 덮으므로, 저장 이후에 늘어난\r\n * 항목은 기본값으로 채워지고 카탈로그에서 빠진 항목은 옛 행에 남아 있어도 나가지 않는다.\r\n * 저장된 행이 없는 코드는 빈 객체를 받는다 - 켜진 적이 없어 보낼 설정이 없다.\r\n */\r\npublic record AiScenarioSetting(String scenarioCode, boolean enabled, List \r\n * The body is uniformly camelCase, {@code recServerId} and {@code recCameraId}\r\n * included. This also makes the two directions agree: the AI's own push to\r\n * {@code POST /api/v1/events} ({@code AiEventItem}) already spells the same two\r\n * values {@code recServerId} and {@code recCameraId}.\r\n *\r\n * \r\n * Neither {@code recServerId} nor {@code recCameraId} is needed by the AI\r\n * today: it connects using {@code rtspUrl}, which is already complete, and it\r\n * correlates events using {@code cameraId}. The AI may ignore both fields. They\r\n * ride along as forward-looking reference, because {@code recCameraId} alone\r\n * is not globally unique - the schema's {@code UK_CAMERA_REC_ID} is\r\n * {@code UNIQUE (rec_server_pk, rec_camera_id)}, so camera {@code 00000012} can\r\n * exist on two different Streaming Servers. Once the AI eventually pulls media\r\n * from the Streaming Server directly instead of being handed an RTSP URL, the\r\n * pair {@code recServerId} + {@code recCameraId} is the identity it will\r\n * need to resolve one camera.\r\n *\r\n * \r\n * {@code startWallTimeMs} 와 {@code rtpClockRate} 는 REC 가 응답에 실어 준 타임라인\r\n * 앵커다. AI 가 탐지 시각을 자기 시계가 아니라 Streaming Server 기준으로 계산하려면\r\n * 둘이 함께 있어야 한다 —\r\n * {@code absoluteMs = startWallTimeMs + rtpTimestamp * 1000 / rtpClockRate}.\r\n * v0.1 요청 계약에는 없는 필드이므로 AI 쪽과 합의가 필요하다. 또한 REC 가 카메라 소스\r\n * 복구와 32-bit wrap 때 앵커를 다시 잡으므로, 같은 cameraId 로 start 를 다시 불러\r\n * 갱신해야 한다.\r\n */\r\npublic record AiStartCommand(long cameraId,\r\n String recServerId,\r\n String recCameraId,\r\n String rtspUrl,\r\n long startWallTimeMs,\r\n int rtpClockRate,\r\n List \r\n * The order matters: the activation gate runs before REC is queried, so a camera\r\n * that will not run AI costs no control-channel request. Nothing is stored here\r\n * and nothing is retried; the caller decides what to do with the outcome.\r\n *\r\n * \r\n * Not a Spring bean. It needs an open Streaming Server control channel, and\r\n * standing that channel up belongs to the Managed authentication work, so this\r\n * is constructed wherever that wiring lands.\r\n */\r\npublic class CameraAiInferenceService {\r\n private static final Logger LOGGER = LoggerFactory.getLogger(CameraAiInferenceService.class);\r\n\r\n /** The AI receives the main track. Sub selection is a separate decision. */\r\n private static final int MAIN_TRACK = 0;\r\n\r\n private static final Pattern URL_CREDENTIALS = Pattern.compile(\"(\\\\w+://)[^/\\\\s@]+@\");\r\n private static final int MAX_LOGGED_MESSAGE = 500;\r\n\r\n private final CameraMapper cameraMapper;\r\n private final ScenarioMapper scenarioMapper;\r\n private final RecStreamQueryService streamQuery;\r\n private final AiInferencePort aiPort;\r\n\r\n public CameraAiInferenceService(CameraMapper cameraMapper, ScenarioMapper scenarioMapper,\r\n RecStreamQueryService streamQuery, AiInferencePort aiPort) {\r\n this.cameraMapper = Objects.requireNonNull(cameraMapper, \"cameraMapper\");\r\n this.scenarioMapper = Objects.requireNonNull(scenarioMapper, \"scenarioMapper\");\r\n this.streamQuery = Objects.requireNonNull(streamQuery, \"streamQuery\");\r\n this.aiPort = Objects.requireNonNull(aiPort, \"aiPort\");\r\n }\r\n\r\n public AiStartOutcome start(long localCameraId) {\r\n CameraRow camera = cameraMapper.findById(localCameraId)\r\n .orElseThrow(() -> new IllegalArgumentException(\"unknown camera: \" + localCameraId));\r\n\r\n if (camera.deletedAtWallMs() != null || \"PENDING_DELETE\".equals(camera.assignmentState())) {\r\n return stop(localCameraId);\r\n }\r\n\r\n AiActivation activation = AiActivation.of(camera);\r\n if (!activation.active()) {\r\n // The camera may still be running from an earlier start; releasing it\r\n // here is why a skip is not simply a no-op.\r\n AiStartOutcome stopped = stop(localCameraId);\r\n return stopped.status() == AiStartOutcome.Status.SKIPPED\r\n ? AiStartOutcome.skipped(activation.reason()) : stopped;\r\n }\r\n\r\n List \r\n * All six codes are always emitted, exactly once each — absence must never\r\n * be read by the AI as \"leave this scenario as it was\", so a code with no\r\n * enabled row rides with {@code enabled: false} rather than being left out.\r\n * A code with no stored row at all gets {@code confidence: null} and empty\r\n * {@code rois}; a code whose only rows are disabled still carries its\r\n * stored {@code confidence} and {@code rois} alongside {@code enabled:\r\n * false}, since that data is harmless to send and matches what the\r\n * settings screen shows for it.\r\n *\r\n * \r\n * {@code IX_SCENARIO_CAMERA_TYPE} is an index, not a unique key, so one\r\n * camera can hold several rows of the same code — a previous delivery unit\r\n * made {@code create} an upsert so new duplicates cannot appear, but rows\r\n * created before that may still exist. When several rows of a code are\r\n * enabled, the row with the smallest {@code scenarioId} among the\r\n * enabled ones is used and the rest are logged. This differs from\r\n * {@link com.icerti.platform.poc.service.scenario.ScenarioService#create\r\n * ScenarioService.create}'s {@code findByCameraAndType}, which picks the\r\n * smallest {@code scenarioId} overall regardless of {@code enabled}. With\r\n * legacy duplicates the AI can therefore run one row's settings while the\r\n * settings screen edits another; it self-corrects the next time that\r\n * scenario is saved, since {@code create} updates the row\r\n * {@code findByCameraAndType} found.\r\n */\r\n private List \r\n * 이렇게 하면 두 방향이 같이 해결된다. 저장된 뒤에 카탈로그가 늘어난 항목은 기본값으로\r\n * 채워지고, 카탈로그에서 빠진 항목이 옛 행에 남아 있어도 나가지 않는다. 뒤쪽이 실제로\r\n * 일어나고 있었다 - {@code CROWD} 의 알림 수준 4종이 카탈로그에서 빠진 뒤에도 저장된\r\n * 행에 남아 계속 실려 나갔다. 그대로 두면 계약의 출처가 카탈로그가 아니라 DB 의 과거가\r\n * 된다.\r\n */\r\n private static JsonNode resolveParameters(ScenarioRow row) {\r\n ScenarioCode code = ScenarioCode.valueOf(row.scenarioCode());\r\n ObjectNode parameters = ScenarioParameterCatalog.defaultParameters(code);\r\n JsonNode stored = row.parameters();\r\n if (stored != null) {\r\n ScenarioParameterCatalog.fieldsByName(code).keySet().forEach(name -> {\r\n JsonNode value = stored.get(name);\r\n if (value != null) {\r\n parameters.set(name, value.deepCopy());\r\n }\r\n });\r\n }\r\n return parameters;\r\n }\r\n\r\n /** ROIs are sorted by {@code roiOrder} so the AI's log order matches what a person sees on screen. */\r\n private static List \r\n * 근거는 AI 팀이 보낸 PR #13 사전 합의안 하나다\r\n * ({@code docs/reference/ai_contract/contextra_pr13_web_start_schema_draft.html}). 설계서 v0.3 p.42~47 에서 온\r\n * 옛 정의(공통 {@code confidence}, 침입 방향·대상 같은 선택 항목)는 AI 가 해석하지 않아\r\n * 전부 걷어냈다. 키 이름은 합의안의 snake_case 를 글자 그대로 쓴다 - 하나라도 어긋나면 AI 는\r\n * unknown field 로 버리고 자기 기본값으로 돌아가므로, 값을 바꾼 티도 나지 않는다.\r\n * 6종 공통 {@code cooldown_seconds} 와 군중의 기준 인원·status 비율은 그 뒤 군중 Web 연동\r\n * 계약({@code docs/reference/ai_contract/26_09_28_crowd_web_contract.html})으로 더해졌다.\r\n *\r\n * \r\n * 기본값 두 개는 합의안 샘플과 다르다. {@code pose_confidence} 는 0.1 이 아니라 0.3,\r\n * {@code smoke_confidence} 는 0.3 이 아니라 0.7 이다. 실측에서 그 값으로는 오탐이 눈에 띄어\r\n * 올렸다. 합의안 자체가 최종 계약이 아니라 \"PR #13 구현 과정에서 기본값·허용범위가 미세\r\n * 조정될 수 있다\"고 적은 문서라 벗어나도 되는 자리다.\r\n *\r\n * \r\n * 범위는 아는 것만 건다. confidence 계열 다섯은 0~1, {@code required_bursts} 는\r\n * 합의안이 적어 둔 1~16 이다. 군중 계약이 적은 {@code cooldown_seconds} 0~300,\r\n * {@code reference_count} 1 이상, 군중 status 비율 0~1 도 건다. 나머지는 상·하한이 모두 없다. 음수까지 열리지만, 범위 밖 값은\r\n * AI 가 무시하고 saved → default 로 되돌아가는 계약이라 저장 단계에서 막을 근거가 없다.\r\n *\r\n * \r\n * 파라미터 정의가 현재 사는 곳이 여기다. 최종적으로는 AI 서버가 이 정의를 소유해야 하고,\r\n * 중간 단계로는 {@code SCENARIO_PARAMETER_DEF} 테이블이 유력하다. 둘 다 지금은 막혀 있다.\r\n * 그래서 정의를 이 파일에 두되 조회 메서드를 하나만 노출해서, 나중에 옮길 때 이 파일만 바뀌도록 했다.\r\n *\r\n * \r\n * {@link ScenarioParameterValidator}가 허용 필드와 값 범위를 모두 이 카탈로그에서 읽고,\r\n * 이벤트 설정 화면도 같은 정의로 입력칸을 그린다. 파라미터를 추가하거나 고칠 곳은 이 파일 하나다.\r\n *\r\n * \r\n * 여기 있는 값은 전부 AI 서버로 나간다. {@code parameters_json}이 Start Body 의\r\n * {@code scenarios[].parameters}에 통째로 실린다({@code AiScenarioSetting} 참고). 저장된 값이\r\n * 비운 항목은 여기 기본값으로 메워 보내므로, AI 는 시나리오 한 종의 파라미터 전체를 항상 받는다.\r\n *\r\n * \r\n * 이미 저장된 {@code parameters_json} 행은 옛 키를 그대로 들고 있다. 따로 옮기지 않는다 -\r\n * {@link ScenarioParameterValidator}가 모르는 키를 떨구고, AI 로 나갈 때는 이 카탈로그의\r\n * 기본값 위에 같은 이름만 덮으므로 옛 키는 실리지 않는다. 화면에서 한 번 저장하면 정리된다.\r\n */\r\npublic final class ScenarioParameterCatalog {\r\n\r\n private static final JsonNodeFactory NODES = JsonNodeFactory.instance;\r\n\r\n /** confidence 계열이 공통으로 갖는 경계. */\r\n private static final double CONFIDENCE_MIN = 0;\r\n private static final double CONFIDENCE_MAX = 1.0;\r\n\r\n private static final Map \r\n * {@code pose_confidence} 는 합의안 샘플이 0.1 인데 실측 오탐 때문에 0.3 으로 올렸다.\r\n */\r\n private static List \r\n * {@code pose_confidence} 는 합의안 샘플이 0.1 인데 실측 오탐 때문에 0.3 으로 올렸다.\r\n * {@code required_bursts} 만 합의안이 허용 범위(1~16)를 적어 두었다.\r\n */\r\n private static List \r\n * Flame 조건과 Smoke 조건은 OR 다. 둘 다 만족해도 이벤트는 하나다. 그래서 두 벌의\r\n * confidence·window·ratio 를 각각 따로 받는다.\r\n *\r\n * \r\n * {@code smoke_confidence} 는 합의안 샘플이 0.3 인데 실측 오탐 때문에 0.7 로 올렸다.\r\n */\r\n private static List \r\n * {@code reference_count} 기본값 50 은 계약 예시값(20)과 다르다. 기본값이 늘 실려 나가므로\r\n * 따로 설정하지 않은 군중 카메라도 이 기준으로 DANGER Event 를 낸다.\r\n *\r\n * \r\n * status 비율 기본값은 계약 예시값이다. {@code safe_ratio} 는 AI 가 받아만 두고 판정에 쓰지\r\n * 않는다. 비율 순서(caution < warning < danger)는 검사하지 않는다 - 어긋나면 AI 가\r\n * 무효로 보고 자기 기본값으로 돌아가는 계약이다.\r\n */\r\n private static List