모더레이션 API의 형식 오류 JSON: Node.js를 사용한 헬스케어 CRM 액션 처리 전략

간단 요약: 모더레이션 API 응답을 한 번 파싱하고, 이를 좁은 명령어 스키마(command schema)와 검증하며, 잘못된 JSON이나 모호한 액션은 수정하여 작성하기보다 검토를 위해 보내야 합니다.

모더레이션 응답이 형식 오류가 발생했더라도 절대 CRM에 쓰여지게 해서는 안 됩니다. 본문(body)을 신뢰할 수 없는 바이트로 취급하고, 한 번 파싱하며, 그 형태를 검증하고, 알려진 필드만 정규화한 후, 모호성은 검토 대상으로 보내야 합니다. 헬스케어 기술 분야의 통화 요약기(sales-call summarizer)의 경우, 잘못된 메모나 후속 조치 작업은 요청이 로그에서 벗어난 후에도 규정 준수 문제(compliance problem)를 야기할 수 있습니다.

제공된 예시는 적절한 사용자 콘텐츠를 받아 모더레이션 API가 CRM 액션을 제안하고, 스키마 검사 후에만 이를 기록합니다. 또한 테넌트별로 토큰 및 재시도 메타데이터(metadata)도 기록합니다. 이는 실패 경로를 검사 가능하게 만들고 비용 결정과 파서의 관행을 분리해 줍니다.

Node.js는 모더레이션 API 응답의 형식 오류 JSON을 어떻게 처리해야 할까요?

파서는 바이트가 JSON으로 디코딩될 수 있는지 여부만 답할 뿐입니다. 그 값이 객체인지, actions가 배열인지, 또는 액션이 실제 연락처를 대상으로 하는지는 알려주지 않습니다. [], {"actions": null}, 그리고 알 수 없는 status를 가진 객체는 모두 유효한 JSON이며 안전하지 않은 CRM 입력값일 수 있습니다.

저는 처음에 파싱을 경계로 취급했습니다. 그것은 너무 작았습니다. 노트북 환경에서 응답을 출력하고 다시 시도하는 것은 무해하게 느껴집니다. 하지만 프로덕션 환경에서는 재시도가 비용을 중복 지출시키고, 원래 페이로드(payload)를 숨기며, 형식 문제를 일관성 없는 작업으로 바꿀 수 있습니다. 유용한 실패 단위는 HTTP 요청 자체가 아니라 제안된 비즈니스 액션입니다.

헬스케어 통화의 경우, 안전한 상태는 '승인됨(accepted)', '거부됨(rejected)', 또는 '검토 필요(needs review)'입니다. 암묵적인 최선 노력 작성(best-effort write)은 존재하지 않습니다. 불확실한 요약 정보가 기회를 조용히 변경하거나 잘못된 테넌트에 텍스트를 첨부하는 일 없이 운영자(operator)를 기다릴 수 있어야 합니다.

CRM 어댑터 앞에 놓이는 네 가지 게이트는 전송 계층 및 콘텐츠 타입, 한 번의 파싱, 스키마 검증, 그리고 도메인 권한 부여입니다.

첫 번째 게이트는 전송(transport) 및 콘텐츠 유형을 확인합니다. 두 번째는 정확히 한 번만 파싱합니다. 세 번째는 작은 스키마를 검증하고, 네 번째는 도메인 규칙을 적용합니다: 테넌트 식별자(tenant identity), 허용된 액션 이름(allowed action names), 경계가 지정된 텍스트(bounded text), 그리고 필수 식별자입니다.

이러한 분리는 복구 결정이 로컬하게 이루어지도록 합니다. 파싱 오류는 엄격한 예산 내에서 재시도될 수 있습니다. 스키마 오류는 보통 격리되어야 하며, 테넌트 불일치(tenant mismatch)는 거부되고 감사 기록을 남겨야 합니다. 예외는 없습니다.

여기서 멈춥니다.

다음은 작은 Node.js 경계(boundary)입니다. CRM 클라이언트가 주입되며 엔드포인트는 일반적(generic)으로 유지됩니다. 파서는 변형된 텍스트를 복구하지 않습니다. 복구는 조사 과정에서 필요한 증거를 변경하기 때문입니다.

