디자인 변경

lib/kis/approval.ts

@@ -4,7 +4,7 @@ import { getKisConfig, getKisWebSocketUrl } from "@/lib/kis/config";
 
 /**
  * @file lib/kis/approval.ts
- * @description KIS 웹소켓 approval key 발급/캐시 관리
+ * @description KIS 웹소켓 승인키 생명주기를 관리합니다.
  */
 
 interface KisApprovalResponse {
@@ -34,12 +34,12 @@ function getApprovalCacheKey(credentials?: KisCredentialInput) {
 }
 
 /**
- * KIS 웹소켓 approval key 발급
- * @param credentials 사용자 입력 키(선택)
- * @returns approval key + expiresAt
- * @see app/api/kis/ws/approval/route.ts POST - 실시간 차트 연결 시 호출
+ * @description 웹소켓 승인키를 발급합니다.
+ * @see app/api/kis/ws/approval/route.ts
  */
-async function issueKisApprovalKey(credentials?: KisCredentialInput): Promise<KisApprovalCache> {
+async function issueKisApprovalKey(
+  credentials?: KisCredentialInput,
+): Promise<KisApprovalCache> {
   const config = getKisConfig(credentials);
 
   const response = await fetch(`${config.baseUrl}/oauth2/Approval`, {
@@ -50,6 +50,7 @@ async function issueKisApprovalKey(credentials?: KisCredentialInput): Promise<Ki
     body: JSON.stringify({
       grant_type: "client_credentials",
       appkey: config.appKey,
+      // Official samples use `secretkey` for Approval endpoint.
       secretkey: config.appSecret,
     }),
     cache: "no-store",
@@ -70,18 +71,13 @@ async function issueKisApprovalKey(credentials?: KisCredentialInput): Promise<Ki
     );
   }
 
-  // 공식 샘플은 1일 단위 재발급을 권장하므로 토큰과 동일하게 보수적으로 23시간 캐시합니다.
+  // KIS samples recommend daily refresh. Cache for 23 hours conservatively.
   return {
     approvalKey: payload.approval_key,
     expiresAt: Date.now() + 23 * 60 * 60 * 1000,
   };
 }
 
-/**
- * approval 응답을 안전하게 JSON으로 파싱합니다.
- * @param rawText fetch 응답 원문
- * @returns KisApprovalResponse
- */
 function tryParseApprovalResponse(rawText: string): KisApprovalResponse {
   try {
     return JSON.parse(rawText) as KisApprovalResponse;
@@ -93,9 +89,8 @@ function tryParseApprovalResponse(rawText: string): KisApprovalResponse {
 }
 
 /**
- * 웹소켓 승인키를 반환합니다.
- * @param credentials 사용자 입력 키(선택)
- * @returns approval key
+ * @description 승인키를 캐시에서 반환하거나 새로 발급합니다.
+ * @see features/dashboard/store/use-kis-runtime-store.ts
  */
 export async function getKisApprovalKey(credentials?: KisCredentialInput) {
   const cacheKey = getApprovalCacheKey(credentials);
@@ -113,6 +108,7 @@ export async function getKisApprovalKey(credentials?: KisCredentialInput) {
 
   const nextPromise = issueKisApprovalKey(credentials);
   approvalIssueInFlightMap.set(cacheKey, nextPromise);
+
   const next = await nextPromise.finally(() => {
     approvalIssueInFlightMap.delete(cacheKey);
   });
@@ -122,9 +118,8 @@ export async function getKisApprovalKey(credentials?: KisCredentialInput) {
 }
 
 /**
- * 거래 모드에 맞는 KIS 웹소켓 URL을 반환합니다.
- * @param credentials 사용자 입력 키(선택)
- * @returns websocket url
+ * @description 거래 환경에 맞는 웹소켓 URL을 반환합니다.
+ * @see app/api/kis/ws/approval/route.ts
  */
 export function resolveKisWebSocketUrl(credentials?: KisCredentialInput) {
   const config = getKisConfig(credentials);
@@ -132,8 +127,8 @@ export function resolveKisWebSocketUrl(credentials?: KisCredentialInput) {
 }
 
 /**
- * 승인키 캐시를 제거합니다.
- * @param credentials 사용자 입력 키(선택)
+ * @description 승인키 캐시를 제거합니다.
+ * @see lib/kis/token.ts
  */
 export function clearKisApprovalKeyCache(credentials?: KisCredentialInput) {
   const cacheKey = getApprovalCacheKey(credentials);