01_관리비 항목 관리 기능 명세서

⚙️ QIRO - 관리비 항목 관리 기능 명세서

1. 문서 정보

문서명: QIRO - 관리비 항목 관리 기능 명세서
기능 ID (선택 사항): F-FEE-SETUP-001
관련 요구사항 ID: (예: QIRO-FR-MF-001)
관련 사용자 스토리 ID: (예: US-BM-XXX, US-SA-XXX)
작성일: 2025년 06월 04일
최종 수정일: 2025년 06월 04일
작성자: QIRO 기획팀
검토자/승인자 (선택 사항): (이름 또는 팀)
문서 버전: 1.4 (계량기 기반 유틸리티 항목 제외 및 관련 내용 수정)

2. 기능 개요

2.1. 목적

건물에서 부과할 관리비 항목(예: 일반관리비, 청소비, 건물보험료, 승강기유지비 등)을 정의하고, 각 항목의 부과 방식(고정액, 면적 비례, 세대별 균등 배분 등), 기준 금액 또는 단가, 부가세(과세) 적용 여부, 적용 기간 등을 설정 및 관리한다. 이를 통해 유연하고 정확한 관리비 부과 체계의 기초를 마련하며, 모든 관리비 산정의 기준 정보를 제공한다.

2.2. 설명

본 기능은 관리비 항목에 대한 CRUD(생성, 조회, 수정, 삭제/비활성화) 기능을 제공한다. 관리자는 시스템에서 사용할 관리비 항목들을 사전에 정의하고, 각 항목의 특성에 맞는 부과 로직과 계산 기준을 설정할 수 있다. 신규로 등록되거나 ‘사용 중지’에서 ‘사용’ 상태로 변경된 항목은 익월 청구분부터 적용되는 것을 원칙으로 한다. 설정된 항목 정보는 실제 관리비 산정 시 핵심 데이터로 활용된다.

2.3. 범위

In-Scope (포함 범위):
- 신규 관리비 항목 생성 (항목명, 유형, 과세 여부, 배분 기준, 기준 금액/단가, 단위, 부가세 적용 여부, 적용 시작일/종료일, 상태 등 설정).
- 기존 관리비 항목 목록 조회 (검색 및 필터링 기능 포함).
- 기존 관리비 항목 정보 수정 (상태 변경: 사용/사용 중지 포함).
- 관리비 항목 삭제 (단, 기 사용된 항목은 삭제 제한 또는 비활성화 처리).
Out-of-Scope (제외 범위):
- 계량기 사용량에 직접 연동되는 전기, 수도, 가스 등 유틸리티 항목의 단가 설정 및 사용량 기반 요금 계산 로직 (이는 별도 “검침 데이터 관리” 및 “유틸리티 요금 정책” 기능과 연계되어 “관리비 산정”에서 처리).
- 관리비 항목별 회계 계정 연동 (별도 회계 설정 기능에서 정의 가능).
- 실제 관리비 계산 로직 (별도 ‘관리비 산정’ 기능에서 처리).
- 건물별/단지별 특정 항목 그룹 관리 (기본적으로 시스템 전역 항목 관리).

3. 사용자 인터페이스 (UI) 및 상호작용

3.1. 관련 화면

QIRO > 관리비 관리 > 관리비 항목 정의 (또는 유사 경로)
- 화면 제목: 관리비 항목 정의
- 화면 부제목: 관리비 항목을 정의하고 배분 기준을 설정합니다

3.2. UI 요소별 상세 설명

화면 1: 관리비 항목 목록 조회 화면 (관리비 항목 정의)

image-관리비 항목 목록 화면

