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: 사용자 설정 (테마, 언어, 뷰어 설정)

하이라이트 & 메모 스키마 상세

-- 하이라이트 테이블
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: 기본 구조 ✅

• 프로젝트 구조 설정
• Docker 환경 구성
• 기본 웹서버 설정 (Nginx + FastAPI)

Phase 2: 인증 시스템 ✅

• 사용자 모델 및 데이터베이스 스키마
• 로그인 API (관리자 계정 생성)
• JWT 토큰 관리
• 권한 미들웨어

Phase 3: 핵심 기능 ✅

• HTML 문서 뷰어 (하이라이트, 메모 기능 포함)
• 문서 업로드 기능
• 통합 검색 기능 (문서 + 메모)

Phase 4: 고급 기능 ✅

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

Phase 5: 문서 관리 시스템 ✅

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

Phase 6: 시스템 안정성 및 통합 ✅

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

Phase 7: 최우선 개선사항 ✅

• 메모-하이라이트 통합: 하이라이트 기반 메모 기능 완전 통합
• 노트 뷰어 기능: 노트에서 하이라이트, 메모, 링크 등 모든 기능 지원
• API 구조 정리: 메모(/api/notes/) vs 노트(/api/note-documents/) 명확한 분리
• 용어 통일: 전체 시스템에서 메모/노트 용어 일관성 확보
• 노트북-서적 링크 시스템: 양방향 링크/백링크 완전 구현

Phase 8: 미완성 핵심 기능 (우선순위) 🚧

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

Phase 9: 관리 및 최적화 (예정)

• 관리자 대시보드 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)

설치 및 실행

개발 환경

# 프로젝트 클론
git clone <repository>
cd document-server

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

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

프로덕션 환경

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

🏢 Synology DS1525+ 최적화 배포

하드웨어 사양

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

스토리지 최적화 전략

SSD 배치 (고성능 요구)

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

HDD 배치 (대용량 저장)

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

Docker Compose 최적화 설정

볼륨 매핑 (docker-compose.synology.yml)

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

시놀로지 환경 배포 명령어

# 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 환경)

# 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 설정 (캐싱 최적화)

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

백업 전략

자동 백업 스크립트

#!/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"

시놀로지 작업 스케줄러 설정

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

모니터링 및 유지보수

리소스 모니터링

# 컨테이너 리소스 사용량 확인
docker stats

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

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

로그 로테이션 설정

# /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)

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