[CRM 개발일지 #2] 공통 코드 상태 관리 구조 개선 + Zustand 적용

🚀 TODAY WORK

백엔드

• 공통 코드 API 개발 (/common-codes)
• JPA Composite Key(CodeId) 적용
• 공통 코드 그룹 조회 서비스 구현
• 관리자 사용자 조회 API 개선
• ApiResponse 공통 응답 구조 적용
• USER\_ROLE / USER\_SPECIALTY / USER\_STATUS 코드 연동

프론트엔드

• Zustand 기반 공통 코드 전역 Store 구성
• 공통 코드 preload 구조 구현
• 관리자 사용자 페이지 코드명 변환 적용
• 공통 코드 util(getCodeName) 작성
• Admin Layout 기반 초기화 구조로 리팩토링

---

🚨 TODAY ISSUE

1. 공통 코드 하드코딩 문제

초기에는 ROLE, STATUS, SPECIALTY 값을 프론트에서 직접 문자열로 처리하고 있었다.

ROLE_ADMIN
ROLE_CONSULTANT
ACTIVE
BACKEND

하지만 운영 단계에서는 코드명 변경 가능성이 있기 때문에
하드코딩 방식은 유지보수에 불리하다고 판단했다.

 

그래서 DB 기반 공통 코드 시스템으로 변경했다.

 

 

2. 공통 코드 테이블 설계

공통 코드 테이블은 아래 구조로 설계

• FK 없이 논리적 참조 사용
• code\_group 기준 그룹 관리
• use\_yn 기반 활성화 처리
• 정렬 순서(order\_no) 지원
• 운영 코드 확장 가능 구조

CREATE TABLE CODE_MNG (
    code_group     VARCHAR(50) NOT NULL,
    code_val       VARCHAR(50) NOT NULL,
    code_nm        VARCHAR(100) NOT NULL,
    parent_code    VARCHAR(50),
    depth          INT NOT NULL DEFAULT 0,
    order_no       INT,
    use_yn         CHAR(1) NOT NULL DEFAULT 'Y',
    created_at     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at     DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    PRIMARY KEY (code_group, code_val)
);

 

 

3. 공통 코드 API 구현

백엔드에서는 /common-codes API를 통해
전체 공통 코드를 그룹별로 반환하도록 구현했다.

{
  "success": true,
  "data": {
    "CUSTOMER_STATUS": [
      {
        "code": "ACTIVE",
        "name": "수강 확정"
      },
      {
        "code": "DORMANT",
        "name": "장기 미응답"
      },
      {
        "code": "IN_PROGRESS",
        "name": "상담 진행 중"
      },
      {
        "code": "NEW",
        "name": "신규 상담 신청"
      },
      {
        "code": "WITHDRAWN",
        "name": "탈퇴"
      }
    ],
    // ...
  }
}

프론트에서는 이 데이터를 preload 후 전역 상태로 관리하도록 구성했다.

 

 

4. Zustand Persist 적용

초기에는 로그인 직후 공통 코드를 preload 했지만
새로고침 시 데이터가 사라지는 문제가 발생했다.

 

원인은 아래와 같았다...

• 로그인 페이지에서 preload 수행
• 페이지 이동(router.push)
• hydration 타이밍 충돌

 

5. 구조 개선 (실무형 구조)

[기존 구조]

로그인
 → 공통코드 preload
 → zustand 저장
 → 페이지 이동

[변경 후 구조]

AdminLayout
 → CodeInitializer
 → 공통코드 preload
 → zustand persist 저장
 → 하위 페이지 사용

공통 코드 로딩 책임을 로그인 페이지가 아니라 Admin Layout으로 이동시켰다.

• 새로고침 유지 가능
• admin 하위 전체 공통 사용 가능
• preload 책임 분리
• 운영형 구조 확장 가능

---

📌 핵심 구현 포인트

공통 코드 Store 를 사용해 localStorage 기반 상태 유지 적용.

persist(...)

CodeInitializer 컴포넌트를 Admin Layout 에서 공통 실행.

<CodeInitializer />

• persist 복원
• 공통 코드 preload
• 전역 상태 저장

---

코드명 변환 util 형태로 화면 출력 시 코드명을 변환

getCodeName(codes, "USER_ROLE", user.roles)

출력 결과

ROLE_ADMIN → 관리자
BACKEND → 백엔드
ACTIVE → 활동

---

💡 느낀 점

이번 작업에서 가장 크게 느낀 부분은
“공통 데이터는 화면이 아니라 레이아웃 레벨에서 관리해야 한다”는 점이었다.

처음에는 단순히 로그인 후 preload 하면 될 거라고 생각했지만,

• hydration
• persist
• router 이동
• SSR / CSR

 

타이밍이 섞이면서 상태 관리가 꼬이는 문제를 경험했다.

(타이밍이 섞일거라고는 생각하지 못했다..)

로그인 = 인증
Layout = preload
Store = 상태 관리
Page = 화면 출력

책임을 분리하는 방식이 가장 안정적인 구조라는 걸 체감했다.

---

🔥 NEXT TODO

• 공통 Badge 컴포넌트 적용
• 날짜 포맷 공통 util 작성
• 공통 Table 컴포넌트 분리
• 고객(Customer) 상태 코드 연동
• 상담 결과 코드 연동
• 코드 캐싱 최적화