UI 요소 ID (선택)	요소명 (Label)	유형 (Type)	기본값/표시 데이터	동작 설명	유효성 규칙/제약조건	비고
FI-LST-00	화면 제목	텍스트	”관리비 항목 정의”	화면의 주된 내용을 나타내는 제목
FI-LST-00a	화면 부제목	텍스트	”관리비 항목을 정의하고 배분 기준을 설정합니다”	화면의 목적을 설명하는 부제목
FI-LST-03	[+ 항목 추가] 버튼	버튼	-	클릭 시 ‘관리비 항목 등록 폼 화면’(또는 팝업)으로 이동/표시		화면 우측 상단 위치
FI-LST-04	관리비 항목 목록	표	-	등록된 관리비 항목들을 표 형태로 표시. 각 행은 개별 관리비 항목을 나타냄.	정렬 기능 제공 권장
(표 컬럼)	항목명	텍스트	(예: 일반관리비)	관리비 항목의 명칭
(표 컬럼)	유형	텍스트	(예: 공용 관리비)	항목의 유형 (예: 공용 관리비, 기타 부과금)		‘개별 사용료’는 계량기 연동 항목 제외
(표 컬럼)	과세 여부	텍스트	(예: 과세)	해당 항목의 과세/비과세 여부
(표 컬럼)	배분 기준	텍스트	(예: 전용면적 비율)	관리비 부과 시 적용되는 배분 기준
(표 컬럼)	단가/금액	숫자/통화	(예: 1,500)	설정된 단가 또는 고정 금액		부과 방식에 따라 의미 상이
(표 컬럼)	단위	텍스트	(예: 원/㎡)	단가 또는 금액의 단위
(표 컬럼)	적용 시작일	날짜	(예: 2025-07-01)	해당 항목 설정의 적용 시작일
(표 컬럼)	적용 종료일	날짜	(예: 2026-06-30)	해당 항목 설정의 적용 종료일 (없을 경우 ‘계속’ 또는 빈 값)
(표 컬럼)	상태	텍스트(배지)	(예: 사용)	항목의 현재 사용 상태 (사용/사용 중지)		상태별 시각적 구분(색상 등)
(표 컬럼)	비고	텍스트	(예: 건물 전체 유지보수 비용)	항목에 대한 추가 설명 또는 특이사항		내용 길 경우 일부만 표시 후 전체 보기 기능 제공
(표 컬럼)	관리	아이콘 버튼 그룹	-	각 항목에 대한 관리 기능 제공 (수정, 삭제)
(표 컬럼 내)	[수정] 아이콘 버튼	아이콘 버튼	(연필 모양)	클릭 시 해당 항목의 정보를 수정할 수 있는 ‘관리비 항목 수정 폼’으로 이동/표시
(표 컬럼 내)	[삭제] 아이콘 버튼	아이콘 버튼	(휴지통 모양)	클릭 시 해당 항목 삭제 확인 팝업 표시 후, 확인 시 항목 삭제 처리	삭제 조건 충족 시	사용 중인 항목은 삭제 불가 또는 비활성화 처리

화면 2: 관리비 항목 등록/수정 폼 화면 image-관리비 항목 추가

