01_정기 관리비 항목 설정

‘가이드 방식’ 정기 관리비 항목 설정

1. 문서 개요

본 문서는 건물관리 시스템의 ‘정기 관리비 항목 설정’ 화면에서, 사용자가 논리적 모순 없이 올바른 부과 규칙을 생성할 수 있도록 안내하는 **‘가이드 방식’**의 단계별 처리 순서를 정의합니다. 이 설계는 표준 라이브러리의 편의성과 각 테넌트별 맞춤 설정의 유연성을 모두 제공하는 것을 목표로 합니다.

2. 핵심 원칙: 라이브러리 기반 설정 (Library-based Configuration)

시스템은 플랫폼에서 제공하는 **표준 항목 라이브러리(템플릿)**를 기반으로 동작합니다. 사용자는 이 라이브러리에서 필요한 항목을 선택하여 자신의 건물에 맞게 ‘고지서 표시명’을 포함한 상세 규칙을 설정합니다. 이를 통해, 시스템 전체의 데이터 정합성을 유지하면서 각 테넌트의 운영 유연성을 보장합니다.

설정의 기본 흐름: 새 항목 추가 클릭 → 폼에서 라이브러리 항목 선택 → 기본 정보 확인 및 표시명 설정 → 부과 대상 선택 → 계산 방식 선택 → 상세 조건 입력 → 저장

3. 단계별 설정 순서 및 시스템 동작

Step 1: 새 항목 추가 및 라이브러리에서 항목 선택

가장 먼저, 설정할 정기 관리비 항목의 기본 템플릿을 선택하는 것으로 모든 설정이 시작됩니다.

• 사용자 행동:
  1. ‘정기 관리비 항목 목록’ 화면에서 [+ 새 항목 추가] 버튼을 클릭합니다.
  2. 새로운 ‘항목 설정 폼’이 나타납니다.
  3. 폼의 가장 첫 번째 항목인 **[드롭다운] 항목 선택**에서 ‘일반관리비’와 같은 표준 항목을 선택합니다.
• 시스템 동작:
  • 시스템은 qiro.standard_billing_items 테이블에서 frequency_type이 **‘정기/반복’**인 모든 항목을 조회하여 ‘항목 선택’ 드롭다운 목록을 구성합니다.

Step 2: 기본 정보 자동 채우기 및 표시명 설정 (첫 번째 필터)

사용자가 1단계에서 특정 항목(예: ‘일반관리비’)을 선택하면, 시스템은 해당 템플릿의 모든 기본 정보를 가져와 폼의 나머지 부분을 자동으로 채웁니다.

• 시스템 반응 (데이터 추출): 시스템은 선택된 항목의 모든 기본 정보를 가져와 폼을 자동으로 채웁니다.
• 사용자 행동: 자동으로 채워진 기본 정보를 확인하고, 고지서에 표시될 이름을 자유롭게 수정합니다.
• 화면 UI:
  • 원본 항목 (내부 관리용): 일반관리비 (사용자에게 표시되지만 수정은 불가능한, 이 항목의 원본 성격. 원본 default_name을 사용합니다.)
  • 고지서 표시명: [ 일반관리비 ] (사용자가 ‘A동 일반관리비’, ‘상가 일반관리비’ 등으로 자유롭게 수정 가능)
  • 항목 종류: 공용관리비 (템플릿의 item_type에 따라 자동 설정되며, 이후 선택지를 필터링하는 기준이 됨)
  • 과세 여부: 과세 (템플릿의 기본 부가세율에 따라 자동 설정)

Step 3: 부과 대상 지정 (두 번째 필터)

Step 2에서 결정된 ‘항목 종류’의 성격에 따라, 시스템은 선택 가능한 ‘부과 대상’ 목록을 동적으로 제시합니다.

• 사용자 행동: ‘부과 대상’ 드롭다운에서 제시된 옵션 중 하나를 선택합니다.
• 시스템 반응 (두 번째 필터링):

만약 항목 종류가…	라면, 부과 대상 드롭다운에는…
공용비	전체 호실계약중인 호실공실선택 호실 (그룹 대상 옵션만 표시)
개별비	이용 호실 (이용자 대상 옵션만 표시)

