PRD.md

PRD: 금융공시 및 주요 공고 크롤링 + 부서 자동 매칭 서비스

문서 버전: v2.0
최초 작성일: 2026-06-17
최종 수정일: 2026-06-19
주요 변경 (v1.0 → v2.0): BGE-M3 모델 전환, Cross-Encoder 재순위화 추가, 단일 모델 디렉터리 구조로 통합, 백엔드 실제 구현 반영

---

1. 개요 (Overview)

1.1 배경

금융위원회, 금융감독원, 법제처 등 금융 유관 기관은 매일 수십 건의 보도자료·공시·공고를 발행한다. 담당 부서 직원은 이를 수동으로 모니터링하고 본인 업무 관련 항목을 선별해야 하는데, 기관별 사이트를 직접 방문해야 하고 "이 공고가 어느 팀 소관인지" 파악하는 데 추가 시간이 소요된다.

1.2 서비스 목적

• 주요 금융 기관의 공시·공고를 시간 단위로 자동 수집
• 각 공고의 본문 내용을 분석하여 사내 담당 부서를 자동 매칭해 함께 노출
• 담당자가 단일 화면에서 관련 공시를 빠르게 파악하고 후속 조치를 취할 수 있도록 지원

1.3 참조 서비스

• 프론트엔드: newstogram.xyz (금융당국 모니터링 봇) — 기관별 카테고리, 기간 필터, Telegram 연동 구조 참조
• 백엔드 모델: v4.1.ipynb — BAAI/bge-m3 기반 두 단계 파인튜닝 + Cross-Encoder 재순위화

---

2. 목표 및 성공 지표 (Goals & KPIs)

목표	측정 지표	목표값
공시 수집 지연 최소화	기관 원문 게시 → 서비스 노출 소요 시간	≤ 1시간
부서 매칭 정확도	Top-1 정확도 (내부 테스트셋 기준)	≥ 80%
부서 매칭 후보 포함률	Top-5 내 정답 부서 포함율	≥ 95%
서비스 가용성	월간 업타임	≥ 99.5%
크롤링 성공률	수집 시도 대비 성공 건수	≥ 99%

---

3. 사용자 및 이해관계자 (Stakeholders)

구분	역할	주요 니즈
내부 업무 담당자	1차 사용자	본인 부서 소관 공고 빠른 파악
부서 관리자	2차 사용자	팀 전체 모니터링 현황 파악
컴플라이언스 팀	이해관계자	규제 변화 대응 현황 추적
IT/개발팀	운영자	크롤러 안정성, 모델 재학습 관리

---

4. 크롤링 대상 및 범위 (Data Sources)

4.1 수집 기관 및 카테고리

기관	카테고리	수집 주기	URL 패턴
금융위원회	보도자료, 고시·공고, 의결 결과	매 1시간	fsc.go.kr
금융감독원	보도자료, 제재·제도 공시	매 1시간	fss.or.kr
금융정보분석원 (KoFIU)	보도자료, 고시	매 1시간	kofiu.go.kr
법령해석포털 (법제처)	법령해석, 의견서	매 2시간	moleg.go.kr
한국은행	금통위 의결, 보도자료	매 2시간	bok.or.kr

참조: newstogram.xyz의 기관 구조(금융감독원·금융위원회·금융정보분석원·법령해석포털·한국은행)를 기반으로 설계

4.2 수집 필드

- 제목 (title)
- 발행 기관 (source_agency)
- 카테고리 (category)
- 게시일시 (published_at)
- 원문 URL (url)
- 본문 텍스트 (body_text)
- 담당부서명 (author_dept) — 원문에 기재된 경우 추출
- 담당자명 / 연락처 (contact_info) — 원문에 기재된 경우 추출
- 첨부파일 링크 목록 (attachments)

---

5. 부서 자동 매칭 기능 (Department Auto-Matching)

5.1 모델 개요 (v4.1.ipynb 기반)

핵심 구조: BGE-M3 Hybrid Retrieval → Cross-Encoder Re-ranking

