01_외부 고지서 고객번호 및 연결 관리 기능 명세서

⚙️ QIRO - 외부 고지서 고객번호 및 연결 관리 기능 명세서

1. 문서 정보

문서명: QIRO - 외부 고지서 고객번호 및 연결 관리 기능 명세서
기능 ID (선택 사항): F-EXTBILL-MGMT-001
관련 요구사항 ID: (예: QIRO-FR-MF-050, QIRO-FR-MF-051)
관련 사용자 스토리 ID: (예: US-BM-XXX, US-AS-XXX)
작성일: 2025년 05월 28일
최종 수정일: 2025년 05월 28일
작성자: QIRO 기획팀
검토자/승인자 (선택 사항): (이름 또는 팀)
문서 버전: 1.2 (UI 이미지 기반 상세 필드 및 복수 용도 지정 기능 반영)

2. 기능 개요

2.1. 목적

건물 단위로 청구되는 주요 외부 공과금(예: 전기, 수도, 가스 등)의 고지서 식별 정보(고객번호/납부자번호, 공급자, 별명 등)를 건물별로 등록하고 관리한다. 등록된 각 고객번호가 관리비 청구 시 개별 사용료와 공용 사용료 중 어떤 용도로 (또는 둘 다) 사용될지를 지정하여, 향후 해당 고객번호로 청구된 월별 총액을 입력하고, 그 금액을 각 세대에 설정된 배분 기준에 따라 부과하기 위한 기초 정보를 제공한다.

2.2. 설명

본 기능은 관리자가 건물별 외부 공급자(예: 한국전력공사, 지역 도시가스사)로부터 받는 공과금 고지서의 고객번호, 종류, 공급자명, 별명, 계량기 번호, 메모 등을 등록/수정/삭제할 수 있도록 한다. 핵심적으로, 각 등록된 고객번호에 대해 관리비 청구 시 개별 사용료로 처리할지, 공용 사용료로 처리할지, 또는 하나의 고객번호로 청구된 금액을 두 용도 모두에 나누어 사용할지 여부를 지정할 수 있다. “고객번호 연결 현황” 섹션은 이렇게 설정된 고객번호가 실제 관리비 항목과 어떻게 연계되는지를 보여준다.

2.3. 범위

In-Scope (포함 범위):
- 외부 고지서 고객번호 기본 정보 CRUD (고객번호, 종류, 공급자, 별명, 계량기 번호, 메모).
- 각 고객번호에 대한 관리비 청구 용도 지정 (개별 사용료, 공용 사용료 - 복수 선택 가능).
- 고객번호 목록 조회 (필터링 및 검색 기능 포함 가능).
- “고객번호 연결 현황” 조회 (등록된 고객번호가 어떤 관리비 항목 유형과 연결되는지 표시).
Out-of-Scope (제외 범위):
- 등록된 고객번호에 대한 월별 실제 고지 금액 입력 (이는 별도의 “월별 외부 고지서 금액 입력” 기능).
- 하나의 고객번호로 청구된 총액을 ‘개별 사용료분’과 ‘공용 사용료분’으로 나누는 구체적인 비율/금액 설정 로직 (본 FRS에서는 용도 지정까지만 다루며, 실제 분배 규칙 설정은 연계 기능 또는 상세 설정에서 다룰 수 있음).
- 입력된 고지 금액을 세대별로 배분하는 상세 계산 로직 실행 (이는 “관리비 산정” 기능).
- 외부 공급자 시스템과의 실시간 연동.

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

3.1. 관련 화면

QIRO > 관리비 관리 > 외부 고지서 관리 (탭)
- 화면 탭 구성: 관리비 항목 | 외부 고지서 관리 (선택됨) | 납부 정보 설정

3.2. UI 요소별 상세 설명 (제공된 이미지 기반)

화면 1: 외부 고지서 고객번호 관리 화면

섹션 1: 외부 고지서 고객번호 관리

섹션 제목: 외부 고지서 고객번호 관리
섹션 부제목: 외부 고지서 고객번호 및 연결 규칙을 관리합니다