Step 4: 계산 방식 지정 (세 번째 필터)

‘부과 대상’의 성격에 따라, 시스템은 적용 가능한 ‘계산 방식’ 목록을 최종적으로 필터링하여 제시합니다.

• 사용자 행동: ‘계산 방식’ 드롭다운에서 제시된 옵션 중 하나를 선택합니다.
• 시스템 반응 (세 번째 필터링):

만약 부과 대상이…	라면, 계산 방식 드롭다운에는…
그룹 (전체, 계약중, 공실, 선택)	총액 면적 비례총액 균등 배분면적당 단가고정액 부과 등 (그룹에 적용 가능한 방식만 표시)
이용 호실	사용량당 단가고정액 부과 등 (이용자에게 적용 가능한 방식만 표시)

Step 5: 상세 조건 입력 (최종 UI 표시)

‘계산 방식’이 최종적으로 선택되면, 시스템은 해당 방식에 필요한 마지막 추가 정보 입력 UI를 화면에 표시합니다.

• 사용자 행동: 표시된 UI에 필요한 값(예: 단가, 면적 종류)을 입력합니다.

Step 6: 저장

사용자가 모든 설정을 마치고 저장하면, 해당 테넌트에게만 적용되는 **새로운 ‘정기 부과 규칙’**이 생성됩니다. 이 규칙은 원본 라이브러리 항목(item_id)과 연결되며, 사용자가 설정한 고유한 ‘고지서 표시명’과 상세 규칙을 함께 저장합니다.

---

Case A: 일반적인 설정 흐름 (부과 대상 먼저 선택)

1. 사용자 행동: 부과 대상 드롭다운에서 **‘전체 호실’**을 선택합니다.
2. 시스템 반응: 계산 방식 드롭다운에는 ‘전체 호실’에 적용 가능한 옵션(총액 면적 비례, 총액 균등 배분 등)만 표시됩니다. 이 목록에는 총액 지분 비율 배분이 포함되지 않아 논리적 모순이 원천적으로 차단됩니다.

Case B: 특수 계산 방식 설정 흐름 (총액 지분 비율 배분 선택)

1. 사용자 행동: 계산 방식 드롭다운에서 **총액 지분 비율 배분(TOTAL_PER_SHARE_RATIO)**을 먼저 선택합니다.

2. 시스템 반응 (동적 UI 변경):

   • 부과 대상을 선택하는 드롭다운 UI가 사라지거나 비활성화됩니다.

   • 대신, 다음과 같은 안내 메시지가 명확하게 표시됩니다.

     “이 계산 방식을 사용하려면, 저장 후 ‘배분 그룹 관리’ 화면에서 호실별 배분율을 정의해야 합니다.”

3. 사용자 행동: 다른 상세 조건 없이 이 상태로 설정을 **[저장]**합니다.

4. 시스템 동작: 이 항목은 ‘총액 지분 비율 배분’ 방식으로 저장되지만, 아직 배분 대상 그룹이 지정되지 않은 ‘설정 필요’ 상태가 됩니다.

Case C: 시설 이용 항목 설정 흐름 (부과 대상이 ‘이용 호실’인 경우)

1. 사용자 행동: 라이브러리에서 ‘헬스장 이용료’ 또는 ‘월 주차료’ 와 같은 시설/서비스 이용 관련 항목을 선택합니다.

2. 시스템 반응 (항목 종류에 따른 자동화):

   • 선택된 항목의 item_type이 ‘개별비’ 또는 **‘시설이용료’**이므로, 시스템은 이 항목의 부과 대상이 **‘이용 호실’**이어야 함을 자동으로 인지합니다.

   • 부과 대상을 선택하는 드롭다운 UI는 **‘이용 호실’**이라는 텍스트로 고정되거나 비활성화됩니다.

   • 동시에 다음과 같은 안내 메시지를 표시합니다.

     “이 항목의 실제 부과 대상 호실은 ‘서비스 이용자 관리’ 화면에서 관리됩니다.”

3. 사용자 행동: ‘이용 호실’ 그룹에 적용할 수 있는 계산 방식(예: 고정액 부과 또는 차량당 단가 배분)을 선택하고, 필요한 상세 조건(금액, 단가 등)을 입력한 후 설정을 **[저장]**합니다.

