45 KiB
45 KiB
AS(디지털 행정지원) 모듈 아키텍처, UI 구조 및 화면 데이터 흐름 분석 보고서
1. 개요 (Overview)
본 문서는 디지털 행정지원 시스템(Administrative Support System, 이하 AS 모듈) 프론트엔드 애플리케이션(apps/as)의 기술 스펙, UI 구조, 컴포넌트 아키텍처 및 화면 데이터 흐름을 상세히 분석하여 정리한 기술 명세서입니다.
AS 모듈은 하수도 기본계획, 재원협의, 설치인가, 설계자문 등 공공 행정 업무의 신청·접수·검토·보완·결재 절차를 전자화하고, 대시보드 및 각종 기준 정보(코드, 체크리스트, 필수 첨부파일 등)를 체계적으로 관리하는 핵심 업무 포털입니다.
2. 프로그램 기술 스펙 (Technology Stack & Specifications)
2.1 코어 런타임 및 프레임워크
| 구분 | 기술 / 라이브러리 | 버전 | 주요 역할 및 용도 |
|---|---|---|---|
| Framework | Next.js | 15.5.18 |
App Router 기반 React 메타 프레임워크, SSR/CSR 하이브리드 지원, Standalone 빌드 배포 |
| Core UI | React / React DOM | 19.x (next 내장) |
컴포넌트 기반 UI 렌더링 엔진 |
| Language | TypeScript | ^5.7.2 |
정적 타입 검사, DTO/인터페이스 정의 및 무결성 보장 |
| Architecture | Feature-Sliced Design (FSD) | v2.1 |
계층형 프론트엔드 아키텍처(App, Pages, Widgets, Features, Entities, Shared) |
| Architecture Lint | Steiger | ^0.5.11 |
FSD 아키텍처 규칙(레이어 간 Import 의존성 방향, Public API 준수 여부) 정적 검사 |
2.2 상태 관리 및 데이터 통신
| 구분 | 기술 / 라이브러리 | 버전 | 주요 역할 및 용도 |
|---|---|---|---|
| Server State | @tanstack/react-query | ^5.75.5 |
서버 데이터 페칭, 캐싱, 동기화, 자동 무효화(invalidateQueries), 쿼리 키 기반 상태 관리 |
| DevTools | @tanstack/react-query-devtools | ^5.75.5 |
React Query 상태 디버깅 및 캐시 모니터링 |
| Client State | Zustand | (내장 / 공유) | 사용자 프로필(user-store), 메뉴/권한(menu-store), 공통 Alert(alert-store) 전역 클라이언트 상태 |
| HTTP Client | Axios | ^1.8.1 |
REST API 클라이언트, 요청 헤더 주입(토큰, 사용자ID, 기기ID), 401 응답 인터셉터 |
| File Transfer | tus-js-client | ^4.3.1 |
TUS 프로토콜 기반 대용량 첨부파일 청크 업로드 및 이어올리기 지원 |
| Cookie Mgt | js-cookie | ^3.0.5 |
브라우저 쿠키(인증 토큰, 사용자 ID, 사이트 ID, 메뉴 코드 등) 제어 |
2.3 폼 관리 및 유효성 검증
| 구분 | 기술 / 라이브러리 | 버전 | 주요 역할 및 용도 |
|---|---|---|---|
| Form Engine | react-hook-form | ^7.54.2 |
비제어 컴포넌트 기반 고성능 폼 상태 관리 (FormProvider, useFormContext) |
| Schema Validation | zod | ^3.24.2 |
선언형 스키마 정의 및 데이터 타입 런타임 유효성 검증 |
| Form Resolver | @hookform/resolvers | ^4.1.3 |
React Hook Form과 Zod 스키마의 바인딩 어댑터 |
| Form DevTools | @hookform/devtools | ^4.4.0 |
폼 상태 및 에러 추적 디버깅 도구 |
2.4 데이터 테이블 및 UI 인터랙션
| 구분 | 기술 / 라이브러리 | 버전 | 주요 역할 및 용도 |
|---|---|---|---|
| Data Grid | @tanstack/react-table | ^8.21.2 |
헤드리스 데이터 테이블, 서버 사이드 페이징/정렬, 컬럼 가상화 기반 |
| Drag & Drop | @dnd-kit/core, @dnd-kit/sortable | ^6.3.1 / ^10.0.0 |
전자결재 결재선 지정 시 결재자 순서 변경 드래그 앤 드롭 |
| UI Primitive | @radix-ui/react-tooltip | ^1.2.8 |
웹 접근성을 준수하는 툴팁 컴포넌트 |
| Icons | lucide-react | ^0.474.0 |
현대적이고 통일된 SVG 벡터 아이콘 세트 |
| Styling | Tailwind CSS + CVA | ^3.4.14 / ^0.7.1 |
유틸리티 퍼스트 CSS 프레임워크 및 조건부 클래스 조합(class-variance-authority) |
| Date Library | dayjs | ^1.11.13 |
날짜/시간 포맷팅, 상대 시간 계산 |
| Mock / Utilities | @faker-js/faker, @frontend-opensource/use-react-hooks | ^9.9.0 / ^1.1.4 |
테스트 목업 데이터 생성 및 전역 Confirm 대화상자 Provider |
2.5 모노레포 내부 패키지 연동 (packages/common)
AS 모듈은 사내 공통 패키지 저장소와 긴밀하게 연계되어 있습니다:
@common/auth: 통합 인증 규격(AuthService,AuthConfig), 토큰 수명 주기 계산(getRemainingMs), 디바이스 식별자 관리(getOrCreateDeviceId).@common/network: 공통 Axios 싱글톤 클라이언트(Client.getInstance()), 공통 인터셉터(errorInterceptor), 401 발생 시 로그인 리다이렉트 처리.@common/components: 통합 GNB/LNB 기본 레이아웃(BaseLayout), 공통 버튼, 인풋, 실렉트, 다이얼로그, 뱃지 등 UI 디자인 시스템.@common/assets: 전사 공통 로고, 이미지 에셋.
2.6 환경 변수 및 설정 (.env.local)
| 환경변수 키 | 값(로컬 기준) | 설명 |
|---|---|---|
NEXT_PUBLIC_PORT |
3000 |
애플리케이션 기본 포트 |
NEXT_PUBLIC_PROXY_HOST |
http://localhost:3003 |
프론트엔드 프록시 엔드포인트 호스트 |
NEXT_PUBLIC_SITE_ID |
AS |
행정지원 시스템 고유 사이트 식별자 |
SERVER_API_URL |
http://localhost:8000 |
백엔드 API 게이트웨이 원본 주소 (미들웨어 프록시 대상) |
NEXT_PUBLIC_DC_SERVICE_API_URL |
https://apigateway.apps.rsonesoft.com |
데이터 연계/DC 서비스 엔드포인트 |
NEXT_PUBLIC_WEBHYP_CTRL_URL |
http://hwp.onasys.co.kr/webhwpctrl |
웹한글 기안기(WebHWP) 컨트롤 서버 주소 |
NEXT_PUBLIC_AUTH_LOGIN_REDIRECT_URL |
/auth/login |
인증 만료 시 리다이렉트될 로그인 경로 |
NEXT_PUBLIC_TINY_API_KEY |
(Secret Key) | 서식 작성용 TinyMCE 웹 에디터 라이선스 키 |
3. 아키텍처 및 UI 구조 (Architecture & UI Structure)
3.1 Next.js App Router와 FSD(v2.1)의 1:1 매핑 구조
AS 모듈은 Feature-Sliced Design v2.1과 Next.js App Router를 결합하여 설계되었습니다:
app/디렉토리: 라우팅 진입점, URL 파라미터 매핑, 루트/그룹 레이아웃, 미들웨어 프록시 및 API Route Handler만 담당합니다. 비즈니스 로직이나 UI 마크업을 직접 포함하지 않고src/pages의 컴포넌트를 Re-export합니다.src/디렉토리: FSD 6계층 구조에 따라 엄격히 분리된 실제 애플리케이션 구현체입니다.
apps/as/
├── app/ # [App Router] 라우팅 엔드포인트
│ ├── (auth)/ # 인증 전용 Route Group (독립 레이아웃)
│ │ ├── auth/login/page.tsx # -> re-export '@/pages/auth'
│ │ └── layout.tsx # 전역 Provider 없는 가벼운 HTML 구조
│ ├── (main)/ # 메인 업무 Route Group
│ │ ├── (with-base-layout)/ # 공통 GNB/사이드바 포함 레이아웃 그룹
│ │ │ ├── dashboard/page.tsx # 대시보드
│ │ │ ├── sewer-bsc-plan/ # 하수도기본계획 (목록/등록/상세/수정)
│ │ │ ├── fnrs-cnsltn/ # 재원협의 (목록/등록/상세/수정)
│ │ │ ├── instl-sncn/ # 설치인가 (목록/등록/상세/수정)
│ │ │ ├── design-cnstn/ # 설계자문 (목록/등록/상세/수정)
│ │ │ ├── my-pbadms-sprt/ # 나의 행정지원
│ │ │ ├── approval-line-management/ # 결재선 관리
│ │ │ ├── checklist-management/ # 체크리스트 관리
│ │ │ ├── code-management/ # 공통코드 관리
│ │ │ ├── esntl-atch-file-mng/ # 필수 첨부파일 관리
│ │ │ ├── rvw-mnpw-mng/ # 검토인력 관리
│ │ │ ├── nti-hstry/ # 알림톡 이력
│ │ │ ├── ntitlk-sndng/ # 알림톡 발송
│ │ │ └── layout.tsx # BaseLayoutWrapper 적용
│ │ └── layout.tsx # Providers(Query, Zustand, Auth, Menu) 적용
│ ├── api/ # Next.js Route Handlers
│ │ ├── auth/logout/route.ts # HttpOnly 쿠키 삭제 로그아웃
│ │ └── proxy/[...url]/route.ts # 로그인 & Refresh 토큰 교환 BFF 프록시
│ └── middleware.ts # 백엔드 API 및 TUS 업로드 리라이트 프록시
│
└── src/ # [FSD 아키텍처 코어]
├── app/ # 1. App Layer (전역 설정, Provider, Layout)
│ ├── layouts/base-layout.tsx # BaseLayoutWrapper (공통 UI Frame)
│ ├── providers/index.tsx # QueryClient, Store, Auth, Menu, Alert 통합
│ └── styles/globals.css # 글로벌 스타일시트
├── pages/ # 2. Pages Layer (화면 단위 조립 슬라이스)
│ ├── dashboard/ # 대시보드 화면
│ ├── sewer-bsc-plan/ # 하수도기본계획 화면군
│ ├── fnrs-cnsltn/ # 재원협의 화면군
│ ├── instl-sncn/ # 설치인가 화면군
│ ├── design-cnstn/ # 설계자문 화면군
│ ├── my-pbadms-sprt/ # 나의 행정지원
│ ├── approval-line-management/ # 결재선 관리
│ ├── checklist-management/ # 체크리스트 관리
│ ├── code-management/ # 코드 관리
│ ├── esntl-atch-file-mng/ # 필수 첨부파일 관리
│ ├── rvw-mnpw-mng/ # 검토인력 관리
│ ├── nti-hstry/ # 알림톡 이력
│ └── ntitlk-sndng/ # 알림톡 발송
├── widgets/ # 3. Widgets Layer (독립 복합 UI 블록)
│ ├── pbadms-sprt/ # 행정지원 공통 폼/뷰 섹션 위젯
│ ├── hangulgiangi/ # 웹한글 기안기 연동 위젯
│ ├── ognz-user-tree/ # 조직도/사용자 선택 트리 위젯
│ ├── bns-picker/ # 업무/사업 선택기
│ └── cnfm/ # 승인/확인 대화상자
├── features/ # 4. Features Layer (사용자 인터랙션 기능)
├── entities/ # 5. Entities Layer (비즈니스 도메인 모델/API/상태)
│ ├── sewer-bsc-plan/ # 하수도기본계획 엔티티
│ ├── fnrs-cnsltn/ # 재원협의 엔티티
│ ├── instl-sncn/ # 설치인가 엔티티
│ ├── design-cnstn/ # 설계자문 엔티티
│ ├── elapr/ # 전자결재 엔티티
│ ├── auth/ # 인증 및 토큰 관리 엔티티
│ ├── menu/ # 메뉴 및 권한 엔티티
│ ├── cklst/ # 체크리스트 엔티티
│ ├── esntl/ # 필수 첨부파일 엔티티
│ ├── tus/ # TUS 업로드 엔티티
│ └── ... # 기타 31개 도메인 엔티티
└── shared/ # 6. Shared Layer (공용 기반 인프라)
├── api/client.ts # Axios 기반 API 클라이언트
├── config/ # 엔드포인트 및 환경설정
├── lib/ # 훅, 테이블/쿼리 유틸리티
├── model/ # 전역 타입 및 공통 모델
├── providers/store-provider.tsx # Zustand Context Provider
├── store/ # Zustand Stores (User, Menu, Alert)
└── ui/ # 다이얼로그, 필드, 아코디언 등 UI 컴포넌트
3.2 레이아웃 계층 구조
graph TD
A["브라우저 요청"] --> B{"경로 구분"}
B -->|"/auth/login"| C["app/(auth)/layout.tsx"]
C --> C1["순수 HTML + Body (globals.css만 로드)"]
C1 --> C2["LoginPage (로그인 폼)"]
B -->|"업무 화면들"| D["app/(main)/layout.tsx"]
D --> D1["RootLayout (HTML data-theme 설정)"]
D1 --> D2["Providers (QueryClient, Store, Confirm)"]
D2 --> D3["AuthWrapper (세션 검증 & Silent Refresh)"]
D3 --> D4["MenuWrapper (URL 매칭 & 조회 권한 체크)"]
D4 --> E["app/(main)/(with-base-layout)/layout.tsx"]
E --> E1["BaseLayoutWrapper"]
E1 --> E2["@common/components BaseLayout (GNB, LNB, Footer)"]
E2 --> E3["PageLayout (공통 패딩 및 레이아웃 컨테이너)"]
E3 --> E4["각 도메인 Page 컴포넌트"]
- 인증 전용 레이아웃 (
(auth)):- GNB나 복잡한 프로바이더 없이 최소한의 스타일만 로드하여 초기 구동 속도를 확보하고, 비로그인 상태의 화면을 렌더링합니다.
- 메인 루트 레이아웃 (
(main)):- 쿠키
site-theme-key를 서버에서 읽어html data-theme을 설정합니다. - 전역 프로바이더(
Providers)를 주입합니다. AuthWrapper: 로그인 여부 확인, 사용자 정보(userInfo) 초기화, 주기적 백그라운드 Silent Refresh 타이머 가동.MenuWrapper: 현재 접속 URL에 해당하는 메뉴 코드 및 권한(inqAuthrtYn) 검사.
- 쿠키
- 공통 프레임 레이아웃 (
(with-base-layout)):- 사내 공통 패키지의
BaseLayout을 래핑하여 표준 헤더, 사이드바, 푸터를 제공합니다. - 메뉴 클릭 시 메뉴 상태 저장(
setCurrentMenuInfo) 및 라우팅을 처리합니다.
- 사내 공통 패키지의
4. 전체 화면 라우트 맵 및 도메인 화면 분석
| 라우트 경로 | 매핑된 Page 컴포넌트 | 주요 역할 및 기능 | 핵심 연계 엔티티 / 위젯 |
|---|---|---|---|
/auth/login |
LoginPage |
시스템 로그인 화면 (ID/PW 인증, 디바이스 ID 전송) | entities/auth, /api/proxy |
/dashboard |
DashboardPage |
메인 포털 대시보드 (전국 유역별 진행 현황 지도, 상태별 건수 카드, 알림/통보 목록, 공지사항) | entities/dashboard, NationalAsMap |
/sewer-bsc-plan |
SewerBscPlanListPage |
하수도 기본계획 목록 조회 및 신규 신청 다이얼로그 호출 | entities/sewer-bsc-plan, useDataTable |
/sewer-bsc-plan/regist |
SewerBscPlanRegistPage |
하수도 기본계획 신규 신청 등록 폼 | widgets/pbadms-sprt, useTus, Zod |
/sewer-bsc-plan/[id] |
SewerBscPlanViewPage |
하수도 기본계획 상세 조회, 검토 이력, 보완요구 처리 | SewerBscPlanDetailGate, HangulGiangi |
/sewer-bsc-plan/[id]/edit |
SewerBscPlanEditPage |
하수도 기본계획 수정 폼 (기존 데이터 프리필) | widgets/pbadms-sprt, useTus |
/fnrs-cnsltn |
FnrsListPage |
재원협의 목록 조회 및 신규 신청 | entities/fnrs-cnsltn, useDataTable |
/fnrs-cnsltn/regist |
FnrsRegistPage |
재원협의 신규 등록 폼 (사업비/재원분담 매트릭스) | widgets/pbadms-sprt, FnrsSharFormSection |
/fnrs-cnsltn/[id] |
FnrsViewPage |
재원협의 상세 조회 및 결재/검토 | FnrsDetailGate, widgets/pbadms-sprt |
/fnrs-cnsltn/[id]/edit |
FnrsEditPage |
재원협의 수정 폼 | widgets/pbadms-sprt, Zod |
/instl-sncn |
InstlListPage |
설치인가 목록 조회 및 신청 | entities/instl-sncn, useDataTable |
/instl-sncn/regist |
InstlRegistPage |
설치인가 등록 폼 (사업비/시설규모/체크리스트) | widgets/pbadms-sprt, Zod |
/instl-sncn/[id] |
InstlViewPage |
설치인가 상세 조회 및 보완 처리 | InstlDetailGate, widgets/pbadms-sprt |
/instl-sncn/[id]/edit |
InstlEditPage |
설치인가 수정 폼 | widgets/pbadms-sprt, Zod |
/design-cnstn |
DesignListPage |
설계자문 목록 조회 | entities/design-cnstn, useDataTable |
/design-cnstn/regist |
DesignRegistPage |
설계자문 등록 폼 | widgets/pbadms-sprt, Zod |
/design-cnstn/[id] |
DesignViewPage |
설계자문 상세 및 자문의견 조회 | DesignDetailGate, widgets/pbadms-sprt |
/design-cnstn/[id]/edit |
DesignEditPage |
설계자문 수정 폼 | widgets/pbadms-sprt, Zod |
/my-pbadms-sprt |
MyPbadmsSprtListPage |
나의 행정지원 (로그인 사용자가 제출/담당한 전체 문서 통합 조회) | entities/sewer-bsc-plan, useDataTable |
/approval-line-management |
ApprovalLineManagementPage |
전자결재 템플릿 관리 및 결재선 드래그 앤 드롭 설정 | entities/elapr, @dnd-kit/core |
/checklist-management |
ChecklistManagementPage |
업무별 체크리스트 템플릿, 점검 항목 및 검토항목 관리 | entities/cklst, Tab View |
/code-management |
CodeManagementPage |
기준 코드 관리 (회계구분, 공종구분, 재원분담구분 코드 트리) | entities/code, entities/acntg, entities/cnstp |
/esntl-atch-file-mng |
EsntlAtchFileMngPage |
업무별 필수 첨부파일 마스터 관리 | entities/esntl, Dialog Form |
/rvw-mnpw-mng |
RvwMnpwMngPage |
검토 인력 배정 및 관리 | entities/rvw-mnpw |
/nti-hstry |
NtiHstryPage |
알림톡 및 시스템 통보 발송 이력 조회 | entities/noti, entities/ntftalk |
/ntitlk-sndng |
NtitlkSndngPage |
알림톡 즉시/예약 발송 화면 | entities/ntftalk, 템플릿 바인딩 |
5. 공통 인프라 및 서브시스템 구조
5.1 인증 및 세션 수명 주기 (BFF + 쿠키 하이브리드 패턴)
AS 시스템은 토큰 탈취 방지와 유연한 백엔드 통신을 위해 BFF(Backend For Frontend)와 브라우저 쿠키를 결합한 하이브리드 세션 관리를 채택했습니다:
sequenceDiagram
autonumber
actor User as 사용자
participant Client as 브라우저 (AuthService)
participant RouteHandler as Next.js API (/api/proxy)
participant Backend as 백엔드 (USER_SERVICE)
participant Storage as 브라우저 Cookie / Store
User->>Client: ID / Password 로그인 요청
Client->>RouteHandler: POST /api/proxy/user-service/login (body: credentials, headers: X-Device-Id)
RouteHandler->>Backend: POST /user-service/login
Backend-->>RouteHandler: 200 OK (Response Headers: access-token, refresh-token, token-id)
Note over RouteHandler: refresh-token은 HttpOnly, Strict 쿠키로 Set-Cookie 생성
RouteHandler-->>Client: 200 OK (JSON: access-token, token-id)
Client->>Storage: document.cookie에 Authorization, token-id 저장
Client->>Client: getRemainingMs(access-token)으로 만료시간 계산 후 Silent Refresh 타이머 설정
opt 세션 만료 1분 전 자동 갱신 (Silent Refresh)
Client->>RouteHandler: PUT /api/proxy/user-service/api/v1/users/token/refresh
Note over RouteHandler: HttpOnly 쿠키의 refresh-token을 헤더에 주입하여 백엔드 호출
RouteHandler->>Backend: PUT /user-service/api/v1/users/token/refresh
Backend-->>RouteHandler: 새 access-token 및 refresh-token 발급
RouteHandler-->>Client: 새 access-token 반환 & 새 refresh-token 쿠키 갱신
Client->>Storage: 새 access-token 쿠키 업데이트 및 다음 타이머 가동
end
opt 로그아웃 (Logout)
Client->>RouteHandler: POST /api/auth/logout
RouteHandler-->>Client: refresh-token 쿠키 삭제
Client->>Storage: Authorization, token-id, Device-Id 쿠키 삭제
Client->>Client: window.dispatchEvent("auth:logout") 발생 -> /auth/login 리다이렉트
end
- 토큰 보관 전략:
access-token: 브라우저 JS가 접근 가능한Authorization쿠키에 저장되어 일반 Axios API 호출 시 즉시 헤더에 삽입됩니다.refresh-token: XSS 공격으로부터 보호하기 위해 Next.js Route Handler(/api/proxy/[...url])에서httpOnly: true,sameSite: "strict"쿠키로만 설정 및 관리됩니다.
- 백그라운드 세션 갱신:
- JWT 페이로드의
exp클레임을 파싱하여 만료 전 일정 시간에 자동으로silentRefresh()가 트리거됩니다.
- JWT 페이로드의
- 인터셉터 기반 401 감지:
- 백엔드 통신 중 토큰 만료 또는 인증 실패(
401 UNAUTHORIZED)가 감지되면errorInterceptor가 동작하여 즉시/auth/login으로 강제 이동시킵니다.
- 백엔드 통신 중 토큰 만료 또는 인증 실패(
5.2 백엔드 프록시 및 미들웨어 라우팅 (middleware.ts)
Next.js 미들웨어(middleware.ts)는 클라이언트의 모든 API 요청을 백엔드 마이크로서비스로 동적 프록시(Rewrite)합니다:
/server/:path*프록시:pathname.includes("/dc-service")인 경우:DC_SERVICE_API_URL로 리라이트.- 그 외 일반 API 요청:
SERVER_API_URL(예:http://localhost:8000)로/server접두사를 제거하여 리라이트.
/attach-service/:path*프록시 (TUS 대용량 업로드):tus-js-client가 파일 업로드 생성 후 백엔드의Location헤더로부터 받은 URL로 PATCH 요청을 직접 날릴 때(/attach-service/api/v1/tus/upload/{id}), 요청 쿠키의 인증 토큰(CLAIM_NAME)과 사용자 ID(AUTH_USER_ID)를 Request Headers에 명시적으로 주입하여 백엔드로 안전하게 바이패스합니다.
- 루트 리다이렉트:
- 사용자가
/경로로 인입 시 기본 업무 페이지인/dashboard로 307 리다이렉트 처리합니다.
- 사용자가
- 보안 헤더 삽입:
- 모든 프록시 응답에
Content-Security-Policy: img-src 'self' data: https: blob:;헤더를 주입합니다.
- 모든 프록시 응답에
5.3 메뉴 동기화 및 페이지 접근 권한 검사 (MenuWrapper)
화면이 변경될 때마다 MenuWrapper 컴포넌트가 활성화되어 2단계 권한 검증을 수행합니다:
- 메뉴 매핑: 백엔드 CMS 서비스(
MenuApi.getMenuRoles(SITE_ID))로부터 인가된 전체 메뉴 트리를 가져와 현재 브라우저의pathname과 일치하는 메뉴 항목을 추출하고, 전역useMenuStore에 저장합니다. - 페이지 단위 권한 검사: 쿠키에 기록된 메뉴 코드(
menu-code-key)를 바탕으로MenuAuthorityApi.getPageMenuAuthority를 호출합니다. - 접근 통제: 반환된 권한 객체의
inqAuthrtYn(조회 권한 여부)이"Y"가 아닌 경우, 경고 팝업("페이지에 대한 조회 권한이 없습니다.")을 띄우고 루트(/)로 강제 이동시킵니다.
5.4 행정지원 공통 업무 위젯 서브시스템 (widgets/pbadms-sprt)
하수도기본계획, 재원협의, 설치인가, 설계자문 등 4대 행정지원 업무는 고유한 서식과 더불어 공통적인 행정 프로세스 서브시스템을 공유합니다. 이를 위해 src/widgets/pbadms-sprt 패키지에 핵심 UI 및 비즈니스 로직이 모듈화되어 있습니다:
widgets/pbadms-sprt/
├── ui/
│ ├── attachments-form-section.tsx # 필수 첨부파일 등록 섹션 (TUS 업로드 연동)
│ ├── attachments-view-section.tsx # 첨부파일 조회 및 다운로드 뷰 섹션
│ ├── business-cost-form-section.tsx # 사업비 매트릭스 입력 및 합계 자동계산 섹션
│ ├── business-scale-form-section.tsx# 사업규모/시설용량 입력 섹션
│ ├── checklist-form-section.tsx # 업무별 체크리스트 탭 및 점검 항목 입력 섹션
│ ├── contact-info-form-section.tsx # 신청자 / 담당자 정보 입력 섹션
│ ├── fnrs-shar-form-section.tsx # 재원분담비율/금액 입력 섹션
│ ├── pbadms-detail-gate.tsx # 상세 화면 접근/수정 권한 검증 게이트
│ ├── pbadms-task-apply-dialog.tsx # 신규 신청 시 업무/행정구역 선택 다이얼로그
│ ├── privacy-consent-section.tsx # 개인정보 수집 및 이용 동의 체크 섹션
│ ├── progress-status-section.tsx # 진행상태 단계 표시기 (신청-접수-검토-보완-완료)
│ ├── splmnt-dmnd-dialog.tsx # 검토자의 보완요구 등록 대화상자
│ ├── splmnt-dmnd-form-section.tsx # 신청자의 보완요구 대응 내용 입력 섹션
│ └── supplement-demand-section.tsx # 보완요구 내역 조회 섹션
└── lib/
├── attachments-form-utils.ts # 파일 업로드 키 매핑 및 필수파일 누락 검증
├── business-cost-form-utils.ts # 공종별 사업비 총액/소계 재계산 엔진
├── business-scale-form-utils.ts # 시설규모 단위 및 합계 재계산
├── can-edit-pbadms-doc.ts # 문서 수정 가능 여부 판단 규칙
├── checklist-form-utils.ts # 체크리스트 트리와 폼 상태 동기화
└── fnrs-shar-form-utils.ts # 사업비 vs 재원분담 총액 일치성 검증 엔진
- 정합성 자동 검증 엔진 (
validateFnrsCstBalance):- 행정 문서 작성 시 공종별 사업비 총합계와 국비/지방비/원인자부담금 등 재원분담 합계가 정확히 일치하는지 클라이언트 폼 단에서 실시간 비교 검증하여 오입력을 원천 차단합니다.
- 수정 권한 가드 (
canEditPbadmsDoc):- 작성자 본인 여부, 현재 문서의 진행 상태 코드(임시저장
TM, 보완요청SL상태일 때만 수정 허용)를 평가하여 뷰 모드와 편집 모드를 제어합니다.
- 작성자 본인 여부, 현재 문서의 진행 상태 코드(임시저장
5.5 TUS 기반 대용량 파일 첨부 서브시스템 (useTus)
대용량 도면, 설계도서, 기본계획 보고서 PDF 등을 안정적으로 업로드하기 위해 TUS 프로토콜을 사용합니다:
- 확장자 화이트리스트 검증: 문서(
.pdf,.hwp,.hwpx,.docx,.xlsx,.pptx), 이미지(.jpg,.png), 압축파일(.zip) 등 사전 정의된 파일만 업로드 허용. - 청크 분할 업로드: 네트워크 불안정 시에도 처음부터 다시 올리지 않고 끊긴 지점부터 이어올리기 수행.
- 진행률 피드백: 파일별 업로드 진행률(
progress) 및 로딩 상태(isUploading)를 실시간 상태값으로 제공하여 프로그레스 바 렌더링. - 메타데이터 바인딩: 파일 업로드 완료 시 백엔드 첨부파일 식별자(
atflCd,atflId)를 획득하여 폼 필드와 연계.
5.6 웹한글 기안기(WebHWP) 연동 아키텍처 (widgets/hangulgiangi)
행정 기관과의 공문서 및 결재 문서 호환을 위해 웹한글 기안기를 브라우저 내에 통합 지원합니다:
- Iframe 브릿지 통신: 웹한글 컨트롤은 Next.js가 제공하는 iframe 내에 격리되어 로드되며,
postMessage기반의 표준 메시징 프로토콜을 통해 부모 창과 통신합니다. - SOP(동일 출처 정책) 해결:
next.config.ts의rewrites설정을 통해/webhwpctrl/:path*경로를 웹한글 컨트롤 서버(WEBHYP_CTRL_URL)로 리라이트 프록시하여 브라우저의 크로스 오리진 제약을 완벽히 우회합니다. - 문서 라이프사이클 관리:
- 원격 첨부파일 다운로드 -> ArrayBuffer/Blob 변환 -> HwpCtrl에 바이트 스트림 로드 -> 웹 기안기에서 편집 -> HwpCtrl에서 Blob 추출 -> TUS 업로드 후 신규 문서 번호 갱신.
6. 화면별 상세 데이터 흐름 (Screen Data Flow)
6.1 목록 조회 및 검색 데이터 흐름 (List Pattern)
모든 목록 화면(하수도기본계획, 재원협의, 설치인가, 설계자문 등)은 URL 기반 상태 동기화 및 TanStack Query 캐싱 패턴을 일관되게 따릅니다:
sequenceDiagram
autonumber
actor User as 사용자
participant Page as ListPage
participant Hook as useSearchParamsState
participant ReactQuery as TanStack Query (usePageQuery)
participant Client as Axios Client
participant Server as Backend API (/server/...)
participant Table as TanStack Table (useDataTable)
User->>Page: 검색 조건 입력 (시도, 문서명 등) 및 검색 클릭
Page->>Hook: setParams({ sidoComCd, sewerBscPlanNm, page: 0 })
Hook->>Hook: 브라우저 URL QueryString 업데이트 (뒤로가기/새로고침 지원)
Hook-->>Page: 최신 params 상태 반환
Page->>ReactQuery: useSewerBscPlanPage(queryParams) 호출
alt 캐시 존재 및 유효한 경우
ReactQuery-->>Page: 캐시된 페이지 데이터 즉시 반환
else 캐시 만료 또는 첫 요청
ReactQuery->>Client: client.get("/as-service/api/v1/...", { params })
Client->>Server: HTTP GET 요청
Server-->>Client: 200 OK (PageResponseDto: content, totalElements, totalPages)
Client-->>ReactQuery: 데이터 캐싱
ReactQuery-->>Page: 최신 데이터 전달
end
Page->>Table: useDataTable({ query, columns, pagination })
Table-->>User: 데이터 그리드 및 페이징 컴포넌트 렌더링
opt 특정 행 클릭
User->>Table: Row Click
Table->>Page: handleRowClick(row)
Page->>Page: withListQs("/sewer-bsc-plan/" + docNo) 호출<br/>(현재 검색조건 쿼리스트링을 유지한 채 상세 페이지로 이동)
end
- 상태 보존 (
useSearchParamsState): 검색 조건과 페이징 상태가 브라우저 URL 쿼리 파라미터와 양방향 동기화되어 사용자가 상세 화면을 조회한 뒤 브라우저 뒤로가기를 눌러도 이전 검색 목록과 페이지가 그대로 유지됩니다. - 헤드리스 테이블 통합 (
useDataTable): TanStack Table의state,getCoreRowModel,manualPagination과 React Query의isPending,isError,data를 바인딩하여 로딩 스켈레톤, 데이터 없음(NoData), 페이징네이션을 일관되게 렌더링합니다.
6.2 상세 조회 및 접근 제어 데이터 흐름 (Detail View Pattern)
상세 화면 진입 시에는 인가 검증과 상세 데이터 로딩이 병렬/순차적으로 처리됩니다:
sequenceDiagram
autonumber
actor User as 사용자
participant ViewPage as [Domain]ViewPage
participant Gate as DetailGate / canEditPbadmsDoc
participant ReactQuery as TanStack Query
participant Server as Backend API
User->>ViewPage: /sewer-bsc-plan/[id]?chgCycl=1 접근
ViewPage->>ReactQuery: useGetSewerBscPlanDetail(id, chgCycl)
ReactQuery->>Server: GET /as-service/api/v1/sewer-bsc-plans/{id}?chgCycl={chgCycl}
Server-->>ReactQuery: 200 OK (상세 DTO: 기본정보, 사업비, 체크리스트, 첨부파일, 진행상태)
ReactQuery-->>ViewPage: 상세 데이터 전달
ViewPage->>Gate: PbadmsDetailGate (doc, currentUser) 평가
alt 조회 권한 없음
Gate-->>User: "문서 열람 권한이 없습니다" 에러 안내 및 목록 이동
else 조회 권한 승인
Gate-->>ViewPage: 본문 렌더링 허용
ViewPage->>ViewPage: 기본정보, 사업비 매트릭스, 첨부파일 목록 렌더링
ViewPage->>ViewPage: canEditPbadmsDoc(doc) 평가 -> [수정], [보완요구], [결재신청] 버튼 노출 제어
end
6.3 폼 등록 및 수정 데이터 흐름 (Form Mutation Pattern)
등록 및 수정 화면에서는 복합 데이터 검증, TUS 파일 비동기 업로드, 트랜잭션 저장이 발생합니다:
sequenceDiagram
autonumber
actor User as 사용자
participant FormPage as [Domain]FormPage
participant RHF as React Hook Form + Zod
participant Tus as useTus (TUS 업로더)
participant AttachServer as ATTACH_SERVICE
participant Mutate as useMutation (Service API)
participant QueryClient as QueryClient
participant AsServer as AS_SERVICE
User->>FormPage: 페이지 진입 (create / edit)
alt 수정 모드 (Edit)
FormPage->>RHF: mapDetailToFormData(initialData)로 폼 기본값 프리필
else 등록 모드 (Create)
FormPage->>RHF: getCreateDefaultValues(userInfo, createDefaults) 세팅
end
User->>FormPage: 1. 파일 첨부 선택
FormPage->>Tus: uploadFileAsync(file)
Tus->>AttachServer: TUS 청크 업로드 (PATCH)
AttachServer-->>Tus: 업로드 완료 (atflCd, atflId 발급)
Tus-->>FormPage: atflCd, atflId 수신
FormPage->>RHF: setValue("essentialFiles", ...) 필드에 파일 ID 바인딩
User->>FormPage: 2. 저장 또는 신청 버튼 클릭
FormPage->>RHF: handleSubmit (Zod Schema 검증)
RHF->>RHF: zodResolver 검증 수행 (필수값, 자릿수, 포맷)
alt 유효성 오류
RHF-->>User: 입력 필드별 에러 메시지 표시
else 유효성 통과
FormPage->>FormPage: assertFnrsCstBalance() (사업비 vs 재원분담 총액 균형 검증)
FormPage->>FormPage: isFormChecklistComplete(), isFormEsntlAtchComplete() 검사
FormPage->>Mutate: sewerBscPlanService.apply(buildApplyPayload(formData))
Mutate->>AsServer: POST/PUT /as-service/api/v1/sewer-bsc-plans/...
AsServer-->>Mutate: 200 OK (성공 응답)
Mutate->>QueryClient: invalidateQueries({ queryKey: sewerBscPlanKeys.all })
QueryClient->>QueryClient: 이전 목록 및 상세 쿼리 캐시 만료 처리
Mutate-->>FormPage: 완료 콜백
FormPage-->>User: "정상적으로 신청되었습니다" 알림 후 목록으로 라우팅
end
6.4 대시보드 화면 데이터 흐름 (Dashboard Pattern)
대시보드(DashboardPage)는 포털 초기 진입 속도를 극대화하기 위해 단일 통합 쿼리(useGetMainDashboard)를 통해 화면 전체 데이터를 원샷으로 수신하여 자식 위젯들에 하향식(Props Drilling 최소화)으로 분배합니다:
graph TD
A["useGetMainDashboard() 쿼리 호출"] --> B["GET /as-service/api/v1/dashboard/main"]
B --> C["DashboardResponseDto"]
C --> D["data.basinDocPrgrsList"] --> D1["NationalAsMap (전국 4대강 유역별 행정지원 현황 지도 시각화)"]
C --> E["data.docPrgrsSttsList"] --> E1["DocPrgrsSttsCards (접수/검토/보완/완료 상태별 카운트 카드)"]
C --> F["data.notiList & notiStats"] --> F1["DashboardNotiList (실시간 업무 통보 및 알림톡 발송 현황)"]
G["독립 쿼리: useGetPosts()"] --> H["GET /board-service/api/v1/posts"]
H --> I["DashboardNoticeTable (시스템 공지사항 테이블)"]
7. 백엔드 마이크로서비스 연계 맵 (Backend Services Integration)
AS 모듈이 ENDPOINT를 통해 통신하는 백엔드 마이크로서비스들의 상세 연계 정보는 다음과 같습니다:
+---------------------------------------------------------------------------------------------------+
| Next.js Middleware Proxy Layer |
| /server/* ==> SERVER_API_URL | /attach-service/* ==> SERVER_API_URL | /cms/* ==> SUB_DOMAIN |
+---------------------------------------------------------------------------------------------------+
| | | | |
v v v v v
[ AS_SERVICE ] [ ATTACH_SERVICE ] [ USER_SERVICE ] [ ELAPR_SERVICE ] [ CMS_SERVICE ]
- 하수도기본계획 - TUS 청크 업로드 - 사용자 로그인 - 전자결재 템플릿 - 공통코드 캐시
- 재원협의 - 첨부파일 메타데이터 - 토큰 갱신 - 결재선 관리 - 메뉴 및 권한
- 설치인가 - 파일 다운로드 - 내 정보 조회 - 결재 요청 - 조직도
- 설계자문 - 결재 진행상태 - 시스템 알림
- 체크리스트 마스터
- 공종/회계 마스터
- 대시보드 통계
| 서비스 명칭 | 기본 엔드포인트 URI | 담당 도메인 및 주요 기능 |
|---|---|---|
AS_SERVICE |
/as-service/api/v1 |
행정지원 비즈니스 코어 - /sewer-bsc-plans: 하수도 기본계획 CRUD- /fnrs-cnsltn-mng: 재원협의 신청 및 분담 관리- /instl-sncn: 설치인가 관리- /design-cnstn: 설계자문 관리- /cklst, /cklst-artcl: 체크리스트 템플릿 및 평가- /acntg-se, /cnstp-se: 회계구분 및 공종구분 기준 코드- /esntl-atch-file: 필수 첨부파일 마스터- /dashboard: 대시보드 종합 지표 |
ATTACH_SERVICE |
/attach-service/api/v1 |
파일 관리 서비스 - /tus/upload: TUS 프로토콜 파일 업로드 엔드포인트- /atfl/attachments: 첨부파일 메타데이터 조회- /atflcd/download, /download: 첨부파일 스트림 다운로드 |
USER_SERVICE |
/user-service/api/v1 |
사용자 및 세션 서비스 - /login: 사용자 로그인 인증- /users/token/refresh: 토큰 재발급(Silent Refresh)- /users/info/me: 현재 로그인 사용자 상세 정보 |
AS_ELAPR_SERVICE |
/as-elapr-service/api/v1 |
전자결재 서비스 - /elapr-tmplt: 결재 서식 템플릿- /elapr-apln: 결재선 지정 및 순서 관리- /elapr-dmnd: 결재 상신 및 승인/반려 요청- /elapr-prgrs-stts: 결재 진행 상태 조회 |
CMS_SERVICE |
/cms-service/api/v1 |
공통 플랫폼 서비스 - /code/cache: 전사 공통코드 캐시 조회- /menu-roles, /menu-authrts: 사이트별 메뉴 및 권한 매핑- /user-ognz: 조직도 및 사용자 트리- /noti: 통보 및 알림 |
NTFTALK_SERVICE |
/ntftalk-service/api/v1 |
알림톡 서비스 - /ntftalk-temp: 알림톡 템플릿 관리- /ata/send: 카카오 알림톡/SMS 발송 |
BOARD_SERVICE |
/board-service/api/v1 |
게시판 서비스 - /posts: 공지사항 게시글 목록 및 상세 조회 |
8. 종합 검토 및 아키텍처적 시사점
8.1 아키텍처적 우수성
- 엄격한 FSD v2.1 계층 원칙 준수:
- 상위 레이어가 하위 레이어만 참조할 수 있는 단방향 의존성 규칙이 확립되어 있으며,
steiger린터를 통해 아키텍처 무결성을 상시 검증합니다.
- 상위 레이어가 하위 레이어만 참조할 수 있는 단방향 의존성 규칙이 확립되어 있으며,
- 도메인 간 공통 프로세스의 위젯 캡슐화 (
widgets/pbadms-sprt):- 하수도기본계획, 재원협의, 설치인가, 설계자문 등 4대 행정지원 업무가 거의 동일한 행정 절차(신청->접수->검토->보완->결재)를 거치므로, 중복될 수 있는 폼 섹션과 계산 로직을
widgets/pbadms-sprt에 응집력 있게 격리하여 재사용성과 유지보수성을 극대화했습니다.
- 하수도기본계획, 재원협의, 설치인가, 설계자문 등 4대 행정지원 업무가 거의 동일한 행정 절차(신청->접수->검토->보완->결재)를 거치므로, 중복될 수 있는 폼 섹션과 계산 로직을
- 견고한 폼 상태와 데이터 유효성 검증 체계:
- 비제어 컴포넌트 기반
react-hook-form과 타입 세이프한zod스키마를 결합하여 복잡한 수치 매트릭스(사업비 합계, 재원분담 총액 균형)의 입력 성능과 무결성을 동시에 달성했습니다.
- 비제어 컴포넌트 기반
- BFF + 쿠키 기반의 안전한 인증 흐름:
- XSS 공격에 취약한 Refresh Token을 브라우저 JS에 노출하지 않고 Next.js Route Handler의 HttpOnly 쿠키로 은닉 관리하면서, 브라우저에서는 만료 시점 기반 자동 갱신(Silent Refresh) 타이머를 가동하여 매끄러운 사용자 경험을 제공합니다.
- 독립 iframe과 리라이트 프록시를 활용한 레거시 웹한글 기안기 통합:
- 웹한글 컨트롤의 브라우저 SOP 문제를 Next.js 리라이트 프록시로 해결하고, iframe 브릿지 통신을 통해 최신 React 19 / Next.js 15 환경에서도 레거시 공문서 기안 기능을 안정적으로 구동시켰습니다.
8.2 개발 및 운영 시 주의점
- Next.js Standalone 배포 시 환경 변수 참조:
SERVER_API_URL등 런타임에 필요한 서버 환경변수는 빌드 타임이 아닌 컨테이너 기동 시점에도 정확히 주입되어야 미들웨어의 API 프록시 리라이트가 정상 작동합니다.
- 미들웨어 콘솔 로깅 부하:
- 현재
middleware.ts에 모든/server요청 및 TUS 프록시 요청에 대해console.log가 상세히 출력되도록 되어 있으므로, 운영 환경(Production) 배포 시에는 로깅 레벨 조정 또는 비활성화가 권장됩니다.
- 현재
- 대용량 파일 첨부 시 리버스 프록시 타임아웃/바디 제한:
- Nginx 등 전면 웹서버를 통과할 때
/attach-service및/server경로에 대한client_max_body_size및 타임아웃 설정이 TUS 업로드 크기에 맞추어 충분히 확보되어야 합니다.
- Nginx 등 전면 웹서버를 통과할 때