UI 요소 ID (선택)	요소명 (Label)	유형 (Type)	기본값/표시 데이터	동작 설명	유효성 규칙/제약조건	비고
EB-LST-01	[+ 고객번호 추가] 버튼	버튼	-	클릭 시 ‘고객번호 추가’ 모달 팝업 표시		화면 우측 상단 위치
EB-LST-02	고객번호 목록	표	-	등록된 외부 고지서 고객번호 정보를 표 형태로 표시	정렬 기능 제공 권장
(표 컬럼)	고객번호	텍스트	(예: 1234567890)	공급자가 부여한 고유 고객 식별 번호
(표 컬럼)	종류	텍스트	(예: 전기)	공과금의 종류 (전기, 수도, 가스 등)
(표 컬럼)	공급자	텍스트	(예: 한국전력공사)	공과금 공급 업체명
(표 컬럼)	별명	텍스트	(예: 주 계량기	사용자가 지정한 외부 고지서의 알기쉬운 명칭
(표 컬럼)	계량기 번호	텍스트	(예: 1234567890)	관련 계량기 번호 (선택 입력 사항)
(표 컬럼)	관리비 청구	텍스트	(예: 개별 사용료, 공용 사용료)	선택한 개별 사용료, 공용 사용료
(표 컬럼)	관리	아이콘 버튼 그룹	-	각 항목에 대한 관리 기능 제공
(표 컬럼 내)	[편집] 아이콘 버튼	아이콘 버튼	(연필 모양)	클릭 시 해당 고객번호 정보를 수정할 수 있는 ‘고객번호 편집’ 모달 팝업 표시
(표 컬럼 내)	[삭제] 아이콘 버튼	아이콘 버튼	(휴지통 모양)	클릭 시 해당 고객번호 삭제 확인 팝업 표시 후, 확인 시 삭제 처리

화면 2 (모달): 고객번호 추가

모달 제목: 고객번호 추가
모달 부제목: 외부 고지서 고객번호를 추가합니다. 고객번호는 외부 고지서를 등록할 때 사용됩니다.

UI 요소 ID (선택)	요소명 (Label)	유형 (Type)	Placeholder/기본값	유효성 규칙/제약조건
EB-ADD-01	고객번호	입력 필드	고객번호를 입력하세요	필수, 최대 50자
EB-ADD-02	종류	드롭다운	(예: 전기)	필수 (전기, 수도, 가스 등)
EB-ADD-03	공급자	입력 필드	공급자를 입력하세요	필수, 최대 100자
EB-ADD-04	별명	입력 필드	구분을 위한 별명을 입력하세요	최대 100자 (목록의 ‘빌딩’ 컬럼에 표시될 수 있음)
EB-ADD-05	계량기 번호 (선택사항)	입력 필드	계량기 번호 (선택사항)	최대 50자
EB-ADD-06	메모	입력 필드	메모를 입력하세요	최대 500자
EB-ADD-07	관리비 청구: 개별 사용료	체크박스	(체크 해제)
EB-ADD-08	관리비 청구: 공용 사용료	체크박스	(체크 해제)
EB-ADD-BTN-01	[취소]	버튼	-
EB-ADD-BTN-02	[추가]	버튼	-

화면 3 (모달): 고객번호 편집
- 모달 제목: 고객번호 편집
- 모달 부제목: 외부 고지서 고객번호를 수정합니다. 고객번호는 외부 고지서를 등록할 때 사용됩니다.
- (입력 필드는 ‘고객번호 추가’와 동일하나, 기존 값으로 채워져 있음)
- 사용 유형 (이미지에는 이 레이블로 표시됨) 섹션에 개별 사용료, 공용 사용료 체크박스가 있음.
- 버튼: [취소], [저장]

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

시나리오 1: 신규 외부 고지서 고객번호 등록 (예: 건물 전체 전기료, 공용 및 개별 모두 해당)
1. 관리자가 ‘외부 고지서 고객번호 관리’ 화면에서 [+ 고객번호 추가] 버튼을 클릭한다.
2. ‘고객번호 추가’ 모달이 표시된다.
3. 관리자가 고객번호, 종류(“전기”), 공급자(“한국전력공사”), 별명(“우리빌딩 전체 전기”), 계량기 번호(선택), 메모(선택)를 입력한다.
4. 관리비 청구 섹션에서 [v] 개별 사용료 와 [v] 공용 사용료 두 항목 모두 체크한다.
5. [추가] 버튼을 클릭한다.
6. 시스템은 유효성 검사 후 정보를 저장하고, “고객번호가 성공적으로 추가되었습니다.” 메시지를 표시한다. 목록이 갱신된다.
7. “고객번호 연결 현황”에는 이 고객번호가 ‘전기’ 종류의 ‘개별 사용료’ 및 ‘공용 사용료’와 연관됨이 표시되거나, 상세 배분 규칙 설정으로 이어지는 링크가 제공될 수 있다.
시나리오 2: 기존 고객번호의 사용 유형 변경
1. 관리자가 목록에서 수정할 고객번호의 [편집] 아이콘을 클릭한다.
2. ‘고객번호 편집’ 모달이 표시되고 기존 정보가 나타난다.
3. 관리자가 ‘사용 유형’(또는 ‘관리비 청구’) 섹션에서 체크박스 선택을 변경한다 (예: ‘공용 사용료’만 체크).
4. [저장] 버튼을 클릭한다.
5. 시스템은 변경사항을 저장하고 목록 및 연결 현황을 갱신한다.

4. 데이터 요구사항

4.1. 외부 고지서 계정 (ExternalBillAccount) 엔티티 속성

속성명 (Attribute)	데이터 타입 (Type)	필수 (PK/FK)	설명	예시/비고
`extBillAccountId`	UUID / Long	PK	외부 고지서 계정 고유 ID
`customerNumber`	String(50)	Y	공급자가 부여한 고객번호/납부자번호
`utilityType`	Enum / String(30)	Y	공과금 종류 (코드화: `ELECTRICITY`, `WATER`, `GAS`)	드롭다운 선택 값
`supplierName`	String(100)	Y	공급자 명칭	”한국전력공사”
`buildingId`	UUID / Long	FK (Y)	연결된 건물 ID (Building 참조)	UI에는 명시적 선택 없으나, 컨텍스트상 필요 또는 ‘별명’과 연계
`accountNickname`	String(100)	Y	계정 별칭 (사용자 식별용)	“행복빌딩 전체 전기”, “본관 전체 수도”
`meterNumber`	String(50)	N	관련 계량기 번호
`remarks`	String(500)	N	메모
`isForIndividualUsage`	Boolean	Y	개별 사용료 청구 대상 여부 (기본값 `false`)	체크박스 연동
`isForCommonUsage`	Boolean	Y	공용 사용료 청구 대상 여부 (기본값 `false`)	체크박스 연동
`isActive`	Boolean	Y	이 계정 정보의 활성 여부 (기본값 `true`)
`createdAt`	DateTime	Y	생성 일시
`createdBy`	String	Y	생성자 ID
`lastModifiedAt`	DateTime	Y	최종 수정 일시
`lastModifiedBy`	String	Y	최종 수정자 ID

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

R-EXTBILL-001: (buildingId + customerNumber + utilityType) 또는 (customerNumber + utilityType + accountNickname) 조합은 시스템 내에서 고유해야 한다 (중복 등록 방지 - 정책 결정 필요).
R-EXTBILL-002: ‘관리비 청구’ 용도(isForIndividualUsage, isForCommonUsage) 중 적어도 하나는 선택되어야 한다 (정책 결정).
R-EXTBILL-003: 고객번호의 utilityType과 isForIndividualUsage / isForCommonUsage 플래그 값에 따라, 시스템은 이 고객번호가 어떤 FeeItem(관리비 항목 설정에서 정의된)과 연관되는지 내부적으로 매핑하거나 “고객번호 연결 현황”에 표시한다.
- 예: utilityType=‘ELECTRICITY’, isForIndividualUsage=true → “세대 전기료” FeeItem과 연관.
- 예: utilityType=‘ELECTRICITY’, isForCommonUsage=true → “공용 전기료” FeeItem과 연관.
R-EXTBILL-004: 만약 하나의 ExternalBillAccount에 대해 isForIndividualUsage와 isForCommonUsage가 모두 true로 설정된 경우:
- 이는 해당 고객번호로 청구된 월별 총액이 추후 ‘개별 사용료분’과 ‘공용 사용료분’으로 나뉘어 처리될 수 있음을 의미한다.
- 실제 금액 분배 로직은 “월별 외부 고지서 금액 입력” 기능 또는 별도의 “배분 규칙 상세 설정” 기능에서 정의되고 처리된다. (본 기능 명세서의 범위는 용도 지정까지)
- “고객번호 연결 현황”에는 이 고객번호가 두 가지 유형의 관리비 항목 모두에 영향을 미침을 명시해야 한다.
R-EXTBILL-005: “고객번호 연결 현황”의 “자동으로 연결됩니다”라는 문구는, 시스템이 utilityType과 isForIndividualUsage/isForCommonUsage 플래그를 조합하여 자동으로 적절한 FeeItem 유형(예: 관리비항목설정의 표준항목)과 매칭하여 참고 정보를 제공함을 의미할 수 있다. (실제 강제적 연결보다는 정보 제공 및 후속 설정 유도)

6. 오류 처리 및 예외 관리

오류 코드 (선택)	발생 조건	오류 메시지 (User-facing)	시스템 처리 방안
E-EXTBILL-01	필수 입력 항목 누락 (고객번호, 종류, 공급자, 별명 등)	“[필드명]은(는) 필수 입력 항목입니다.”	저장 차단, 해당 필드에 오류 표시
E-EXTBILL-02	고객번호 중복 (정책에 따라)	“이미 등록된 고객번호 설정입니다 ([별명] - [종류]).”	저장 차단, 고객번호 필드에 오류 표시
E-EXTBILL-03	관리비 청구 용도 미선택 (정책에 따라)	“관리비 청구 용도(개별 사용료 또는 공용 사용료)를 하나 이상 선택해주세요.”	저장 차단, 안내 메시지 표시

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

P-EXTBILL-01: 고객번호 목록 조회 시 (최대 1000개 기준) 2초 이내 응답.
P-EXTBILL-02: 고객번호 정보 저장(생성/수정) 시 1초 이내 처리 완료.

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

S-EXTBILL-01: 외부 고지서 고객번호 관리 기능은 ‘총괄관리자’, ‘관리소장’, ‘경리담당자’ 등 인가된 역할만 접근 가능하다.
S-EXTBILL-02: 고객번호, 공급자 정보 등은 중요 정보로 간주하여 접근 권한을 통제한다.
S-EXTBILL-03: 정보 변경 이력은 감사 로그에 기록되어야 한다.

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

건물정보 관리: (UI에는 명시적 선택 없으나 데이터 모델상) buildingId를 통해 특정 건물과 고객번호를 연결한다.
관리비 항목 설정 (FeeItem): ‘관리비 청구’ 용도 선택에 따라, 이 고객번호가 어떤 종류의 관리비 항목(예: 공용 전기료, 세대 수도료 등)과 연관되는지 시스템 내부적으로 연결된다. “고객번호 연결 현황”에 이 정보가 반영된다.
월별 외부 고지서 금액 입력 (또는 월별 공용 관리비 입력): 본 기능에서 등록된 ExternalBillAccount를 기준으로 해당 청구월의 건물 단위 총 청구액을 입력받는다. 이때, isForIndividualUsage와 isForCommonUsage 플래그를 참조하여 입력받을 금액의 성격을 구분하거나, 만약 둘 다 true이면 총액을 분할하여 입력받는 UI를 제공할 수 있다.
관리비 산정: 본 기능에서 설정된 고객번호 및 청구 용도 플래그를 기반으로, 입력된 총액을 ‘관리비 항목 설정’에 정의된 배분 기준에 따라 각 세대에 배분 계산한다.

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

고객번호 기본 정보 CRUD 테스트.
‘관리비 청구’ 용도 체크박스 조합(개별만, 공용만, 둘 다, 둘 다 해제-정책에 따라)에 따른 저장 및 표시 테스트.
고객번호 중복 등록 시도 시 예외 처리 테스트.
‘고객번호 연결 현황’ 섹션에 정보가 올바르게 표시되는지 확인 (특히 utilityType과 용도 플래그 조합에 따른 연결).
등록된 고객번호 정보가 후속 기능(월별 금액 입력, 관리비 산정)에서 정상적으로 사용되는지 연계 테스트.

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

외부 고지서 고객번호 (External Bill Customer Number): 외부 공급자가 건물 단위로 발행하는 공과금 고지서의 식별 번호 (납부자번호 등).
별명 (Account Nickname): 여러 고객번호를 구분하거나 특정 건물/용도를 쉽게 식별하기 위해 사용자가 부여하는 이름.
관리비 청구 용도 (Maintenance Fee Billing Purpose): 해당 고객번호로 청구되는 금액이 관리비 부과 시 ‘개별 사용료’로 처리될지, ‘공용 사용료’로 처리될지, 또는 둘 다에 해당하는지를 나타내는 구분.

12. 문서 이력

버전	날짜	작성자	주요 변경 내용
1.0	2025년 06월 02일	QIRO 기획팀	외부 고지서 고객번호 및 연결 관리 초기 명세서 안 작성
1.1	2025년 06월 02일	QIRO 기획팀	외부 고지서 금액의 상세 배분 규칙 설정(링크 테이블) 개념 반영 (이후 v1.2에서 UI 단순화로 변경)
1.2	2025년 06월 02일	QIRO 기획팀	사용자 제공 UI 이미지(고객번호 추가/편집 모달) 기반으로 필드 상세화 및 ‘개별/공용 사용료’ 용도 지정 기능 명확화.

참고 화면

image-외부고지서관리 image-고객번호추가 image-고객번호편집