신규 청구월 생성 및 초기값 설정 기능 명세서

⚙️ QIRO - 신규 청구월 생성 및 초기값 설정 기능 명세서

1. 문서 정보

문서명: QIRO - 신규 청구월 생성 및 초기값 설정 기능 명세서
기능 ID (선택 사항): F-BILL-CREATE-001
관련 요구사항 ID: (예: QIRO-FR-BMGT-001, QIRO-FR-BMGT-005)
관련 사용자 스토리 ID: (예: US-BM-XXX, US-AS-XXX)
작성일: 2025년 05월 29일
최종 수정일: 2025년 05월 29일
작성자: QIRO 기획팀
검토자/승인자 (선택 사항): (이름 또는 팀)
문서 버전: 1.0

2. 기능 개요

2.1. 목적

새로운 청구월(예: 2025년 7월분)을 시스템에 생성하고, 해당 청구월의 관리비 항목별 초기 설정값 및 전월 미납액 등의 기초 데이터를 효율적이고 안전하게 설정한다. 특히, 이전 청구월의 마감 상태에 따라 최적의 초기값을 제안하고, “선택적 데이터 가져오기” 기능을 통해 사용자가 주도적으로 필요한 데이터를 선별하여 새 청구월의 초기 설정을 완료할 수 있도록 지원한다.

2.2. 설명

본 기능은 사용자가 새로운 청구월을 생성하는 시점에서 시작된다. 시스템은 먼저 “관리비 항목 설정”에 등록된 최신 마스터 항목 목록을 기준으로 새 청구월의 관리비 항목들을 구성한다. 이후, 직전 청구월의 마감 여부를 판단하여 초기값(항목별 설정값, 전월 미납액 등)을 설정하는 방식을 결정한다. 사용자는 시스템이 제안하는 기본값 외에도 “선택적 데이터 가져오기” 기능을 활용하여 이전 달의 특정 항목 설정값 또는 마스터 기본값을 선택적으로 가져와 새 청구월의 초기 데이터를 더욱 유연하고 정교하게 구성할 수 있다.

2.3. 범위

In-Scope (포함 범위):
- 신규 청구월 생성 (대상 연/월 지정).
- 생성 시 “관리비 항목 설정”의 마스터 항목 목록을 기준으로 새 청구월의 관리비 항목 리스트 구성.
- 이전 청구월 마감 상태 자동 감지.
- 이전 청구월 마감 시:
  - 항목별 설정값 및 전월 미납액 등 주요 데이터를 이전 달 확정 값으로 자동 기본 설정.
  - “선택적 데이터 가져오기” 기능을 통해 사용자가 항목별로 이전 달 확정값, 마스터 기본값 중 선택하여 초기값 수정 가능.
- 이전 청구월 미마감 시:
  - 항목별 설정값: “관리비 항목 설정”의 마스터 기본값을 최우선으로 자동 설정.
  - 전월 미납액: ‘0’ 또는 ‘미정산’으로 자동 설정.
  - “선택적 데이터 가져오기” 기능을 통해 사용자가 항목별 설정값만 이전 달 미확정 값 또는 마스터 기본값 중에서 선택적으로 가져오기 가능 (강력한 경고 메시지 동반).
- 이전 청구월 마감 후 데이터 확정:
  - (미마감 상태에서 생성된 새 청구월에 대해) 이전 달 마감 시, 확정된 전월 미납액 등을 시스템이 자동으로 업데이트하거나, 사용자가 “선택적 데이터 가져오기”를 통해 확정된 값을 정확히 가져오도록 유도.
Out-of-Scope (제외 범위):
- “관리비 항목 설정” 기능 자체.(별도 기능 명세서에서 정의)
- “청구월 관리” 기능 중 상태 변경(마감 처리 등) 로직 (단, 본 기능은 상태를 참조하고, 생성 시 초기 상태를 ‘입력 중’으로 설정).
- 공과금(검침값) 입력, 관리비 산정, 고지서 발급, 수납 처리 등 후속 관리비 업무 기능 자체.

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

3.1. 관련 화면

