BO 개발 가이드

X2BEE 솔루션 3.0의 일관된 개발 스타일을 위해 사용되는 프로그래밍 표준을 설명합니다. 일관된 코드 스타일을 유지하며, 솔루션을 활용한 개발의 효율성과 가독성을 위해 가이드라인을 준수 해야합니다.

Next.js 15 기반의 애플리케이션 개발을 위한 코드 재사용성, 타입 안정성, 성능 최적화 원칙과 함께 프로젝트의 구조와 개발 표준을 설명합니다.

---

Route 생성 가이드

• NEXT15 - App Router 사용

• URL은 폴더 계층대로 약어집을 기반으로 조합하여 생성

• 1차분류 : 모듈 , 2차분류 : 업무

  • 예) /src/app/[pageType]/display/standard-category-mgmt/page.tsx → /display/standard-category-mgmt

• 페이지 컴포넌트(page.tsx) → use client 사용을 최소화

표준 구조 예시:

app	(multi-lang)	모듈	업무	다국어 적용을 위한 그룹
	(task-popup)			업무팝업 그룹 ex) 전시연결세트 팝업
	[pageType]			pageType: 'page' | 'tab' | 'pagepopup' default 값을 넣지 않으면 layout에서 page로 기본 설정
	popup			공통 및 일반 팝업
	auth			권한관련 (로그인 페이지)
	error			에러페이지

---

Component 생성 가이드

• 1차분류 : 모듈 , 2차분류 : 업무

  • 예) /src/components/display/display-category-mgmt /display-category-tree.tsx

• 업무별 필수 type, schema 별도 파일로 정의

standard-category-schema.ts

export const StandardCategoryGoodsAttrSchema = z.object({
  stdCtgNo: StringSchema({ key: 'display.standardCategory.field.stdCtgNo' })
});
export type StandardCategoryGoodsAttrSchemaType = z.infer<typeof StandardCategoryGoodsAttrSchema>;

• 컴포넌트 내부에서만 사용될 것으로 판단되는 타입은 컴포넌트 내부에 선언

StandardCategoryGoodsAttrGrid.tsx

type Props = {stdCtgNo: string };
export default function StandardCategoryGoodsAttrGrid({ stdCtgNo }: Props) { 
... }

• 업무 및 state 기준으로 컴포넌트를 세밀하게 구성하여 리렌더링(Re-render) 이슈 최소화

• key 설정으로 컴포넌트의 life-cycle을 명시적으로 관리 가능

  • key는 상세하게 남겨 주는 것을 권장 (단순 ID만 사용할 경우 키 중복 가능)

예시:

usage-example.tsx

<CommonSectionBox>
  <StandardCategoryForm
    standardCategory={standardCategory}
    key={`standard_category_form_${standardCategory.stdCtgNo}`}
  />
</CommonSectionBox>

컴포넌트 내부 예시:

StandardCategoryForm.tsx

const StandardCategoryForm = ({ standardCategory }: Props) => {
  const { data: formData, success } = useSafeParse(
    StandardCategorySchema.safeParse(standardCategory)
  );
  ...
}

---

API 호출 가이드

• REST API 사용

• Zod 스키마에서 추출된 타입 사용

• Promise 형식 반환을 기본으로 함

GET 예시:

api-get.ts

export const fetchDisplaySubCategoryList = async (
  params: DisplayCategorySearchSchemaType
) => 
  (await restApi.get(
    `${API_PATH}/getSubCategoryList`, 
    { 
      params 
    }
  )) as GridResponse<DisplayCategorySchemaType[]>;

POST/PUT/DELETE 예시:

api-post.ts

export const fetchRegistDisplayCategory = async (
  body: DisplayCategorySchemaType
) => 
  (await restApi.post(
    API_PATH, 
    {
     body 
    }
  )) as ResponseEntity<DisplayCategorySchemaType>;

핸들러 및 클라이언트 API 사용 규칙:

• handleResponse, handleGridResponse : getData 내부에서 isSuccess로 기본 데이터 출력

  • isSuccess: boolean

  • code: string

  • message: string

  • getData: () => T

• clientRestApi : clientRequest 시 사용, 기본 옵션으로 로딩 enabled

  • api: Promise

  • options(optional) → loading: true

사용 예시:

useClientRestApi-example.tsx

const clientRestApi = useClientRestApi();

const fetchGridData = useCallback(async () => {
  const api = async () => {
    const response = await fetchDisplaySubCategoryList({ dispCtgNo: displayCategory.dispCtgNo });
    const { getData } = handleGridResponse(response as GridResponse<DisplayCategorySchemaType[]>);
    const payload = getData() as X2beeSimplePaginationDataType<DisplayCategorySchemaType>;
    setGridPayload(payload.rows);
  };

  await clientRestApi({
    api,
    // options: { loading: true } // 옵션 생략 가능
  });
}, [displayCategory.dispCtgNo]);

---

Custom Hooks 생성 가이드

• 재사용이 필요하고 hooks 사용이 필요할 경우 생성

• 로직 복잡도로 인해 별도로 관리를 해야할 경우 (Utils 선고려, 내부에서 Hooks 사용 여부 고려)

---

Utils 생성 가이드

• 재사용이 필요한 경우

• 내부에서 hooks 사용이 되지 않는 경우

• 구문이 복잡하여 별도로 관리가 필요한 경우

• 서버 영역에서 사용이 필요할 경우

---