feat(data-pipeline): Instagram 엔티티 enrichment 파이프라인 추가

docs/agent/database-summary.md

@@ -2,11 +2,12 @@
 title: Database — Agent Summary
 owner: llm
 status: draft
-updated: 2026-04-30
+updated: 2026-05-11
 tags: [db, agent]
 related:
   - docs/database/operating-model.md
   - docs/database/01-schema-usage.md
+  - docs/database/entity-enrichment-pipeline.md
   - docs/architecture/assets-project.md
   - docs/database/04-supabase-cli-setup.md
 ---
@@ -29,6 +30,7 @@ prod 는 assets 의 존재를 모르고, assets 도 prod 를 모른다 (cross-pr
 ## Canonical sources
 
 - **운영 모델 (먼저 읽기)**: [`docs/database/operating-model.md`](../database/operating-model.md) — 영역/시스템 매트릭스, "어디 추가하나" 결정 트리, drift 회피, dev 시드 절차
+- Entity enrichment RFC: [`docs/database/entity-enrichment-pipeline.md`](../database/entity-enrichment-pipeline.md) — assets Instagram tags → prod `instagram_accounts` → `artists`/`brands`/`groups`
 - 스키마 사용법: [`docs/database/01-schema-usage.md`](../database/01-schema-usage.md)
 - 데이터 흐름: [`docs/database/03-data-flow.md`](../database/03-data-flow.md)
 - 업데이트 체크리스트: [`docs/database/02-update-checklist.md`](../database/02-update-checklist.md)
@@ -40,6 +42,7 @@ prod 는 assets 의 존재를 모르고, assets 도 prod 를 모른다 (cross-pr
 
 - **prod public schema**: 앱 데이터 (posts, items, users, solutions, social 등) + 엔티티 카탈로그 (artists/groups/brands, #333)
 - **assets public schema**: 파이프라인 스테이징 (raw_post_sources, raw_posts, pipeline_events) + 5-state 상태머신
+- **entity enrichment**: assets `raw_posts.platform_metadata.tagged_usernames` 는 후보 증거이고, scheduler state/usage 는 assets `pipeline_settings` / `gemini_usage_events` 가 소유한다. reviewed account/entity state 는 prod `public.instagram_accounts` / `artists` / `brands` / `groups` 가 소유한다.
 - Migration 전략:
   - prod: SeaORM (테이블·컬럼) + Supabase CLI SQL (RLS·함수, `supabase/migrations` 가 SOT, #282)
   - assets: Supabase CLI SQL only (`supabase-assets/migrations/`). SeaORM 은 assets 를 건드리지 않음.
@@ -57,3 +60,4 @@ prod 는 assets 의 존재를 모르고, assets 도 prod 를 모른다 (cross-pr
 - 2026-04-30: 운영 모델 단일 진입점 (`operating-model.md`) 추가 (#371). PRD ref 갱신 (`womgfy...` → `tdchmitwczlwydzkyczu`).
 - 2026-04-25: warehouse 스키마 드롭 + assets 프로젝트 분리 반영 (#333 / #335)
 - 2026-04-17: 초기 작성 (Phase 1)
+- 2026-05-11: Instagram tagged account → entity catalog enrichment RFC 추가.

docs/agent/web-routes-and-features.md

@@ -2,7 +2,7 @@
 title: Web Routes & Features — Agent Reference
 owner: human
 status: approved
-updated: 2026-04-17
+updated: 2026-05-11
 tags: [agent, ui]
 ---
 
@@ -43,6 +43,7 @@ App Router 기준 (`packages/web/app/`). 작업 시 이 표와 실제 `app/` 트
 | `/admin/entities/group-members` | 그룹 멤버 관리                                                                                                              |
 | `/admin/raw-post-sources`       | 수집 소스 등록/관리 (Pinterest 등 — #327)                                                                                   |
 | `/admin/raw-posts`              | **검증 큐** (#333) — assets 의 raw_posts 를 status 탭(COMPLETED/IN_PROGRESS/ERROR/VERIFIED) 으로 필터링, "검증" 버튼으로 prod posts 반영 |
+| `/admin/data-pipeline/instagram-accounts` | Instagram tagged account enrichment queue, Gemini grounding quota, scheduler controls, manual entity review. See [`docs/database/entity-enrichment-pipeline.md`](../database/entity-enrichment-pipeline.md). |
 | `/request/upload`               | Image upload with DropZone                                                                                                  |
 | `/request/detect`               | AI detection results with item spotting                                                                                     |
 | `/request/try`                  | Try 포스트 업로드 페이지                                                                                                    |

docs/architecture/assets-project.md

@@ -2,14 +2,18 @@
 title: Assets Supabase Project
 owner: human
 status: approved
-updated: 2026-04-25
+updated: 2026-05-11
 tags: [architecture, db, agent]
+related:
+  - docs/database/entity-enrichment-pipeline.md
 ---
 
 # Assets Supabase Project (#333)
 
 **한 줄 요약**: Pinterest/Instagram 등 외부 플랫폼에서 수집·파싱한 raw_posts 와 파이프라인 중간 상태를 별도 Supabase 프로젝트(`assets`)에 격리. prod 는 admin 이 검증 완료한 데이터만 보유.
 
+> Instagram tagged accounts 는 assets `raw_posts.platform_metadata.tagged_usernames` 에 후보 증거로 남고, reviewed account/entity state 는 prod `public.instagram_accounts` / `artists` / `brands` / `groups` 가 소유한다. 상세 RFC 는 [`docs/database/entity-enrichment-pipeline.md`](../database/entity-enrichment-pipeline.md).
+
 ## 왜 분리했나
 
 PR #258 의 raw_posts 파이프라인이 prod Supabase 의 `warehouse.raw_post*` 테이블을 직접 사용하면서 두 가지 문제가 누적됐다:
@@ -28,6 +32,7 @@ PR #258 의 raw_posts 파이프라인이 prod Supabase 의 `warehouse.raw_post*`
 │ public.raw_posts                              │
 │   └ status pipeline_status                    │
 │   └ verified_at / verified_by                 │
+│   └ platform_metadata.tagged_usernames (IG)   │
 │ public.pipeline_events                        │
 │ + RLS: service-role only                      │
 └──────────────▲──────────────┬─────────────────┘
@@ -89,6 +94,19 @@ NOT_STARTED → IN_PROGRESS → COMPLETED ──(admin verify)──► VERIFIED
 
 로컬 개발자가 cloud assets(공유) 데이터를 오염시키지 않도록 `APP_ENV=local` 일 때 verify 엔드포인트는 **prod INSERT 만** 수행하고 assets status write 를 스킵한다. production 배포에서만 status=VERIFIED 가 기록된다.
 
+### 5. Instagram tagged accounts 는 downstream entity enrichment 입력
+
+Instagram adapter 는 Instaloader GraphQL payload 의 tagged users 를
+`raw_posts.platform_metadata.tagged_usernames` 로 저장한다. 이 값은 assets
+프로젝트 안에서는 raw evidence 이며, account classification 이나 artist/brand/group
+승격 상태를 의미하지 않는다.
+
+Entity enrichment pipeline 은 이 raw evidence 를 읽어 prod `public.instagram_accounts`
+에 username 기준으로 upsert 한다. Scheduler 상태와 Gemini 사용량은 assets
+`pipeline_settings` / `gemini_usage_events` 에 남기고, Gemini/profile
+backfill/admin review 의 검증된 결과만 prod entity catalog 에 기록한다. 두
+프로젝트 사이에는 여전히 FK 를 만들지 않는다.
+
 ## verify 시퀀스
 
 ```
@@ -152,6 +170,7 @@ prod 에서 `warehouse` 스키마를 완전 드롭하고 살아남는 엔티티
 | `caption` | 텍스트 (Pinterest description, IG caption 등) | 합성 케이스: NULL 또는 prompt |
 | `author_name` | 저자/소스 명 (Pinterest pinner 등) | — |
 | `platform_metadata` | 플랫폼별 자유 메타 (saves, board_id, hashtags 등) | 합성 케이스: 보통 NULL |
+| `platform_metadata.tagged_usernames` | Instagram tagged account 후보. 쉼표 구분 username 문자열. Entity enrichment pipeline 의 입력으로만 사용 | Instagram raw_posts |
 | `parse_result` | 비전파싱 결과 (아이템 bbox, 브랜드 후보 등) | 모든 케이스 동일 — Vision 결과 |
 | `dispatch_id` | ai-server scheduler 의 1회 dispatch 추적 키 | — |
 
@@ -161,3 +180,4 @@ prod 에서 `warehouse` 스키마를 완전 드롭하고 살아남는 엔티티
 
 - 2026-04-26: r2_url/r2_key 컬럼 드롭, image_url 단일화 (#347)
 - 2026-04-25: 초기 작성 — 두 프로젝트 분리, 5-state 상태머신, verify 플로우 (#333)
+- 2026-05-11: Instagram tagged accounts 를 entity enrichment downstream input 으로 문서화.