관리비 관리 > 청구월 관리 > [+ 신규 청구월 생성] 버튼 클릭 후 진행되는 일련의 화면 또는 모달 팝업.

3.2. UI 요소별 상세 설명

화면 1: 신규 청구월 생성 기본 정보 입력

UI 요소 ID (선택)	요소명 (Label)	유형 (Type)	기본값/표시 데이터	동작 설명	유효성 규칙/제약조건
BC-NEW-01	대상 연도	숫자	현재 연도	청구월 대상 연도 자동 설정	필수, 유효한 연도(예: 2020~)
BC-NEW-02	대상 월	숫자	현재 월 + 1	청구월 대상 월 자동 설정	필수, 1~12
BC-NEW-03	[생성 및 초기값 설정 진행] 버튼	버튼	-	표시된 연/월로 신규 청구월 생성 프로세스 시작	해당 연월 미 존재 시 활성화

화면 2: 청구월 초기값 설정 (이전 달 마감 여부에 따라 UI/동작 변화)

공통 표시 정보:
- 생성 대상 청구월 (예: 2025년 7월)
- 이전 청구월 (예: 2025년 6월) 및 마감 상태 (예: “마감됨” 또는 “미마감 상태”) 자동 표시.

[선택적 데이터 가져오기] 버튼 또는 영역:

UI 요소 ID (선택)	요소명 (Label)	유형 (Type)	기본값/표시 데이터	동작 설명
BC-OPT-01	데이터 가져오기 실행 버튼	버튼	-	클릭 시 아래 “항목별 데이터 선택” 테이블의 내용을 바탕으로 현재 청구월에 값 적용.
BC-OPT-02	전체 항목 일괄 적용 옵션	드롭다운/라디오	(선택)	모든 항목에 대해 “이전 달 값 사용”, “마스터 기본값 사용” 등을 일괄 선택.

복사 대상 선택 테이블: (새 청구월의 관리비 항목 목록 기반)

컬럼명	설명	UI 요소 예시 (각 행)
관리비 항목명	”관리비 항목 설정”에서 가져온 항목	텍스트 (읽기전용)
데이터 소스 선택	각 항목의 설정값을 어디서 가져올지 선택	드롭다운: “이전 달 값”, “마스터 기본값”
현재 설정값 (입력)	“데이터 소스 선택”에 따라 표시/입력. “이전 달 값” 또는 “마스터 기본값” 선택 시 해당 값 자동 표시(읽기전용).	입력 필드/텍스트
(경고) 이전 달 상태	이전 달이 미마감이고 “이전 달 값”을 선택한 경우, 경고 아이콘 및 메시지 표시 영역	아이콘 + 툴팁/텍스트
전월 미납액	(이 항목은 “전월 미납액” 관련 항목에만 표시)	텍스트 (자동 채워짐 - 이전 달 마감 시) 또는 ‘0’/‘미정산’ (이전 달 미마감 시)

[최종 저장] 버튼 / [청구월 생성 완료] 버튼

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

시나리오 A: 이전 달이 ‘마감’된 상태에서 신규 청구월 생성
1. 관리자가 [신규 청구월 생성] 버튼을 통해 대상 연/월이 표시되고 [생성 및 초기값 설정 진행] 버튼을 클릭한다.
2. 시스템은 이전 달이 ‘마감’되었음을 확인하고, “관리비 항목 설정”의 마스터 항목들로 새 청구월의 항목 목록을 구성한다.
3. 기본 연동: 시스템은 각 항목의 설정값(단가 등)과 “전월 미납액”을 이전 달의 ‘확정된’ 값으로 자동 채워서 “항목별 데이터 선택 테이블”에 표시한다 (데이터 소스: “이전 달 값”으로 자동 선택).
4. 선택적 데이터 가져오기 활용: 관리자는 필요시 특정 항목의 “데이터 소스 선택”을 “마스터 기본값”으로 변경하거나, “직접 입력”을 선택하여 값을 수정한다. 새로 추가된 마스터 항목에 대해서도 값을 설정한다.
5. 모든 설정 검토 후 [최종 저장] 버튼을 클릭하면, 새 청구월이 ‘입력 중’ 상태로 생성되고 설정된 초기값들이 저장된다.
시나리오 B: 이전 달이 ‘미마감’ 상태에서 신규 청구월 생성
1. (A-1과 동일) 관리자가 대상 연/월 표시된 후 [생성 및 초기값 설정 진행] 버튼 클릭.
2. 시스템은 이전 달이 ‘미마감’ 상태임을 확인하고, “관리비 항목 설정”의 마스터 항목들로 새 청구월의 항목 목록을 구성한다.
3. 안전한 초기 생성:
  - 각 항목의 설정값(단가 등): “관리비 항목 설정”의 마스터 기본값을 가져와 “항목별 데이터 선택 테이블”에 표시한다 (데이터 소스: “마스터 기본값”으로 자동 선택).
  - “전월 미납액”: ‘0’ 또는 ‘미정산’으로 표시한다.
