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 Codehub:backendtask는 같은 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:8080loopback 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-uiCSS/JS 링크는 템플릿 컨텍스트의shared_ui_asset()헬퍼가 파일 수정 시각 기준 버전 쿼리를 붙여 렌더링함. - 공통 CSS 링크 선언은
shared-uistylesheet 매크로를 통해 중앙화함. - 공통 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는 서명, 만료,
sidclaim, Hub SQLitetb_user_session_n의 활성 세션 상태를 모두 통과해야 유효함. - Swagger 인증도 같은 JWT 검증과 세션 유효성 확인 경로를 사용함.
- AI 에이전트 표준 master-data API는 Bearer JWT의
role=ROLE_AIclaim을 검증함. ROLE_AIJWT는 일반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과 개발 UI15013을 포함함.- 요구 모듈 권한이 없으면 공통 로그인 화면으로 돌아가며
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 SQLitetb_user_session_n에 사용자 세션 row를 생성하고 JWTsid, JWTexp, HttpOnly 쿠키max_age를 설정함. - 사용자 세션은
session_id,user_id,issued_at,expires_at,revoked_at,last_seen_at,user_agent,ip_address,is_active값을 포함함. - JWT의
sidclaim은 Hub SQLitetb_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가 JWTsidclaim과 매칭됨. - 세션 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·UNKNOWNusage_quantity합계이며FAILED를 제외함. 과금 여부를 알 수 없는 호출을 사용한 것으로 세어 월 상한을 보수적으로 지키기 위함임. - 사용 로그는 작업 삭제와 무관하게 유지하며 작업과 외래키로 묶지 않고
input_params의audiobook_job_id·구간 키로 추적함. 본문 텍스트와 오디오는 기록하지 않음. - 구간 캐시는 DB가 아니라 작업 폴더의
cache/<음성>/<sha256>.mp3파일임. 키는 엔진·음성·인코딩·텍스트의 해시임.
5. API와 화면 진입
5.1 인증 API
POST /api/auth/loginPOST /api/auth/logoutGET /api/auth/verifyGET /api/auth/encryptGET /api/auth/app/authorize: 브라우저 로그인 쿠키와state·PKCEcode_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/typesGET /api/hub/codes/types/with-countsPOST /api/hub/codes/typesGET /api/hub/codes/types/{code_type_code}/metaPATCH /api/hub/codes/types/{code_type_code}/metaDELETE /api/hub/codes/types/{code_type_code}GET /api/hub/codes/{code_type_code}GET /api/hub/codes/{code_type_code}/allPOST /api/hub/codes/batch
- 메타 API
GET /api/hub/metasGET /api/hub/metas/progressiveGET /api/hub/metas/{meta_id}GET /api/hub/metas/by-key/{meta_key}POST /api/hub/metasPATCH /api/hub/metas/{meta_id}DELETE /api/hub/metas/{meta_id}
- AI 프롬프트 API (
require_module("HUB")적용)GET /api/hub/promptsGET /api/hub/prompts/by-key/{prompt_key}GET /api/hub/prompts/{prompt_key}/versionsPOST /api/hub/promptsPOST /api/hub/prompts/versions/{prompt_id}/activatePATCH /api/hub/prompts/{prompt_key}/active
- 포털 메뉴 API
GET /api/hub/portal-menusGET /api/hub/portal-menus/{menu_id}POST /api/hub/portal-menusPATCH /api/hub/portal-menus/{menu_id}DELETE /api/hub/portal-menus/{menu_id}
- 사용자 API
GET /api/hub/usersGET /api/hub/users/progressiveGET /api/hub/users/{user_id}POST /api/hub/usersPATCH /api/hub/users/{user_id}DELETE /api/hub/users/{user_id}
- AI 로그 API
GET /api/hub/ai-logscreatedDateFrom·createdDateTo의 KST 날짜 범위에 헤더 필터와sort를 적용함. 기본 정렬은 최신순이며 비용 정렬은 미산정 행을 뒤에 배치함.- 페이지 첫 응답의
snapshotId를 이어지는 요청에 전달하면 그 ID 이후에 쌓인 행을 제외함. 같은 비용에서는 최신 시각과 로그 ID로 순서를 결정함.
GET /api/hub/ai-logs/summaryGET /api/hub/ai-logs/{usage_log_id}- 구조화 호출이면 선택적
structuredDiagnostics로 같은 요청의 관련 호출과 단계별 검증 결과를 반환함. 조회는HUB모듈 권한을 사용함.
- 구조화 호출이면 선택적
- 대시보드 API
GET /api/hub/dashboardGET /api/hub/dashboard?forceRefresh=trueGET /api/hub/dashboard/diet는HUB와HEALTH권한을 모두 요구하고 현재 사용자의 인증 토큰으로 QuestLogGET /api/questlog/missions/status를 호출해 식단 카드를 만듦(식단 카드 절).- 목표·기간·판정의 단일 관리 주체는 QuestLog 사용자별 설정과 미션 판정이며 Hub 메타는 대시보드 응답에서 읽지 않음.
- 응답은
Cache-Control: no-store로 제공하고 사용자별 섭취량은 대시보드의 공통 수집 캐시에 넣지 않음.
GET /api/hub/dashboard/preferencesPATCH /api/hub/dashboard/preferencesPOST /api/hub/dashboard/investments/reorder
- 도구 API (
require_module("HUB")적용)GET /api/hub/tools/md/categoriesPOST /api/hub/tools/md/generatePOST /api/hub/tools/md/publishPOST /api/hub/tools/bookmarks/checkPOST /api/hub/tools/bookmarks/analyzePOST /api/hub/tools/bookmarks/savePOST /api/hub/tools/master-data/refresh
GET /api/hub/users/progressive는 사용자 PKid의 숫자 헤더 조건과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의 텍스트 헤더 조건을 목록과 총 건수 조회에 공통 검색 문법으로 적용함. 별도/summaryAPI는 기간별 전체 요약 계약을 유지함.
오디오북 API
- 모든 API에
require_module("HUB")를 적용하며 접두사는/api/hub/tools/audiobook임.GET /status,GET /files,GET /book,POST /estimatePOST /previews,POST /conversionsGET /jobs(epub_path생략 시 EPUB과 무관하게 전체 작업 최신순),GET /jobs/{job_id},GET /jobs/{job_id}/audioPOST /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-menusPOST /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/validatePOST /api/internal/auth/refreshGET /api/internal/auth/health-report-owner는 자동 리포트·발송의 소유자 적격성을 확인하기 위해 활성 계정의 HEALTH·QUESTLOG 권한을 반환함.- 내부 인증 API는 서버 간 호출 전용이며,
HUB_API_INTERNAL_TOKEN_HEADER헤더와 토큰 검증을 통과한 요청만 허용함. POST /api/internal/auth/validate는 요청 body의 현재 JWT를 검증하고 Hub SQLitetb_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_AIJWT를 요구함.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/configPOST /api/portal/config
5.7 웹 화면
GET /loginPOST /loginGET /dashboardGET /portalGET /toolsGET /tools/mdGET /tools/audiobookGET /tools/pro-wrestling-newsGET /portal-menusGET /usersGET /codesGET /metasGET /promptsGET /ai-logsGET /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_BOOKMARKroute key와AIBOT_MD_INSTRUCTION,AIBOT_MD_USER_TEMPLATE,AIBOT_WEB_ANALYSIS_INSTRUCTIONAI 프롬프트를 재사용함. 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_TTSroute이며 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-uistylesheet 매크로를 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를 해석하고, 없으면hubslug를 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는 등록된localhostUI 포트의local_menu_url을 요청자의 LAN HTTP 또는 Tailnet HTTPS origin에 맞춰 응답하며 저장된 포털 메뉴 값은 변경하지 않음.
7.4 대시보드 화면
개요
/dashboard는 포털과 분리된 동적 데이터 대시보드 화면임.- 대시보드는 소식/핫딜, AI 사용량, 투자 관심 목록, 홈서버 상태를 카드 단위로 표시함.
식단 카드
GET /api/hub/dashboard/diet는HUB와HEALTH권한을 모두 요구하고 현재 사용자의 인증 토큰으로 QuestLogGET /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로 제공하고 사용자별 섭취량은 대시보드의 공통 수집 캐시에 넣지 않음.
- Hub는 Health 집계를 직접 조회하거나 평균·판정을 계산하지 않고 QuestLog가 계산한 두 미션의 목표·실적·판정·예정분을 식단 카드 형식으로 옮겨 담음. 주 기준은 QuestLog의
- 응답은
targetKcal,weeklyTargetKcal, 오늘 먹은 양todayKcal(판정 불가면null, 기록이 없으면0), 아직 먹지 않은 예정분todayPlannedKcal, 판정 상태todayStatus·weekStatus(IN_PROGRESS·FAIL, 판정 불가면null), 이번 주 지난 날짜 평균weekAverageKcal(지난 날이 없으면null),weekIncludesToday임.- 평균·초과 판정은 QuestLog
주간 평균 열량미션의 판정 그대로이며(기록 없는 날은 0, 주간 한도를 넘겨 실패하면 평균에 오늘 포함,weekIncludesToday는 QuestLog의basisNote가오늘 포함일 때 참) 판정은 예정분을 뺀 먹은 양만 사용함.
- 평균·초과 판정은 QuestLog
뉴스·핫딜 카드
- 뉴스 카드는 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응답의 각 keyusage_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.md8.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을 재정의할 수 있음.
- Hub 로컬 캐시를 비우고 Chess·Health·Message·Rename·Track·WOW·BizCard의
- 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_TTSroute)을 알리는 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를 따름.