frontend/apps/as/docs/pwrk-cnsltn/development-guide.md

재원협의·실무협의 프론트엔드 개발 가이드

대상 앱: frontend/apps/as
작성일: 2026-08-27
개정일: 2026-09-07
버전: 2.0
Process: PR-AS-003 (재원협의 관리 — 실무협의 및 AI 검증 통합)

SoT (2026-09-03 완결):

• 프로세스·상태·버튼: 03.재원협의_실무협의_프로세스_통합_v완결.md
• REST 설계: 05.재원협의_상태별_endpoint_설계.md
• 공통코드: FNRSSTTS (SV, ST, LE, FV, ER, SL, AC, TE, TP, RM, RB, RC, RA, AV, EV, RK, RR, EP, TA)

백엔드 서비스:

• as-service — /api/v1/fnrs-cnsltn-mng, /api/v1/pwrk-cnsltn-mng, /api/v1/pwrk-cnsltn-doc-crt-rslt, /api/v1/dcrag-to
• as-elapr-service — /api/v1/elapr-dmnd, /api/v1/elapr-prgrs-stts, /api/v1/elapr-apln

현재 프론트 상태: 재원협의(fnrs-cnsltn)·전자결재(elapr)·DC RAG TO(dcrag-to)는 존재한다. 실무협의(pwrk-cnsltn-*) 엔티티·화면은 미구현. 버튼 매트릭스·상태코드는 v2.1 잔존이며 v3.0(FNRSSTTS)과 불일치한다. 9절 참고.

---

1. 문서 목적

재원협의 4대 주체(기초·광역·환경청·공단)의 상태 전이·버튼·API를 apps/as에 구현할 때 쓰는 프론트엔드 가이드이다.

v1.0은 공단 접수자의 자료검증 → 초안생성 → 웹기안기만 다뤘다. v2.0은 2026-09-03 완결 프로세스 기준으로 신청부터 최종종결(TA)까지, 실무협의·AI 3파이프라인·결재선·보완 루프를 포함한다.

상세 표·시퀀스·DTO는 본문에 넣지 않고 레퍼런스로 분리한다. 구현 중에는 본문의 규칙만 보고, 표가 필요하면 해당 파일을 연다.

---

2. 문서 맵

파일	내용	언제 보는가
development-guide.md (본 문서)	도메인, 핵심 규칙, 화면 흐름, 갭, 구현 순서	일상 구현
ref-process-status.md	4-Lane 시퀀스, Activity, FNRSSTTS, 보완 3루프, AI 타임아웃, 결재선 복사	상태 전이·폴링 UX
ref-screen-buttons.md	38행 화면·역할·버튼 매트릭스, 버튼 가시성	button-config.ts 개편
ref-endpoint.md	버튼→API 총괄, 단계별 입출력, FE 호출 금지 API, Gap Analysis	엔티티·service 매핑
ref-frontend-entities.md	ENDPOINT, 슬라이스, Service 시그니처, 폴링, 웹기안기, DTO	엔티티 레이어 구현
ref-webhwp-api.md	웹한글기안기 v3 HwpCtrl Properties/Methods, Open/SaveAs	기안기 위젯 연동

---

3. 도메인 개요

실무협의서(PWRK)는 재원협의서(FNRS)의 하위 문서이다. 재원협의 1건당 실무협의서는 1건만 생성된다.

문서	번호 예시	필드
재원협의	F-20260824-0001	fnrsCnsltnDocNo / upDocNo
실무협의	P-20260827-0001	pwrkCnsltnDocNo

진행상태는 재원협의 마스터 tb_as_fnrs_cnsltn_mng.prgrs_stts_com_cd (FNRSSTTS)가 SSOT이다. 실무협의 문서의 prgrsSttsComCd는 연계 표시용이며, 화면 버튼은 재원협의 상태로 분기한다.

3-1. 4대 주체

역할	코드	화면 소유	핵심 구간
기초자치단체	ROLE_USER05	작성/수정/상세	신청, 3종 보완, 조치결과, 최종확인
광역자치단체	ROLE_USER04	상세	경유 제출, 결과 전달
유역·지방환경청	ROLE_USER03	상세	의뢰/자체종결, 1·2차 회신
한국환경공단	ROLE_USER01	상세 + 결재선	파일검증, 검토자지정, 1·2차 기술검토