4. “선택적 데이터 가져오기”를 통한 준비 작업: 관리자는 “항목별 데이터 선택 테이블”에서 특정 항목의 “데이터 소스 선택”을 “이전 달 값”으로 변경할 수 있다.
  - 이때, 해당 값 옆에 “가져오려는 값은 아직 확정되지 않은 이전달의 정보이며, 이전달 마감 시 변경될 수 있습니다. 최종 부과 전 반드시 확인하십시오!” 경고 메시지가 명확히 표시된다.
5. 모든 설정 검토 후 [최종 저장] 버튼을 클릭하면, 새 청구월이 ‘입력 중’ 상태로 생성되고 설정된 초기값들이 저장된다.
시나리오 C: (시나리오 B 이후) 이전 달 마감 후, 새 청구월에 확정 데이터 반영
1. 이전 청구월이 ‘마감’ 처리된다.
2. 시스템은 이전에 ‘미마감’ 상태에서 생성된 다음 청구월(현재 작업 중인 청구월)에 대해 “이전 달 데이터가 확정되었습니다. 전월 미납액 등 주요 정보를 업데이트하시겠습니까?” 알림을 표시하거나,
3. 관리자가 해당 청구월의 초기값 설정 화면에 다시 진입하여 [선택적 데이터 가져오기] 기능을 실행한다.
4. “항목별 데이터 선택 테이블”에서 “전월 미납액” 등의 항목에 대해 “데이터 소스 선택”을 “이전 달 값(확정됨)“으로 선택(또는 시스템이 자동 제안)하여 정확한 값을 가져온다.
5. [최종 저장] 버튼을 클릭하여 확정된 값으로 업데이트한다.

4. 데이터 요구사항

4.1. 입력 데이터

생성 대상 청구 연도/월
(선택적 데이터 가져오기 시):
- 각 관리비 항목별 데이터 소스 선택 값 (PREVIOUS_MONTH, MASTER_DEFAULT)
- 직접 입력 시 해당 항목의 설정값 (단가, 요율 등)

4.2. 출력/저장 데이터

신규 BillingMonth 레코드: billingMonthId, year, month, status='INPUTTING' 등.

BillingMonthFeeItemSetting (가칭, 청구월별 항목 설정값) 레코드 (각 항목별로 생성/업데이트):

속성명	데이터 타입	설명	예시
`settingId`	UUID/Long (PK)	청구월 항목 설정 고유 ID
`billingMonthId`	UUID/Long (FK)	해당 청구월 ID
`feeItemId`	UUID/Long (FK)	관리비 항목 ID
`unitPrice`	BigDecimal/Double	해당 청구월에 적용될 단가 (또는 고정액)	1500.00
`rate`	BigDecimal/Double	해당 청구월에 적용될 요율 (필요시)	0.05 (5%)
`vatApplicable`	Boolean	해당 청구월에 이 항목 부가세 적용 여부	true
`dataSource`	Enum/String	이 설정값의 출처	`PREVIOUS_CONFIRMED`, `MASTER_DEFAULT`, `PREVIOUS_UNCONFIRMED`, `MANUAL`
`isConfirmedByPrevious`	Boolean	이전달 마감 후 확정된 값으로 업데이트 되었는지 여부 (미마감->마감 시)	true/false
… (기타 필요한 설정값)