UI 요소 ID (선택)	요소명 (Label)	유형 (Type)	기본값/표시 데이터	동작 설명	유효성 규칙/제약조건	비고
FI-FRM-01	항목 ID	텍스트 (읽기전용)	(자동생성/표시)	시스템 내부 관리용 ID		수정 시에는 기존 ID 표시
FI-FRM-02	항목명	입력 필드	-	관리비 항목의 명칭 입력	필수 입력, 최대 50자, 중복 불가 (단, 적용 기간 다르면 허용 가능 - 정책)
FI-FRM-03	유형	드롭다운/라디	(선택)	공용 관리비, 기타 부과금 등 선택	필수 선택	선택에 따라 ‘배분 기준’ 옵션 변경
FI-FRM-03a	과세 여부	드롭다운/라디오	과세	과세, 비과세 선택	필수 선택
FI-FRM-03b	배분 기준	드롭다운	(선택)	전용면적 비율, 호실 균등, (기타 사용자 정의 가능 배분 기준) 등 선택	’유형’에 따라 필수 또는 선택적	’사용량 비례’는 계량기 기반 유틸리티의 경우 여기서 제외
FI-FRM-04	단가/금액	숫자 입력 필드	0	부과 방식(배분 기준)에 따른 단가 또는 총액 입력	숫자만 입력, (배분 기준별 유효성)	예: ‘고정액’ 유형 시 항목 전체 금액
FI-FRM-05	단위	입력 필드	(예: 원, 원/㎡)	단가의 단위 (또는 총액의 단위)	(배분 기준별 추천값)
FI-FRM-06	부가세 적용 여부	체크박스	미적용	해당 항목에 부가세(VAT) 적용 여부 선택 (위 ‘과세 여부’와 통합 또는 상세 설정)
FI-FRM-06a	상태	라디오	사용	사용, 사용 중지 선택		’사용 중지’에서 ‘사용’으로 변경 시 ‘적용 시작일’ 확인/수정 안내 필요
FI-FRM-07	적용 시작일	날짜 선택	등록일 기준 익월 1일	해당 항목 설정이 적용되는 시작일	필수 입력, YYYY-MM-DD 형식, 현재 청구월 마감일 이후 또는 익월 1일 이후	신규 등록 또는 ‘사용 중지’에서 ‘사용’으로 변경 시 익월 청구분부터 적용됩니다.
FI-FRM-08	적용 종료일 (선택)	날짜 선택	-	해당 항목 설정이 만료되는 날짜 (미입력시 계속)	YYYY-MM-DD 형식, 시작일 이후
FI-FRM-09	설명 (선택)	텍스트 영역	-	항목에 대한 추가 설명	최대 200자
FI-FRM-10	[저장] 버튼	버튼	-	입력된 정보 저장	모든 필수 항목 유효성 통과 시 활성화
FI-FRM-11	[취소] 버튼	버튼	-	이전 화면(목록)으로 이동
FI-FRM-12	[삭제] 버튼 (수정시)	버튼	-	해당 항목 삭제 (조건부 활성화)	해당 항목이 사용 중이지 않을 때만 활성화	확인 팝업 표시

3.3. 주요 사용자 시나리오 (흐름)

시나리오 1: 신규 관리비 항목 등록
1. 관리자가 ‘관리비 항목 목록 조회 화면’에서 [+ 항목 추가] 버튼을 클릭한다.
2. 시스템은 ‘관리비 항목 등록 폼 화면’을 표시하며, ‘적용 시작일’은 기본적으로 등록일의 익월 1일로 설정된다. 상태는 ‘사용’으로 기본 설정된다.
3. 관리자가 항목명, 부과 방식, 단가, 단위, 부가세 여부 등 필수 정보를 입력하고, 필요시 ‘적용 시작일’을 익월 이후 날짜로 수정한다.
4. 관리자가 [저장] 버튼을 클릭한다.
5. 시스템은 입력값 유효성을 검사한다. (특히 ‘적용 시작일’이 현재 작업 중인 청구월 또는 그 이전이 아닌지 확인)
  - 성공 시: “관리비 항목이 성공적으로 등록되었습니다.” 메시지를 표시하고, 항목 정보를 저장한 후 목록 화면으로 이동하여 추가된 항목을 표시한다.
  - 실패 시: 오류 메시지를 해당 필드 또는 상단에 표시하고, 수정을 요청한다.
시나리오 2: 기존 관리비 항목 수정 (정보 변경)
1. 관리자가 ‘관리비 항목 목록 조회 화면’에서 수정할 항목을 클릭한다.
2. 시스템은 해당 항목 정보가 채워진 ‘관리비 항목 수정 폼 화면’을 표시한다.
3. 관리자가 필요한 정보(예: 단가, 비고 등)를 수정하고 [저장] 버튼을 클릭한다. (‘적용 시작일’ 및 ‘상태’ 변경 시에는 아래 시나리오 또는 관련 규칙 확인)
4. 시스템은 유효성 검사 후, 성공 시 정보를 업데이트하고 목록 화면으로 이동한다.
시나리오 3: ‘사용 중지’ 항목을 ‘사용’ 상태로 변경 (항목 재사용)
1. 관리자가 ‘관리비 항목 목록 조회 화면’에서 ‘사용 중지’ 상태인 항목을 선택하여 수정 화면으로 진입한다.
2. 관리자가 항목의 ‘상태’를 ‘사용’으로 변경한다.
3. 시스템은 현재 설정된 ‘적용 시작일’을 확인한다.
  - 만약 ‘적용 시작일’이 과거이거나 현재 청구월에 해당하면, 시스템은 “해당 항목을 다시 사용하려면 적용 시작일을 익월 이후로 설정해야 합니다. 적용 시작일을 [시스템 추천일: 익월 1일]로 자동 변경하거나 직접 수정해주세요.” 와 같은 안내를 표시한다. (정책에 따라 자동 변경 또는 사용자 수정 유도)
