Standardize overseas stock symbol formats across systems

- Introduce symbol conversion utilities (`to_kis_symbol`, `to_yahoo_symbol`, `to_db_symbol`) in `symbol.py` for consistent formatting between DB, KIS API, and Yahoo Finance.
- Migrate existing DB data to standardized `.` format using `migrate_symbols_to_dot_format.sql`.
- Update services and tasks to handle symbol normalization automatically: KIS APIs, Yahoo Finance fetch, trading services, and manual holdings comparisons.
- Add comprehensive tests for symbol conversion utilities and real-world scenario validations.

Author: robin-watcha

CLAUDE.md

@@ -156,6 +156,47 @@ stock_info (마스터 테이블)        stock_analysis_results (분석 결과)
 - 최신 분석: Correlated Subquery 또는 Window Function 사용
 - 히스토리: `stock_info_id`로 JOIN하여 시간순 정렬
 
+### 해외주식 심볼 변환 시스템
+
+**배경:** 해외주식 심볼은 서비스마다 다른 구분자를 사용함 (예: 버크셔 해서웨이 B)
+- Yahoo Finance: `BRK-B` (하이픈)
+- 한국투자증권 API: `BRK/B` (슬래시)
+- DB 저장 형식: `BRK.B` (점) ← **기준**
+
+**구조:**
+```
+app/core/symbol.py              # 심볼 변환 유틸리티
+├── to_kis_symbol()             # DB → KIS API (. → /)
+├── to_yahoo_symbol()           # DB → Yahoo Finance (. → -)
+└── to_db_symbol()              # 외부 → DB (- 또는 / → .)
+```
+
+**적용된 파일:**
+- `app/services/kis.py` - KIS API 호출 시 자동 변환
+- `app/services/yahoo.py` - Yahoo Finance 호출 시 자동 변환
+- `app/tasks/kis.py` - 심볼 비교 시 정규화
+- `app/services/kis_holdings_service.py` - 보유주식 조회 시 정규화
+- `app/services/kis_trading_service.py` - 매도 주문 시 정규화
+
+**DB 테이블 (해외주식 심볼 저장):**
+| 테이블 | 컬럼 | 설명 |
+|--------|------|------|
+| `stock_info` | `symbol` | 종목 마스터 |
+| `manual_holdings` | `ticker` | 수동 잔고 (토스 등) |
+| `stock_aliases` | `ticker` | 종목 별칭 매핑 |
+| `symbol_trade_settings` | `symbol` | 종목별 거래 설정 |
+
+**마이그레이션:** 기존 데이터가 `-` 또는 `/` 형식이면 `.` 형식으로 변환 필요
+```bash
+# scripts/migrate_symbols_to_dot_format.sql 실행
+psql -d your_db -f scripts/migrate_symbols_to_dot_format.sql
+```
+
+**테스트:**
+```bash
+uv run pytest tests/test_symbol_conversion.py -v
+```
+
 ### API 서비스 클라이언트
 
 ```

scripts/migrate_symbols_to_dot_format.sql

@@ -0,0 +1,46 @@
+-- 해외주식 심볼 형식 정규화 마이그레이션
+-- 하이픈(-) 또는 슬래시(/) 형식을 점(.) 형식으로 변환
+--
+-- 실행 전 백업 권장:
+-- pg_dump -t stock_info -t manual_holdings -t stock_aliases -t symbol_trade_settings your_db > backup.sql
+
+-- 1. stock_info 테이블 (해외주식만 - instrument_type이 equity_us인 경우)
+UPDATE stock_info
+SET symbol = REPLACE(REPLACE(symbol, '-', '.'), '/', '.')
+WHERE instrument_type = 'equity_us'
+  AND (symbol LIKE '%-%' OR symbol LIKE '%/%');
+
+-- 2. manual_holdings 테이블 (해외주식만 - market_type이 US인 경우)
+UPDATE manual_holdings
+SET ticker = REPLACE(REPLACE(ticker, '-', '.'), '/', '.')
+WHERE market_type = 'US'
+  AND (ticker LIKE '%-%' OR ticker LIKE '%/%');
+
+-- 3. stock_aliases 테이블 (해외주식만 - market_type이 US인 경우)
+UPDATE stock_aliases
+SET ticker = REPLACE(REPLACE(ticker, '-', '.'), '/', '.')
+WHERE market_type = 'US'
+  AND (ticker LIKE '%-%' OR ticker LIKE '%/%');
+
+-- 4. symbol_trade_settings 테이블 (해외주식만 - instrument_type이 equity_us인 경우)
+UPDATE symbol_trade_settings
+SET symbol = REPLACE(REPLACE(symbol, '-', '.'), '/', '.')
+WHERE instrument_type = 'equity_us'
+  AND (symbol LIKE '%-%' OR symbol LIKE '%/%');
+
+-- 변경된 레코드 확인
+SELECT 'stock_info' as table_name, COUNT(*) as count
+FROM stock_info
+WHERE instrument_type = 'equity_us' AND symbol LIKE '%.%'
+UNION ALL
+SELECT 'manual_holdings', COUNT(*)
+FROM manual_holdings
+WHERE market_type = 'US' AND ticker LIKE '%.%'
+UNION ALL
+SELECT 'stock_aliases', COUNT(*)
+FROM stock_aliases
+WHERE market_type = 'US' AND ticker LIKE '%.%'
+UNION ALL
+SELECT 'symbol_trade_settings', COUNT(*)
+FROM symbol_trade_settings
+WHERE instrument_type = 'equity_us' AND symbol LIKE '%.%';

tests/test_symbol_conversion.py

@@ -0,0 +1,134 @@
+"""
+해외주식 심볼 변환 유틸리티 테스트
+
+심볼 형식:
+- DB (기준): `.` (예: BRK.B)
+- Yahoo Finance: `-` (예: BRK-B)
+- KIS API: `/` (예: BRK/B)
+"""
+import pytest
+
+from app.core.symbol import to_db_symbol, to_kis_symbol, to_yahoo_symbol
+
+
+class TestToKisSymbol:
+    """to_kis_symbol 함수 테스트 (DB → KIS API)"""
+
+    def test_converts_dot_to_slash(self):
+        """`.`을 `/`로 변환"""
+        assert to_kis_symbol("BRK.B") == "BRK/B"
+        assert to_kis_symbol("BRK.A") == "BRK/A"
+
+    def test_simple_symbol_unchanged(self):
+        """구분자 없는 심볼은 그대로 유지"""
+        assert to_kis_symbol("AAPL") == "AAPL"
+        assert to_kis_symbol("NVDA") == "NVDA"
+        assert to_kis_symbol("TSLA") == "TSLA"
+
+    def test_multiple_dots(self):
+        """다중 `.` 처리"""
+        assert to_kis_symbol("A.B.C") == "A/B/C"
+
+    def test_empty_string(self):
+        """빈 문자열 처리"""
+        assert to_kis_symbol("") == ""
+
+
+class TestToYahooSymbol:
+    """to_yahoo_symbol 함수 테스트 (DB → Yahoo Finance)"""
+
+    def test_converts_dot_to_hyphen(self):
+        """`.`을 `-`로 변환"""
+        assert to_yahoo_symbol("BRK.B") == "BRK-B"
+        assert to_yahoo_symbol("BRK.A") == "BRK-A"
+
+    def test_simple_symbol_unchanged(self):
+        """구분자 없는 심볼은 그대로 유지"""
+        assert to_yahoo_symbol("AAPL") == "AAPL"
+        assert to_yahoo_symbol("NVDA") == "NVDA"
+
+    def test_multiple_dots(self):
+        """다중 `.` 처리"""
+        assert to_yahoo_symbol("A.B.C") == "A-B-C"
+
+    def test_empty_string(self):
+        """빈 문자열 처리"""
+        assert to_yahoo_symbol("") == ""
+
+
+class TestToDbSymbol:
+    """to_db_symbol 함수 테스트 (외부 형식 → DB)"""
+
+    def test_converts_hyphen_to_dot(self):
+        """Yahoo 형식 `-`를 `.`으로 변환"""
+        assert to_db_symbol("BRK-B") == "BRK.B"
+        assert to_db_symbol("BRK-A") == "BRK.A"
+
+    def test_converts_slash_to_dot(self):
+        """KIS 형식 `/`를 `.`으로 변환"""
+        assert to_db_symbol("BRK/B") == "BRK.B"
+        assert to_db_symbol("BRK/A") == "BRK.A"
+
+    def test_simple_symbol_unchanged(self):
+        """구분자 없는 심볼은 그대로 유지"""
+        assert to_db_symbol("AAPL") == "AAPL"
+        assert to_db_symbol("NVDA") == "NVDA"
+
+    def test_already_dot_format(self):
+        """이미 `.` 형식인 심볼은 그대로 유지"""
+        assert to_db_symbol("BRK.B") == "BRK.B"
+
+    def test_mixed_separators(self):
+        """혼합 구분자 처리 (모두 `.`로 변환)"""
+        assert to_db_symbol("A-B/C") == "A.B.C"
+
+    def test_empty_string(self):
+        """빈 문자열 처리"""
+        assert to_db_symbol("") == ""
+
+
+class TestRoundTrip:
+    """왕복 변환 테스트"""
+
+    @pytest.mark.parametrize("symbol", [
+        "AAPL",
+        "BRK.B",
+        "NVDA",
+        "TSLA",
+        "A.B.C",
+    ])
+    def test_kis_roundtrip(self, symbol: str):
+        """DB → KIS → DB 왕복 변환"""
+        kis_symbol = to_kis_symbol(symbol)
+        back_to_db = to_db_symbol(kis_symbol)
+        assert back_to_db == symbol
+
+    @pytest.mark.parametrize("symbol", [
+        "AAPL",
+        "BRK.B",
+        "NVDA",
+        "TSLA",
+    ])
+    def test_yahoo_roundtrip(self, symbol: str):
+        """DB → Yahoo → DB 왕복 변환"""
+        yahoo_symbol = to_yahoo_symbol(symbol)
+        back_to_db = to_db_symbol(yahoo_symbol)
+        assert back_to_db == symbol
+
+
+class TestRealWorldSymbols:
+    """실제 사용되는 심볼 테스트"""
+
+    @pytest.mark.parametrize("db_symbol,kis_symbol,yahoo_symbol", [
+        ("BRK.B", "BRK/B", "BRK-B"),  # 버크셔 해서웨이 B
+        ("BRK.A", "BRK/A", "BRK-A"),  # 버크셔 해서웨이 A
+        ("AAPL", "AAPL", "AAPL"),     # 애플 (구분자 없음)
+        ("NVDA", "NVDA", "NVDA"),     # 엔비디아 (구분자 없음)
+        ("CONY", "CONY", "CONY"),     # CONY ETF (구분자 없음)
+    ])
+    def test_symbol_conversions(self, db_symbol: str, kis_symbol: str, yahoo_symbol: str):
+        """실제 심볼 변환 검증"""
+        assert to_kis_symbol(db_symbol) == kis_symbol
+        assert to_yahoo_symbol(db_symbol) == yahoo_symbol
+        assert to_db_symbol(kis_symbol) == db_symbol
+        assert to_db_symbol(yahoo_symbol) == db_symbol