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

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

-- 하이라이트 테이블
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
• 문서 통계 및 분석
• 모바일 반응형 최적화
• 고급 검색 필터
• 문서 버전 관리

현재 상태 (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

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