Epic: Entity ID migration — text → FK-first catalog & app

[CIOI]

Goal

artist_name / group_name / metadata.brand 등 text 중심 참조를 줄이고, artist_id / group_id / brand_id 및 instagram_accounts FK를 앱·검색·저장 경로의 기본 키로 전환한다.

Context

• Operation DB: artists, brands, groups, instagram_accounts (~1,518 IA rows, 2026-05-25)
• Instagram enrichment pipeline (Build Instagram account enrichment pipeline for artist/brand/group catalog #495, closed PR feat(data-pipeline): Instagram 엔티티 enrichment 파이프라인 추가 #544)는 tagged_usernames → catalog 경로
• Legacy 수동 catalog·name-only posts/solutions는 자동 enrichment만으로 채워지지 않음
• Admin enrichment UI prod 500: web service_role 설계 오류 → fix(admin): Instagram accounts enrichment API 프로덕션 500 오류 #578 (api-server 이관)

Program structure

Sprint 1 (vertical slice — @philippekwak)

Track	Issue	Sprint task
Audit & S2 plan	#581	S1-philippekwak-5
Enrichment scale-up	#578, #495	S1-philippekwak-6
Backfill queue PoC	#582	S1-philippekwak-7 (stretch)

Monorepo pointer: docs/database/entity-id-migration-program.md

Sprint 2+ (waves — 본 epic 하위에서 쪼갤 예정)

• Meilisearch: artists/brands/groups id 기반 검색 인덱스
• Write path: upload / verify / admin 저장 시 FK 우선
• UI resolver: render 시 id → name / thumbnail / profile
• Promote policy: 전량 auto-promote (confidence gate 유지)

References

• docs/database/entity-enrichment-pipeline.md
• docs/database/entity-id-migration-program.md
• Build Instagram account enrichment pipeline for artist/brand/group catalog #495 (PoC, closed)
• fix(admin): Instagram accounts enrichment API 프로덕션 500 오류 #578 (admin API — api-server proxy, no Vercel service role)
• Entity ID migration audit & S2 rollout plan #581 (audit)
• Entity FK / legacy catalog backfill queue (PoC) #582 (backfill queue PoC)

Security note

DATABASE_SERVICE_ROLE_KEY는 web(Vercel)이 아닌 api-server / ai-server에만 둔다.

Definition of done (epic — program level)

• S1 audit (Entity ID migration audit & S2 rollout plan #581) + S2 ordered task list 합의
• Enrichment admin + scheduler prod 운영 가능 (fix(admin): Instagram accounts enrichment API 프로덕션 500 오류 #578 merged)
• posts/solutions FK NULL 비율 baseline + 개선 추이
• S2 waves 각각 별도 issue로 착수

[CIOI]

Child issues (S1)

Sprint task	Issue
S1-philippekwak-5 — audit & S2 plan	#581
S1-philippekwak-6 — enrichment scale-up	#578, #495
S1-philippekwak-7 — backfill queue PoC (stretch)	#582

Existing / linked

• Build Instagram account enrichment pipeline for artist/brand/group catalog #495 — Instagram enrichment PoC (closed, PR feat(data-pipeline): Instagram 엔티티 enrichment 파이프라인 추가 #544)
• fix(admin): Instagram accounts enrichment API 프로덕션 500 오류 #578 — admin API api-server proxy (open; branch fix/578-entity-enrichment-via-api-server)