4. 관리자가 ‘적용 시작일’을 유효한 익월 이후 날짜로 설정(또는 확인)하고 [저장] 버튼을 클릭한다.
5. 시스템은 변경 사항(상태 및 적용 시작일)을 저장하고, “항목 상태가 ‘사용’으로 변경되었으며, [적용 시작일]부터 적용됩니다.” 메시지를 표시한다.

4. 데이터 요구사항

4.1. 관리비 항목 (FeeItem) 엔티티 속성

속성명 (Attribute)	데이터 타입 (Type)	필수 (PK/FK)	설명	예시/비고
`feeItemId`	UUID / Long	PK	관리비 항목 고유 ID (시스템 자동 생성)
`itemName`	String(100)	Y	항목명	”일반관리비”, “청소비”
`impositionMethod`	Enum / String(20)	Y	부과 방식 코드	`FIXED_AMOUNT`, `PER_AREA`, `PER_SHARE`, `COMMON_TOTAL_PER_AREA`, `COMMON_TOTAL_PER_SHARE`
`unitPrice`	BigDecimal / Double	(조건부 Y)	단가 (또는 고정액/총액)	부과 방식이 ‘고정액’이 아니거나, 배분 대상 총액이 아닐 경우 필수
`unit`	String(20)	(조건부 Y)	단위	”원”, “원/㎡”, “원/세대”
`vatApplicable`	Boolean	Y	부가세 적용 여부	`true` / `false` (기본값 `false`)
`description`	String(500)	N	항목 설명
`effectiveStartDate`	Date	Y	적용 시작일. 신규 등록 또는 ‘사용 중지’에서 ‘사용’으로 변경 시, 이 날짜는 실제 관리비 산정 시 현재 진행 중인 청구월이 아닌 익월부터의 적용 여부를 결정합니다.	YYYY-MM-DD. 기본값은 익월 1일.
`effectiveEndDate`	Date	N	적용 종료일 (null이면 계속 유효)	YYYY-MM-DD
`status`	Enum / String(10)	Y	상태 코드	`ACTIVE`, `INACTIVE` (기본값 `ACTIVE`)
`createdBy`	String	Y	생성자 ID
`createdAt`	DateTime	Y	생성 일시
`lastModifiedBy`	String	Y	최종 수정자 ID
`lastModifiedAt`	DateTime	Y	최종 수정 일시

4.2. 부과 방식 (ImpositionMethod) 코드 예시

FIXED_AMOUNT: 세대별 고정액 부과 (예: IPTV 사용료)
PER_AREA: 세대 전용 면적 비례 부과 (예: 일반 관리비)
PER_SHARE: 세대 지분(또는 동일 배분 N) 비례 부과 (예: 공동현관 유지비 N등분)
COMMON_TOTAL_PER_AREA: 특정 공용비 총액을 입력받아 면적 비례 배분 (예: 건물 화재보험료 총액 배분)
COMMON_TOTAL_PER_SHARE: 특정 공용비 총액을 입력받아 세대 지분(또는 N등분) 비례 배분 (예: 청소용역비 총액 배분)
(제외) PER_USAGE: 계량기 사용량 비례 부과 (본 명세서 범위 밖, 별도 기능에서 처리)

5. 처리 로직 및 비즈니스 규칙

