본문으로 건너뛰기

JunkBox libs/shared-core 가이드

1. 라이브러리 역할​

  • shared-core는 모든 앱이 공통으로 사용하는 백엔드 기반 라이브러리임.
  • 설정, 비동기 DB, 공통 엔티티, 인증, 비밀번호, 예외, 공통 마스터 데이터 저장소, 공통 master-data 소비 클라이언트와 TTL 캐시를 제공함.
  • 공통 loguru 기반 애플리케이션 로깅 초기화도 제공함.

2. 패키지 구조​

junkbox_shared_core/
├── config/
├── db/
├── exceptions/
├── header_filter.py
├── logging.py
├── masterdata/
├── models/
└── security/

3. 설정 계층​

3.1 Settings 구조​

  • pydantic-settings 기반 Settings 클래스를 사용함.
  • 기본 ENV_FILE 값은 .env.local임.
  • ENV_FILE 기준 환경 파일과 같은 디렉터리의 .env.shared를 함께 로딩함.
  • ENV_FILE 기준 환경 파일과 같은 디렉터리의 .env.chess도 함께 로딩함. Chess 전용 Lichess API base URL, OAuth와 Stockfish 설정은 이 파일에서 관리함.
  • ENV_FILE이 base profile env 파일명 뒤에 앱 suffix를 붙인 형태이면 같은 디렉터리의 .env.local 또는 .env.prod를 base profile env로 함께 로딩할 수 있음.
  • 설정 source 우선순위는 명시적 초기화 값, .env.chess, 선택된 ENV_FILE, base profile env, .env.shared, 셸 환경 변수, file secret 순서임.
  • .env.shared에는 모든 프로필에서 같은 공통 정책과 비민감 공통 설정을 둠. 서비스 연결 대상처럼 프로필마다 달라지는 값과 민감정보는 선택된 .env.local 또는 .env.prod에 둠.
  • AUTOMATION_BASE_URL은 .env.local에서 http://localhost:18007, .env.prod에서 http://junkbox-automation-api:8080을 사용함. 선택된 ENV_FILE이 .env.shared보다 높은 우선순위이므로 프로필별 값을 확정함.
  • 실행 시점 환경 변수 오염으로 기본 설정이 흔들리지 않도록 설계함.
  • 개발 Chess 컨테이너는 프로젝트 루트의 .env.chess를 /app/env/.env.chess에 읽기 전용으로 마운트함. 운영 Chess 컨테이너는 /sorc001/junkbox/env/.env.chess, /sorc001/junkbox/env/.env.shared, /sorc001/junkbox/env/.env.prod를 함께 참조하고, ENV_FILE=/app/env/.env.prod 기준으로 로딩하는 전제를 가짐.
  • 설정 객체는 app, database, auth, server, modules, masterdata, dashboard, rename, wow, lichess, hub_tools, ai 중첩 모델 구조를 사용함.
  • 앱 코드는 settings.modules.hub.base_url, settings.modules.hub.database_url, settings.modules.chess.base_url, settings.modules.chess.database_url, settings.modules.health.database_url, settings.modules.wow.database_url, settings.ai.providers.litellm.api_key, settings.ai.providers.litellm.base_url, settings.lichess.oauth_client_id, settings.lichess.stockfish_path, settings.rename.asite.base_url, settings.wow.wcl.client_id, settings.hub_tools.github.repo 같은 중첩 경로 접근을 기본으로 사용함.
  • 모듈별 로깅 설정도 settings.modules.hub.logging, settings.modules.chess.logging, settings.modules.health.logging, settings.modules.wow.logging 같은 중첩 경로 접근을 사용함.
  • 기존 호환을 위해 일부 flat alias 프로퍼티도 제공하지만, 신규 구현은 중첩 모델 접근을 우선함.

3.2 주요 설정 책임​

보관 항목​

  • Hub 공통 SQLite 연결 정보 보관
  • Chess 도메인 SQLite 연결 정보 보관
  • Health 도메인 SQLite 연결 정보 보관
  • Raid 도메인 SQLite 연결 정보 보관
  • JWT 서명과 알고리즘 보관
  • 쿠키 옵션 보관
  • 앱 프로필 보관
  • CORS 설정 보관
  • 공통 로깅 rotation, retention, compression 정책 보관
  • profile별 로깅 level, diagnose/backtrace 토글 보관
  • AI 라우팅 파일 경로와 공통 런타임 마스터데이터 디렉터리 경로를 보관함.
  • 공통 로그인 복귀 기준이 되는 HUB_BASE_URL, HEALTH_BASE_URL, WOW_BASE_URL 보관
  • Hub가 Health 음식 요약을 내부 호출할 때 사용할 선택적 HEALTH_INTERNAL_BASE_URL을 보관하며, 미설정 시 HEALTH_BASE_URL을 사용함.
  • Automation worker가 WoW internal Job API를 호출할 때 WOW_BASE_URL보다 우선하는 선택적 WOW_INTERNAL_BASE_URL(modules.wow.internal_base_url)을 보관함. 미설정 시 WOW_BASE_URL을 사용함.
  • Chess 앱 진입과 Automation의 Chess internal Job API 대상 기준이 되는 CHESS_BASE_URL 보관
  • 모듈 간 내부 API 호출 기준이 되는 HUB_INTERNAL_BASE_URL 보관
  • Rename 수집과 파일 시스템 작업 기준이 되는 ASITE_*, RENAME_BASE_DIR, RENAME_TARGET_DIR_NAME 보관
  • Raid WCL 연동에 필요한 WCL_CLIENT_ID, WCL_CLIENT_SECRET, WCL_TOKEN_URL, WCL_API_URL, WCL_MAX_CONCURRENCY 보관
  • Lichess API base URL, OAuth client id·callback URL과 Stockfish 실행 경로·분석 제한값을 보관함. 종료 대국 동기화 일정과 재시도 정책은 Automation 작업 정의에서 관리함.
  • LiteLLM proxy 연동에 필요한 LITELLM_BASE_URL, LITELLM_API_KEY 보관
  • 내부 master-data API 토큰과 TTL/타임아웃 설정 보관
  • hub 대시보드 Glances API 접속 설정 보관
  • hub 대시보드 OpenRouter Management API 접속 설정 보관

