o2o-plagiarism-ai/docs/API_GUIDE_BAIKAL.md

# 저작권 탭 API 연동 가이드

## 1. 연동 요약

저작권 탭은 아래 API를 한 번 호출해 렌더링한다.

```text
POST https://plagiarism.o2o.kr/v1/plagiarism/review
```

이 API는 내부적으로 표절 탐지, AI 생성 의심도 산출, 판례 비교를 수행하지만 앱에는
화면에 필요한 요약값만 반환한다. 상세 탐지 API의 `matches`, `evidence_spans`,
`extracted_elements`, `score_semantics`, 모델 정보 등은 응답하지 않는다.

## 2. 공통 규격

| 항목 | 값 |
|---|---|
| Base URL | `https://plagiarism.o2o.kr` |
| Method | `POST` |
| Path | `/v1/plagiarism/review` |
| Content-Type | `application/json; charset=utf-8` |
| 인증 | 운영에서 설정된 경우 `X-API-Key` 헤더 사용 |
| 시간 | ISO 8601 UTC |

## 3. 요청

### 최소 요청

```json
{
  "doc_id": "episode-001",
  "text": "창밖으로 보이는 숲은 오늘따라 유난히 푸르게 보였다."
}
```

### 전체 요청

```json
{
  "doc_id": "episode-001",
  "text": "검사할 에피소드 본문 전체",
  "metadata": {
    "title": "에피소드 1",
    "author": "홍길동",
    "genre": "자서전"
  },
  "options": {
    "threshold": null,
    "top_k": 5,
    "autobiography_mode": null
  },
  "legal_context": {
    "work_type": "literary",
    "access_evidence": null,
    "protected_expression_reviewed": false,
    "rights_verified": false
  }
}
```

| 필드 | 타입 | 필수 | 설명 |
|---|---|---:|---|
| `doc_id` | string | O | 호출 측 문서 또는 에피소드 ID |
| `text` | string | O | 검사할 본문, 1자 이상 |
| `metadata` | object | X | 제목, 저자, 장르 등 표시·추적용 메타데이터 |
| `options.threshold` | number/null | X | 탐지 임계값. 미지정 시 서버 기본값 |
| `options.top_k` | integer | X | 내부 비교 후보 수, 기본 5 |
| `options.autobiography_mode` | boolean/null | X | 자서전 특화 전처리 사용 여부 |
| `legal_context` | object | X | 사람이 확인한 접근 가능성·권리관계 등의 법적 맥락 |

일반적인 저작권 탭 연동에서는 `doc_id`, `text`만 전달하면 된다.

## 4. 응답

### 침해 의심이 낮은 예시

```json
{
  "doc_id": "episode-001",
  "copyright": {
    "originality_percent": 98,
    "similarity_percent": 2,
    "compared_count": 31560,
    "has_suspicion": false,
    "description": "등록 원문 검색 세그먼트 31,560건과 대조한 결과 표절 의심 구간이 없습니다."
  },
  "similar_sentences": {
    "count": 0,
    "label": "0건"
  },
  "ai_generation_suspicion": {
    "level": "low",
    "label": "낮음"
  },
  "legal_judgment": {
    "status": "low",
    "label": "등록 판례 기준 침해 의심 낮음",
    "summary": "등록 코퍼스에서 일치 증거가 확인되지 않아 판례 기반 침해 의심을 제시하지 않습니다. 다만 미매칭은 비침해 확정이 아닙니다.",
    "precedent_ids": []
  },
  "analyzed_at": "2026-08-18T03:00:00Z"
}
```

### 판례에 따른 침해 의심 예시

```json
{
  "doc_id": "episode-002",
  "copyright": {
    "originality_percent": 10,
    "similarity_percent": 90,
    "compared_count": 31560,
    "has_suspicion": true,
    "description": "등록 원문 검색 세그먼트 31,560건과 대조한 결과 표절 의심 구간이 확인되었습니다."
  },
  "similar_sentences": {
    "count": 5,
    "label": "5건"
  },
  "ai_generation_suspicion": {
    "level": "unknown",
    "label": "확인 불가"
  },
  "legal_judgment": {
    "status": "suspected",
    "label": "판례에 비추어 저작권 침해 의심",
    "summary": "2011고단6934, 2013노232 판례의 판단 기준과 탐지 증거를 비교한 결과, 표현 일치 범위가 커 저작권 침해가 의심되어 추가 검토가 필요합니다.",
    "precedent_ids": ["2011고단6934", "2013노232"]
  },
  "analyzed_at": "2026-08-18T03:01:00Z"
}
```

