본문으로 건너뛰기

JunkBox 공통 마스터 데이터 가이드

1. 문서 목적​

  • 이 문서는 JunkBox에서 코드와 메타 정보를 AI와 사람이 동일한 기준으로 조회하고 변경하기 위한 공통 규칙 문서임.
  • Nexus는 참고용으로만 보고, 실제 기준 데이터의 Source of Truth는 JunkBox hub-api와 Hub SQLite /sorc001/junkbox/db/hub.sqlite3 파일로 고정함.
  • AI 코딩 시 코드/메타 마스터데이터를 추정하거나 하드코딩하지 않고, 항상 현재 DB 상태를 조회한 뒤 구현하도록 강제하는 것이 목적임.

2. 적용 범위​

  • 공통코드
  • 코드 타입 메타
  • 메타 정보
  • 포털 메뉴
  • 이 문서는 JunkBox 전체 공통 규칙(Global Rule)이며 모든 앱 모듈이 공유함.

3. 핵심 원칙​

3.1 Source of Truth 원칙​

  • 공통 마스터데이터의 단일 관리 주체는 apps/hub-api임.
  • 실제 저장 원본은 Hub SQLite /sorc001/junkbox/db/hub.sqlite3 파일임.
  • 다른 앱이나 모듈은 공통 마스터데이터를 자체 파일, 상수, 별도 테이블로 중복 소유하지 않음.

3.2 AI 조회 우선 원칙​

  • AI는 기능 개발 또는 설정 추가 전에 반드시 현재 마스터데이터를 먼저 조회함.
  • 조회 없이 코드/메타 값을 추정해서 새 값을 만들거나 하드코딩하지 않음.
  • 조회 결과를 현재 컨텍스트로 삼고, 필요한 변경분만 SQL 산출물로 생성함.

3.3 변경 산출물 원칙​

  • AI는 변경 전 scripts/fetch_master_data.py 통합 snapshot으로 현재 코드·메타 식별자를 확인함.
  • Hub SQLite 변경은 대상 파일, 테이블, 컬럼을 확인한 뒤 사용자 승인 방식에 따라 직접 반영하거나 수동 반영 산출물로 작성함.
  • 사용자에게 직접 반영 권한을 받은 Hub SQLite 변경은 tb_code_type_c, tb_common_c 등 대상 테이블의 논리 키를 기준으로 UPSERT하고 반영 뒤 결과와 스키마를 검증함.
  • 직접 반영 권한이 없거나 PostgreSQL 대상인 변경은 프로젝트 루트의 ai-outputs/에 SQL 또는 Markdown 수동 반영 산출물로 남김.
  • ai-outputs/는 AI가 직접 적용하지 않는 DB 마스터데이터, 메타 프롬프트, 운영 설정 변경분을 사용자가 검토해 수동 반영하기 위한 위치임.

3.4 계약 유지 원칙​

  • API 응답과 저장소 계약 필드는 snake_case를 유지함.
  • 메타는 meta_key, 공통코드는 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 검색용으로 색인한 벡터 캐시이며 공통 마스터데이터 원본이 아님.
  • 마스터데이터 변경은 이 문서의 SQL 산출물 원칙을 따름.
  • 개발 문서 변경은 vault/docs/junkbox/**/*.md 파일을 직접 수정한 뒤 Git 검증과 개발 문서 벡터 캐시 동기화 흐름을 따름.
  • AI 에이전트의 표준 마스터데이터 조회 경로는 scripts/fetch_master_data.py가 호출하는 JWT 기반 통합 snapshot API임.
  • 개발 문서 검색은 vault.docs, vault.doc_chunks, vault.doc_embeddings와 개발 문서 검색 스크립트 흐름을 사용함.

4. 현재 소스 기준 확인 결과​

4.1 라우터 기준 진입점​

  • apps/hub-api/src/junkbox_hub_api/main.py에서 마스터데이터 라우터가 다음 prefix로 등록되어 있음.
  • 공통코드: /api/hub
  • 메타: /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}