인증과 토큰​

  • COOKIE_NAME 기본값은 JUNKBOX_AUTH임.
  • JWT_SECRET_KEY는 브라우저 사용자 인증용 JWT 서명/검증 키임.
  • 사용자 세션 만료 시간과 슬라이딩 갱신 임계값은 shared-core 설정이 아니라 hub-api 정책 파일에서 관리함.
  • HUB_API_INTERNAL_TOKEN은 모듈 간 내부 인증 API와 내부 master-data API 호출용 서버 간 토큰임.
  • AI_ACCESS_TOKEN은 AI 에이전트가 표준 통합 master-data API를 호출할 때 사용하는 ROLE_AI JWT 값임.
  • FASTAPI_BASE_URL은 AI 에이전트 로컬 스크립트가 호출할 hub-api base URL임.
  • 사용자 인증 JWT 서명키, 서버 간 내부 토큰, AI 에이전트 토큰은 용도가 다르므로 서로 다른 랜덤 값을 사용하는 것을 기본 원칙으로 함.

CORS와 로깅 경로​

  • server.cors_origins는 모든 FastAPI 앱이 공통으로 재사용하는 CORS 허용 origin 목록임.
  • modules.hub.logging.file_path, modules.chess.logging.file_path, modules.health.logging.file_path, modules.wow.logging.file_path는 모듈별 파일 로그 출력 위치를 나타냄.

SQLite 접속 설정​

  • modules.hub.database_url은 Hub 공통 SQLite DB 접속 문자열임.
  • HUB_DATABASE_URL이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/hub.sqlite3, 컨테이너 실행은 /app/db/hub.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
  • modules.chess.database_url은 Chess 도메인 SQLite DB 접속 문자열임.
  • CHESS_DATABASE_URL이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/chess.sqlite3, 컨테이너 실행은 /app/db/chess.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
  • modules.health.database_url은 Health 도메인 SQLite DB 접속 문자열임.
  • HEALTH_DATABASE_URL이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/health.sqlite3, 컨테이너 실행은 /app/db/health.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
  • modules.wow.database_url은 Raid 도메인 SQLite DB 접속 문자열임.

신규 앱 모듈 설정​

  • modules.bizcard.database_url, modules.bizcard.scan_dir는 BizCard 전용 SQLite와 명함 이미지 폴더를 나타내며 BIZCARD_DATABASE_URL, BIZCARD_SCAN_DIR에서 읽음.
  • BIZCARD_DATABASE_URL이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/bizcard.sqlite3, 컨테이너 실행은 /app/db/bizcard.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
  • modules.sipmon.database_url은 SipMon 도메인 SQLite DB 접속 문자열이며 SIPMON_DATABASE_URL에서 읽음. 값이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/sipmon.sqlite3, 컨테이너 실행은 /app/db/sipmon.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
  • modules.questlog.database_url은 QuestLog 사용자 미션 설정·결과 SQLite 접속 문자열이며 QUESTLOG_DATABASE_URL에서 읽음.
    • 값이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/questlog.sqlite3, 컨테이너 실행은 /app/db/questlog.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
    • modules.questlog.base_url은 QUESTLOG_BASE_URL, internal_base_url은 QUESTLOG_INTERNAL_BASE_URL(Hub→QuestLog 서버 간 호출용)에서 읽음.
    • modules.questlog.service_token과 service_token_header는 QUESTLOG_SERVICE_TOKEN, QUESTLOG_SERVICE_TOKEN_HEADER(기본 X-Junkbox-Service-Token)에서 읽으며 QuestLog와 Chess가 같은 값을 공유함.
    • 비밀값이라 Git 추적 환경 파일에 넣지 않음.
    • modules.chess.internal_base_url은 CHESS_INTERNAL_BASE_URL에서 읽으며 QuestLog가 Chess 집계 API를 서버 간으로 호출할 때 base_url보다 우선함.
  • modules.knowbit.database_url은 Knowbit 사용자 학습 SQLite 접속 문자열이며 KNOWBIT_DATABASE_URL에서 읽음.
    • 값이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/knowbit.sqlite3, 컨테이너 실행은 /app/db/knowbit.sqlite3 기준 SQLite DSN을 기본값으로 사용함.
    • modules.knowbit.documents_dir의 기본값은 /ext001/data001/junkbox/knowbit/documents이며 KNOWBIT_DOCUMENTS_DIR로 변경함.
    • 한 요청의 원문 근거 상한과 개별 문서 안전 상한은 각각 context_max_bytes, document_max_bytes로 관리함.
  • modules.message.backup_service_token, modules.message.backup_service_token_file, modules.message.backup_owner_user_id는 각각 MESSAGE_BACKUP_SERVICE_TOKEN, MESSAGE_BACKUP_SERVICE_TOKEN_FILE, MESSAGE_BACKUP_OWNER_USER_ID에서 읽음.
    • Message API의 백업 인증은 파일 경로가 설정된 경우 파일 값을 우선 사용하며, 소유자 설정으로 발송 이력을 귀속함.
  • modules.wow.recruitment_notification_owner_user_id는 WOW_RECRUITMENT_NOTIFICATION_OWNER_USER_ID에서 읽으며 WOW 구인 알림 Message 이력의 소유자를 지정함. 비어 있으면 소유자 없이 발송함.
  • WOW_DATABASE_URL이 비어 있으면 로컬 비컨테이너 실행은 /sorc001/junkbox/db/wow.sqlite3, 컨테이너 실행은 /app/db/wow.sqlite3 기준 SQLite DSN을 기본값으로 사용함.

3.3 경로 및 내부 호출 설정​

AI 라우팅 경로​

  • MASTER_DATA_DIR는 AI 라우팅 YAML 기본 디렉토리 계산에 사용함.
  • 로컬 기본 MASTER_DATA_DIR는 프로젝트 루트 기준 apps/hub-api/var/master-data임.
  • 컨테이너 기본 MASTER_DATA_DIR는 /app/var/master-data임.
  • AI_ROUTING_YAML_PATH는 AI 라우팅 파일 경로 오버라이드용임.
  • AI_ROUTING_YAML_PATH가 비어 있으면 MASTER_DATA_DIR/ai-routing.yml을 기본값으로 계산함.

Hub 내부 호출​

  • HUB_API_INTERNAL_TOKEN, HUB_API_INTERNAL_TOKEN_HEADER는 내부 master-data API 호출 인증 설정임.
  • HUB_INTERNAL_BASE_URL은 소비 앱 실행 위치에서 접근 가능한 hub-api 내부 API base URL임.
  • 로컬 VS Code task 기준 hub-api는 18001 포트로 실행되며, 컨테이너 내부 통신 기준 운영 compose는 http://junkbox-hub:8080 계열 내부 주소를 사용함.

