# 저작권 탭 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": 37891,
    "has_suspicion": false,
    "description": "등록 원문 검색 세그먼트 37,891건과 대조한 결과 표절 의심 구간이 없습니다."
  },
  "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": 37891,
    "has_suspicion": true,
    "description": "등록 원문 검색 세그먼트 37,891건과 대조한 결과 표절 의심 구간이 확인되었습니다."
  },
  "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`로 바꾸지 않는다. 학습 모델이 없거나 채점할 수 없는 경우다.
현재 운영 서버에는 한국어 자서전 대조 데이터로 학습한 모델이 적재되어 있어 정상적인
본문에는 `low`, `medium`, `high` 중 하나가 반환된다. 이 값은 AI 작성 확정 판정이 아니라
사람 검토 우선순위를 위한 보조 신호다.

## 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`를 사용한다.

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

상세 응답에는 기존 필드 외에 다음 정보가 추가되었다. 모두 추가 필드이므로 기존
`/v1/plagiarism/review` 연동에는 영향이 없다.

| 응답 필드 | 설명 |
|---|---|
| `ai_generation` | 모델 버전, 점수, 구간별 의심도와 주의사항 |
| `legal_risk` | 판례 기반 검토 상태, 인용 사건번호와 A/B/C 검토 등급 |
| `score_semantics` | 검색 점수와 임계값의 의미, 일치 범위 |
| `has_similarity_match` | 등록 코퍼스에서 유사 원문이 확인됐는지 여부 |
| `corpus_scope_note` | 검색 대상 코퍼스 범위 안내 |
| `matches[].source_*` | 일치 원문의 문서·세그먼트·페이지·문자 좌표 |

## 10. 판례 조회 API

관리 화면에서 엔진에 적재된 판례를 검색할 때 사용한다. 판례 545건 전체가 검색·인용
후보이며, A/B/C는 제외 기준이 아니라 검토 품질과 직접성을 나타내는 우선순위다.

```text
GET /v1/precedents?q=어문저작물&grade=A&work_type=literary&offset=0&limit=25
```

| 쿼리 | 설명 |
|---|---|
| `q` | 사건번호·제목·판단 요지 검색 |
| `grade` | `A`, `B`, `C`, `unreviewed` 중 하나 |
| `work_type` | 저작물 유형 필터 |
| `offset`, `limit` | 페이지 위치와 개수. `limit` 최대 100 |

응답의 `loaded_total`은 전체 적재 판례 수, `graded_total`은 사람이 A/B/C 검토를 마친
판례 수다. 각 항목에는 `case_id`, `title`, `source_url`, `grade`, `holding_excerpt` 등이
포함된다.

## 11. 맞춤 요약 API

```text
POST /v1/summary
```

```json
{
  "text": "요약할 자서전 본문",
  "detail": "standard",
  "emphasis": ["가족", "창업"],
  "max_sentences": 5,
  "use_abstractive": false
}
```

| 필드 | 설명 |
|---|---|
| `detail` | `brief`, `standard`, `detailed`. 기본 `standard` |
| `emphasis` | 우선 반영할 주제·키워드, 최대 10개 |
| `ratio` | 직접 지정할 요약 비율. 지정하면 `detail`보다 우선 |
| `max_sentences` | 최대 요약 문장 수 |
| `use_abstractive` | LLM 사용 요청. 사용할 수 없으면 추출 요약으로 폴백 |

## 12. 상태 확인 API

`GET /v1/health`에서 기존 상태값과 함께 다음 필드를 확인할 수 있다.

| 필드 | 설명 |
|---|---|
| `corpus_size` | 검색 가능한 전체 세그먼트 수 |
| `corpus_documents` | 적재된 원문 문서 수 |
| `index_backend` | 현재 검색 인덱스 구현 |
| `ai_model_ready` | 학습된 AI 의심도 모델 준비 여부 |
| `precedent_count` | 엔진에 적재된 판례 수 |