taxbaik/docs/COMMON_CODE_POLICY.md

Common Code Policy

이 문서는 어드민 콤보, 상태, 유형, 출처 값의 단일 기준이다. 값은 DB common_codes를 우선 사용하고, 화면은 표시명만 바꾼다.

Canonical Rules

• code_value는 저장 키다.
• code_name은 화면 표시값이다.
• code_value는 공백을 넣지 않는다.
• code_group도 공백 없이 대문자/숫자/언더스코어 중심의 안정된 키를 쓴다.
• 새 콤보를 추가할 때는 먼저 common_codes에 그룹을 추가한다.
• 화면 하드코딩 배열은 금지한다. 불가피하면 임시 폴백으로만 두고 제거 계획을 함께 적는다.
• 같은 의미의 값이 테이블마다 다르면 저장값을 먼저 통일하고 마이그레이션으로 이관한다.

Grouping Rules

• 상태값: *_STATUS
• 유형값: *_TYPE
• 출처값: *_SOURCE
• 위험도/스코어: *_LEVEL

Standard Groups

• INQUIRY_SERVICE_TYPE
• INQUIRY_STATUS
• CONSULTING_ACTIVITY_TYPE
• ANNOUNCEMENT_DISPLAY_TYPE
• CLIENT_STATUS
• CLIENT_SERVICE_TYPE
• CLIENT_TAX_TYPE
• CLIENT_SOURCE
• CONTRACT_SERVICE_TYPE
• REVENUE_SERVICE_TYPE
• FILING_TYPE
• TAX_RISK_LEVEL
• BUSINESS_TYPE
• FAQ_CATEGORY

Data Rules

• DB seed와 운영 데이터의 저장값이 다르면 UI를 먼저 맞추지 말고 저장값을 먼저 정규화한다.
• 한글 코드값을 사용하더라도 컬럼 길이를 먼저 검토하고, 업무 테이블과 마스터 테이블을 함께 조정한다.
• 한글 code_value가 필요하면 DB 컬럼 길이와 인덱스 길이를 먼저 확인하고, 초과 가능성이 있으면 표시값과 저장값을 분리한다.
• 표시용 문구가 길면 code_name에 둔다.

UI Rules

• MudSelect는 code_value를 바인딩하고 code_name을 보여준다.
• 검색형이면 MudAutocomplete를 쓰고, 선택형이면 MudSelect를 쓴다.
• 자유 입력을 허용하지 않을 값은 텍스트 필드로 만들지 않는다.

Acceptance Criteria

• 신규 콤보 추가 시 DB 마이그레이션이 먼저 존재해야 한다.
• 화면에 하드코딩된 선택값이 없어야 한다.
• 기존 저장값과 신규 저장값의 불일치가 없어야 한다.

Audit

• 점검 SQL은 docs/ops/COMMON_CODE_AUDIT.sql를 사용한다.
• 그룹 공백, 값 공백, 길이 초과, 테이블 매핑 불일치는 이 SQL에서 먼저 잡는다.