Step 4: 후속 작업 (상세 내용 정의)

• 만약 Case B처럼 총액 지분 비율 배분 항목을 설정했다면, 사용자는 이제 ‘배분 그룹 관리’ 화면으로 이동하여 해당 항목에 대한 배분 대상 호실과 각 호실의 지분율을 상세하게 설정해야 합니다.
• 만약 Case C처럼 부과 대상이 **‘이용 호실’**인 항목을 설정했다면, 사용자는 이제 ‘서비스 이용자 관리’ 화면으로 이동하여 해당 서비스를 실제로 이용할 호실들을 목록에 추가/관리해야 합니다.

---

부과 대상별 적용 가능 계산 방식 가이드

1. 문서 개요

본 문서는 건물관리 시스템에서 관리비 항목을 설정할 때, 사용자가 선택하는 ‘부과 대상(Target Scope)‘의 유형에 따라 **적용 가능한 ‘계산 방식(Calculation Method)‘**이 무엇인지 명확하게 정의합니다. 이 가이드는 사용자가 논리적 모순 없이 올바른 부과 규칙을 설정하도록 돕는 것을 목표로 합니다.

2. ‘부과 대상’ 중심의 계산 방식 선택

관리비 항목 설정의 핵심은 “누구에게(부과 대상)” 부과할지를 먼저 결정하고, 그 다음 “어떻게(계산 방식)” 나눌지를 결정하는 것입니다. 아래는 각 부과 대상의 성격에 따라 적용할 수 있는 계산 방식의 전체 목록입니다.

유형 1: 일반 그룹 (General Group)

여러 호실의 집합을 대상으로, 공통의 비용을 배분하거나 동일한 규칙을 일괄 적용할 때 사용합니다.

• 해당 부과 대상: 전체 호실, 계약중인 호실, 선택 호실

적용 가능한 계산 방식	이럴 때 사용하세요 (상세 설명 및 예시)
TOTAL_PER_AREA (총액 면적 비례 배분)	“이번 달에 발생한 전체 비용을 그룹 내 호실들의 면적에 비례하여 공평하게 나누고 싶을 때” • 예시: 전체 호실에 부과된 ‘일반관리비’ 총액 1,000만원을 각 호실의 계약면적 비율로 배분
TOTAL_PER_UNIT_EQUAL (총액 균등 배분)	“이번 달에 발생한 전체 비용을 그룹 내 호실 수로 똑같이 나누고 싶을 때” • 예시: 계약중인 호실에 부과된 ‘케이블TV’ 단체 계약 요금 50만원을 세대수로 균등하게 배분
RATE_PER_AREA (면적당 단가 배분)	“그룹 내 모든 호실에, 각 호실의 면적 1㎡당 정해진 단가를 곱하여 부과하고 싶을 때” • 예시: 전체 호실에, 계약면적 ㎡당 1,500원의 ‘기본 관리비’를 부과
RATE_PER_VEHICLE (차량당 단가 배분)	“그룹 내 각 호실이 등록한 차량 대수에 비례하여 주차료를 부과하고 싶을 때” • 예시: 계약중인 호실을 대상으로, 등록된 차량 1대당 5만원의 ‘월 주차료’를 부과
RATE_PER_OCCUPANT (인원당 단가 배분)	“그룹 내 각 호실의 거주 인원수에 비례하여 요금을 부과하고 싶을 때” • 예시: 계약중인 호실을 대상으로, 거주 인원 1인당 1,000원의 ‘커뮤니티 행사비’를 부과
FIXED_AMOUNT (고정액 부과)	“그룹 내 모든 호실에 동일한 고정 금액을 매달 부과하고 싶을 때” • 예시: 전체 호실에 ‘정기 방역비’로 월 3,000원을 일괄 부과

유형 2: 공실 그룹 (Vacant Group)

비어있는 호실들만을 대상으로 비용을 부과할 때 사용합니다. (청구는 소유주에게 전달됩니다)

• 해당 부과 대상: 공실

