Skip to main content

JunkBox apps/hub-api 가이드

업무 개요​

  • Hub는 JunkBox의 관문이자 운영 콘솔임. 사용자는 Hub에서 한 번 로그인하고 포털에서 권한이 있는 앱으로 이동함.
  • 핵심 개념은 사용자와 앱 권한 코드(allowed_modules), 포털 메뉴(APP·SERVICE), 마스터데이터(공통코드·메타·AI 프롬프트), AI 사용 로그, 대시보드임.
  • 관리자는 HUB 권한으로 사용자·권한, 포털 메뉴, 공통코드, 메타, AI 프롬프트를 관리하고 AI 사용 로그를 확인함.
  • 대시보드는 홈서버 상태와 개인 관심 정보를 한 화면에 모아 보여줌.
  • 도구 화면은 Markdown 문서를 생성해 Vault에 등록하고 Linkding에 북마크를 등록함.
  • 다른 앱은 Hub가 발급한 JWT와 Hub internal API로 인증과 마스터데이터를 소비함. 로그인과 기준 데이터를 한 곳에 모아 앱마다 중복 구현하지 않는 것이 목적임.

1. 역할과 책임 경계​

  • apps/hub-api는 JunkBox의 상시 운영 허브임.
  • 인증 API, 공통 로그인 화면, 운영 관리자 화면, 공통 마스터 데이터 관리 API, 공통 마스터 데이터 런타임 제공자를 동시에 담당함.
  • 다른 앱과 모듈이 재사용할 공통 코드, 코드 타입, 메타, 포털 메뉴의 단일 관리 주체임.
  • Hub 로그인 사용자가 사용하는 도구 화면의 Markdown 문서 생성·Vault 등록과 Linkding 북마크 등록 API를 제공함.
  • chess-api, health-api, rename-api, wow-api 같은 타 앱의 공통 로그인 진입점 역할을 수행함.
  • health 앱의 운동 계획 생성은 health-api 규칙 엔진이 담당하며 hub-api의 역할 범위가 아님.

1.1 운동 계획 생성과의 경계​

  • health 앱의 운동 계획 생성 공개 진입점과 실행 주체는 health-api임.
  • hub-api는 workout이 참조하는 BODY_PART, WORKOUT_ROUTINE_MODE, WORKOUT_STATUS 공통코드와 로그인/세션 검증, internal master-data API를 제공함.
  • health 운동 종목 기준정보는 health SQLite tb_workout_exercise_m이 런타임 소스 오브 트루스이며, hub 공통코드 EXERCISE는 초기 bootstrap source로만 사용할 수 있음.

2. 런타임과 배포​

  • FastAPI 애플리케이션 엔트리포인트는 junkbox_hub_api.main:app임.
  • 기본 루트 /는 /portal로 리다이렉트됨.
  • 상태 확인 경로는 /health임.
  • OpenAPI 노출 경로는 /docs, /redoc, /openapi.json임.
  • 인증, 예외 처리, 공통 정적 자산 마운트, 웹 페이지 라우터, API 라우터를 하나의 앱에서 통합함.
  • apps/hub-ui/dist를 /hub-ui 경로로 직접 마운트함.
  • libs/shared-ui 산출 자산은 /shared-ui 경로로 직접 마운트함.
  • CORS 허용 origin 목록은 shared-core 설정의 server.cors_origins를 공통으로 사용함.

