From f968458c5cc83a565641f5a01eb8eefdd7ac1817 Mon Sep 17 00:00:00 2001 From: AI Assistant Date: Fri, 13 Mar 2026 17:56:43 +0900 Subject: [PATCH] Rewrite TODO as project handover --- TODO.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 188 insertions(+), 13 deletions(-) diff --git a/TODO.md b/TODO.md index c14a731..2329fea 100644 --- a/TODO.md +++ b/TODO.md @@ -1,13 +1,188 @@ -- [x] 1. 프로젝트 폴더 구조 생성 -- [x] 2. Dockerfile 및 Unraid XML 템플릿 작성 -- [x] 3. Gitea Actions CI/CD 파일 작성 (.gitea/workflows/build-push.yaml) -- [x] 4. SQLite DB 모델 및 초기화 로직 (backend/models) -- [x] 5. Python yt-dlp 워커 스크립트 작성 (worker/downloader.py) -- [x] 6. Go 백엔드 라우팅 및 파일 업로드(Zone B) 구현 -- [x] 7. Go - Python 연동 로직 (Zone C 다운로드 실행) -- [x] 8. Google CSE 및 Gemini 2.5 Flash 연동 로직 (Zone A) -- [x] 9. WebSocket 서버 및 진행률 방송 로직 -- [x] 10. 프론트엔드 메인 UI 구성 (Tailwind 3-Zone Layout) -- [x] 11. 프론트엔드 JS 통신 로직 및 상태 바 렌더링 연동 -- [x] 12. 전체 기능 통합 테스트 -- [x] 13. Git Init 및 자동 Push (Gitea) +# AI Media Hub Handover + +## Project Summary +- Project: `ai-media-hub` +- Goal: AI-assisted media discovery + ingest dashboard for Unraid +- Backend: Go +- Worker: Python + `yt-dlp` + `ffmpeg` +- Frontend: HTML + Vanilla JS + Tailwind CDN +- Database: SQLite +- Current search backend: `SearXNG` +- Current vision/ranking backend: `Gemini 2.5 Flash` +- Deployment target: single Docker container on Unraid +- Git remote: `https://git.savethenurse.com/savethenurse/ai-media-hub.git` + +## Current Architecture +- `backend/main.go` + App bootstrap, env loading, static frontend serving, route registration +- `backend/handlers/api.go` + Upload/download/search APIs, WebSocket progress broadcast, debug event broadcast +- `backend/services/cse.go` + Actual search backend service + Despite filename, this is no longer Google CSE logic + It now wraps SearXNG search, source filtering, result enrichment, preview asset parsing +- `backend/services/gemini.go` + Query translation, deterministic query expansion helper, Gemini vision scoring + Also extracts first video frame with `ffmpeg` when no thumbnail exists +- `backend/models/db.go` + SQLite init + download history +- `worker/downloader.py` + `yt-dlp` probe/download + ffmpeg clip extraction +- `frontend/index.html` + Main dashboard UI, preview modal, debug log panel +- `frontend/app.js` + API calls, WebSocket status bar, hover preview playback, debug logger panel, platform toggles +- `frontend/style.css` + Custom styles, clamp helpers, slider thumb styles, debug panel scrollbar styles +- `unraid-template.xml` + Unraid template for current `git.savethenurse.com` image source + +## Search Flow: Current Implementation +1. User enters a query in Zone A. +2. Frontend sends `/api/search` with: + - `query` + - selected `platforms` +3. Backend translates the query to English in `GeminiService.TranslateQuery`. + Fallback order: + - Gemini translation + - Google Translate HTTP fallback + - small Korean media-term dictionary replacement +4. Backend builds deterministic English search variants in `GeminiService.ExpandQuery`. +5. Backend calls `SearchService.SearchMedia(...)`. +6. Search service queries SearXNG for: + - `Envato` + - `Artgrid` + - `Google Video` +7. Search service filters source URLs aggressively: + - Google Video: YouTube-only + - Envato: `elements.envato.com` item URLs only + - Artgrid: `artgrid.io/clip/...` only +8. Search service enriches results: + - Envato: parses item page HTML for `og:image` and preview video URL + - Artgrid: attempts clip API + HTML parsing for thumbnails and preview sources +9. Backend ranks all results locally. +10. Backend evaluates all ranked results with Gemini vision in batches. +11. Backend merges Gemini recommendations + fallback ranked items and returns JSON to frontend. +12. Frontend renders cards and hover previews. + +## Direct Downloader Flow: Current Implementation +1. User enters URL in Zone C. +2. Frontend checks duplicate history via `/api/history/check`. +3. Frontend loads preview metadata via `/api/download/preview`. +4. Preview modal opens with: + - media preview + - duration + - crop dual-thumb slider + - quality select +5. User confirms download. +6. Backend launches Python worker. +7. Worker downloads source with `yt-dlp`, clips with `ffmpeg`, emits JSON progress lines. +8. Backend rebroadcasts progress over WebSocket. + +## Current Features Implemented +- [x] Project folder structure +- [x] Dockerfile +- [x] Gitea workflow +- [x] Unraid template +- [x] SQLite download history +- [x] File upload +- [x] yt-dlp direct downloader +- [x] Preview modal for direct download +- [x] Crop selection slider +- [x] Quality selection +- [x] WebSocket realtime progress +- [x] Search source toggles +- [x] Search card hover preview support +- [x] Debug log panel in frontend +- [x] `.log` download from debug panel + +## Important Current Constraints / Known Problems +- Search backend has been rewritten multiple times and is still the main unstable area. +- Envato previews are parsed mainly from page HTML metadata / structured data. +- Artgrid previews are partially inferred from: + - clip page HTML + - clip API attempts + - HLS preview handling in frontend +- Search relevance is still not considered stable enough. +- Gemini batch evaluation exists, but search quality can still degrade if upstream SearXNG results are noisy. +- Frontend JavaScript was not linted with Node tooling in this environment because `node` is not installed here. + +## Frontend Debug Logger +- UI button: bottom-right `Logs` +- Files: + - `frontend/index.html` + - `frontend/app.js` + - `frontend/style.css` +- Logs currently capture: + - API request / response + - WebSocket progress messages + - ignored WS debug messages + - status updates + - platform toggle state + - preview source attach / detach + - hover start / hover end + - modal preview open / close + - browser errors + - promise rejections + - backend debug broadcasts + +## Current Environment Variables +- `APP_ROOT` +- `APP_ADDR` +- `SQLITE_PATH` +- `DOWNLOADS_DIR` +- `FRONTEND_DIR` +- `WORKER_SCRIPT` +- `SEARXNG_BASE_URL` +- `SEARXNG_GOOGLE_VIDEO_ENGINE` +- `SEARXNG_WEB_ENGINE` +- `GEMINI_API_KEY` + +## Unraid Template Notes +- Current image repository in template: + `git.savethenurse.com/savethenurse/ai-media-hub:latest` +- Current registry in template: + `https://git.savethenurse.com` + +## Docker / Build Notes +- Dockerfile uses: + - Go build stage + - static ffmpeg image stage + - Python runtime stage +- Heavy apt ffmpeg install path was removed earlier to reduce build time. + +## Git / Push Workflow Used So Far +- Branch: `main` +- Remote: `origin` +- All requested changes were committed and pushed incrementally to: + `https://git.savethenurse.com/savethenurse/ai-media-hub.git` + +## Recent Relevant Commits +- `8ed1e84` Add in-app debug log panel +- `823bf12` Reflect selected platforms in search status +- `cceb040` Update platform status and HLS previews +- `ad8afd5` Tighten source filters and add platform toggles +- `27000db` Hide overlays during hover preview +- `b78865d` Rewrite search flow and enrich preview assets +- `de24886` Filter non-English expansions and prefer stock sources +- `0bd458d` Boost translated search fallback and source priority + +## Next Priority Areas +- [ ] Search backend quality stabilization + The search service is the main unresolved area. +- [ ] Envato / Artgrid preview extraction hardening +- [ ] Search result relevance validation against real user queries +- [ ] Better matching between rendered description and actual linked asset +- [ ] Add proper frontend build/lint step if Node becomes available + +## Verified Locally In This Environment +- [x] `go build ./backend` +- [x] Python syntax check for worker at various stages +- [x] basic server boot / `/healthz` at various stages +- [ ] full browser-level validation was not fully reproducible in this environment + +## Short Handover Summary +- The codebase exists and runs. +- Upload/download features mostly exist. +- Search is implemented but is still the most fragile subsystem. +- A visible debug logging panel now exists in the web UI and should be used first when continuing work.