R-FEE-SETUP-001: 항목명은 시스템 내에서 고유해야 한다. (단, 적용 기간이 다르면 동일명 허용 가능 여부 정책 결정 필요)
R-FEE-SETUP-002: 부과 방식에 따라 필수 입력값이 달라진다.
- FIXED_AMOUNT 선택 시: ‘단가/금액’ 필드는 해당 세대별 고정 금액을 의미한다. ‘단위’는 ‘원/세대’ 등으로 고정.
- PER_AREA 선택 시: ‘단가/금액’ 필드는 면적당 단가를 의미한다. ‘단위’는 ‘원/㎡’ 등으로 고정.
- COMMON_TOTAL_PER_AREA 또는 COMMON_TOTAL_PER_SHARE 선택 시: ‘단가/금액’ 필드는 비활성화되거나 의미가 없을 수 있으며, 실제 월별 총액은 “월별 공용 관리비 입력” 기능에서 입력받아 이 항목의 배분 기준을 사용한다. ‘단위’는 해당 배분 기준을 나타낸다.
R-FEE-SETUP-003: ‘적용 시작일’은 필수이며, ‘적용 종료일’은 시작일 이후여야 한다 (입력 시).
R-FEE-SETUP-004: 이미 관리비 산정에 사용된 항목은 삭제할 수 없으며, 대신 ‘상태’를 ‘INACTIVE(사용 중지)‘로 변경하여 더 이상 사용되지 않도록 한다. 신규 산정 시에는 ACTIVE 상태이며 적용 기간 내의 항목만 사용한다.
R-FEE-SETUP-005: 부가세 적용 여부 선택 시, 실제 관리비 계산에서 해당 항목 금액에 부가세(예: 10%)를 가산한다.
R-FEE-SETUP-006: 신규로 등록되는 관리비 항목은 등록 시점의 ‘현재 청구월’(관리비 작업이 진행 중인 가장 최근의 청구월)에는 적용되지 않는다. 해당 항목은 ‘적용 시작일’이 도래하는 청구월부터 관리비 산정에 포함된다. ‘적용 시작일’은 기본적으로 등록일의 익월 1일로 제안되며, 사용자는 익월 이후의 날짜로만 설정할 수 있다.
R-FEE-SETUP-007: ‘사용 중지(INACTIVE)’ 상태의 관리비 항목을 ‘사용(ACTIVE)’ 상태로 변경할 경우, 해당 항목은 신규 등록 규칙(R-FEE-SETUP-006)과 동일하게 처리되어, 변경 시점의 현재 청구월이 아닌 ‘적용 시작일’이 도래하는 익월 청구분부터 적용된다. 만약 기존 ‘적용 시작일’이 과거이거나 현재 청구월에 해당한다면, 시스템은 사용자에게 익월 이후 날짜로 ‘적용 시작일’을 수정하도록 안내하거나, 정책에 따라 자동으로 익월 1일 등으로 조정할 수 있다. (UI/UX 정책 결정 필요: 자동 조정 후 알림 vs. 사용자 수정 강제)

6. 오류 처리 및 예외 관리

오류 코드 (선택)	발생 조건	오류 메시지 (User-facing)	시스템 처리 방안
E-FEE-SETUP-01	필수 입력 항목 누락	”[필드명]은(는) 필수 입력 항목입니다.”	저장 차단, 해당 필드에 오류 표시
E-FEE-SETUP-02	항목명 중복	”이미 사용 중인 항목명입니다.”	저장 차단, 항목명 필드에 오류 표시
E-FEE-SETUP-03	단가/금액/날짜 등 형식 오류	”[필드명]의 형식이 올바르지 않습니다.”	저장 차단, 해당 필드에 오류 표시
E-FEE-SETUP-04	적용 종료일이 시작일보다 빠름	”적용 종료일은 시작일 이후여야 합니다.”	저장 차단, 날짜 필드에 오류 표시
E-FEE-SETUP-05	사용 중인 항목 삭제 시도	”해당 항목은 관리비 산정에 사용되어 삭제할 수 없습니다. 대신 ‘사용 중지’ 처리하세요.”	삭제 차단, 안내 메시지 표시
E-FEE-SETUP-06	적용 시작일이 현재 청구월 또는 이전 (신규 등록 또는 상태 변경 시)	“적용 시작일은 현재 진행 중인 청구월 이후(익월부터)로 설정해야 합니다.”	저장 차단, 적용 시작일 필드에 오류 표시

