> 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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tech.x2bee.com/dev-guide/pjt-prepare/publish-your-docs/undefined.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.