4.3 현재 내부 소비용 조회 엔드포인트​

  • 코드 타입 전체: GET /api/internal/master-data/codes/{code_type_code}
  • 메타 키 조회: GET /api/internal/master-data/metas/by-key/{meta_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를 하나의 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 앱 런타임 소비 구조​

  • workout-api, raid-api, rename-api, jeevtrap는 shared-core.masterdata.MasterDataService를 통해 공통 master-data를 소비함.
  • AI 기능을 사용하는 chess-api, jeevtrap는 shared-ai의 Hub API usage-log writer를 통해 AI 사용 이력을 전달하며 Hub SQLite 파일을 직접 열지 않음.
  • MasterDataService는 HubMasterDataClient와 TtlAsyncCache를 조합하여 코드 목록, 메타 값, active 포털 메뉴 목록을 조회함.
  • 앱별 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 화면 문구는 컴포넌트 코드에 한국어 문구로 직접 작성함.
  • jeevtrap Discord UI 문구와 slash command 설명은 앱 내부 카탈로그의 한국어 문구를 사용함.
  • 운영 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를 기준으로 현재 등록 상태를 확인함.
  4. 기존 값 재사용 여부와 신규 키 필요 여부를 판단함.
  5. 소스 구현을 진행함.
  6. 변경이 필요하면 SQL 파일을 생성함.

6. AI 조회 절차 상세​

6.1 텍스트와 마스터데이터 경계​

  • 화면 문구, 에러 문구, 피드백 문구, Discord interaction label처럼 사용자가 직접 보는 일반 텍스트는 DB 마스터데이터 조회 대상이 아님.
  • 일반 텍스트는 각 화면과 서비스 코드에 한국어 문구로 직접 작성함.
  • 통일이 필요한 표현은 DB 메시지 키가 아니라 공통 UI 가이드와 현재 화면 문구를 기준으로 맞춤.
  • 로그, 콘솔 출력, 주석, 개발자 디버그 문자열은 사용자 UI 텍스트 기준에 포함하지 않음.

6.2 메타 조회​

  • 메타 전체 파악은 통합 snapshot의 metas 배열을 우선 사용함.
  • 특정 설정 키 확인도 snapshot의 meta_key 기준 검색을 우선 사용함.
  • 프롬프트 템플릿, 운영 설정 문자열, 장문 설명성 값은 메타 우선 여부를 먼저 검토함.
  • workout 앱의 운동 계획 생성은 메타 프롬프트를 사용하지 않음.
  • workout 앱의 운동 계획 생성은 workout-api 규칙 엔진이 Workout SQLite 운동 기준정보와 운동 기록을 기준으로 수행함.
  • WORKOUT_COACH_INSTRUCTION, WORKOUT_COACH_USER_TEMPLATE 같은 workout 계획 프롬프트 메타는 현재 workout 런타임 계약에 포함되지 않음.
  • EXCHANGE_RATE 메타는 1달러당 원화 환율을 나타내며 meta_val에는 숫자 문자열만 저장하는 전제를 사용함.
  • 화면에서 USD 기준 금액을 원화로 표시해야 할 때는 EXCHANGE_RATE.meta_val을 숫자로 해석해 곱함.

6.3 공통코드 조회​

  • 공통코드 조회는 통합 snapshot의 code_types와 codes 객체를 우선 사용함.
  • 필요한 타입은 code_types에서 확인하고, 해당 타입의 실제 코드는 codes[code_type_code]에서 읽음.
  • 관리자 화면 기준의 추가 속성 검토가 필요하면 보조적으로 GET /api/hub/codes/types/{code_type_code}/meta를 사용함.
  • AI_MODEL 공통코드는 AI usage log 추정 비용 계산용 기준 데이터임.
  • AI_MODEL.common_code는 provider:model 형식의 full model id와 일치해야 함.
  • AI_MODEL.attribute01은 입력 토큰 USD 단가, AI_MODEL.attribute02는 출력 토큰 USD 단가이며 둘 다 100만 토큰 기준 숫자값으로 관리함.
  • provider와 model을 별도 변수로 관리하는 런타임에서도 단가 매칭은 런타임에서 조합한 provider:model 문자열과 AI_MODEL.common_code를 직접 비교하는 방식임.
  • litellm:openrouter/deepseek/deepseek-v4-flash는 OpenRouter DeepSeek V4 Flash를 LiteLLM proxy 경유로 사용할 때의 AI_MODEL 식별자임.
  • WORKOUT_ROUTINE_MODE 공통코드는 운동 계획 생성 시 사용자가 선택하는 루틴 구분의 소스 오브 트루스임.
  • workout 운동 계획 화면은 WORKOUT_ROUTINE_MODE 활성 공통코드 라벨을 조회해 모바일 하단 선택 시트 option으로 표시하며, 화면 문구 자체는 메시지 마스터데이터로 관리하지 않음.
  • workout 규칙 엔진은 UPPER, LOWER를 명시 계산 대상으로 사용함.
  • WORKOUT_ROUTINE_MODE에 그 밖의 활성 코드가 남아 있으면 화면 option에는 표시될 수 있으나, workout 규칙 엔진은 알 수 없는 루틴 모드를 상체 루틴으로 정규화함.
  • BODY_PART 공통코드는 workout 운동 기준정보와 운동 선택 필터가 사용하는 운동 부위의 소스 오브 트루스임.
  • WORKOUT_STATUS 공통코드는 workout 세트 상태의 소스 오브 트루스임.
  • RUNNING_STEP 공통코드는 workout 러닝 단계 유형의 소스 오브 트루스임.
  • RUNNING_STEP.common_code는 러닝 단계의 activity_type_code로 저장됨.
  • RUNNING_STEP.common_code_name은 러닝 계획 편집 화면, 러닝 실행 화면, 음성 안내 문구의 단계 유형 표시명으로 사용됨.
  • RUNNING_STEP.sort_order_no는 러닝 단계 유형 선택 목록의 정렬 기준임.
  • 러닝 단계 이름은 별도 텍스트 마스터나 SQLite 컬럼으로 관리하지 않으며 RUNNING_STEP 라벨을 기준으로 표시함.
  • workout 운동 종목 기준정보의 런타임 소스 오브 트루스는 workout SQLite tb_workout_exercise_m임.
  • EXERCISE 공통코드는 workout 운동 기준정보 테이블을 초기 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로 매핑함.
  • workout 운동 관리 화면에서 생성·수정되는 운동 기준정보는 hub 공통코드 EXERCISE를 직접 변경하지 않음.
  • 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_SOURCE 공통코드는 Message 앱의 발송 출처 선택지와 메시지 이력 source 값의 소스 오브 트루스임.
  • 활성 코드 BACKUP, WORKOUT, ETC를 사용함. BACKUP, WORKOUT는 코드와 코드명이 같은 영문 대문자이며, ETC의 코드명은 기타임.
  • 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_MEMBER_CATEGORY 공통코드는 Raid 공대원 풀의 구분 소스 오브 트루스임. 활성 코드는 SELF(나), TRACKING(추적), RAID_MEMBER(공대원)이며 sort_order_no는 각각 1, 2, 3임.
  • Raid 목록과 관리 화면은 RAID_MEMBER_CATEGORY의 활성 코드와 sort_order_no를 그대로 사용하며, 라벨을 별도 화면 상수로 중복 관리하지 않음.

6.4 조회 결과 활용 규칙​

  • AI는 조회 결과를 기준으로 기존 식별자를 재사용해야 하며, 비슷한 의미의 신규 키를 임의 생성하지 않음.
  • 같은 의미의 코드와 메타를 화면별로 중복 생성하지 않음.
  • 기존 키가 있으면 값만 재사용하거나 SQL로 변경 요청을 산출함.

7. 변경 규칙​

7.1 승인 기반 변경 방식​

  • PostgreSQL 마스터데이터에는 API 또는 DB 직접 변경을 수행하지 않음. 사용자 검토용 수동 반영 산출물을 ai-outputs/에 생성함.
  • Hub SQLite 마스터데이터는 변경 대상 DB 파일과 테이블·컬럼을 먼저 확인함.
  • Hub SQLite 직접 변경은 사용자가 직접 반영을 승인한 경우에만 수행함. 승인 범위 밖이면 수동 반영 산출물을 생성함.
  • 직접 반영은 SQLite INSERT ... ON CONFLICT DO UPDATE UPSERT를 우선 사용하고, 반영 뒤 PRAGMA table_info(...)와 대상 코드·메타 조회로 검증함.

7.2 SQL 파일 위치와 이름​

  • 현재 프로젝트에는 Flyway 또는 Alembic 기반 마이그레이션 폴더가 정착되어 있지 않으므로, AI가 직접 적용하지 않는 마스터데이터 변경 SQL은 프로젝트 루트의 ai-outputs/ 폴더에 생성함.
  • 프로젝트 루트의 ai-outputs/ 폴더는 작업자 로컬 검토 및 수동 반영용 산출물 위치임.
  • 필요한 SQL 산출물은 사용자가 검토한 뒤 별도 운영 절차로 적용함.
  • 파일명 규칙은 {권장파일명}_{yyyymmddhh24miss}.sql 형식을 사용함.
  • 권장 접두사는 masterdata로 고정함.
  • 예시:
ai-outputs/masterdata_add_user_menu_codes_20260517144251.sql
ai-outputs/masterdata_update_ai_prompt_metas_20260517144510.sql
ai-outputs/masterdata_add_workout_status_codes_20260517144733.sql

7.3 SQL 작성 원칙​

  • DB는 Hub SQLite를 사용함.
  • 중복 반영 방지를 위해 SQLite INSERT ... ON CONFLICT DO UPDATE 기반 UPSERT를 사용함.
  • 논리 식별자 충돌 기준은 다음을 우선 사용함.
  • 메타: 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
) VALUES (
    'EXAMPLE_SETTING',
    'example',
    '예시 설정값',
    1,
    'ai_masterdata',
    'ai_masterdata'
)
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 = CURRENT_TIMESTAMP;

