be5d42a418
용도를 내부 문서로 못박았다. 고객 인수물이 아니므로 납품 품질 기준을 적용하지 않는다 — 감사에서 나온 한글 폰트 미번들과 영어 뷰어 UI 는 archify 한계라 spec 으로는 못 고치는데, 사내 머신에는 한글 폰트가 있으므로 low 로 내렸다. 승격 조건(그 둘이 먼저 blocker)을 PROJECT_MAP 다이어그램 절에 적어 두었다. 그 위에 두 번째 게이트를 올린다. 기존 test_diagram_sync 가 "산출물이 spec 보다 낡았나"를 본다면, test_diagram_facts 는 "spec 이 코드보다 낡았나"를 본다. 그림에는 코드에서 뽑은 상수가 라벨과 카드 문장으로 하드카피돼 있어서, SCORER_VERSION 을 올리거나 믹스인을 하나 추가하면 코드는 통과하고 그림만 조용히 틀려졌다. CLAUDE.md 가 그 값들을 규칙으로 못박아 두었는데 정작 같은 값을 그린 다이어그램에는 보호가 없었다. SCORER_VERSION · SCHEMA_VERSION · 믹스인 개수 · app-*.js 개수 · 바디 상한 · 인증 실패 10회/60초 · 프롬프트 12행 상한 · 풀 상한 60/20 · 기본 모델 · 런타임 의존성 3종 "지문 유사도 0.9+ -> 80점" 은 이름 있는 상수가 아니라 risk_scoring 안의 인라인 리터럴이라, import 대신 실제로 채점해서 확인한다. 라벨이 주장하는 값과 스코어러가 내는 값이 같은지를 직접 본다. 차단을 실증했다 — SCORER_VERSION v3->v4 로 3건, MAX_PROMPT_EVIDENCE 12->16 으로 2건이 실패한다. 영향받는 다이어그램 전부에서 잡힌다. 발견 가능성도 정리했다. 감사에서 "3.3MB 산출물이 어떤 문서 색인에도 없다"가 나왔으므로 README 색인에 등재하고, PROJECT_MAP 까지 가지 않아도 되도록 docs/diagrams/README.md 에 직접 수정 금지·재생성 명령·CSP 주의를 두었다. 검증: ruff clean, pytest 619 passed (사실 게이트 +19). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BStHFrjQj2VypecSG9ex1V
102 lines
5.3 KiB
Markdown
102 lines
5.3 KiB
Markdown
# POSA Copyrighter
|
|
|
|
이미지 저작권 위험을 자동 분석하고, 운영자가 콘솔에서 근거를 확인해 **승인 / 보류 / 반려**를 판정하는 폐쇄망(air-gapped) 운영 도구입니다.
|
|
|
|
- **분석 서버**: 제출 이미지를 분석해 위험도·근거를 산출하고 SQLite에 저장
|
|
- **운영자 콘솔**: 심사 큐, 근거 검토, 판정, 지식 DB, 감사 로그를 제공하는 단일 페이지 웹 GUI
|
|
- **외부 근거 검색**: Naver 검색, Google Vision/Custom Search, 로컬 LLM(Ollama) 연동(선택)
|
|
|
|
## 요구 사항
|
|
|
|
- Python 3.13
|
|
- 런타임 서드파티 의존성은 이미지 처리 라이브러리뿐입니다(지연 로딩): `numpy`, `opencv-python-headless`, `pillow`
|
|
|
|
> **폐쇄망(air-gapped) 원칙**: 모든 의존성·자산은 빌드/스테이징 머신에서 미리 받아 **오프라인 휠**로 설치합니다. 대상 서버는 설치·실행 시 인터넷에 접근하지 않습니다. 자세한 절차는 [`docs/operations/offline-install.md`](docs/operations/offline-install.md)를 참고하세요.
|
|
|
|
## 설치
|
|
|
|
```bash
|
|
# 개발 머신 (온라인) — 의존성 설치
|
|
pip install -r requirements.txt # 런타임
|
|
pip install -r requirements-dev.txt # 테스트 포함
|
|
|
|
# 폐쇄망 대상 — 오프라인 휠로 설치 (예시)
|
|
pip install --no-index --find-links wheelhouse -r requirements.txt
|
|
```
|
|
|
|
`.env.example`를 복사해 `.env`를 만들고 필요한 값(인증 토큰, 검색 API 키 등)을 채웁니다. 키를 비워 두면 해당 외부 검색은 자동으로 비활성화됩니다.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
## 실행
|
|
|
|
```bash
|
|
python run_copyrighter_server.py
|
|
# 옵션은 런처에 그대로 전달됩니다
|
|
python run_copyrighter_server.py --host 127.0.0.1 --port 9500
|
|
```
|
|
|
|
> `python -m rights_filter.server` 로 직접 실행하려면 `src/` 가 import 경로에 있어야 합니다
|
|
> (`PYTHONPATH=src`, Windows PowerShell 은 `$env:PYTHONPATH="src"`). 런처는 이 경로 설정과
|
|
> 작업 디렉터리 고정을 대신 해 주므로 `run_copyrighter_server.py` 사용을 권장합니다.
|
|
|
|
주요 옵션: `--host`, `--port`, `--db`(SQLite 경로), `--images`(제출 이미지 폴더), `--static`(운영자 GUI 경로), `--env`(.env 경로).
|
|
|
|
기본값으로 실행하면 `http://127.0.0.1:9500` 에서 운영자 콘솔이 열립니다.
|
|
|
|
> 보안: `COPYRIGHTER_AUTH_TOKEN`이 비어 있으면 데이터 라우트가 **인증 없이** 열립니다. 단일 호스트 개발 환경 외에는 반드시 토큰을 설정하세요.
|
|
>
|
|
> 토큰을 설정하면 **틀린 토큰을 제시한 시도**는 클라이언트 주소별로 60초당 10회로 제한되고, 초과 시 `429`와 `Retry-After`를 반환합니다. 토큰을 아직 입력하지 않은 요청(콘솔 최초 로드)은 시도로 세지 않으므로 정상 운영자가 잠기지 않습니다.
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
src/rights_filter/ 분석·서버·통합·도메인 로직 (Python)
|
|
server/ http.server 기반 API + 정적 파일 서빙, SQLite 저장소
|
|
analysis/ 이미지 분석·위험도 산출
|
|
integrations/ Naver / Google / LLM 어댑터
|
|
web/operator-gui/ 운영자 콘솔 (정적 SPA: index.html, app-*.js, styles.css)
|
|
tests/ pytest 테스트
|
|
operator_gui/ 운영자 GUI 정적 검증 + Playwright E2E
|
|
docs/ 기획·설계·운영 문서
|
|
```
|
|
|
|
콘솔 스크립트는 관심사별로 `app-*.js` 15개로 나뉘어 있고, **`index.html` 의 로드 순서가
|
|
의미를 갖습니다**(클래식 스크립트가 하나의 전역 스코프를 공유). 순서와 목록은
|
|
[`docs/PROJECT_MAP.md`](docs/PROJECT_MAP.md) 에 있으며 정적 테스트가 이를 고정합니다.
|
|
|
|
## 검증 / 테스트
|
|
|
|
커밋 전 게이트는 **단일 명령**입니다(CI 도 같은 명령을 호출합니다). ruff 린트와 pytest 전체를
|
|
순서대로 실행합니다.
|
|
|
|
```powershell
|
|
.\verify.ps1 # 린트 + 테스트 전체
|
|
.\verify.ps1 -SkipLint # 빠른 내부 루프 (테스트만)
|
|
.\verify.ps1 -Coverage # src/ 커버리지 리포트 포함
|
|
```
|
|
|
|
개별 실행이 필요할 때:
|
|
|
|
```bash
|
|
python -m pytest # 또는 그냥 pytest — pytest.ini 가 경로를 설정합니다
|
|
python -m ruff check src tests # 설정: ruff.toml
|
|
|
|
# 운영자 GUI E2E (Playwright)
|
|
playwright install chromium # 빌드 머신에서 1회 — 브라우저 바이너리는 오프라인 번들에 포함
|
|
python -m pytest tests/operator_gui/
|
|
```
|
|
|
|
- 브라우저(E2E) 테스트는 Playwright/Chromium이 없으면 **자동으로 건너뜁니다**(`importorskip` + graceful skip).
|
|
- 운영자 워크벤치는 `tests/operator_gui/pages/`의 Page Object(`OperatorWorkbench`)와 `conftest.py`의 공용 픽스처를 사용합니다.
|
|
|
|
## 문서
|
|
|
|
- [프로젝트 구조 지도 (PROJECT_MAP)](docs/PROJECT_MAP.md) — 파일·라우트·스키마 위치, 로드 순서, 알려진 부채
|
|
- [작업 이력 (INDEX)](docs/INDEX.md)
|
|
- [프로젝트 소개 및 기술 구현](docs/project-introduction-and-technical-implementation.md)
|
|
- [운영 워크리스트](docs/operations/copyrighter-operation-worklist.md)
|
|
- [오프라인 설치 절차](docs/operations/offline-install.md)
|
|
- [구조 다이어그램 4종](docs/diagrams/) — 시스템 구성 · 증거 데이터 흐름 · 운영자 심사 · 제출물 상태 전이 (**내부 문서**, 납품물 아님)
|