SEC Portfolio Signals (MVP)

미국 SEC 공시 기반 포트폴리오/시그널 대시보드입니다.

• 13F 분기 보유 포트폴리오
• (기본) 최근 3회 13F 제출분까지 보유 이력 반영
• Form 4 내부자 거래
• Schedule 13D/13G 대량보유 시그널

Tech Stack

• Backend: FastAPI, SQLAlchemy, Alembic, Celery, Redis, PostgreSQL
• Frontend: Next.js(App Router), TypeScript, Tailwind, TanStack Query/Table, Recharts
• Infra: Docker Compose, Makefile

Quick Start

1. 환경변수 설정

cp .env.example .env

2. .env에서 SEC_USER_AGENT를 실제 연락처로 변경

SEC_USER_AGENT=MySECApp/1.0 (your-email@example.com)
MARKET_CACHE_TTL_SECONDS=60
MANAGER_CACHE_TTL_SECONDS=120
SYNC_AUTO_ENABLED=false
ADMIN_USERNAME=change-this-admin-id
ADMIN_PASSWORD=change-this-admin-password
ADMIN_SESSION_SECRET=change-this-session-secret
SUPER_INVESTOR_CIKS=0001067983,0001350694,0001336528,0001345471,0001549575,0002012383,0001393818,0001274173,0000914208,0000093751,0000895421,0000886982,0000831001,0000820027,0001137774,0001126328,0001099219,0000927628,0000759944,0000720005,0000720672,0000713676

3. 전체 서비스 실행

make install
make up

4. 접속

• Frontend: http://localhost:3000
• API: http://localhost:8000/api

운영 배포 (권장: VPS + Docker Compose)

1. 서버 준비 (Ubuntu 22.04+, Docker/Compose 설치)
2. 레포 클론 후 .env 설정

SEC_USER_AGENT=MySECApp/1.0 (your-email@example.com)
DOMAIN=app.yourdomain.com
CORS_ORIGINS=https://app.yourdomain.com
NEXT_PUBLIC_API_BASE_URL=https://app.yourdomain.com/api
SYNC_AUTO_ENABLED=false
ADMIN_USERNAME=change-this-admin-id
ADMIN_PASSWORD=change-this-admin-password
ADMIN_SESSION_SECRET=change-this-session-secret

3. DNS에서 app.yourdomain.com -> 서버 공인 IP 연결
4. 프로덕션 실행

make up-prod

5. 확인

• 웹: https://app.yourdomain.com
• 헬스체크: https://app.yourdomain.com/api/healthz

6. 보안 권장

• 방화벽은 80/443만 외부 오픈
• 5432/6379는 외부에 열지 않기
• ADMIN_PASSWORD를 충분히 강하게 설정
• ADMIN_SESSION_SECRET를 충분히 긴 랜덤 문자열로 설정

프로덕션 관련 파일

• docker-compose.prod.yml
• deploy/Caddyfile
• deploy/EC2_RUNBOOK.md
• deploy/ec2/bootstrap-ubuntu.sh
• deploy/ec2/deploy.sh

외부 기기(같은 Wi-Fi) 접속

localhost 대신 개발 머신 IP를 사용하세요.

예시 (HOST_IP=192.168.0.10):

CORS_ORIGINS=http://localhost:3000,http://192.168.0.10:3000
NEXT_PUBLIC_API_BASE_URL=http://192.168.0.10:8000/api

예시 CIK

• Berkshire Hathaway: 0001067983
• Bridgewater Associates: 0001350694
• Pershing Square Capital: 0001336528

사용 방법

1. /admin에서 관리자 로그인
2. /managers에서 전체 운용사 검색(이름/CIK)
3. /super-investors에서 수퍼투자자만 분리 조회/동기화
4. /compare에서 내 포트폴리오를 입력해 유사한 운용사/수퍼투자자 비교
5. 상세(/managers/[cik] 또는 /super-investors/[cik])에서 Portfolio / Changes / Signals / Filings 확인
6. Sync 버튼 또는 POST /api/managers/super-investors/sync로 최신 공시 동기화
   • Sync/Job API는 관리자 로그인 세션(Authorization: Bearer <access_token>)이 필요합니다.

주요 API

• GET /api/managers
• GET /api/managers/super-investors
• GET /api/managers/{cik}
• GET /api/managers/{cik}/portfolio
• GET /api/managers/{cik}/changes
• GET /api/managers/{cik}/signals
• GET /api/managers/{cik}/filings
• POST /api/managers/{cik}/sync
• POST /api/managers/super-investors/sync
• POST /api/market/portfolio-compare
• GET /api/jobs/{job_id}

Sync/Job 인증 헤더

curl -X POST "http://localhost:8000/api/admin/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"<ADMIN_USERNAME>","password":"<ADMIN_PASSWORD>"}'

curl -X POST "http://localhost:8000/api/managers/super-investors/sync" \
  -H "Authorization: Bearer <access_token>"

EC2 배포 준비

cp deploy/.env.ec2.example .env
bash deploy/ec2/deploy.sh

자세한 절차는 deploy/EC2_RUNBOOK.md를 참고하세요.

개발 커맨드

make install
make up
make down
make up-prod
make down-prod
make logs-prod
make test
make lint

투자 고지

이 프로젝트는 공개 공시 데이터 시각화 도구이며 투자 조언이 아닙니다.