공시 본문 텍스트 (query, 길이 제한 없음 — BGE-M3 최대 8192 토큰)
        ↓ preprocess(): 제목 + 담당부서 힌트 + 본문 구조화
  ┌─────────────────────────────────────────────────────┐
  │  학습 파이프라인 (Google Colab GPU, v4.1.ipynb)       │
  │                                                     │
  │  Stage 1: 도메인 적응                                │
  │    Base  : BAAI/bge-m3 (570M 파라미터, 8192 토큰)    │
  │    데이터 : 업무담당규정.docx (문단 단위 self-positive) │
  │    Loss  : MultipleNegativesRankingLoss              │
  │       ↓ 저장 → bge_m3_finetuned/                   │
  │                                                     │
  │  Stage 2: 부서 매칭 특화                              │
  │    Base  : bge_m3_finetuned/ (Stage 1 출력)          │
  │    데이터 : dept.xlsx (단일 업무문장 + 부서+업무 조합   │
  │            + 무작위 3~5개 업무 결합 증강)             │
  │    Loss  : MultipleNegativesRankingLoss              │
  │       ↓ 저장 → bge_m3_finetuned/ (덮어쓰기)         │
  └─────────────────────────────────────────────────────┘
        ↓ (최종 모델: bge_m3_finetuned/)
  ┌──────────────┬──────────────┬──────────────┐
  │ Dense Score  │ TF-IDF Score │ BM25 Score   │
  │ BGE-M3 임베딩│ (char 2-5gram)│ (토큰 기반)  │
  │    55%       │    25%       │    20%       │
  └──────────────┴──────────────┴──────────────┘
        ↓ Min-Max 정규화 + 가중 합산
  상위 120개 후보 (CANDIDATE_K=120)
        ↓
  ┌─────────────────────────────────────────────┐
  │  Cross-Encoder Re-ranking (RERANK_TOP_K=10) │
  │  모델: BAAI/bge-reranker-v2-m3              │
  │  confidence = sigmoid(s0)*0.7 + gap*0.3     │
  └─────────────────────────────────────────────┘
        ↓
  최종 부서 1건 + confidence_score 반환

이전 모델(v3.ipynb) 대비 변경 사항:

항목	v3 (구)	v4.1 (현재)
Base 모델	jhgan/ko-sroberta-multitask (122M)	BAAI/bge-m3 (570M)
최대 입력 길이	512 토큰 (길이 초과 시 정보 손실)	8192 토큰 (전체 본문 처리 가능)
언어 지원	한국어 전용	다국어 (한국어 포함)
Re-ranking	없음	Cross-Encoder (bge-reranker-v2-m3)
모델 후보 수집	top-80 → 다수결 top-5	top-120 → Cross-Encoder top-10 → top-1
신뢰도 계산	bi-encoder 점수 직접 사용	sigmoid 정규화 + gap 가중치
모델 저장 경로	stage1_domain_retriever/, stage2_dept_retriever/	bge_m3_finetuned/ (단일 경로)

5.2 입력 데이터 (dept.xlsx)

컬럼	설명
HNG_BR_NM	부서명 (한글)
OFWRK_NM	해당 부서의 업무 설명

• 부서별 5행 단위 chunk로 분할하여 검색 corpus 구성 (DEPT_CHUNK_SIZE=5)
• corpus 텍스트 형식: [부서명] {dept}\n[담당업무]\n- {work1}\n- {work2}...

5.3 쿼리 전처리 (preprocess)

# BGE-M3 (max 8192 tokens) — 길이 제한 없이 전체 본문 구조화
# 1. 첫 줄을 제목으로 분리
# 2. "담당 부서/과/팀" 힌트 문장 최대 3개 우선 배치
# 3. 나머지 본문 이어 붙임
→ "{제목} {힌트문장1} {힌트문장2} {본문전체}"

5.4 매칭 결과 스펙

{
  "dept": "디지털금융총괄과",
  "confidence": 0.87,
  "needs_review": false
}

• needs_review: confidence < CONFIDENCE_REVIEW(0.4) 시 true
• confidence: Cross-Encoder sigmoid 정규화 기반 (s0 * 0.7 + gap * 0.3)
  • Reranker 미사용 시 bi-encoder top-1 점수로 대체

5.5 모델 운영 방식

