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을 거치지 않는 호출은 사용자가 허가 예외로 정한 경우만 허용하며 이 절의 허가 예외 목록에 대상과 사유를 등록함. 목록에 없는 직접 호출은 위반임.
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')를 사용함.
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 함수를 사용함.
신규 도메인과 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·고유 제약·중복 방지 인덱스는 조회 빈도만으로 제거하지 않음.
화면과 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 컨테이너가 공통 볼륨으로 공유함.