공통코드 체계

에너지 현장은 타입이 계속 늘어납니다. 처음엔 전력계만 있다가 유량계, 가스계, 분진계, 소음계가 들어오고, 알람 유형과 설비 유형도 고객마다 추가됩니다.

이걸 코드의 enum이나 DB ENUM 컬럼으로 관리하면 타입 하나 추가할 때마다 배포가 필요합니다. 그래서 에너지 플랫폼은 대부분의 타입과 상태를 공통코드 테이블 하나로 관리합니다.

1. 테이블 구조

common_code

컬럼	설명
code_id (PK)	코드 ID. 다른 테이블이 FK로 참조
code_group	코드 그룹 (METER_TYPE, ALARM_TYPE …)
code	코드 값 (영문 대문자, 최대 50자)
code_name	화면 표시명
description	설명
sort_order	정렬 순서
is_deleted	soft delete

code_group + code 조합이 논리적 유일 키입니다. 다른 테이블은 xxx_type_id, xxx_status_id 컬럼으로 code_id를 참조합니다.

2. 주요 코드 그룹

그룹	쓰이는 곳	예시
SERVICE_TYPE	회사 서비스, 역할, 메뉴	EnMS, 구독 서비스 등
BUSINESS_TYPE	회사 업종	제조, 건물
METER_TYPE	meter.meter_type_id	전력, 유량, 가스, 분진, 소음
METER_STATUS	계기 통신 상태	on / off
EQUIPMENT_STATUS	equipment.status_id	가동, 정지, 폐기
ALARM_TYPE	alarm_rule.alarm_type_id	상한, 하한, 통신장애
ALARM_SEVERITY	alarm_rule_threshold.severity_id	정보, 경고, 위험
IMAGE_ROLE	설비/계기 이미지	전경, 명판, 설치 위치
MEMBER_STATUS	member	활성, 잠김, 탈퇴
SCOPE_TYPE	데이터 조회 범위 정책	전체, 회사, 사업장

3. 코드 ID vs 코드 값

FK는 code_id(숫자)로 걸고, 로직은 code(문자)로 판단합니다.

// 나쁜 예: 환경마다 code_id 가 다르면 깨짐
if (meter.meterTypeId === 12) { ... }

// 좋은 예: code 값으로 판단
const meterType = await CommonCode.findByPk(meter.meterTypeId)
if (meterType.code === 'POWER_METER') { ... }

개발/운영 DB의 code_id가 다를 수 있습니다. 코드에 숫자 ID를 박지 마세요
자주 쓰는 코드는 서버 시작 시 code_group별로 메모리에 캐시합니다
보고서, DAQ 같은 다른 언어의 서비스도 같은 code 문자열 규칙을 따라야 합니다

4. 설계 원칙

code는 바꾸지 않는다: 화면 표시명은 code_name만 바꿉니다. code는 로직과 다른 서비스가 참조합니다
삭제는 soft delete: 과거 데이터가 참조하고 있으므로 물리 삭제 금지
정렬은 sort_order: 화면 드롭다운 순서를 코드로 제어
그룹 이름은 테이블.컬럼과 맞춘다: meter_type_id → METER_TYPE
속성이 생기면 테이블로 승격: 단위, 계수, 색상 같은 속성이 붙기 시작하면 별도 마스터로 분리합니다 (예: energy_source)

5. 공통코드로 두지 않는 것

대상	이유	대신
에너지원	단위, 탄소/TOE 계수 필요	energy_source
요금제	단가, 기간 이력 필요	electricity_tariff
소모품	회사별, 단위, 교체 주기	consumable_master
유지보수 분류	회사별 커스텀	equipment_maintenance_class

공통코드는 "이름 하나와 순서" 정도만 필요한 값에 씁니다. 속성이 있는 값을 공통코드에 우겨넣고 description에 JSON을 넣기 시작하면 관리가 무너집니다.

6. 화면 연동

프론트는 GET /common-codes?group=METER_TYPE 같은 API로 드롭다운을 채웁니다
앱 시작 시 자주 쓰는 그룹을 한 번에 받아 전역 상태에 캐시합니다
표시명 다국어가 필요하면 code_name_en 컬럼이나 별도 번역 테이블을 둡니다

7. 운영 팁

코드 추가는 마이그레이션 스크립트로 관리합니다. 운영 DB에 수동 insert 하면 환경별 차이가 생깁니다
관리자 화면에서 코드 추가를 열어주더라도 code는 생성 후 수정 불가로 막습니다
그룹 목록과 의미를 문서로 남깁니다. 1년 뒤에는 아무도 SCOPE_TYPE이 뭔지 기억하지 못합니다