diff --git a/docs/categories.md b/docs/categories.md new file mode 100644 index 0000000..dc57a47 --- /dev/null +++ b/docs/categories.md @@ -0,0 +1,77 @@ +# 카테고리 체계 + +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 임시파일 정리 + +업로드 중에는 `.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` 포함 — 진행 중 파일을 잘못 픽업하지 않음. diff --git a/frontend/src/routes/+page.svelte b/frontend/src/routes/+page.svelte index d5336f9..6b7a176 100644 --- a/frontend/src/routes/+page.svelte +++ b/frontend/src/routes/+page.svelte @@ -7,13 +7,17 @@ dashboardSummary, type DashboardSummary, type PipelineStatus, + type QueueLag, } from '$lib/stores/system'; import { domainBgClass, domainLabel } from '$lib/utils/domainSlug'; import { api } from '$lib/api'; import Card from '$lib/components/ui/Card.svelte'; import EmptyState from '$lib/components/ui/EmptyState.svelte'; import Skeleton from '$lib/components/ui/Skeleton.svelte'; - import { Inbox, Scale, FileText, Activity, StickyNote, Newspaper, Pin, ChevronRight, Pencil } from 'lucide-svelte'; + import { + Inbox, Scale, FileText, Activity, StickyNote, Newspaper, Pin, ChevronRight, Pencil, + Library, Mic, Video, Sparkles, + } from 'lucide-svelte'; import { renderMemoHtml, toggleTaskLine } from '$lib/utils/memoRenderer'; import { addToast } from '$lib/stores/toast'; @@ -56,40 +60,77 @@ } // ─── 파이프라인 ─── - const STAGE_ORDER = ['extract', 'classify', 'embed', 'preview'] as const; + const STAGE_ORDER = ['extract', 'stt', 'classify', 'embed', 'preview', 'thumbnail'] as const; const STAGE_LABEL: Record = { - extract: '추출', classify: '분류', embed: '임베딩', preview: '미리보기', + extract: '추출', stt: '전사', classify: '분류', embed: '임베딩', + preview: '미리보기', thumbnail: '썸네일', }; interface PipelineRow { stage: string; label: string; pending: number; processing: number; failed: number; total: number; + // §4 — queue_lag 의 oldest_pending_age_sec (적체 신호용) + oldestPendingAgeSec: number | null; } - function buildPipelineRows(items: PipelineStatus[]): PipelineRow[] { - const grouped = new Map(); + function buildPipelineRows(items: PipelineStatus[], lag: QueueLag[]): PipelineRow[] { + // §4 — 24h 누적 (pipeline_status) + 현재 시점 lag (queue_lag) 두 소스 머지. + // queue_lag 가 있으면 stage 별 pending/processing/failed 는 그쪽 (정확) 사용. + const lagMap = new Map(lag.map((l) => [l.stage, l])); + const grouped = new Map(); for (const it of items) { - const cur = grouped.get(it.stage) ?? { pending: 0, processing: 0, failed: 0 }; + const cur = grouped.get(it.stage) ?? { pending: 0, processing: 0, failed: 0, ageSec: null }; if (it.status === 'pending') cur.pending += it.count; else if (it.status === 'processing') cur.processing += it.count; else if (it.status === 'failed') cur.failed += it.count; grouped.set(it.stage, cur); } + // queue_lag 로 덮어쓰기 (현재 시점 신호가 우선) + for (const l of lag) { + grouped.set(l.stage, { + pending: l.pending, processing: l.processing, failed: l.failed, + ageSec: l.oldest_pending_age_sec, + }); + } + // queue_lag 만 있는 stage 도 전부 포함 + const allStages = new Set([...grouped.keys(), ...lagMap.keys()]); const orderedStages = [ - ...STAGE_ORDER.filter((s) => grouped.has(s)), - ...[...grouped.keys()].filter((s) => !STAGE_ORDER.includes(s as never)), + ...STAGE_ORDER.filter((s) => allStages.has(s)), + ...[...allStages].filter((s) => !STAGE_ORDER.includes(s as never)), ]; return orderedStages.map((stage) => { const r = grouped.get(stage)!; - return { stage, label: STAGE_LABEL[stage] ?? stage, ...r, total: r.pending + r.processing + r.failed }; + return { + stage, label: STAGE_LABEL[stage] ?? stage, + pending: r.pending, processing: r.processing, failed: r.failed, + total: r.pending + r.processing + r.failed, + oldestPendingAgeSec: r.ageSec, + }; }); } - let pipelineRows = $derived(summary ? buildPipelineRows(summary.pipeline_status) : []); + let pipelineRows = $derived( + summary ? buildPipelineRows(summary.pipeline_status, summary.queue_lag ?? []) : [] + ); let pipelineMax = $derived(Math.max(1, ...pipelineRows.map((r) => r.total))); let totalFailed = $derived(summary?.failed_count ?? 0); let totalPending = $derived(pipelineRows.reduce((s, r) => s + r.pending, 0)); + // §4 — 카테고리 mini-card 데이터 + const CATEGORY_CARDS: { key: string; label: string; href: string; icon: any }[] = [ + { key: 'library', label: '자료실', href: '/library', icon: Library }, + { key: 'audio', label: '오디오', href: '/audio', icon: Mic }, + { key: 'video', label: '비디오', href: '/video', icon: Video }, + ]; + + function formatAge(sec: number | null): string { + if (sec == null || sec <= 0) return ''; + if (sec < 60) return `${sec}초 전`; + if (sec < 3600) return `${Math.floor(sec / 60)}분 전`; + if (sec < 86400) return `${Math.floor(sec / 3600)}시간 전`; + return `${Math.floor(sec / 86400)}일 전`; + } + // 파이프라인 접힘 상태 let pipelineManualClosed = $state(false); let pipelineOpen = $derived(pipelineManualClosed ? false : totalFailed > 0); @@ -241,6 +282,43 @@ + + {#if summary.category_counts && (Object.keys(summary.category_counts).length > 0 || summary.library_pending_suggestions > 0)} +
+ {#each CATEGORY_CARDS as cat} + {@const count = summary.category_counts?.[cat.key] ?? 0} + + +
+

{cat.label}

+ +
+

{count.toLocaleString()}

+

카테고리

+ + + {/each} + + + + +
+

자료실 제안

+ +
+

+ {summary.library_pending_suggestions} +

+ {#if summary.library_pending_suggestions > 0} +

검토하기 →

+ {:else} +

대기 없음

+ {/if} + + +
+ {/if} +
@@ -319,7 +397,14 @@ {#each pipelineRows as row (row.stage)}
- {row.label} + + {row.label} + {#if row.oldestPendingAgeSec && row.oldestPendingAgeSec > 600} + + ({formatAge(row.oldestPendingAgeSec)}) + + {/if} + 대기 {row.pending} · 처리 {row.processing} ·