Skip to main content

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_AI JWT 검증을 사용함.

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 프로세스는 같은 서비스에 PromptStore loader를 주입해 자체 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_AI role을 가진 장기 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 조회 기본 순서​

  1. 작업 범위가 코드인지, 메타인지 식별함.
  2. uv run python scripts/fetch_master_data.py로 통합 snapshot을 조회함.
  3. snapshot의 code_types, codes, metas, prompts를 기준으로 현재 등록 상태를 확인함.
  4. 기존 값 재사용 여부와 신규 키 필요 여부를 판단함.
  5. 소스 구현을 진행함.
  6. 변경이 필요하면 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.md 7.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.md 4.4절을 따름.
  • 대상 Hub SQLite 파일과 tb_portal_menu_m의 실제 컬럼·현재 메뉴를 먼저 확인하고, 앱 목적에 맞는 menu_name, menu_type_code=APP, icon_type_code=APP_ICON, 해당 앱의 shared-ui 아이콘 slug icon_val, 승인된 운영 URL menu_url, 개발 UI URL local_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 표시명을 일괄 변경하지 않음.
  • 전용 아이콘 자산이 없으면 기존 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_URL
  • AI_ACCESS_TOKEN
  • 개발 문서 벡터 캐시 동기화와 검색을 함께 사용할 때는 아래 값도 같은 파일에 준비함.
  • VAULT_DATABASE_URL
  • AI_EMBEDDING_API_KEY
  • AI_EMBEDDING_BASE_URL
  • VAULT_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를 따름.