296 lines
10 KiB
Markdown
296 lines
10 KiB
Markdown
# 저작권 탭 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` | 엔진에 적재된 판례 수 |
|