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
- **주 배포 환경**: Synology DS1525+ (32GB RAM, SSD 캐싱)
- **보조 배포 환경**: Mac Mini (개발/테스트)
- **프로세스 관리**: 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: 최우선 개선사항 ✅
- [x] **메모-하이라이트 통합**: 하이라이트 기반 메모 기능 완전 통합
- [x] **노트 뷰어 기능**: 노트에서 하이라이트, 메모, 링크 등 모든 기능 지원
- [x] **API 구조 정리**: 메모(`/api/notes/`) vs 노트(`/api/note-documents/`) 명확한 분리
- [x] **용어 통일**: 전체 시스템에서 메모/노트 용어 일관성 확보
- [x] **노트북-서적 링크 시스템**: 양방향 링크/백링크 완전 구현

### Phase 8: 미완성 핵심 기능 (우선순위) 🚧
- [x] **노트 편집기**: 노트 생성/편집 UI 완성 (`/note-editor.html`) ✅
- [x] **노트북 관리 API**: 노트북 CRUD 백엔드 완성 ✅
- [x] **노트북 관리 UI**: 프론트엔드 CRUD 기능 완성 (`/notebooks.html`) ✅
  - 노트북 목록 조회/표시, 생성/편집/삭제 모달
  - 토스트 알림 시스템, 통계 대시보드
  - 노트북별 노트 관리 및 빠른 노트 생성
- [x] **메모 트리 시스템**: 계층적 메모 구조 및 관리 (`/memo-tree.html`) ✅
  - 트리 구조 메모 생성/편집/삭제, Monaco 에디터 통합
  - 드래그 앤 드롭으로 노드 재배치, 정사 경로 설정
  - 다양한 노드 타입 (메모, 폴더, 챕터, 캐릭터, 플롯)
  - 실시간 시각적 피드백 및 토스트 알림
- [ ] **고급 검색**: 문서/노트/메모 통합 검색 필터링
- [ ] **사용자 관리**: 다중 사용자 지원 및 권한 관리

### Phase 9: 관리 및 최적화 (예정)
- [ ] 관리자 대시보드 UI
- [ ] 문서 통계 및 분석
- [ ] 모바일 반응형 최적화
- [ ] 문서 버전 관리
- [ ] 성능 최적화 및 캐싱

## 현재 상태 (2025-01-26)

### ✅ 완료된 기능
- **완전한 백엔드 API**: FastAPI + SQLAlchemy + PostgreSQL
- **사용자 인증**: JWT 기반 로그인/로그아웃
- **문서 관리**: 업로드, 조회, 목록, 삭제 (드래그&드롭 지원)
- **태그 시스템**: 문서 분류 및 필터링
- **하이라이트 & 메모**: 텍스트 선택 → 하이라이트 → 메모 추가
- **책갈피**: 페이지 북마크 및 빠른 이동
- **통합 검색**: 문서 내용 + 메모 통합 검색
- **실시간 UI**: 업로드 후 즉시 목록 새로고침
- **할일관리 시스템**: 검토필요/TODO/완료된일 3단계 워크플로우
- **메모 트리**: 계층적 메모 구조 및 Monaco 에디터
- **노트북 시스템**: 노트 문서 그룹화 및 관리
- **모바일 최적화**: 햅틱 피드백, 풀투리프레시, 반응형 디자인

### 🚀 테스트 가능한 기능
1. **로그인**: `admin@test.com` / `admin123`
2. **문서 업로드**: HTML 파일 드래그&드롭 또는 선택
3. **문서 뷰어**: 업로드된 문서 클릭하여 뷰어 페이지 이동
4. **태그 관리**: 업로드 시 태그 추가, 목록에서 태그별 필터링
5. **할일관리**: `/todos.html` - 검토필요 → TODO → 완료된일 워크플로우
6. **메모 트리**: `/memo-tree.html` - 계층적 메모 작성 및 관리
7. **노트북**: `/notebooks.html` - 노트 문서 그룹화 및 편집

### 🔧 실행 중인 서비스
- **프론트엔드**: 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

# Synology DS1525+ 최적화 배포 (권장)
./scripts/deploy-synology.sh
```

### 📋 Synology NAS 배포
DS1525+ (32GB RAM, SSD 캐시) 환경에 최적화된 배포 가이드는 [README-DEPLOYMENT.md](README-DEPLOYMENT.md)를 참조하세요.

**주요 특징:**
- 32GB RAM 최적화 (PostgreSQL 8GB, Redis 8GB)
- SSD/HDD 하이브리드 스토리지 전략
- 자동 배포 스크립트 및 모니터링 도구
- 성능 최적화된 설정 (Nginx 캐시, DB 튜닝)

## 🏢 Synology DS1525+ 최적화 배포

### 하드웨어 사양
- **모델**: Synology DS1525+ (5-Bay NAS)
- **CPU**: AMD Ryzen R1600 (4코어/8스레드)
- **메모리**: 32GB DDR4 ECC
- **스토리지**: SSD 읽기/쓰기 캐싱 활성화
- **네트워크**: 기가비트 이더넷

### 스토리지 최적화 전략

#### SSD 배치 (고성능 요구)
```bash
# 시스템 및 고빈도 액세스 데이터
/volume1/docker/document-server/
├── database/          # PostgreSQL 데이터 (SSD)
├── redis/            # Redis 캐시 (SSD)
├── logs/             # 애플리케이션 로그 (SSD)
└── config/           # 설정 파일 (SSD)
```

#### HDD 배치 (대용량 저장)
```bash
# 대용량 파일 저장소
/volume2/document-storage/
├── documents/        # HTML 문서 파일 (HDD)
├── uploads/          # 업로드된 원본 파일 (HDD)
├── backups/          # 데이터베이스 백업 (HDD)
└── archives/         # 아카이브 파일 (HDD)
```

### Docker Compose 최적화 설정

#### 볼륨 매핑 (docker-compose.synology.yml)
```yaml
version: '3.8'