항목	내용
학습 환경	Google Colab GPU (CUDA, A100 권장)
학습 주기	dept.xlsx 업데이트 시 Stage 2 재학습 (월 1회 이상)
모델 저장	bge_m3_finetuned/ — Stage 1 저장 후 Stage 2 덮어쓰기 (단일 경로)
Drive 백업	Google Drive /bge_m3_finetuned/ 에 자동 저장 후 가중치 파일 존재 검증
추론 환경	CPU 서버 (인퍼런스는 GPU 불필요)
fallback 순서	bge_m3_finetuned/ → HF 캐시 BAAI/bge-m3 다운로드
reranker fallback	reranker_model/ → HF 캐시 BAAI/bge-reranker-v2-m3 / 로드 실패 시 bi-encoder 단독 사용
신뢰도 임계값	CONFIDENCE_AUTO=0.7 (자동 확정) / CONFIDENCE_REVIEW=0.4 (수동 검토)

---

6. 프론트엔드 요구사항 (Frontend Requirements)

newstogram.xyz 구조를 참조하되, 부서 매칭 결과 노출이 핵심 추가 기능

6.1 주요 화면 구성

6.1.1 메인 피드 화면

┌─────────────────────────────────────────────────┐
│  [로고] 금융공시 모니터링        Telegram | About │
├─────────────────────────────────────────────────┤
│  기관 탭: [전체] [금융위] [금감원] [KoFIU] [법제처] [한국은행] │
│  기간 필터: [오늘] [이번주] [이번달] [전체]          │
│  부서 필터: [전체 부서 ▼]   카테고리: [전체 ▼]       │
├─────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ [금융위원회] 보도자료  2026-06-17 14:30      │ │
│ │ "마이데이터 활용 금리인하요구 서비스" 혁신금융 3건 지정 │ │
│ │                                             │ │
│ │ 매칭 부서: 🏢 디지털금융총괄과  ████████░░ 87% │ │
│ │ 후보: 핀테크혁신과 71% | 전자금융과 60%         │ │
│ │                          [원문 보기] [공유]   │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ [금융위원회] 보도자료  2026-06-17 10:15      │ │
│ │ 연체 채무자 채권매각 관행 개선방안             │ │
│ │                                             │ │
│ │ 매칭 부서: 🏢 서민금융과        ████████░░ 83% │ │
│ │           [원문 보기] [공유]                  │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

6.1.2 공시 상세 화면

• 원문 전체 본문 표시
• 매칭 부서 정보 (Top-5 신뢰도 바 차트)
• 원문 기재 담당부서 / 담당자 / 연락처 (존재 시)
• 원문 URL 바로가기
• 첨부파일 다운로드 링크

6.1.3 부서별 대시보드

• 내 부서 필터 설정 후 저장
• 해당 부서 관련 공시만 모아보기
• 미확인 건수 뱃지 표시

6.2 UI 컴포넌트 요구사항

컴포넌트	설명
공시 카드	기관 배지, 카테고리, 제목, 게시일시, 매칭 부서 + 신뢰도
부서 매칭 바	신뢰도 % 시각화 (progress bar), 상위 3개 후보 표시
기간 필터	D(오늘) / W(이번주) / M(이번달) / ALL
기관 필터 탭	기관별 탭 + 미확인 건수 뱃지
부서 필터 드롭다운	부서명 검색 가능한 select
알림 설정	Telegram / 이메일 수신 조건 설정
신뢰도 경고	신뢰도 < 40% 시 "⚠️ 수동 검토 필요" 표시

6.3 Telegram Bot 연동

• 신규 공시 수집 즉시 구독 채널에 푸시
• 메시지 형식: [기관] 제목 | 매칭부서: {dept} ({score}%) | {url}
• 부서별 채널 분리 구독 지원

---

7. 백엔드 아키텍처 (Backend Architecture)

7.1 전체 구성 (현재 구현)

┌──────────────────────────────────────────────────────────────────┐
│                          외부 기관 사이트                          │
│  금융위 | 금감원 | KoFIU | 법제처 | 한국은행                       │
└─────────────────────┬────────────────────────────────────────────┘
                      │ HTTP/Playwright