7. (기능별) 성능 요구사항

P-FEE-SETUP-01: 관리비 항목 목록 조회 시, 100개 항목 기준 1초 이내 응답.
P-FEE-SETUP-02: 관리비 항목 저장(생성/수정) 시 1초 이내 처리 완료.

8. (기능별) 보안 요구사항

S-FEE-SETUP-01: 관리비 항목 설정 기능은 ‘총괄관리자’ 또는 ‘관리소장’ 역할(또는 이에 준하는 권한을 가진 역할)만 접근 가능하다.
S-FEE-SETUP-02: 관리비 항목의 변경(생성, 수정, 삭제, 상태 변경) 이력은 감사 로그에 기록되어야 한다 (변경자, 변경 시간, 변경 내용).

9. 다른 기능/모듈과의 연관성

월별 관리비 자동 산정 (Maintenance Fee Calculation): 본 기능에서 설정된 관리비 항목 정의(부과 방식, 단가/금액, 적용 시작일/종료일, 상태 등)는 ‘관리비 산정’ 기능의 핵심 입력 데이터 및 계산 로직의 기준이 된다.
회계 관리 (Accounting Management): (선택 사항) 관리비 항목과 회계 계정 과목을 연결하여, 관리비 부과 시 자동 회계 전표 생성의 기초 데이터로 활용될 수 있다.
월별 공용 관리비 입력: 특정 공용 관리비 항목(예: COMMON_TOTAL_PER_AREA 유형)의 경우, 본 기능에서 항목과 배분 기준을 정의하고, 실제 월별 발생 총액은 “월별 공용 관리비 입력” 기능에서 입력받아 연동된다.

10. (선택 사항) 테스트 고려 사항

다양한 부과 방식에 대한 항목 생성 및 저장 테스트 (특히 COMMON_TOTAL_ 방식 제외한 항목 중심).
항목명 중복 시 예외 처리 테스트.
적용 시작일/종료일 설정에 따른 유효성 검증 테스트.
신규 항목 등록 시 ‘적용 시작일’ 기본값 확인 및 익월부터 적용되는 로직 검증 (관리비 산정 기능 연계 테스트).
‘적용 시작일’을 현재 청구월 또는 이전으로 설정 시도 시 오류 처리 테스트.
‘사용 중지’ 상태의 항목을 ‘사용’ 상태로 변경 시, 익월 적용 규칙(적용 시작일 재설정/확인 포함)이 올바르게 적용되는지 테스트.
사용 중인 항목 삭제 시도 시 제한 처리 테스트.
부가세 적용 여부에 따른 값 처리 확인 (산정 기능 테스트 시 연계).

11. 용어 정의 (선택 사항)

부과 방식 (Imposition Method): 관리비를 각 세대에 부과하는 기준 (예: 세대별 고정 금액, 면적당 단가, 특정 총액을 세대별 N등분).
배분 기준 (Allocation Criteria): 공용 관리비 등을 각 세대에 나누어 부과할 때 사용되는 기준 (예: 전용면적 비율, 세대별 균등).
현재 청구월 (Current Billing Month): 시스템에서 관리비 관련 작업(입력, 산정 등)이 진행 중인 가장 최근의 청구월.
익월 (Next Month): 다음 달.

12. 문서 이력

버전	날짜	작성자	주요 변경 내용
1.0	2025-05-28	QIRO 기획팀	초기 명세서 작성
1.1	2025-05-28	QIRO 기획팀	UI 일람 화면 정보 반영
1.2	2025-05-28	QIRO 기획팀	신규 관리비 항목 익월 적용 규칙 반영 및 관련 항목 수정
1.3	2025-05-28	QIRO 기획팀	관리비 항목 상태 변경(‘사용 중지’->‘사용’) 시 익월 적용 규칙 반영 및 관련 항목 수정
1.4	2025-06-04	QIRO 기획팀	계량기 기반 유틸리티 항목 설정 제외 및 관련 내용 수정 (본 문서로 통합 완료)