document-server/README.md

# Document Server

HTML 문서 관리 및 뷰어 시스템

## 프로젝트 개요

PDF 문서를 OCR 처리하고 AI로 HTML로 변환한 후, 웹에서 효율적으로 관리하고 열람할 수 있는 시스템입니다.

## 📝 용어 정의

시스템에서 사용하는 주요 용어들을 명확히 구분합니다:

### 핵심 용어
- **메모 (Memo)**: 하이라이트 기반의 메모 기능
  - 하이라이트에 달리는 짧은 코멘트
  - 문서 뷰어에서 텍스트 선택 → 하이라이트 → 메모 작성
  - API: `/api/notes/` (하이라이트 메모 전용)

- **노트 (Note)**: 독립적인 문서 작성 기능
  - HTML 기반의 완전한 문서
  - 기본 뷰어 페이지에서 확인 및 편집
  - 하이라이트, 메모, 링크 등 모든 기능 사용 가능
  - 노트북에 그룹화 가능
  - API: `/api/note-documents/`

- **노트북 (Notebook)**: 노트 문서들을 그룹화하는 폴더
  - 노트들의 컨테이너 역할
  - 계층적 구조 지원
  - API: `/api/notebooks/`

### 기능별 구분
| 기능 | 용어 | 설명 | 주요 API | 뷰어 지원 |
|------|------|------|----------|----------|
| 하이라이트 메모 | 메모 (Memo) | 하이라이트에 달리는 짧은 코멘트 | `/api/notes/` | ✅ 문서 뷰어 |
| 독립 문서 작성 | 노트 (Note) | HTML 기반 완전한 문서 | `/api/note-documents/` | ✅ 동일 뷰어 (모든 기능) |
| 문서 그룹화 | 노트북 (Notebook) | 노트들을 담는 폴더 | `/api/notebooks/` | - |

### 문서 처리 워크플로우
1. PDF 스캔 후 OCR 처리
2. AI를 통한 HTML 변환 (필요시 번역 포함)
3. PDF 원본은 Paperless에 업로드
4. HTML 파일은 Document Server에서 관리

## 주요 기능

### 핵심 기능
- **사용자 인증**: 로그인 (관리자 계정 생성), JWT 기반 세션 관리
- **HTML 문서 뷰어**: 변환된 HTML 문서를 웹에서 열람
- **스마트 하이라이트**: 텍스트 선택 후 밑줄/하이라이트 표시
- **연결된 메모**: 하이라이트에 직접 메모 추가 및 편집
- **메모 관리**: 메모만 따로 보기, 검색, 정렬 기능
- **빠른 네비게이션**: 메모에서 원문 위치로 즉시 이동
- **책갈피 기능**: 페이지 북마크 및 빠른 이동
- **통합 검색**: 문서 내용 + 메모 내용 통합 검색

### 추가 기능
- **문서 관리**: HTML + PDF 원본 통합 관리 (Paperless 스타일)
- **태그 시스템**: 문서 분류 및 조직화
- **문서 업로드**: 드래그&드롭, 일괄 업로드
- **사용자 관리**: 개인별 메모, 북마크, 권한 관리
- **관리자 기능**: 사용자 생성, 문서 관리, 시스템 설정
- **문서 메타데이터**: 제목, 날짜, 카테고리, 커스텀 필드

## 기술 스택

### Backend
- **언어**: Python 3.11+
- **프레임워크**: FastAPI 0.104+
- **ORM**: SQLAlchemy 2.0+
- **데이터베이스**: PostgreSQL 15+
- **캐싱**: Redis 7+
- **비동기**: asyncio, asyncpg
- **인증**: JWT (python-jose)
- **파일 처리**: python-multipart, Pillow
- **검색**: Elasticsearch 8+ (또는 Whoosh)

### Frontend
- **기본**: HTML5, CSS3, JavaScript (ES6+)
- **CSS 프레임워크**: Tailwind CSS 3+
- **UI 컴포넌트**: Alpine.js 3+ (경량 반응형)
- **검색 UI**: Fuse.js (클라이언트 사이드 검색)
- **에디터**: Quill.js 1.3+ (메모 기능)
- **하이라이트**: Rangy.js (텍스트 선택/하이라이트)
- **아이콘**: Heroicons / Lucide

### 웹서버 & 프록시
- **리버스 프록시**: Nginx 1.24+
- **ASGI 서버**: Uvicorn 0.24+
- **정적 파일**: Nginx (직접 서빙)

### 데이터베이스 & 저장소
- **주 데이터베이스**: PostgreSQL 15+ (문서 메타데이터, 사용자 데이터)
- **전문 검색**: PostgreSQL Full-Text Search + Elasticsearch (선택)
- **캐싱**: Redis 7+ (세션, 검색 결과 캐싱)
- **파일 저장소**: 로컬 파일시스템 (향후 S3 호환 스토리지)

### 개발 도구
- **패키지 관리**: Poetry (Python 의존성)
- **코드 포맷팅**: Black, isort
- **린팅**: Flake8, mypy (타입 체킹)
- **테스팅**: pytest, pytest-asyncio
- **API 문서**: FastAPI 자동 생성 (Swagger/OpenAPI)