BillingMonthUnitUnpaidAmount (가칭, 청구월 세대별 전월 미납액) 레코드:

속성명	데이터 타입	설명	예시
`unpaidId`	UUID/Long (PK)	전월 미납액 고유 ID
`billingMonthId`	UUID/Long (FK)	해당 청구월 ID
`unitId`	UUID/Long (FK)	세대 ID
`unpaidAmount`	BigDecimal/Double	해당 청구월에 이월된 전월 미납액	55000.00
`dataSource`	Enum/String	이 미납액의 출처 (위 `dataSource`와 유사)	`PREVIOUS_CONFIRMED` 등

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

R-BC-001: 새로운 청구월의 관리비 항목 목록은 항상 시스템의 “관리비 항목 설정”에 등록된 ACTIVE 상태의 최신 마스터 항목들을 기준으로 생성된다.
R-BC-002 (이전 달 마감 시 기본 연동):
- 새 청구월의 각 항목별 설정값(BillingMonthFeeItemSetting): 이전 달 마감 시 사용된 확정 설정값을 기본으로 가져온다. dataSource는 PREVIOUS_CONFIRMED로 기록된다.
- 새 청구월의 세대별 전월 미납액(BillingMonthUnitUnpaidAmount): 이전 달 마감 시 확정된 최종 미납액을 자동으로 가져온다. dataSource는 PREVIOUS_CONFIRMED로 기록된다.
R-BC-003 (이전 달 미마감 시 안전한 초기 생성):
- 새 청구월의 각 항목별 설정값: “관리비 항목 설정”의 마스터 기본값을 최우선으로 가져온다. dataSource는 MASTER_DEFAULT로 기록된다.
- 새 청구월의 세대별 전월 미납액: ‘0’ 또는 ‘미정산’으로 설정하고, dataSource는 UNSETTLED로 기록된다.
R-BC-004 (“선택적 데이터 가져오기” 로직):
- 사용자는 UI를 통해 각 항목별 설정값의 데이터 소스를 “이전 달 값”, “마스터 기본값”, “직접 입력” 중 선택할 수 있다.
- “이전 달 값” 선택 시:
  - 이전 달 마감 상태면 확정값을 가져온다 (dataSource -> PREVIOUS_CONFIRMED).
  - 이전 달 미마감 상태면 해당 시점의 미확정 설정값을 가져오되, UI에 강력한 경고 메시지(“가져오려는 값은 아직 확정되지 않은 이전달의 정보이며, 이전달 마감 시 변경될 수 있습니다…”)를 표시한다. dataSource는 PREVIOUS_UNCONFIRMED로 기록된다.
- “마스터 기본값” 선택 시: “관리비 항목 설정”의 현재 마스터 값을 가져온다 (dataSource -> MASTER_DEFAULT).
- “직접 입력” 선택 시: 사용자가 입력한 값을 사용한다 (dataSource -> MANUAL).
- (주의) 미마감된 이전 달의 ‘결과값’(예: 미납액)은 “선택적 데이터 가져오기”로 가져올 수 없거나, 가져오더라도 ‘미확정 임시값’임을 명확히 표시하고 최종 마감 후 반드시 확정값으로 갱신해야 함을 안내한다.
R-BC-005 (이전 달 마감 후 필수 데이터 확정 업데이트):
- 시나리오 B로 생성된 청구월에 대해, 이전 청구월이 최종 ‘마감’ 처리되면, 시스템은 해당 청구월의 BillingMonthUnitUnpaidAmount (전월 미납액) 및 기타 이전달 결과값에 의존하는 항목들을 이전달의 확정된 최종값으로 자동 업데이트하거나, 사용자에게 “선택적 데이터 가져오기” 기능을 통해 해당 ‘확정된 결과값’들을 선택하여 정확하게 가져오도록 강력히 유도해야 한다. 이 과정에서 dataSource는 PREVIOUS_CONFIRMED로, isConfirmedByPrevious는 true로 업데이트 된다. 이 업데이트는 필수적이다.
R-BC-006: 신규 청구월 생성 시 초기 상태는 항상 INPUTTING으로 설정된다.

