스킬 정리 및 리팩토링

common-docs/api-reference/kis-error-code-reference.md

@@ -0,0 +1,30 @@
+# KIS 오류코드 적용 기준 (2026-02-26)
+
+## 1) 기준 소스
+- 공식 오류코드 페이지: `https://apiportal.koreainvestment.com/faq-error-code`
+- 확인 방식: 실제 브라우저 렌더링 후 테이블 추출
+- 코드 반영 위치: `lib/kis/error-codes.ts`
+
+## 2) 코드 반영 목적
+- `msg_cd`만 보일 때 의미를 바로 알기 어렵기 때문에,
+  코드와 문구를 같이 표시해 장애 원인 파악 속도를 높입니다.
+- 토큰 발급/폐기, REST 호출, 웹소켓 제어 오류 메시지의 형식을 통일합니다.
+
+## 3) 적용된 모듈
+- `lib/kis/error-codes.ts`
+  - 공식 FAQ 코드 문구 매핑
+  - `getKisErrorGuide(msgCode)` 제공
+  - `buildKisErrorDetail(...)` 제공
+- `lib/kis/client.ts`
+  - REST 실패 메시지에 `msg_cd + 공식 문구` 반영
+- `lib/kis/token.ts`
+  - 토큰 발급/폐기 실패 메시지에 `msg_cd + 공식 문구` 반영
+- `lib/kis/approval.ts`
+  - 승인키 발급 실패 메시지에 `msg_cd + 공식 문구` 반영
+- `features/kis-realtime/stores/kisWebSocketStore.ts`
+  - 실시간 제어 오류(`OPSP*`) 메시지에 공식 문구 반영
+
+## 4) 운영 시 참고
+- 화면/로그에 `EGW00103`, `OPSP8996`처럼 코드가 보이면
+  `lib/kis/error-codes.ts`에서 즉시 문구를 확인할 수 있습니다.
+- 신규 코드가 추가되면 공식 FAQ 기준으로 맵에 추가합니다.