Build Instagram account enrichment pipeline for artist/brand/group catalog

[CIOI]

요약

Instagram tagged account를 기반으로 artists, brands, groups 카탈로그를 채우는 Data Pipeline 워크플로우를 구축한다.

소유권은 다음처럼 분리한다.

• Operation DB: 검증된 entity/account 결과 상태
• Assets DB: pipeline runtime state, scheduler 상태, Gemini 사용량/비용 집계

배경

현재 Instaloader 수집 과정에서 Instagram tagged account가 assets raw_posts.platform_metadata.tagged_usernames에 저장되고 있다. Operation DB에는 이미 instagram_accounts, artists, brands, groups, group_members가 있지만, 과거 n8n 기반 warehouse workflow는 현재 public schema와 맞지 않는다.

기존 entity dashboard에서 artist/brand/group 자체는 편집할 수 있지만, Instagram account 후보를 수집하고, profile을 보강하고, Gemini 판단 결과를 확인한 뒤 entity catalog로 자동 반영하는 전용 Data Pipeline 화면이 없다.

Gemini 2.5 Flash + Google Search grounding을 사용해서 누락된 name_en, name_ko, 계정 type, 계정 role, regional classification, brand country_of_origin을 보강한다. Grounding은 paid tier 기준 1,500 RPD 무료 한도가 있으므로, scheduler가 안전하게 동작하려면 사용량을 기존 assets Gemini cost table에 기록하고 admin에서 확인할 수 있어야 한다.

범위

• Operation instagram_accounts에는 오래 남을 classification column만 추가한다.
  • account_type
  • entity_ig_role
• Operation brands에 country_of_origin text not null default 'NA'를 추가한다.
• Gemini/profile enrichment 세부 상태는 별도 column으로 늘리지 않고 instagram_accounts.metadata.entity_enrichment 아래에 저장한다.
• Scheduler runtime state는 assets pipeline_settings.platform = 'entity_enrichment' row에 저장한다.
• Gemini 사용량은 기존 assets gemini_usage_events에 기록한다.
  • pipeline = 'entity_enrichment'
  • step = 'instagram_account_review'
• assets raw_posts.platform_metadata.tagged_usernames에서 username을 추출해 operation instagram_accounts에 normalized username 기준으로 upsert한다.
• Instaloader로 Instagram profile metadata를 best-effort로 backfill한다.
  • display_name
  • bio
  • profile_image_url
• Profile image는 기존 R2 public URL 전략을 재사용한다.
• Gemini 2.5 Flash + Google Search grounding으로 이름/type/role/region/country of origin을 보강한다.
• /admin/data-pipeline/instagram-accounts 페이지에서 queue, scheduler, Gemini quota usage, enrichment 결과를 모니터링한다.
• High-confidence primary account는 artists, brands, groups에 자동 생성 또는 연결한다.
• secondary/regional account는 instagram_accounts에 명시적 role/region과 함께 남긴다.
• 수동 보정은 pipeline queue가 아니라 기존 artists, brands, groups admin 화면에서 진행한다.
• operation/assets DB 소유권과 workflow를 문서화한다.

비범위

• 기존 raw posts review queue를 대체하지 않는다.
• 불확실한 Gemini 판단을 자동 publish하지 않는다.
• Pipeline queue에서 account별 approve/edit UI를 만들지 않는다.
• Pinterest/raw post pipeline 자체를 재설계하지 않는다.
• regional/secondary Instagram account 때문에 중복 primary entity를 만들지 않는다.
• group_members를 Gemini 결과만으로 자동 생성하지 않는다.
• Operation DB에 entity enrichment scheduler settings 또는 Gemini daily usage table을 새로 만들지 않는다.

수용 기준

• Admin이 Data Pipeline 아래에서 Instagram account enrichment queue를 볼 수 있다.
• Admin이 Data Pipeline에서 enrichment scheduler를 켜고 끌 수 있다.
• Scheduler 상태는 assets pipeline_settings의 entity_enrichment row를 사용한다.
• Admin이 오늘의 Gemini grounded-search 사용량, 남은 quota, configured cap, cap reached 상태를 볼 수 있다.
• Scheduler는 assets gemini_usage_events 기준으로 daily Gemini grounding cap을 지킨다.
• 모든 grounded request는 기존 Gemini cost tracking path를 통해 기록된다.
• assets raw posts에서 추출한 tagged username은 normalize/deduplicate 후 operation instagram_accounts에 upsert된다.
• Gemini output은 opaque text가 아니라 instagram_accounts.metadata.entity_enrichment.gemini_review에 structured data로 저장된다.
• Profile backfill 상태와 provenance는 dedicated column이 아니라 instagram_accounts.metadata.entity_enrichment.profile_backfill에 저장된다.
• Admin은 Gemini evidence와 profile metadata를 보고 후보 계정의 enrichment 결과를 확인할 수 있다.
• Account type은 artist, fashion-only brand, group, other, unknown으로 저장되고 표시된다.
• Fashion brand 정의는 fashion product brand 또는 fashion retailer로 제한한다.
  • magazine/media, beauty/cosmetics, tech company, character/IP owner는 other로 분류한다.
• Account role은 primary, secondary, regional, unknown으로 저장되고 표시된다.
• Regional account는 entity_region_code를 저장한다. 예: JP, KR.
• Brand primary entity는 country_of_origin을 저장한다. 모르면 NA를 사용한다.
• High-confidence primary account는 올바른 artists, brands, groups row를 생성 또는 연결하고 primary_instagram_account_id를 설정한다.
• Secondary/regional account는 명시적 role/region과 함께 instagram_accounts에 남는다.
• Group account는 primary group account일 때 groups row 생성/연결까지만 자동 처리한다. group_members는 기존 admin workflow에서 관리한다.
• Entity image/logo URL은 R2-backed profile image URL로 채울 수 있다.
• 자동 write는 metadata 또는 audit log를 통해 provenance를 보존한다.
• Schema, data flow, quota policy, enrichment rule 문서가 업데이트된다.

구현 메모

• Generic entity CRUD screen에 먼저 넣기보다는 Data Pipeline page로 시작한다.
• Candidate extraction은 assets에서 읽고, catalog write는 operation에 쓴다.
• Scheduler runtime state와 Gemini usage는 assets에 남긴다.
• 두 Supabase project 사이에 cross-project FK는 만들지 않는다.
• Operation DB에는 scheduler settings / Gemini daily usage table을 만들지 않는다.
• 기존 assets table을 재사용한다.
  • pipeline_settings
  • gemini_usage_events
  • gemini_spend_daily
• 첫 릴리스는 새 tagged account뿐 아니라 기존 operation instagram_accounts 중 name/image/review state가 부족한 계정도 처리한다.
• Profile/logo image 저장은 기존 R2 public URL 전략을 재사용하고, Supabase Storage bucket은 추가하지 않는다.
• Instaloader profile backfill은 best-effort로 처리한다. 세션 만료/rate limit/challenge로 실패해도 Gemini enrichment는 계속 진행한다.

[thxforall]

Closed after confirming PR #544 was merged into dev. This issue was linked with a closing keyword in the PR body.

[CIOI]

Superseded by program epic #580 for ID-first catalog & app migration. PoC scope remains valid; follow-up: #578, #581, #582.