SQLite 접속 설정​

  • HUB_DATABASE_URL은 hub-api가 공통코드, 코드 타입, 메타, 포털 메뉴, 사용자, 사용자 세션, 대시보드 사용자 preference, AI usage log를 저장하는 SQLite 파일 DB URL임.
  • 로컬 비컨테이너 기준 기본 HUB_DATABASE_URL은 sqlite+aiosqlite:////sorc001/junkbox/db/hub.sqlite3임.
  • Docker 기준 HUB_DATABASE_URL은 sqlite+aiosqlite:////app/db/hub.sqlite3이며 compose가 /sorc001/junkbox/db를 /app/db로 마운트함.
  • Hub SQLite 파일은 hub-api가 앱 import 시점에 settings.modules.hub.database_url로 초기화하는 Hub 소유 전역 DB engine을 사용함.
  • CHESS_DATABASE_URL은 Chess OAuth 연결, 대국, 수순, 엔진 분석, 코칭용 파일 DB URL임.
  • Lichess 수동 발급 개인 토큰, 봇 계정명, 기본 상대 ID는 Chess 환경 변수로 사용하지 않음. PKCE OAuth가 board:play 권한의 access token을 발급하고 Chess SQLite에 저장함.
  • 로컬 비컨테이너 기준 기본 CHESS_DATABASE_URL은 sqlite+aiosqlite:////sorc001/junkbox/db/chess.sqlite3임.
  • Docker 기준 CHESS_DATABASE_URL은 sqlite+aiosqlite:////app/db/chess.sqlite3이며 compose가 /sorc001/junkbox/db를 /app/db로 마운트함.
  • Chess SQLite 파일은 chess-api가 앱 전용 engine과 session maker를 소유하며 Hub 전역 engine을 사용하지 않음.
  • HEALTH_DATABASE_URL은 health-api가 운동 세션과 운동 기록을 저장하는 SQLite 파일 DB URL임.
  • 로컬 비컨테이너 기준 기본 HEALTH_DATABASE_URL은 sqlite+aiosqlite:////sorc001/junkbox/db/health.sqlite3임.
  • Docker 기준 HEALTH_DATABASE_URL은 sqlite+aiosqlite:////app/db/health.sqlite3이며 compose가 /sorc001/junkbox/db를 /app/db로 마운트함.
  • Health SQLite 파일은 health-api가 앱 import 시점에 settings.modules.health.database_url로 앱 전용 DB engine을 초기화함.
  • WOW_DATABASE_URL은 wow-api가 공대원, 레이드 소속, 레이드 점수, 보스 점수를 저장하는 SQLite 파일 DB URL임.
  • 로컬 비컨테이너 기준 기본 WOW_DATABASE_URL은 sqlite+aiosqlite:////sorc001/junkbox/db/wow.sqlite3임.
  • Docker 기준 WOW_DATABASE_URL은 sqlite+aiosqlite:////app/db/wow.sqlite3이며 compose가 /sorc001/junkbox/db를 /app/db로 마운트함.
  • WOW 앱 SQLite 파일은 wow-api가 앱 import 시점에 settings.modules.wow.database_url로 앱 전용 DB engine을 초기화함.

마스터데이터 호출 설정​

  • MASTERDATA_CODES_TTL_SECONDS, MASTERDATA_METAS_TTL_SECONDS는 모듈별 공통 master-data TTL 캐시 설정임.
  • MASTERDATA_HTTP_TIMEOUT_SECONDS는 내부 master-data API 호출 타임아웃 설정임.

대시보드 외부 연동​

  • DASHBOARD_GLANCES_BASE_URL은 Glances REST API v4 base URL이며, 비어 있으면 홈서버 상태 카드는 미설정으로 표시됨.
  • DASHBOARD_GLANCES_USERNAME, DASHBOARD_GLANCES_PASSWORD는 Glances Basic Auth 설정임.
  • DASHBOARD_GLANCES_BEARER_TOKEN은 Glances 또는 프록시 앞단에서 Bearer 인증을 사용할 때의 토큰 설정임.
  • DASHBOARD_OPENROUTER_MANAGEMENT_API_KEY는 hub 대시보드 AI 카드가 OpenRouter credits와 API key별 사용량을 조회할 때 사용하는 Management API Key임.
  • DASHBOARD_OPENROUTER_MANAGEMENT_API_KEY는 completion 호출용 API key가 아니라 OpenRouter 관리 API 전용 secret임.
  • DASHBOARD_OPENROUTER_BASE_URL은 OpenRouter 관리 API base URL이며 기본값은 https://openrouter.ai임.
  • DASHBOARD_OPENROUTER_TIMEOUT_SECONDS는 OpenRouter credits/key 목록 조회 타임아웃 설정임.
  • OpenRouter Management API Key는 secret이므로 .env.shared에 값을 저장하지 않고 로컬은 .env.local, 운영은 /sorc001/junkbox/env/.env.prod 같은 profile별 secret env에서 관리함.
  • hub 대시보드 HTTP 수집 타임아웃, 전체 응답 TTL, 일반 외부 HTML source별 TTL, 핫딜 source별 TTL, Glances 호출 타임아웃은 apps/hub-api/var/dashboard-policy.yml에서 관리함.

Rename·Linkding·Vault 설정​

  • ASITE_BASE_URL, ASITE_LOGIN_URL, ASITE_USERNAME, ASITE_PASSWORD는 Rename 수집기 로그인과 조회 기준값임.
  • RENAME_BASE_DIR는 Rename 파일 작업 루트 경로이며, RENAME_TARGET_DIR_NAME은 그 루트 하위의 입력 작업 폴더명임. Rename 작업 폴더는 ${RENAME_BASE_DIR}/${RENAME_TARGET_DIR_NAME}이고, 폴더명은 비어 있지 않은 단일 상대 경로여야 함. 절대 경로, 상위 경로 이동, 다단계 경로는 허용하지 않음.
  • LINKDING_BASE_URL은 Linkding REST API base URL임.
  • LINKDING_API_TOKEN은 Linkding REST API 인증 토큰임.
  • VAULT_GITHUB_*는 GitHub contents API 기반 마크다운 저장 경로 계산과 인증에 사용함. Hub 도구의 연결 설정은 settings.hub_tools.github, settings.hub_tools.linkding에 보관함.