3-2. 핵심 식별자

필드	의미	비고
fnrsCnsltnDocNo	재원협의문서번호	상태 전이·목록 PK
pwrkCnsltnDocNo	실무협의문서번호	P-YYYYMMDD-NNNN. 검토자지정(ER→AC) 시 발급
upDocNo	상위문서번호	재원협의 번호. upDocSeComCd = "FNRS"
crtDmndUuid	생성요청 UUID	초안 폴링·웹기안기·다운로드 키
verSn	버전일련번호	복합 PK (crtDmndUuid, verSn). 저장 시 서버가 +1
orgnlOtptDocCn	HWP 바이너리	목록/상세 응답은 항상 null. 다운로드·webhwp/open만 사용
elaprCycl	결재 차수	1차 TE, 2차 RK. 금액검증 완료 후 1차 결재선 복사

3-3. IIPBS 약어

한글	약어	필드 예
재원	FNRS	fnrsCnsltnDocNo
실무	PWRK	pwrkCnsltnDocNo
협의	CNSLTN	fnrs-cnsltn-mng
생성	CRT	crtDmndUuid
요청	DMND	crtDmndUuid, elapr-dmnd
검증	VRFC	vrfcSttsComCd
보완	SPLMNT	splmntDmndList
결재	ELAPR / ATRZ	elaprCycl, atrzSeComCd

---

4. 상태코드 한눈에 보기

상위코드 FNRSSTTS. v1.0의 PWRKSTTS(DV, AR, TR 등)는 폐기한다.

정방향:

SV → ST → LE → FV → ER → AC → TE → TP → RM → RB → RC → RA → AV → EV → RK → RR → EP → TA

자체종결: LE → EP → TA
보완: ER|TE|RK → SL 후 직전 상태로 복귀.

코드	명칭	FE에서 할 일
SV	저장	기초 작성화면 저장/신청/삭제
ST	신청완료	광역 환경청제출
LE	환경청 검토	자체종결(EP) 또는 기술검토 의뢰(FV)
FV	파일검증	AI 진행 표시. 30분 후 ER Fallback
ER	기술검토 의뢰	공단 접수자: 파일보완 / 수동파일검증 / 검토자지정
SL	보완요청	기초 수정화면. 복귀 대상은 이력의 직전 상태
AC	초안생성	AI 진행 표시. 30분 후 TE Fallback
TE	기술검토	웹기안기·검토완료·보완. 결재선 1차
TP	기술검토 회신	환경청 → 광역 RM
RM	재원협의결과회신	광역 → 기초 RB
RB	지자체회신	기초 실무협의서 관리 / 조치완료
RC	조치결과서 제출	광역 → 환경청 RA
RA	조치결과서제출(환경청)	환경청 2차 의뢰 AV
AV	금액검증	AI 진행 표시. 30분 후 EV Fallback
EV	조치결과검토의뢰	공단 접수자: 2차 결재선 검토자지정 → RK
RK	조치결과서검토	웹기안기·금액검증 재실행·보완. 결재선 2차
RR	조치결과서검토 회신	환경청 → 광역 EP
EP	검토결과 회신	광역 → 기초 TA
TA	검토결과 회신(종료)	기초 조회만. 고시(TB) 아님

코드 의미·구버전 대조·보완 루프·AI Fallback은 ref-process-status.md.

---

5. 프론트가 지켜야 할 핵심 규칙

1. 상태 SSOT는 FNRSSTTS. 버튼 가시성은 (dtlInstCd, prgrsSttsComCd, atrzSeComCd)로만 계산한다. 공단은 결재선 구분(ATRZ01 접수자, ATRZ02 검토자, ATRZ03 승인자, ATRZ99 최종승인자)을 추가로 본다.
2. AI 콜백 API는 화면에서 호출하지 않는다. POST /dcrag/documents/verify-result, POST /dcrag/draft/complete, POST /dcrag/cost/verify-result는 서버 전용이다.
3. 초안생성 1차 트리거는 검토자지정이다. POST /elapr-dmnd (ER → AC). 예전처럼 POST /pwrk-cnsltn-mng로 초안을 시작하지 않는다.
4. 기술검토 의뢰는 LE → FV 전용 API POST /fnrs-cnsltn-mng/{docNo}/request-examine. 현재 코드의 updatePrgrsStts(ER) 직행은 폐기.
5. 수동 AI 재실행은 상태를 바꾸지 않는다.

