# 케이스 매칭 응답 계약 (2026-09-18)

## 표시 대상

`POST /v1/plagiarism/detect`와 `POST /v1/plagiarism/batch`의 options에
`"audience": "author"`를 지정하면 저자용 JSON으로 직렬화한다.
생략 시 `admin`이며 기존 케이스 후보·판례·법률 검토 응답이 유지된다.
허용하지 않은 audience 값은 422다. 이 선택은 권한 인증을 대신하지 않는다.

```json
{
  "doc_id": "manuscript-123",
  "text": "검사할 원고 본문",
  "options": {"audience": "author", "return_evidence": true}
}
```

저자용 응답은 `legal_risk`, `is_infringement`를 생략한다. matches 각각에서
`case_id`, `case_title`, `case_candidates`, `tags`, `infringement_type`,
`publication_verdict`, `publication_verdict_status`를 생략한다(빈 값 반환이 아닌 키 생략).
일치 원천·좌표·증거 구간·점수·match_reasons는 유지한다. `return_evidence=false`이면
기존처럼 evidence_spans는 빈 목록이다. 자유형 `ccl_basis`는 다음 고정 문장을 사용한다.

- 매칭 있음: `확인이 필요한 부분이 있습니다.`
- 매칭 없음: `등록된 비교 자료에서 일치 구간을 찾지 못했습니다.`

매칭 없음은 비침해/출간 가능 판정이 아니다.
배치에서는 항목별 결과에 동일 규칙이 적용된다. 경량 `/v1/plagiarism/review`도
같은 옵션을 받고 legal_judgment의 판례 ID를 비우고 코드 없는 검토 문장을 제공한다.
기존 review 응답의 필드 구성은 유지한다.

## 출간 판정

taxonomy 케이스와 관리자용 case_candidates 각각에 `publication_verdict`를 제공한다.
현재 값은 전부 null이다. 컴북스 코드표와 케이스 대응표가 없기 때문이다.
null은 출간 허용·불가 중 어느 쪽도 의미하지 않는다.

관리자용 match의 `publication_verdict`는 대표값이고, 아직 null이다.
`publication_verdict_status=source_pending`은 후보 판정 자료 미확보다.
일부 후보에 판정이 들어왔어도 우선순위 규칙을 확보하기 전에는 대표값을 만들지 않고
`review_required`를 반환한다. 코드표와 보수적 순서가 확정되면 이를 검증하는
회귀 테스트와 함께 대표 선정 로직을 추가한다. 후보별 판정은 삭제하지 않는다.
현재 스키마의 문자열은 연결 지점이며 공식 9종 enum 정의가 아니다.

## 감사 기록 연결

상세 detect와 배치 항목에 `request_id`(매 호출별 UUID), `engine_version`,
`taxonomy_version`, `analyzed_at`이 들어간다. 같은 doc_id로 재검사하면 request_id는 달라진다.
새 기본 엔진 버전은 `o2o-plagiarism-2.2.1-cases-v1.3`이다. 환경변수로 버전을
덮어쓰는 운영 환경은 배포 시 같은 값을 반영해야 한다.

바이칼은 관리자용 원본 응답을 보관하고 요청/원천 ID와 연결해 최종 확정·수정 이유·
검토자·시각을 기록한다. 저자용 JSON에는 관리자의 확정에 필요한 후보가 없으므로
그것만 보관하면 케이스 정확도 평가를 할 수 없다. 감사 로그 5년 저장은 API UUID를
추가했다고 구현되는 기능이 아니며 바이칼 저장 계층에서 별도 구현해야 한다.