공용 수집기 (관리형)

어떤 수집 기능을 쓸지 모르겠다면

데이터 수집, 어떤 기능으로? 결정 가이드를 먼저 보세요.

플랫폼 공용 데이터(DART 공시/시세/거시 등) 수집기를 등록하고 자격증명·스케줄을 관리합니다. 관리자가 등록하면 모든 사용자가 인텔리전스 메뉴에서 조회합니다.

용어: 코드·URL 의 intel 은 회사명이 아니라 intelligence 의 약어입니다 (business/market intelligence 관례) — 금융·기업 인텔리전스 수집 계층(Intel Platform)을 가리킵니다. 등록된 소스는 Dagster intel_source_cron_sensor 가 60초마다 cron 만기를 평가해 자동 실행하고, 수집 결과는 Bronze(iceberg.bronze.intel_<domain>_raw) → Silver(PG intel_*) 로 적재됩니다.

• 메뉴 경로: /admin/intel-sources (admin 전용)
• 키 주입·운영 절차: Intel Platform — Collector API Key 운영

엔드투엔드: 5단계 전부 UI 로 (키 발급 → 수집 확인)

새 수집을 붙이는 전 과정입니다. 1단계(외부 발급)를 제외한 모든 단계가 이 화면 안에서 끝납니다 — kubectl/SQL 불필요.

1단계 — API 키 발급 (외부 사이트)

대상 collector 의 발급처에서 키를 발급받습니다. 발급처 링크·무료 여부는 키 매트릭스 참조. (rss/pykrx/ccxt 는 키 불필요 — 2단계 생략)

2단계 — 키 설정 (UI)

페이지 하단 "수집기 API 키" 패널에서 해당 collector 의 키 설정 클릭 → 발급받은 키 붙여넣기 → 저장. 재시작 없이 즉시 반영되며, 배지가 DB (UI 관리) 로 바뀌면 완료입니다. 상세는 아래 수집기 API 키 관리 절.

3단계 — 소스 등록 (UI)

상단 신규 등록 버튼 → 이름 / 수집기 / 도메인 / 스케줄(프리셋 또는 cron, 비우면 수동 전용) 입력 → 저장. 수집기 선택 시 API 키 필요 여부가 안내됩니다.