6. 오류 처리 및 예외 관리

오류 코드 (선택)	발생 조건	오류 메시지 (User-facing)	시스템 처리 방안
E-BC-01	(선택적 가져오기) 이전 달 데이터 조회 실패	”이전 달 데이터를 가져오는 중 오류가 발생했습니다.”	해당 항목 값 비우거나 마스터 기본값으로 대체, 오류 알림
E-BC-02	(선택적 가져오기) 마스터 기본값 조회 실패	”관리비 항목 마스터 정보를 가져오는 중 오류가 발생했습니다.”	해당 항목 값 비우거나 사용자 직접 입력 유도, 오류 알림
E-BC-03	미마감 이전 달의 ‘결과값’(미납액 등)을 확정값처럼 처리 시도	”아직 이전 달이 마감되지 않아 정확한 OOO 값을 가져올 수 없습니다.”	해당 값 ‘미정산’ 처리 및 안내 메시지

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

P-BC-01: 신규 청구월 생성 및 기본 초기값(마스터 기준) 설정 완료까지 5초 이내.
P-BC-02: “선택적 데이터 가져오기” 실행 시 (기준 설정 필요) 데이터 로드 및 화면 표시에 5초 이내, 최종 저장 3초 이내.

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

S-BC-01: 신규 청구월 생성 및 초기값 설정 기능은 ‘총괄관리자’, ‘관리소장’ 등 인가된 역할만 접근 가능하다.
S-BC-02: 청구월 생성 및 주요 초기값 변경 이력은 감사 로그에 기록되어야 한다.

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

청구월 관리: 이 기능은 ‘청구월 관리’의 핵심적인 하위 프로세스이다. 생성된 청구월은 ‘청구월 관리’ 목록에 추가된다.
관리비 항목 설정: 새로운 청구월의 관리비 항목 목록 및 마스터 기본 설정값을 가져오는 원천 데이터이다.
(이후 모든 관리비 관련 기능): 공과금 입력, 관리비 입력(공용), 관리비 산정, 고지서 발급, 수납 처리 기능들은 모두 본 기능을 통해 생성되고 초기 설정된 ‘청구월’을 기준으로 작업을 수행한다.

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

이전 청구월이 ‘마감’된 경우와 ‘미마감’된 경우 각각에 대한 신규 청구월 생성 및 초기값 설정 테스트.
“선택적 데이터 가져오기” 기능의 다양한 시나리오 테스트:
- 특정 항목만 이전 달 값 가져오기.
- 특정 항목만 마스터 기본값 사용하기.
- 특정 항목 직접 입력하기.
- 미마감 이전 달에서 ‘설정값’ 가져오기 시 경고 메시지 확인.
이전 달 마감 후, ‘미마감’ 상태에서 생성되었던 다음 청구월의 ‘전월 미납액’ 등이 확정값으로 올바르게 업데이트(자동 또는 수동 유도)되는지 검증.
“관리비 항목 설정”에 신규 항목 추가/기존 항목 변경 후, 새 청구월 생성 시 항목 목록 및 기본값이 올바르게 반영되는지 테스트.

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

마스터 기본값 (Master Default Value): “관리비 항목 설정”에 정의된 각 관리비 항목의 표준 설정값(단가, 요율 등).
확정된 값 (Confirmed Value): 이전 청구월이 ‘마감’ 처리되어 더 이상 변경되지 않는 최종 데이터 값 (예: 최종 미납액, 실제 사용된 단가).
미확정 값 (Unconfirmed Value): 이전 청구월이 아직 ‘마감’되지 않아 변경될 가능성이 있는 잠정적인 데이터 값.
선택적 데이터 가져오기 (Optional Data Import): 새 청구월 초기값 설정 시, 사용자가 각 항목별로 데이터 소스(이전 달, 마스터 등)를 선택하거나 직접 입력할 수 있도록 하는 기능.

12. 문서 이력

버전	날짜	작성자	주요 변경 내용
1.0	2025-05-29	QIRO 기획팀	신규 청구월 생성 및 초기값 설정 (선택적 데이터 가져오기 기능 통합) 기능 명세서 초안 작성