┌─────────────────────▼────────────────────────────────────────────┐
│                     크롤러 레이어 (Crawler Layer)                  │
│  - 기관별 크롤러 모듈 (독립 스케줄, APScheduler)                   │
│  - 중복 감지 (URL unique constraint)                              │
│  - 본문 정제 (HTML → plain text)                                  │
│  - 원문 담당부서/연락처 추출 (정규식)                               │
└─────────────────────┬────────────────────────────────────────────┘
                      │ 수집 즉시 매칭 처리 (동기)
┌─────────────────────▼────────────────────────────────────────────┐
│              부서 매칭 서비스 (matcher.py)                         │
│  - BGE-M3 Hybrid Retrieval (Dense 55% + TF-IDF 25% + BM25 20%) │
│  - Cross-Encoder Re-ranking (bge-reranker-v2-m3)                │
│  - confidence = sigmoid(s0)*0.7 + gap*0.3                       │
└─────────────────────┬────────────────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────────────────┐
│                   데이터베이스 (SQLite / 운영: PostgreSQL 검토)     │
│  announcements, dept_matches, departments, crawl_logs            │
└─────────────────────┬────────────────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────────────────┐
│                    API 서버 (FastAPI + uvicorn)                   │
│  GET /api/v1/announcements  |  GET /api/v1/announcements/{id}    │
│  GET /api/v1/departments    |  POST /api/v1/match                │
└─────────────────────┬────────────────────────────────────────────┘
                      │
             ┌────────┴──────────┐
             ▼                   ▼
       웹 프론트엔드           Telegram Bot
       (Vanilla JS)           (알림 발송, 예정)
       API_BASE: localhost:8000

7.2 크롤러 설계 원칙

• 기관별 독립 모듈: 각 기관의 구조 변경이 다른 기관에 영향 없도록 분리
• 점진적 크롤링: 마지막 수집 ID/날짜 이후 신규 건만 수집
• 중복 방지: (source_agency, url) unique constraint + 제목+날짜 해시 체크
• 요청 간격 준수: 기관별 robots.txt 존중, 요청 간 1~3초 딜레이
• 에러 처리: 수집 실패 시 지수 백오프 재시도 (최대 3회)
• 스케줄러: APScheduler (BackgroundScheduler) — 기관별 독립 주기 설정

7.3 부서 매칭 모델 서빙

항목	내용
프레임워크	FastAPI + uvicorn
모델 로딩	서버 시작 시 1회 로드 (get_matcher() singleton), 메모리 상주
임베더 로드 순서	bge_m3_finetuned/ (가중치 파일 존재 확인) → HF 캐시 BAAI/bge-m3
Reranker 로드 순서	reranker_model/ → HF 캐시 BAAI/bge-reranker-v2-m3 → 없으면 bi-encoder 단독
추론 단위	공시 1건당 predict() 1회 호출
응답 SLA	건당 ≤ 500ms (CPU 기준)
가중치 파일 검증	_is_valid_model_dir() — config.json + model.safetensors 또는 pytorch_model.bin 모두 존재 시에만 로드

---

8. 데이터 모델 (Data Schema)

현재 구현: SQLite (data/announcements.db)
운영 확장: PostgreSQL 전환 검토

8.1 announcements (공시 테이블)

CREATE TABLE announcements (
    id              INTEGER      PRIMARY KEY AUTOINCREMENT,
    source_agency   VARCHAR(50)  NOT NULL,  -- 금융위원회, 금감원 등
    category        VARCHAR(50)  NOT NULL,  -- 보도자료, 고시공고, 의결결과 등
    title           TEXT         NOT NULL,
    body_text       TEXT,
    published_at    DATETIME     NOT NULL,
    url             TEXT         NOT NULL UNIQUE,
    author_dept_raw VARCHAR(100),           -- 원문 기재 담당부서
    contact_raw     TEXT,                   -- 원문 기재 담당자/연락처
    crawled_at      DATETIME     DEFAULT CURRENT_TIMESTAMP,
    is_matched      BOOLEAN      DEFAULT 0
);
CREATE INDEX idx_ann_published ON announcements(published_at DESC);
CREATE INDEX idx_ann_agency    ON announcements(source_agency);

