> 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/developer-guide-en/pjt-prepare/publish-your-docs/general-programming-standards.md).

# General Programming Standards

This section explains the general programming standards used in the X2BEE NEXT project. Following these guidelines helps maintain a consistent code style and improves the project's efficiency and readability.

***

## Naming Conventions

1. **Using the Abbreviations Glossary**
   * All naming should be done using the Abbreviations Glossary.
   * Module-classification folder names are excluded from the abbreviations-glossary naming convention. (e.g., display, goods, event, order, etc.)
2. **URL Creation Policy**

   Uses the app router, and is created in the form module name/parent menu name/screen function name.

   * **Module name**: Use the full name
   * **Parent menu name**: Combine using abbreviations, fitting within about 15 characters
   * **Screen function name**: Combine using abbreviations, fitting within about 20 characters
   * Other general words are abbreviated (e.g., mgmt, info, reg, mod)

   Example:

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

## Multilingual Message Key Declaration Method

### File Creation Rules

Manage multilingual messages by language and by module by creating \*.json files per language/module, or per language/module path/task. \*.json file names are written in camelCase.

* \*.json file creation methods
  * Create \*.json files by module\
    e.g.) `src/locales/langs/[ko, en, ja, ...]/goods.json`
  * Create \*.json files by module path/task\
    e.g.) `src/locales/langs/[ko, en, ja, ...]/display/mallMgmt.json`
* When used in common popups, use only the key after `baseInfoMgmt.label.popup`\
  e.g.) `baseInfoMgmt.label.popup.displayCategoryListPopup.title`

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

* Common fields (`sysModDtm`, `sysRegDtm`, etc.) are declared in the `common.json` file

## File Naming Rules

Separate folders clearly by task, use kebab-case, and limit the file type to ts.

### Directory Structure

* **utils**: Defines common and task-specific utils.\
  e.g.) `~/utils/module-name/task-utils.ts` — `~/utils/common/common-utils.ts`
* **types**: Defines TypeScript types.\
  e.g.) `~/types/module-name/task-types.ts` — `~/types/goods/goods-mgmt-types.ts`
* **schema**: Defines zod schemas per task.\
  e.g.) `~/schema/module-name/task-schema.ts` — `~/schema/goods/goods-mgmt-schema.ts`
* **api**: Defines API calls per task.\
  e.g.) `~/api/module-name/task-api.ts` — `~/api/display/standard-category-api.ts`
* **constants**: Defines constant value information per task.\
  e.g.) `~/constants/module-name/task-constants.ts` — `~/constants/display/display-constants.ts`
* **grid**: Defines grid information per task/screen. (BO)\
  e.g.) `~/components/module-name/screen-function-name/task/sample-grid.tsx` — `~/components/goods/goods-mgmt/goods-info/goods-info-grid.tsx`
* **grid-column**: Defines grid column information per task/screen. (BO)\
  e.g.) `~/grid/module-name/grid_file_name.ts` — `~/grid/display/site-grid.ts`
* **search-form**: Defines the search form per task/screen.\
  e.g.) `~/components/module-name/screen-function-name/task/sample-search-form.tsx` — `~/components/display/site-mgmt/site-info-mgmt/site-search-form.tsx`
* **grouping section between components**: Defined when multiple components need to be grouped per task/screen.\
  e.g.) To group `site-grid.tsx` and `site-search-form.tsx` together: `~/components/display/site-mgmt/site-info-mgmt/site-search-section.tsx`
* **components declared inside page.tsx**: Defines components for the page content area per task/screen.\
  e.g.) `~/components/module-name/screen-function-name/task/sample-contents.tsx` — `~/components/display/site-mgmt/site-info-mgmt/site-contents.tsx`
* **store**: Defines zustand stores per module.\
  e.g.) `~/store/module-name/sample-store.ts` — `~/store/common/auth-store.ts`
* **hooks**: Defines common and module-specific shared logic as hooks.\
  e.g.) `~/hooks/module-name/use-sample.ts` or `~/hooks/module-name/task/use-sample.ts` — `~/hooks/common/popup/use-popup-actions.ts`

## Common Popups and Multilingual Popups

* **Common popup folder creation rules**: Define common popups per module/task within the `popup` folder.
  * Create a folder per module\
    e.g.) `~/app/popup/brand-list` → `~/app/popup/goods/brand-list`
* **Multilingual popup folder creation rules**: Define the multilingual-related Context by wrapping it as a provider in the layout. To use the multilingual Context, define it in the following format:\
  `~/app/(multi-lang)/(popup)/module-name/*`\
  e.g.) `~/app/(multi-lang)/(popup)/goods/brand-mgmt/brand-info-mgmt/brand-info-multi-lang`

## Code Style

Apply Lint and Prettier to maintain code consistency. Use npm options to apply Lint and Prettier across the entire source.

* Apply Lint to the entire source: `npm run lint:fix`
* Apply Prettier to the entire source: `npm run fm:fix`