function parseModerationPayload(rawBody, contentType) {
  if (!contentType.toLowerCase().includes("application/json")) {
    return { state: "needs_review", reason: "unexpected_content_type" };
...
}

결과는 부울(boolean) 값이 아닙니다. 이는 호출자에게 두 번 파싱하지 않고도 재시도, 보류 또는 거부할 수 있는 충분한 정보를 제공합니다. 이 구분이 중요한 이유는 워커가 유효한 객체로 시작하여 잘린 문자열에서 끝나는 응답을 받을 때입니다. 핸들러(handler)에서 재시도하는 것은 합리적일 수 있지만, 부분적으로 복구된 객체를 CRM 라이터에 전달하는 것은 그렇지 않습니다. 원본 응답, 콘텐츠 유형, 테넌트 컨텍스트, 재시도 횟수, 그리고 검증 이유는 내부 이벤트로 함께 전송되어야 하며, 민감한 호출 텍스트는 보존 정책(retention policy) 뒤에 남겨져야 합니다. 실제 서비스에서는 캡처된 본문(captured bodies)의 크기를 제한하고, 테넌트 정책에 따라 호출 내용을 마스킹(redact)하며, 민감한 텍스트를 자유롭게 로깅하는 대신 상관관계 ID(correlation ID)를 첨부해야 합니다.

스키마 게이트는 JSON뿐만 아니라 액션 자체를 어떻게 보호하나요?

검증은 모델 응답보다 더 좁은 내부 객체를 생성해야 합니다. CRM 라이터는 요청 컨텍스트에서 테넌트 ID, 허용 목록에 있는 액션 종류(allow-listed action kind), 안정적인 레코드 ID(stable record ID), 그리고 경계가 지정된 텍스트만을 수락할 수 있습니다. 모델이 테넌트를 선택해서는 안 됩니다.

제한적인 계약(narrow contract)의 경우, 해당 계약으로 테스트되면 작은 검증기(validator)만으로 충분합니다. 더 큰 스키마의 경우, JSON Schema validator를 사용하고 명령 소비자(command consumer)와 함께 스키마 버전을 관리해야 합니다. 두 경우 모두, 부작용(side effect)이 발생하기 전에 알 수 없는 액션 종류(unknown action kinds)와 누락된 식별자(missing identifiers)는 거부해야 합니다.

const allowedKinds = new Set(["create_follow_up", "add_call_note"]);

function toCommands(payload, requestContext) {
...
}

이것은 실제적인 트레이드오프입니다. 오탐지 거부(false rejection)는 검토 단계 비용을 발생시키지만, 오탐지 수용(false acceptance)은 불완전한 출처(incomplete provenance)를 가진 부작용을 만듭니다. 임계값(thresholds)을 코드와 메트릭에 명시해야 합니다. 저는 시작 제약 조건으로 2,000자 텍스트 제한과 한 번의 재시도(retry)를 사용하며, 리플레이 결과가 정당화할 때만 변경합니다. 잘못된 응답은 무한한 재시도 루프를 소비해서는 안 됩니다.

복구는 문자열 수리가 아닌 상태 기계이다 (Recovery is a state machine, not string repair)

보통의 콘텐츠에 대해서는 작은 재시도 예산(retry budget)과 호출 및 테넌트 컨텍스트에서 파생된 Idempotency key를 사용해야 합니다. 구문 분석 실패(parse failure)가 발생하더라도, 테넌트가 여전히 예산 내에 있다면 한 번의 제한적인 재생성(constrained regeneration)을 트리거할 수 있습니다. 원래 응답은 첫 번째 실패의 증거로 보존됩니다. 이것은 문자열 수리가 아니라 응답 처리입니다.

재시도 후 경로는 결정론적(deterministic)입니다:

• 유효한 페이로드 및 명령: Idempotent CRM 작업을 대기열에 추가합니다(enqueue);
• 스키마가 유효하지 않은 유효 JSON: 검토를 위해 보류합니다;
• 예산 초과 후 잘못된 JSON: 실패 이유와 함께 보류합니다;
• 테넌트 또는 권한 불일치: 거부하고, 감사하며, 맹목적으로 재생성하지 않습니다.

대기열 소비자(queue consumer)는 Idempotency 검사를 반복 수행합니다. HTTP 핸들러 게이트만으로는 중복 전송(duplicate delivery), 워커 재시작(worker restart), 또는 운영자 리플레이(operator replay)로부터 보호할 수 없습니다. 명령 ID(command ID)가 반복적인 전달을 무해하게 만들어야 합니다.

이것이 바로 노트북에서 프로덕션으로 전환하는 습관이 중요한 지점입니다. 어댑터를 연결하기 전에, 잘린 JSON, 객체 대신 JSON 문자열, 중복된 액션, 너무 긴 텍스트, 그리고 잘못된 테넌트가 포함된 유효한 응답 등과 같은 피처(fixtures)를 사용하여 동일한 계약을 실행해야 합니다. 피처 세트는 작지만, 커버리지(coverage)는 그렇지 않습니다.

이 패턴을 복사하기 전에 측정해야 할 것들

테넌트별로 잘못된 응답(malformed responses)을, 액션 유형별 스키마 거부(schema rejections)를, 재시도 횟수(retry count), 검토 대기열 연령(review queue age), 중복 억제(duplicate suppression), 그리고 운영자가 나중에 되돌린 승인된 액션을 측정해야 합니다. 정책에 따라 콘텐츠를 제외하거나 마스킹 처리하여, 테넌트 범위의 원장(ledger)에 입력 및 출력 토큰 수, 재시도 원인, 지연 시간(latency)을 기록하십시오. 단일 집계율은 노이즈가 심한 테넌트나 재시도를 두 배로 늘린 프롬프트 수정 사항을 가릴 수 있습니다.

프롬프트와 검증기(validator)를 함께 평가해야 합니다. 더 엄격한 스키마는 안전하지 않은 쓰기 작업(unsafe writes)을 줄이는 동시에 검토 볼륨을 증가시킬 수 있으며, 이는 자동으로 회귀(regression)를 의미하는 것은 아닙니다. 정제된 테스트 케이스(sanitized fixtures)로 리플레이 하네스(replay harness)를 구축하고, 단순히 산문만 평가하기보다 최종 명령어(final commands)에 점수를 매기며, 배포 전에 모든 스키마 변경 사항이 해당 케이스들을 통과하도록 만드십시오.

파싱은 데이터를 읽을 수 있게 만들고; 검증(validation)은 데이터를 적격하게 만들며; 권한 부여(authorization)와 동일성(idempotency)은 부작용(side effect)을 시도해도 안전하게 만듭니다. 이 결정들을 분리하여, 잘못된 출력물이 신비로운 CRM 변이(mutation)가 되는 대신 검토 이벤트가 되도록 하십시오.

참고 자료 (Further reading)

• https://www.rfc-editor.org/rfc/rfc8259
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
• https://json-schema.org/specification
• https://platform.openai.com/docs/guides/structured-outputs