frontend/apps/sn/docs/작업계획/SN-노후하수관로정비사업/003-fe-SN-노후하수관로정비사업-최종확정예산사업팝업-작업계획.md

SN-노후하수관로정비사업 최종확정예산사업 팝업 FE 작업계획

1. 목표와 기준

• 기준 문서: COMMON_DOCS_ROOT/작업계획/SN-노후하수관로정비사업/006-de-공통-최종확정예산사업팝업-신규기능작업계획.md
• 대상 부모 화면: /oper/obsltPplBiz
• 상태: 사용자 승인 구현 완료, 실 API·브라우저 검증 대기
• 부모 화면에서 필수 사업구분을 먼저 선택한 경우에만 공용 브라우저 popup을 연다.
• popup에서 ONSEMIRO 최종확정예산 33개 항목을 조회·다중선택하고 부모 업무로 일괄 등록한다.
• 등록 성공 메시지를 부모에 전달한 뒤 popup을 닫고 부모 목록을 기존 조회조건으로 다시 조회한다.

2. 공통계획 변경사항 동기화 확인

항목	이전 FE 계획	사용자 수정 공통계획 반영
팝업 방식	같은 화면의 UiModal	app/(popupLayout)/popup/[popupKey] 기반 window popup
popup 구현 위치	features/obsltPpl/ui/CfmtnBgtModal.tsx	features/cfmtnBgt/ui/CfmtnBgtPopupContent.tsx
사업구분 선택	popup 내부 SelectBox	부모 화면 조회조건에서 먼저 선택, 미선택 시 알림 후 popup 미오픈
등록 버튼	노후하수관로사업 등록	popup의 등록 버튼
검색 초기값	최신연도 일반 조회	전년도 및 부모 업무별 세부사업·내역사업·세부내역 자동조건
지역 데이터	신규 옵션 API 직접 사용	useOperStore.ts에 ONSEMIRO 주소 옵션을 추가하여 사용
완료 처리	Modal state close	postMessage로 부모 알림·재조회 요청 후 window.close()
기능 재사용	노후하수관로 전용 Modal	부모 업무정보를 query parameter로 받는 공용 popup content

3. 예정 수정 파일

구분	예정 파일	변경 계획
부모 연결	apps/sn/src/features/obsltPpl/ui/ObsltPplListPage.tsx	사업구분 필수검증, window popup open, 완료 메시지 수신, 기존 조건 재조회
popup 본체	apps/sn/src/features/cfmtnBgt/ui/CfmtnBgtPopupContent.tsx	검색, 33개 열, 다중선택, 등록, Excel 다운로드
API	apps/sn/src/features/cfmtnBgt/api/cfmtn-bgt-api.ts	코드·목록·선택등록 API
타입	apps/sn/src/features/cfmtnBgt/model/cfmtn-bgt-types.ts	33개 조회필드, 검색·등록·응답, 부모 context 계약
Excel	apps/sn/src/features/cfmtnBgt/lib/cfmtn-bgt-excel.ts	적용 조회조건 전체 결과 XLSX 생성
popup 정의	apps/sn/src/features/windowPopup/model/popupDefinitions.ts	cfmtnBgt key, 제목, 대형 popup 크기, 필수 query parameter 정의
popup 등록	apps/sn/src/features/windowPopup/registry.tsx	CfmtnBgtPopupContent registry 연결
완료 메시지	apps/sn/src/features/windowPopup/model/types.ts	최종확정예산 등록 완료 message type 추가
popup 메시지	기존 features/windowPopup/lib/popupMessage.ts 재사용	등록 결과 payload 전송 후 popup 닫기
운영 store	apps/sn/app/store/useOperStore.ts	기존 operation-service 주소 상태를 유지하고 ONSEMIRO 전용 주소 상태·fetch 함수 추가

4. 부모 화면 계약

• 최종확정예산사업 버튼은 기존 목록 액션 영역에 추가한다.
• 버튼 클릭 시 현재 조회조건의 사업구분을 검사한다.
• 선택되지 않았으면 사업구분을 먼저 선택해 주세요. 알림을 표시하고 popup을 열지 않는다.
• 선택된 사업구분과 부모 식별정보를 openWindowPopup("cfmtnBgt", params)로 전달한다.
• popup 완료 메시지는 다른 popup 메시지와 구분되는 고유 type으로 수신한다.
• 성공 시 popup 응답의 등록·중복제외 건수를 부모 알림에 표시하고, 기존 적용 조회조건을 유지한 첫 페이지를 재조회한다.
• popup이 단순 종료되거나 등록에 실패하면 부모 목록은 재조회하지 않는다.

5. popup query parameter와 재사용 계약

제안 parameter:

이름	필수	설명
parentType	Y	부모 업무 식별자, 노후하수관로는 obsltPplBiz
bizSe	Y	부모가 선택한 사업구분
parentMessageType	Y	성공 시 부모가 수신할 popup message type

• popup은 parentType과 bizSe로 초기 검색조건과 등록 API를 결정한다.
• 다른 화면이 재사용할 때는 popup 본체를 복사하지 않고 부모별 초기조건·등록 adapter만 추가한다.
• 필수 parameter가 없으면 조회하지 않고 누락 안내를 표시한다.

6. 검색 초기값

• 연도 기본값은 공통계획의 최신 명시인 전년도로 한다.
  • 예: 현재가 2026년이면 2025년
• 부모가 obsltPplBiz일 때:

부모 사업구분	세부사업 초기조건	내역사업 초기조건	세부내역 초기조건
정비사업	하수관로정비%	하수관로정비	노후하수관로정비%
정밀조사	하수관로정비%	노후하수관로정밀조사지원	전체/미지정

