HTS 자동화

HTS RPA는 메리츠증권 iMeritz XII HTS의 UI를 자동으로 조작합니다. API가 제공되지 않으므로 pywinauto와 win32gui를 사용한 UI 자동화 방식을 채택합니다.

환경 요구사항

항목	요구사항
Python	64-bit (32-bit HTS와 호환 가능)
실행 권한	관리자 권한 필수
백엔드	`win32gui` (주문창) + `pywinauto` (인증서 창)

HTS 로그인 플로우

1. HTS 프로그램 실행
      ↓
2. 공동인증서 선택 팝업 자동 표시
   - 설치된 인증서 목록에서 순서로 선택
      ↓
3. 공동인증서 비밀번호 입력 → 확인
      ↓
4. 인증 완료 → 메인 프로그램 로딩
      ↓
5. 계좌 비밀번호 일괄등록 팝업 (선택적)
      ↓
6. HTS 사용 준비 완료

인증서 선택 창

창 정보:

제목 패턴: 인증서 선택.*
클래스: #32770

컨트롤 매핑:

요소	타입	ctrl_id	설명
인증서 목록	List	2026	인증서 리스트
비밀번호 입력	Edit	2061	인증서 비밀번호 입력란
확인 버튼	Button	1	”인증서 선택(확인)“
취소 버튼	Button	2	”취소(닫기)”

인증서 목록 구조:

List (ctrl_id=2026)
├── Header: 가입자명 | 만료일 | 정책등급 | 발급기관
├── ListItem: "홍길동-1234567"
│   ├── Text: 홍길동-1234567
│   ├── Text: 2026-04-28
│   ├── Text: 증권(개인)
│   └── Text: SignKorea
└── ...

주문 창 [06100]

창 정보:

제목: [06100]해외주식 주문창
화면번호: 6100

핵심 컨트롤:

요소	클래스	ctrl_id	설명
종목코드	iMeritz MaskEdit2	3860	종목코드 입력
수량	iMeritz MaskEdit	3900	주문 수량
가격	iMeritz MaskEdit	3930	주문 가격
상단 탭	SysTabControl32	3810	매수/매도 선택
하단 탭	SysTabControl32	3785	미체결/보유종목/주문가능
일괄취소	Button	3815	미체결 일괄취소

사용자 입력 차단

HTS 자동화 중 사용자의 마우스/키보드 입력으로 인한 포커스 이동을 방지합니다.

from utils.input_blocker import input_blocked

# 인증서 로그인 중 입력 차단 (타임아웃 30초)
with input_blocked("Certificate login", timeout_seconds=30):
    login_handler.login_with_certificate(...)
# 자동으로 입력 해제됨

안전 기능:

기능	설명
타임아웃 자동 해제	기본 30초, 지정 가능
프로그램 종료 시 해제	atexit 핸들러 등록
비상 탈출	Ctrl+Alt+Del로 Task Manager 접근 가능
컨텍스트 매니저	`with` 패턴으로 안전한 사용 보장

DPI 스케일링 대응

HTS는 100%와 125% DPI 환경을 모두 지원합니다. 컨트롤 좌표 계산 시 ControlFinder.scale_for_dpi()를 사용하여 DPI 스케일링에 대응합니다.

데이터 조회 방식

HTS에서 데이터를 추출할 때는 CSV Export 방식을 사용합니다.

해당 탭 선택 (미체결, 보유종목, 주문가능 등)
우클릭 → CSV 저장 메뉴 선택
임시 디렉토리에 CSV 파일 저장
CSV 파일 파싱하여 데이터 추출
임시 파일 정리

탐색 도구

창 목록 확인

python scripts/hts_inspector.py --list

특정 창 상세 탐색

python scripts/hts_inspector.py --window "창제목" --save output.txt

특정 컨트롤 유형 검색

python scripts/hts_inspector.py --window "창제목" --type Edit
python scripts/hts_inspector.py --window "창제목" --type Button

주의사항

관리자 권한: HTS 자동화 및 입력 차단 기능에 반드시 필요합니다
백엔드 선택: 인증서 창은 pywinauto (UIA), 주문창은 win32gui 사용
타이밍: 창이 완전히 로드된 후 조작해야 합니다 (적절한 wait 필요)
비밀번호 보안: 비밀번호는 Windows 자격증명관리자(keyring)에서 로드
DPI 스케일링: 좌표 계산 시 반드시 scale_for_dpi() 사용