프로그래밍 일반표준

X2BEE NEXT프로젝트에서 사용되는 프로그래밍 일반 표준에 대해 설명합니다. 이 가이드라인을 따르면 일관된 코드 스타일을 유지하며 프로젝트의 효율성과 가독성을 높일 수 있습니다.

---

명명규칙

1. 약어집 활용

   • 모든 명명은 약어집을 활용해 작성합니다.

   • 모듈 구분 폴더명은 약어집 참고 명명규칙에서 제외합니다. (예: display, goods, event, order 등)

1. URL 생성 정책

   app 라우터를 사용하며, 모듈명/상위 메뉴명/화면기능명 형태로 생성합니다.

   • 모듈명: 풀네임 사용

   • 상위 메뉴명: 15자 기준으로 최대한 맞추어 약어 사용하여 조합

   • 화면 기능명: 20자 기준으로 최대한 맞추어 약어 사용하여 조합

   • 그 외 일반적인 단어는 약어로 처리합니다 (예: mgmt, info, reg, mod)

   예시:

   • /goods/goodsMgmt.goodsMgmtView.do → src/app/[pageType]/goods/goods-mgmt/goods-info-mgmt

다국어 Message Key 선언 방식

파일 생성 규칙

언어별, 모듈별 *.json 파일 생성 또는 언어별·모듈별 path/업무별 *.json 생성하여 언어별·모듈별로 다국어 메시지를 관리합니다. *.json 파일명은 camelCase 형식으로 명명합니다.

• *.json 파일 생성 방식

  • 모듈별 *.json 파일 생성 예) src/locales/langs/[ko, en, ja, ...]/goods.json

  • 모듈별 path/업무별 *.json 파일 생성 예) src/locales/langs/[ko, en, ja, ...]/display/mallMgmt.json

• 공통팝업에서 사용 시 baseInfoMgmt.label.popup 이후 key만 사용 예) baseInfoMgmt.label.popup.displayCategoryListPopup.title

{ 
  "displayCategoryListPopup": { 
    "title": "전시 카테고리 조회 ",
    "...": "..." 
  } 
}

• 공통 필드(sysModDtm, sysRegDtm 등)는 common.json 파일 내 선언

파일명 규칙

업무별 명확한 폴더 분리를 하며, kebab-case, 파일타입은 ts로 제한합니다.

디렉토리 구조

• utils: 공통 및 업무별 유틸을 정의합니다. 예) ~/utils/모듈명/업무-utils.ts — ~/utils/common/common-utils.ts

• types: 타입스크립트의 타입을 정의합니다. 예) ~/types/모듈명/업무-types.ts — ~/types/goods/goods-mgmt-types.ts

• schema: 업무별 zod 스키마를 정의합니다. 예) ~/schema/모듈명/업무-schema.ts — ~/schema/goods/goods-mgmt-schema.ts

• api: 업무별 API 호출을 정의합니다. 예) ~/api/모듈명/업무-api.ts — ~/api/display/standard-category-api.ts

• constants: 업무별 상수값 정보를 정의합니다. 예) ~/constants/모듈명/업무-constants.ts — ~/constants/display/display-constants.ts

• grid: 업무·화면별 그리드 정보를 정의합니다. (BO) 예) ~/components/모듈명/화면기능명/업무/sample-grid.tsx — ~/components/goods/goods-mgmt/goods-info/goods-info-grid.tsx

• grid-column: 업무·화면별 그리드 컬럼 정보를 정의합니다. (BO) 예) ~/grid/모듈명/그리드_파일명.ts — ~/grid/display/site-grid.ts

• search-form: 업무·화면별 검색폼을 정의합니다. 예) ~/components/모듈명/화면기능명/업무/sample-search-form.tsx — ~/components/display/site-mgmt/site-info-mgmt/site-search-form.tsx

• component 간 grouping section: 업무·화면별 다수 컴포넌트를 그룹으로 묶을 때 정의합니다. 예) site-grid.tsx와 site-search-form.tsx를 묶고 싶은 경우 ~/components/display/site-mgmt/site-info-mgmt/site-search-section.tsx

• page.tsx 내부 선언 component: 업무·화면별 페이지 컨텐츠 영역의 컴포넌트를 정의합니다. 예) ~/components/모듈명/화면기능명/업무/sample-contents.tsx — ~/components/display/site-mgmt/site-info-mgmt/site-contents.tsx

• store: zustand의 store를 모듈별로 정의합니다. 예) ~/store/모듈명/sample-store.ts — ~/store/common/auth-store.ts

• hooks: 공통·모듈별 공통 사용 부분을 hooks로 정의합니다. 예) ~/hooks/모듈명/use-sample.ts 또는 ~/hooks/모듈명/업무/use-sample.ts — ~/hooks/common/popup/use-popup-actions.ts

공통팝업 및 다국어 팝업

• 공통팝업 폴더 생성 규칙: 모듈·업무별 공통팝업을 popup 폴더 내에서 정의합니다.

  • 모듈별로 폴더를 생성 예) ~/app/popup/brand-list → ~/app/popup/goods/brand-list

• 다국어팝업 폴더 생성 규칙: 다국어 관련 Context를 layout에 provider로 감싸서 정의합니다. 다국어 Context를 사용하기 위해서 다음 형식으로 정의합니다: ~/app/(multi-lang)/(popup)/모듈명/* 예) ~/app/(multi-lang)/(popup)/goods/brand-mgmt/brand-info-mgmt/brand-info-multi-lang

코드 스타일

Lint와 Prettier를 적용하여 코드의 일관성을 유지합니다. npm 옵션을 이용해서 전체 소스에 대해 Lint, Prettier를 적용합니다.

• 전체 소스 Lint 적용: npm run lint:fix

• 전체 소스 Prettier 적용: npm run fm:fix