## 5. 화면 매핑

| 화면 항목 | 응답 경로 | 표시 방법 |
|---|---|---|
| 독창성 98% | `copyright.originality_percent` | 숫자 뒤 `%` |
| 저작권 · 유사도 2% | `copyright.similarity_percent` | 숫자 뒤 `%` |
| 대조 결과 설명 | `copyright.description` | 문자열 그대로 표시 |
| 유사 문장 0건 | `similar_sentences.label` | 문자열 그대로 표시 |
| AI 생성 의심도 낮음 | `ai_generation_suspicion.label` | 문자열 그대로 표시 |
| 판례 판단 제목 | `legal_judgment.label` | 의심 또는 검토 필요 시 표시 |
| 판례 판단 근거 | `legal_judgment.summary` | 제목 아래 설명으로 표시 |
| 근거 판례 | `legal_judgment.precedent_ids[]` | 사건번호 배지로 표시 |

`compared_count`는 현재 등록된 검색 세그먼트 수다. 원천 PDF 파일 수 또는 외부 공개
문서 전체 건수로 바꾸어 표기하지 않는다.

## 6. 상태값

### `legal_judgment.status`

| 값 | 의미 | 권장 UI |
|---|---|---|
| `suspected` | 판례와 탐지 증거에 비추어 침해 의심 | 빨간색 또는 주의 표시 |
| `low` | 현재 증거에서 침해 의심 낮음 | 기본 또는 정상 표시 |
| `review_required` | 관련 판례에 따른 추가 확인 필요 | 노란색 검토 표시 |
| `unavailable` | 등록 판례가 없어 비교 불가 | 회색 안내 표시 |

### `ai_generation_suspicion.level`

| 값 | 한글 라벨 |
|---|---|
| `low` | 낮음 |
| `medium` | 중간 |
| `high` | 높음 |
| `unknown` | 확인 불가 |

`unknown`을 임의로 `low`로 바꾸지 않는다. 학습 모델이 없거나 채점할 수 없는 경우다.

## 7. 호출 예시

```bash
curl -X POST 'https://plagiarism.o2o.kr/v1/plagiarism/review' \
  -H 'Content-Type: application/json' \
  -d '{
    "doc_id": "episode-001",
    "text": "검사할 에피소드 본문"
  }'
```

```javascript
const response = await fetch(
  "https://plagiarism.o2o.kr/v1/plagiarism/review",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ doc_id: episodeId, text: episodeText })
  }
);

if (!response.ok) throw new Error(`저작권 검사 실패: ${response.status}`);
const result = await response.json();

originality.textContent = `${result.copyright.originality_percent}%`;
copyrightDescription.textContent = result.copyright.description;
similarSentenceCount.textContent = result.similar_sentences.label;
aiSuspicion.textContent = result.ai_generation_suspicion.label;
legalTitle.textContent = result.legal_judgment.label;
legalDescription.textContent = result.legal_judgment.summary;
```

## 8. 오류 처리

| HTTP | 의미 | 처리 |
|---|---|---|
| `200` | 검사 완료 | 응답으로 화면 갱신 |
| `401` | API 키 누락 또는 불일치 | 인증 설정 확인 |
| `422` | 요청 형식 오류 또는 빈 본문 | 입력값 확인 |
| `503` | 탐지 또는 판례 검토 기능 사용 불가 | 잠시 후 재시도 |
| `500` | 서버 내부 오류 | 오류 로그와 `doc_id` 전달 |

앱은 검사 중 로딩 상태를 표시하고, 실패하면 직전 성공 결과를 새 결과처럼 표시하지 않는다.

## 9. 상세 API

관리자 화면에서 일치 원문, 좌표, 점수 구성 등 상세 증거가 필요할 때만
`POST /v1/plagiarism/detect`를 사용한다. 모바일 저작권 탭은 응답 크기가 작은
`POST /v1/plagiarism/review`를 사용한다.

이 결과는 등록 코퍼스와 판례에 기반한 검토 보조 의견이며 법률상 침해 확정이 아니다.