적용 가능한 계산 방식	이럴 때 사용하세요 (상세 설명 및 예시)
TOTAL_PER_AREA (총액 면적 비례 배분)	• 공실 세대들에게 부과되는 ‘공용 전기료’ 총액을 각 공실의 면적 비율로 배분
TOTAL_PER_UNIT_EQUAL (총액 균등 배분)	• 공실 세대들에게 부과되는 ‘기본 관리비’ 총액을 공실 수로 균등하게 배분
RATE_PER_AREA (면적당 단가 배분)	• 공실에 대해, 면적(㎡)당 500원의 ‘공실 관리비’를 책정하여 부과
FIXED_AMOUNT (고정액 부과)	• 공실에 대해, 매월 2만원의 ‘최소 관리비’를 고정적으로 부과
※ 적용 불가 방식: RATE_PER_VEHICLE, RATE_PER_OCCUPANT, ...USAGE 계열 등. (공실에는 차량, 인원, 사용량이 없음)

유형 3: 이용자 그룹 (User Group)

특정 서비스나 자원을 ‘이용’하는 호실들만을 대상으로 비용을 부과할 때 사용합니다.

• 해당 부과 대상: 서비스 이용 호실, 계량기 사용 호실, 차량 등록 호실 등

적용 가능한 계산 방식	이럴 때 사용하세요 (상세 설명 및 예시)
RATE_PER_USAGE (사용량당 단가 배분)	“각 이용자의 실제 사용량(계량기 검침값)에 정해진 단가를 곱하여 부과하고 싶을 때” • 예시: ‘세대 전기료’ 항목에 대해, 각 세대의 전기 사용량(kWh)에 단가 120원을 곱하여 계산
FIXED_AMOUNT (고정액 부과)	“서비스를 신청한 모든 이용자에게 매달 동일한 구독료를 부과하고 싶을 때” • 예시: ‘헬스장 이용료’ 항목에 대해, 이용 신청자들에게 매월 고정액 3만원을 부과
INDIVIDUAL_USAGE_PROPORTIONAL (사용량 비례 총액 배분)	“서비스 이용자 전체에게 부과된 요금 총액을, 각 이용자의 사용량 비율에 따라 나누고 싶을 때” • 예시: 단지 전체에 부과된 ‘지역난방비’ 총액을, 각 세대의 난방 사용량(열량계) 비율에 따라 배분
TIERED_RATE_PER_USAGE (구간별 요율 배분)	“각 이용자의 실제 사용량에 대해, 사용량 구간별로 다른 단가(누진세)를 적용하여 부과하고 싶을 때” • 예시: 누진세가 적용되는 전기 요금 계산 시 사용

유형 4: 개별 지정 호실 (Individual Unit)

일회성 이벤트로 인해 단 하나의 특정 호실 또는 여러 호실에 각기 다른 금액을 부과해야 할 때 사용합니다.

• 해당 부과 대상: 관리자가 월별 부과 시 직접 지정하는 특정 호실(들)

적용 가능한 계산 방식	이럴 때 사용하세요 (상세 설명 및 예시)
DIRECT_ASSIGNMENT (직접 지정 부과)	“이번 달에만, 이 호실(들)에, 이 금액(들)을, 이 사유로 부과해야 할 때” • 예시: 관리자가 ‘일회성 비용 부과’ 화면에서 ‘101호’를 선택하고, ‘유리 파손 수리비’ 사유로 ‘150,000원’을 직접 입력하여 부과

유형 5: 사전 정의된 배분 그룹 (Predefined Unit)

미리 약속된 특정 비율(%)로 그룹 내에서 나누고 싶을 때 사용합니다.

• 해당 부과 대상: 사전 정의된 배분 그룹

적용 가능한 계산 방식	이럴 때 사용하세요 (상세 설명 및 예시)
TOTAL_PER_SHARE_RATIO (총액 지분 비율 배분)	“이번 달에 발생한 전체 비용을, 미리 약속된 특정 비율(%)로 그룹 내에서 나누고 싶을 때” • 예시: ‘상가 그룹’으로 사전 정의된 배분 그룹을 지정하고, 상가 전용 시설비 총액을 각 상가의 지분율에 따라 배분

부과 대상과 계산 방식에 따른 동적 UI 매트릭스

1. 문서 개요

