관리비 항목

정의

관리비 항목은 건물의 운영 및 유지보수에 필요한 비용을 항목별로 구분하여 관리하는 기본 단위입니다. 각 항목은 고유한 이름을 가지며, 관리비 청구서에 개별 항목명으로 표시되어 입주자에게 청구됩니다.

예: “일반관리비”, “청소비”, “전기료” 등 각각의 항목이 청구서의 개별 행으로 나타납니다.

관리비 항목은 사용 목적에 따라 청구항목 템플릿과 청구월 청구항목 두 가지로 나뉩니다.

---

청구항목 템플릿 (ChargeItemTemplate)

청구항목 템플릿은 반복적으로 사용되는 관리비 항목의 기본 틀을 정의하는 마스터 데이터입니다. 템플릿을 사용하면 매번 동일한 정보를 입력할 필요 없이 관리비 항목을 생성할 수 있습니다.

구성 요소

항목명 (name)

타입: string

설명: 관리비 항목의 이름입니다. (예: “1층 공용 전기료”)

목적: 항목을 식별하고 구분하기 위해 필요합니다. 이 이름이 청구서에 표시됩니다.

청구금액 (amount)

타입: integer

설명: 해당 항목의 총 청구금액 (VAT 포함)입니다. 공급 가액이 아닙니다.

목적: 항목별로 부과할 금액을 명확히 하기 위해 필요합니다.

부가세율 (vat_rate)

타입: string | null

설명: 과세 상태를 나타냅니다. null이면 비과세, "0.0"이면 영세율, "0.1"이면 10% 세율을 의미합니다.

목적: 세금 계산 및 세금계산서를 발행 하기 위해 필요합니다.

배분 규칙 (allocation_rule)

타입: object

설명: 청구금액을 각 호실에 배분하는 방식을 정의합니다.

목적: 항목의 비용을 어떻게 배분할지 명확히 하기 위해 필요합니다.
자세한 내용은 배분방식 문서를 참고하세요.

비고 (description)

타입: string | null

설명: 항목에 대한 추가 설명이나 특이사항을 기록합니다.

목적: 사용자가 항목에 대한 주석을 남길 수 있게 하기 위해 필요합니다.

데이터 모델

TypeScript

// 배분 규칙(allocation_rule)은 관련 문서의 배분방식 문서에 정의되어 있습니다.
// 이 문서에서는 설명을 위해 간략화된 타입을 사용합니다.
export type AllocationRule = {
  type: "SCOPE_BASE" | "SPECIFIC_UNITS" | "UNIT_RATIO";
  // ... 각 타입에 따른 추가 속성
};

export type ChargeItemTemplateRequest = {
  /** 청구항목명 */
  name: string;
  /** 청구금액 (VAT 포함) */
  amount: number;
  /** 비고 */
  description?: string | null;
  /** 부가세율 (e.g., "0.1" for 10%) */
  vat_rate?: string | null;
  /** 배분 규칙 */
  allocation_rule: AllocationRule;
};

export type ChargeItemTemplateResponse = ChargeItemTemplateRequest & {
  /** 템플릿 ID */
  id: number;
  /** 생성 시간 */
  created_at: string;
  /** 수정 시간 */
  updated_at: string;
};

Kotlin

// 배분 규칙(allocation_rule)은 OpenAPI vo/charge-item-vo.yaml에 정의되어 있습니다.
// 이 문서에서는 설명을 위해 간략화된 타입을 사용합니다.
sealed class AllocationRule {
    // data class ScopeBase(...) : AllocationRule()
    // data class SpecificUnits(...) : AllocationRule()
    // data class UnitRatio(...) : AllocationRule()
}

data class ChargeItemTemplateRequest(
    /** 청구항목명 */
    val name: String,
    /** 청구금액 (VAT 포함) */
    val amount: Int,
    /** 비고 */
    val description: String?,
    /** 부가세율 (e.g., "0.1" for 10%) */
    val vat_rate: String?,
    /** 배분 규칙 */
    val allocation_rule: AllocationRule
)