2.1 로컬 개발 서버 연동​

  • hub-api는 18001 포트 기준 백엔드로 실행할 수 있음.
  • apps/hub-ui는 15001 포트 기준 Vite 개발 서버로 실행할 수 있음.
  • just hub-backend는 터미널에서 백그라운드로 실행되고, VS Code hub:backend task는 같은 recipe를 전경 모드로 호출함. recipe는 JunkBox 프로젝트 루트에서 uv run --package junkbox-hub-api uvicorn ...을 사용하여 hub-api 패키지의 jinja2, python-multipart, uvicorn[standard] 같은 런타임 의존성을 해석함.
  • 페이지 HTML은 18001이 렌더링하고, React 엔트리와 HMR 자산은 15001/hub-ui/* 경로에서 로드함.
  • Vite 프록시는 검증된 localhost·LAN HTTP·Tailnet HTTPS 개발 origin을 x-junkbox-dev-server-url로 전달하며, 서버 렌더링 HTML은 해당 origin에서 React 엔트리와 HMR 자산을 로드함. 브라우저 접근 방식과 LAN 수신 구조는 코어 가이드의 로컬 개발 계약을 따름.
  • Hub CORS는 공통 설정 origin에 등록된 UI 개발 포트의 LAN HTTP와 Tailnet HTTPS origin을 추가하며 credentials 요청을 허용함. 18001 백엔드는 루프백 수신을 유지함.

2.2 운영 배포 기준​

  • Hub 운영 컨테이너 내부 포트는 8080이며 호스트 관리 도구 접근을 위한 127.0.0.1:8001:8080 loopback publish를 사용함.
  • 운영 이미지는 apps/hub-ui/dist, libs/shared-ui 자산, hub-api 실행 코드를 함께 포함함.
  • 운영 이미지는 오디오북 결합·인코딩에 쓰는 ffmpeg와 ffprobe를 포함함.
  • 운영 환경변수는 /sorc001/junkbox/env/.env.shared와 /sorc001/junkbox/env/.env.prod를 함께 참조하고, 컨테이너 내부 ENV_FILE=/app/env/.env.prod 기준으로 로딩함.
  • Hub 도구 연결 설정은 공통 Settings의 hub_tools.github, hub_tools.linkding이 소유함. 운영 Compose는 환경 디렉터리를 /app/env에 read-only로 마운트함.
  • 운영 Hub Compose는 Linkding 주소가 컨테이너 기준 localhost로 설정된 경우 호스트에 도달하도록 host.docker.internal:host-gateway를 등록함.
  • 운영 로그 볼륨은 /logs001/junkbox/hub-api 호스트 경로를 컨테이너 내부 /app/logs에 연결함.
  • Hub Compose는 EPUB 폴더 /ext001/book001/books를 같은 경로의 read-only로, 오디오북 작업 폴더 /ext001/data001/junkbox/hub/tools/audiobook-work를 같은 경로의 쓰기 가능으로 마운트함. 원본 EPUB을 읽기 전용으로 두어 변환이 원본을 바꾸지 못하게 함.
  • 공통 애플리케이션 로그 파일 경로는 /app/logs/app.log임.
  • Hub SQLite DB 파일은 호스트 /sorc001/junkbox/db/hub.sqlite3에 위치하고, 운영 컨테이너에서는 /sorc001/junkbox/db를 /app/db로 마운트해 /app/db/hub.sqlite3로 접근함.
  • 운영 HUB_DATABASE_URL은 sqlite+aiosqlite:////app/db/hub.sqlite3 값을 사용함.
  • 운영 AI 라우팅 파일은 호스트 /sorc001/junkbox/master-data/ai-routing.yml를 컨테이너 내부 /app/var/master-data/ai-routing.yml로 마운트해서 사용함.
  • 대시보드 런타임 정책값은 apps/hub-api/var/dashboard-policy.yml에서 관리함.
  • 대시보드 정책 파일은 로컬 Git 원본 기준 apps/hub-api/var/dashboard-policy.yml, 컨테이너 기준 /app/apps/hub-api/var/dashboard-policy.yml 경로를 사용함.
  • 대시보드 AI 카드의 OpenRouter credits와 API key별 사용량 조회에는 DASHBOARD_OPENROUTER_MANAGEMENT_API_KEY가 필요함.
  • Hub의 Health 음식 요약 조회는 HEALTH_INTERNAL_BASE_URL을 우선 사용하고, 없으면 HEALTH_BASE_URL을 사용함. 운영·로컬 Compose의 내부 주소는 http://junkbox-health:8080임.
  • 운영 OpenRouter Management API Key는 /sorc001/junkbox/env/.env.prod 같은 profile별 secret env에서 관리하며 .env.shared에 값을 두지 않음.
  • 공통 shared-ui CSS/JS 링크는 템플릿 컨텍스트의 shared_ui_asset() 헬퍼가 파일 수정 시각 기준 버전 쿼리를 붙여 렌더링함.
  • 공통 CSS 링크 선언은 shared-ui stylesheet 매크로를 통해 중앙화함.
  • 공통 CSS는 hub-ui-base.css와 화면 모드별 hub-ui-mobile.css, hub-ui-desktop.css를 조합해서 로드하며, 화면별 필요에 따라 두 모드 CSS를 함께 로드할 수 있음.
  • hub 공통 메뉴바는 화면 본문 폭 정책과 분리해서 뷰포트 기준으로 반응형 동작하며, PC-only 본문 화면도 모바일 폭에서는 드로어 메뉴를 사용함.

2.3 공통 로깅 초기화​

  • 앱 import 시점에 shared-core의 setup_app_logging()을 호출함.
  • 설정값은 settings.modules.hub.logging에서 읽음.
  • 로그 sink는 콘솔 출력과 파일 출력 두 축으로 동시에 구성됨.
  • 파일 정책은 rotation, retention, compression, enqueue 옵션을 공통 설정값 기준으로 적용함.
  • LOG_DIAGNOSE_TOGGLE이 켜진 profile에서는 diagnose, backtrace를 함께 활성화함.

3. 인증과 권한​

3.1 토큰 입력 경로​

  • API는 Authorization: Bearer 헤더와 COOKIE_NAME 설정값 기준 HttpOnly 쿠키를 모두 수용함.
  • 현재 기본 쿠키 이름은 JUNKBOX_AUTH임.
  • 인증 해석 우선순위는 Authorization 헤더가 먼저임.
  • 일반 사용자 JWT는 서명, 만료, sid claim, Hub SQLite tb_user_session_n의 활성 세션 상태를 모두 통과해야 유효함.
  • Swagger 인증도 같은 JWT 검증과 세션 유효성 확인 경로를 사용함.
  • AI 에이전트 표준 master-data API는 Bearer JWT의 role=ROLE_AI claim을 검증함.
  • ROLE_AI JWT는 일반 require_module(...) 기반 비즈니스 API 접근에 사용할 수 없으며 권한 의존성 단계에서 403으로 차단됨.

3.2 로그인과 페이지 접근 흐름​

  • 보호 페이지는 강제 인증 구조를 사용함.
  • 비로그인 요청은 /login?redirect=...&required_module=...로 리다이렉트됨.
  • 로그인 성공 시 redirect 값이 허용된 경로 또는 허용된 앱 origin이면 해당 위치로 이동함.
  • 로컬 profile의 로그인 복귀 허용 origin에는 공통 설정값 외에 등록된 UI 개발 포트의 LAN HTTP와 Tailnet HTTPS origin이 포함됨. 공유 접속에서 redirect가 없으면 요청 방식에 맞는 Health 음식 기록 또는 Chess 앱 주소를 기본 복귀 위치로 사용함.
  • redirect가 비어 있거나 허용되지 않으면 required_module 기준 기본 위치로 이동함.
  • required_module=HEALTH의 기본 복귀 위치는 Health 앱의 /diet-records이며, 기존 요청에 유효한 redirect가 있으면 해당 경로를 유지함.
  • required_module=APP는 네이티브 앱의 브라우저 로그인 인계에만 사용하며 로그인 자격 검증은 수행하되 HUB 관리자 권한을 요구하지 않음. 로그인 후 원래 /api/auth/app/authorize 요청으로 복귀함.
  • HUB 보호 페이지는 HUB 권한을 요구함.
  • allowed_modules에 과거 SYSTEM 값이 있어도 내부 판단은 HUB 권한으로 정규화하여 처리함.
  • CHESS 앱에서 공통 로그인으로 들어온 경우 required_module=CHESS 기준 검증을 수행함.
  • HEALTH 앱에서 공통 로그인으로 들어온 경우 required_module=HEALTH 기준 검증을 수행함.
  • WOW 앱에서 공통 로그인으로 들어온 경우 required_module=WOW 기준 검증을 수행함.
  • SIPMON 앱에서 공통 로그인으로 들어온 경우 required_module=SIPMON 기준 검증을 수행하고, 유효한 redirect가 없으면 SipMon /dashboard로 복귀함.
  • KNOWBIT 앱에서 공통 로그인으로 들어온 경우 required_module=KNOWBIT 기준 검증을 수행하고, 유효한 redirect가 없으면 Knowbit /learn으로 복귀함.
  • QUESTLOG 앱에서 공통 로그인으로 들어온 경우 required_module=QUESTLOG 기준 검증을 수행하고, 유효한 redirect가 없으면 QuestLog /quests로 복귀함. 허용 redirect origin에 QuestLog 운영 URL과 개발 UI 15013을 포함함.
  • 요구 모듈 권한이 없으면 공통 로그인 화면으로 돌아가며 permission_denied=1을 전달함.
  • 로그인 화면은 permission_denied=1을 감지하면 권한 없음 alert를 한 번 표시하고 현재 URL에서 해당 쿼리 플래그를 제거함.
  • 현재 세션 검증 결과의 allowed_modules에 요구 모듈이 없으면 로그인 화면을 다시 렌더링하여 credential 재검증 후 최신 권한 claim이 포함된 JWT를 발급할 수 있음.
  • 최근 로그인에 성공한 아이디는 공통 쿠키에 기록되며, 이후 로그인 화면 진입 시 기본 아이디 값으로 다시 채워짐.
  • 인증 쿠키와 최근 로그인 아이디 쿠키는 검증된 Tailnet HTTPS 개발 요청에서 Secure를 사용함. LAN HTTP 개발 요청은 로컬 쿠키 설정을 따름.

3.3 JWT 갱신 흐름​

  • 사용자 세션 만료 시간과 슬라이딩 갱신 임계값은 apps/hub-api/var/auth-policy.yml에서 관리함.
  • 현재 세션 정책은 expiration_minutes=120, sliding_threshold_minutes=30임.
  • 로그인 성공 시 hub-api는 세션 정책의 만료 시간을 기준으로 Hub SQLite tb_user_session_n에 사용자 세션 row를 생성하고 JWT sid, JWT exp, HttpOnly 쿠키 max_age를 설정함.
  • 사용자 세션은 session_id, user_id, issued_at, expires_at, revoked_at, last_seen_at, user_agent, ip_address, is_active 값을 포함함.
  • JWT의 sid claim은 Hub SQLite tb_user_session_n.session_id와 매칭되어야 함.
  • 일반 사용자 JWT 검증은 JWT 서명과 만료뿐 아니라 세션 row의 활성 상태, revoke 상태, 만료 시각, 사용자 활성 상태를 확인함.
  • hub-api도 공통 SlidingSessionMiddleware를 등록하여 브라우저 쿠키 기반 요청의 세션 갱신을 처리함.
  • POST /api/internal/auth/validate는 개별 앱과 공통 인증 의존성이 일반 사용자 JWT의 세션 유효성을 hub에 위임할 때 사용하는 내부 API임.
  • POST /api/internal/auth/refresh는 현재 JWT와 세션 row를 검증하고, 만료까지 남은 시간이 슬라이딩 임계값 이하이면 같은 sid와 DB의 최신 사용자 권한 기준으로 새 JWT를 발급함.
  • 개별 앱의 슬라이딩 세션 미들웨어는 직접 JWT를 재발급하지 않고 POST /api/internal/auth/refresh에 갱신 판단과 토큰 발급을 위임함.
  • 로그아웃은 현재 요청 토큰의 sid에 해당하는 세션 row를 revoke하고 인증 쿠키를 만료시킴.
  • 사용자 비밀번호 변경, 계정 비활성화, 권한 변경, 사용자 삭제는 해당 사용자의 활성 세션을 revoke함.
  • 만료되었거나 유효하지 않거나 revoke된 토큰은 슬라이딩 갱신 대상이 아니며, 표준 인증 실패 흐름에서 로그인 재진입 또는 JSON 401로 처리됨.

3.4 API 실패 정책​

  • 인증 실패는 JSON 401 응답임.
  • 권한 부족은 JSON 403 응답임.
  • HTML 페이지는 JSON 오류를 직접 노출하지 않고 로그인 또는 로그인 화면의 권한 없음 alert 흐름으로 분기함.
  • HTML 권한 부족에 대한 별도 권한 오류 템플릿은 사용하지 않음.

4. 데이터​

4.1 Hub SQLite 공통 마스터 데이터​

  • 공통코드와 코드 타입은 Hub SQLite tb_common_c, tb_code_type_c를 소스 오브 트루스로 사용함.
  • 메타는 Hub SQLite tb_meta_m을 소스 오브 트루스로 사용함.
  • AI 프롬프트와 버전 이력은 Hub SQLite tb_ai_prompt_m을 소스 오브 트루스로 사용함. PromptStore가 현재 버전·활성 상태를 관리함.
  • 포털 메뉴는 Hub SQLite tb_portal_menu_m을 소스 오브 트루스로 사용함.
  • 네이티브 인증 일회용 코드 해시·사용자·PKCE challenge·만료·사용 시각은 Hub SQLite tb_app_auth_code_n에 저장함. 원문 코드나 앱 토큰은 이 테이블에 저장하지 않음.
  • 일반 UI 텍스트와 사용자 메시지는 DB 기반 공통 마스터 데이터 대상이 아니며 각 앱의 소스 코드에 한국어 문구로 직접 작성함.
  • apps/hub-api는 DB를 직접 다루지 않고 shared-core의 공통 마스터 데이터 저장소를 통해 읽고 저장함.
  • 저장소 클래스 이름은 JsonMasterDataStore를 유지하지만 현재 구현은 DB 기반임.
  • AI 전용 read-only API도 같은 저장소 계층을 재사용하며 별도 복제 저장소를 두지 않음.
  • hub-api는 앱 import 시점에 settings.modules.hub.database_url을 사용해 shared-core 전역 async engine을 Hub SQLite로 초기화함.
  • 로컬 비컨테이너 실행의 기본 Hub DSN은 sqlite+aiosqlite:////sorc001/junkbox/db/hub.sqlite3임.
  • Docker 실행의 Hub DSN은 sqlite+aiosqlite:////app/db/hub.sqlite3이며 compose가 호스트 /sorc001/junkbox/db를 컨테이너 /app/db로 마운트함.
  • SQLite 연결은 DB 파일 부모 디렉터리를 준비하고 PRAGMA journal_mode=WAL, PRAGMA busy_timeout=5000, PRAGMA foreign_keys=ON을 적용함.

4.2 YAML 기반 AI 라우팅 데이터​

  • AI 기능별 라우팅은 YAML 파일을 소스 오브 트루스로 사용함.
  • 로컬 Git 원본 경로는 apps/hub-api/var/master-data/ai-routing.yml임.
  • 컨테이너 런타임 기본 경로는 /app/var/master-data/ai-routing.yml임.
  • 운영 호스트 공통 파일 경로는 /sorc001/junkbox/master-data/ai-routing.yml임.
  • APP_PROFILE 값에 따라 ai-routing.local.yml, ai-routing.prod.yml 같은 profile별 파일을 우선 선택함.
  • profile별 파일이 없으면 기본 ai-routing.yml을 사용함.

4.3 Hub SQLite 리소스​

  • 사용자는 DB 기반 구조를 사용함.
  • AI 로그 DTO와 writer protocol은 shared-ai가 소유하고, hub-api는 Hub SQLite 저장, 조회 API, 운영 화면을 제공함.
  • 사용자 리소스는 Hub SQLite tb_user_m를 기준으로 하며 id 물리 PK, user_id 논리 식별자 구조를 사용함.
  • 사용자 allowed_modules는 HUB, CHESS, HEALTH, RENAME, WOW, TRACK, MESSAGE, BIZCARD, SIPMON, KNOWBIT, QUESTLOG 앱 모듈 접근 권한을 SQLite JSON 배열로 저장함. 사용자 관리 권한 선택지도 이 코드들로 제한하며 사용하지 않는 SAM, TELEGRAM, EXTERNAL은 제공하지 않음.
  • 사용자 로그인 세션은 Hub SQLite tb_user_session_n를 기준으로 하며 session_id가 JWT sid claim과 매칭됨.
  • 세션 row는 다중 기기 로그인을 허용하는 사용자별 세션 단위 상태이며, 로그아웃 또는 사용자 보안 속성 변경 시 revoke됨.
  • AI 사용 로그는 Hub SQLite tb_ai_usage_logs_n를 기준으로 함.
  • tb_ai_usage_logs_n의 선택적 요청 ID와 시도 순번으로 구조화 호출을 찾음. tb_ai_response_diagnostics_n은 사용 로그 ID와 단계별 진단을 보유하며 사용 로그 삭제 시 함께 삭제됨.
  • 구조화 응답 진단 스키마의 적용 도구는 JunkBox의 scripts/migrate_hub_ai_response_diagnostics.py임. 적용 순서는 Hub SQLite 스키마, Hub API, 진단을 보내는 호출자 순임.
  • Hub 외부 앱의 AI 런타임은 Hub internal usage-log API만 호출하며, Hub SQLite 파일 또는 Hub 세션 메이커에 직접 접근하지 않음.
  • 사용자 생성과 수정 시 created_by, updated_by는 사용자 id 기준으로 기록함.

4.4 오디오북 변환 데이터​

  • tb_hub_audiobook_job_n은 변환 작업(미리듣기·챕터·전체) 한 건을 저장함. 상태는 PENDING·RUNNING·SUCCEEDED·FAILED·CANCEL_REQUESTED·CANCELED임.
  • 작업 행은 EPUB 루트 기준 상대 경로, 음성, 출력 형식, 구간 진행 수, 예상·과금 문자 수, 작업 폴더 기준 결과 경로, 사용자에게 보여 줄 오류 문구를 가짐. 삭제는 deleted_at으로 표시함.
  • 오디오북 전용 사용량 테이블은 없고 음성 합성 호출 1건당 1행이 공통 AI 사용 로그 tb_ai_usage_logs_n에 쌓임. module_code=HUB, feature_code=TOOLS_AUDIOBOOK, usage_unit=CHARACTER, usage_quantity는 입력 문자 수, usage_status는 RESERVED·SUCCEEDED·FAILED·UNKNOWN임. 비용은 LiteLLM이 돌려준 est_cost(USD)임.
  • 월 집계는 KST 당월의 RESERVED·SUCCEEDED·UNKNOWN usage_quantity 합계이며 FAILED를 제외함. 과금 여부를 알 수 없는 호출을 사용한 것으로 세어 월 상한을 보수적으로 지키기 위함임.
  • 사용 로그는 작업 삭제와 무관하게 유지하며 작업과 외래키로 묶지 않고 input_params의 audiobook_job_id·구간 키로 추적함. 본문 텍스트와 오디오는 기록하지 않음.
  • 구간 캐시는 DB가 아니라 작업 폴더의 cache/<음성>/<sha256>.mp3 파일임. 키는 엔진·음성·인코딩·텍스트의 해시임.

5. API와 화면 진입​

5.1 인증 API​

  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/verify
  • GET /api/auth/encrypt
  • GET /api/auth/app/authorize: 브라우저 로그인 쿠키와 state·PKCE code_challenge를 검증하고 2분 유효 일회용 코드를 공통 native_app_scheme(request)에 따라 운영 junkbox://auth 또는 검증된 local/docker-local 개발 UI의 junkbox-dev://auth로 전달함.
    • 운영 profile은 개발 origin 헤더가 있어도 운영 scheme을 유지하며 코드·PKCE·세션 저장 계약은 동일함.
    • 미인증 시 required_module=APP 로그인으로 연결함.
  • POST /api/auth/app/exchange: 코드 해시·PKCE verifier·만료·미사용 조건을 원자적으로 검증하고 사용자 세션 JWT를 발급함.
  • POST /api/auth/app/refresh: Bearer 앱 세션을 Hub 정책에 따라 갱신하고 JWT를 반환함.

5.2 hub API​

  • 공통코드 API
    • GET /api/hub/codes/types
    • GET /api/hub/codes/types/with-counts
    • POST /api/hub/codes/types
    • GET /api/hub/codes/types/{code_type_code}/meta
    • PATCH /api/hub/codes/types/{code_type_code}/meta
    • DELETE /api/hub/codes/types/{code_type_code}
    • GET /api/hub/codes/{code_type_code}
    • GET /api/hub/codes/{code_type_code}/all
    • POST /api/hub/codes/batch
  • 메타 API
    • GET /api/hub/metas
    • GET /api/hub/metas/progressive
    • GET /api/hub/metas/{meta_id}
    • GET /api/hub/metas/by-key/{meta_key}
    • POST /api/hub/metas
    • PATCH /api/hub/metas/{meta_id}
    • DELETE /api/hub/metas/{meta_id}
  • AI 프롬프트 API (require_module("HUB") 적용)
    • GET /api/hub/prompts
    • GET /api/hub/prompts/by-key/{prompt_key}
    • GET /api/hub/prompts/{prompt_key}/versions
    • POST /api/hub/prompts
    • POST /api/hub/prompts/versions/{prompt_id}/activate
    • PATCH /api/hub/prompts/{prompt_key}/active
  • 포털 메뉴 API
    • GET /api/hub/portal-menus
    • GET /api/hub/portal-menus/{menu_id}
    • POST /api/hub/portal-menus
    • PATCH /api/hub/portal-menus/{menu_id}
    • DELETE /api/hub/portal-menus/{menu_id}
  • 사용자 API
    • GET /api/hub/users
    • GET /api/hub/users/progressive
    • GET /api/hub/users/{user_id}
    • POST /api/hub/users
    • PATCH /api/hub/users/{user_id}
    • DELETE /api/hub/users/{user_id}
  • AI 로그 API
    • GET /api/hub/ai-logs
      • createdDateFrom·createdDateTo의 KST 날짜 범위에 헤더 필터와 sort를 적용함. 기본 정렬은 최신순이며 비용 정렬은 미산정 행을 뒤에 배치함.
      • 페이지 첫 응답의 snapshotId를 이어지는 요청에 전달하면 그 ID 이후에 쌓인 행을 제외함. 같은 비용에서는 최신 시각과 로그 ID로 순서를 결정함.
    • GET /api/hub/ai-logs/summary
    • GET /api/hub/ai-logs/{usage_log_id}
      • 구조화 호출이면 선택적 structuredDiagnostics로 같은 요청의 관련 호출과 단계별 검증 결과를 반환함. 조회는 HUB 모듈 권한을 사용함.
  • 대시보드 API
    • GET /api/hub/dashboard
    • GET /api/hub/dashboard?forceRefresh=true
    • GET /api/hub/dashboard/diet는 HUB와 HEALTH 권한을 모두 요구하고 현재 사용자의 인증 토큰으로 QuestLog GET /api/questlog/missions/status를 호출해 식단 카드를 만듦(식단 카드 절).
      • 목표·기간·판정의 단일 관리 주체는 QuestLog 사용자별 설정과 미션 판정이며 Hub 메타는 대시보드 응답에서 읽지 않음.
      • 응답은 Cache-Control: no-store로 제공하고 사용자별 섭취량은 대시보드의 공통 수집 캐시에 넣지 않음.
    • GET /api/hub/dashboard/preferences
    • PATCH /api/hub/dashboard/preferences
    • POST /api/hub/dashboard/investments/reorder
  • 도구 API (require_module("HUB") 적용)
    • GET /api/hub/tools/md/categories
    • POST /api/hub/tools/md/generate
    • POST /api/hub/tools/md/publish
    • POST /api/hub/tools/bookmarks/check
    • POST /api/hub/tools/bookmarks/analyze
    • POST /api/hub/tools/bookmarks/save
    • POST /api/hub/tools/master-data/refresh
  • GET /api/hub/users/progressive는 사용자 PK id의 숫자 헤더 조건과 user_id, updated_by의 텍스트 헤더 조건을 목록·총 건수에 동일하게 적용함.
  • GET /api/hub/metas/progressive는 meta_key, description에 공통 헤더 검색 문법을 적용함. 마스터 데이터 저장소의 다른 메타 조회는 기존 일부 포함 검색 계약을 유지함.
  • GET /api/hub/ai-logs는 module_code, feature_code, full_model_id, sender_id의 텍스트 헤더 조건을 목록과 총 건수 조회에 공통 검색 문법으로 적용함. 별도 /summary API는 기간별 전체 요약 계약을 유지함.

오디오북 API​

  • 모든 API에 require_module("HUB")를 적용하며 접두사는 /api/hub/tools/audiobook임.
    • GET /status, GET /files, GET /book, POST /estimate
    • POST /previews, POST /conversions
    • GET /jobs(epub_path 생략 시 EPUB과 무관하게 전체 작업 최신순), GET /jobs/{job_id}, GET /jobs/{job_id}/audio
    • POST /jobs/{job_id}/cancel, POST /jobs/{job_id}/resume, DELETE /jobs/{job_id}
  • 오디오북 내부 Job API: POST /api/hub/internal/automation/audiobook-convert는 Automation worker만 require_automation_job("hub.audiobook-convert")로 호출함.

5.3 내부 master-data API​

  • GET /api/internal/master-data/codes/{code_type_code}
  • GET /api/internal/master-data/metas/by-key/{meta_key}
  • GET /api/internal/master-data/prompts/by-key/{prompt_key}
  • GET /api/internal/master-data/portal-menus
  • POST /api/internal/master-data/ai-usage-logs, POST /api/internal/master-data/ai-usage-logs/reservations, PATCH /api/internal/master-data/ai-usage-logs/{usage_log_id}
  • PUT /api/internal/master-data/ai-usage-logs/{usage_log_id}/diagnostics는 성공한 사용 로그에 요청 ID와 시도 순번이 일치하는 단계별 진단을 적재함. 같은 사용 로그 ID와 단계의 재전송은 최초 기록을 보존함.
  • POST /api/internal/master-data/cache/refresh
  • 내부 API는 서버 간 호출 전용이며, HUB_API_INTERNAL_TOKEN_HEADER 헤더와 토큰 검증을 통과한 요청만 허용함.
  • AI usage-log 기록 요청은 module, feature, full model id, channel, sender, input/output, token 수, 성공 여부, 실행 시간, 실행 시각, 비용, 과금 단위·수량·호출 상태(usage_unit·usage_quantity·usage_status)를 받음. reservations는 월 상한 검사와 RESERVED 행 삽입을 한 트랜잭션으로 처리하고 상한 초과 시 409를 반환하며, PATCH는 예약 행을 결과 상태·비용으로 갱신함.
  • AI 사용 기록의 offset 포함 실행 시각과 SQLite의 timezone 없는 KST 시각은 shared-core.ensure_kst()로 한국 시간에 정규화해 조회 응답과 날짜 필터에 사용함. 서버 로컬 시간대에 의존하지 않음.
  • 응답은 HTTP 201과 usage_log_id를 반환함. 토큰 누락은 401, 토큰 불일치는 403, Hub internal token 설정 누락은 503으로 처리함.

5.4 내부 인증 API​

  • POST /api/internal/auth/validate
  • POST /api/internal/auth/refresh
  • GET /api/internal/auth/health-report-owner는 자동 리포트·발송의 소유자 적격성을 확인하기 위해 활성 계정의 HEALTH·QUESTLOG 권한을 반환함.
  • 내부 인증 API는 서버 간 호출 전용이며, HUB_API_INTERNAL_TOKEN_HEADER 헤더와 토큰 검증을 통과한 요청만 허용함.
  • POST /api/internal/auth/validate는 요청 body의 현재 JWT를 검증하고 Hub SQLite tb_user_session_n 기준 세션 유효성을 확인한 뒤 현재 사용자, 권한, role, session_id를 반환함.
  • POST /api/internal/auth/refresh는 요청 body의 현재 JWT를 검증하고, 세션 테이블과 세션 정책의 슬라이딩 임계값 기준으로 새 JWT 발급 필요 여부를 반환함.
  • 토큰이 유효하고 갱신이 필요 없으면 refreshed=false, token=null, max_age_seconds를 반환함.
  • 토큰이 유효하고 갱신이 필요하면 refreshed=true, 새 token, max_age_seconds를 반환함.

5.5 AI master-data API​

  • GET /api/v1/master/all
  • /api/v1/master/all은 AI 에이전트 표준 통합 조회 경로이며 ROLE_AI JWT를 요구함.
  • POST /api/v1/master/ai-usage-logs는 개발 도구(문서 임베딩 동기화·검색)가 호출 사용량을 공통 AI 사용 로그에 남기는 ROLE_AI 전용 경로이며 모듈은 VAULT임.
  • 통합 snapshot API는 exported_at, code_types, codes, metas, prompts를 하나의 JSON 응답으로 반환함.

5.6 포털 API​

  • GET /api/portal/config
  • POST /api/portal/config

5.7 웹 화면​

  • GET /login
  • POST /login
  • GET /dashboard
  • GET /portal
  • GET /tools
  • GET /tools/md
  • GET /tools/audiobook
  • GET /tools/pro-wrestling-news
  • GET /portal-menus
  • GET /users
  • GET /codes
  • GET /metas
  • GET /prompts
  • GET /ai-logs
  • GET /error/403
  • /error/403은 하위 호환 진입점이며 권한 없음 처리는 코어 가이드 인증 절의 실패 정책을 따름.

6. 연동​

6.1 공통 라이브러리 의존​

  • hub-api는 provider 구현 자체를 직접 소유하지 않음.
  • 공통 AI 기능은 libs/shared-ai를 통해 사용함.

6.2 라우팅과 프로필​

  • 기능별 provider/model 선택은 ai-routing.yml 계열 YAML이 결정함.
  • provider API 키와 base URL은 .env.shared + ENV_FILE 조합이 결정함.
  • Hub Markdown 생성과 URL 분석은 LiteLLM provider를 사용하며 모델 연결은 AI 라우팅 YAML이 소유함.
  • Hub 도구의 AI 호출은 HUB_TOOLS_MD, HUB_TOOLS_BOOKMARK route key와 AIBOT_MD_INSTRUCTION, AIBOT_MD_USER_TEMPLATE, AIBOT_WEB_ANALYSIS_INSTRUCTION AI 프롬프트를 재사용함. usage log의 module은 HUB, feature는 TOOLS_MD 또는 TOOLS_BOOKMARK임.
  • 모델·단가 원본은 LiteLLM이며 AI_MODEL 공통코드와 별도의 Hub 모델·단가 관리 화면을 사용하지 않음. 비용 수집 계약은 docs/junkbox/libs/guide-lib-shared-ai.md를 따름.
  • usage log의 full_model_id는 라우팅 YAML의 provider:model 조합이며 litellm: 접두어도 공통 라우팅에서 자동 구성함.
  • est_cost는 LiteLLM 응답의 x-litellm-response-cost 헤더에서 얻은 USD 예상 비용이고, 미산정은 NULL임. 모델 설정·단가 변경 시 과거 로그의 모델명·토큰·비용을 재계산하지 않음.
  • /api/hub/ai-logs/summary는 오늘과 오늘을 포함한 최근 7일의 비용 합계 및 미산정 건수를 제공함. 비용 합계는 NULL을 제외하고 명시적 0을 포함함.
  • avgExecutionTimeMs는 실행 시간이 기록된 오늘의 성공 호출을 집계함.
  • AI 로그 화면의 원화 표시는 메타 EXCHANGE_RATE의 meta_val을 1달러당 원화 숫자값으로 사용함.
  • 어떤 provider 어댑터가 선택되는지는 model이 아니라 라우팅 YAML의 provider 값이 결정함.

6.3 structured output과 fallback​

  • shared-ai의 공통 structured generation 계층이 JSON 파싱, Pydantic 검증, JSON 재생성, usage log 누적을 처리함.
  • LiteLLM proxy는 route의 structured_output_mode와 모델 계열에 따라 response format을 선택함.
  • Gemini 계열 auto 전략은 response_format={"type":"json_object","response_schema":...}를 우선 시도함.
  • LiteLLM 또는 하위 모델이 response format 옵션을 거부하면 JSON only 지시문 강화 fallback 요청을 1회 재시도함.
  • 따라서 AI route의 provider/model이 변경되어도 structured output 계약을 우선 유지하는 구조임.

6.4 오디오북 외부 연동​

  • 음성 합성은 shared-ai의 SharedAiService.synthesize_speech로 LiteLLM /audio/speech를 호출함. 라우팅은 ai-routing*.yml의 HUB_AUDIOBOOK_TTS route이며 LiteLLM에 등록된 Google Chirp 3 HD 모델 google-chirp3-hd를 가리킴. Google 인증(서비스 계정)은 LiteLLM이 소유하고 Hub는 LITELLM_API_KEY만 사용함.
  • 공백·줄바꿈을 포함한 Chirp 3 HD 예상 비용 계산은 ops/litellm/Dockerfile로 빌드하는 LiteLLM 이미지가 담당함. 별도 LiteLLM Compose의 이미지 선택은 ops/litellm/compose.chirp-cost.yml에서 정의함.
  • 엔진과 음성 목록은 코드 레지스트리 services/audiobook/tts.py의 ENGINES가 소유함. 엔진·음성 추가는 이 레지스트리만 고침.
  • Hub는 AUTOMATION_BASE_URL과 서비스 토큰으로 변환 실행을 Automation에 등록하고 상태를 조회함. Automation worker는 HUB_INTERNAL_BASE_URL로 Hub 내부 Job API를 호출함.

7. 화면 구조​

7.1 공통 구조​

  • 모든 관리자 화면은 공통 베이스 템플릿과 shared-ui 산출 자산을 사용함.
  • React 운영 화면 소스는 apps/hub-ui에서 .ts/.tsx 기준으로 관리함.
  • 공통 베이스 템플릿은 dev client와 React refresh preamble의 단일 선언 지점임.
  • 공통 베이스 템플릿은 shared-ui stylesheet 매크로를 import하고, hub-ui-base.css, hub-ui-mobile.css, hub-ui-desktop.css, junkbox-tabulator.css, app-shell.js에 버전 쿼리를 붙여 운영 캐시 잔존 영향을 줄임.
  • 공통 베이스 템플릿은 favicon_url 컨텍스트가 있으면 <link rel="icon">을 렌더링함.
  • 공통 베이스 템플릿은 기본적으로 body_mode_class에 mobile 문자열이 포함되면 mobile CSS를, 그 외에는 desktop CSS를 로드함.
  • 화면 컨텍스트에서 include_mobile_css 또는 include_desktop_css를 지정하면 기본 CSS 조합에 필요한 모드 CSS를 추가로 로드할 수 있음. /portal은 본문 모바일 폭을 유지하면서 상단 메뉴를 PC/모바일 반응형으로 표시하기 위해 mobile CSS와 desktop CSS를 함께 로드함.
  • 공통 베이스 템플릿은 inline <style> 블록을 포함하지 않으며, 모든 스타일은 shared-ui 산출 CSS에서 공급됨.
  • hub 웹 화면의 favicon은 포털 메뉴의 menu_type_code=APP, icon_type_code=APP_ICON, icon_val 조합에서 hub 앱 아이콘 slug를 해석하고, 없으면 hub slug를 fallback으로 사용함.
  • 서버 템플릿 문구는 템플릿 또는 라우터 컨텍스트에 한국어 문구로 직접 작성함.
  • 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값만 DB 조회 구조를 사용함.

7.2 로그인 화면​

  • 로그인 화면은 서버 렌더링 폼 구조임.
  • 공통 로그인 화면은 최소 텍스트 중심의 단순한 구조를 사용함.
  • 로그인 폼은 화면 중앙의 모바일 고정 폭 카드 안에 배치함. 흰색 로그인 버튼은 폼 내부에 두고 일반 모바일 액션 버튼과 같은 3.25rem 최소 높이를 사용함.
  • 로그인 화면 상단 eyebrow 브랜드 텍스트는 JUNKBOX를 사용함.
  • 인증 오류는 서버에서 다시 로그인 페이지를 렌더링하면서 메시지를 주입하는 방식임.
  • 최근 로그인 성공 아이디가 있으면 공통 쿠키 값을 기본 아이디 입력값으로 사용함.

7.3 포털 화면​

  • 포털은 운영 허브 홈 화면임.
  • APP와 SERVICE 탭을 사용하여 카드 그룹을 분리함.
  • APP 탭은 포털 메뉴의 menu_type_code=APP 값을 기준으로 구성함.
  • 하위 호환을 위해 DB에 남아 있는 menu_type_code=PROJECT 값은 포털 소비 화면과 정렬 저장에서 APP 탭으로 해석함.
  • 포털 소비 화면의 탭 외형과 선택 상호작용은 hub-ui가 shared-ui 공통 segmented tab 계약으로 렌더링함.
  • 카드 설명 노출 여부와 아이콘 렌더링 방식은 포털 메뉴 저장소의 is_desc_visible, icon_type_code, icon_val 기준으로 결정함.
  • icon_type_code=TEXT는 icon_val을 텍스트 아이콘으로 표시함.
  • icon_type_code=IMAGE는 icon_val을 이미지 URL로 사용함.
  • icon_type_code=APP_ICON은 icon_val을 shared-ui 앱 아이콘 slug로 해석하여 /shared-ui/app-icons/{icon_val}/icon.svg를 포털 카드 아이콘으로 사용함.
  • 포털 메뉴의 APP_ICON + icon_val 조합은 포털 카드 아이콘, 앱 favicon, PWA 아이콘을 같은 앱 아이콘 세트로 연결하는 단일 관리 지점임.
  • 로컬 프로필에서는 local_menu_url, 그 외 프로필에서는 menu_url을 소비함.
  • 로컬 프로필의 GET /api/portal/config는 등록된 localhost UI 포트의 local_menu_url을 요청자의 LAN HTTP 또는 Tailnet HTTPS origin에 맞춰 응답하며 저장된 포털 메뉴 값은 변경하지 않음.

7.4 대시보드 화면​

개요​

  • /dashboard는 포털과 분리된 동적 데이터 대시보드 화면임.
  • 대시보드는 소식/핫딜, AI 사용량, 투자 관심 목록, 홈서버 상태를 카드 단위로 표시함.

식단 카드​

  • GET /api/hub/dashboard/diet는 HUB와 HEALTH 권한을 모두 요구하고 현재 사용자의 인증 토큰으로 QuestLog GET /api/questlog/missions/status?codes=DAILY_CALORIE_LIMIT&codes=WEEKLY_CALORIE_AVG_LIMIT(QUESTLOG_INTERNAL_BASE_URL 우선, 타임아웃 8초)를 호출함.
    • Hub는 Health 집계를 직접 조회하거나 평균·판정을 계산하지 않고 QuestLog가 계산한 두 미션의 목표·실적·판정·예정분을 식단 카드 형식으로 옮겨 담음. 주 기준은 QuestLog의 주간 평균 열량 미션에 고정된 월요일을 따름.
    • QuestLog 호출이 실패하거나 사용자에게 QUESTLOG 권한이 없으면 502로 응답하고 대시보드의 다른 카드는 유지함.
    • 대시보드는 QuestLog 판정 응답의 목표를 표시함. 원본 목표의 관리 주체는 Health임.
    • 응답은 Cache-Control: no-store로 제공하고 사용자별 섭취량은 대시보드의 공통 수집 캐시에 넣지 않음.
  • 응답은 targetKcal, weeklyTargetKcal, 오늘 먹은 양 todayKcal(판정 불가면 null, 기록이 없으면 0), 아직 먹지 않은 예정분 todayPlannedKcal, 판정 상태 todayStatus·weekStatus(IN_PROGRESS·FAIL, 판정 불가면 null), 이번 주 지난 날짜 평균 weekAverageKcal(지난 날이 없으면 null), weekIncludesToday임.
    • 평균·초과 판정은 QuestLog 주간 평균 열량 미션의 판정 그대로이며(기록 없는 날은 0, 주간 한도를 넘겨 실패하면 평균에 오늘 포함, weekIncludesToday는 QuestLog의 basisNote가 오늘 포함일 때 참) 판정은 예정분을 뺀 먹은 양만 사용함.

뉴스·핫딜 카드​

  • 뉴스 카드는 wmania 최신뉴스와 네이버 스포츠 야구/해외야구 인기 기사 API를 HTTP 방식으로 수집함.
  • 네이버 스포츠 야구/해외야구 수집은 api-gw.sports.naver.com/news/articles/{section}에 KST 기준 오늘 날짜를 yyyyMMdd 형식으로 넣고 sort=popular, page=1, pageSize=5, isPhoto=N으로 조회함. 수집에는 curl-cffi를 사용하며 카드의 전체보기 URL은 sports.news.naver.com/{section}/index 계열 URL을 유지함.
  • 핫딜 카드는 FMKorea 핫딜 인기순 페이지의 HTML 목록에서 최신 5건의 제목, 링크, 쇼핑몰/가격/배송 정보를 수집함.
  • 대시보드 데이터는 사용자 요청이 있을 때만 수집하며, 전체 응답을 사용자 공통 인메모리 캐시에 30분간 보관함. 다른 사용자의 요청도 유효한 전체 응답 캐시를 재사용하고, 만료된 뒤 처음 들어오는 요청에서 다시 수집함.
  • WMania, 네이버 스포츠, FunETF의 성공 수집 캐시와 FMKorea 핫딜 수집 캐시도 30분을 기준으로 함. 수동 새로고침은 전체 응답 및 일반 source 캐시를 무시하고 다시 수집하며, 완료 시점부터 전체 응답의 30분 TTL을 다시 계산함. 일시 제한에 따른 재요청 차단 시간은 유지함.
  • WMania/핫딜 수집 응답이 Retry-After를 포함한 일시 제한 상태이면 해당 시간 동안 재요청을 피하고, 이전 성공 카드가 있으면 stale 데이터를 우선 표시함.
  • FMKorea 핫딜 수집이 HTTP 430 차단 상태를 반환하고 이전 성공 카드가 있으면 카드의 항목 목록과 updatedAt은 마지막 성공 데이터 기준으로 유지하고, status=error와 차단 상태 오류 메시지를 함께 반환함.
  • FMKorea 핫딜 수집이 HTTP 430 차단 상태를 반환하지만 이전 성공 카드가 없으면 항목 없는 오류 카드로 표시함.
  • 외부 HTML source별 성공 카드와 차단 상태는 hub-api 프로세스 인메모리 캐시에 저장되며, 프로세스 재시작 후에는 이전 성공 카드가 유지되지 않음.

투자 카드​

  • 국내 주식 카드는 DASHBOARD_STOCK_DOMESTIC 공통코드 목록을 기준으로 네이버 금융 국내 주식과 국내 지수 API를 조회함.
  • 해외 주식 카드는 DASHBOARD_STOCK_OVERSEAS 공통코드 목록을 기준으로 네이버 금융 해외 주식과 해외 지수 API를 조회함.
  • 펀드 카드는 DASHBOARD_FUND 공통코드 목록을 기준으로 FunETF 공개 기준가 API를 조회함.
  • 펀드 카드는 성공 수집 행을 hub-api 프로세스 인메모리 캐시에 저장하며, FunETF가 HTTP 429 또는 Cloudflare 확인 응답을 반환하면 재요청을 잠시 피하고 이전 성공 펀드 행을 우선 반환함.
  • FunETF 일시 제한 상태에서 이전 성공 펀드 캐시가 없으면 펀드 항목은 카드 내부 오류 항목으로 반환됨.
  • 투자 카드 항목 순서는 공통코드의 sort_order_no를 따름.
  • POST /api/hub/dashboard/investments/reorder는 펀드/국내 주식/해외 주식 카드의 드래그 정렬 결과를 받아 해당 공통코드의 sort_order_no를 10 단위로 재부여함.
  • POST /api/hub/dashboard/investments/reorder의 assetType은 FUND, STOCK_DOMESTIC, STOCK_OVERSEAS만 사용함.
  • 투자 카드가 읽는 DASHBOARD_STOCK_DOMESTIC, DASHBOARD_STOCK_OVERSEAS, DASHBOARD_FUND 공통코드의 common_code·attribute01~03 의미는 docs/junkbox/common/guide-jb-common-master-data.md의 Hub 대시보드 코드 타입이 소유함.
  • 대시보드 투자 수집 provider는 공통코드 속성값으로 전환하지 않으며, 주식/지수는 네이버 금융, 펀드는 FunETF 수집기로 고정됨.

사용자 preference​

  • GET /api/hub/dashboard/preferences는 현재 로그인 사용자의 대시보드 즐겨찾기 카드 id 목록과 탭별 카드 순서 preference를 반환함.
  • PATCH /api/hub/dashboard/preferences는 현재 로그인 사용자의 favoriteCardIds, cardOrders를 저장함.
  • 대시보드 사용자 preference는 Hub SQLite tb_dashboard_user_preference_n에 사용자별 1 row로 저장함.
  • tb_dashboard_user_preference_n.user_id는 tb_user_m.user_id를 참조하며, 사용자 삭제 시 cascade 삭제됨.
  • favorite_card_ids는 SQLite JSON 배열이며 즐겨찾기 카드 id를 표시 순서대로 저장하고 최대 8개까지만 허용함.
  • card_orders는 SQLite JSON object이며 news, economy, system 같은 탭 key별 카드 id 배열을 저장함.
  • 즐겨찾기와 카드 순서 preference는 대시보드 데이터 수집 캐시와 분리된 DB 사용자 설정이며, /api/hub/dashboard 응답 TTL에 포함되지 않음.
  • preference API는 중복/빈 카드 id를 정규화하고, 지원하지 않는 탭 key의 카드 순서 값은 저장 대상에서 제외함.

AI 카드​

  • AI 카드는 OpenRouter Management API를 기준으로 사용량과 크레딧을 조회함.
  • AI 카드의 금일, 금주, 금월 사용량은 OpenRouter GET /api/v1/keys 응답의 usage_daily, usage_weekly, usage_monthly를 API key 목록 전체 기준으로 합산한 USD 값임.
  • AI 카드의 key별 주간 사용량은 같은 GET /api/v1/keys 응답의 각 key usage_weekly 값을 사용함.
  • AI 카드의 잔여 크레딧은 OpenRouter GET /api/v1/credits 응답의 total_credits - total_usage 계산값을 사용함.
  • AI 카드 사용량은 Hub SQLite tb_ai_usage_logs_n 로그 집계를 fallback으로 사용하지 않으며, OpenRouter 조회가 실패하거나 Management API Key가 없으면 미설정 또는 오류 상태를 반환함.
  • AI 카드 사용량은 OpenRouter 응답의 USD 값을 그대로 제공하며, 메타 EXCHANGE_RATE를 통한 KRW 환산을 수행하지 않음.
  • OpenRouter Management API Key는 completion endpoint 호출에 사용하지 않는 관리 API 전용 secret이며, DASHBOARD_OPENROUTER_MANAGEMENT_API_KEY로 주입함.

홈서버 상태 카드​

  • 홈서버 상태 응답은 DASHBOARD_GLANCES_BASE_URL이 설정된 경우 Glances REST API v4의 CPU, 메모리, processlist, containers 정보를 조회함.
  • 홈서버 상태 응답은 cpu, memory, topProcesses, problemContainers, containersSummary, updatedAt을 포함함.
  • topProcesses는 Glances processlist 응답을 CPU 사용률 내림차순으로 정렬한 상위 5건이며, 프로세스명, PID, CPU 사용률, 메모리 사용률, 상태를 포함함.
  • problemContainers는 Docker containers 응답 중 비정상 상태만 최대 10건 반환함.
  • Docker 컨테이너 상태가 running, up, healthy, Up ... (healthy) 계열이면 정상으로 분류하고, unhealthy, exited처럼 정상 조건에 해당하지 않는 상태만 문제 컨테이너로 분류함.
  • containersSummary는 Docker 컨테이너의 total, running, healthy, unhealthy, problem 개수를 제공함.
  • DASHBOARD_GLANCES_BASE_URL이 비어 있으면 홈서버 상태 응답은 미설정 상태와 빈 메트릭/목록/요약을 반환함.

수집 캐시와 타임아웃​

  • 대시보드 전체 응답 TTL, 일반 HTML source별 TTL, 핫딜 source별 TTL, 외부 HTTP 수집 타임아웃, Glances 호출 타임아웃은 apps/hub-api/var/dashboard-policy.yml에서 관리함.
  • 대시보드 전체 응답 TTL과 WMania·네이버 스포츠·FunETF 같은 일반 source별 TTL의 기본값은 각각 1800초임.
  • FMKorea 핫딜 source별 TTL의 기본값은 1800초임.
  • 대시보드 정책 파일은 collection.http_timeout_seconds, cache.dashboard_ttl_seconds, cache.external_source_ttl_seconds, cache.hotdeal_source_ttl_seconds, glances.timeout_seconds 값을 제공함.
  • 외부 사이트/API 오류는 전체 화면 실패가 아니라 카드별 오류 상태로 노출함.
  • HTTP/HTML 수집 보조 기능은 libs/shared-crawler를 사용하며, Playwright 브라우저 크롤링은 대시보드 기본 경로에서 사용하지 않음.

7.5 Portal 설정 화면​

  • /portal-menus는 단일 Tabulator 기반 저장형 관리자 화면임.
  • 목록 조회, 신규 생성, 수정, 체크박스 기반 멀티 선택 삭제를 하나의 그리드에서 처리함.
  • 소비 화면 /portal과 동일한 DB 포털 메뉴 저장소를 기준으로 동작함.
  • 메뉴 타입 선택값은 APP, SERVICE를 사용하며, 기존 PROJECT 값은 화면 정규화 단계에서 APP로 표시함.
  • 아이콘 타입 선택값은 APP_ICON, TEXT, IMAGE를 사용함.

7.6 공통코드 화면​

  • /codes는 좌측 코드 타입 목록과 우측 작업 영역으로 구성된 2패널 화면임.
  • 코드 타입 메타와 실제 코드는 저장소 레벨에서 분리되어 관리됨.
  • 좌측 type_code, type_name 선택은 현재 코드 타입을 활성화하고 우측 코드 목록과 메타를 조회한 뒤 같은 셀에서 직접 편집하는 동작을 수행함.
  • 코드 타입의 code_type_code 변경 시 저장소는 해당 코드 타입 하위 공통코드의 code_type_code도 함께 갱신함.
  • 좌측 코드 타입 목록과 우측 코드 목록은 각각 체크박스 기반 멀티 선택 삭제를 지원함.
  • 우측 코드 목록의 선택 삭제는 저장 대기 목록에 삭제 키를 쌓고 POST /api/hub/codes/batch 저장 시 실제 삭제를 반영함.

7.7 메타 화면​

  • /metas는 처음에 전체 폭 Tabulator 목록을 보여주며, 행 클릭 또는 신규에서 오른쪽 절반의 비모달 상세 패널을 열어 편집함. 패널이 열린 동안 왼쪽 목록 스크롤과 다른 행 선택이 가능하며 접기로 패널만 닫음.
  • 메타 값은 긴 텍스트를 직접 편집할 수 있는 textarea 중심 구조를 가짐.
  • 좌측 목록은 체크박스 기반 멀티 선택 삭제를 지원하며, 우측 상세 삭제 버튼도 유지함.

7.8 AI 프롬프트 화면​

  • Hub Markdown 시스템·사용자 템플릿은 AIBOT_MD_INSTRUCTION, AIBOT_MD_USER_TEMPLATE이며 카테고리 선택 정책도 시스템 DB 지침에 포함됨. 북마크 분석은 AIBOT_WEB_ANALYSIS_INSTRUCTION, AIBOT_WEB_ANALYSIS_USER_TEMPLATE을 사용하며 입력 변수는 url, title, body임.
  • 업무·공통 LLM 지침은 모두 같은 메뉴에서 버전별로 관리함. 전체 DB 관리 범위는 common/guide-jb-common-master-data.md 8.3절을 따름.
  • /prompts는 현재 버전 목록·버전 이력·신규 버전 저장·이전 버전 재적용·활성 상태 변경을 제공함.
  • 전체 폭 목록, 오른쪽 절반 상세 오버레이, 행 전환과 접기 동작은 /metas와 동일한 shared-ui 컴포넌트·스타일을 사용함.
  • 일반 관리자 화면 API는 HUB 모듈 권한을 요구하며 내부 소비 API는 내부 토큰만 허용함.

7.9 도구 화면 및 API​

  • /tools와 /tools/md는 Hub 세션과 HUB 모듈 권한을 사용하며, 도구 API도 모두 require_module("HUB")으로 보호함.
  • /tools의 마스터데이터 캐시 갱신은 POST /api/hub/tools/master-data/refresh를 호출함.
    • Hub 로컬 캐시를 비우고 Chess·Health·Message·Rename·Track·WOW·BizCard의 POST /api/internal/master-data/cache/refresh로 병렬 전파함.
    • 각 앱의 공통코드·메타·AI 프롬프트 캐시 항목 수와 성공·실패를 개별 반환하며 일부 앱 실패가 다른 앱의 갱신을 막지 않음.
    • 로컬 개발 포트와 운영 서비스 주소가 기본 대상이고 MASTERDATA_REFRESH_TARGETS로 대상 URL을 재정의할 수 있음.
  • Markdown 생성은 사용자의 초안을 HUB_TOOLS_MD 모델 라우팅과 PromptService로 읽은 활성 AI 프롬프트로 변환하고, 결과를 편집·미리보기한 뒤 사용자가 Vault 카테고리를 선택해 등록함. AI 카테고리 추천은 사용하지 않음.
  • GET /api/hub/tools/md/categories는 GitHub Vault의 재귀 트리에서 등록 가능한 폴더를 조회함. docs와 private/imaginations 하위의 이미지 폴더를 제외하고, docs/uncategorized를 우선 표시함.
  • POST /api/hub/tools/md/publish는 현재 허용된 카테고리를 다시 확인하고, 파일명을 정규화한 뒤 같은 이름이 있으면 번호를 붙여 중복을 피함. 후보를 최대 100개 확인하고 GitHub contents API로 문서를 등록함.
  • 북마크는 URL 중복 확인, 웹페이지 분석과 제목·요약·태그 편집, Linkding 저장 순서로 처리함. 분석은 HUB_TOOLS_BOOKMARK 모델 라우팅과 PromptService의 AI 프롬프트를 재사용함.
  • Vault GitHub 및 Linkding 연결 값은 VAULT_GITHUB_*, LINKDING_* 환경변수로 읽으며 hub_tools 설정이 소유함.

7.10 EPUB 오디오북 변환 설정과 입력​

  • 서버의 EPUB을 Google Chirp 3 HD 한국어 음성으로 읽어 MP3 또는 M4B 오디오북으로 만드는 도구임. 목적은 개인 사용자가 월 무료 제공량 안에서 음질을 비교하고 변환하는 것임.
  • 변환 범위는 미리듣기·챕터·전체임. 미리듣기는 설정한 길이만큼 본문 앞부분을 만들며 M4B는 전체에서만 선택함.
  • 폴더 설정은 아래 환경변수로, 운영 값은 Hub 메타로 읽음. 환경 파일 배치는 개발 환경·운영 배포 가이드의 환경 파일 분류를 따름.
환경변수의미
HUB_AUDIOBOOK_EPUB_ROOT선택할 수 있는 EPUB 루트. 읽기 전용으로만 사용함
HUB_AUDIOBOOK_WORK_DIR작업 폴더. output/(결과), cache/(구간 캐시), tmp/(조립 중 파일)를 둠
메타 키의미
HUB_AUDIOBOOK_MONTHLY_CHAR_LIMIT월간 과금 문자 수 상한. 기본 900000
HUB_AUDIOBOOK_PREVIEW_SECONDS미리듣기 길이(초). 기본 180, 허용 60~600
HUB_AUDIOBOOK_DEFAULT_VOICE화면의 기본 음성 이름. 기본 Gacrux
  • 메타는 요청마다 읽어 변경이 다음 요청부터 반영됨. 행이 없거나 비활성이거나 정수가 아니거나 허용 범위·음성 목록을 벗어나면 코드 기본값을 쓰고 경고 로그를 남김. 엔진은 코드 상수 google-chirp3-hd임. 월 사용량은 공통 사용 로그가 소유하므로 메타를 바꿔도 이번 달 사용량은 유지됨.
  • 설정이 비어 있어도 화면 진입, EPUB 탐색, 챕터 확인, 예상 문자 수 계산은 동작함. 생성만 빠진 항목(폴더, LITELLM_API_KEY와 HUB_AUDIOBOOK_TTS route)을 알리는 503으로 거부함.
  • EPUB은 루트 기준 상대 경로로만 받음. 루트 밖 경로와 심볼릭 링크 탈출을 거부하고 .epub 일반 파일만 읽음. 압축은 디스크에 풀지 않고 메모리에서 읽으며 DRM 적용 EPUB은 거부함.
  • 챕터는 spine 순서의 XHTML 문서임. 제목은 목차, 문서의 첫 제목, 본문 N 순서로 정함. 텍스트가 없는 문서는 챕터에서 제외하고, 200자 미만이거나 목차·판권류 제목인 문서는 is_body=false로 두어 기본 변환 대상에서 뺌.

7.11 EPUB 오디오북 변환 실행과 출력​

  • 본문은 문장·문단 경계를 지키며 UTF-8 3,000바이트 이하 구간으로 나눔. Google 요청 한도 5,000바이트에 여유를 두어 구간 실패 시 재시도 비용을 줄임.
  • 과금 문자 수는 공백과 줄바꿈을 포함한 구간 문자 수임. 구간 캐시에 있는 구간은 호출하지 않으며 예상치에서도 0으로 셈.
  • 월 상한은 shared-ai가 호출 직전 쓰기 트랜잭션에서 검사와 RESERVED 삽입을 함께 처리해 동시 호출에도 초과하지 않음. 상한 초과 시 호출하지 않으며 사용량은 앱 집계라 Google 실제 청구와 다를 수 있음.
  • 호출은 429·5xx만 2회 재시도하고 4xx는 재시도하지 않음. 타임아웃처럼 과금 여부를 알 수 없는 호출은 재시도 없이 UNKNOWN으로 남김. 상세는 docs/junkbox/libs/guide-lib-shared-ai.md를 따름.
  • 미리듣기는 음성 1개 단위의 동기 요청임. 같은 EPUB·음성·시작 챕터의 동시 실행은 409로 거부하며, 서버 재시작으로 남은 RUNNING 미리듣기는 시작 시 FAILED로 정리함.
  • 챕터·전체 변환은 Automation hub.audiobook-convert 작업으로 실행함. 계약은 docs/junkbox/apps/guide-apps-automation-api.md를 따르며 Hub는 배치마다 240초 시간 예산 안에서 구간을 합성함.
  • 변환은 자동 재시도하지 않고 사용자의 resume으로만 이어 감. 캐시가 멱등 키라 중단·실패 뒤에도 이미 만든 구간은 다시 호출하지 않음. 같은 변환의 활성 작업이 있으면 새로 만들지 않고 기존 작업을 반환함.
  • 3분 넘게 갱신이 없는 PENDING·RUNNING 변환은 Automation의 최신 실행이 실패이면 조회 시 FAILED로 정리함. 월 상한에 닿으면 그 지점에서 실패로 멈추고 다음 달에 재개할 수 있음.
  • 결과 파일명은 KST yyyyMMddHHmmss를 붙여 만들며 덮어쓰지 않음. 전체는 <EPUB 이름>_<시각>, 챕터는 _chNN_, 미리듣기는 _preview_<음성>_을 포함함. 같은 이름이 있으면 시각을 1초씩 늦춤.
  • 챕터·전체 MP3는 ffmpeg로 재인코딩 없이 결합하고 ID3 태그를 넣음. M4B는 챕터별 길이로 챕터 메타데이터를 만들고 AAC 64 kbps 모노로 인코딩하며 표지는 넣지 않음. 미리듣기는 구간을 바이트로 이어 붙여 ffmpeg가 필요 없음.

7.12 프로 레슬링 뉴스 수집·저장·발송​

  • WMania 목록 파서는 대시보드와 공유함. WMania 수집기는 상세 등록 시각과 본문을 읽고, 경기 결과 리포트를 제외하고 번호형 단신을 구분함. 공통 리포트 처리부는 크롤링과 API 수집기가 같은 기사 형식을 반환하도록 받음.
  • 수집 종료 시각은 자동 실행의 예약 시각 또는 수동 실행의 요청 시각임. 시작 기준은 남은 최신 리포트의 종료 시각임. 이력이 비어 있으면 시작 제한 없이 수집함.
  • 종료 직전까지의 게시글을 최신순으로 최대 40개 수집함. 첫 수집 또는 상한 도달 시에는 수집한 가장 오래된 글의 등록 시각을 시작으로 저장함. 시작 기준과 기사 모두 없을 때는 0건 발송을 요청한 자동 수집만 리포트를 만들고, 이번 예약 시각의 24시간 전을 시작으로 저장함.
  • HUB_WRESTLING_DIGEST_INSTRUCTION과 HUB_WRESTLING_DIGEST_USER_TEMPLATE을 사용하고, HUB_WRESTLING_DIGEST 경로로 최대 16개 주요 소식을 요약함. 이전 7일의 삭제되지 않은 리포트를 중복 비교에 쓰고 단신 ID로 원문을 검증함.
  • Hub SQLite의 tb_hub_pro_wrestling_digest_n은 리포트 ID, 소유자, 실행 키, 수집 기간, 자동·수동 구분, 요약 및 발송 상태를 저장함. 시작 시 테이블 이름 이관과 날짜 기반 리포트 가져오기를 처리함. 발송된 /tools/wrestling-news 리포트 링크도 지원함.
  • 화면은 소유자 기준으로 최근 30건과 상세를 조회함. DELETE /api/hub/tools/pro-wrestling-news/reports/{report_id}는 소유자 리포트의 삭제 시각을 기록함. 삭제한 리포트는 조회·수집 기준에서 빠지며 실행 키는 재시도 중복 방지에 사용함.
  • HUB_PRO_WRESTLING_DIGEST_OWNER_USER_ID로 취합·설정 변경 및 발송 소유자를 정함. 호환 키로 HUB_WRESTLING_DIGEST_OWNER_USER_ID를 받음. /api/hub/tools/pro-wrestling-news의 /settings와 /runs는 Automation의 설정·수동 실행을 중계함.
  • POST /api/hub/internal/automation/pro-wrestling-digest는 해당 Automation 작업 인증을 요구함. 발송 요청이 있고 주요 소식이 있으면 Message에 리포트 ID별 요청 키와 상세 URL의 리포트 보기 버튼을 전달함.
  • 주요 소식이 0건이면 자동 수집의 0건 발송 요청이 있을 때만 같은 형식으로 발송함.

8. 관련 문서​

  • 프로젝트 전체 구조는 docs/junkbox/common/guide-jb-overview.md, 공통 원칙은 docs/junkbox/common/guide-jb-core.md를 따름.
  • 공통 AI 라이브러리 구조는 docs/junkbox/libs/guide-lib-shared-ai.md를 따름.
  • 공통 크롤링 보조 구조는 docs/junkbox/libs/guide-lib-shared-crawler.md를 따름.
  • 운동 계획 도메인 소비 구조는 docs/junkbox/apps/guide-apps-health-api.md, docs/junkbox/apps/guide-apps-health-ui.md를 따름.