From e3e6f1089319fea60d0b877102a3f4aa45482e99 Mon Sep 17 00:00:00 2001 From: Daseul Kim Date: Tue, 10 Jun 2025 11:34:02 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=A7=80=EB=B6=95=EC=9E=AC=EC=A0=81?= =?UTF-8?q?=ED=95=A9=EC=84=B1=20hooks=20description=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/hooks/useSuitable.ts | 110 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 7 deletions(-) diff --git a/src/hooks/useSuitable.ts b/src/hooks/useSuitable.ts index 0bbc29b..8ee7ca7 100644 --- a/src/hooks/useSuitable.ts +++ b/src/hooks/useSuitable.ts @@ -20,6 +20,16 @@ export function useSuitable() { clearSelectedItems, } = useSuitableStore() + /** + * @description 지붕재 적합성 데이터 조회. API를 호출하여 검색 조건에 맞는 지붕재 적합성 데이터를 페이지 단위로 조회 + * + * @param {Object} param + * @param {number} [param.pageNumber] 페이지 번호 (기본값: 1) + * @param {string} [param.category] 지붕재그룹코드 + * @param {string} [param.keyword] 검색키워드 + * + * @returns {Promise} 지붕재 적합성 데이터 + */ const getSuitables = async ({ pageNumber, category, @@ -40,11 +50,16 @@ export function useSuitable() { const response = await axiosInstance(null).get('/api/suitable/list', { params }) return response.data } catch (error) { - console.error('지붕재 데이터 로드 실패:', error) + console.error(`지붕재 적합성 데이터 조회 실패: ${error}`) return [] } } + /** + * @description 지붕재 적합성 데이터 아이디 조회. API를 호출하여 검색 조건에 맞는 지붕재 적합성 데이터의 main_id, detail_id를 조회 + * + * @returns {Promise} 지붕재 적합성 데이터 아이디 목록 + */ const getSuitableIds = async (): Promise => { try { const params: Record = {} @@ -53,11 +68,19 @@ export function useSuitable() { const response = await axiosInstance(null).get('/api/suitable/pick', { params }) return response.data } catch (error) { - console.error('지붕재 아이디 로드 실패:', error) + console.error(`지붕재 적합성 데이터 아이디 조회 실패: ${error}`) return [] } } + /** + * @description 지붕재 적합성 데이터 조회. API를 호출하여 지붕재 적합성 데이터의 모든 컬럼을 조회 + * + * @param {string} ids 지붕재 적합성 데이터의 main_id (쉼표로 구분된 문자열) + * @param {string} [detailIds] 지붕재 적합성 데이터의 detail_id (쉼표로 구분된 문자열) + * + * @returns {Promise} 지붕재 적합성 데이터 + */ const getSuitableDetails = async (ids: string, detailIds?: string): Promise => { try { const params: Record = { ids: ids } @@ -65,12 +88,17 @@ export function useSuitable() { const response = await axiosInstance(null).post('/api/suitable', params) return response.data } catch (error) { - console.error('지붕재 상세 데이터 로드 실패:', error) + console.error(`지붕재 적합성 상세 데이터 조회 실패: ${error}`) return [] } } - const getSuitableCommCode = () => { + /** + * @description 지붕재 적합성 공통 코드 조회. API를 호출하여 지붕재 적합성 데이터에서 사용하는 공통 코드 조회 후 스토어에 맵핑하여 저장 + * + * @returns {void} + */ + const getSuitableCommCode = (): void => { const headCodes = Object.values(SUITABLE_HEAD_CODE) as SUITABLE_HEAD_CODE[] for (const code of headCodes) { getCommCode(code).then((res) => { @@ -79,11 +107,26 @@ export function useSuitable() { } } + /** + * @description 지붕재 적합성 공통 코드의 JP 코드명 조회 + * + * @param {string} headCode 공통 코드의 head_code + * @param {string} code 공통 코드의 code + * + * @returns {string} 공통 코드의 JP 코드명 + */ const toCodeName = (headCode: string, code: string): string => { const commCode = suitableCommCode.get(headCode) return commCode?.find((item) => item.code === code)?.codeJp || '' } + /** + * @description 지붕재 적합성 detail 데이터를 string 형태로 받아 파싱하여 반환 + * + * @param {string} suitableDetailString 지붕재 적합성 detail string + * + * @returns {SuitableDetail[]} 파싱된 지붕재 적합성 detail 데이터 + */ const toSuitableDetail = (suitableDetailString: string): SuitableDetail[] => { if (!suitableDetailString) return [] try { @@ -93,20 +136,32 @@ export function useSuitable() { } return suitableDetailArray } catch (error) { - console.error('지붕재 데이터 파싱 실패:', error) + console.error(`지붕재 적합성 detail 데이터 파싱 실패: ${error}`) return [] } } + /** + * @description 지붕재 적합성 상위 데이터 클릭 시 호출되는 함수. 지붕재 적합성 detail 데이터에서 id 목록을 추출하여 Set 형태로 반환 + * + * @param {string} suitableDetailString 지붕재 적합성 detail 데이터 + * + * @returns {Set} 지붕재 적합성 detail 데이터의 id 목록 + */ const toSuitableDetailIds = (suitableDetailString: string): Set => { try { return new Set(JSON.parse(suitableDetailString).map(({ id }: { id: number }) => id)) } catch (error) { - console.error('지붕재 데이터 파싱 실패:', error) + console.error(`지붕재 적합성 detail 데이터 파싱 실패: ${error}`) return new Set() } } + /** + * @description 지붕재 적합성 조회 페이지에서 보여지는 지붕재 적합성 데이터 조회 + * + * @returns {Object} 지붕재 적합성 데이터 조회 결과 + */ const { data: suitables, fetchNextPage, @@ -135,12 +190,29 @@ export function useSuitable() { enabled: searchCategory !== '' || searchKeyword !== '', }) + /** + * @description 지붕재 적합성 스토어 초기화. 선택된 지붕재 적합성 데이터, 검색 카테고리, 검색 키워드 초기화 + * + * @param {Object} param + * @param {boolean} [param.items] 선택된 지붕재 적합성 데이터 초기화 여부 + * @param {boolean} [param.category] 검색 카테고리 초기화 여부 + * @param {boolean} [param.keyword] 검색 키워드 초기화 여부 + * + * @returns {void} + */ const clearSuitableStore = ({ items = false, category = false, keyword = false }: { items?: boolean; category?: boolean; keyword?: boolean }) => { if (items) clearSelectedItems() if (category) clearSearchCategory() if (keyword) clearSearchKeyword() } + /** + * @description 지붕재 적합성 비고에 따른 아이콘 반환 + * + * @param {string} value 지붕재 적합성 비고 + * + * @returns {string} 지붕재 적합성 비고에 따른 아이콘 + */ // TODO: 추후 지붕재 적합성 데이터 CUD 구현 시 ×, -, ー 데이터 관리 필요 const suitableCheckIcon = (value: string): string => { const iconMap: Record = { @@ -152,6 +224,13 @@ export function useSuitable() { return iconMap[value] || iconMap.default } + /** + * @description 지붕재 적합성 비고에 따른 적합 결과 반환 + * + * @param {string} value 지붕재 적합성 비고 + * + * @returns {string} 지붕재 적합성 비고에 따른 적합 결과 + */ // TODO: 추후 지붕재 적합성 데이터 CUD 구현 시 ○, ×, -, ー 데이터 관리 필요 const suitableCheckMemo = (value: string): string => { if (value === '○') return '設置可' @@ -160,6 +239,13 @@ export function useSuitable() { return `${value}で設置可` } + /** + * @description 선택된 지붕재 적합성 데이터의 main_id, detail_id를 쉼표로 구분하여 반환. 선택된 지붕재 적합성 데이터가 없으면 빈 문자열 반환 + * + * @returns {Object} 선택된 지붕재 적합성 데이터의 main_id, detail_id + * @returns {string} 선택된 지붕재 적합성 데이터의 main_id (쉼표로 구분된 문자열) + * @returns {string} 선택된 지붕재 적합성 데이터의 detail_id (쉼표로 구분된 문자열) + */ const serializeSelectedItems = (): { ids: string; detailIds: string } => { const ids: string[] = [] const detailIds: string[] = [] @@ -170,11 +256,21 @@ export function useSuitable() { return { ids: ids.join(','), detailIds: detailIds.length > 0 ? detailIds.join(',') : '' } } + /** + * @description 선택된 지붕재 적합성 데이터 조회. API를 호출하여 선택된 지붕재 적합성 데이터의 모든 컬럼을 조회 + * + * @returns {Promise} 선택된 지붕재 적합성 데이터 + */ const getSelectedSuitables = async (): Promise => { const { ids, detailIds } = serializeSelectedItems() return await getSuitableDetails(ids, detailIds) } + /** + * @description 선택된 지붕재 적합성 데이터 pdf 다운로드. form 태그를 생성하여 직접 API를 호출하여 pdf 다운로드 + * + * @returns {Promise} 선택된 지붕재 적합성 데이터 pdf 다운로드 + */ const downloadSuitablePdf = async (): Promise => { try { const { ids, detailIds } = serializeSelectedItems() @@ -210,7 +306,7 @@ export function useSuitable() { form.submit() document.body.removeChild(form) } catch (error) { - console.error('지붕재 상세 데이터 pdf 다운로드 실패:', error) + console.error(`지붕재 적합성 상세 데이터 pdf 다운로드 실패: ${error}`) } }