> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/dev-guide/pjt-prepare/publish-your-docs/undefined.md).

# 프로그래밍 일반표준

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

***

## 명명규칙

1. **약어집 활용**
   * 모든 명명은 [약어집](/dev-guide/pjt-prepare/publish-your-docs.md#undefined-3)을 활용해 작성합니다.
   * 모듈 구분 폴더명은 약어집 참고 명명규칙에서 제외합니다. (예: display, goods, event, order 등)

2. **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`

```json
{ 
  "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`