환경 파일과 운영 값​

  • 선택된 ENV_FILE은 base profile env와 .env.shared보다 우선함. APP_PROFILE은 프로필별 AI 라우팅 파일 선택에도 사용함.
  • 운영에서는 APP_PROFILE=prod, HUB_BASE_URL, CHESS_BASE_URL, HEALTH_BASE_URL, WOW_BASE_URL, HUB_INTERNAL_BASE_URL, COOKIE_DOMAIN, COOKIE_SECURE, HUB_API_INTERNAL_TOKEN, AI_ACCESS_TOKEN, FASTAPI_BASE_URL, RENAME_BASE_DIR, RENAME_TARGET_DIR_NAME, WCL_CLIENT_ID, WCL_CLIENT_SECRET, Lichess OAuth 설정, Stockfish 설정, LITELLM_BASE_URL, LITELLM_API_KEY, DASHBOARD_OPENROUTER_MANAGEMENT_API_KEY의 정합성이 중요함.

로그 경로​

  • 운영 컨테이너 내부 공통 로그 디렉터리는 /app/logs임.
  • 운영 컨테이너 내부 공통 AI 라우팅 런타임 경로는 /app/var/master-data/ai-routing.yml임.
  • 운영 호스트 공통 AI 라우팅 파일 경로는 /sorc001/junkbox/master-data/ai-routing.yml임.
  • 로컬 기본 로그 디렉터리는 프로젝트 루트 기준 var/log/{app-name} 구조임.
  • 로컬 var/log/ 하위 로그 파일과 rotation 압축 파일은 Git 추적 대상이 아니며 .gitignore에서 제외함.
  • 운영 기본 로그 파일 경로는 hub-api=/app/logs/app.log, chess-api=/app/logs/app.log, health-api=/app/logs/app.log, wow-api=/app/logs/app.log임.

3.4 개발 브라우저 주소 판별​

  • dev_access.py는 APP_PROFILE=local 또는 docker-local에서만 Vite 프록시가 전달한 x-junkbox-dev-server-url을 브라우저 주소의 근거로 사용함. 운영 profile에서는 이 헤더를 무시함.

  • 헤더는 등록된 UI 개발 포트 15001, 15002, 15003, 15004, 15006, 15008, 15009, 15010, 15011, 15012, 15013 중 하나이며, http://localhost·http://127.0.0.1·Android 에뮬레이터의 http://10.0.2.2·기본 경로의 사설 IPv4 주소 또는 현재 Tailscale DNS 이름의 HTTPS 주소일 때만 허용함. 요청 경로, query, 사용자 정보가 포함된 값은 허용하지 않음.

  • browser_request_url()은 보호 화면의 로그인 복귀 URL을 현재 브라우저 origin으로 구성함. browser_app_base_url()은 같은 LAN 또는 Tailnet의 다른 앱 URL을 구성하고, browser_portal_url()은 포털 메뉴의 로컬 localhost URL을 현재 접속 방식의 앱 URL로 변환함.

  • remote_dev_origins()은 허용된 UI 포트에 대한 Android 에뮬레이터 10.0.2.2 HTTP, LAN HTTP 및 Tailnet HTTPS origin을 로그인 복귀와 개발 CORS 검증에 제공함. is_remote_dev_request()는 Tailnet HTTPS만 판별하고, is_shared_dev_request()는 LAN과 Tailnet의 공유 접속을 판별함.

  • native_app_scheme(request)는 같은 개발 origin 검증을 사용하여 local/docker-local의 유효한 UI 요청에서만 junkbox-dev, 나머지는 junkbox를 반환함. Hub 앱 로그인 복귀와 Health 웹→앱 연결의 공통 기준이며 요청자가 임의의 callback scheme을 지정하는 계약을 추가하지 않음.

3.5 로깅 설정 구조​

  • 공통 로깅 정책은 LOG_ROTATION_LIMIT, LOG_RETENTION_DAYS, LOG_COMPRESSION_TYPE 기준으로 제어함.
  • profile별 로깅 동작은 LOG_LEVEL, LOG_DIAGNOSE_TOGGLE 기준으로 제어함.
  • 위 공통 키는 modules.hub.logging, modules.chess.logging, modules.health.logging, modules.wow.logging에 공통 주입됨.
  • 필요 시 HUB_LOG_*, CHESS_LOG_*, HEALTH_LOG_*, WOW_LOG_* 키로 모듈별 override를 줄 수 있는 구조를 가짐.
  • diagnose와 backtrace는 LOG_DIAGNOSE_TOGGLE 값과 연동되며, 로컬 디버깅 문맥에서만 활성화하는 구성을 전제로 함.

4. 공통 로깅 계층​

4.1 초기화 책임​

  • setup_app_logging()은 shared-core가 제공하는 공통 초기화 진입점임.
  • FastAPI 앱은 부팅 시점에 이 함수를 호출하여 표준 출력과 파일 출력을 동시에 구성함.
  • 표준 logging으로 들어오는 로그도 intercept handler를 통해 loguru로 수렴시킴.

4.2 파일 출력 정책​

  • 콘솔 출력은 sys.stdout 기준 단일 sink를 사용함.
  • 파일 출력은 모듈별 logging.file_path 기준 sink를 사용함.
  • 파일 sink는 rotation, retention, compression, enqueue=True, encoding="utf-8" 정책을 공통으로 적용함.
  • 현재 기본 운영 파일명은 앱 디렉터리 아래 app.log임.
  • 운영 호스트 볼륨과 결합되면 실제 파일 경로는 /logs001/junkbox/{app-name}/app.log 구조가 됨.

4.3 적용 모듈​

  • 현재 hub-api, chess-api, health-api, wow-api가 공통 로깅 초기화를 직접 사용함.
  • shared-ai 기반 기능의 로그도 최종적으로 같은 loguru sink 체계로 수렴함.

5. DB 계층​

5.1 엔진​

  • create_async_engine(database_url)은 명시적으로 전달한 SQLite DSN만 사용함.
  • hub-api는 sqlite+aiosqlite:// 계열 HUB_DATABASE_URL로 engine을 초기화함.
  • health-api는 sqlite+aiosqlite:// 계열 HEALTH_DATABASE_URL로 engine을 초기화함.
  • wow-api는 sqlite+aiosqlite:// 계열 WOW_DATABASE_URL로 engine을 초기화함.
  • chess-api는 sqlite+aiosqlite:// 계열 CHESS_DATABASE_URL로 앱 전용 engine을 초기화함.
  • SQLAlchemy echo 설정은 DB_ECHO를 사용함.
  • SQLite engine은 DB 파일 부모 디렉터리를 준비함.
  • SQLite engine은 연결 시 PRAGMA journal_mode=WAL, PRAGMA busy_timeout=5000, PRAGMA foreign_keys=ON을 적용함.
  • Chess 전용 engine도 같은 SQLite pragma와 부모 디렉터리 준비 규칙을 적용하며 앱 lifespan 종료 시 dispose됨.
  • ensure_engine_initialized()는 초기화되지 않은 전역 엔진 사용을 오류로 처리함.
  • get_session_maker()는 Hub처럼 자기 SQLite 파일을 소유한 프로세스가 초기화한 세션 메이커만 반환함.

