본문으로 건너뛰기

JunkBox 코어 가이드

1. 문서 범위​

  • 이 문서는 JunkBox 전체에 적용하는 구조 원칙과 공통 계약을 정의함. 기술 스택, 책임 경계, 날짜·시간, 데이터베이스, ORM, 인증·권한, 공통 마스터 데이터 구조를 다룸.
  • 앱·포트·권한 코드 목록과 앱 간 연동은 docs/junkbox/common/guide-jb-overview.md가 소유함.
  • 설정·환경 파일, 로컬 개발 실행, 신규 앱 생성 계약, 운영 배포, 개발 문서 벡터 캐시는 docs/junkbox/common/guide-jb-dev-ops.md가 소유함.
  • 앱별 상세 계약은 각 앱 가이드가 소유하며 이 문서는 앱 고유 규칙을 반복하지 않음.

2. 기술 스택​

2.1 백엔드​

  • 언어는 Python 계열을 사용함.
  • 웹 프레임워크는 FastAPI임.
  • ORM 계층은 SQLModel과 SQLAlchemy 2 비동기 스택을 사용함.
  • SQLite 비동기 드라이버는 aiosqlite임.
  • 워크스페이스와 패키지 관리는 uv를 사용함.
  • 공통 애플리케이션 로깅은 loguru 기반 구조를 사용함.
  • 체스 분석은 Stockfish를 사용하며 복기 코칭은 저장된 분석 결과를 근거로 Automation 작업에서 생성함.
  • 레이드 점수 연동은 httpx 기반 외부 HTTP 호출과 GraphQL 요청을 사용함.
  • 애플리케이션 런타임 저장소는 SQLite를 사용함.
  • AI 개발 문서 지식 검색은 애플리케이션 런타임과 분리된 Vault PostgreSQL pgvector와 OpenAI 호환 embeddings API를 사용함.