8. 식별자 및 데이터 설계 규칙​

8.1 텍스트 표현​

  • 일반 UI 문구는 message_code를 만들지 않고 한국어 문구를 소스에 직접 작성함.
  • 공통 버튼, 공통 상태, 공통 빈값 문구는 현재 화면에서 쓰는 표현을 우선 맞춤.
  • 문장형 메시지는 하십시오체와 마침표 규칙을 지킴.
  • 기능명이나 화면명을 과도하게 붙여 비슷한 표현을 중복 확산하지 않음.

8.2 메타​

  • meta_key는 설정 키 성격을 명확히 드러내는 대문자 스네이크 케이스를 우선 사용함.
  • 장문 텍스트, 프롬프트, 템플릿, 운영 제어값은 메타에 두는 것을 우선 검토함.

8.3 공통코드​

  • 코드 타입은 도메인 분류이며, 실제 값은 해당 타입 하위 코드로 관리함.
  • 코드 타입과 실제 코드를 같은 레벨에서 혼용하지 않음.
  • 코드 타입 식별자는 대문자 스네이크 케이스를 사용함. MESSAGE_SOURCE처럼 도메인과 역할을 함께 드러내는 이름을 사용함.
  • 공통코드 UI 표시 라벨은 common_code_name, 설명은 common_code_desc를 우선 사용함.
  • 코드 타입 UI 표시 라벨은 code_type_code_name, 설명은 code_type_code_desc를 우선 사용함.
  • 순서가 사용자 경험에 직접 영향을 주는 공통코드는 sort_order_no를 정렬 기준으로 사용함.