본 문서는 건물관리 시스템의 ‘청구 항목 설정’ 화면에서, 사용자가 선택하는 **‘부과 대상(Target Scope)‘**과 **‘계산 방식(Calculation Method)‘**의 모든 유효한 조합에 따라, 시스템이 사용자에게 제시해야 할 **‘항목 설정 시점’과 ‘월별 데이터 입력 시점’**의 UI 요소를 명확하게 정의하는 종합 매트릭스입니다.

2. 핵심 원칙: “규칙 설정”과 “실행값 입력”의 분리

• 규칙 설정 화면: 매월 반복될 부과 규칙(기본 단가, 배분 방법 등)을 미리 정의합니다.
• 월별 입력 화면: 매월 변동되는 실제 데이터(총액, 사용량 등)를 입력하고, 필요시 설정된 기본 단가/금액을 수정(Override)합니다.

3. ‘부과 대상’ 및 ‘계산 방식’ 조합별 UI 요소 매트릭스

부과 대상 (target_scope)	계산 방식 (allocation_method)	규칙 설정 화면 UI	월별 데이터 입력 화면 UI
전체, 계약중, 선택 호실	TOTAL_PER_AREA (총액 면적 비례 배분)	[드롭다운] 배분 기준 면적 • 옵션: 전용, 공급, 계약** • [숫자 입력] 월별 총액(원)**	[숫자 입력] 월별 총액(원)
	TOTAL_PER_UNIT_EQUAL (총액 균등 배분)	[숫자 입력] 월별 총액(원)	[숫자 입력] 월별 총액(원)
	RATE_PER_AREA (면적당 단가 배분)	[숫자 입력] 기본 면적당 단가(원) [드롭다운] 기준 면적	(자동 계산) 필요시 단가 수정 가능
	RATE_PER_VEHICLE (차량당 단가 배분)	[숫자 입력] 기본 차량당 단가(원)	(자동 계산) 필요시 단가 수정 가능
	RATE_PER_OCCUPANT (인원당 단가 배분)	[숫자 입력] 기본 인원당 단가(원)	(자동 계산) 필요시 단가 수정 가능
	FIXED_AMOUNT (고정액 부과)	[숫자 입력] 기본 고정 부과액(원)	(자동 계산) 필요시 금액 수정 가능
공실	TOTAL_PER_AREA (총액 면적 비례 배분)	[드롭다운] 배분 기준 면적	[숫자 입력] 월별 총액(원)
	TOTAL_PER_UNIT_EQUAL (총액 균등 배분)	[숫자 입력] 월별 총액(원)	[숫자 입력] 월별 총액(원)
	RATE_PER_AREA (면적당 단가 배분)	[숫자 입력] 기본 면적당 단가(원) [드롭다운] 기준 면적	(자동 계산) 필요시 단가 수정 가능
	FIXED_AMOUNT (고정액 부과)	[숫자 입력] 기본 고정 부과액(원)	(자동 계산) 필요시 금액 수정 가능
이용자 그룹 (서비스, 계량기 등)	RATE_PER_USAGE (사용량당 단가 배분)	[숫자 입력] 기본 사용량당 단가(원)	[표 입력] 월별 세대 사용량 필요시 단가 수정 가능
	TIERED_RATE_PER_USAGE (구간별 요율 배분)	[UI] 구간별 단가 설정	[표 입력] 월별 세대 사용량
	FIXED_AMOUNT (고정액 부과)	[숫자 입력] 기본 고정 부과액(원)	(자동 계산) 필요시 금액 수정 가능
	INDIVIDUAL_USAGE_PROPORTIONAL (사용량 비례 총액 배분)	[숫자 입력] 월별 총액(원)	[숫자 입력] 월별 총액(원) [표 입력] 월별 세대 사용량
사전 정의된 배분 그룹	TOTAL_PER_SHARE_RATIO (총액 지분 비율 배분)	[숫자 입력] 월별 총액(원)
	--- 관리비 등록 화면 ---
개별 지정 호실 (일회성 부과 시)	DIRECT_ASSIGNMENT (직접 지정 부과)	(규칙 설정 없음)	‘일회성 비용 부과’ 화면에서: [호실 선택] [숫자 입력] 부과 금액(원) [텍스트 입력] 부과 사유