청구월 주요 상태와 내부 진행 상태 관계 정의

📊 QIRO 청구월 주요 상태와 내부 진행 상태 관계 정의

1. 문서 정보

문서명: QIRO 청구월 주요 상태와 내부 진행 상태 관계 정의
프로젝트명: QIRO (중소형 건물관리 SaaS) 프로젝트
작성일: 2025년 05월 30일
최종 수정일: 2025년 05월 30일
작성자: QIRO 기획팀
검토자/승인자 (선택 사항): (이름 또는 팀)
문서 버전: 1.0

2. 개요

2.1. 문서 목적

본 문서는 QIRO 서비스 내에서 관리되는 ‘청구월(Billing Month)‘의 생명주기를 정의하고, 각 주요 상태(준비중, 진행중, 완료)와 해당 상태 내에서의 세부적인 내부 진행 상태 간의 관계를 명확히 기술하는 것을 목적으로 한다. 이를 통해 청구월 관리 업무의 일관성과 투명성을 확보하고, 시스템 기능 설계 및 사용자 이해를 돕는다.

2.2. 적용 범위

본 정의는 QIRO 서비스의 관리비 청구 및 수납과 관련된 모든 청구월의 상태 관리에 적용된다.

2.3. 참고 문서

QIRO - 신규 청구월 생성 및 초기값 설정 기능 명세서.md
QIRO - 청구월 관리 기능 명세서.md (가칭)

3. 청구월 주요 상태 정의

QIRO 서비스의 청구월은 다음과 같은 3가지 주요 상태를 가진다:

🔵 준비중 (Preparing / PREPARING): 새로운 청구월이 생성되어 관리비 부과를 위한 기초 데이터를 입력하고 설정하는 초기 단계. 데이터의 입력 및 수정이 주로 이루어진다.
🟠 진행중 (In Progress / IN_PROGRESS): 기초 데이터 입력이 완료된 후, 실제 관리비를 계산하고, 고지서를 발급하며, 수납을 처리하는 핵심적인 업무가 진행되는 단계. 이 상태의 청구월은 시스템 내에서 하나만 존재할 수 있다.
✅ 완료 (Completed / COMPLETED): 해당 청구월의 모든 관리비 관련 업무가 종결되고 데이터가 최종 확정되어 더 이상 수정할 수 없는 상태. 다음 달로 이월될 정보를 확정한다.

4. 주요 상태별 내부 진행 상태 상세

주요 청구월 상태 (Main Status)	내부 진행 상태 (Internal Progress)	설명	다음 단계로의 주요 트리거/조건 (또는 해당 내부 진행 상태 달성 조건)
1. 🔵 준비중 (Preparing)	1.1. `초기 설정 완료 (Initial Setup Complete)`	신규 청구월 생성, 마스터 관리비 항목 로드, 이전 달 데이터(설정값, 미확정 미납액 등) 선택적 연동 및 기본 설정이 완료된 시점.	사용자가 신규 청구월 생성 후 초기값 설정을 저장하고, 본격적인 데이터 입력 단계로 진입 준비 완료.
	1.2. `기초 데이터 입력중 (Data Entry in Progress)`	세대별 검침값, 건물 단위 공과금 총액, 기타 변동 비용 등 관리비 산정에 필요한 모든 기초 데이터를 시스템에 입력하고 검토하는 과정.	모든 필수 기초 데이터 입력 완료 및 내부 검증 통과.
	1.3. `산정 (Calculation)`	모든 기초 데이터 입력이 최종 확인되어, 관리비 산정을 즉시 실행할 수 있는 상태.	사용자가 ‘관리비 산정 실행’ 액션 개시 준비 완료. (이 내부 진행 상태 달성 후, ‘진행중’ 상태로 전환 가능)
2. 🟠 진행중 (In Progress)	2.1. `관리비 확정 (Maintenance Fee Confirmed)`	시스템이 모든 기초 데이터를 바탕으로 세대별 관리비를 자동으로 계산하고, 관리자가 그 결과를 내부적으로 확정한 상태. 이 시점부터 고지서 생성 가능.	관리비 자동 계산 실행 및 산정 결과 최종 확정.
	2.2. `고지 완료 (Invoicing Complete)`	확정된 산정 내역을 바탕으로 관리비 고지서가 생성되고 입주민/임차인에게 발송(또는 통지)까지 완료된 상태. 이 시점부터 수납 처리 시작.	고지서 생성 및 발송(또는 시스템 내 ‘발급 완료’ 처리) 완료.
	2.3. `수납 진행중 (Payment Collection in Progress)`	발송된 고지서에 따라 관리비 납부 내역을 기록하고 미납 현황을 추적 관리하는 기간. 이 상태는 납부 마감일 이후까지 지속될 수 있음.	월 결산 및 마감 작업 시작 결정 시점까지 지속.