2.2 프런트엔드 및 정적 자산​

  • 운영 화면 프런트엔드는 각 apps/*-ui의 Vite 6 기반 React + TypeScript 프로젝트를 사용함.
  • FastAPI는 서버 렌더링 HTML 골격 위에 각 앱의 dist 정적 자산을 마운트하여 화면을 제공함.
  • 로컬 개발에서는 각 UI 앱의 Vite 개발 서버와 FastAPI 백엔드를 병행 실행할 수 있음.
  • UI 개발 서버의 수신 구성과 LAN·Tailnet 접속 경로는 개발 환경·운영 배포 가이드의 로컬 개발 절을 따름.
  • 운영 컨테이너 내부 포트는 모든 Docker 서비스가 8080으로 통일함. 규칙은 공통 개발 환경·운영 배포 가이드의 운영 컨테이너 포트 통일 규칙을 따름.
  • 공통 UI 자산은 libs/shared-ui에서 제공함.
  • 공통 앱 아이콘 자산은 libs/shared-ui의 app-icons/{slug}/icon.svg, icon-180.png, icon-192.png, icon-512.png 구조로 제공함.
  • 운영 화면 소스는 .ts와 .tsx만 사용하며, 신규 화면 로직을 .js로 직접 작성하지 않음.
  • TypeScript 컴파일은 strict 모드를 기준으로 유지함.
  • 운영 자산의 표준 서빙 흐름은 백엔드 포트가 빌드된 프런트 산출물을 직접 서빙하는 구조임.
  • 공통 shared-ui 정적 자산은 서버 템플릿이 버전 쿼리 파라미터를 붙여 링크하므로, 배포 후 CDN이 예전 고정 경로 CSS를 계속 재사용하지 않는 구조임.
  • 공통 CSS는 hub-ui-base.css와 화면 모드별 hub-ui-mobile.css 또는 hub-ui-desktop.css를 조합해서 로드하는 구조임.
  • 공통 CSS와 Tabulator vendor CSS 링크 선언은 libs/shared-ui의 stylesheet 매크로로 중앙화하며, 공통 베이스 템플릿과 standalone 템플릿은 같은 매크로를 호출함.
  • 공통 베이스 템플릿과 standalone 템플릿은 inline <style>을 포함하지 않으며, 모든 CSS는 libs/shared-ui 산출물에서 공급함.
  • 화면 폰트는 shared-ui가 제공하는 PretendardVariable.woff2와 hub-ui-base.css의 중앙 폰트 선언을 기준으로 통일함.
  • 앱 favicon, Apple touch icon, PWA manifest icon은 포털 메뉴의 APP_ICON + icon_val 관리값을 shared-ui 앱 아이콘 slug로 해석하여 같은 아이콘 세트를 사용함.

2.3 인증​

  • JWT 기반 인증을 사용함.
  • 토큰 전달 경로는 Authorization: Bearer 헤더와 COOKIE_NAME 설정값 기준 HttpOnly 쿠키를 병행함.
  • 현재 기본 쿠키 이름은 JUNKBOX_AUTH임.
  • 비밀번호 처리는 passlib와 bcrypt 조합을 사용함.
  • 로그인 화면은 hub-api가 공통 진입점을 제공하고, 각 앱은 required_module과 redirect를 기준으로 복귀 흐름을 사용함.
  • 공통 로그인 화면은 마지막으로 로그인에 성공한 user_id를 별도 쿠키에 저장하고 다음 로그인 기본값으로 사용함.

3. 핵심 구조 원칙​

3.1 웹 우선과 기능별 웹·네이티브 운영​

  • 일반 조회·입력·관리 기능은 웹을 우선하며, 백그라운드 지속 실행·음성·기기 연동처럼 웹 제약을 해소하거나 효용이 큰 기능을 네이티브 대상으로 삼음.
  • 기능별로 웹과 네이티브 구현을 병행해 사용할 수 있으며, 사용성·안정성 검증에 따라 상호 보완하거나 한쪽으로 통합·제거하는 운영 원칙임. 동일 기능의 두 구현을 영구 유지하거나 일괄 네이티브 전환하는 정책은 아님.
  • 병행 구현은 화면·실행 환경의 선택임. 사용자 계정·권한·도메인 데이터·마스터데이터의 별도 사본을 업무 저장소로 이중 관리하지 않으며 기존 도메인 API와 서버 소유권을 기준으로 함.
  • 동일 기능을 웹과 네이티브에서 병행 구현할 때 음성 안내를 추가하거나 수정하면 양쪽의 안내 시점·문구·신호음·진동을 대조하고 일치시킴. 재생은 각 플랫폼의 공통 기능을 사용하며, 브라우저나 OS 제약으로 생기는 차이는 해당 기능 가이드에 명시함.
  • 현재 Health 웹의 러닝 계획 관리와 /running-run/{planId} 실행은 유지됨. 네이티브의 첫 구현 대상은 러닝 실행이며 계획 목록·상세·생성·수정과 로그인 화면은 기존 웹을 재사용하는 설계 기준임.
  • 후속 요청에서 특정 기능의 책임을 재배치하거나 한쪽 구현을 제거할 때는 대상 기능·데이터 호환성·대체 진입·기존 사용자 흐름을 확인하고 요청 범위에서 처리함. 네이티브 프로젝트 생성만으로 기존 웹 기능을 제거하지 않음.

3.2 운영 허브 집중화​

  • 인증, 권한 체크, 공통 마스터 데이터 관리, 운영 관리자 화면은 hub-api에 집중함.
  • 다른 앱이 공통코드와 메타 원본을 자체적으로 소유하지 않음.
  • Hub 외 보호 앱은 로그인 화면, 로그인 API, credential 검증 API를 독자적으로 소유하지 않고 hub-api 공통 로그인 진입점과 hub-api가 발급한 JWT를 사용함.
  • 다른 앱은 DB 기반 공통 master-data 로컬 원본 데이터를 직접 소유하지 않고 hub-api 내부 API를 통해 조회함.
  • 다른 앱은 Hub SQLite 파일을 직접 열지 않으며, AI 사용 로그도 shared-ai가 Hub internal API로 전달하고 Hub가 저장함.
  • AI 코딩 컨텍스트도 공통 master-data 로컬 원본을 직접 읽지 않고 hub-api의 ROLE_AI JWT 기반 통합 snapshot API를 통해 조회함.

3.3 공통 로직 중앙화​

  • JunkBox 서버의 예약·정기·배치 실행은 automation-api가 유일하게 소유함. 새 배치·예약·cron 작업은 개별 서버 앱의 lifespan, asyncio loop, scheduler 클래스에 추가하지 않고 Automation 작업 계약으로 등록함. 사용자가 폰에서 시작한 운동의 실시간 타이머·단계 전환은 네이티브 실행 책임이며 서버 예약 작업과 구분함.
  • 호스트 인프라 백업은 sleepzz 사용자 OS 크론으로 매일 08:00에 실행되며 도메인 예약 작업과 별도임. 백업 결과 알림은 Message API의 백업 서비스 인증 경로로 전달함.
  • 도메인 앱은 자기 SQLite 데이터와 업무 규칙을 소유하고, Automation이 호출할 최소 범위 internal Job API를 제공함.
  • Automation은 Hub·Message·도메인 SQLite 파일을 직접 읽거나 쓰지 않으며, 대상 앱 HTTP API와 service-to-service 인증으로만 작업을 실행함.
  • 도메인 조건이 즉시 발생한 메시지는 도메인 앱 outbox publisher가 Message API를 직접 호출함. 즉시 조건마다 Automation을 경유하지 않음.
  • Message API는 메시지 채널 전달, 발송 이력, 전달 재시도만 소유함. Message UI의 예약·정기 관리 화면은 Automation API가 소유하는 작업 정의를 조회·수정하는 표현 계층임.
  • 설정, JWT/쿠키 유틸리티, 공통 인증 의존성, 예외, 공통 엔티티, 공통 마스터 데이터 저장소, master-data 내부 API 소비 클라이언트, TTL 캐시는 shared-core에 둠.
  • 사용자 로그인 세션의 영속 상태와 유효성 판정은 hub-api에 둠.
  • AI provider 어댑터, 기능별 모델 라우팅, usage-log writer, AI 통신 예외 정규화는 shared-ai에 둠.
  • 외부 AI 모델·AI API(LLM, 임베딩, TTS, STT, 이미지 생성·인식 등 과금형 추론 호출)는 shared-ai → LiteLLM proxy → Hub 공통 사용 로그(tb_ai_usage_logs_n) 경로로만 사용함. 모델 등록과 단가는 LiteLLM이 소유하므로 앱은 공급자를 직접 호출하거나 자체 사용량 테이블·단가 계산을 두지 않음. 월 상한처럼 호출 전 통제가 필요한 기능은 공통 로그의 사전 예약을 사용함.
  • LiteLLM 표준의 대상이 아닌 것은 기기·서버 안에서 도는 로컬 모델(Android 내장 TTS), 추론이 아닌 관리·조회 API(OpenRouter 사용량 조회), Lichess·Stockfish 같은 비LLM 엔진임. 과금되는 외부 추론인지가 판정 기준임.
  • LiteLLM을 거치지 않는 호출은 사용자가 허가 예외로 정한 경우만 허용하며 이 절의 허가 예외 목록에 대상과 사유를 등록함. 목록에 없는 직접 호출은 위반임.
  • 허가 예외 목록: 등록된 예외 없음.
  • 레이아웃, 스타일, 공통 템플릿, Tabulator 헬퍼, 앱 셸 동작은 shared-ui에 둠.
  • 앱별 CSS, 화면별 CSS, inline style은 운영 화면 구현 표준에 포함하지 않음.
  • 각 앱 화면의 페이지 진입점과 타입 계약은 해당 {app}-ui에 둠.
  • Vite 개발 모드 자산 주입과 React refresh preamble 주입은 공통 베이스 템플릿과 서버 템플릿 컨텍스트를 통해 처리함.
  • 모듈 간 직접 DB 결합보다 내부 API 재사용을 우선함.
  • 공통 규칙은 shared-core, shared-ai, shared-ui로 수렴시킴.
  • 운영 화면은 관리 생산성과 빠른 확인을 우선함.

3.4 TypeScript 우선 원칙​

  • 프런트엔드 소스 코드는 TypeScript 기준으로 유지함.
  • 신규 화면, 공통 헬퍼, 앱 셸 로직은 .ts 또는 .tsx로 작성함.
  • TypeScript 설정은 strict 모드를 유지함.
  • any 사용은 최후 수단으로 제한하며, API 응답과 테이블 데이터는 명시적 타입 계약을 우선함.
  • 브라우저 전역 주입이 필요하면 window 임의 확장보다 import.meta.env와 타입 선언 파일을 우선 사용함.

3.5 데이터 관리 구조​

  • 공통코드, 코드 타입, 메타, 포털 메뉴는 DB 기반 마스터 데이터 구조를 사용함.
  • 포털 메뉴의 앱 구분은 menu_type_code=APP을 사용하며, 하위 호환 데이터의 PROJECT 값은 포털 소비 화면에서 APP 그룹으로 해석될 수 있음.
  • 포털 메뉴의 icon_type_code=APP_ICON과 icon_val은 포털 카드 아이콘, 앱 favicon, PWA 설치 아이콘을 같은 shared-ui 앱 아이콘 slug로 묶는 단일 관리 지점임.
  • 사용자에게 노출되는 일반 UI 텍스트는 소스에 한국어 문구로 직접 작성함.
  • 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값은 기존 DB 기반 구조를 사용함.
  • LLM 런타임 프롬프트의 단일 관리 지점은 Hub AI 프롬프트 메뉴와 tb_ai_prompt_m임. 업무·공통 지침의 전체 적용 범위는 common/guide-jb-common-master-data.md 8.3절을 따름.
  • AI 기능별 모델 라우팅은 YAML 기반 정책 파일 구조를 사용함.
  • 사용자, 사용자 세션, AI 로그, 운동 기록, 레이드 운영 데이터는 DB 기반 구조를 사용함.
  • 공통코드, 코드 타입, 메타, 포털 메뉴, 사용자, 사용자 세션, 대시보드 사용자 preference, AI usage log는 Hub SQLite 파일 /sorc001/junkbox/db/hub.sqlite3를 사용함.
  • 앱 도메인 데이터는 해당 앱의 API가 단독 writer인 앱 전용 SQLite 파일에 저장함. 다른 앱의 원본 데이터는 복제하지 않고 API로 조회함.
  • AI 개발 지식 검색용 문서 캐시는 PostgreSQL vault 스키마와 pgvector 기반 벡터 테이블을 사용함.
  • 개발 문서 캐시의 원본은 vault/docs/**/*.md 파일이며, JunkBox 개발 가이드의 Source of Truth는 vault/docs/junkbox/**/*.md 파일임.
  • 따라서 현재 시스템은 DB 기반 운영 데이터, YAML 기반 AI 라우팅 정책, 벡터 DB 기반 개발 문서 캐시를 함께 다루는 구조임.
  • DB 기반 사용자 구조에서 Hub SQLite tb_user_m는 id 물리 PK와 user_id 논리 식별자를 함께 사용함.
  • DB 기반 사용자 세션 구조는 Hub SQLite tb_user_session_n을 사용하며 JWT의 sid claim과 세션 테이블의 session_id를 연결함.

