docs: 최신 API 연동 명세와 PDF 갱신

docs/API_GUIDE_BAIKAL.md

@@ -81,9 +81,9 @@ POST https://plagiarism.o2o.kr/v1/plagiarism/review
   "copyright": {
     "originality_percent": 98,
     "similarity_percent": 2,
-    "compared_count": 31560,
+    "compared_count": 37891,
     "has_suspicion": false,
-    "description": "등록 원문 검색 세그먼트 31,560건과 대조한 결과 표절 의심 구간이 없습니다."
+    "description": "등록 원문 검색 세그먼트 37,891건과 대조한 결과 표절 의심 구간이 없습니다."
   },
   "similar_sentences": {
     "count": 0,
@@ -111,9 +111,9 @@ POST https://plagiarism.o2o.kr/v1/plagiarism/review
   "copyright": {
     "originality_percent": 10,
     "similarity_percent": 90,
-    "compared_count": 31560,
+    "compared_count": 37891,
     "has_suspicion": true,
-    "description": "등록 원문 검색 세그먼트 31,560건과 대조한 결과 표절 의심 구간이 확인되었습니다."
+    "description": "등록 원문 검색 세그먼트 37,891건과 대조한 결과 표절 의심 구간이 확인되었습니다."
   },
   "similar_sentences": {
     "count": 5,
@@ -170,6 +170,9 @@ POST https://plagiarism.o2o.kr/v1/plagiarism/review
 | `unknown` | 확인 불가 |
 
 `unknown`을 임의로 `low`로 바꾸지 않는다. 학습 모델이 없거나 채점할 수 없는 경우다.
+현재 운영 서버에는 한국어 자서전 대조 데이터로 학습한 모델이 적재되어 있어 정상적인
+본문에는 `low`, `medium`, `high` 중 하나가 반환된다. 이 값은 AI 작성 확정 판정이 아니라
+사람 검토 우선순위를 위한 보조 신호다.
 
 ## 7. 호출 예시
 
@@ -222,3 +225,71 @@ legalDescription.textContent = result.legal_judgment.summary;
 `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` | 엔진에 적재된 판례 수 |

docs/API_SPEC_BAIKAL.md

@@ -12,7 +12,7 @@
 |---|---|
 | Base URL (개발/통합 테스트) | `https://plagiarism.o2o.kr` |
 | 프로토콜 | HTTPS, `Content-Type: application/json` (UTF-8) |
-| 인증 | 개발 단계 없음 → **운영 전 API 키/토큰 추가 예정** |
+| 인증 | 운영 설정 시 `X-API-Key` 헤더 사용 |
 | Swagger(자동 명세) | `{BASE}/docs` — 실시간 스키마 확인 가능 |
 | 실서비스 배포 | 개인정보(자서전) 보호를 위해 **Docker 온프레미스 납품** 예정 (실사용자 본문은 오투오 서버로 전송 안 함) |
 
@@ -62,6 +62,12 @@
     "threshold": null,
     "top_k": 5,
     "autobiography_mode": null
+  },
+  "legal_context": {
+    "work_type": "literary",
+    "access_evidence": null,
+    "protected_expression_reviewed": false,
+    "rights_verified": false
   }
 }
 ```
@@ -75,6 +81,7 @@
 | `options.threshold` | float\|null | – | 판정 임계값. null이면 서버 기본(0.85) |
 | `options.top_k` | int | – | 최대 매칭 수 (기본 5) |
 | `options.autobiography_mode` | bool\|null | – | 자서전 특화 전처리. null이면 서버 설정 |
+| `legal_context` | object | – | 사람이 확인한 접근 가능성·창작성·권리관계. 없으면 미확인으로 처리 |
 
 ### 응답 (저작권 탭에 표시되는 "깨끗한 글" 예시)
 
@@ -87,17 +94,17 @@
     "originality_percent": 98,
     "similarity_percent": 2,
     "similar_sentence_count": 0,
-    "compared_count": 35000,
+    "compared_count": 37891,
     "has_suspicion": false,
     "ai_suspicion_level": "low"
   },
   "ai_generation": {
     "suspicion_level": "low",
-    "score": 0.06,
+    "score": 0.02,
-    "is_stub": true,
+    "is_stub": false,
-    "available": false,
+    "available": true,
-    "model_version": "unavailable",
+    "model_version": "logreg-nolen-kf-ko-v1-qwen3.8-27b-autobiography-v1-auroc0.998",
-    "note": "학습된 모델이 없어 채점하지 않음"
+    "note": "한국어 자서전 범위의 검토 우선순위 점수이며 AI 작성 확정 판정이 아님"
   },
   "matches": [],
   "extracted_elements": {
@@ -122,7 +129,7 @@
     "originality_percent": 45,
     "similarity_percent": 55,
     "similar_sentence_count": 1,
-    "compared_count": 35000,
+    "compared_count": 37891,
     "has_suspicion": true,
     "ai_suspicion_level": "low"
   },
@@ -163,13 +170,17 @@
 | `is_infringement` | bool | 후방호환용 임계 초과 매칭 여부. 법적 침해 확정 아님 |
 | `confidence` | float | 최상위 매칭 결합 유사도 원값(0~1). **화면 표시는 `review_summary` 사용 권장** |
 | `review_summary` | object | **저작권 탭 UI 직접 매핑** (§1 표 참조) |
-| `ai_generation` | object | AI 생성 의심도 상세. 미학습이면 `available=false`, 휴리스틱이면 `is_stub=true` |
+| `ai_generation` | object | AI 생성 의심도 상세. 현재 학습 모델 사용 시 `available=true`, `is_stub=false` |
 | `matches[]` | array | 매칭된 원본별 상세 (표절 시). 태그·케이스·근거 구간 포함 |
 | `matches[].tags[]` | array | 법령 태그. `role`: `primary`(주)/`secondary`(보조), `label_ko` 한글 표기 |
 | `matches[].case_id` | string | 39종 침해 케이스 ID (예: A6) |
 | `matches[].evidence_spans[]` | array | 본문 내 일치 구간 `{start, end, matched}` — 하이라이트용 |
 | `matches[].partial_signal` | object | 군집화 기반 부분 표절(인물만 교체 등) 분해 — 침해요소 DB 적재용 |
 | `ccl_basis` | string\|null | 사람이 읽는 판정 근거 문장 |
+| `legal_risk` | object\|null | 판례 기반 위험도, 사건번호, A/B/C 검토 등급과 판단 근거 |
+| `score_semantics` | object\|null | 검색 점수·임계값·일치 범위의 의미 |
+| `has_similarity_match` | bool\|null | 등록 코퍼스 유사 원문 확인 여부 |
+| `corpus_scope_note` | string\|null | 검색 대상 코퍼스 범위 안내 |
 | `engine_version` | string | 엔진 버전 |
 
 ---
@@ -181,9 +192,27 @@
 | POST | `/v1/plagiarism/batch` | 배치 검사(≤500건). `202` + `job_id` 반환 → 아래 상태 조회 |
 | GET | `/v1/plagiarism/batch/{job_id}` | 배치 상태·결과 조회 |
 | POST | `/v1/summary` | 스토리 요약 (과제2 ②) |
+| GET | `/v1/precedents` | 전체 판례 검색·등급·저작물 유형 필터 |
 | GET | `/v1/taxonomy` | 10종 법령 태그 + 39 케이스 정의 (동일 라벨 공유용) |
 | GET | `/v1/health` | 엔진 상태·코퍼스 크기·버전 |
 
+### 맞춤 요약 옵션
+
+`POST /v1/summary`는 `detail`(`brief|standard|detailed`), `emphasis`(최대 10개),
+`ratio`, `max_sentences`, `use_abstractive`를 받는다. `ratio`를 지정하면 `detail`보다
+우선한다.
+
+### 판례 조회
+
+`GET /v1/precedents`는 `q`, `grade`(`A|B|C|unreviewed`), `work_type`, `offset`,
+`limit` 쿼리를 지원한다. 운영 판례 545건 전체가 검색·인용 후보이며 A/B/C 등급은
+제외 조건이 아니라 검토 품질과 직접성에 따른 우선순위다.
+
+### 상태 확인 확장
+
+`GET /v1/health`에는 `corpus_documents`, `index_backend`, `ai_model_ready`,
+`precedent_count`가 추가되었다.
+
 ---
 
 ## 5. 에러 포맷
@@ -211,4 +240,6 @@ FastAPI 표준. HTTP 상태코드 + `detail`.
    높게 나오므로 직접 표시 금지. 독창성 환산은 오투오가 `review_summary`에서 완료해 제공.
 3. **개인정보** — 실사용자 자서전 본문은 개인정보. 실서비스는 온프레미스(Docker) 납품으로
    전환 예정. 개발 단계 REST 호출 시에도 테스트 데이터 사용 권장.
-4. `compared_count` 는 현재 로딩된 코퍼스 크기. 실데이터 적재 후 실제 대조 건수로 표시됨.
+4. `compared_count` 는 현재 로딩된 검색 세그먼트 수다. 문서 수와 혼동하지 않는다.
+5. 현재 운영 코퍼스는 612개 문서, 37,891개 세그먼트이며 판례는 545건이다. 데이터
+   증분 적재 시 수치는 달라질 수 있으므로 화면에서는 API 반환값을 그대로 사용한다.