3. ✅ 완료 (Completed)	3.1. `마감 처리중 (Closing in Progress)`	최종 수납 마감, 미납액 및 (필요시) 연체료 확정, 관련 회계 자료 정리 등 해당 청구월의 모든 업무를 종결하기 위한 마무리 작업 진행.	모든 마감 작업 완료 및 내부 검토 통과.
	3.2. `최종 마감 ( Closed)`	해당 청구월의 모든 관리비 업무가 공식적으로 종결되고, 모든 데이터는 읽기 전용으로 전환되며, 다음 달로 이월될 정보(미납액 등)가 최종 확정된 상태.	사용자가 ‘최종 마감’ 액션 실행 및 시스템 처리 완료.

5. 상태 변경 흐름도 (State Transition Flowchart)

graph TD
    A([신규 청구월 생성]) --> B[1 준비중];
    B -- 1.3 산정 준비 완료 후 산정 실행 및 확정 --> C[2 진행중];
    C -- 2.3 수납 진행 완료 후 월 마감 처리 --> D[3 완료];

    subgraph "준비중 내부"
        B1[1.1 초기 설정 완료] --> B2[1.2 기초 데이터 입력중]
        B2 --> B3[1.3 산정 준비 완료]
    end

    subgraph "진행중 내부"
        C1[2.1 산정 완료] --> C2[2.2 고지 완료]
        C2 --> C3[2.3 수납 진행중]
    end

    subgraph "완료 내부"
        D1[3.1 마감 처리중] --> D2[3.2 최종 마감]
    end

    C -- (제한적 롤백) <br/> 산정/고지 오류 수정 필요 시 <br/> (고지서 발송 전) --> B;
    D -- (매우 제한적 롤백) <br/> 마감 취소 필요 시 --> C;

    %% 스타일링 (선택)
    classDef preparing fill:#e6f3ff,stroke:#007bff,stroke-width:2px;
    classDef inprogress fill:#fff3e0,stroke:#ffa000,stroke-width:2px;
    classDef completed fill:#e8f5e9,stroke:#4caf50,stroke-width:2px;

    class B preparing;
    class C inprogress;
    class D completed;

그림 1: 청구월 주요 상태 및 내부 진행 흐름도

6. 주요 상태 변경 조건 및 영향 요약

6.1. `(없음)` → `준비중 (PREPARING)`

트리거: 신규 청구월 생성 기능 실행.
조건: 해당 연월의 청구월 미존재. (여러 ‘준비중’ 월 동시 존재 가능)
주요 작업: 초기 상태 준비중으로 설정, 마스터 항목 기반 구성, 이전 달 데이터 연동(상태별 차등).
영향: 해당 청구월에 대한 기초 데이터 입력 및 설정 작업 시작 가능.

6.2. `준비중 (PREPARING)` → `진행중 (IN_PROGRESS)`

트리거: 관리비 산정 실행 및 그 결과 확정 시 (또는 고지서 발급 시작 시).
조건:
1. 해당 ‘준비중’ 청구월의 모든 필수 기초 데이터 입력 완료 (1.3 산정 준비 완료 내부 진행 상태 달성).
2. 시스템 내 다른 ‘진행중’ 상태의 청구월이 없어야 함 (단일 ‘진행중’ 원칙).
주요 작업: 상태를 진행중으로 변경. 기초 데이터 수정 제한 시작.
영향: 관리비 계산, 고지서 발급, 수납 처리 등 핵심 업무 진행 단계로 진입.

6.3. `진행중 (IN_PROGRESS)` → `완료 (COMPLETED)`

트리거: 월 마감 처리 기능 실행.
조건:
1. 해당 ‘진행중’ 청구월의 수납 처리 및 모든 관련 업무(미납 확정 등) 종결.
2. 시간 순서상 해당 청구월 이전의 모든 청구월들이 이미 ‘완료’ 상태여야 함 (순차적 마감 원칙).
주요 작업: 상태를 완료로 변경. 모든 데이터 읽기 전용 전환. 다음 달 이월 데이터(최종 미납액 등) 확정.
영향: 해당 청구월의 모든 관리비 업무 공식 종결. 확정된 데이터는 다음 달 및 회계 처리의 기준이 됨.

6.4. 상태 롤백 (Rollback)

진행중 → 준비중: 고지서 공식 발송 전, 수납 처리 시작 전 등 매우 제한적인 조건 하에, 중대한 데이터 오류 수정 목적으로 상위 관리자 승인 하에 가능. 기존 산정 내역 등은 무효화.
완료 → 진행중 (“마감 취소”): 극히 예외적인 상황(회계적 오류 등)에서 최상위 관리자 승인 및 상세 사유 기록 하에 가능. 데이터 정합성에 큰 영향을 미치므로 최대한 지양하고 ‘정정 고지’ 등 대체 방안 우선 고려.

7. 문서 이력

버전	날짜	작성자	주요 변경 내용
1.0	2025년 05월 30일	QIRO 기획팀	청구월 주요 상태와 내부 진행 상태 관계 정의 초안 작성