251 lines
19 KiB
Markdown
251 lines
19 KiB
Markdown
# 재원협의·실무협의 프론트엔드 개발 가이드
|
|
|
|
> **대상 앱**: `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절](#9-현재-코드-vs-to-be-갭) 참고.
|
|
|
|
---
|
|
|
|
## 1. 문서 목적
|
|
|
|
재원협의 4대 주체(기초·광역·환경청·공단)의 **상태 전이·버튼·API**를 `apps/as`에 구현할 때 쓰는 프론트엔드 가이드이다.
|
|
|
|
v1.0은 공단 접수자의 **자료검증 → 초안생성 → 웹기안기**만 다뤘다. v2.0은 2026-09-03 완결 프로세스 기준으로 **신청부터 최종종결(**`TA`**)까지**, 실무협의·AI 3파이프라인·결재선·보완 루프를 포함한다.
|
|
|
|
상세 표·시퀀스·DTO는 본문에 넣지 않고 레퍼런스로 분리한다. 구현 중에는 본문의 규칙만 보고, 표가 필요하면 해당 파일을 연다.
|
|
|
|
---
|
|
|
|
## 2. 문서 맵
|
|
|
|
| 파일 | 내용 | 언제 보는가 |
|
|
| -------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------- |
|
|
| [development-guide.md](./development-guide.md) (본 문서) | 도메인, 핵심 규칙, 화면 흐름, 갭, 구현 순서 | 일상 구현 |
|
|
| [ref-process-status.md](./ref-process-status.md) | 4-Lane 시퀀스, Activity, `FNRSSTTS`, 보완 3루프, AI 타임아웃, 결재선 복사 | 상태 전이·폴링 UX |
|
|
| [ref-screen-buttons.md](./ref-screen-buttons.md) | 38행 화면·역할·버튼 매트릭스, 버튼 가시성 | `button-config.ts` 개편 |
|
|
| [ref-endpoint.md](./ref-endpoint.md) | 버튼→API 총괄, 단계별 입출력, FE 호출 금지 API, Gap Analysis | 엔티티·service 매핑 |
|
|
| [ref-frontend-entities.md](./ref-frontend-entities.md) | ENDPOINT, 슬라이스, Service 시그니처, 폴링, 웹기안기, DTO | 엔티티 레이어 구현 |
|
|
| [ref-webhwp-api.md](./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](./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](./ref-screen-buttons.md). API 상세는 [ref-endpoint.md](./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`.
|
|
|
|
---
|