3.6 사용자별 데이터 격리​

  • Health의 공유 운동 기준정보를 제외한 도메인 기능은 소유자 user_id를 저장하고, API·service 계층의 모든 조회·집계·계산·변경 경로에서 현재 사용자 조건을 강제함.
  • 요청 본문이나 쿼리로 받은 사용자 식별자를 신뢰하지 않고 인증 토큰의 사용자를 기준으로 함.

4. 날짜와 시간 기준​

  • JunkBox 전체의 업무 날짜와 시각은 Asia/Seoul(KST, UTC+9) 기준임. 신규 웹·네이티브 앱과 기존 기능의 추가·수정에 동일하게 적용함. 현재 날짜·시각, 기본 입력값, 날짜 경계, 일정·예약, 날짜 필터·집계, 감사 일시, API·화면 표시의 기준을 KST로 통일함.
  • Python은 shared-core의 now_kst()·today_kst()·now_kst_naive(), 웹은 shared-ui의 KST 유틸을 사용함. 네이티브 앱에서 업무 날짜·시각이 필요하면 앱 내부 공통 코드에서 ZoneId.of("Asia/Seoul")을 명시함. 서버·컨테이너·브라우저·기기의 기본 시간대에 의존하지 않으며 한국 자정 직전·직후를 KST 이외의 환경에서도 검증함.
  • 모든 JunkBox SQLite의 업무·감사 일시는 offset 없는 Asia/Seoul 일시로 저장함. 앱에서 생성하는 일시는 shared-core의 now_kst_naive()를 사용하고, ORM을 거치지 않는 SQL에도 KST 값을 전달하거나 KST SQL 표현식을 명시함.
  • 새 DB·테이블은 최초 스키마부터 DB가 자동 채우는 값도 KST로 정의함.
    • 현재 일시 기본값은 DEFAULT (datetime('now', '+9 hours')), 현재 날짜 기본값은 DEFAULT (date('now', '+9 hours'))를 사용함.
    • 시각 전용 값이 DB에서 자동 생성되어야 할 때는 time('now', '+9 hours')를 사용함.
    • 기존 컬럼과 비교하는 경우 저장 포맷과 소수초 정밀도도 맞춤.
    • 이 규칙은 ORM의 컬럼 기본값과 별개로 DDL, 스키마 초기화, 마이그레이션, 수동 SQL에 적용함.
  • Python DDL과 ORM의 server_default에는 junkbox_shared_core.datetime의 SQLITE_KST_TIMESTAMP, SQLITE_KST_DATE를 사용함. 각 앱의 SQLite 파일은 독립적으로 관리하며 동일한 SQL 표현식을 공유함.
  • SQLite의 CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME은 UTC를 반환함. 'localtime'은 실행 환경 시간대에 의존하므로 둘 다 업무 시각 생성에 사용하지 않음. 개발·운영 Compose의 TZ=Asia/Seoul 설정만으로 SQLite 기본값을 보장할 수 없음. DB 기본값은 INSERT에서 값이 생략된 경우에 적용되며 갱신 시각은 UPDATE가 직접 설정함.
  • SQLite의 timezone 없는 일시는 KST 로컬 일시로 해석함. 외부 API가 UTC 또는 offset을 포함한 일시를 제공하면 저장 전에 KST로 정규화하며, timezone-aware 컬럼 계약이 없는 SQLite 저장소에서는 timezone 정보를 제거함. 날짜 전용 값과 사용자가 직접 입력한 업무 시각은 변환 대상이 아님.
  • 앱에서 날짜 전용 기본값은 today_kst()로 계산하며 날짜와 현재 시각을 함께 판단할 때는 now_kst()를 한 번 얻어 같은 시점의 날짜·시각을 사용함. JWT NumericDate, epoch, 외부 API 토큰 만료 같은 절대시각은 해당 프로토콜을 따르고 업무 날짜·SQLite 저장·화면 표시 경계에서 KST로 해석함. 운동 타이머·timeout 등 경과 시간은 단조 시계로 계산함.
  • PostgreSQL에서 시점을 보관하는 timestamptz는 절대시각 계약을 유지함. DB 세션의 TimeZone은 Asia/Seoul을 기준으로 하고, 업무일 계산·날짜 필터처럼 SQL 결과의 날짜 경계가 중요한 곳에는 AT TIME ZONE 'Asia/Seoul'을 명시함.
  • 신규 SQLite 스키마는 KST 이외의 실행 환경에서 자동 생성 컬럼을 생략한 INSERT와 한국 자정 전후의 날짜 경계를 검증함. 기존 스키마 변경은 초기 생성과 업그레이드를 모두 검증하고, offset 없는 기존 값의 원래 시간대는 작성 경로와 근거를 확인한 뒤 판단함.
  • 기존 SQLite의 기본값을 이관할 때는 파일별로 백업을 만들고 트랜잭션에서 기본값을 교체함. 기존 값, 인덱스, 트리거, 자동증가 번호를 보존하며 외래키와 DB 무결성을 검증함.
  • 개발·운영 Compose는 공통 timezone anchor로 각 서비스에 TZ=Asia/Seoul을 명시함. 이 실행 환경 설정과 별개로 업무 시각 계산은 공통 KST 함수를 사용함.