### 인프라 & 배포
- **컨테이너**: Docker 24+ & Docker Compose
- **배포 환경**: Mac Mini / Synology NAS
- **프로세스 관리**: Docker (컨테이너 오케스트레이션)
- **로그 관리**: Python logging + 파일 로테이션
- **모니터링**: 기본 헬스체크 (향후 Prometheus + Grafana)

### 외부 연동
- **Paperless-ngx**: REST API 연동 (원본 PDF 다운로드)
- **OCR**: Tesseract (필요시 추가 OCR 처리)
- **AI 번역**: OpenAI API / Google Translate API (선택)

## 포트 할당

- **24100**: Nginx (메인 웹서버)
- **24101**: Database (PostgreSQL/SQLite)
- **24102**: Backend API 서버
- **24103**: 추가 서비스용 예약

## 프로젝트 구조

```
document-server/
├── README.md
├── docker-compose.yml
├── nginx/
│   ├── Dockerfile
│   └── nginx.conf
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt (Python) / package.json (Node.js)
│   ├── src/
│   │   ├── main.py / app.js
│   │   ├── models/
│   │   ├── routes/
│   │   └── services/
│   └── uploads/
├── frontend/
│   ├── static/
│   │   ├── css/
│   │   ├── js/
│   │   └── assets/
│   └── templates/
├── database/
│   ├── init/
│   └── migrations/
└── docs/
    └── api.md
```

## 데이터베이스 스키마 (예상)

### 주요 테이블
- **users**: 사용자 정보 (이메일, 비밀번호 해시, 권한, 생성일)
- **documents**: 문서 메타데이터 (제목, HTML/PDF 경로, 업로드자, 생성일)
- **document_tags**: 문서 태그 (다대다 관계)
- **tags**: 태그 정보 (이름, 색상, 설명)
- **highlights**: 하이라이트 정보 (사용자별, 문서별, 텍스트 범위, 색상)
- **notes**: 메모 정보 (하이라이트 연결, 메모 내용, 생성/수정일)
- **bookmarks**: 책갈피 정보 (사용자별, 문서별, 페이지 위치)
- **user_sessions**: 사용자 세션 관리 (JWT 토큰, 만료일)
- **user_preferences**: 사용자 설정 (테마, 언어, 뷰어 설정)

### 하이라이트 & 메모 스키마 상세
```sql
-- 하이라이트 테이블
highlights (
    id: UUID PRIMARY KEY,
    user_id: UUID REFERENCES users(id),
    document_id: UUID REFERENCES documents(id),
    start_offset: INTEGER,        -- 텍스트 시작 위치
    end_offset: INTEGER,          -- 텍스트 끝 위치
    selected_text: TEXT,          -- 선택된 텍스트 (검색용)
    highlight_color: VARCHAR(7),  -- 하이라이트 색상 (#FFFF00)
    element_selector: TEXT,       -- DOM 요소 선택자
    created_at: TIMESTAMP,
    updated_at: TIMESTAMP
)

-- 메모 테이블 (하이라이트와 1:1 관계)
notes (
    id: UUID PRIMARY KEY,
    highlight_id: UUID REFERENCES highlights(id) ON DELETE CASCADE,
    content: TEXT NOT NULL,       -- 메모 내용
    is_private: BOOLEAN DEFAULT true,
    tags: TEXT[],                 -- 메모 태그
    created_at: TIMESTAMP,
    updated_at: TIMESTAMP
)
```

## 개발 단계

### Phase 1: 기본 구조 ✅
- [x] 프로젝트 구조 설정
- [x] Docker 환경 구성
- [x] 기본 웹서버 설정 (Nginx + FastAPI)

### Phase 2: 인증 시스템 ✅
- [x] 사용자 모델 및 데이터베이스 스키마
- [x] 로그인 API (관리자 계정 생성)
- [x] JWT 토큰 관리
- [x] 권한 미들웨어

### Phase 3: 핵심 기능 ✅
- [x] HTML 문서 뷰어 (하이라이트, 메모 기능 포함)
- [x] 문서 업로드 기능
- [x] 통합 검색 기능 (문서 + 메모)

### Phase 4: 고급 기능 ✅
- [x] 스마트 하이라이트 (텍스트 선택 → 하이라이트)
- [x] 연결된 메모 (하이라이트 ↔ 메모 1:1 연결)
- [x] 책갈피 시스템 (위치 저장 및 빠른 이동)
- [x] 메모 관리 (검색, 필터링, 태그)
- [x] 고급 검색 (문서 + 메모 통합 검색)

### Phase 5: 문서 관리 시스템 ✅
- [x] 문서 태그 관리 시스템 (태그 생성, 필터링)
- [x] 문서 메타데이터 관리 (제목, 설명, 날짜, 언어)
- [x] 사용자별 권한 시스템
- [x] 관리자 계정 기반 사용자 생성
- [x] Paperless 스타일 문서 관리