8.4 포털 메뉴​

  • 포털 메뉴는 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 설치 아이콘을 같은 앱 아이콘 세트로 연결하는 관리 계약임.
  • 신규 앱 포털 메뉴를 추가하기 전에는 통합 snapshot과 현재 포털 메뉴를 조회하여 기존 URL, 표시 순서, 아이콘 slug, 운영 포트 배정을 확인함.
  • 신규 앱은 임의의 다음 포트 번호나 유사한 메뉴 키를 추정하지 않으며, 현재 등록값과 충돌하지 않는 URL·포트·식별자를 선택함.
  • 포털 메뉴 변경은 Hub SQLite 마스터데이터 변경임. AI가 직접 적용할지 수동 SQL 산출물을 만들지는 SQLite 변경 권한과 사용자 승인 기준으로 결정함.

9. AI 개발 작업 사이클​

  1. 작업 지시를 받으면 먼저 어떤 마스터데이터가 필요한지 식별함.
  2. scripts/fetch_master_data.py로 통합 snapshot을 조회해 현재 상태를 확인함.
  3. 기존 키 재사용 가능 여부를 먼저 판단함.
  4. 화면/백엔드 구현을 진행함.
  5. 필요한 Hub SQLite 변경은 사용자 승인 방식에 따라 직접 반영하거나 프로젝트 루트 ai-outputs/에 SQL 파일로 생성함.
  6. 작업 보고 시 소스 구현 여부와 마스터데이터 직접 반영 또는 수동 SQL 파일 생성 여부를 함께 알림.

10. JSON 내려받기 전략 권장안​

10.1 현재 판단​

  • AI 에이전트는 scripts/fetch_master_data.py 실행 한 번으로 마스터데이터 전체 문맥을 확보할 수 있음.
  • 단건 확인과 대량 문맥 수집 모두 통합 snapshot을 우선 사용함.
  • 개별 read-only API는 하위 호환 또는 수동 확인 용도로만 사용함.

10.2 통합 snapshot 사용 권장​

  • 여러 화면과 여러 모듈을 한 번에 다루는 AI 작업에서는 개별 API를 여러 번 호출하는 방식보다 읽기 전용 JSON snapshot이 더 효율적임.
  • 권장 실행 명령은 다음과 같음.
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": {
    "AI_MODEL": [],
    "MENU_TYPE": []
  },
  "metas": []
}

10.3 권장 결론​

  • 기본 원칙은 "통합 snapshot으로 전체 문맥 확보 후, 필요 시 개별 엔드포인트로 세부 확인"임.
  • 이 조합이 가장 안정적이고, AI가 중복 키 생성이나 누락 판단을 줄이기에 좋음.

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-core.md를 따름.
  • 공통 저장소 구조는 docs/junkbox/libs/guide-lib-shared-core.md를 따름.
  • hub-api 상세는 docs/junkbox/apps/guide-apps-hub-api.md를 따름.