5.2 세션​

  • async_sessionmaker()를 사용함.
  • AsyncSession을 모든 앱의 공통 세션 타입으로 사용함.
  • get_session() 의존성은 async with 기반으로 세션을 제공함.
  • get_session()은 요청 종료 시 commit 또는 rollback을 공통 처리함.

5.3 AsyncSession 사용 규칙​

  • session.exec()를 사용하지 않음.
  • await session.execute(select(...)) 패턴을 사용함.
  • 결과 해석은 scalar_one_or_none(), scalar_one(), scalars().all(), all()을 상황별로 명시함.
  • 저장소 계층은 asynccontextmanager 기반 세션 래퍼를 사용해 읽기와 쓰기 commit 경계를 분리할 수 있음.

6. 모델 계층​

6.1 공통 모델​

  • BaseEntity는 created_at, updated_at, created_by, updated_by, is_active 공통 필드를 제공함.
  • SQLite 감사 일시는 now_kst_naive()로 생성하여 KST(UTC+9) timezone 없는 로컬 일시로 저장함. 신규 SQLite 앱은 UTC 기본값·CURRENT_TIMESTAMP를 사용하지 않으며 외부 UTC 시각은 KST로 정규화한 뒤 저장함.
  • 공통 시계 now_kst()는 timezone-aware KST 일시, today_kst()는 KST 날짜, now_kst_naive()는 SQLite 저장용 timezone 없는 KST 일시를 반환함. 앱은 datetime.now()와 date.today()로 서버 로컬 시간대에 의존하지 않음.
  • SQLite가 직접 생성하는 날짜·일시 기본값은 junkbox_shared_core.datetime의 SQLITE_KST_DATE, SQLITE_KST_TIMESTAMP를 사용함. TimestampMixin은 Python 기본값과 SQLite server_default를 모두 제공함.
  • ensure_kst()는 offset 포함 일시를 KST로 변환하고 timezone 없는 입력을 KST로 해석하며, as_kst_naive()는 이를 SQLite 저장용 일시로 정규화함.
  • SQLite 파일 DB 엔티티가 SQLModel로 정의됨.
  • BaseEntity 계열 엔티티는 감사 컬럼 NOT NULL 제약을 만족할 수 있도록 기본값 전략을 가짐.

6.2 현재 주요 엔티티​

  • UserEntity
  • CodeTypeEntity
  • CommonCodeEntity
  • MetaEntity
  • PromptEntity
  • PortalMenuEntity
  • DashboardUserPreferenceEntity
  • WorkoutSessionEntity
  • WorkoutRecordEntity
  • MemberEntity
  • RaidMemberEntity
  • RaidScoreEntity
  • BossScoreEntity

6.3 마스터데이터 엔티티 매핑​

  • CodeTypeEntity는 Hub SQLite tb_code_type_c에 매핑되며 코드 타입 전용 컬럼명 code_type_code_id, code_type_code, code_type_code_name, code_type_code_desc를 사용함.
  • CommonCodeEntity는 Hub SQLite tb_common_c에 매핑됨.
  • MetaEntity는 Hub SQLite tb_meta_m에 매핑됨.
  • PromptEntity는 Hub SQLite tb_ai_prompt_m에 매핑되며 (prompt_key, version) 유니크 제약과 is_current=1인 키별 단일 현재 버전 유니크 인덱스를 사용함.
  • PortalMenuEntity는 Hub SQLite tb_portal_menu_m에 매핑됨.
  • UserEntity는 Hub SQLite tb_user_m에 매핑됨.
  • DashboardUserPreferenceEntity는 Hub SQLite tb_dashboard_user_preference_n에 매핑됨.
  • WorkoutSessionEntity는 Health SQLite tb_workout_session_n에 매핑됨.
  • WorkoutRecordEntity는 Health SQLite tb_workout_record_n에 매핑됨.
  • MemberEntity는 WOW 앱 SQLite tb_member_m에 매핑됨.
  • RaidMemberEntity는 WOW 앱 SQLite tb_raid_member_n에 매핑됨.
  • RaidScoreEntity는 WOW 앱 SQLite tb_raid_member_raid_score_n에 매핑됨.
  • BossScoreEntity는 WOW 앱 SQLite tb_raid_member_boss_score_n에 매핑됨.

6.4 엔티티 설계 규칙​

  • SQLite 호환 도메인 엔티티는 PostgreSQL schema qualifier와 PostgreSQL 전용 타입을 사용하지 않음.
  • Hub/Health SQLite JSON 컬럼은 SQLAlchemy 공통 JSON 타입을 사용하고, DB 내부 JSON 조건 검색보다 Python 객체 read/write를 기준으로 소비함.
  • Hub/Health PK 컬럼은 SQLite에서 INTEGER PRIMARY KEY로 동작하도록 SQLite variant를 가진 정수 PK 타입을 사용함.
  • WOW 앱 SQLite 엔티티는 schema qualifier와 PostgreSQL 전용 타입을 사용하지 않으며, 단일 PK는 INTEGER PRIMARY KEY, 점수 엔티티는 SQLModel 복합 PK를 사용함.
  • Chess SQLite 엔티티는 schema qualifier와 PostgreSQL 전용 UUID/JSONB/default를 사용하지 않음. UUID PK는 SQLAlchemy 공통 UUID 타입과 Python uuid4()로 생성하고, event_payload는 SQLAlchemy 공통 JSON 타입으로 저장함.
  • allowed_modules는 list[str] + SQLite JSON 배열 구조를 사용함.
  • DashboardUserPreferenceEntity.favorite_card_ids는 list[str] + SQLite JSON 배열 구조를 사용하고, 대시보드 큰 카드 즐겨찾기 id를 표시 순서대로 보관함.
  • DashboardUserPreferenceEntity.card_orders는 dict[str, list[str]] + SQLite JSON object 구조를 사용하고, 대시보드 탭별 큰 카드 정렬 순서를 보관함.
  • DB 컬럼명이 레거시 이름이어도 앱 내부 필드명은 현재 계약에 맞게 매핑할 수 있음.
  • 사용자 엔티티는 id 물리 PK와 user_id 논리 식별자를 함께 사용함.
  • DB 기반 감사 컬럼이 NOT NULL 제약을 가지는 엔티티는 기본값 또는 API 계층 보강으로 None 삽입을 피해야 함.

7. 공통 마스터 데이터 계층​

