# 2단계 통합 인터페이스 명세 (오투오 ↔ 바이칼/컴북스)

> 계획서 마일스톤 2.4(요소 추출+표절 검출 고도화 통합), 3.x(침해요소 DB 공유),
> 5.x(공유서비스 고도화) 연동을 위한 API 계약. 데이터 수령 전 사전 확정용.

## 1. 오투오가 제공하는 API (현행)

| Method | Path | 용도 | 비고 |
|---|---|---|---|
| POST | `/v1/plagiarism/detect` | 단건 표절 탐지 | 군집 부분표절 신호 포함 |
| POST | `/v1/plagiarism/batch` | 배치(≤500) | 비동기 잡 |
| POST | `/v1/summary` | 스토리 요약 | 신규(과제2 ②) |
| GET | `/v1/taxonomy` | 10태그·39케이스 | 컴북스/바이칼 라벨 공유 |
| GET | `/v1/health` | 엔진 상태 | |

## 2. detect 응답 — 2단계 신규 필드 `partial_signal`

군집화 기반 요소별 부분 표절 분해. 바이칼 침해요소 DB 에 '무엇을 바꿔치기했는지'를
구조화해 적재할 수 있도록 제공.

```json
{
  "matches": [{
    "source_doc": "ref-0003",
    "similarity": 0.88,
    "tags": [{"tag": "reproduction", "role": "primary", "label_ko": "복제권"}],
    "case_id": "A1",
    "partial_signal": {
      "cluster_id": 2,
      "verdict": "element_swap_plagiarism",
      "signature_score": 0.74,
      "per_element": {"lemmas": 0.92, "keywords": 0.88, "characters": 0.0, "motifs": 0.1},
      "retained_elements": ["lemmas", "keywords"],
      "changed_elements": ["characters", "motifs"]
    }
  }]
}
```

- `verdict`: `near_duplicate` | `element_swap_plagiarism` | `weak` | `none`
- `element_swap_plagiarism` = 본문(lemma/키워드) 유지 + 인물/모티프만 교체한 표절.

## 3. 바이칼 침해요소 DB 연동 (계획서 3.x)

- 오투오 detect 결과 → 바이칼 침해요소 케이스 DB 적재 매핑:
  - `case_id`, `tags[]`, `partial_signal.verdict`, `score_breakdown` → DB 컬럼.
  - 분류체계 버전 동기화: `GET /v1/taxonomy` 의 `cases_version`/`meta_tags_version`.
- 합의 필요: ① DB 스키마(필드/타입), ② 적재 방식(API push vs 배치 export),
  ③ 침해요소 식별자 체계(컴북스 콘텐츠>제품>아티클 식별코드와 매핑).

## 4. 공유서비스 / 저작권 자동 분석 경계

- 저작권 침해 **자동 분석 모듈**(1차/2차 침해 자동 판단, 권한 기반 적용범위 계산)은
  계획서상 **바이칼** 담당(p.22). 오투오는 표절 '유사도/태그/케이스' 신호까지 제공,
  권한·계약 기반 침해 '확정' 판단은 바이칼 모듈로 위임.
- 경계 인터페이스: 오투오 `MatchResult` → 바이칼 침해 판단 입력. 본 매핑 표를
  통합 설계 회의에서 확정.

## 5. 인증/배포

- 현재 API Key 인증(`app/core/auth.py`). 공유서비스 통합 시 OAuth2(계획서 p.18)와의
  연동 방식 협의.
- 상용 데이터 구간 암호화(AES256-CBC)·키 배포는 바이칼 공유서비스 아키텍처 기준 적용.

## 6. 통합 테스트 항목(연말 인수시험 역산)

- [ ] taxonomy 버전 동기화 라운드트립
- [ ] detect → 바이칼 DB 적재 E2E
- [ ] partial_signal 필드 계약 테스트
- [ ] summary 엔드포인트 통합
- [ ] 배치 처리 성공률 95%(마일스톤 점검기준)