5. 데이터베이스 전략​

5.1 SQLite 파일과 소유권​

  • 애플리케이션 런타임은 SQLite 파일 DB를 사용함.
  • 앱별 SQLite 파일은 호스트 /sorc001/junkbox/db/{app}.sqlite3에 두며 파일 목록은 시스템 개요의 앱 표를 따름. 로컬 비컨테이너 실행과 컨테이너가 같은 파일을 사용함.
  • Docker Compose는 호스트 /sorc001/junkbox/db를 컨테이너 /app/db에 마운트함. 컨테이너 기준 DSN은 sqlite+aiosqlite:////app/db/{app}.sqlite3, 로컬 비컨테이너 기본 DSN은 sqlite+aiosqlite:////sorc001/junkbox/db/{app}.sqlite3 형식이며 앱별 {APP}_DATABASE_URL로 설정함.
  • SQLite 파일은 Docker 이미지 생명주기와 분리된 호스트 영속 파일이며 컨테이너 내부 임시 파일로 관리하지 않음.
  • 각 SQLite 파일의 writer는 해당 앱 하나임. Automation SQLite만 automation-api와 automation worker가 함께 씀.
  • Hub·WOW·Chess·Health SQLite 연결은 PRAGMA journal_mode=WAL, PRAGMA busy_timeout=5000, PRAGMA foreign_keys=ON을 적용함.
  • 앱 추가 시 앱별 단독 writer가 명확한 도메인은 별도 SQLite 파일 DB를 사용하고, 다른 앱의 SQLite 파일에는 직접 접근하지 않음.
  • SQLite 파일 간 DB 레벨 FK를 전제로 하지 않으며, user_id 같은 cross-domain 식별자는 서비스 계층의 느슨한 참조로 유지함.