services:
  database:
    volumes:
      # SSD: 데이터베이스 성능 최적화
      - /volume1/docker/document-server/database:/var/lib/postgresql/data
      
  redis:
    volumes:
      # SSD: 캐시 성능 최적화
      - /volume1/docker/document-server/redis:/data
      
  backend:
    volumes:
      # SSD: 로그 및 설정
      - /volume1/docker/document-server/logs:/app/logs
      - /volume1/docker/document-server/config:/app/config
      # HDD: 대용량 파일 저장
      - /volume2/document-storage/uploads:/app/uploads
      - /volume2/document-storage/documents:/app/documents
      
  nginx:
    volumes:
      # SSD: 설정 및 캐시
      - /volume1/docker/document-server/nginx:/etc/nginx/conf.d
      # HDD: 정적 파일 서빙
      - /volume2/document-storage/documents:/usr/share/nginx/html/documents:ro
```

### 시놀로지 환경 배포 명령어

```bash
# 1. 디렉토리 생성
sudo mkdir -p /volume1/docker/document-server/{database,redis,logs,config,nginx}
sudo mkdir -p /volume2/document-storage/{documents,uploads,backups,archives}

# 2. 권한 설정
sudo chown -R 1000:1000 /volume1/docker/document-server/
sudo chown -R 1000:1000 /volume2/document-storage/

# 3. 시놀로지 최적화 배포
docker-compose -f docker-compose.synology.yml up -d

# 4. 서비스 상태 확인
docker-compose -f docker-compose.synology.yml ps
```

### 성능 최적화 설정

#### PostgreSQL 튜닝 (32GB RAM 환경)
```ini
# postgresql.conf
shared_buffers = 8GB                    # RAM의 25%
effective_cache_size = 24GB             # RAM의 75%
work_mem = 256MB                        # 복잡한 쿼리용
maintenance_work_mem = 2GB              # 인덱스 구축용
checkpoint_completion_target = 0.9      # SSD 최적화
wal_buffers = 64MB                      # WAL 버퍼
random_page_cost = 1.1                  # SSD 환경 최적화
```

#### Redis 설정 (캐싱 최적화)
```conf
# redis.conf
maxmemory 4gb                           # 캐시 메모리 제한
maxmemory-policy allkeys-lru            # LRU 정책
save 900 1                              # 자동 저장 설정
save 300 10
save 60 10000
```

### 백업 전략

#### 자동 백업 스크립트
```bash
#!/bin/bash
# /volume1/docker/document-server/scripts/backup.sh

BACKUP_DIR="/volume2/document-storage/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# 데이터베이스 백업
docker-compose -f docker-compose.synology.yml exec -T database \
  pg_dump -U postgres document_server > "$BACKUP_DIR/db_backup_$DATE.sql"

# 설정 파일 백업
tar -czf "$BACKUP_DIR/config_backup_$DATE.tar.gz" \
  /volume1/docker/document-server/config/

# 7일 이상 된 백업 파일 삭제
find "$BACKUP_DIR" -name "*.sql" -mtime +7 -delete
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete

echo "Backup completed: $DATE"
```

#### 시놀로지 작업 스케줄러 설정
```bash
# 매일 새벽 2시 자동 백업
# 제어판 > 작업 스케줄러 > 생성 > 사용자 정의 스크립트
0 2 * * * /volume1/docker/document-server/scripts/backup.sh
```

### 모니터링 및 유지보수

#### 리소스 모니터링
```bash
# 컨테이너 리소스 사용량 확인
docker stats

# 디스크 사용량 확인
df -h /volume1 /volume2

# 시놀로지 시스템 상태
cat /proc/meminfo | grep -E "MemTotal|MemAvailable"
```

#### 로그 로테이션 설정
```bash
# /etc/logrotate.d/document-server
/volume1/docker/document-server/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 1000 1000
    postrotate
        docker-compose -f docker-compose.synology.yml restart backend
    endscript
}
```

### 네트워크 최적화

#### 포트 포워딩 설정
- **외부 포트**: 24100 (HTTPS 리버스 프록시 권장)
- **내부 포트**: 24100 (Nginx)
- **방화벽**: 필요한 포트만 개방

#### SSL/TLS 설정 (Let's Encrypt)
```bash
# Certbot을 통한 SSL 인증서 자동 갱신
docker run --rm -v /volume1/docker/document-server/ssl:/etc/letsencrypt \
  certbot/certbot certonly --webroot \
  -w /volume2/document-storage/documents \
  -d your-domain.com
```

## 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 기반 문서 요약
- 문서 버전 관리