data class ChargeItemTemplateResponse(
    /** 템플릿 ID */
    val id: Int,
    /** 청구항목명 */
    val name: String,
    /** 청구금액 (VAT 포함) */
    val amount: Int,
    /** 비고 */
    val description: String?,
    /** 부가세율 (e.g., "0.1" for 10%) */
    val vat_rate: String?,
    /** 배분 규칙 */
    val allocation_rule: AllocationRule,
    /** 생성 시간 */
    val created_at: String,
    /** 수정 시간 */
    val updated_at: String
)

---

청구월 청구항목 (MonthlyChargeItem)

청구월 청구항목은 특정 청구월에 실제로 부과되는 개별 관리비 항목입니다. 이 항목은 청구항목 템플릿으로부터 생성되거나, 특정 월에만 발생하는 일회성 비용을 위해 직접 생성될 수 있습니다.

예: 2024년 8월 청구서에 포함될 “승강기 수리비”는 해당 월에만 존재하는 청구월 청구항목입니다.

구성 요소

청구월 청구항목은 청구항목 템플릿의 모든 구성 요소를 상속받으며, 다음과 같은 추가 속성을 가집니다.

확정 여부 (is_confirmed)

타입: boolean

설명: 해당 청구 항목의 수정 가능 여부를 나타냅니다. true로 설정되면 더 이상 수정하거나 삭제할 수 없으며, 관리비 산출에 포함될 준비가 되었음을 의미합니다.

목적: 청구 항목이 올바른지 확인하고, 최종적으로 청구서에 포함될 준비가 되었음을 나타내기 위해 필요합니다.

데이터 모델

TypeScript

// 배분 규칙(allocation_rule)은 관련 문서의 배분방식 문서에 정의되어 있습니다.
// 이 문서에서는 설명을 위해 간략화된 타입을 사용합니다.
export type AllocationRule = {
  type: "SCOPE_BASE" | "SPECIFIC_UNITS" | "UNIT_RATIO";
  // ... 각 타입에 따른 추가 속성
};

export type MonthlyChargeItemRequest = {
  /** 청구항목명 */
  name: string;
  /** 청구금액 (VAT 포함) */
  amount: number;
  /** 비고 */
  description?: string | null;
  /** 부가세율 (e.g., "0.1" for 10%) */
  vat_rate?: string | null;
  /** 배분 규칙 */
  allocation_rule: AllocationRule;
};

export type MonthlyChargeItemResponse = MonthlyChargeItemRequest & {
  /** 청구항목 ID */
  id: number;
  /** 확정 여부 */
  is_confirmed: boolean;
  /** 생성 시간 */
  created_at: string;
  /** 수정 시간 */
  updated_at: string;
};

Kotlin

// 배분 규칙(allocation_rule)은 OpenAPI vo/charge-item-vo.yaml에 정의되어 있습니다.
// 이 문서에서는 설명을 위해 간략화된 타입을 사용합니다.
sealed class AllocationRule {
    // data class ScopeBase(...) : AllocationRule()
    // data class SpecificUnits(...) : AllocationRule()
    // data class UnitRatio(...) : AllocationRule()
}

data class MonthlyChargeItemRequest(
    /** 청구항목명 */
    val name: String,
    /** 청구금액 (VAT 포함) */
    val amount: Int,
    /** 비고 */
    val description: String?,
    /** 부가세율 (e.g., "0.1" for 10%) */
    val vat_rate: String?,
    /** 배분 규칙 */
    val allocation_rule: AllocationRule
)

data class MonthlyChargeItemResponse(
    /** 청구항목 ID */
    val id: Int,
    /** 청구항목명 */
    val name: String,
    /** 청구금액 (VAT 포함) */
    val amount: Int,
    /** 비고 */
    val description: String?,
    /** 부가세율 (e.g., "0.1" for 10%) */
    val vat_rate: String?,
    /** 배분 규칙 */
    val allocation_rule: AllocationRule,
    /** 확정 여부 */
    val is_confirmed: Boolean,
    /** 생성 시간 */
    val created_at: String,
    /** 수정 시간 */
    val updated_at: String
)

관련 문서

배분방식 관리비 항목의 금액을 각 호실에 나누는 규칙을 정의합니다.