5.2 앱별 저장 범위​

  • Hub SQLite는 공통 운영 데이터, 인증, 마스터데이터, 포털 구성, 대시보드 사용자 preference, AI 사용 로그를 저장함.
  • 다른 앱은 공통 기준정보, 사용자 인증, 세션 검증, 포털 메뉴, AI usage log를 직접 DB 파일로 소유하거나 write하지 않고 hub-api internal API와 JWT/Cookie 계약을 사용함.
  • WOW 앱 SQLite는 레이드 도메인 데이터를 저장함. Hub 사용자·공통코드·메타 또는 다른 SQLite 파일에 DB 레벨 FK를 걸지 않음.
  • Chess SQLite는 OAuth 연결 계정, 완료 대국, 수순, Stockfish 분석, 복기 코칭 데이터를 소유하며 Hub SQLite 사용자 ID를 저장하거나 SQLite 파일 간 FK를 만들지 않음.
  • Health SQLite는 운동 기준정보, 운동 세션, 운동 기록, 운동 계획, 러닝 계획, 체중 측정, 투약 기록, 음식 기준정보와 음식 기록을 저장함.
  • 공통코드, 메타, 사용자 인증, 사용자 세션, 포털 메뉴, AI usage log는 Health SQLite 파일로 복제하지 않음.
  • 운동 종목 기준정보는 health SQLite tb_workout_exercise_m이 런타임 소스 오브 트루스이며, hub 공통코드 EXERCISE는 초기 bootstrap source로만 사용할 수 있음.
  • Message SQLite는 tb_message_log_n 발송 이력만 소유함. schedule_id, recurrence_id, recurrence_scheduled_at은 기존 이력 호환용 컬럼이며 새 일정 정의로 사용하지 않음.
  • Automation SQLite는 작업 정의·수정 이력·실행 이력 테이블을 소유함.
  • BizCard SQLite는 명함 원본 식별 정보와 인식·수정 필드를 저장함.
  • QuestLog SQLite는 사용자별 미션 설정 이력과 확정 결과 스냅샷을 저장하며 스키마는 ai-outputs/questlog/schema.sql임.
  • SipMon SQLite는 사용자 설정·주류 분류·주류·음주 세션·잔 기록을 저장함.
  • 테이블 구조와 세부 저장 계약은 각 앱 가이드가 소유함.
  • Linkding 북마크 저장은 Linkding REST API를 사용하며 Hub는 Linkding DB 파일이나 테이블에 직접 접근하지 않음.
  • DB 기반 운영 엔티티는 created_at, updated_at 같은 감사 컬럼 NOT NULL 제약을 충족하는 기본값 전략을 함께 가져야 함.
  • AI 개발 지식 캐시는 애플리케이션 런타임과 분리된 PostgreSQL vault 스키마를 사용하며 구조는 개발 환경·운영 배포 가이드를 따름.

