⚙️ [기능추가][AI] SEC EDGAR 공식 공시 수집 파이프라인 추가

[twq110]

📝 현재 문제점

• 현재 데이터 수집기는 뉴스·시장 데이터 중심이며, 투자 이벤트의 기준 시각과 원문 근거가 되는 SEC 공식 공시 파이프라인이 없습니다.
• 공시별 accession number, 접수 시각, 원문 및 Exhibit가 표준화되어 있지 않아 뉴스 연결·AI 근거 추출·이벤트 수익률 계산을 안정적으로 재실행하기 어렵습니다.
• Form 4의 주식 보상·옵션 행사까지 단순 매수·매도로 분류하면 내부자 거래 신호가 왜곡될 수 있습니다.

🛠️ 해결 방안 / 제안 기능

• SEC EDGAR를 기준 원천으로 사용하는 서버 측 공시 수집 파이프라인을 구현합니다.
• CIK↔Ticker 매핑과 Submissions API를 이용해 8-K 및 Form 4 제출 이력을 수집합니다.
• 8-K Item 2.02·5.02의 본문과 관련 Exhibit를 저장하고, Form 4 XML은 구조화된 거래 데이터로 변환합니다.
• Form 4의 신호 대상은 우선 비파생 증권 거래코드 P(매수)와 S(매도)로 제한합니다.
• accession number를 고유 키로 사용해 중복을 방지하고, 실패 후에도 안전하게 재실행할 수 있도록 upsert를 적용합니다.
• SEC 자동 접근 정책에 맞는 식별 가능한 User-Agent를 사용하고 전체 요청을 초당 10회 이하로 제한하며, 캐시·재시도·지수 백오프를 적용합니다.
• 저장된 공시 메타데이터와 원문을 조회할 수 있는 백엔드 API를 제공합니다.

⚙️ 작업 내용

• CIK↔Ticker 매핑 수집 및 갱신 로직 구현
• SEC Submissions API 클라이언트 구현
• 8-K Item 코드 필터링 및 이벤트 유형 정규화
• accession number·accepted_at·filing_date·primary_document 저장
• 8-K Item 2.02 본문 및 Exhibit 99.1 수집
• 8-K Item 5.02 본문 및 관련 Exhibit 수집
• Form 4 원문 XML 수집 및 파서 구현
• Form 4 발행사·보고자·직책·거래일·거래코드·수량·가격·거래 후 보유량 추출
• Form 4 비파생 증권 거래코드 P·S만 신호 대상으로 분리
• 주식 보상·옵션 행사·파생증권 거래를 P·S 신호와 구분해 원본 데이터로 보존
• SEC 요청 속도 제한, 식별 User-Agent, 로컬 캐시, 타임아웃 및 재시도 구현
• accession number 기준 멱등 upsert와 중복 수집 방지
• 개별 공시 실패가 전체 배치를 중단하지 않도록 실패 격리 및 로그 구현
• 공시 목록·상세·원문 조회용 백엔드 API 구현
• HTML·XML fixture 기반 단위 테스트 작성
• 실제 SEC 표본을 이용한 통합 테스트 작성
• 실행 방법·환경변수·데이터 스키마·API 명세를 한글로 문서화

완료 조건:

• 동일 수집 구간을 두 번 실행해도 중복 레코드가 생성되지 않음
• 8-K 2.02, 8-K 5.02, Form 4 표본을 각각 정상 수집
• Form 4 P·S 거래와 보상·옵션·파생 거래가 구분됨
• 모든 공시에 accession number, accepted_at, SEC 원문 URL이 저장됨
• 요청 속도가 전체 프로세스 기준 초당 10회를 초과하지 않음
• 네트워크 오류와 SEC 제한 응답 이후 재실행 가능
• 공시 목록·상세 API에서 저장 결과 조회 가능
• 단위 테스트와 실제 표본 통합 테스트 통과

참고 자료:

• SEC EDGAR Application Programming Interfaces
• SEC Webmaster FAQ 및 자동 접근 정책
• SEC EDGAR Ownership XML Technical Specification

🙋‍♂️ 담당자

• 백엔드: @twq110
• AI: @twq110
• 프론트엔드: 해당 없음
• 디자인: 해당 없음