7.1 저장소 책임​

  • masterdata/ 패키지는 공통코드, 코드 타입, 메타, AI 프롬프트, 포털 메뉴 저장소를 담당함.
  • 공통코드·메타·포털 메뉴 진입점은 JsonMasterDataStore이고 AI 프롬프트의 버전별 저장·조회 진입점은 PromptStore임.
  • 클래스 이름은 호환성을 위해 유지되지만, 현재 구현은 JSON/YAML 파일 저장소가 아니라 DB 저장소임.
  • hub-api는 공통 마스터 데이터 CRUD와 AI snapshot 구성 시 이 저장소 계층을 사용함.
  • health-api, wow-api, rename-api 같은 소비 앱은 저장소를 직접 호출하지 않고 공통 소비 서비스로 hub-api 내부 API를 호출함.
  • MasterDataService는 HubMasterDataClient와 TtlAsyncCache를 조합하여 소비 앱의 코드 목록과 메타 조회를 담당함.
  • HUB_API_INTERNAL_TOKEN이 설정된 소비 앱은 local store fallback을 사용하지 않고 HUB_INTERNAL_BASE_URL의 내부 API 호출을 우선함.

7.2 관리 대상​

  • Hub SQLite tb_code_type_c
  • Hub SQLite tb_common_c
  • Hub SQLite tb_meta_m
  • Hub SQLite tb_ai_prompt_m
  • Hub SQLite tb_portal_menu_m

7.3 저장 원칙​

  • 저장소는 공통 세션 메이커를 사용해 읽기/쓰기 세션을 분리함.
  • 쓰기 작업은 저장소 내부에서 commit 경계를 관리함.
  • 앱 계층은 저장소가 반환하는 현재 계약 필드명만 소비함.
  • 소비 앱은 저장소가 아니라 MasterDataService가 반환하는 현재 계약 필드명만 소비함.

7.4 공통코드 구조​

  • 코드 타입 메타는 tb_code_type_c에 저장함.
  • 실제 코드는 tb_common_c에 저장함.
  • 코드 타입과 일반 코드를 한 테이블에 섞지 않음.
  • 공통코드 조회와 저장 API는 tb_common_c 기준의 common_code_id, code_type_code, common_code 계약을 유지하고, 코드 타입 메타는 tb_code_type_c 기준의 code_type_code_id, code_type_code, code_type_code_name, code_type_code_desc 계약을 사용함.

7.5 텍스트 처리 구조​

  • 일반 UI 텍스트는 shared-core 마스터데이터 계약에 포함하지 않음.
  • Python 서버 렌더링 문구와 React UI 문구는 각 템플릿/컴포넌트 소스에 한국어로 직접 작성함.

7.6 메타 구조​

  • 메타는 meta_key, meta_val, description, is_active 중심 구조를 사용함.
  • attribute01~attribute05, sort_order 같은 레거시 메타 보조 컬럼은 현재 계약에서 사용하지 않음.

7.7 AI 프롬프트 구조​

  • 프롬프트는 prompt_key, version, prompt_val, description, is_active, is_current 중심 구조를 사용함.
  • PromptStore.create_version()은 동일 키의 이전 현재 버전을 해제하고 다음 버전을 현재 버전으로 저장함. activate_version()은 과거 버전을 현재·활성 상태로 전환하며, set_active()는 현재 버전 번호를 유지한 채 활성 상태만 변경함.
  • get_current(active_only=True)는 비활성 또는 누락된 현재 버전을 반환하지 않음.

7.8 포털 메뉴 구조​

  • 포털 메뉴는 menu_id, menu_name, menu_type_code, menu_url, local_menu_url, icon_type_code, icon_val, description, is_desc_visible, sort_order_no, is_active 중심 구조를 사용함.
  • 앱 메뉴는 menu_type_code=APP을 사용함.
  • 하위 호환을 위해 menu_type_code=PROJECT 값은 포털 소비 화면과 정렬 저장에서 APP 그룹으로 해석될 수 있음.
  • 서비스 메뉴는 menu_type_code=SERVICE를 사용함.
  • icon_type_code=TEXT는 icon_val을 텍스트 아이콘으로 사용함.
  • icon_type_code=IMAGE는 icon_val을 이미지 URL로 사용함.
  • icon_type_code=APP_ICON은 icon_val을 shared-ui 앱 아이콘 slug로 사용함.
  • APP_ICON의 icon_val은 포털 카드 아이콘, 앱 favicon, PWA 설치 아이콘을 같은 앱 아이콘 세트로 연결하는 관리 값임.
  • 포털 소비 화면과 포털 메뉴 관리 화면은 같은 저장소를 공유함.
  • 포털 정렬 저장은 탭별 sort_order_no 갱신으로 처리함.
  • 포털 정렬 저장에서 APP 탭은 APP과 하위 호환 PROJECT active row 집합을 함께 대상으로 삼을 수 있음.

7.9 소비 클라이언트와 TTL 캐시​

  • HubMasterDataClient는 hub-api 내부 master-data API를 호출하는 공통 HTTP 클라이언트임. get_prompt()는 활성 현재 버전 프롬프트 row를 반환하며 local profile의 토큰 미설정 fallback은 PromptStore를 사용함.
  • HubMasterDataClient는 HUB_INTERNAL_BASE_URL, HUB_API_INTERNAL_TOKEN, HUB_API_INTERNAL_TOKEN_HEADER, MASTERDATA_HTTP_TIMEOUT_SECONDS 설정을 사용함.
  • TtlAsyncCache는 key별 TTL 캐시와 key별 lock을 제공하여 동일 master-data 요청의 중복 로딩을 줄임. clear()는 세대 번호를 갱신해 갱신 이전에 시작된 로딩 결과가 다시 캐시에 들어오지 않도록 함.
  • MasterDataService는 코드 타입별 코드 목록, 코드명 맵, 메타 값, active 포털 메뉴 목록을 조회하는 공통 서비스임.
  • MasterDataService.get_portal_app_icon_key(app_key, match_values=...)는 active 포털 메뉴 중 APP 또는 하위 호환 PROJECT 메뉴의 APP_ICON 값을 찾아 앱 아이콘 slug를 반환함.
  • find_portal_app_description(rows, app_key, match_values=...)와 MasterDataService.get_portal_app_description(...)은 active APP/PROJECT 메뉴를 앱 아이콘 slug 또는 메뉴 이름·URL로 식별하고, is_desc_visible이 참인 행의 비어 있지 않은 description을 반환함. 메뉴 조회 오류나 표시할 설명이 없으면 None을 반환하여 앱 셸의 설명 요소를 숨김.
  • 앱별 favicon 또는 PWA icon slug는 앱 내부 상수보다 포털 메뉴의 APP_ICON + icon_val을 우선 사용하고, 조회 실패 시 앱 기본 slug를 fallback으로 사용할 수 있음.
  • create_masterdata_service()는 앱별 FastAPI 의존성 또는 daemon 초기화 코드가 공통 소비 서비스를 만들 때 사용하는 진입점임.
  • MASTERDATA_CODES_TTL_SECONDS, MASTERDATA_METAS_TTL_SECONDS가 각 데이터 범주의 캐시 TTL을 제어함.
  • PromptService는 활성 현재 버전 AI 프롬프트를 HubMasterDataClient.get_prompt() 또는 주입된 loader로 조회하고 최대 15초 TTL로 캐시함. get_row(), get_value(), render()를 제공하며 조회 실패 시 stale 값을 사용하지 않음.
  • clear_masterdata_cache()와 clear_prompt_cache()는 공통코드·메타 및 프롬프트 캐시를 비움. POST /api/internal/master-data/cache/refresh 라우터는 HUB_API_INTERNAL_TOKEN_HEADER와 HUB_API_INTERNAL_TOKEN으로 인증한 뒤 두 캐시를 비우고 항목 수를 반환함.
  • Hub의 갱신 대상은 MASTERDATA_REFRESH_TARGETS의 쉼표 구분 name=http://host:port 값으로 지정할 수 있음. 미지정 시 로컬 개발 포트와 운영 Compose 서비스 주소를 사용함.

