From 35c63ce37a3bab3100422cfd1920f77f0f2b4a24 Mon Sep 17 00:00:00 2001 From: changukyu Date: Sun, 21 Jun 2026 22:35:31 +0900 Subject: [PATCH] docs: add project README --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..709e428 --- /dev/null +++ b/README.md @@ -0,0 +1,78 @@ +# 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 -m rights_filter.server --host 127.0.0.1 --port 9500 +``` + +주요 옵션: `--host`, `--port`, `--db`(SQLite 경로), `--images`(제출 이미지 폴더), `--static`(운영자 GUI 경로), `--env`(.env 경로). + +기본값으로 실행하면 `http://127.0.0.1:9500` 에서 운영자 콘솔이 열립니다. + +> 보안: `COPYRIGHTER_AUTH_TOKEN`이 비어 있으면 데이터 라우트가 **인증 없이** 열립니다. 단일 호스트 개발 환경 외에는 반드시 토큰을 설정하세요. + +## 프로젝트 구조 + +``` +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/ 기획·설계·운영 문서 +``` + +## 테스트 + +```bash +# 전체 +python -m pytest + +# 운영자 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`의 공용 픽스처를 사용합니다. + +## 문서 + +- [프로젝트 소개 및 기술 구현](docs/project-introduction-and-technical-implementation.md) +- [운영 워크리스트](docs/operations/copyrighter-operation-worklist.md) +- [오프라인 설치 절차](docs/operations/offline-install.md)