JunkBox 공통 마스터 데이터 가이드
1. 문서 목적
- 이 문서는 JunkBox에서 코드·메타·AI 프롬프트 정보를 AI와 사람이 동일한 기준으로 조회하고 변경하기 위한 공통 규칙 문서임.
- 기준 데이터의 Source of Truth는 JunkBox
hub-api와 Hub SQLite/sorc001/junkbox/db/hub.sqlite3파일임. - AI 코딩 시 코드/메타 마스터데이터를 추정하거나 하드코딩하지 않고, 항상 현재 DB 상태를 조회한 뒤 구현하도록 강제하는 것이 목적임.
2. 적용 범위
- 공통코드
- 코드 타입 메타
- 메타 정보
- AI 프롬프트와 버전 이력
- 포털 메뉴
- 이 문서는 JunkBox 전체 공통 규칙(Global Rule)이며 모든 앱 모듈이 공유함.
3. 핵심 원칙
3.1 Source of Truth 원칙
- 공통 마스터데이터의 단일 관리 주체는
apps/hub-api임. - 실제 저장 원본은 Hub SQLite
/sorc001/junkbox/db/hub.sqlite3파일임. - 다른 앱이나 모듈은 공통 마스터데이터를 자체 파일, 상수, 별도 테이블로 중복 소유하지 않음.
3.2 AI 조회 우선 원칙
- AI는 기능 개발 또는 설정 추가 전에 반드시 현재 마스터데이터를 먼저 조회함.
- 조회 없이 코드/메타 값을 추정해서 새 값을 만들거나 하드코딩하지 않음.
- 조회 결과를 기준으로 기존 코드·메타 식별자를 재사용함.
3.3 변경 범위
- 현재 마스터데이터와의 중복을 피하도록 3.4절의 논리 식별자를 기준으로 필요한 변경분을 정함.
3.4 계약 유지 원칙
- API 응답과 저장소 계약 필드는
snake_case를 유지함. - 메타는
meta_key, 프롬프트는prompt_key와version, 공통코드는code_type_code + common_code조합을 논리 식별자로 사용함. - 사용자가 화면에서 보는 일반 텍스트는 소스 코드에 한국어 문구로 직접 작성함.
- 공통코드 라벨, 메타 설정값처럼 데이터 자체가 DB 마스터데이터인 값은 현재 코드/메타 구조를 사용함.
- 텍스트만을 위해 DB 메시지 마스터, 메시지 코드, 메시지 조회 유틸을 새로 만들지 않음.
3.5 AI 개발 지식 캐시와의 경계
- 공통 마스터데이터의 Source of Truth는
hub-api가 관리하는 Hub SQLite/sorc001/junkbox/db/hub.sqlite3파일임. - 개발 구조 가이드 문서의 Source of Truth는 Git으로 관리되는
vault/docs/junkbox/**/*.md파일임. vault스키마의 문서 벡터 테이블은vault/docs/**/*.md파일을 AI 검색용으로 색인한 벡터 캐시이며 공통 마스터데이터 원본이 아님.- 마스터데이터 변경에는 7절의 저장·검증 규칙을 적용함.
- 개발 문서 변경은
vault/docs/junkbox/**/*.md파일을 직접 수정한 뒤 Git 검증과 개발 문서 벡터 캐시 동기화 흐름을 따름. - AI 에이전트의 표준 마스터데이터 조회 경로는
scripts/fetch_master_data.py가 호출하는 JWT 기반 통합 snapshot API임. - 개발 문서 검색은
vault.docs,vault.doc_chunks,vault.doc_embeddings와 개발 문서 검색 스크립트 흐름을 사용함.
4. 조회 API와 소비 구조
4.1 라우터 진입점
apps/hub-api/src/junkbox_hub_api/main.py에서 마스터데이터 라우터가 다음 prefix로 등록되어 있음.- 공통코드:
/api/hub - 메타·AI 프롬프트:
/api/hub - 내부 소비용:
/api/internal/master-data - AI 에이전트 표준 조회용:
/api/v1/master
4.2 공개 조회 엔드포인트
- 코드 타입 목록 조회:
GET /api/hub/codes/types - 코드 타입 메타 조회:
GET /api/hub/codes/types/{code_type_code}/meta - 코드 목록 조회:
GET /api/hub/codes/{code_type_code} - 코드 전체 조회:
GET /api/hub/codes/{code_type_code}/all - 메타 목록 조회:
GET /api/hub/metas - 메타 점진 조회:
GET /api/hub/metas/progressive - 메타 단건 조회:
GET /api/hub/metas/{meta_id} - 메타 키 조회:
GET /api/hub/metas/by-key/{meta_key} - AI 프롬프트 현재 버전 목록:
GET /api/hub/prompts - AI 프롬프트 현재 버전 단건:
GET /api/hub/prompts/by-key/{prompt_key} - AI 프롬프트 버전 이력:
GET /api/hub/prompts/{prompt_key}/versions
4.3 내부 소비용 조회 엔드포인트
- 코드 타입 전체:
GET /api/internal/master-data/codes/{code_type_code} - 메타 키 조회:
GET /api/internal/master-data/metas/by-key/{meta_key} - 활성 AI 프롬프트 현재 버전 조회:
GET /api/internal/master-data/prompts/by-key/{prompt_key} - active 포털 메뉴 목록 조회:
GET /api/internal/master-data/portal-menus - AI usage log 기록:
POST /api/internal/master-data/ai-usage-logs
4.4 AI 에이전트 표준 조회 엔드포인트
- 표준 통합 snapshot 조회:
GET /api/v1/master/all - 인증은
Authorization: Bearer {AI_ACCESS_TOKEN}형식의 JWT를 사용함. - JWT payload는
sub=JUNKBOX_AI_AGENT,role=ROLE_AI구조를 기준으로 함. - AI 전용 JWT는 만료 클레임을 포함하지 않는 장기 로컬 자격 증명으로 관리함.
ROLE_AI토큰은 표준 통합 snapshot API에만 사용하며, 일반api/hub비즈니스 API 접근은 권한 의존성 단계에서 차단됨.- 통합 snapshot 응답은
exported_at,code_types,codes,metas,prompts를 하나의 JSON 객체로 반환함.
4.5 인증 구조
api/hub계열 조회 API는require_module("HUB")를 사용하므로 JWT 인증과HUB모듈 권한이 필요함.api/internal/master-data계열 조회 API는HUB_API_INTERNAL_TOKEN_HEADER+HUB_API_INTERNAL_TOKEN검증을 사용함.- AI usage log 기록 API도 같은 서버 간 토큰을 검증하며, Hub만 Hub SQLite
tb_ai_usage_logs_n에 저장함. api/v1/master계열 조회 API는ROLE_AIJWT 검증을 사용함.
4.6 앱 런타임 소비 구조
- Hub 외 앱은
shared-core.masterdata.MasterDataService를 통해 공통 master-data를 소비함. - AI 기능을 사용하는 앱은
shared-ai의 Hub API usage-log writer를 통해 AI 사용 이력을 전달하며 Hub SQLite 파일을 직접 열지 않음. MasterDataService는HubMasterDataClient와TtlAsyncCache를 조합하여 코드 목록, 메타 값, active 포털 메뉴 목록을 조회함.- AI 프롬프트는
shared-core.masterdata.PromptService가HubMasterDataClient.get_prompt()의 내부 API를 통해 조회함. Hub 프로세스는 같은 서비스에PromptStoreloader를 주입해 자체 DB를 조회함. - Hub 도구의
POST /api/hub/tools/master-data/refresh는 Hub와 등록된 소비 앱의 인메모리 캐시를 갱신하고 앱별 성공·실패를 반환함. 소비 앱은POST /api/internal/master-data/cache/refresh를 서버 간 내부 토큰으로 보호하며, 공통코드·메타·AI 프롬프트 캐시를 비운 뒤 다음 조회에서 현재 값을 가져옴. - 서버 앱 셸의 브랜드 설명은 Hub 포털 메뉴의
description을 사용함.is_desc_visible이 거짓이거나 설명이 비어 있거나 조회에 실패하면 설명 요소를 표시하지 않음. - 앱별 favicon 또는 PWA icon slug는 포털 메뉴의
menu_type_code=APP,icon_type_code=APP_ICON,icon_val조합에서 해석할 수 있음. APP_ICON의icon_val은shared-ui앱 아이콘 asset slug이며, 포털 카드 아이콘과 앱 favicon/PWA 아이콘을 같은 관리 값으로 묶음.- 소비 앱은
HUB_API_INTERNAL_TOKEN이 설정된 경우HUB_INTERNAL_BASE_URL의hub-api내부 master-data API를 호출함. HUB_INTERNAL_BASE_URL은 소비 앱 실행 위치에서 접근 가능한hub-api주소와 포트를 가리켜야 함.- Python 서버 렌더링 문구는 템플릿 또는 라우터 컨텍스트에 한국어 문구로 직접 작성함.
- React 화면 문구는 컴포넌트 코드에 한국어 문구로 직접 작성함.
- 운영 profile에서
HUB_API_INTERNAL_TOKEN이 비어 있으면 내부 master-data 소비는 실패함. APP_PROFILE=local에서HUB_API_INTERNAL_TOKEN이 비어 있으면 개발 편의용 local store fallback을 사용할 수 있음.
5. AI 전용 조회 규칙
5.1 표준 인증 입력값
- AI가 마스터데이터를 읽기 위해 사용하는 표준 자격 정보는
scripts/.env.ai의AI_ACCESS_TOKEN임. AI_ACCESS_TOKEN은ROLE_AIrole을 가진 장기 JWT 값임.FASTAPI_BASE_URL은scripts/fetch_master_data.py가 호출할 hub-api base URL임.- 로컬 개발 예시는
http://localhost:18001이며, 운영 배포 후 운영 주소를 사용할 수 있음. scripts/.env.ai는 Git 추적 대상이 아닌 작업자별 비밀 설정 파일임.scripts/.env.ai.template은 공유 가능한 설정 키 예시를 제공함.
5.2 조회 경로 구분
- AI 기본 경로는
scripts/fetch_master_data.py를 통한GET /api/v1/master/all통합 snapshot 조회임. - AI는 DB에 직접 접속하지 않으며 hub-api를 단일 진실 공급원으로 사용함.
- 필요 시 아래 보조 경로도 함께 사용할 수 있음.
- 사람/관리자 컨텍스트:
JWT + require_module("HUB")가 걸린/api/hub/*조회 API 사용 - 서비스 간 내부 컨텍스트:
HUB_API_INTERNAL_TOKEN_HEADER가 필요한/api/internal/master-data/*사용
5.3 AI 조회 기본 순서
- 작업 범위가 코드인지, 메타인지 식별함.
uv run python scripts/fetch_master_data.py로 통합 snapshot을 조회함.- snapshot의
code_types,codes,metas,prompts를 기준으로 현재 등록 상태를 확인함. - 기존 값 재사용 여부와 신규 키 필요 여부를 판단함.
- 소스 구현을 진행함.
- 변경이 필요하면 SQL 파일을 생성함.
6. AI 조회 절차 상세
6.1 텍스트와 마스터데이터 경계
- 화면 문구, 에러 문구, 피드백 문구, Discord interaction label처럼 사용자가 직접 보는 일반 텍스트는 DB 마스터데이터 조회 대상이 아님.
- 일반 텍스트는 각 화면과 서비스 코드에 한국어 문구로 직접 작성함.
- 통일이 필요한 표현은 DB 메시지 키가 아니라 공통 UI 가이드와 현재 화면 문구를 기준으로 맞춤.
- 로그, 콘솔 출력, 주석, 개발자 디버그 문자열은 사용자 UI 텍스트 기준에 포함하지 않음.
6.2 메타 조회
-
메타 전체 파악은 통합 snapshot의
metas배열을 우선 사용함. -
특정 설정 키 확인도 snapshot의
meta_key기준 검색을 우선 사용함. -
운영 설정 문자열과 비프롬프트 장문 값은 메타 계약을 검토함. AI 시스템 프롬프트와 사용자 템플릿은
tb_ai_prompt_m및 snapshot의prompts배열에서prompt_key로 확인함. -
health 앱의 운동 계획 생성은 AI 프롬프트 저장소를 사용하지 않음.
-
health 앱의 운동 계획 생성은
health-api규칙 엔진이 Health SQLite 운동 기준정보와 운동 기록을 기준으로 수행함. -
WORKOUT_COACH_INSTRUCTION,WORKOUT_COACH_USER_TEMPLATE는 AI 프롬프트 저장소의 키이며 현재 health 규칙 엔진 런타임 계약에는 포함되지 않음. -
EXCHANGE_RATE메타는 1달러당 원화 환율을 나타내며meta_val에는 숫자 문자열만 저장하는 전제를 사용함. -
화면에서 USD 기준 금액을 원화로 표시해야 할 때는
EXCHANGE_RATE.meta_val을 숫자로 해석해 곱함. -
HEALTH_REPORT_ANALYSIS_DEFAULTS는 주간 리포트 조회 범위 기본값을 JSON으로 관리함. 운동별 조회 회차, 근력 최대 조회 주 수, 체중 조회 주 수에 사용자 설정이 없으면 각 기본값을 사용함. -
HEALTH_DAILY_CALORIE_TARGET_KCAL메타는 QuestLog 사용자의 일일 열량 목표가 처음 만들어질 때 한 번 읽는 최초 목표값(kcal)임. 활성이고 QuestLog 허용 범위(500~10000) 안의 정수일 때만 쓰고, 읽지 못하거나 범위를 벗어나면 QuestLog 기본값 1850을 사용함. 이후 목표는 사용자별 QuestLog 설정이 유일한 원천이며 메타를 바꿔도 기존 사용자에게는 영향이 없음. Hub 대시보드는 이 메타를 직접 읽지 않음. -
HEALTH_WEEKLY_CALORIE_AVG_TARGET_KCAL메타는 QuestLog주간 평균 열량미션의 하루 평균 목표(kcal)가 처음 만들어질 때 한 번 읽는 최초 목표값이며 일일 목표 메타와 독립적으로 관리함. 읽는 규칙(활성·허용 범위 500~10000·기본값 1850)과 이후 사용자별 설정이 유일한 원천이라는 점은 일일 목표 메타와 같음. 커스텀 미션은 목표를 사용자가 직접 입력하므로 메타를 사용하지 않음. -
HUB_AUDIOBOOK_MONTHLY_CHAR_LIMIT,HUB_AUDIOBOOK_PREVIEW_SECONDS,HUB_AUDIOBOOK_DEFAULT_VOICE메타는 Hub EPUB 오디오북 변환의 월 과금 문자 수 상한(기본 900000), 미리듣기 길이(초, 60~600, 기본 180), 화면 기본 음성(기본Gacrux)임. 요청마다 읽으며 행이 없거나 비활성이거나 범위를 벗어나면 코드 기본값을 사용함. 상세는apps/guide-apps-hub-api.md7.10절을 따름.
6.3 공통코드 조회
조회 방식
- 공통코드 조회는 통합 snapshot의
code_types와codes객체를 우선 사용함. - 필요한 타입은
code_types에서 확인하고, 해당 타입의 실제 코드는codes[code_type_code]에서 읽음. - 관리자 화면 기준의 추가 속성 검토가 필요하면 보조적으로
GET /api/hub/codes/types/{code_type_code}/meta를 사용함.
AI 모델과 비용
- AI 모델 등록과 입력·출력 단가는 LiteLLM에서 단일 관리함. Hub에는
AI_MODEL공통코드·코드 타입·속성 설정이나 별도의 모델·단가 관리 테이블을 두지 않음. - LiteLLM API의
input_cost_per_token,output_cost_per_token은 USD/1토큰 기준임. 100만 토큰 기준 단가를 이관할 때는 1,000,000으로 나눠 적용함. shared-ai는 LiteLLM 응답의usage에서 토큰을 읽고,x-litellm-response-cost헤더의 USD 비용을 사용 로그에 저장함. Hub 공통코드 조회나 자체 단가 계산은 수행하지 않음.- 로그의
full_model_id는 라우팅 YAML의provider:model조합임.litellm:접두어는AiRouteConfig.full_model_id가 자동으로 구성하며 공통코드에 수동 등록하지 않음. 예시는litellm:openrouter/deepseek/deepseek-v4.1-flash임. - 비용을 얻지 못하면
est_cost=NULL로 저장하고, 명시적인 비용0과 구분함. 예상 비용은 최종 공급자 청구 금액을 확정하는 값이 아님. - 모델 사용 여부는 현재 앱 호출 경로와 라우팅 설정을 기준으로 판단함. 과거
tb_ai_usage_logs_n의 모델명은 현재 LiteLLM 모델 등록 여부와 별개이며, 로그는 자체full_model_id와est_cost를 저장해 과거 사용량과 비용을 보존함. 모델·단가 변경이나 기준정보 삭제를 이유로 과거 로그를 재계산하거나 수정하지 않음.
Health 코드 타입
WORKOUT_ROUTINE_MODE공통코드는 운동 계획 생성 시 사용자가 선택하는 루틴 구분의 소스 오브 트루스임.- health 운동 계획 화면은
WORKOUT_ROUTINE_MODE활성 공통코드 라벨을 조회해 모바일 하단 선택 시트 option으로 표시하며, 화면 문구 자체는 메시지 마스터데이터로 관리하지 않음. - health 규칙 엔진은
UPPER,LOWER를 명시 계산 대상으로 사용함. WORKOUT_ROUTINE_MODE에 그 밖의 활성 코드가 남아 있으면 화면 option에는 표시될 수 있으나, health 규칙 엔진은 알 수 없는 루틴 모드를 상체 루틴으로 정규화함.BODY_PART공통코드는 health 운동 기준정보와 운동 선택 필터가 사용하는 운동 부위의 소스 오브 트루스임.WORKOUT_STATUS공통코드는 health 세트 상태의 소스 오브 트루스임.RUNNING_STEP공통코드는 health 러닝 단계 유형의 소스 오브 트루스임.RUNNING_STEP.common_code는 러닝 단계의activity_type_code로 저장됨.RUNNING_STEP.common_code_name은 러닝 계획 편집 화면, 러닝 실행 화면, 음성 안내 문구의 단계 유형 표시명으로 사용됨.RUNNING_STEP.sort_order_no는 러닝 단계 유형 선택 목록의 정렬 기준임.- 러닝 단계 이름은 별도 텍스트 마스터나 SQLite 컬럼으로 관리하지 않으며
RUNNING_STEP라벨을 기준으로 표시함. - health 운동 종목 기준정보의 런타임 소스 오브 트루스는 health SQLite
tb_workout_exercise_m임. EXERCISE공통코드는 health 운동 기준정보 테이블을 초기 bootstrap할 때 사용할 수 있는 이관 source임.EXERCISE.common_code는 bootstrap 시exercise_code,common_code_name은exercise_name,common_code_desc는exercise_desc,parent_common_code는body_part_code로 매핑함.EXERCISE.attribute01은 bootstrap 시weight_step_kg,attribute02는min_weight_kg,attribute03은max_weight_kg로 매핑함.- health 운동 관리 화면에서 생성·수정되는 운동 기준정보는 hub 공통코드
EXERCISE를 직접 변경하지 않음.
Hub 대시보드 코드 타입
DASHBOARD_STOCK_DOMESTIC공통코드는 hub 대시보드 국내 주식 관심 목록의 소스 오브 트루스임.DASHBOARD_STOCK_OVERSEAS공통코드는 hub 대시보드 해외 주식 관심 목록의 소스 오브 트루스임.DASHBOARD_FUND공통코드는 hub 대시보드 펀드 관심 목록의 소스 오브 트루스임.DASHBOARD_STOCK_DOMESTIC,DASHBOARD_STOCK_OVERSEAS,DASHBOARD_FUND의common_code는 외부 조회 식별자,common_code_name은 사용자 표시명으로 사용함.DASHBOARD_STOCK_DOMESTIC.attribute01과DASHBOARD_STOCK_OVERSEAS.attribute01은 투자 항목 종류이며STOCK,INDEX값을 사용함.DASHBOARD_STOCK_DOMESTIC.attribute02,DASHBOARD_STOCK_OVERSEAS.attribute02,DASHBOARD_FUND.attribute02는 상세 URL로 사용함.DASHBOARD_STOCK_DOMESTIC.attribute03,DASHBOARD_STOCK_OVERSEAS.attribute03,DASHBOARD_FUND.attribute01,DASHBOARD_FUND.attribute03은 현재 대시보드 수집 로직에서 사용하지 않음.DASHBOARD_STOCK_DOMESTIC.common_code는attribute01=STOCK이면 네이버 국내 주식 API의 6자리 종목코드,attribute01=INDEX이면 네이버 국내 지수 API의 지수 코드이며 코스피는KOSPI형식을 사용함.DASHBOARD_STOCK_OVERSEAS.common_code는attribute01=STOCK이면 네이버 해외 주식 API의 Reuters code이며NVDA.O,GOOGL.O같은 형식을 사용하고,attribute01=INDEX이면 네이버 해외 지수 API의 지수 Reuters code이며 S&P 500은.INX형식을 사용함.DASHBOARD_FUND.common_code는 FunETF 펀드 코드이며 provider는 마스터데이터 속성값이 아니라 hub 대시보드 펀드 수집기에서FUNETF로 고정함.- 대시보드 투자 관심 목록의 표시 순서는 공통코드
sort_order_no를 기준으로 함.
Message 코드 타입
MESSAGE_SOURCE공통코드는 Message 앱의 발송 출처 선택지와 메시지 이력source값의 소스 오브 트루스임.- 활성 코드
BACKUP,HEALTH,ETC,WOW를 사용함.BACKUP,HEALTH,WOW는 코드와 코드명이 같은 영문 대문자이며ETC의 코드명은기타임.WOW는 WoW 앱의 발송 출처임. MESSAGE_TYPE공통코드는 Message 요청과 이력의message_type_code소스 오브 트루스임. 활성 코드는INFO,SUCCESS,WARNING,FAILURE이며 표시명은 각각정보,성공,경고,실패임.MESSAGE_REQUEST_METHOD공통코드는 Message 이력의request_method_code소스 오브 트루스임. 활성 코드는API,SCHEDULE,RECURRENCE,MANUAL_RESEND이며 표시명은 각각즉시,예약,정기,API임.- Message UI는 Hub SQLite를 직접 읽지 않고 Message API
GET /api/message/meta/sources,GET /api/message/meta/message-types,GET /api/message/meta/request-methods를 통해 활성 공통코드를 조회함. Message API는MasterDataService를 통해 Hub 내부 master-data API를 소비함.
Raid·BizCard 코드 타입
RAID_MEMBER_CATEGORY공통코드는 Raid 공대원 풀의 구분 소스 오브 트루스임. 활성 코드는SELF(나),TRACKING(추적),RAID_MEMBER(공대원)이며sort_order_no는 각각1,2,3임.- Raid 목록과 관리 화면은
RAID_MEMBER_CATEGORY의 활성 코드와sort_order_no를 그대로 사용하며, 라벨을 별도 화면 상수로 중복 관리하지 않음. BIZCARD_CATEGORY(코드 타입 표시명명함 분류) 공통코드는 BizCard 명함에 해시태그처럼 여러 개 지정하는 분류의 소스 오브 트루스임. 활성 코드는CUSTOMER(고객),PARTNER(협력사)이며sort_order_no는 각각1,2임. 추가 분류는 Hub 공통코드 화면에서 등록함.- BizCard API는
MasterDataService로BIZCARD_CATEGORY를 조회해GET /api/bizcard/categories로 제공하고, 명함과의 연결(tb_bizcard_card_category_r.category_code)만 자체 SQLite에 저장함. 비활성 코드는 이미 지정된 분류의 표시와 삭제에만 쓰이고 새로 지정할 수 없음. 공통코드 캐시 TTL(codes_ttl_seconds, 기본 300초) 때문에 Hub의 분류 변경은 BizCard에 최대 그 시간만큼 늦게 반영됨.
6.4 조회 결과 활용 규칙
- AI는 조회 결과를 기준으로 기존 식별자를 재사용해야 하며, 비슷한 의미의 신규 키를 임의 생성하지 않음.
- 같은 의미의 코드와 메타를 화면별로 중복 생성하지 않음.
- 기존 키가 있으면 해당 키와 값을 재사용하고, 값 변경이 필요하면 같은 키에 반영함.
7. 변경 규칙
7.1 Hub SQLite 반영과 검증
- Hub SQLite 마스터데이터는 변경 대상 DB 파일과 테이블·컬럼을 먼저 확인함.
- 반영 후
PRAGMA table_info(...)와 대상 코드·메타 조회로 스키마와 적용 결과를 검증함.
7.2 SQL 파일 위치와 이름
- 프로젝트는 Flyway·Alembic 같은 마이그레이션 도구를 사용하지 않음.
- 수동 반영용 마스터데이터 SQL의 위치는
junkbox/AGENTS.md의마스터데이터와 DB 변경절을 따름. - 필요한 SQL 산출물은 사용자가 검토한 뒤 별도 운영 절차로 적용함.
- 파일명 규칙은
{권장파일명}_{yyyymmddhh24miss}.sql형식을 사용함. - 권장 접두사는
masterdata로 고정함. - 예시:
ai-outputs/masterdata_add_user_menu_codes_20260517144251.sql
ai-outputs/masterdata_add_ai_prompts_20260517144510.sql
ai-outputs/masterdata_add_workout_status_codes_20260517144733.sql
7.3 SQL 작성 원칙
- DB는 Hub SQLite를 사용함.
- 공통코드와 메타의 중복 반영 방지를 위해 SQLite
INSERT ... ON CONFLICT DO UPDATE기반 UPSERT를 사용함. - 수동 SQL에서도 감사 일시를 KST로 설정함. 현재 일시를 쓸 때는
datetime('now', '+9 hours')를 명시해 기존 테이블에 남은 DB 기본값이나 실행 환경 시간대에 의존하지 않음. - AI 프롬프트는
(prompt_key, version)고유성을 유지하고 새 본문·설명 저장 시 다음 버전을 생성함. 현재 버전 선택과 활성 상태 변경은PromptStore계약을 따름. - 논리 식별자 충돌 기준은 다음을 우선 사용함.
- 메타:
meta_key - 공통코드:
(code_type_code, common_code) - 코드 타입:
code_type_code - 삭제가 필요하면 하드 삭제보다
is_active=false비활성화를 우선 검토함.
7.4 SQL 작성 예시 원칙
INSERT INTO tb_meta_m (
meta_key,
meta_val,
description,
is_active,
created_by,
updated_by,
created_at,
updated_at
) VALUES (
'EXAMPLE_SETTING',
'example',
'예시 설정값',
1,
'ai_masterdata',
'ai_masterdata',
datetime('now', '+9 hours'),
datetime('now', '+9 hours')
)
ON CONFLICT (meta_key)
DO UPDATE SET
meta_val = EXCLUDED.meta_val,
description = EXCLUDED.description,
is_active = EXCLUDED.is_active,
updated_by = EXCLUDED.updated_by,
updated_at = EXCLUDED.updated_at;
8. 식별자 및 데이터 설계 규칙
8.1 텍스트 표현
- 일반 UI 문구는
message_code를 만들지 않고 한국어 문구를 소스에 직접 작성함. - 공통 버튼, 공통 상태, 공통 빈값 문구는 현재 화면에서 쓰는 표현을 우선 맞춤.
- 문장형 메시지는 하십시오체와 마침표 규칙을 지킴.
- 기능명이나 화면명을 과도하게 붙여 비슷한 표현을 중복 확산하지 않음.
8.2 메타
meta_key는 설정 키 성격을 명확히 드러내는 대문자 스네이크 케이스를 우선 사용함.- 비프롬프트 장문 설정값과 운영 제어값은 메타에 두는 것을 우선 검토함.
8.3 AI 프롬프트
- 앱·공통 라이브러리가 LLM에 전달하는 모든 시스템 지침, 사용자 템플릿, 추가 지침은 Hub SQLite
tb_ai_prompt_m의prompt_key,version,is_current,is_active로 관리함. Hub AI 프롬프트 메뉴는 업무·공통 지침을 동일하게 조회·수정·활성화함. - 업무 지침뿐 아니라 JSON 출력 강제, 스키마 fallback, 구조화 응답 재생성 지침도 DB 관리 대상임. 소스 상수·문자열 추가·Markdown·YAML·환경변수에 런타임 지침 본문이나 대체본을 두지 않음. 스킬과 에이전트 개발 지침은 별도 관리 대상임.
PromptService는 활성 현재 버전을 조회하고${변수명}템플릿에 실행 데이터를 주입함. 템플릿 변수 계약은 해당 키의 설명에 명시하며, 값은 재귀 렌더링하지 않음. 누락·비활성·조회 실패는 오류로 처리함.- 모델의 행동을 지시하는 자연어는 DB가 소유함. 실행 입력, JSON 직렬화, 구조적 응답 스키마, 서버 검증은 코드가 소유하며 자연어 지침을 스키마 설명에 숨기지 않음.
- 본문과 설명의 수정은 새 버전을 생성하고 이전 버전을 보존함. 프롬프트 변경은
PromptService캐시 정책에 따라 반영하며 조회·캐시 구조는 코어 가이드 8.3절을 따름.
8.4 공통코드
- 코드 타입은 도메인 분류이며, 실제 값은 해당 타입 하위 코드로 관리함.
- 코드 타입과 실제 코드를 같은 레벨에서 혼용하지 않음.
- 코드 타입 식별자는 대문자 스네이크 케이스를 사용함.
MESSAGE_SOURCE처럼 도메인과 역할을 함께 드러내는 이름을 사용함. - 공통코드 UI 표시 라벨은
common_code_name, 설명은common_code_desc를 우선 사용함. - 코드 타입 UI 표시 라벨은
code_type_code_name, 설명은code_type_code_desc를 우선 사용함. - 순서가 사용자 경험에 직접 영향을 주는 공통코드는
sort_order_no를 정렬 기준으로 사용함.
8.5 포털 메뉴
- 포털 메뉴는 Hub SQLite
tb_portal_menu_m을 소스 오브 트루스로 사용함. - 앱 메뉴는
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 설치 아이콘을 같은 앱 아이콘 세트로 연결하는 관리 계약임.- APP/하위 호환 PROJECT 메뉴의
description과is_desc_visible은 포털 카드와 해당 앱의 상단 브랜드 설명에 공통으로 적용됨. 앱 셸은 포털 메뉴의 활성 행을 조회하며 자체 설명 문구를 별도로 소유하지 않음. - 신규 앱 포털 메뉴를 추가하기 전에는 통합 snapshot과 현재 포털 메뉴를 조회하여 기존 URL, 표시 순서, 아이콘 slug, 운영 포트 배정을 확인함.
- 신규 앱은 임의의 다음 포트 번호나 유사한 메뉴 키를 추정하지 않으며, 현재 등록값과 충돌하지 않는 URL·포트·식별자를 선택함.
- 신규 웹앱의 Portal APP 메뉴 등록 범위는
common/guide-jb-dev-ops.md4.4절을 따름. - 대상 Hub SQLite 파일과
tb_portal_menu_m의 실제 컬럼·현재 메뉴를 먼저 확인하고, 앱 목적에 맞는menu_name,menu_type_code=APP,icon_type_code=APP_ICON, 해당 앱의 shared-ui 아이콘 slugicon_val, 승인된 운영 URLmenu_url, 개발 UI URLlocal_menu_url, 기존 순서와 조화되는sort_order_no,is_active를 설정함.description·is_desc_visible도 기존 Portal 관례와 사용자 요청에 맞춤.
- Portal의
menu_name은Health,Track,SipMon처럼 짧은 앱 이름으로 관리함.- Hub 이외 웹앱의 공통 상단
brand_title및app_name은 이를 기준으로JunkBox {menu_name}형식과 동일한 대소문자를 사용함. - 이미 있는
JunkBox접두어를 중복하지 않으며 신규 앱 등록·앱 이름 변경 시 소스의 상단 이름과 Portal 이름을 함께 맞추고 렌더링 결과를 확인함. - 이 규칙을 이유로 Portal 메뉴 이름 자체에 접두어를 붙이거나 Hub·화면별 제목·PWA 표시명을 일괄 변경하지 않음.
- Hub 이외 웹앱의 공통 상단
- 전용 아이콘 자산이 없으면 기존 shared-ui 아이콘 체계에 적합한 아이콘 세트를 추가하며, Portal 카드·favicon·PWA를 같은 slug로 연결함. 기존 앱 메뉴의 명확한 식별자를 재사용해 중복 없이 등록·갱신하고 무관한 메뉴·순서는 보존함. 스키마·반영 결과와 실제 Portal의 앱 이름·아이콘·순서·링크·앱 진입을 확인함.
9. AI 작업 지침
- 마스터데이터 사전 조회와 DB 적용 방식은
junkbox/AGENTS.md의마스터데이터와 DB 변경절을 따름.
10. 통합 snapshot 사용
- AI 에이전트는
scripts/fetch_master_data.py실행 한 번으로 마스터데이터 전체 문맥을 확보함. 단건 확인과 대량 문맥 수집 모두 통합 snapshot을 우선 사용함. - 여러 화면과 모듈을 함께 다루는 작업에서 개별 API를 여러 번 호출하는 방식보다 효율적이며, 중복 키 생성과 누락 판단을 줄이는 것이 목적임.
- 개별 read-only API는 세부 확인이나 수동 확인 용도로만 사용함.
- 실행 명령은 다음과 같음.
uv run python scripts/fetch_master_data.py
- 이 스크립트는
FASTAPI_BASE_URL/api/v1/master/all을 호출함. - 응답 예시:
{
"exported_at": "2026-05-17T14:42:51+09:00",
"code_types": [],
"codes": {
"MENU_TYPE": []
},
"metas": []
}
11. 환경 변수 기준
scripts/.env.ai에는 최소한 아래 값을 준비해야 함.FASTAPI_BASE_URLAI_ACCESS_TOKEN- 개발 문서 벡터 캐시 동기화와 검색을 함께 사용할 때는 아래 값도 같은 파일에 준비함.
VAULT_DATABASE_URLAI_EMBEDDING_API_KEYAI_EMBEDDING_BASE_URLVAULT_EMBEDDING_MODEL
12. 관련 파일
- 라우터 등록:
apps/hub-api/src/junkbox_hub_api/main.py - 코드 API:
apps/hub-api/src/junkbox_hub_api/api/v1/codes.py - 메타 API:
apps/hub-api/src/junkbox_hub_api/api/v1/metas.py - AI 전용 마스터데이터 API:
apps/hub-api/src/junkbox_hub_api/api/v1/ai_masterdata.py - 내부 마스터데이터 API:
apps/hub-api/src/junkbox_hub_api/api/v1/internal_masterdata.py - 권한 의존성:
libs/shared-core/src/junkbox_shared_core/security/dependencies.py - AI 에이전트 조회 스크립트:
scripts/fetch_master_data.py - AI 에이전트 환경 변수 예시:
scripts/.env.ai.template
13. 관련 문서
- 시스템 구조는
docs/junkbox/common/guide-jb-overview.md, 공통 원칙은docs/junkbox/common/guide-jb-core.md를 따름. - 공통 저장소 구조는
docs/junkbox/libs/guide-lib-shared-core.md를 따름. hub-api상세는docs/junkbox/apps/guide-apps-hub-api.md를 따름.