• % 조건은 화면 label에 %를 표시한다는 뜻이 아니라 BE code/options 조회에서 prefix 일치 항목을 선택하는 계약이다.
• popup을 닫았다 다시 열면 부모가 전달한 사업구분으로 초기조건을 다시 계산한다.
• 조회조건: 환경청, 시도, 시군구, 세부사업, 내역사업, 세부내역, 년도, 사업명
• 구분 조건은 만들지 않는다. 환경청은 선택조건이며, 환경청을 선택하지 않아도 시도를 독립적으로 선택할 수 있어야 한다.
• 버튼 순서: 조회, 초기화, 엑셀다운로드
• 초기화는 부모 업무에서 계산한 초기조건으로 되돌리고 결과와 선택을 지운다.
• 초기 년도는 현재년도 기준 전년도로 고정한다.

7. ONSEMIRO 주소 store 계약

• 기존 useOperStore의 govArea/city/sgg와 /operation-service/api/v1/addr/* 호출은 다른 화면이 사용하므로 변경하거나 대체하지 않는다.
• 같은 store에 다음과 같은 ONSEMIRO 전용 상태를 별도로 추가한다.
  • onsemiroGovArea, onsemiroCity, onsemiroSgg
  • fetchOnsemiroGovArea, fetchOnsemiroCity, fetchOnsemiroSgg
• 신규 API:
  • /api/v1/onsemiro/addr/city
  • /api/v1/onsemiro/addr/sgg
  • /api/v1/onsemiro/addr/govArea
• 현재 신규 Addr API 응답은 원본 camelCase 필드이므로 SelectBox 변환 시 다음을 사용한다.

구분	text	val
시도	sido	adstDstrCd
시군구	gugun	adstDstrCd
환경청/지자체	lclgvrnmntNm	lclgvrnmntCd 또는 조회계약에서 확정한 환경청 코드

• 시도 변경 시 adstDstrCd 앞자리 또는 BE가 제공하는 관계 기준으로 시군구 후보를 제한하고 기존 시군구 선택을 초기화한다.
• govArea 응답은 원본 테이블이 지자체 기준이므로 popup의 실제 환경청 선택 label/code가 맞는지 BE 조회결과로 최종 확인한다.

8. 목록·선택·등록 계약

• 첫 열에 전체선택/행선택 checkbox를 제공한다.
• 페이지 이동 후에도 SEQ_NO Set을 유지한다.
• 조회·초기화로 적용조건이 바뀌면 선택 Set을 지운다.
• 33개 열은 다단 헤더와 목록 내부 가로 스크롤을 사용한다.
• popup 내부에는 사업구분 SelectBox를 두지 않는다.
• 선택행이 없으면 등록 버튼을 비활성화한다.
• 확인 문구는 부모가 전달한 사업구분을 사용한다.
• 등록 요청은 SEQ_NO[]만이 아니라 부모에서 전달한 bizSe를 함께 보낸다.
• 성공 시 등록·중복제외 건수를 popup message payload로 전달하고 닫는다.
• 실패 시 popup과 선택상태를 유지한다.

9. Excel 계약

• FE에서 적용 조회조건 전체 결과를 1,000건 단위로 반복 조회해 생성한다.
• 파일명: 최종확정예산관리_{년도}.xlsx
• 시트명: 최종확정예산관리
• 열 순서: 원본 Excel A~AG 33개 열
• 날짜는 apps/sn/src/features/common/util.ts의 formatDate()를 사용해 yyyy-MM-dd로 표시한다.
• 금액/보조율은 숫자, 사업코드는 문자열로 출력한다.
• 버튼명은 엑셀다운로드이며 초기화 바로 오른쪽에 둔다.

10. 검증

• 부모 사업구분 미선택 시 popup 미오픈과 알림 확인
• popupDefinitions → registry → CfmtnBgtPopupContent 연결 확인
• 부모별 전년도·사업구분별 초기조건 확인
• ONSEMIRO 주소 store가 기존 operation-service 상태를 변경하지 않는지 확인
• 여러 페이지 다중선택과 조건 변경 시 선택 초기화 확인
• 성공 postMessage 수신, popup close, 부모 목록 조회조건 유지 재조회 확인
• popup 재오픈 시 부모 조건으로 초기화 확인
• 33개 열 가로 스크롤, 날짜·금액 포맷, Excel 전체결과 확인
• 변경 파일 ESLint·대상 TypeScript 및 사용자 승인 후 SN build·브라우저 검증

11. 영향·롤백·확정 계약

• 영향: features/obsltPpl, 신규 features/cfmtnBgt, 기존 features/windowPopup, app/store/useOperStore.ts
• route 파일은 공용 /popup/[popupKey]를 재사용하고 신규 route를 만들지 않는다.
• 타 앱과 공통 package는 변경하지 않는다.
• 롤백: 신규 cfmtnBgt feature 제거, popup definition/registry/message와 부모 연결·store 전용 상태만 원복한다.
• 부모 화면에서 선택한 사업구분을 별도 명칭 변환 없이 등록 API에 전달한다.
• 같은 원본은 다시 등록하지 않고 이미 등록된 사업임을 안내한다.
• 초기 년도는 현재년도의 전년도로 설정하며 최신 보유연도 fallback은 적용하지 않는다.
• 규모·금액 15개 필드는 조회·Excel 전용으로 유지한다.
• 운영 ONSEMIRO의 하수관로정비(312) 코드는 현 계획대로 우선 구현하고 운영 확인 결과에 따라 후속 보정한다.
• govArea 응답에서 환경청 label/code로 사용할 필드는 구현 전 실제 응답으로 확인한다.