7.10 텍스트 포맷팅 기준​

  • 메시지 DB 조회나 공통 메시지 포맷팅 헬퍼는 사용하지 않음.
  • 파라미터가 필요한 사용자 문구는 각 호출 지점에서 템플릿 리터럴, f-string, Jinja 변수 치환 등 언어별 기본 문자열 기능으로 작성함.
  • 반복되는 문구가 실제 중복 비용을 만들 때만 앱 내부 상수나 작은 helper를 검토함.

7.11 local fallback 정책​

  • APP_PROFILE=local에서 HUB_API_INTERNAL_TOKEN이 비어 있으면 HubMasterDataClient는 개발 편의용 local store fallback을 사용할 수 있음.
  • local fallback은 JsonMasterDataStore를 통해 같은 DB 저장소 계약을 조회함.
  • 운영 profile에서는 HUB_API_INTERNAL_TOKEN 누락 시 내부 master-data API 소비가 실패함.
  • 운영 profile에서는 공통 master-data 조회가 조용히 로컬 DB 직접 조회로 전환되지 않음.
  • fallback이 동작하면 경고 로그를 남김.

8. 인증 계층​

8.1 JWT 유틸리티​

  • 토큰 생성, 검증, 쿠키 생성 책임을 가짐.
  • 앱은 JWT 구현 세부사항을 직접 다루지 않음.
  • 사용자 로그인 토큰 생성 시 만료 시간은 호출자가 명시적으로 전달함.
  • 사용자 로그인 토큰은 sid claim을 포함할 수 있으며, sid는 hub-api가 소유하는 사용자 세션 row의 session_id와 매칭됨.
  • 사용자 세션 만료 시간과 슬라이딩 갱신 임계값의 소스 오브 트루스는 hub-api 정책 파일임.
  • shared-core는 사용자 세션 row를 직접 저장하거나 조회하지 않으며, 일반 사용자 JWT의 세션 유효성 판정은 hub 내부 인증 API에 위임함.
  • 쿠키 생성 시 max_age_seconds는 호출자가 명시적으로 전달하며, shared-core는 세션 정책값을 직접 소유하지 않음.
  • 로그인·로그아웃·슬라이딩 갱신 쿠키는 요청이 검증된 Tailnet HTTPS 개발 origin이면 Secure를 사용함. localhost와 LAN HTTP 개발 요청은 기존 쿠키 설정을 따르며, 운영 쿠키 설정은 유지됨.
  • AI 에이전트 전용 토큰은 sub=JUNKBOX_AI_AGENT, role=ROLE_AI claim을 포함하고 만료 클레임을 포함하지 않는 장기 토큰 구조임.

8.2 의존성 함수​

  • get_current_user는 필수 인증임.
  • get_optional_user는 선택 인증임.
  • require_ai_role은 AI 에이전트 전용 read-only API에서 ROLE_AI claim을 강제하는 의존성임.
  • require_module(module_code)는 권한 강제 의존성임.
  • require_modules(*module_codes)는 전달된 모든 모듈 권한을 강제하는 의존성임.
  • require_automation_job(job_type)는 Automation worker 전용 internal Job API 의존성이고, require_questlog_service()는 QuestLog 서버만 호출하는 집계 전용 API 의존성임. 후자는 X-Junkbox-Service: questlog와 modules.questlog.service_token을 상수 시간 비교로 검증하며 토큰이 설정되지 않으면 모두 403임. 사용자 JWT·Automation 토큰으로는 통과하지 않음.
  • 공통 인증 의존성은 Authorization: Bearer 헤더를 우선 해석하고, 없으면 COOKIE_NAME 설정값 기준 쿠키를 해석함.
  • 일반 사용자 JWT는 로컬 서명/만료 검증 후 HUB_INTERNAL_BASE_URL의 POST /api/internal/auth/validate를 호출해 세션 유효성, 최신 사용자 활성 상태, 최신 권한을 확인함.
  • POST /api/internal/auth/validate 호출에는 HUB_API_INTERNAL_TOKEN_HEADER 헤더와 HUB_API_INTERNAL_TOKEN을 사용함.
  • hub 인증 validate 응답의 allowed_modules가 현재 권한 판단의 기준임.
  • ROLE_AI JWT는 사용자 세션 테이블 검증 대상이 아니며 require_ai_role이 필요한 read-only API에서만 허용됨.
  • require_module(module_code)는 ROLE_AI 토큰이 일반 비즈니스 API에 접근하면 403으로 차단함.
  • require_modules(*module_codes)도 ROLE_AI 토큰을 일반 비즈니스 API에서 403으로 차단하며, 정규화된 각 모듈 코드가 allowed_modules에 모두 포함되어야 현재 사용자를 반환함.