5.3 삭제 상태와 인덱스 정책​

  • 신규 도메인과 deleted_at 계약을 가진 화면의 삭제 액션은 row를 물리 삭제하지 않고 nullable deleted_at에 삭제 시각을 저장함. 조회·수정·실행 대상은 deleted_at IS NULL로 제한함. SQLite의 삭제 시각은 KST naive datetime, PostgreSQL은 TIMESTAMPTZ를 사용함. 기존 물리 삭제 경로의 데이터 관계와 앱별 계약은 전환 전 별도로 확인함.
  • is_deleted, del_flag, del_yn 등 별도 삭제 여부 플래그를 deleted_at과 중복 저장하지 않음. 삭제 여부는 deleted_at IS NULL 또는 IS NOT NULL로 판정함.
  • is_active는 화면에서 비활성화·재활성화할 수 있는 운영 상태에만 사용하며 삭제 여부와 독립적으로 관리함. 비활성화만으로 row를 숨기거나 삭제 시각을 기록하지 않음. 삭제된 row를 기본 목록에서 제외하는 조건과 비활성 row를 목록에 포함하는 옵션은 분리함.
  • 상위 row 삭제 시 연결 데이터의 처리 범위는 앱별 계약을 따름. 도메인 기록과 참조 관계를 확인하기 전까지 삭제 표시된 row를 정기적으로 물리 삭제하는 작업을 만들지 않음.
  • deleted_at 단독 인덱스를 모든 테이블에 일괄 생성하지 않음. 사용자·상위 row·날짜·정렬 조건과 실제 데이터 규모를 기준으로 복합 인덱스 또는 WHERE deleted_at IS NULL 부분 인덱스를 선택함. 부분 고유 인덱스가 현재 유효한 row만 제한하는 경우 그 조건을 유지함.
  • 인덱스 추가·제거 전후 SQLite는 EXPLAIN QUERY PLAN, PostgreSQL은 EXPLAIN과 사용 통계로 실제 조회 경로를 확인함. 삭제 데이터의 기간별 물리 정리가 필요하고 데이터량이 충분할 때만 deleted_at 범위 인덱스를 별도로 검토함. PK·고유 제약·중복 방지 인덱스는 조회 빈도만으로 제거하지 않음.

6. 비동기 ORM 규격​

6.1 엔진과 세션​

  • create_async_engine()과 async_sessionmaker()를 사용함.
  • 의존성 주입은 async def get_session() 제너레이터 패턴을 사용함.
  • 세션 타입은 sqlalchemy.ext.asyncio.AsyncSession임.

6.2 SQLModel 사용 규칙​

  • Field(..., sa_column=Column(...)) 조합에서는 중복 옵션 선언을 피함.
  • SQLite 엔티티는 PostgreSQL schema qualifier와 PostgreSQL 전용 타입을 사용하지 않음.
  • 믹스인 컬럼 재사용으로 인한 선언 충돌을 피함.

6.3 조회 패턴​

  • AsyncSession에서는 SQLModel 동기 exec()를 사용하지 않음.
  • await session.execute(select(...)) 기반 SQLAlchemy 네이티브 패턴을 사용함.
  • 결과 해석은 scalar_one_or_none(), scalars().all(), all() 등으로 명시함.

7. 인증 및 권한 구조​