### Phase 6: 시스템 안정성 및 통합 ✅
- [x] 프론트엔드-백엔드 완전 연동
- [x] Pydantic v2 호환성 수정
- [x] Alpine.js 컴포넌트 간 안전한 통신
- [x] API 오류 처리 및 사용자 피드백
- [x] 실시간 문서 목록 새로고침

### Phase 7: 최우선 개선사항 (진행 중) 🔥
- [ ] **메모-하이라이트 통합**: 하이라이트 기반 메모 기능 완전 통합
- [ ] **노트 뷰어 기능**: 노트에서 하이라이트, 메모, 링크 등 모든 기능 지원
- [ ] **API 구조 정리**: 메모(`/api/notes/`) vs 노트(`/api/note-documents/`) 명확한 분리
- [ ] **용어 통일**: 전체 시스템에서 메모/노트 용어 일관성 확보

### Phase 8: 향후 개선사항 (예정)
- [ ] 관리자 대시보드 UI
- [ ] 문서 통계 및 분석
- [ ] 모바일 반응형 최적화
- [ ] 고급 검색 필터
- [ ] 문서 버전 관리

## 현재 상태 (2025-08-21)

### ✅ 완료된 기능
- **완전한 백엔드 API**: FastAPI + SQLAlchemy + PostgreSQL
- **사용자 인증**: JWT 기반 로그인/로그아웃
- **문서 관리**: 업로드, 조회, 목록, 삭제 (드래그&드롭 지원)
- **태그 시스템**: 문서 분류 및 필터링
- **하이라이트 & 메모**: 텍스트 선택 → 하이라이트 → 메모 추가
- **책갈피**: 페이지 북마크 및 빠른 이동
- **통합 검색**: 문서 내용 + 메모 통합 검색
- **실시간 UI**: 업로드 후 즉시 목록 새로고침

### 🚀 테스트 가능한 기능
1. **로그인**: `admin@test.com` / `admin123`
2. **문서 업로드**: HTML 파일 드래그&드롭 또는 선택
3. **문서 뷰어**: 업로드된 문서 클릭하여 뷰어 페이지 이동
4. **태그 관리**: 업로드 시 태그 추가, 목록에서 태그별 필터링

### 🔧 실행 중인 서비스
- **프론트엔드**: http://localhost:24100
- **백엔드 API**: http://localhost:24102
- **데이터베이스**: PostgreSQL (포트 24101)
- **캐시**: Redis (포트 24103)

## 설치 및 실행

### 개발 환경
```bash
# 프로젝트 클론
git clone <repository>
cd document-server

# Docker 환경 실행
docker-compose up -d

# 개발 모드 실행
docker-compose -f docker-compose.dev.yml up
```

### 프로덕션 환경
```bash
# 프로덕션 배포
docker-compose -f docker-compose.prod.yml up -d
```

## API 엔드포인트 (예상)

### 인증 관리
- `POST /api/auth/register` - 회원가입
- `POST /api/auth/login` - 로그인
- `POST /api/auth/logout` - 로그아웃
- `POST /api/auth/refresh` - 토큰 갱신
- `GET /api/auth/me` - 현재 사용자 정보

### 사용자 관리
- `GET /api/users/profile` - 프로필 조회
- `PUT /api/users/profile` - 프로필 수정
- `PUT /api/users/password` - 비밀번호 변경
- `GET /api/users/preferences` - 사용자 설정
- `PUT /api/users/preferences` - 사용자 설정 변경

### 문서 관리
- `GET /api/documents` - 문서 목록 (사용자별 권한 적용)
- `POST /api/documents` - 문서 업로드
- `GET /api/documents/:id` - 문서 상세
- `DELETE /api/documents/:id` - 문서 삭제

### 검색
- `GET /api/search?q=keyword` - 문서 검색
- `GET /api/search/advanced` - 고급 검색

### 사용자 기능 (인증 필요)
- `POST /api/annotations` - 밑줄/하이라이트 저장
- `GET /api/annotations/:document_id` - 문서별 주석 조회
- `GET /api/bookmarks` - 책갈피 목록
- `POST /api/bookmarks` - 책갈피 추가
- `POST /api/notes` - 메모 저장
- `GET /api/notes/:document_id` - 문서별 메모 조회

### 관리자 기능
- `GET /api/admin/users` - 사용자 목록
- `PUT /api/admin/users/:id` - 사용자 권한 변경
- `GET /api/admin/documents` - 전체 문서 관리

### Paperless 연동
- `GET /api/paperless/download/:id` - 원본 PDF 다운로드
- `GET /api/paperless/sync` - Paperless 동기화

## 보안 고려사항

- 파일 업로드 검증
- XSS 방지
- CSRF 토큰
- 사용자 인증/권한
- 파일 접근 제어

## 성능 최적화

- HTML 문서 캐싱
- 검색 인덱싱
- 이미지 최적화
- CDN 활용 (필요시)

## 향후 계획

- 모바일 반응형 지원
- 다국어 지원
- 협업 기능 (공유, 댓글)
- AI 기반 문서 요약
- 문서 버전 관리