8.3 hub 인증 클라이언트​

  • HubAuthClient는 개별 앱과 공통 인증 계층이 hub 내부 인증 API를 호출할 때 사용하는 공통 HTTP 클라이언트임.
  • HubAuthClient.validate()는 POST /api/internal/auth/validate를 호출해 일반 사용자 JWT의 세션 유효성을 확인함.
  • HubAuthClient.refresh()는 POST /api/internal/auth/refresh를 호출해 슬라이딩 세션 갱신 필요 여부와 새 JWT를 조회함.
  • 내부 호출 설정은 HUB_INTERNAL_BASE_URL, HUB_API_INTERNAL_TOKEN, HUB_API_INTERNAL_TOKEN_HEADER, MASTERDATA_HTTP_TIMEOUT_SECONDS를 사용함.
  • 클라이언트는 요청의 user-agent와 client IP 또는 x-forwarded-for 값을 hub에 전달할 수 있으며, hub는 이를 세션 last_seen_at, user_agent, ip_address 갱신에 사용할 수 있음.
  • hub 내부 인증 API가 401을 반환하면 클라이언트는 인증 실패로 해석하고 사용자 인증 흐름에 처리를 위임함.

8.4 권한 정규화​

  • allowed_modules는 배열, JSON 문자열, 콤마 문자열 등 다양한 입력을 수용할 수 있어야 함.
  • 내부 판단은 대문자 모듈 코드 배열 기준으로 수행함.
  • 과거 SYSTEM 코드는 HUB와 같은 운영 허브 권한으로 정규화함.
  • 사용자 관리 API는 허용 모듈 입력을 대문자 코드 집합으로 정규화하고, 중복과 미허용 코드를 제거함.

8.5 슬라이딩 세션 미들웨어​

  • SlidingSessionMiddleware는 브라우저 쿠키 기반 요청의 세션 갱신을 공통 처리함.
  • 미들웨어는 요청 쿠키에 COOKIE_NAME 토큰이 없으면 아무 동작도 하지 않음.
  • 미들웨어는 HUB_INTERNAL_BASE_URL의 POST /api/internal/auth/refresh를 호출하고 HUB_API_INTERNAL_TOKEN_HEADER 헤더에 HUB_API_INTERNAL_TOKEN을 전달함.
  • hub 내부 인증 API가 refreshed=true와 새 토큰을 반환하면 미들웨어는 응답에 같은 쿠키 이름으로 새 HttpOnly 쿠키를 설정함.
  • hub 내부 인증 API가 refreshed=false를 반환하면 미들웨어는 쿠키를 변경하지 않음.
  • hub 내부 인증 API가 인증 실패 토큰에 대해 401을 반환하면 미들웨어는 세션 갱신을 수행하지 않고 이후 인증 흐름에 처리를 위임함.
  • 미들웨어의 갱신 판단은 hub 세션 테이블과 정책 YAML을 기준으로 하며, shared-core는 직접 세션 저장소를 소유하지 않음.
  • hub 내부 인증 API 호출이 네트워크 오류, timeout, 401을 제외한 오류 상태로 실패하면 미들웨어는 공통 예외 응답으로 처리함.
  • 미들웨어는 로그인, 로그아웃, /api/internal/*, 정적 자산, 문서, 헬스체크 경로를 갱신 대상에서 제외함.
  • add_sliding_session_middleware(app)는 hub, health, raid, rename, chess 같은 공통 로그인 소비 앱의 FastAPI 앱 초기화 시 등록함.

9. 비밀번호 계층​

9.1 해싱​

  • passlib 컨텍스트를 사용함.
  • bcrypt 조합을 기준으로 동작함.

9.2 호환성 처리​

  • passlib가 기대하는 bcrypt 인터페이스 차이를 보정하는 shim을 포함함.
  • 목적은 경고 제거와 안정적 해시/검증 유지임.

10. 예외 계층​

  • 커스텀 예외 타입을 제공함.
  • FastAPI 예외 핸들러 등록 함수를 제공함.
  • 앱은 HTTP 상태 코드와 메시지 포맷을 공통 규칙으로 유지함.
  • add_exception_handlers는 요청 검증 오류(RequestValidationError)를 HTTP 422와 detail(첫 오류의 필드와 사유를 담은 한국어 한 문장 문자열), status_code, 원본 errors(type·loc·msg)로 응답함. 화면이 detail을 그대로 표시할 수 있도록 배열이 아닌 문자열로 줌.
  • 서비스에서 올라온 ValueError는 메시지에 한글이 있으면 업무 규칙 위반으로 보고 HTTP 400과 해당 메시지로 응답함. 한글이 없는 ValueError는 내부 오류로 보고 기존처럼 HTTP 500 Internal server error로 응답함. 새 업무 규칙 오류는 CustomException을 우선 사용함.

11. 헤더 검색 해석​

  • junkbox_shared_core.header_filter는 원격 Tabulator 입력형 헤더 검색 문법을 parse_header_filter, escape_like, sqlalchemy_header_filter로 제공함.
  • 일반 입력은 이스케이프된 대소문자 무시 일부 포함 검색, =는 정확 일치 검색임. 숫자·날짜 종류의 >, <, >=, <=는 대소 비교이며 텍스트 종류에서 부등호로 시작하는 입력은 일반 문자열로 취급함.
  • 숫자 비교는 유한한 숫자만 허용하고 날짜 비교는 유효한 YYYY-MM-DD 입력만 허용함. 잘못된 비교값은 일치 행이 없는 SQL 조건을 반환함.
  • 서버 조회 화면은 필터를 목록과 총 건수 쿼리에 동일하게 적용함. 일반 관리자 조회 API의 기존 검색 의미를 바꿀 필요가 없는 경우에는 헤더 검색을 명시적으로 요청한 경로에만 이 문법을 적용함.

12. 사용 원칙​

  • 앱 코드에서 중복 인증, 중복 설정, 중복 세션 생성을 만들지 않음.
  • 공통 규칙은 shared-core에 수렴시킴.
  • 새 앱 추가 시 우선 shared-core 의존으로 시작함.
  • 공통 마스터 데이터 소비가 필요하면 앱별 HTTP 클라이언트나 TTL 캐시를 새로 만들지 않고 MasterDataService를 사용함.
  • 공통 마스터 데이터 추가가 필요하면 우선 DB 저장소와 hub-api API 계약에 맞는지 검토함.
  • AI 전용 master-data 접근은 앱별 임의 구현보다 hub-api의 ROLE_AI 기반 통합 snapshot API와 공통 인증 의존성을 우선 사용함.
  • AI 라우팅처럼 정책성 파일이 필요한 경우에만 YAML 경로 관리 방식을 사용함.

13. 단위 표기​

  • junkbox_shared_core.units는 단위 표기 표준(공통 UI 가이드 2.8)을 서버 생성 문구에 적용하는 format_quantity·with_unit을 제공함. 기호 단위는 줄바꿈 방지 공백으로 띄우고 한글 단위와 %·각도는 붙임.