8.2 dept_matches (부서 매칭 결과)

CREATE TABLE dept_matches (
    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
    announcement_id     INTEGER REFERENCES announcements(id),
    final_dept          VARCHAR(100),
    confidence_score    REAL,
    needs_review        BOOLEAN DEFAULT 0,
    match_method        VARCHAR(50),        -- dense+tfidf+bm25+crossencoder
    model_version       VARCHAR(30),
    matched_at          DATETIME DEFAULT CURRENT_TIMESTAMP,
    is_manual_override  BOOLEAN DEFAULT 0,
    override_dept       VARCHAR(100)
);

8.3 departments (부서 목록)

CREATE TABLE departments (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    dept_name   VARCHAR(100) NOT NULL UNIQUE,  -- HNG_BR_NM
    is_active   BOOLEAN DEFAULT 1,
    updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

8.4 crawl_logs (크롤링 이력)

CREATE TABLE crawl_logs (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    source_agency   VARCHAR(50),
    started_at      DATETIME,
    finished_at     DATETIME,
    collected_count INTEGER,
    error_count     INTEGER,
    error_detail    TEXT
);

---

9. API 설계 (API Spec)

9.1 공시 목록 조회

GET /api/v1/announcements
Query Params:
  - source_agency: string (optional)
  - category: string (optional)
  - dept: string (optional)           ← 매칭 부서 필터
  - range: D|W|M|ALL (default: W)
  - page: int (default: 1)
  - per_page: int (default: 20)
  - min_confidence: float (optional)  ← 신뢰도 임계값 필터

Response 200:
{
  "total": 142,
  "page": 1,
  "items": [
    {
      "id": 1001,
      "source_agency": "금융위원회",
      "category": "보도자료",
      "title": "마이데이터 활용 금리인하요구 서비스...",
      "published_at": "2026-06-17T14:30:00+09:00",
      "url": "https://fsc.go.kr/...",
      "matched_dept": "디지털금융총괄과",
      "confidence_score": 0.87,
      "needs_review": false
    }
  ]
}

9.2 공시 상세 조회

GET /api/v1/announcements/{id}
Response 200: 공시 전체 필드 + 매칭 결과 + 원문 담당부서/연락처

9.3 부서 목록 조회

GET /api/v1/departments
Response 200: [{ "dept_name": "디지털금융총괄과" }, ...]

9.4 수동 매칭 재요청

POST /api/v1/announcements/{id}/rematch
Body: { "override_dept": "핀테크혁신과" }  ← 생략 시 모델 재추론
Response 200: 갱신된 매칭 결과

---

10. 비기능 요구사항 (Non-Functional Requirements)

항목	요구사항
성능	공시 목록 API 응답 ≤ 200ms (DB 조회 기준)
보안	API 인증 (JWT or API Key), HTTPS 필수
로깅	크롤링 실패, 매칭 오류, API 오류 중앙 로그 수집
모니터링	크롤러 수집 건수, 매칭 성공률, 신뢰도 분포 대시보드
확장성	크롤링 대상 기관 추가 시 기존 코드 수정 최소화
데이터 보관	공시 원문 2년 보관, 크롤링 로그 6개월 보관
알림 신뢰성	Telegram 메시지 발송 실패 시 재시도 3회

---

11. 개발 로드맵 (Milestones)

Phase 1 — 크롤러 + 기본 피드 ✅ 완료

• 금융위원회, 금감원, KoFIU, 법제처, 한국은행 크롤러 구현 및 DB 적재
• FastAPI 기반 기본 API 서버 (목록/상세 조회)
• 프론트엔드 메인 피드 화면 (Vanilla JS, API_BASE: http://localhost:8000/api/v1)
• 중복 감지 (URL unique) 및 APScheduler 기반 스케줄러 설정
• SQLite 데이터베이스 (data/announcements.db)

Phase 2 — 부서 매칭 통합 ✅ 완료

• BGE-M3 (BAAI/bge-m3) 기반 Hybrid Retrieval 매칭 서비스 구현
• Cross-Encoder (BAAI/bge-reranker-v2-m3) 재순위화 통합
• 두 단계 파인튜닝 파이프라인 (v4.1.ipynb) — 단일 bge_m3_finetuned/ 경로 저장
• 프론트엔드 부서 매칭 결과 UI 통합 (실제 AI 매칭 결과 노출 확인)
• 신뢰도 임계값 기반 자동 확정 / 수동 검토 분류

Phase 3 — 알림 및 고도화 (예정)

• Telegram Bot 알림 연동
• 부서 필터 / 구독 설정 기능
• 크롤링 모니터링 대시보드
• PostgreSQL 전환 (운영 환경 스케일업 시)

Phase 4 — 안정화 및 운영 자동화 (예정)

• 모델 성능 평가 (테스트셋 기반 Top-1/Top-5 정확도 측정)
• dept.xlsx 업데이트 시 자동 모델 재학습 파이프라인
• 부서별 미확인 건수 뱃지 및 읽음 처리
• 첨부파일 다운로드 기능

---

12. 리스크 및 제약사항 (Risks & Constraints)

리스크	영향도	상태	대응 방안
기관 사이트 구조 변경으로 크롤러 파싱 실패	중	진행 중	기관별 크롤러 독립 모듈화 + 실패 알림
부서 매칭 정확도 저하 (dept.xlsx 미갱신)	중	진행 중	월 1회 dept.xlsx 업데이트 및 재학습 프로세스 수립
GPU 없이 모델 재학습 불가	중	진행 중	Google Colab GPU 활용 (Drive 저장 + 가중치 검증 자동화)
크롤링 차단 (IP 블록, robots.txt 위반)	높	진행 중	User-Agent 설정, 요청 딜레이 준수, 필요 시 IP 로테이션
공시 본문 길이 초과로 정보 손실	—	해소	BGE-M3 도입으로 최대 8192 토큰 처리 가능
Colab 세션 종료로 모델 저장 실패	중	완화	Google Drive 우선 저장 + 가중치 파일 존재 검증으로 무음 실패 방지
동일 기관 내 부서명 유사성으로 매칭 혼동	중	진행 중	Cross-Encoder 재순위화 + 매칭 불가 임계값(0.4) + 수동 검토 큐 운영

---

13. 용어 정리 (Glossary)

용어	정의
HNG_BR_NM	dept.xlsx 내 한글 부서명 컬럼
OFWRK_NM	dept.xlsx 내 업무 설명 컬럼
BGE-M3	BAAI/bge-m3 — 570M 파라미터, 8192 토큰 지원 다국어 임베딩 모델
Cross-Encoder	쿼리-문서 쌍을 직접 입력받아 관련도 점수를 출력하는 재순위화 모델 (BAAI/bge-reranker-v2-m3)
Bi-Encoder	쿼리와 문서를 각각 임베딩한 뒤 코사인 유사도로 비교하는 검색 모델 (BGE-M3)
Dense Score	BGE-M3 임베딩 코사인 유사도 (가중치 55%)
TF-IDF Score	char 2~5 gram 기반 희소 벡터 유사도 (가중치 25%)
BM25 Score	토큰 기반 확률적 검색 점수 (가중치 20%)
CANDIDATE_K	1단계 Hybrid Retrieval에서 수집하는 후보 수 (현재 120)
RERANK_TOP_K	Cross-Encoder에 넘기는 최종 후보 수 (현재 10)
Top-1 정확도	최종 예측 부서가 정답인 비율
confidence	매칭 확신도 (0~1), sigmoid(s0)*0.7 + gap*0.3 공식 적용
needs_review	confidence < 0.4 시 true, 수동 검토 큐 대상
CONFIDENCE_AUTO	자동 확정 임계값 (0.7)
CONFIDENCE_REVIEW	수동 검토 임계값 (0.4)
bge_m3_finetuned/	Stage 1 도메인 적응 후 Stage 2 부서 매칭 파인튜닝 결과를 덮어쓴 최종 단일 모델 디렉터리
APScheduler	백엔드 크롤러 주기 실행에 사용하는 Python 스케줄러 라이브러리
MultipleNegativesRankingLoss	배치 내 타 샘플을 자동 negative로 활용하는 sentence-transformers 학습 손실 함수