hyungi_document_server/docs/categories.md

카테고리 체계

Document Server 의 1차 진입점. 6 활성 + 3 유보. 자세한 결정 배경은 ~/.claude/plans/luminous-sprouting-hamster.md (v2.1) 참조.

6 활성 + 3 유보

카테고리	상태	저장 경로 (/volume4/Document_Server/PKM/)	처리 파이프
document	활성	Inbox/...	extract → classify → embed (+ preview/OCR)
library	활성 — 사용자 승인 후 전이	동상 + @library/... 태그	동상
news	활성	DB 만	news_collector → classify
memo	활성	DB 만	메모 UI → embed
audio	활성 (§3)	Recordings/	stt → classify → embed (extract 건너뜀)
video	활성 (§3, 최소판)	Videos/	thumbnail 만 (classify/embed 안 함)
mail	유보	(별도 plan)	—
calendar	유보	(별도 plan)	—
plex	유보	(별도 plan)	—

역할 분리 원칙 (4 축)

축	역할	주인	누가 변경
documents.category enum	1차 진입점 — UI 탭/라우트/Sidebar 분기	document/library/news/memo/audio/video (+ 유보)	백필(§1) + 사용자 승인(§2) + file_watcher(§3)
user_tags 의 @library/...	자료실 내부 서가 경로 (카테고리가 library 일 때 위치)	사용자 승인 태그	사용자 승인 + PATCH /documents/{id}
facet_doctype	AI 가 식별한 문서 유형 (분류 신호, 필터/검색 key)	분류 파이프라인 산출물	classify_worker
ai_suggestion (JSONB)	AI 가 제안했지만 미승인 된 변경 후보 (category/path/doctype)	승인 UI 소비	classify_worker 작성 / /accept-suggestion clear

4 축을 섞지 않는다. 예:

• AI 가 발주서라고 판단 → facet_doctype='발주서' 설정 (분류 신호 완료). category 는 건드리지 않음.
• 동시에 ai_suggestion = {proposed_category:'library', proposed_path, confidence, source_updated_at} 저장.
• 사용자가 /library 승인 UI 에서 1-click 승인 → 그제서야 category='library' + user_tags += @library/..., ai_suggestion clear.
• 승인 전까지 문서는 category='document' 로 문서함 에 남음.

자동 library 승격은 v2.1 에서 하지 않는다. 메트릭(precision > 0.9 AND reject_rate < 0.1 AND 월 제안 수 > 20 1개월 유지) 충족 시 별도 plan 으로 검토. → ~/.claude/projects/-Users-hyungiahn/memory/project_document_server_future_integrations.md

업로드 경로

채널	document	library	audio	video	news	memo
웹 업로드 (UploadDropzone)	✅	indirect (§4 의존)	✅	✅ direct play 만 (mp4/webm)	❌	❌
NAS 드롭 (file_watcher)	✅	❌ (자동 전이 금지)	✅	✅ + quarantine	❌	❌
외부 collector	❌	❌	❌	❌	news_collector	❌
내부 UI	❌	❌	❌	❌	❌	/memos

Video 채널별 정책 (§3 핵심 결정)

mp4 (H.264 AAC), webm (VP9) 만 브라우저 direct play 가능. 그 외 (mov/mkv/avi) 는 채널마다 다르게 처리:

채널	.mp4 .webm	.mov .mkv .avi
웹 업로드	수락 → category='video', 썸네일 생성	거부 (400 + error_code='unsupported_codec'). UploadDropzone 가 배너 안내.
NAS 드롭 (file_watcher)	수락 → category='video', 썸네일 생성	quarantine import — DB 에 category='video' + needs_conversion=true, VideoPlayer 가 "재생 불가 — 변환 필요" 카드. 파일 삭제 안 함.

업로드 한도 + error_code 체계 (§4)

업로드 한도는 settings.upload.max_bytes 가 단일 진실 공급원 (현재 100MB). 프록시 (home-caddy) 는 max_bytes * content_length_slack_ratio (기본 1.05) 이상 유지.

서버 응답 detail 은 {error_code, message} 객체:

error_code	HTTP	의미
body_too_large	413	Content-Length 또는 누적이 max_bytes 초과
upload_timeout	408	서버 read timeout
network_abort	499	클라이언트 abort / 연결 끊김
empty_file	400	0 바이트
invalid_input	400	파일명/경로/필드 검증 실패
unsupported_codec	400	웹 업로드 direct play 불가 비디오 (.mov/.mkv/.avi)
internal	500	그 외 알 수 없는 에러

Orphan 임시파일 정리

업로드 중에는 <name>.uploading 임시명으로 NAS Inbox 에 쓰고 완료 시 atomic rename. 정상 abort 는 endpoint 가 즉시 정리하지만 프로세스 크래시 / 강제 종료 잔존물은 cleanup_orphan_uploads APScheduler job (10분 주기) 이 수거. 최근 3회 누적 삭제 ≥ cleanup_warn_threshold (기본 10) 이면 WARNING 로그 — abort 가 구조적으로 많거나 대용량 업로드 실패 반복 신호.

file_watcher 의 SKIP_EXTENSIONS 에 .uploading 포함 — 진행 중 파일을 잘못 픽업하지 않음.