• ER 파일검증 → POST /dcrag-to/documents/transfer
• TE 초안생성 → POST /dcrag-to/documents/draft/generate (타임아웃·실패 시에만)
• RK 금액검증 → POST /dcrag-to/documents/cost/verify

6. 진행상태만 바꾸는 버튼은 POST /fnrs-cnsltn-mng/doc/updatePrgrsStts를 재사용한다. (ST→LE, RM→RB, RC→RA, RR→EP, EP→TA)
7. 보완요청/보완완료는 공통 API reqsupplement / submitsupplement. 복귀 상태(ER/TE/RK)는 서버가 이력에서 결정한다. 프론트는 직전 상태를 추측해 보내지 않는다.
8. 결재 승인/회신은 PUT /elapr-prgrs-stts/{id}/process 하나. 1차 최종승인자 → TP, 2차 → RR은 서버가 Feign으로 처리한다.
9. 2차 결재선은 EV에서 수동 검토자지정. POST /elapr-dmnd (elaprCycl: 2, docPrgrsSttsComCd: RK). 1차 결재선 자동 copy-line은 사용하지 않는다.
10. 웹기안기는 webhwp/open 응답을 axios blob으로 조회한 뒤 File로 감싸 HwpCtrl.Open에 전달한다. blob: Object URL과 orgnlOtptDocCn은 쓰지 않는다.

---

6. 화면 데이터 흐름

재원협의 목록 → 상세/작성이 본체다. 실무협의 목록은 공단 검토 보조 화면이다.

BEGIN
  CALL fnrsCnsltnMngService.findPage(...)
  ON 행 CLICK → /fnrs-cnsltn/{fnrsCnsltnDocNo}

  CALL findById(fnrsCnsltnDocNo)
  COMPUTE buttons = getButtonConfigs(dtlInstCd, prgrsSttsComCd, atrzSeComCdList)

  // ----- 기초 ROLE_USER05 -----
  ON [저장] (빈값/SV)     → saveApply(prgrsSttsComCd: SV)
  ON [신청완료] (SV)      → saveApply(prgrsSttsComCd: ST)
  ON [삭제] (SV)          → remove
  ON [파일보완완료] (SL←ER) → submitsupplement
  ON [보완완료] (SL←TE|RK)  → submitsupplement
  ON [실무협의서 관리] (RB) → GET webhwp/open (blob) → HwpCtrl.Open(File)
  ON [조치완료] (RB)        → submit-actn-result { isSubmit: true }
  ON [결과회신] (TA)      → API 없음 (조회)

  // ----- 광역 ROLE_USER04 -----
  ON [환경청제출] (ST)    → updatePrgrsStts(LE)
  ON [지자체회신] (RM)    → updatePrgrsStts(RB)
  ON [조치결과서제출] (RC) → updatePrgrsStts(RA)
  ON [결과회신] (EP)      → updatePrgrsStts(TA)

  // ----- 환경청 ROLE_USER03 -----
  ON [결과회신] (LE 자체종결) → tech-review → EP
  ON [기술검토 의뢰] (LE)     → request-examine → FV  → START POLL FV
  ON [재원협의 결과 회신] (TP) → tech-review → RM
  ON [실무협의서 관리] (RA)   → GET webhwp/open (blob) → HwpCtrl.Open(File) (저장 불가)
  ON [조치결과 검토의뢰] (RA) → request-actn-review → AV → START POLL AV
  ON [결과회신] (RR)           → updatePrgrsStts(EP)

  // ----- 공단 ROLE_USER01 -----
  ON [파일보완] (ER, ATRZ01)     → GET file-vrfc-results → 팝업 → reqsupplement
  ON [파일검증] (ER, ATRZ01)     → dcrag-to transfer (상태 유지)
  ON [검토자지정] (ER, ATRZ01)   → POST elapr-dmnd (docPrgrsSttsComCd: AC) → START POLL AC
  ON [검토자지정] (EV, ATRZ01)   → POST elapr-dmnd (elaprCycl: 2, docPrgrsSttsComCd: RK)
  ON [실무협의서관리] (TE|RK)    → GET webhwp/open (blob) → HwpCtrl.Open(File)
  ON [실무협의서생성] (TE, 실패/타임아웃) → dcrag-to draft/generate
  ON [검토결과조회] (TE)         → pwrk-cnsltn-mng findById | findByUpDocNo
  ON [저장] (TE|RK)              → pwrk-cnsltn-mng save-apply
  ON [검토완료]                  → elapr-prgrs-stts process (상신)
  ON [보완요청] (TE|RK)          → 보완 팝업 → reqsupplement
  ON [금액검증] (RK)             → dcrag-to cost/verify
  ON [결재(승인)]                → process (중간)
  ON [결재(회신)]                → process (최종 → TP 또는 RR)

  // ----- AI 진행 중 (FV / AC / AV) -----
  POLL 상태 또는 draft status. 30분 안내. 종료 후 상세 invalidate
