taxbaik/docs/COMBO_POLICY.md

Combo Policy

이 문서는 TaxBaik 어드민의 콤보 정책을 정한다. 여기서 콤보는 MudSelect, MudAutocomplete, MudChip, 상태 필터, 코드 선택 입력을 포함한다.

Policy

• 닫힌 집합은 MudSelect를 쓴다.
• 열린 집합 또는 검색이 필요한 집합은 MudAutocomplete를 쓴다.
• 상태/유형/등급처럼 값이 고정된 항목은 문자열 직접 입력을 금지한다.
• 선택한 값은 저장 값과 표시 값을 분리한다.
• 표시 값은 사람이 읽는 라벨, 저장 값은 코드값이어야 한다.
• null 허용 여부는 UI에서 명시한다.
• 전체, 선택 안 함, 기타는 서로 다른 의미로 취급한다.
• 다중 선택이 필요하면 단일 선택 콤보를 억지로 재사용하지 않는다.

Closed Set

다음 경우 MudSelect를 기본으로 사용한다.

• 상태
• 세금 유형
• 신고 유형
• 위험도
• 고정 서비스 유형
• 공지 유형

규칙:

• 값은 상수, enum, 공통코드 중 하나에서만 가져온다.
• MudSelectItem의 라벨과 값은 일치하는 쌍으로 관리한다.
• 운영자가 값의 의미를 추측해야 하는 항목은 콤보로 두지 않는다.

Search Set

다음 경우 MudAutocomplete를 기본으로 사용한다.

• 고객 선택
• 회사 선택
• 데이터가 많아 스크롤 선택이 비효율적인 경우

규칙:

• 검색어 입력 후 서버 또는 클라이언트 필터 결과를 보여준다.
• 결과가 적을 때는 MudSelect보다 MudAutocomplete를 우선하지 않는다.
• 선택 후 보여주는 텍스트와 저장되는 id를 분리한다.

Display Rules

• 목록에서는 상태를 칩으로 보여준다.
• 폼에서는 텍스트보다 구조화된 값으로 저장한다.
• 필터에서는 현재 선택값이 명확히 보이게 한다.
• Clearable은 의미가 명확한 경우에만 켠다.

Standard Sources

• 상태 값은 InquiryStatusMapper 또는 전용 enum을 사용한다.
• 공지/신고/세무 정보는 각 도메인별 공통코드 소스를 둔다.
• 고객/회사 선택은 검색형 콤보로 통일한다.

Anti-Patterns

• 같은 화면에 MudSelect와 자유 텍스트 입력을 섞어 같은 의미를 표현
• 코드값과 표시값을 뒤섞어서 저장
• 콤보 옵션을 화면마다 하드코딩
• 기타를 예외 처리처럼 쓰고 실제 저장 값은 제각각 두는 것
• 전체를 저장 값으로 사용

Acceptance Criteria

• 신규 어드민 화면은 이 문서의 Closed Set/Search Set 중 하나를 명시해야 한다.
• 상태/유형/등급 입력이 있는 화면은 콤보 정책 위반이 없어야 한다.
• 고객/회사처럼 데이터가 많은 항목은 검색형 선택으로 통일한다.