---
name: financial-notes-extraction
description: 재무제표 주석 자동 추출 및 검색 시스템
---
# 재무제표 주석 추출 가이드
## 개요
이 skill은 재무제표 주석 자동 추출 시스템의 구조와 사용 방법을 설명합니다. XML 공시서류에서 연결재무제표 주석, 재무제표 주석, 사업의 내용, 회사의 개요를 동적으로 추출하고 구조화된 캐시로 저장합니다.
## 사용 시나리오
- 재무제표 주석 추출 로직 수정
- 새로운 섹션 추출 추가
- 검색 기능 개선
- 캐시 구조 변경
## 시스템 아키텍처
### 추출 프로세스
```mermaid
graph TD
A[공시서류 XML 다운로드] --> B[XML 파싱]
B --> C{재무제표 주석 존재?}
C -->|Yes| D[섹션 탐지]
C -->|No| E[에러 반환]
D --> F[연결재무제표 주석 추출]
D --> G[재무제표 주석 추출]
D --> H[사업의 내용 추출]
D --> I[회사의 개요 추출]
F --> J[테이블 및 문단 분리]
G --> J
H --> K[하위 섹션 분리]
I --> K
J --> L[JSON 구조화]
K --> L
L --> M[캐시 저장]
M --> N[검색 가능 상태]
```
### 캐시 구조
```
disclosure_cache/
└── financial_notes_{rcp_no}/
├── metadata.json
├── consolidated_notes/ # 3. 연결재무제표 주석
│ ├── metadata.json
│ ├── tables/ # 테이블 JSON 파일들
│ └── paragraphs/ # 문단 JSON 파일들
├── separate_notes/ # 5. 재무제표 주석
│ ├── metadata.json
│ ├── tables/
│ └── paragraphs/
├── business_content/ # II. 사업의 내용
│ ├── metadata.json
│ └── subsections/
│ ├── 1_사업의_개요/
│ ├── 2_영업의_현황/
│ └── ...
└── company_overview/ # I. 회사의 개요
├── metadata.json
└── subsections/
├── 1_회사의_개요/
├── 2_회사의_연혁/
└── ...
```
## 구현 가이드
### 1. 섹션 탐지
`financial_notes_extractor.py`의 섹션 탐지 함수들:
```python
# 연결재무제표 주석 및 재무제표 주석 탐지
sections = detect_financial_notes_sections(xml_content)
# 회사의 개요 탐지
overview_sections = detect_company_overview_sections(xml_content)
# 사업의 내용 탐지
business_sections = detect_business_content_sections(xml_content)
```
### 2. 추출 실행
```python
from mcp_opendart.utils.financial_notes_extractor import extract_financial_notes
# 재무제표 주석 추출
extracted_data = extract_financial_notes(
xml_content=xml_content,
corp_name="삼성전자",
rcp_no="20240101000001"
)
# 결과 구조
{
"status": "000",
"sections": {
"consolidated_notes": {...},
"separate_notes": {...},
"business_content": {...},
"company_overview": {...}
}
}
```
### 3. 캐시 저장
```python
from mcp_opendart.utils.financial_notes_extractor import save_extracted_data
# 추출된 데이터 저장
save_path = "disclosure_cache/financial_notes_20240101000001"
saved_path = save_extracted_data(extracted_data, save_path)
```
### 4. 검색 기능
`search_financial_notes` tool 사용:
```python
# 키워드 검색
results = search_financial_notes(
rcp_no="20240101000001",
search_term="매출액",
section_type="all", # 또는 "consolidated_notes", "separate_notes" 등
search_in="both", # "tables", "paragraphs", "both"
case_sensitive=False,
max_results=50
)
```
## 섹션별 추출 로직
### 1. 연결재무제표 주석 / 재무제표 주석
- **탐지**: TITLE 태그 패턴 매칭
- **추출**: 테이블과 문단 분리
- **저장**: `tables/`, `paragraphs/` 디렉토리
### 2. 사업의 내용
- **탐지**: "II. 사업의 내용" 패턴
- **추출**: 하위 섹션별 분리
- **저장**: `subsections/` 디렉토리
### 3. 회사의 개요
- **탐지**: "I. 회사의 개요" 패턴
- **추출**: 하위 섹션별 분리
- **저장**: `subsections/` 디렉토리
## 예제
### 예제 1: 재무제표 주석 추출
```python
# ds001.py의 extract_financial_notes_document 메서드
def extract_financial_notes_document(self, rcp_no: str) -> Dict[str, Any]:
# XML 다운로드
xml_content = self.get_disclosure_document(rcp_no)["xml_content"]
# 재무제표 주석 추출
from ..utils.financial_notes_extractor import extract_financial_notes
extracted_data = extract_financial_notes(xml_content, corp_name, rcp_no)
# 캐시 저장
from ..utils.financial_notes_extractor import save_extracted_data
save_path = project_root / 'mcp_opendart' / 'utils' / 'data' / 'disclosure_cache' / f'financial_notes_{rcp_no}'
save_extracted_data(extracted_data, str(save_path))
return extracted_data
```
### 예제 2: 검색 결과 활용
```python
# search_financial_notes tool에서
results = {
"status": "000",
"results": {
"tables": [
{
"section": "consolidated_notes",
"table_id": "table_001",
"headers": ["항목", "금액"],
"matched_content": "매출액 관련 테이블"
}
],
"paragraphs": [
{
"section": "separate_notes",
"content": "매출액은 주요 사업부문에서 발생...",
"line_number": 1234
}
]
}
}
```
## 주의사항
1. **하드코딩 최소화**
- 섹션 탐지는 패턴 매칭 사용
- 하드코딩된 섹션명 지양
2. **에러 처리**
- 재무제표 주석이 없으면 명확한 에러 메시지
- 다른 보고서를 찾아보라는 안내 제공
3. **캐시 무효화**
- 현재는 수동 삭제만 가능
- 필요시 재추출 로직 추가
4. **성능**
- 대용량 XML 파일 처리 고려
- 메모리 효율적인 파싱 사용
5. **검색 정확도**
- 유사도 매칭 사용 (20% 이상)
- 섹션명 매칭 시 전체 내용 포함
## 관련 파일
- [src/mcp_opendart/utils/financial_notes_extractor.py](src/mcp_opendart/utils/financial_notes_extractor.py) - 추출 로직
- [src/mcp_opendart/apis/ds001.py](src/mcp_opendart/apis/ds001.py) - 추출 호출
- [src/mcp_opendart/tools/disclosure_tools.py](src/mcp_opendart/tools/disclosure_tools.py) - search_financial_notes tool