목록은 신규 등록순(최신 상단) 으로 표시되며, 상단 툴바에서 이름/도메인 검색·수집기 타입·활성 상태로 필터링할 수 있습니다 (#2556 — 벌크 소스가 많은 환경에서 운영 소스 탐색용).

• financials 도메인은 저장 전 필수 파라미터(corp_codes)를 확인하세요.

4단계 — 실행 (UI)

등록된 행의 ▶ 실행 버튼으로 즉시 1회 수집하거나, 활성 스위치를 켜면 스케줄 자동 실행됩니다.

5단계 — 결과 확인 (UI)

• 목록의 마지막 상태 / 마지막 실행 컬럼 — success 와 실행 시각 확인:

• 수동 실행 시 응답 토스트의 records/errors 건수
• 실제 데이터는 사이드바 인텔리전스 > 시세(/intel/market) 또는 SQL 편집기에서 조회합니다 — 기업·공시 / 뉴스·토픽 메뉴는 아직 "준비 중" 배지 상태입니다. Bronze 테이블 이름은 domain 과 1:1 이 아니므로(예: ohlcv_daily → intel_ohlcv_raw, youtube_videos → intel_youtube_raw, patents_kr → intel_patents_raw) 실행 결과 패널의 table_fqn 값을 그대로 사용하세요. Silver 반영이 늦으면 실행·상태 확인의 센서 항목 참조

지원 collector 타입 (12종)

collector_type	대상	API 키
dart	한국 DART 공시·재무제표	GEND_DART_API_KEY
sec_edgar	미국 SEC EDGAR 공시	GEND_SEC_USER_AGENT (User-Agent 문자열)
pykrx	KOSPI/KOSDAQ 일봉 OHLCV	불필요
fred	미국 거시지표 (FRED)	GEND_FRED_API_KEY
ecos	한국은행 거시지표 (ECOS)	GEND_ECOS_API_KEY
polygon	미국 주식 시세 (Polygon)	GEND_POLYGON_API_KEY
naver_news	네이버 뉴스 검색	GEND_NAVER_CLIENT_ID/SECRET
rss	RSS 피드	불필요
youtube	YouTube 동영상 메타	GEND_YOUTUBE_API_KEY
kipris	한국 특허 (KIPRIS)	GEND_KIPRIS_API_KEY
issuer_csv	발행사 CSV	불필요
ccxt	Crypto 거래소 시세 (binance/bybit/okx — 분봉·체결)	불필요 (public API)
(기타)	intel_factory.py 의 _INTEL_COLLECTOR_MAP 참조	—

새 타입 추가는 코드 작업(컬렉터 클래스 + 팩토리 등록)이 필요하지만, 기존 타입의 새 소스는 이 화면에서 row 추가만으로 됩니다.

소스 정의 필드

필드	의미
collector_type / domain	수집기 종류와 대상 도메인 (filings/financials/ohlcv_daily/articles/macro …)
params_json	도메인별 파라미터 (아래 참조)
schedule_cron	cron 또는 프리셋 (5m/15m/1h/6h/12h/daily). NULL = 수동 실행 전용
enabled	sensor 자동 실행 대상 여부
vault_secret_path	(선택) 소스별 Vault KV2 경로 — secret 의 api_key 필드를 읽음. 미지정 시 env 키 사용
checkpoint_json	증분 커서 (collector 가 자동 관리 — 수동 편집 주의)

도메인별 필수 파라미터

• financials (DART 재무제표) — params_json 에 8자리 DART 고유번호 필수. 누락 시 매 실행 failed:

  {"corp_codes": ["00126380", "00164779"]}

  선택: bsns_year(기본 직전 연도), reprt_code(11011 사업/11012 반기/11013 1Q/11014 3Q), fs_div(CFS 연결/OFS 별도).

• filings (DART 공시) — params_json {} 가능 (전체 최신 공시). corp_code 로 특정사 한정 가능.

• ohlcv_daily (pykrx) — 파라미터 불필요. 평일 cron (0 18 * * 1-5 = KST 새벽 3시) 권장.

• ohlcv_minute / trades (ccxt) — params_json 예:

  {"symbol": "BTC/USDT", "exchange": "binance", "market_type": "swap", "interval": "15m"}

  interval 은 ohlcv_minute 전용 (1m/5m/15m). 정기 silver 적재는 Dagster 자산(silver_intel_ohlcv_minute/silver_intel_trades)이 담당하므로 이 소스는 cron 없이 수동 실행·연결 테스트 용도로 두는 것을 권장합니다 (#2535).

수집기 API 키 관리 (#2460)

페이지 하단 "수집기 API 키" 섹션에서 키 필요 collector (dart/fred/ecos/polygon/naver_news/youtube/kipris/sec_edgar) 의 키를 kubectl 없이 관리합니다:

• 키 설정/회전 — "키 설정" 클릭 → 다이얼로그에 키 입력(password 마스킹, 8자 이상) → 저장. Fernet 암호화 저장되며 재시작 없이 즉시 반영. 저장 후 말미 4자만 표시 (write-only)

• naver_news 는 2필드 (#2499) — 다이얼로그에 CLIENT_ID + CLIENT_SECRET 이 함께 표시됩니다. 최초 설정은 둘 다 입력(각 8자 이상), 이후 SECRET 을 비워두면 기존 값 유지(키만 회전). 목록 힌트에 SECRET ····말미4자 로 설정 여부가 표시됩니다

  

  

• 사용 소스 배지 — DB (UI 관리) / 환경변수 / 미설정. 해석 순서는 DB → 소스별 vault 경로 → env. 저장하면 해당 행이 아래처럼 배지·힌트·설정자/시각으로 전환됩니다

  

• 삭제 — env/Vault 폴백으로 복귀. 폴백 없으면 해당 수집기 실행 불가

운영자용 상세(마스터키·레거시 env 경로·한계)는 Collector API Key 운영 참조.

조회 권한 — 소유 워크스페이스만 (ADR-0035 D-5)

Intel 데이터는 수집한 소스를 소유한 워크스페이스의 것입니다(ADR-0035). 따라서 intel 전용 MCP 도구(query_intel_filings·query_intel_macro·query_intel_articles·list_intel_sources 등)는 호출자의 활성 워크스페이스 소유 행만 반환합니다.

아직 완전한 격리는 아닙니다

범용 SQL 도구(execute_query·sample_table)로 같은 Bronze 테이블을 직접 조회하면 현재는 워크스페이스 술어가 붙지 않습니다(#3165). 따라서 아래 표는 intel 전용 도구의 동작이며, intel 데이터의 완전한 테넌트 격리는 #3165 해소 후에 성립합니다. 민감한 워크스페이스 데이터라면 그때까지 Trino 접근 자체를 grant 로 제한하세요.

호출자	조회 범위
소유 워크스페이스 멤버	해당 워크스페이스 행
플랫폼 관리자(데이터평면 자격)	전 워크스페이스. 단 GEND_ADMIN_DATA_PLANE_MODE=enforce 에서는 break-glass 역할이 있어야 하며, 없으면 자기 워크스페이스로 펜스됩니다(#2700 D2)
워크스페이스 멤버십 없음	거부(fail-closed) — 종전에는 필터가 걸리지 않아 전 테넌트 행이 보였습니다
플랫폼 관리자인데 break-glass 없음 + 활성 워크스페이스 없음(enforce 모드)	거부 — 사유가 구분돼 표시됩니다(멤버십 문제로 오인 방지)
인증 비활성 배포(GEND_AUTH_ENABLED=false)	패스스루 — 식별할 호출자가 없어 펜스 기준값을 만들 수 없고, 인증이 꺼진 이상 다른 평면도 모두 열려 있습니다

• 다른 워크스페이스의 intel 데이터가 필요하면 마켓플레이스 구독을 사용하세요(ADR-0035 D-4) — 소유 워크스페이스 관리자가 도구를 배포하면 구독자가 호출할 수 있습니다.
• 이 변경 전 적재된 데이터는 D-5 재태깅으로 소유 워크스페이스(finance-invest)에 수렴돼 있습니다 — 별도 조치 불필요.

실행·상태 확인

• 행의 실행 액션(또는 POST /api/v1/intel/sources/{id}/run)으로 수동 실행 — 응답에 records_count/error_count/new_checkpoint 가 즉시 반환됩니다.
• Bronze 워크스페이스 스탬프: 적재 행의 workspace_id 는 실행한 사람이 아니라 소스 소유 워크스페이스(IntelSource.workspace_id) 기준입니다 (ADR-0035 D-2) — 누가·어떤 활성 워크스페이스에서 실행하든 같은 소스의 신규 데이터는 같은 파티션에 쌓이고, Silver 와도 일치합니다. 실행은 소유 워크스페이스 자격이 있는 사용자(또는 플랫폼 관리자)로 제한됩니다.
  • 과도기 주의: 기존 적재분은 ADR-0035 D-5 재태깅 전까지 종전 파티션에 남아 있고, dedup 은 파티션 내부에서만 적용됩니다 — 레거시 파티션의 동일 내용은 skipped 로 잡히지 않습니다. 소유 워크스페이스가 비어 있는 레거시 소스는 백필 전까지 종전대로 실행자 워크스페이스로 적재됩니다.
• Bronze 중복 정책: 관리형 collector 도 셀프서비스 파이프라인 sink 와 동일하게 content_hash dedup 을 적용합니다 (#2469) — 같은 파라미터로 재실행해도 내용이 동일한 레코드는 Bronze 에 다시 쌓이지 않으며, 응답 bronze.skipped 로 건너뛴 건수를 확인할 수 있습니다 (records_count 는 수집 건수, bronze.row_count 는 실제 신규 적재 건수).
• 실행 결과의 "bronze: 0 rows · 중복 N 건 스킵" 은 실패가 아니라 dedup 의 정상 동작입니다 (#2670) — 수집분 전체가 이미 적재된 내용과 동일했다는 뜻입니다. 토스트와 마지막 수집 결과 패널 양쪽에 표기됩니다:

• 강제 재적재가 필요하면: dedup 은 content_hash 기준이므로 checkpoint_json 을 되돌려도 재적재되지 않습니다. 해당 Bronze 행을 먼저 삭제해야 합니다.

  Bronze 는 영구 보존 원장 — 삭제는 되돌릴 수 없습니다

  Bronze 테이블은 모든 워크스페이스가 공유하는 단일 테이블이고 workspace_id 는 파티션이 아니라 일반 컬럼입니다. 따라서 workspace_id 술어를 반드시 포함해야 합니다 — 빠뜨리면 같은 external_id 를 수집한 다른 테넌트의 행과 전사(NULL) 행까지 영구 삭제됩니다.

  이 DELETE 는 GenD SQL 편집기로 실행할 수 없습니다(SqlGuard SELECT-only) — 플랫폼 운영자가 Trino CLI/JDBC 로 직접 실행합니다.

  -- 1) 영향 범위 먼저 확인 (테이블명은 실행 결과 패널의 table_fqn 값)
  SELECT workspace_id, count(*) FROM <table_fqn>
  WHERE external_id = '<id>' GROUP BY workspace_id;
  
  -- 2) 관리형(전사) 적재분
  DELETE FROM <table_fqn> WHERE external_id = '<id>' AND workspace_id IS NULL;
  -- 2') 특정 워크스페이스 적재분
  DELETE FROM <table_fqn> WHERE external_id = '<id>' AND workspace_id = '<ws-uuid>';

  셀프서비스 파이프라인의 본문 백필 커서 리셋은 REST Source QA 가이드 §백필의 런북을 따릅니다.

• last_status = success/failed/idle. 주의: 키 미주입 등으로 팩토리 단계에서 거부되면 failed 가 아니라 idle 로 남을 수 있습니다 — enabled 인데 last_run_at 이 갱신되지 않으면 키 주입 상태를 먼저 확인하세요.

• Silver 반영은 intel_source_dynamic_partition_sensor (Dagster) 가 담당 — Bronze 는 신선한데 Silver 가 안 늘면 해당 센서의 RUNNING 여부를 확인하세요.

관련 API

/api/v1/intel/sources — 목록/생성/수정/실행. 상세 스키마는 API Reference 참조.

관련 가이드

• Intel Platform — Collector API Key 운영 — 키 발급처·주입 절차 (운영자)
• REST Source QA 가이드 — 관리형 수집기 대신 워크스페이스 셀프서비스로 REST API 를 수집하는 경로