END

38행 버튼 표는 ref-screen-buttons.md. API 상세는 ref-endpoint.md.

---

7. 버튼 → API 축약

프론트가 치는 것만. 콜백·스케줄러는 제외.

주체	버튼	From → To	Method & URI
기초	저장 / 신청완료	→SV / SV→ST	POST /fnrs-cnsltn-mng/save-apply
기초	삭제	SV	DELETE /fnrs-cnsltn-mng/{docNo}
광역	환경청제출	ST→LE	POST /fnrs-cnsltn-mng/doc/updatePrgrsStts
환경청	결과회신(자체종결)	LE→EP	POST /fnrs-cnsltn-mng/{docNo}/tech-review
환경청	기술검토 의뢰	LE→FV	신규 POST /fnrs-cnsltn-mng/{docNo}/request-examine
공단 접수	파일보완 팝업	ER	GET /fnrs-cnsltn-mng/{docNo}/file-vrfc-results
공단 접수	파일보완요청	ER→SL	POST /fnrs-cnsltn-mng/{docNo}/reqsupplement
공단 접수	파일검증 재실행	ER 유지	POST /dcrag-to/documents/transfer
공단 접수	검토자지정	ER→AC	POST /elapr-dmnd (elaprCycl: 1)
공단 접수	검토자지정	EV→RK	POST /elapr-dmnd (elaprCycl: 2)
공단 검토	실무협의서관리	TE/RK	GET .../pwrk-cnsltn-doc-crt-rslt/{uuid}/webhwp/open
공단 검토	실무협의서생성	TE 유지	POST /dcrag-to/documents/draft/generate
공단 검토	저장	TE/RK	POST /pwrk-cnsltn-mng/save-apply
공단	검토완료 / 결재(승인·회신)	TE 유지 / TE→TP / RK→RR	PUT /elapr-prgrs-stts/{id}/process
공단 검토	보완요청	TE→SL / RK→SL	POST /fnrs-cnsltn-mng/{docNo}/reqsupplement
기초	파일보완완료 / 보완완료	SL→ER / TE / RK	POST /fnrs-cnsltn-mng/{docNo}/submitsupplement
환경청	재원협의 결과 회신	TP→RM	POST /fnrs-cnsltn-mng/{docNo}/tech-review
광역	지자체회신	RM→RB	updatePrgrsStts
기초	실무협의서 관리	RB 유지	GET .../pwrk-cnsltn-doc-crt-rslt/{uuid}/webhwp/open
기초	조치완료	RB→RA	신규 POST /pwrk-cnsltn-mng/{pwrkDocNo}/submit-actn-result (isSubmit: true)
광역	조치결과서제출	RC→RA	updatePrgrsStts
환경청	실무협의서 관리	RA 유지 (조회)	GET .../pwrk-cnsltn-doc-crt-rslt/{uuid}/webhwp/open
환경청	조치결과 검토의뢰	RA→AV	신규 POST /fnrs-cnsltn-mng/{docNo}/request-actn-review
공단 검토	금액검증 재실행	RK 유지	POST /dcrag-to/documents/cost/verify
환경청	결과회신	RR→EP	updatePrgrsStts
광역	결과회신	EP→TA	updatePrgrsStts
웹기안기	저장	버전 +1	POST /pwrk-cnsltn-doc-crt-rslt multipart
공통	다운로드	—	GET /pwrk-cnsltn-doc-crt-rslt/{uuid}/download

신규 4개: request-examine, submit-actn-result, request-actn-review, EV 2차 elapr-dmnd.

---