7.1 인증 책임 경계​

  • 사용자 credential 검증, JWT 발급, 공통 로그인 화면, 공통 로그아웃 API는 hub-api가 담당함.
  • 사용자 세션 정책, 사용자 세션 영속 상태, JWT 세션 유효성 판정, JWT 슬라이딩 갱신 판단은 hub-api가 담당함.
  • Hub 외 앱은 자체 /api/auth/login 또는 /api/auth/check 계열 credential 검증 API를 제공하지 않음.
  • 개별 앱은 hub-api가 발급한 JWT를 Authorization: Bearer 헤더 또는 COOKIE_NAME 기준 HttpOnly 쿠키에서 읽고, 일반 사용자 JWT의 세션 유효성 판정은 hub-api 내부 인증 API에 위임함.
  • 개별 앱은 브라우저 쿠키 기반 요청에 대해 shared-core 슬라이딩 세션 미들웨어를 등록하고, 갱신 판단과 새 토큰 발급은 hub-api 내부 인증 API에 위임함.
  • 개별 앱의 앱 셸 로그아웃 동작은 HUB_BASE_URL 기준 hub-api의 /api/auth/logout을 호출함.

7.2 공통 의존성​

  • get_current_user는 필수 인증임.
  • get_optional_user는 선택 인증임.
  • require_module(module_code)는 모듈 권한 강제 의존성임.
  • require_modules(*module_codes)는 전달된 모든 모듈 권한을 강제하는 공통 의존성임.
  • 공통 인증 의존성은 일반 사용자 JWT의 서명과 만료를 검증한 뒤 HUB_INTERNAL_BASE_URL의 POST /api/internal/auth/validate를 호출해 세션 유효성을 확인함.
  • AI 에이전트 전용 ROLE_AI JWT는 사용자 세션 테이블 검증 대상이 아니며 require_ai_role 전용 read-only API에서만 허용됨.
  • SlidingSessionMiddleware는 브라우저 쿠키 기반 interaction마다 hub 내부 인증 API를 호출해 세션 갱신 필요 여부를 확인함.
  • SlidingSessionMiddleware는 인증 실패한 토큰을 강제로 갱신하지 않으며, 만료되었거나 유효하지 않거나 hub에서 revoke된 토큰은 표준 인증 의존성과 페이지 라우터 실패 흐름이 처리함.
  • SlidingSessionMiddleware는 /api/internal/*, 정적 자산, 로그인, 로그아웃, 헬스체크, 문서 경로를 갱신 대상에서 제외함.

7.3 세션 정책​

  • 사용자 세션 만료와 슬라이딩 갱신 임계값은 hub-api 소유 정책 파일인 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를 설정함.
  • 일반 사용자 JWT는 sid claim을 포함하며, sid는 Hub SQLite tb_user_session_n.session_id와 매칭되어야 유효함.
  • hub-api는 세션 row의 is_active, revoked_at, expires_at, 사용자 is_active를 기준으로 JWT 세션 유효성을 판정함.
  • 요청 토큰의 남은 시간이 슬라이딩 갱신 임계값 이하이면 hub-api는 같은 sid를 유지하고 DB의 최신 사용자 권한을 기준으로 새 JWT를 발급하며 브라우저 쿠키를 다시 설정함.
  • 로그아웃, 사용자 비밀번호 변경, 계정 비활성화, 권한 변경, 사용자 삭제는 관련 사용자 세션을 revoke하여 기존 일반 사용자 JWT를 무효화함.
  • JWT_SECRET_KEY, 알고리즘, 쿠키 보안 옵션은 환경 설정으로 관리하고, 세션 만료와 슬라이딩 임계값은 hub 정책 YAML로 관리함.
  • HUB_INTERNAL_BASE_URL, HUB_API_INTERNAL_TOKEN, HUB_API_INTERNAL_TOKEN_HEADER는 개별 앱이 hub 내부 인증 API와 master-data API를 호출할 때 사용하는 서버 간 설정임.

7.4 권한 데이터​

  • allowed_modules는 Hub SQLite JSON 배열을 기준으로 저장됨.
  • 애플리케이션 내부에서는 list[str]로 다룸.
  • 비교와 판정은 대문자 모듈 코드 기준으로 수행함.
  • SYSTEM 값은 인증 계층에서 HUB로 정규화하여 처리함.

7.5 실패 정책​

  • HTML 페이지 요청은 리다이렉트 기반 인증 흐름을 사용함.
  • API 요청은 JSON 401/403 응답을 유지함.
  • HTML 페이지의 모듈 권한 부족은 hub-api 로그인 화면에 permission_denied=1을 전달하는 흐름으로 처리함.
  • 로그인 화면은 permission_denied=1이 있으면 권한 없음 alert를 1회 표시하고 쿼리 플래그를 제거함.
  • 앱별 권한 오류 템플릿은 사용하지 않음. /error/403 같은 하위 호환 라우트도 별도 권한 오류 페이지를 렌더링하지 않고 Hub 로그인 화면의 권한 없음 alert 흐름으로 연결함.
  • 화면과 API의 접근 제어는 앱별 권한 코드를 기준으로 하며 코드는 시스템 개요의 앱 표를 따름. 운영 관리자 영역은 HUB 권한을 사용함.
  • Health의 공유 운동 기준정보 관리 영역은 HEALTH와 HUB 권한을 모두 기준으로 접근을 제어함.
  • Automation 일반 작업 관리 API는 운영용 HUB 권한을 사용함. Message 전용 일정 API는 MESSAGE 권한과 작업 소유자 필터를 사용하며 Automation에는 별도 사용자 앱 UI가 없음.
  • 개발 모드 로그인 복귀 시 redirect는 원래 UI 앱 origin을 유지하고, hub-api는 허용 origin 검증 후 해당 UI 앱 경로로 복귀시킴.

8. 공통 마스터 데이터 구조​

8.1 현재 대상​

  • 공통코드
  • 메타
  • AI 프롬프트
  • 포털 메뉴
  • AI 라우팅

8.2 저장 방식​

  • 공통 마스터 데이터의 소스 오브 트루스는 hub-api가 관리하는 Hub SQLite /sorc001/junkbox/db/hub.sqlite3 파일임.
  • 코드 타입은 tb_code_type_c, 공통코드는 tb_common_c, 메타는 tb_meta_m, 버전별 AI 프롬프트는 tb_ai_prompt_m, 포털 메뉴는 tb_portal_menu_m을 사용함.
  • AI 라우팅 로컬 원본은 apps/hub-api/var/master-data/ai-routing.yml 계열 파일을 사용함.
  • 마스터 데이터 CRUD는 hub-api와 shared-core 저장소 계층을 통해 수행함.
  • AI 에이전트 표준 통합 snapshot API는 GET /api/v1/master/all이며 ROLE_AI JWT를 사용함.

8.3 운영 방식​

  • DB 기반 공통 마스터데이터는 hub-api가 단일 관리 주체임.
  • 화면과 API는 파일 저장소를 직접 노출하지 않고 shared-core 저장소 계층을 통해 접근함.
  • 다른 앱과 모듈은 공통코드·메타·포털 메뉴를 shared-core.masterdata.MasterDataService로 소비하고, AI 프롬프트는 shared-core.masterdata.PromptService로 소비함.
  • shared-core.masterdata.HubMasterDataClient는 HUB_INTERNAL_BASE_URL, HUB_API_INTERNAL_TOKEN, HUB_API_INTERNAL_TOKEN_HEADER로 내부 API를 호출함.
  • shared-core.masterdata.TtlAsyncCache는 코드와 메타 조회 결과를 TTL 기준으로 재사용함. PromptService는 동일 캐시를 사용하되 프롬프트 조회 TTL을 최대 15초로 제한하고 조회 실패 시 stale 값을 반환하지 않음.
  • Hub 도구의 캐시 갱신은 Hub와 소비 앱의 공통코드·메타·프롬프트 인메모리 캐시를 비우며, 각 앱은 다음 조회에서 Hub의 현재 값을 다시 가져옴. 서버 간 갱신은 내부 토큰으로 보호됨.
  • Python 서버 렌더링 문구와 React UI 문구는 각 템플릿/컴포넌트 소스에 한국어로 직접 작성함.
  • APP_PROFILE=local에서 HUB_API_INTERNAL_TOKEN이 비어 있으면 개발 편의용 local store fallback을 사용할 수 있음.
  • 운영 profile에서 HUB_API_INTERNAL_TOKEN이 비어 있으면 내부 master-data API 소비는 실패해야 하며, 조용히 로컬 DB 조회로 전환하지 않음.
  • AI 코딩은 scripts/fetch_master_data.py 실행 결과인 통합 snapshot을 우선 사용함.
  • AI가 대량 문맥을 확보할 때는 FASTAPI_BASE_URL/api/v1/master/all 결과를 기준으로 함.
  • AI 라우팅 정책 파일은 Git 형상관리 원본을 apps/hub-api/var/master-data에 두고, 운영 배포 시 /sorc001/junkbox/master-data/ai-routing.yml로 동기화한 뒤 hub-api, bizcard-api 컨테이너가 공통 볼륨으로 공유함.

9. 관련 문서​

  • 앱 목록과 앱 간 연동, 문서 체계는 docs/junkbox/common/guide-jb-overview.md를 따름.
  • 설정, 로컬 개발, 신규 앱 생성, 운영 배포는 docs/junkbox/common/guide-jb-dev-ops.md를 따름.
  • 공통 마스터 데이터 규칙은 docs/junkbox/common/guide-jb-common-master-data.md를 따름.
  • 공통 UI 원칙과 운영 화면 시각 규칙은 docs/junkbox/common/guide-jb-common-ui.md를 단일 기준으로 따름.
  • 공통 라이브러리 구조는 docs/junkbox/libs/의 각 가이드를 따름.
  • 앱별 구조는 docs/junkbox/apps/의 각 가이드를 따름.