Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 leedj312
|
2298549a73 |
@@ -1,33 +0,0 @@
|
||||
name: Deploy Frontend
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- deploy
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Setup SSH
|
||||
run: |
|
||||
mkdir -p ~/.ssh
|
||||
echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/deploy_key
|
||||
chmod 600 ~/.ssh/deploy_key
|
||||
ssh-keyscan -p 28 -H 192.168.0.4 >> ~/.ssh/known_hosts
|
||||
|
||||
- name: Deploy
|
||||
run: |
|
||||
ssh -i ~/.ssh/deploy_key -p 28 onasys@192.168.0.4 << 'EOF'
|
||||
cd ~/frontend
|
||||
git restore .
|
||||
git clean -fd
|
||||
git pull origin deploy
|
||||
pnpm install
|
||||
pnpm turbo build
|
||||
pm2 reload all
|
||||
EOF
|
||||
+4
-17
@@ -1,11 +1,12 @@
|
||||
# turbo
|
||||
.turbo/
|
||||
**/.vscode/
|
||||
*.code-workspace
|
||||
|
||||
# dependencies
|
||||
node_modules/
|
||||
.idea/
|
||||
|
||||
# build
|
||||
.next/
|
||||
dist/
|
||||
|
||||
# build
|
||||
.next
|
||||
@@ -19,17 +20,3 @@ apps/fo/.next/**/*
|
||||
# env
|
||||
#.env*
|
||||
.qodo
|
||||
|
||||
# next-agents-md
|
||||
.next-docs/
|
||||
|
||||
pnpm-lock.yaml
|
||||
settings.json
|
||||
.npmrc
|
||||
.cursor
|
||||
.agent
|
||||
CLAUDE.MD
|
||||
|
||||
apps/**/tsconfig.tsbuildinfo
|
||||
packages/**/tsconfig.tsbuildinfo
|
||||
logs/
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
#!/bin/sh
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
||||
if [ "$BRANCH" != "main" ]; then
|
||||
exit 0
|
||||
fi
|
||||
echo "Branch: $BRANCH"
|
||||
echo "Changed packages (dry-run):"
|
||||
pnpm turbo run build --filter="...[origin/$BRANCH]" --dry-run
|
||||
echo "Starting build..."
|
||||
pnpm turbo run build --filter="...[origin/$BRANCH]"
|
||||
Vendored
-196
@@ -1,196 +0,0 @@
|
||||
{
|
||||
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "dev:as 디버그",
|
||||
"runtimeExecutable": "pnpm",
|
||||
"runtimeArgs": [
|
||||
"run",
|
||||
"dev:as"
|
||||
],
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
],
|
||||
"resolveSourceMapLocations": [
|
||||
"${workspaceFolder}/**",
|
||||
"!**/node_modules/**"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "integratedTerminal",
|
||||
"sourceMaps": true,
|
||||
"env": {
|
||||
"NODE_OPTIONS": "--inspect --max-old-space-size=8192"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"name": "dev:as 서버 컴포넌트 디버그 (node-terminal)",
|
||||
"command": "pnpm --filter as dev",
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
{
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"name": "dev:as 통합 디버그 (Server + Client)",
|
||||
"command": "pnpm --filter as dev",
|
||||
"cwd": "${workspaceFolder}",
|
||||
"serverReadyAction": {
|
||||
"action": "debugWithChrome",
|
||||
"pattern": "- Local:\\s+(https?://.+)",
|
||||
"uriFormat": "%s",
|
||||
"webRoot": "${workspaceFolder}/apps/as"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "Playwright: 현재 활성화된 테스트 디버그",
|
||||
"runtimeExecutable": "pnpm",
|
||||
"runtimeArgs": [
|
||||
"--filter",
|
||||
"cs",
|
||||
"exec",
|
||||
"playwright",
|
||||
"test",
|
||||
"${relativeFile}"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "integratedTerminal",
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "Playwright: cs 로그인 테스트 디버그",
|
||||
"runtimeExecutable": "pnpm",
|
||||
"runtimeArgs": [
|
||||
"--filter",
|
||||
"cs",
|
||||
"exec",
|
||||
"playwright",
|
||||
"test",
|
||||
"tests/login.spec.ts"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "integratedTerminal",
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"name": "dev:cs 통합 디버그 (Server + Client)",
|
||||
"command": "pnpm --filter cs dev",
|
||||
"cwd": "${workspaceFolder}",
|
||||
"serverReadyAction": {
|
||||
"action": "debugWithChrome",
|
||||
"pattern": "- Local:\\s+(https?://.+)",
|
||||
"uriFormat": "%s",
|
||||
"webRoot": "${workspaceFolder}/apps/cs"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "dev:cs 디버그",
|
||||
"runtimeExecutable": "pnpm",
|
||||
"runtimeArgs": [
|
||||
"run",
|
||||
"dev:cs"
|
||||
],
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
],
|
||||
"resolveSourceMapLocations": [
|
||||
"${workspaceFolder}/**",
|
||||
"!**/node_modules/**"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "integratedTerminal",
|
||||
"sourceMaps": true,
|
||||
"env": {
|
||||
"NODE_OPTIONS": "--inspect --max-old-space-size=8192"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "node",
|
||||
"request": "attach",
|
||||
"name": "dev:cs 서버 연결 (attach)",
|
||||
"port": 9229,
|
||||
"restart": true,
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
],
|
||||
"sourceMaps": true,
|
||||
"resolveSourceMapLocations": [
|
||||
"${workspaceFolder}/apps/cs/**",
|
||||
"!**/node_modules/**"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "chrome",
|
||||
"request": "launch",
|
||||
"name": "dev:cs 클라이언트 디버그 (Chrome)",
|
||||
"url": "http://localhost:3000",
|
||||
"webRoot": "${workspaceFolder}/apps/cs",
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
],
|
||||
"sourceMaps": true,
|
||||
"resolveSourceMapLocations": [
|
||||
"${workspaceFolder}/apps/cs/**",
|
||||
"!**/node_modules/**"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "dev:st 디버그",
|
||||
"runtimeExecutable": "pnpm",
|
||||
"runtimeArgs": [
|
||||
"run",
|
||||
"dev:st"
|
||||
],
|
||||
"skipFiles": [
|
||||
"<node_internals>/**",
|
||||
"**/node_modules/**"
|
||||
],
|
||||
"resolveSourceMapLocations": [
|
||||
"${workspaceFolder}/**",
|
||||
"!**/node_modules/**"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "integratedTerminal",
|
||||
"sourceMaps": true,
|
||||
"env": {
|
||||
"NODE_OPTIONS": "--inspect --max-old-space-size=8192"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"name": "dev:st 통합 디버그 (Server + Client)",
|
||||
"command": "pnpm --filter st dev",
|
||||
"cwd": "${workspaceFolder}",
|
||||
"serverReadyAction": {
|
||||
"action": "debugWithChrome",
|
||||
"pattern": "- Local:\\s+(https?://.+)",
|
||||
"uriFormat": "%s",
|
||||
"webRoot": "${workspaceFolder}/apps/st"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
Vendored
-8
@@ -1,8 +0,0 @@
|
||||
{
|
||||
"chat.tools.terminal.autoApprove": {
|
||||
"pnpm": true
|
||||
},
|
||||
"playwright.configs": [
|
||||
"apps/cs/playwright.config.ts"
|
||||
]
|
||||
}
|
||||
@@ -201,4 +201,3 @@ http://dev.onasys.co.kr:8000/webjars/swagger-ui/index.html?urls.primaryName=atta
|
||||
- 사이드바 메뉴 클릭 시 "menuCd" 데이터 쿠키 저장 처리
|
||||
- 쿠키명 : menu-code-key
|
||||
- 해당 메뉴 쿠키 데이터 가져와 페이지 권한 및 상당 Breadcrumb 데이터 전달 처리
|
||||
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
# src/shared/config/env.ts 참고
|
||||
NEXT_PUBLIC_PORT=
|
||||
NEXT_PUBLIC_PROXY_HOST=
|
||||
NEXT_PUBLIC_SITE_ID=
|
||||
SERVER_API_URL=
|
||||
|
||||
# 401 시 브라우저 리다이렉트 대상
|
||||
NEXT_PUBLIC_AUTH_LOGIN_REDIRECT_URL=/auth/login
|
||||
@@ -1,3 +0,0 @@
|
||||
{
|
||||
"extends": "next/core-web-vitals"
|
||||
}
|
||||
@@ -1,36 +0,0 @@
|
||||
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
|
||||
|
||||
# dependencies
|
||||
/node_modules
|
||||
/.pnp
|
||||
.pnp.js
|
||||
.yarn/install-state.gz
|
||||
|
||||
# testing
|
||||
/coverage
|
||||
|
||||
# next.js
|
||||
/.next/
|
||||
/out/
|
||||
|
||||
# production
|
||||
/build
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
|
||||
# debug
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# local env files
|
||||
.env*.local
|
||||
|
||||
# vercel
|
||||
.vercel
|
||||
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
@@ -1,8 +0,0 @@
|
||||
{
|
||||
"semi": true,
|
||||
"trailingComma": "all",
|
||||
"singleQuote": false,
|
||||
"printWidth": 100,
|
||||
"tabWidth": 2,
|
||||
"plugins": ["prettier-plugin-tailwindcss"]
|
||||
}
|
||||
@@ -1,187 +0,0 @@
|
||||
# Template Application
|
||||
|
||||
Next.js 애플리케이션 with FSD(Feature Sliced Design) 아키텍처
|
||||
|
||||
## 기술 스택
|
||||
|
||||
- **프레임워크**: Next.js 15 + TypeScript
|
||||
- **스타일링**: Tailwind CSS
|
||||
- **상태관리**: Zustand
|
||||
- **데이터 페칭**: TanStack Query (React Query)
|
||||
- **폼 관리**: React Hook Form + Zod
|
||||
- **테이블**: TanStack Table
|
||||
- **HTTP 클라이언트**: Axios
|
||||
- **날짜 처리**: Day.js
|
||||
|
||||
## 프로젝트 구조 (FSD + Next.js App Router)
|
||||
|
||||
이 프로젝트는 **Feature-Sliced Design v2.1**과 **FSD 공식 Next.js 가이드**에 맞춰 구성되어 있습니다. Next.js `app/`은 라우트만 담당하고, 실제 레이어는 `src/` 아래에 있습니다.
|
||||
|
||||
```
|
||||
_template/
|
||||
├── app/ # Next.js App Router (루트) — 라우트·레이아웃 진입점만
|
||||
│ ├── layout.tsx # 루트 레이아웃 (src/app에서 providers, styles import)
|
||||
│ └── (with-base-layout)/
|
||||
│ ├── layout.tsx # BaseLayout 래퍼 (src/app/layouts에서 import)
|
||||
│ └── page.tsx # re-export: export { MainPage as default } from '@/pages/home'
|
||||
│
|
||||
├── pages/ # 빈 폴더 + README (Next.js가 src/pages를 Pages Router로 쓰지 않도록)
|
||||
│ └── README.md
|
||||
│
|
||||
└── src/ # FSD 레이어 (실제 코드)
|
||||
├── app/ # App 레이어 (슬라이스 없음, 세그먼트만)
|
||||
│ ├── providers/ # 전역 Providers (QueryClient 등)
|
||||
│ ├── styles/ # 글로벌 스타일 (globals.css)
|
||||
│ └── layouts/ # 공통 레이아웃 컴포넌트 (BaseLayoutWrapper)
|
||||
│
|
||||
├── pages/ # Pages 레이어 (페이지 슬라이스)
|
||||
│ └── home/
|
||||
│ ├── ui/
|
||||
│ └── index.ts # Public API
|
||||
│
|
||||
├── widgets/ # Widgets 레이어
|
||||
├── features/ # Features 레이어
|
||||
├── entities/ # Entities 레이어
|
||||
└── shared/ # Shared 레이어
|
||||
├── ui/
|
||||
├── api/
|
||||
├── lib/
|
||||
└── config/
|
||||
```
|
||||
|
||||
### 계층 구조 이해하기
|
||||
|
||||
FSD는 **3단계 계층**으로 구성됩니다:
|
||||
|
||||
1. **Layers (레이어)**: 책임과 의존성에 따른 수평적 분리 (app, pages, widgets, features, entities, shared)
|
||||
2. **Slices (슬라이스)**: 비즈니스 도메인에 따른 수직적 분리 (user, product, auth-login 등)
|
||||
3. **Segments (세그먼트)**: 기술적 목적에 따른 분리 (ui, api, model, lib 등)
|
||||
|
||||
> 📚 각 레이어의 자세한 설명은 해당 폴더의 README.md를 참고하세요.
|
||||
|
||||
## FSD 레이어 설명
|
||||
|
||||
FSD는 계층적 아키텍처로, 각 레이어는 책임의 범위와 의존성의 정도에 따라 구분됩니다. 7개의 표준화된 레이어가 있으며, 프로젝트에 필요한 레이어만 사용하면 됩니다.
|
||||
|
||||
### 레이어 계층 구조 (위에서 아래로)
|
||||
|
||||
```
|
||||
app/ ↑ 가장 높은 책임, 가장 많은 의존성
|
||||
pages/ |
|
||||
widgets/ |
|
||||
features/ |
|
||||
entities/ |
|
||||
shared/ ↓ 가장 낮은 책임, 의존성 없음
|
||||
```
|
||||
|
||||
### 1. App
|
||||
- **목적**: 앱 전체에 영향을 주는 기술적/비즈니스적 사항
|
||||
- **내용**: Context providers, 글로벌 스타일, 스토어 설정, 라우터 설정, 애널리틱스
|
||||
- **특징**: 슬라이스가 없고 세그먼트로만 구성
|
||||
- **의존성**: 모든 하위 레이어 사용 가능
|
||||
|
||||
### 2. Pages (src/pages)
|
||||
- **목적**: 웹사이트나 애플리케이션을 구성하는 페이지/화면
|
||||
- **내용**: 페이지 UI, 로딩 상태, 에러 바운더리, 데이터 fetching
|
||||
- **특징**: 한 페이지당 한 슬라이스 (유사한 페이지는 그룹화 가능). Next.js `app/`의 route 파일에서 re-export
|
||||
- **의존성**: `widgets`, `features`, `entities`, `shared` 사용 가능
|
||||
|
||||
> 💡 **FSD v2.1 권장사항**: "pages-first" 접근 방식을 따라, 재사용되지 않는 큰 UI 블록과 비즈니스 로직은 페이지 슬라이스에 유지하세요.
|
||||
|
||||
### 3. Widgets
|
||||
- **목적**: 큰 규모의 독립적인 UI 블록
|
||||
- **내용**: 여러 features와 entities를 조합한 복합 UI
|
||||
- **사용 시기**: 여러 페이지에서 재사용되거나, 페이지에 여러 개의 큰 독립적 블록이 있을 때
|
||||
- **의존성**: `features`, `entities`, `shared` 사용 가능 (다른 `widgets` 불가)
|
||||
|
||||
### 4. Features
|
||||
- **목적**: 사용자가 수행하는 주요 상호작용과 비즈니스 기능
|
||||
- **내용**: 사용자 시나리오 (예: 로그인, 상품 검색, 댓글 작성)
|
||||
- **사용 시기**: 여러 페이지에서 재사용되는 기능
|
||||
- **의존성**: `entities`, `shared` 사용 가능 (다른 `features` 불가)
|
||||
|
||||
### 5. Entities
|
||||
- **목적**: 비즈니스가 다루는 실제 개념 (User, Product, Order 등)
|
||||
- **내용**: 데이터 모델, 타입, API 요청, 엔티티의 시각적 표현
|
||||
- **특징**: 비즈니스 용어로 명명
|
||||
- **의존성**: 다른 `entities`, `shared` 사용 가능
|
||||
|
||||
### 6. Shared
|
||||
- **목적**: 애플리케이션의 기반 제공
|
||||
- **내용**: API 클라이언트, UI Kit, 유틸리티 라이브러리, 글로벌 설정
|
||||
- **특징**: 비즈니스 로직 없음, 슬라이스가 없고 세그먼트로만 구성
|
||||
- **의존성**: 외부 라이브러리만 사용 가능 (다른 레이어 불가)
|
||||
|
||||
## 시작하기
|
||||
|
||||
```bash
|
||||
# 의존성 설치
|
||||
pnpm install
|
||||
|
||||
# 개발 서버 실행
|
||||
pnpm run dev
|
||||
|
||||
# 프로덕션 빌드
|
||||
pnpm run build
|
||||
|
||||
# 프로덕션 서버 실행
|
||||
pnpm start
|
||||
```
|
||||
|
||||
## 환경 변수
|
||||
|
||||
`.env.local` 파일 생성:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_API_URL=http://localhost:3000/api
|
||||
```
|
||||
|
||||
## FSD 핵심 규칙
|
||||
|
||||
### 1. Import 규칙
|
||||
|
||||
> **슬라이스 내의 모듈(파일)은 오직 하위 레이어에 있는 슬라이스만 import할 수 있습니다.**
|
||||
|
||||
```typescript
|
||||
// ✅ 올바른 import (하위 레이어)
|
||||
// features/auth-login/ui/form.tsx
|
||||
import { User } from "entities/user";
|
||||
import { Button } from "shared/ui/button";
|
||||
|
||||
// ❌ 잘못된 import (같은 레이어)
|
||||
// features/auth-login/ui/form.tsx
|
||||
import { PostForm } from "features/post-create"; // 금지!
|
||||
|
||||
// ❌ 잘못된 import (상위 레이어)
|
||||
// features/auth-login/ui/form.tsx
|
||||
import { Header } from "widgets/header"; // 금지!
|
||||
```
|
||||
|
||||
### 2. Public API 규칙
|
||||
|
||||
> **슬라이스 외부에서는 Public API(index.ts)를 통해서만 접근해야 합니다.**
|
||||
|
||||
```typescript
|
||||
// ✅ 올바른 import (Public API 사용)
|
||||
import { LoginForm } from "features/auth-login";
|
||||
|
||||
// ❌ 잘못된 import (내부 구조 직접 접근)
|
||||
import { LoginForm } from "features/auth-login/ui/login-form";
|
||||
```
|
||||
|
||||
**Public API 작성 시 주의사항**:
|
||||
- 와일드카드 re-export(`export * from`) 사용 지양
|
||||
- 필요한 것만 명시적으로 export
|
||||
- 슬라이스의 인터페이스를 명확하게 표현
|
||||
|
||||
```typescript
|
||||
// ❌ 나쁜 예시
|
||||
export * from "./ui/Comment";
|
||||
export * from "./model/comments";
|
||||
|
||||
// ✅ 좋은 예시
|
||||
export { Comment } from "./ui/comment";
|
||||
export { CommentForm } from "./ui/comment-form";
|
||||
export { useComments } from "./model/use-comments";
|
||||
export type { Comment, CommentFormData } from "./model/types";
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
import type { ReactNode } from "react";
|
||||
import { BaseLayoutWrapper } from "@/app/layouts/base-layout";
|
||||
|
||||
interface WithBaseLayoutProps {
|
||||
children: ReactNode;
|
||||
}
|
||||
|
||||
export default function WithBaseLayout({ children }: WithBaseLayoutProps) {
|
||||
return <BaseLayoutWrapper>{children}</BaseLayoutWrapper>;
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
export { MainPage as default } from "@/pages/home";
|
||||
@@ -1,169 +0,0 @@
|
||||
# App Layer
|
||||
|
||||
**App**은 애플리케이션 전체에 영향을 미치는 기술적, 비즈니스적 사항을 다루는 최상위 레이어입니다.
|
||||
|
||||
## 목적
|
||||
|
||||
- 애플리케이션의 진입점(entrypoint) 제공
|
||||
- 전역 Context Providers 설정
|
||||
- 라우터 구성
|
||||
- 글로벌 스타일 정의
|
||||
- 전역 상태 저장소 설정
|
||||
- 애널리틱스 및 모니터링 설정
|
||||
|
||||
## 특징
|
||||
|
||||
- **슬라이스 없음**: App 레이어는 Shared처럼 슬라이스가 없고 세그먼트로만 구성됩니다
|
||||
- **전체 앱 관심사**: 특정 비즈니스 도메인이 아닌 앱 전체와 관련된 코드만 포함
|
||||
- **최상위 레이어**: 모든 하위 레이어의 모듈을 자유롭게 import 가능
|
||||
|
||||
## 구조 (Next.js App Router)
|
||||
|
||||
Next.js를 사용하는 경우, App 레이어는 주로 `app/` 디렉토리로 표현됩니다:
|
||||
|
||||
```
|
||||
app/
|
||||
├── (routes)/ # 라우트 그룹 및 페이지
|
||||
│ ├── (auth)/
|
||||
│ │ ├── login/
|
||||
│ │ │ └── page.tsx
|
||||
│ │ └── register/
|
||||
│ │ └── page.tsx
|
||||
│ └── (main)/
|
||||
│ ├── dashboard/
|
||||
│ │ └── page.tsx
|
||||
│ └── settings/
|
||||
│ └── page.tsx
|
||||
├── layout.tsx # 루트 레이아웃
|
||||
├── page.tsx # 홈 페이지
|
||||
├── globals.css # 글로벌 스타일
|
||||
├── providers.tsx # 전역 Providers 설정
|
||||
└── error.tsx # 글로벌 에러 핸들러
|
||||
```
|
||||
|
||||
### 일반적인 FSD 세그먼트 구조
|
||||
|
||||
FSD 표준 세그먼트를 사용하는 경우:
|
||||
|
||||
```
|
||||
app/
|
||||
├── entrypoint/ # 애플리케이션 진입점 (프레임워크별)
|
||||
│ └── index.tsx
|
||||
├── providers/ # Context Providers
|
||||
│ ├── query-provider.tsx
|
||||
│ ├── theme-provider.tsx
|
||||
│ └── index.tsx
|
||||
├── styles/ # 글로벌 스타일
|
||||
│ ├── globals.css
|
||||
│ └── theme.css
|
||||
├── store/ # 글로벌 상태 저장소 설정
|
||||
│ └── index.ts
|
||||
└── routes/ # 라우터 설정
|
||||
└── index.tsx
|
||||
```
|
||||
|
||||
## 예시
|
||||
|
||||
### Next.js Providers 설정
|
||||
|
||||
```typescript
|
||||
// app/providers.tsx
|
||||
'use client';
|
||||
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import { ThemeProvider } from 'next-themes';
|
||||
import { useState } from 'react';
|
||||
|
||||
export function Providers({ children }: { children: React.ReactNode }) {
|
||||
const [queryClient] = useState(() => new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: {
|
||||
staleTime: 60 * 1000,
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
return (
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
|
||||
{children}
|
||||
</ThemeProvider>
|
||||
</QueryClientProvider>
|
||||
);
|
||||
}
|
||||
|
||||
// app/layout.tsx
|
||||
import { Providers } from './providers';
|
||||
import './globals.css';
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
return (
|
||||
<html lang="ko">
|
||||
<body>
|
||||
<Providers>
|
||||
{children}
|
||||
</Providers>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 글로벌 설정
|
||||
|
||||
```typescript
|
||||
// app/config/analytics.ts
|
||||
export function initAnalytics() {
|
||||
if (typeof window !== 'undefined') {
|
||||
// 애널리틱스 초기화
|
||||
}
|
||||
}
|
||||
|
||||
// app/config/monitoring.ts
|
||||
export function initMonitoring() {
|
||||
// 에러 모니터링 설정
|
||||
}
|
||||
```
|
||||
|
||||
## Next.js App Router와 FSD
|
||||
|
||||
Next.js의 `app/` 디렉토리는 FSD의 **App 레이어**와 **Pages 레이어**를 동시에 담당합니다:
|
||||
|
||||
- **루트 레벨 파일들** (`layout.tsx`, `providers.tsx`, `globals.css`): App 레이어
|
||||
- **라우트 폴더들** (`dashboard/`, `login/` 등): Pages 레이어
|
||||
|
||||
각 페이지별 비즈니스 로직은:
|
||||
- 재사용되지 않는 UI는 페이지 슬라이스(`app/dashboard/` 등) 안에 유지
|
||||
- 재사용되는 기능은 `features/` 레이어로 분리
|
||||
- 여러 페이지에서 재사용되는 큰 UI 블록은 `widgets/` 레이어로 분리
|
||||
|
||||
## 레이어 의존성 규칙
|
||||
|
||||
✅ **허용되는 의존성**:
|
||||
- 모든 하위 레이어 (`pages`, `widgets`, `features`, `entities`, `shared`)
|
||||
- 같은 `app` 레이어 내의 다른 세그먼트
|
||||
- 외부 라이브러리
|
||||
|
||||
❌ **금지된 의존성**:
|
||||
- 없음 (App은 최상위 레이어)
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **비대화 방지**: App 레이어가 너무 커지면 관리가 어려워집니다. 대부분의 로직은 하위 레이어에 배치하세요
|
||||
2. **전역 관심사만**: 특정 페이지나 기능에만 관련된 코드는 해당 레이어로 이동
|
||||
3. **라우터 레벨 로직**: 라우터 및 서버 레벨 로직은 이 레이어에 유지
|
||||
4. **Processes 레이어 사용 지양**: Processes 레이어는 deprecated되었으므로 해당 로직은 `app`이나 `features`에 배치
|
||||
|
||||
## FSD v2.1 권장사항
|
||||
|
||||
최신 FSD 버전(v2.1)은 **"pages-first"** 접근 방식을 권장합니다:
|
||||
|
||||
- 더 많은 코드를 페이지 슬라이스에 유지
|
||||
- 큰 UI 블록과 재사용되지 않는 비즈니스 로직은 즉시 추출하지 말고 페이지에 보관
|
||||
- 실제로 재사용이 필요할 때만 `features`나 `widgets`로 분리
|
||||
|
||||
이 접근 방식은 과도한 추상화를 방지하고 코드를 더 쉽게 탐색할 수 있게 합니다.
|
||||
@@ -1,25 +0,0 @@
|
||||
import type { Metadata } from "next";
|
||||
import { cookies } from "next/headers";
|
||||
import { Providers } from "@/app/providers";
|
||||
import "@/app/styles/globals.css";
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: "유역하수도통합플랫폼 Hasuon",
|
||||
description: "행정지원시스템",
|
||||
};
|
||||
|
||||
interface RootLayoutProps {
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export default async function RootLayout({ children }: RootLayoutProps) {
|
||||
const theme = (await cookies()).get("site-theme-key");
|
||||
|
||||
return (
|
||||
<html lang="ko" data-theme={theme?.value}>
|
||||
<body>
|
||||
<Providers>{children}</Providers>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
@@ -1,18 +0,0 @@
|
||||
import { defineConfig, globalIgnores } from "eslint/config";
|
||||
import nextVitals from "eslint-config-next/core-web-vitals";
|
||||
import nextTs from "eslint-config-next/typescript";
|
||||
|
||||
const eslintConfig = defineConfig([
|
||||
...nextVitals,
|
||||
...nextTs,
|
||||
// Override default ignores of eslint-config-next.
|
||||
globalIgnores([
|
||||
// Default ignores of eslint-config-next:
|
||||
".next/**",
|
||||
"out/**",
|
||||
"build/**",
|
||||
"next-env.d.ts",
|
||||
]),
|
||||
]);
|
||||
|
||||
export default eslintConfig;
|
||||
@@ -1,50 +0,0 @@
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
import { PORT, PROXY_HOST, SERVER_API_URL, SITE_ID } from "@/shared/config";
|
||||
|
||||
const serverApiUrl = process.env.SERVER_API_URL ?? "http://localhost:3000";
|
||||
|
||||
// CSP 헤더 설정 함수 (img-src만)
|
||||
function addSecurityHeaders(response: NextResponse): NextResponse {
|
||||
response.headers.set("Content-Security-Policy", "img-src 'self' data: https: blob:;");
|
||||
return response;
|
||||
}
|
||||
|
||||
export function middleware(req: NextRequest) {
|
||||
const pathname = req.nextUrl.pathname;
|
||||
const searchParams = req.nextUrl.searchParams;
|
||||
|
||||
const logMessages: string[] = [
|
||||
`[Middleware Request] ${new Date().toISOString()}`,
|
||||
`[Environment]\n Mode: ${process.env.NODE_ENV}\n Port: ${PORT}\n Proxy Host: ${PROXY_HOST}\n Server API URL: ${SERVER_API_URL}\n Site ID: ${SITE_ID}`,
|
||||
`[Request]\n Original Pathname: ${pathname}`,
|
||||
];
|
||||
|
||||
if (pathname.startsWith("/server")) {
|
||||
const queryParams = searchParams.toString();
|
||||
const newUrl = `${serverApiUrl}${pathname.replace("/server", "")}${
|
||||
queryParams ? `?${queryParams}` : ""
|
||||
}`;
|
||||
|
||||
logMessages.push(` Rewritten URL: ${newUrl}`);
|
||||
logMessages.push("\n--------------------------------\n");
|
||||
console.log(logMessages.join("\n"));
|
||||
|
||||
const response = NextResponse.rewrite(new URL(newUrl));
|
||||
return addSecurityHeaders(response);
|
||||
}
|
||||
|
||||
// if (pathname === "/") {
|
||||
// const response = NextResponse.redirect(new URL("/dashboard", req.url));
|
||||
// return addSecurityHeaders(response);
|
||||
// }
|
||||
|
||||
logMessages.push("\n--------------------------------\n");
|
||||
console.log(logMessages.join("\n"));
|
||||
|
||||
const response = NextResponse.next();
|
||||
return addSecurityHeaders(response);
|
||||
}
|
||||
|
||||
export const config = {
|
||||
matcher: ["/server/:path*", "/"],
|
||||
};
|
||||
@@ -1,8 +0,0 @@
|
||||
import type { NextConfig } from "next";
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
reactStrictMode: true,
|
||||
transpilePackages: ["@common/assets"],
|
||||
};
|
||||
|
||||
export default nextConfig;
|
||||
@@ -1,36 +0,0 @@
|
||||
{
|
||||
"name": "template",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"lint": "next lint",
|
||||
"lint:fsd": "steiger ."
|
||||
},
|
||||
"dependencies": {
|
||||
"@common/assets": "workspace:*",
|
||||
"@common/components": "workspace:*",
|
||||
"@common/network": "workspace:*",
|
||||
"@hookform/resolvers": "^4.1.3",
|
||||
"@tanstack/react-query": "^5.75.5",
|
||||
"@tanstack/react-query-devtools": "^5.75.5",
|
||||
"@tanstack/react-table": "^8.21.2",
|
||||
"axios": "^1.8.1",
|
||||
"dayjs": "^1.11.13",
|
||||
"next": "15.5.18",
|
||||
"react-hook-form": "^7.54.2",
|
||||
"zod": "^3.24.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"eslint": "^9.0.0",
|
||||
"eslint-config-next": "15.3.8",
|
||||
"postcss": "^8.4.49",
|
||||
"prettier": "^3.4.2",
|
||||
"prettier-plugin-tailwindcss": "^0.6.11",
|
||||
"steiger": "^0.5.11",
|
||||
"tailwindcss": "^3.4.14",
|
||||
"typescript": "^5.7.2"
|
||||
}
|
||||
}
|
||||
@@ -1,9 +0,0 @@
|
||||
# 이 폴더는 비워 둡니다 (FSD + Next.js App Router)
|
||||
|
||||
Next.js가 `src/pages`를 **Pages Router**용 `pages` 디렉터리로 인식하지 않도록,
|
||||
프로젝트 루트에 **빈 `pages` 폴더**를 두는 것이 FSD 공식 가이드 권장사항입니다.
|
||||
|
||||
- 실제 페이지(FSD Pages 레이어)는 **`src/pages`**에 있습니다.
|
||||
- Next.js 라우트는 **`app/`** 에서 `src/pages`를 re-export 하는 방식으로 연결됩니다.
|
||||
|
||||
[Feature-Sliced Design - Usage with Next.js (App Router)](https://feature-sliced.design/docs/guides/tech/with-nextjs)
|
||||
@@ -1,8 +0,0 @@
|
||||
/** @type {import('postcss-load-config').Config} */
|
||||
const config = {
|
||||
plugins: {
|
||||
tailwindcss: {},
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
@@ -1,35 +0,0 @@
|
||||
"use client";
|
||||
|
||||
import { useCallback } from "react";
|
||||
import { usePathname, useRouter } from "next/navigation";
|
||||
import { useQueryClient } from "@tanstack/react-query";
|
||||
import { BaseLayout } from "@common/components";
|
||||
import type { MenuItem } from "@/entities/menu";
|
||||
import { PageLayout } from "@/shared/ui/page-layout";
|
||||
|
||||
interface BaseLayoutWrapperProps {
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export function BaseLayoutWrapper({ children }: BaseLayoutWrapperProps) {
|
||||
const router = useRouter();
|
||||
const pathname = usePathname();
|
||||
const queryClient = useQueryClient();
|
||||
|
||||
const handleMenuClick = useCallback(
|
||||
(item: MenuItem) => {
|
||||
router.push(item.urlPath);
|
||||
},
|
||||
[router],
|
||||
);
|
||||
|
||||
return (
|
||||
<BaseLayout
|
||||
queryClient={queryClient}
|
||||
currentPath={pathname ?? ""}
|
||||
handleMenuClick={handleMenuClick}
|
||||
>
|
||||
<PageLayout>{children}</PageLayout>
|
||||
</BaseLayout>
|
||||
);
|
||||
}
|
||||
@@ -1,18 +0,0 @@
|
||||
"use client";
|
||||
|
||||
import { QueryClientProvider } from "@tanstack/react-query";
|
||||
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
|
||||
import { queryClient } from "@/shared/lib";
|
||||
|
||||
interface ProvidersProps {
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export function Providers({ children }: ProvidersProps) {
|
||||
return (
|
||||
<QueryClientProvider client={queryClient}>
|
||||
{children}
|
||||
<ReactQueryDevtools initialIsOpen={false} />
|
||||
</QueryClientProvider>
|
||||
);
|
||||
}
|
||||
@@ -1,15 +0,0 @@
|
||||
@import "@common/assets/styles/base.css";
|
||||
@import "@common/assets/styles/diveicon.css";
|
||||
@import "@common/components/index.css";
|
||||
|
||||
@tailwind base;
|
||||
@tailwind components;
|
||||
@tailwind utilities;
|
||||
|
||||
html,
|
||||
body {
|
||||
color: var(--foreground);
|
||||
background: var(--background);
|
||||
font-family: "Noto Sans KR", sans-serif;
|
||||
font-size: 10px;
|
||||
}
|
||||
@@ -1,114 +0,0 @@
|
||||
# Entities Layer
|
||||
|
||||
**Entities**는 프로젝트가 다루는 실제 비즈니스 개념을 나타내는 레이어입니다. 비즈니스에서 제품을 설명할 때 사용하는 용어들(예: User, Product, Order)이 주로 엔티티가 됩니다.
|
||||
|
||||
## 목적
|
||||
|
||||
- 비즈니스 엔티티의 데이터 모델 및 타입 정의
|
||||
- 엔티티 관련 API 요청 함수 관리
|
||||
- 엔티티의 시각적 표현 제공 (재사용 가능한 UI)
|
||||
- 여러 페이지에서 동일한 외관을 재사용할 수 있도록 지원
|
||||
|
||||
## 구조
|
||||
|
||||
각 엔티티 슬라이스는 다음 세그먼트로 구성됩니다:
|
||||
|
||||
```
|
||||
entities/
|
||||
└── [entity-name]/
|
||||
├── model/ # 데이터 저장소, 검증 스키마, 상태 관리
|
||||
├── api/ # 엔티티 관련 API 요청 함수
|
||||
├── ui/ # 엔티티 시각적 표현 (선택적)
|
||||
├── lib/ # 엔티티 관련 유틸리티 (선택적)
|
||||
├── @x/ # 다른 엔티티로부터의 cross-import용 Public API (선택적)
|
||||
└── index.ts # Public API
|
||||
```
|
||||
|
||||
### 세그먼트 설명
|
||||
|
||||
- **model**: 데이터 모델, 타입 정의, 상태 저장소 (Zustand 등)
|
||||
- **api**: 백엔드 API 호출 함수
|
||||
- **ui**: 엔티티를 표시하는 UI 컴포넌트 (완전한 UI 블록이 아니라 재사용 가능한 표현)
|
||||
- **lib**: 엔티티 관련 유틸리티 함수
|
||||
- **@x**: 다른 엔티티가 이 엔티티를 import할 때 사용하는 명시적 cross-import API
|
||||
- **index.ts**: 슬라이스의 Public API (외부에서 사용할 수 있는 것만 export)
|
||||
|
||||
## 예시
|
||||
|
||||
```typescript
|
||||
// entities/user/model/user.ts
|
||||
export interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
role: 'admin' | 'user';
|
||||
}
|
||||
|
||||
// entities/user/api/get-user.ts
|
||||
import type { User } from '../model/user';
|
||||
|
||||
export async function getUser(id: string): Promise<User> {
|
||||
const response = await fetch(`/api/users/${id}`);
|
||||
return response.json();
|
||||
}
|
||||
|
||||
// entities/user/ui/user-card.tsx
|
||||
import type { User } from '../model/user';
|
||||
|
||||
interface UserCardProps {
|
||||
user: User;
|
||||
onClick?: () => void;
|
||||
}
|
||||
|
||||
export function UserCard({ user, onClick }: UserCardProps) {
|
||||
return (
|
||||
<div onClick={onClick}>
|
||||
<h3>{user.name}</h3>
|
||||
<p>{user.email}</p>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// entities/user/index.ts
|
||||
export { type User } from './model/user';
|
||||
export { getUser } from './api/get-user';
|
||||
export { UserCard } from './ui/user-card';
|
||||
```
|
||||
|
||||
## 엔티티 간 관계
|
||||
|
||||
엔티티가 서로 연결되어 있을 때는 `@x` 표기법을 사용하여 명시적으로 cross-import를 관리하는 것이 권장됩니다:
|
||||
|
||||
```typescript
|
||||
// entities/artist/model/artist.ts
|
||||
import type { Song } from 'entities/song/@x/artist';
|
||||
|
||||
export interface Artist {
|
||||
name: string;
|
||||
songs: Array<Song>;
|
||||
}
|
||||
|
||||
// entities/song/@x/artist.ts
|
||||
export type { Song } from '../model/song';
|
||||
```
|
||||
|
||||
> `@x` 폴더를 사용하면 엔티티 간 연결을 명확하게 만들어 함께 리팩터링이 필요한 코드를 쉽게 찾을 수 있습니다.
|
||||
|
||||
## 레이어 의존성 규칙
|
||||
|
||||
✅ **허용되는 의존성**:
|
||||
- `shared` 레이어의 모듈
|
||||
- 같은 엔티티 슬라이스 내의 다른 세그먼트
|
||||
- 다른 엔티티 슬라이스 (필요한 경우, `@x` 표기법 권장)
|
||||
|
||||
❌ **금지된 의존성**:
|
||||
- `features` 레이어
|
||||
- `widgets` 레이어
|
||||
- `pages` 레이어
|
||||
- `app` 레이어
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **UI 컴포넌트는 완전한 비즈니스 로직을 포함하지 않음**: UI는 주로 props나 slots를 통해 다양한 비즈니스 로직을 연결할 수 있도록 설계
|
||||
2. **엔티티 간 비즈니스 로직은 상위 레이어에**: 엔티티 간 상호작용의 비즈니스 로직은 Features나 Pages 레이어에서 처리
|
||||
3. **데이터 관리에 집중**: 복잡한 비즈니스 로직보다는 데이터 모델, 검증, 저장에 집중
|
||||
@@ -1 +0,0 @@
|
||||
export { type MenuItem } from "./model/types";
|
||||
@@ -1,19 +0,0 @@
|
||||
export interface MenuItem {
|
||||
menuCd: number;
|
||||
menuKornNm: string;
|
||||
menuEngNm: string;
|
||||
parentId: number | null;
|
||||
sortSeq: number;
|
||||
iconNm?: string;
|
||||
children: MenuItem[] | null;
|
||||
levelNo: number;
|
||||
urlPath: string;
|
||||
menuLnkgTypeCd: string;
|
||||
menuLnkgSn: number;
|
||||
menuPath: string;
|
||||
qrcd: string;
|
||||
useYn: string;
|
||||
otptYn: string;
|
||||
newWndwYn: string;
|
||||
requiredUrlPath: boolean;
|
||||
}
|
||||
@@ -1,133 +0,0 @@
|
||||
# Features Layer
|
||||
|
||||
**Features**는 앱의 주요 사용자 상호작용과 기능을 구현하는 레이어입니다. 사용자가 실제로 수행하는 작업들로, 주로 비즈니스 엔티티와 관련이 있습니다.
|
||||
|
||||
## 목적
|
||||
|
||||
- 사용자가 중요하게 생각하는 주요 상호작용 구현
|
||||
- 재사용 가능한 비즈니스 기능 제공
|
||||
- 여러 페이지에서 사용되는 기능의 중복 제거
|
||||
|
||||
## Feature로 만들어야 하는 경우
|
||||
|
||||
> ⚠️ **중요**: 모든 것을 feature로 만들 필요는 없습니다.
|
||||
|
||||
Feature로 만드는 것이 좋은 지표:
|
||||
|
||||
- **여러 페이지에서 재사용됨**: 예를 들어, 여러 에디터가 있고 모두 댓글 기능이 있다면, 댓글은 재사용 가능한 feature입니다
|
||||
- **중요한 비즈니스 기능**: 신규 프로젝트 참여자가 Features 폴더를 보고 앱의 주요 기능을 빠르게 파악할 수 있어야 합니다
|
||||
|
||||
Feature가 너무 많으면 중요한 기능이 묻히므로, 신규 참여자의 경험을 최적화하여 결정하세요.
|
||||
|
||||
## 구조
|
||||
|
||||
각 feature 슬라이스는 다음 세그먼트로 구성됩니다:
|
||||
|
||||
```
|
||||
features/
|
||||
└── [feature-name]/
|
||||
├── ui/ # 상호작용을 수행하는 UI (폼, 버튼 등)
|
||||
├── api/ # 액션 수행에 필요한 API 호출 (선택적)
|
||||
├── model/ # 검증 및 내부 상태 관리 (선택적)
|
||||
├── lib/ # 유틸리티 함수 (선택적)
|
||||
├── config/ # feature flags (선택적)
|
||||
└── index.ts # Public API
|
||||
```
|
||||
|
||||
### 세그먼트 설명
|
||||
|
||||
- **ui**: 사용자 상호작용을 위한 UI 컴포넌트 (폼, 모달, 버튼 등)
|
||||
- **api**: feature 실행에 필요한 API 요청 함수
|
||||
- **model**: 폼 검증, 내부 상태, 비즈니스 로직
|
||||
- **lib**: feature 내부에서만 사용되는 유틸리티
|
||||
- **config**: feature flags, feature별 설정값
|
||||
- **index.ts**: 슬라이스의 Public API (외부에서 사용할 수 있는 것만 export)
|
||||
|
||||
## 예시
|
||||
|
||||
```typescript
|
||||
// features/auth-login/ui/login-form.tsx
|
||||
import { useState } from 'react';
|
||||
import { loginUser } from '../api/login-user';
|
||||
import type { LoginCredentials } from '../model/types';
|
||||
|
||||
export function LoginForm() {
|
||||
const [credentials, setCredentials] = useState<LoginCredentials>({
|
||||
email: '',
|
||||
password: ''
|
||||
});
|
||||
|
||||
const handleSubmit = async (e: React.SubmitEvent) => {
|
||||
e.preventDefault();
|
||||
await loginUser(credentials);
|
||||
};
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit}>
|
||||
<input
|
||||
type="email"
|
||||
value={credentials.email}
|
||||
onChange={(e) => setCredentials({ ...credentials, email: e.target.value })}
|
||||
/>
|
||||
<input
|
||||
type="password"
|
||||
value={credentials.password}
|
||||
onChange={(e) => setCredentials({ ...credentials, password: e.target.value })}
|
||||
/>
|
||||
<button type="submit">로그인</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
|
||||
// features/auth-login/api/login-user.ts
|
||||
import type { LoginCredentials } from '../model/types';
|
||||
|
||||
export async function loginUser(credentials: LoginCredentials) {
|
||||
const response = await fetch('/api/auth/login', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify(credentials),
|
||||
});
|
||||
return response.json();
|
||||
}
|
||||
|
||||
// features/auth-login/model/types.ts
|
||||
export interface LoginCredentials {
|
||||
email: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
// features/auth-login/index.ts
|
||||
export { LoginForm } from './ui/login-form';
|
||||
export { loginUser } from './api/login-user';
|
||||
export type { LoginCredentials } from './model/types';
|
||||
```
|
||||
|
||||
## 레이어 의존성 규칙
|
||||
|
||||
✅ **허용되는 의존성**:
|
||||
|
||||
- `shared` 레이어의 모듈
|
||||
- `entities` 레이어의 모듈
|
||||
- 같은 feature 슬라이스 내의 다른 세그먼트
|
||||
|
||||
❌ **금지된 의존성**:
|
||||
|
||||
- 다른 `features` 슬라이스 (feature 간 직접 의존 금지)
|
||||
- `widgets` 레이어
|
||||
- `pages` 레이어
|
||||
- `app` 레이어
|
||||
|
||||
> 💡 **팁**: 여러 features가 공통 기능을 필요로 한다면, 그 기능을 `shared` 레이어로 이동시키거나 `entities` 레이어에서 관리하세요.
|
||||
|
||||
## 명명 규칙
|
||||
|
||||
- 소문자와 대시 사용: `auth-login`, `post-create`, `comment-edit`
|
||||
- 동사 형태 권장: 사용자 액션을 나타내는 이름 사용
|
||||
- 명확하고 구체적으로: 기능의 목적이 명확하게 드러나도록
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **하나의 기능에만 집중**: 각 feature는 단일 사용자 시나리오를 구현해야 합니다
|
||||
2. **재사용성 고려**: 여러 페이지에서 사용될 수 있도록 설계
|
||||
3. **독립성 유지**: 다른 features에 의존하지 않고 독립적으로 작동
|
||||
4. **적절한 추상화**: 너무 많은 feature를 만들지 말고, 중요한 기능 위주로 구성
|
||||
@@ -1 +0,0 @@
|
||||
export { MainPage } from "./ui/main-page";
|
||||
@@ -1,9 +0,0 @@
|
||||
"use client";
|
||||
|
||||
export function MainPage() {
|
||||
return (
|
||||
<div className="flex h-full flex-col items-center justify-center py-10">
|
||||
<h1 className="mb-4 text-3xl font-bold">Home</h1>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,149 +0,0 @@
|
||||
# Shared Layer
|
||||
|
||||
**Shared**는 애플리케이션의 기반을 형성하는 레이어입니다. 외부 세계(백엔드, 서드파티 라이브러리, 환경)와의 연결을 생성하고, 높은 응집력을 가진 자체 라이브러리를 정의하는 곳입니다.
|
||||
|
||||
## 목적
|
||||
|
||||
- 외부 시스템 및 라이브러리와의 통합
|
||||
- 프로젝트 전체에서 사용되는 공통 코드 제공
|
||||
- 비즈니스 로직이 없는 재사용 가능한 유틸리티 및 UI 제공
|
||||
- 글로벌 설정 및 환경 변수 관리
|
||||
|
||||
## 특징
|
||||
|
||||
- **슬라이스 없음**: Shared 레이어는 비즈니스 도메인이 없으므로 슬라이스로 나뉘지 않습니다
|
||||
- **세그먼트 구성**: 기술적 목적에 따라 세그먼트로 직접 구성됩니다
|
||||
- **자유로운 import**: Shared 내의 모든 파일은 서로를 참조하고 import할 수 있습니다
|
||||
|
||||
## 구조
|
||||
|
||||
```
|
||||
shared/
|
||||
├── ui/ # 애플리케이션 UI Kit
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── modal/
|
||||
│ └── index.ts
|
||||
├── api/ # API 클라이언트 및 백엔드 엔드포인트 함수
|
||||
│ ├── client.ts
|
||||
│ └── index.ts
|
||||
├── lib/ # 내부 라이브러리 모음
|
||||
│ ├── dates/ # 날짜 관련 유틸리티
|
||||
│ ├── colors/ # 색상 관련 유틸리티
|
||||
│ ├── text/ # 텍스트 처리 유틸리티
|
||||
│ └── index.ts
|
||||
├── config/ # 환경 변수, 글로벌 feature flags
|
||||
│ ├── env.ts
|
||||
│ └── index.ts
|
||||
├── types/ # 공통 타입 정의
|
||||
│ └── index.ts
|
||||
├── i18n/ # 번역 설정, 글로벌 번역 문자열
|
||||
│ └── index.ts
|
||||
└── routes/ # 라우트 상수 또는 패턴
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## 세그먼트 설명
|
||||
|
||||
### 📁 ui
|
||||
애플리케이션의 UI Kit로, 비즈니스 로직을 포함하지 않는 재사용 가능한 UI 컴포넌트들입니다.
|
||||
|
||||
- Button, Input, Modal 같은 기본 컴포넌트
|
||||
- 비즈니스 로직은 없지만 UI 로직은 포함 가능 (예: Autocomplete, SearchBar)
|
||||
- 비즈니스 테마 컴포넌트도 허용 (예: 회사 로고, 페이지 레이아웃)
|
||||
|
||||
### 📁 api
|
||||
API 클라이언트 및 특정 백엔드 엔드포인트 요청 함수입니다.
|
||||
|
||||
- HTTP 클라이언트 설정 (Axios, Fetch 등)
|
||||
- 인증 인터셉터
|
||||
- 공통 에러 핸들링
|
||||
|
||||
### 📁 lib
|
||||
내부 라이브러리 모음으로, 각 라이브러리는 **하나의 관심사**에 집중해야 합니다.
|
||||
|
||||
> ⚠️ **중요**: `helpers`나 `utils` 폴더처럼 덤프 폴더로 만들지 마세요. 각 라이브러리는 명확한 초점 영역(예: dates, colors, text)을 가져야 하며, README로 문서화해야 합니다.
|
||||
|
||||
### 📁 config
|
||||
환경 변수, 글로벌 feature flags 및 앱 전체 설정입니다.
|
||||
|
||||
### 📁 types
|
||||
프로젝트 전체에서 사용되는 공통 타입 정의입니다.
|
||||
|
||||
### 📁 i18n
|
||||
번역 설정 코드 및 글로벌 번역 문자열입니다.
|
||||
|
||||
### 📁 routes
|
||||
라우트 상수 또는 라우트 매칭 패턴입니다.
|
||||
|
||||
## 예시
|
||||
|
||||
```typescript
|
||||
// shared/ui/button/button.tsx
|
||||
interface ButtonProps {
|
||||
children: React.ReactNode;
|
||||
variant?: 'primary' | 'secondary';
|
||||
onClick?: () => void;
|
||||
}
|
||||
|
||||
export function Button({ children, variant = 'primary', onClick }: ButtonProps) {
|
||||
return (
|
||||
<button
|
||||
className={variant === 'primary' ? 'bg-blue-500' : 'bg-gray-500'}
|
||||
onClick={onClick}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
);
|
||||
}
|
||||
|
||||
// shared/api/client.ts
|
||||
import axios from 'axios';
|
||||
|
||||
export const apiClient = axios.create({
|
||||
baseURL: process.env.NEXT_PUBLIC_API_URL,
|
||||
timeout: 10000,
|
||||
});
|
||||
|
||||
// shared/lib/dates/format-date.ts
|
||||
import dayjs from 'dayjs';
|
||||
|
||||
export function formatDate(date: Date, format: string = 'YYYY-MM-DD'): string {
|
||||
return dayjs(date).format(format);
|
||||
}
|
||||
|
||||
// shared/config/env.ts
|
||||
export const ENV = {
|
||||
apiUrl: process.env.NEXT_PUBLIC_API_URL!,
|
||||
isDev: process.env.NODE_ENV === 'development',
|
||||
} as const;
|
||||
```
|
||||
|
||||
## 레이어 의존성 규칙
|
||||
|
||||
✅ **허용되는 의존성**:
|
||||
- 같은 `shared` 레이어 내의 다른 세그먼트 (자유로운 cross-import)
|
||||
- 외부 라이브러리 및 패키지
|
||||
|
||||
❌ **금지된 의존성**:
|
||||
- `entities` 레이어
|
||||
- `features` 레이어
|
||||
- `widgets` 레이어
|
||||
- `pages` 레이어
|
||||
- `app` 레이어
|
||||
|
||||
> 💡 **원칙**: Shared는 가장 낮은 레이어이므로 상위 레이어에 의존하지 않습니다.
|
||||
|
||||
## 세그먼트 명명 규칙
|
||||
|
||||
세그먼트 이름은 **내용의 목적**을 설명해야 하며, **본질**을 설명하면 안 됩니다.
|
||||
|
||||
❌ **나쁜 예시**: `components`, `hooks`, `types` (본질을 설명)
|
||||
✅ **좋은 예시**: `ui`, `api`, `lib/dates`, `config` (목적을 설명)
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **비즈니스 로직 없음**: Shared는 순수한 기술적 코드만 포함
|
||||
2. **높은 재사용성**: 앱 전체에서 사용될 수 있어야 함
|
||||
3. **명확한 라이브러리 구조**: `lib` 내부는 관심사별로 명확하게 분리
|
||||
4. **문서화**: 각 라이브러리는 README로 사용법과 목적을 문서화
|
||||
@@ -1,9 +0,0 @@
|
||||
import { Client } from "@common/network";
|
||||
import { PROXY_HOST, SITE_ID } from "@/shared/config/env";
|
||||
|
||||
const BASE_URL = `${PROXY_HOST}/server`;
|
||||
|
||||
export const apiClient = Client.getInstance({
|
||||
baseURL: BASE_URL,
|
||||
siteId: SITE_ID,
|
||||
});
|
||||
@@ -1 +0,0 @@
|
||||
export { apiClient } from "./client";
|
||||
@@ -1,8 +0,0 @@
|
||||
export const PORT = process.env.NEXT_PUBLIC_PORT || "3000";
|
||||
export const PROXY_HOST = process.env.NEXT_PUBLIC_PROXY_HOST || `http://localhost:${PORT}`;
|
||||
export const SITE_ID = process.env.NEXT_PUBLIC_SITE_ID || "AS";
|
||||
export const SERVER_API_URL = process.env.SERVER_API_URL;
|
||||
export const CLAIM_NAME = process.env.NEXT_PUBLIC_CLAIM_NAME || "Authorization";
|
||||
export const ACCESS_TOKEN = process.env.NEXT_PUBLIC_ACCESS_TOKEN || "access-token";
|
||||
export const REFRESH_TOKEN = process.env.NEXT_PUBLIC_REFRESH_TOKEN || "refresh-token";
|
||||
export const AUTH_USER_ID = process.env.NEXT_PUBLIC_AUTH_USER_ID || "token-id";
|
||||
@@ -1 +0,0 @@
|
||||
export * from "./env";
|
||||
@@ -1,12 +0,0 @@
|
||||
import dayjs from "dayjs";
|
||||
import "dayjs/locale/ko";
|
||||
import utc from "dayjs/plugin/utc";
|
||||
import timezone from "dayjs/plugin/timezone";
|
||||
import relativeTime from "dayjs/plugin/relativeTime";
|
||||
|
||||
dayjs.extend(utc);
|
||||
dayjs.extend(timezone);
|
||||
dayjs.extend(relativeTime);
|
||||
dayjs.locale("ko");
|
||||
|
||||
export { dayjs };
|
||||
@@ -1,2 +0,0 @@
|
||||
export { queryClient } from "./query-client";
|
||||
export { dayjs } from "./dayjs";
|
||||
@@ -1,11 +0,0 @@
|
||||
import { QueryClient } from "@tanstack/react-query";
|
||||
|
||||
export const queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: {
|
||||
retry: 1,
|
||||
refetchOnWindowFocus: false,
|
||||
staleTime: 60 * 1000,
|
||||
},
|
||||
},
|
||||
});
|
||||
@@ -1,29 +0,0 @@
|
||||
export interface BaseEntity {
|
||||
id: string;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
export interface PaginationParams {
|
||||
page: number;
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export interface PaginationResponse<T> {
|
||||
data: T[];
|
||||
total: number;
|
||||
page: number;
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export interface ApiResponse<T> {
|
||||
success: boolean;
|
||||
data: T;
|
||||
message?: string;
|
||||
}
|
||||
|
||||
export interface ApiError {
|
||||
message: string;
|
||||
code?: string;
|
||||
status?: number;
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
export { PageLayout } from "./page-layout";
|
||||
@@ -1,35 +0,0 @@
|
||||
"use client";
|
||||
|
||||
import { PageTitle } from "@common/components";
|
||||
|
||||
const mockCurrentMenuInfo = {
|
||||
menuCd: 0,
|
||||
menuKornNm: "메인",
|
||||
menuEngNm: "Main",
|
||||
parentId: null,
|
||||
sortSeq: 0,
|
||||
children: null,
|
||||
levelNo: 0,
|
||||
urlPath: "/",
|
||||
menuLnkgTypeCd: "",
|
||||
menuLnkgSn: 0,
|
||||
menuPath: "메인",
|
||||
qrcd: "",
|
||||
useYn: "Y",
|
||||
otptYn: "Y",
|
||||
newWndwYn: "N",
|
||||
requiredUrlPath: false,
|
||||
};
|
||||
|
||||
function PageLayout({ children }: { children: React.ReactNode }) {
|
||||
const menuPaths = mockCurrentMenuInfo.menuPath.split(">").map((path) => path.trim());
|
||||
|
||||
return (
|
||||
<div className="bg-container h-auto min-h-full pb-2">
|
||||
<PageTitle title={mockCurrentMenuInfo.menuKornNm} menuPaths={menuPaths} />
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export { PageLayout };
|
||||
@@ -1,135 +0,0 @@
|
||||
# Widgets Layer
|
||||
|
||||
**Widgets**는 큰 규모의 독립적인 UI 블록을 위한 레이어입니다. 여러 features와 entities를 조합하여 완전한 기능을 제공하는 복합 컴포넌트를 담습니다.
|
||||
|
||||
## 목적
|
||||
|
||||
- 큰 규모의 독립적인 UI 블록 구성
|
||||
- 여러 features와 entities를 하나의 응집력 있는 UI로 결합
|
||||
- 여러 페이지에서 재사용되는 복잡한 UI 제공
|
||||
- 페이지 레벨 레이아웃 및 섹션 관리
|
||||
|
||||
## Widget으로 만들어야 하는 경우
|
||||
|
||||
Widget은 다음 조건에 해당할 때 사용하세요:
|
||||
|
||||
✅ **Widget으로 만들기 좋은 경우**:
|
||||
- 여러 페이지에서 재사용되는 큰 UI 블록
|
||||
- 페이지에 여러 개의 큰 독립적 블록이 있고, 이것이 그 중 하나인 경우
|
||||
- 페이지 레벨 레이아웃 컴포넌트 (nested routing 시스템 사용 시)
|
||||
|
||||
❌ **Widget으로 만들지 말아야 하는 경우**:
|
||||
- UI 블록이 페이지의 대부분을 차지하고 재사용되지 않는 경우 → 페이지 슬라이스 내부에 직접 배치
|
||||
- 작은 재사용 컴포넌트 → `shared/ui`에 배치
|
||||
|
||||
## 구조
|
||||
|
||||
각 widget 슬라이스는 다음 세그먼트로 구성됩니다:
|
||||
|
||||
```
|
||||
widgets/
|
||||
└── [widget-name]/
|
||||
├── ui/ # 위젯의 메인 UI 컴포넌트
|
||||
├── model/ # 위젯 내부 상태 관리 (선택적)
|
||||
├── api/ # 위젯 전용 API 호출 (선택적)
|
||||
├── lib/ # 위젯 내부 유틸리티 (선택적)
|
||||
└── index.ts # Public API
|
||||
```
|
||||
|
||||
### 세그먼트 설명
|
||||
|
||||
- **ui**: 여러 features와 entities를 조합한 위젯 UI
|
||||
- **model**: 위젯 내부 상태 및 로직 (선택적)
|
||||
- **api**: 위젯이 필요로 하는 데이터 fetching (선택적)
|
||||
- **lib**: 위젯 내부에서만 사용되는 헬퍼 함수 (선택적)
|
||||
- **index.ts**: 슬라이스의 Public API (외부에서 사용할 수 있는 것만 export)
|
||||
|
||||
## 예시
|
||||
|
||||
```typescript
|
||||
// widgets/header/ui/header.tsx
|
||||
import { Logo } from 'shared/ui/logo';
|
||||
import { Navigation } from 'shared/ui/navigation';
|
||||
import { UserMenu } from 'features/user-menu';
|
||||
import { NotificationBell } from 'features/notifications';
|
||||
|
||||
export function Header() {
|
||||
return (
|
||||
<header>
|
||||
<Logo />
|
||||
<Navigation />
|
||||
<NotificationBell />
|
||||
<UserMenu />
|
||||
</header>
|
||||
);
|
||||
}
|
||||
|
||||
// widgets/product-list/ui/product-list.tsx
|
||||
import { useProducts } from '../api/use-products';
|
||||
import { ProductCard } from 'entities/product';
|
||||
import { AddToCartButton } from 'features/cart-add-item';
|
||||
|
||||
export function ProductList() {
|
||||
const { data: products, isLoading } = useProducts();
|
||||
|
||||
if (isLoading) return <div>로딩 중...</div>;
|
||||
|
||||
return (
|
||||
<div>
|
||||
{products.map((product) => (
|
||||
<div key={product.id}>
|
||||
<ProductCard product={product} />
|
||||
<AddToCartButton productId={product.id} />
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// widgets/product-list/api/use-products.ts
|
||||
import { useQuery } from '@tanstack/react-query';
|
||||
import { getProducts } from 'entities/product';
|
||||
|
||||
export function useProducts() {
|
||||
return useQuery({
|
||||
queryKey: ['products'],
|
||||
queryFn: getProducts,
|
||||
});
|
||||
}
|
||||
|
||||
// widgets/product-list/index.ts
|
||||
export { ProductList } from './ui/product-list';
|
||||
```
|
||||
|
||||
## 레이어 의존성 규칙
|
||||
|
||||
✅ **허용되는 의존성**:
|
||||
- `shared` 레이어의 모듈
|
||||
- `entities` 레이어의 모듈
|
||||
- `features` 레이어의 모듈
|
||||
- 같은 widget 슬라이스 내의 다른 세그먼트
|
||||
|
||||
❌ **금지된 의존성**:
|
||||
- 다른 `widgets` 슬라이스 (widget 간 직접 의존 금지)
|
||||
- `pages` 레이어
|
||||
- `app` 레이어
|
||||
|
||||
## 명명 규칙
|
||||
|
||||
- 소문자와 대시 사용: `header`, `sidebar`, `product-list`
|
||||
- 명사 형태 권장: UI 블록의 성격을 나타내는 이름 사용
|
||||
- 구체적으로: 위젯의 역할이 명확하게 드러나도록
|
||||
|
||||
## Nested Routing 사용 시
|
||||
|
||||
Remix 같은 nested routing 시스템을 사용한다면:
|
||||
- Widgets 레이어를 flat routing의 Pages 레이어처럼 사용 가능
|
||||
- 완전한 라우터 블록 생성 (데이터 fetching, loading states, error boundaries 포함)
|
||||
- 페이지 레이아웃을 이 레이어에 저장 가능
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **독립성 유지**: 각 위젯은 독립적으로 작동 가능해야 합니다
|
||||
2. **적절한 크기**: 너무 작은 컴포넌트는 `shared/ui`에, 재사용되지 않으면 `pages`에 배치
|
||||
3. **응집력**: 관련된 features와 entities를 의미 있게 조합
|
||||
4. **재사용 최적화**: 여러 페이지에서 동일한 방식으로 사용될 수 있도록 설계
|
||||
@@ -1,26 +0,0 @@
|
||||
import type { Config } from "tailwindcss";
|
||||
import presetConfig from "../../tailwind.config.preset";
|
||||
|
||||
const config: Config = {
|
||||
presets: [presetConfig],
|
||||
content: [
|
||||
"./pages/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
"./shared/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
"./entities/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
"./features/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
"./widgets/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
"./app/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
"../../packages/common/components/dist/**/*.{js,ts,jsx,tsx,mdx}",
|
||||
],
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
background: "var(--background)",
|
||||
foreground: "var(--foreground)",
|
||||
},
|
||||
},
|
||||
},
|
||||
plugins: [],
|
||||
};
|
||||
|
||||
export default config;
|
||||
@@ -1,33 +0,0 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2017",
|
||||
"lib": ["dom", "dom.iterable", "esnext"],
|
||||
"allowJs": true,
|
||||
"skipLibCheck": true,
|
||||
"strict": true,
|
||||
"noEmit": true,
|
||||
"esModuleInterop": true,
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"jsx": "preserve",
|
||||
"incremental": true,
|
||||
"plugins": [
|
||||
{
|
||||
"name": "next"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"@/*": ["./src/*"]
|
||||
}
|
||||
},
|
||||
"include": [
|
||||
"next-env.d.ts",
|
||||
"**/*.ts",
|
||||
"**/*.tsx",
|
||||
".next/types/**/*.ts",
|
||||
"../../packages/common/types/**/*.d.ts"
|
||||
],
|
||||
"exclude": ["node_modules", ".next", "dist", "coverage", "storybook-static", "public"]
|
||||
}
|
||||
@@ -1,3 +0,0 @@
|
||||
{
|
||||
"extends": "next/core-web-vitals"
|
||||
}
|
||||
@@ -1,36 +0,0 @@
|
||||
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
|
||||
|
||||
# dependencies
|
||||
/node_modules
|
||||
/.pnp
|
||||
.pnp.js
|
||||
.yarn/install-state.gz
|
||||
|
||||
# testing
|
||||
/coverage
|
||||
|
||||
# next.js
|
||||
/.next/
|
||||
/out/
|
||||
|
||||
# production
|
||||
/build
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
|
||||
# debug
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# local env files
|
||||
.env.*
|
||||
|
||||
# vercel
|
||||
.vercel
|
||||
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
@@ -1,8 +0,0 @@
|
||||
{
|
||||
"semi": true,
|
||||
"trailingComma": "all",
|
||||
"singleQuote": false,
|
||||
"printWidth": 100,
|
||||
"tabWidth": 2,
|
||||
"plugins": ["prettier-plugin-tailwindcss"]
|
||||
}
|
||||
@@ -1,187 +0,0 @@
|
||||
# Template Application
|
||||
|
||||
Next.js 애플리케이션 with FSD(Feature Sliced Design) 아키텍처
|
||||
|
||||
## 기술 스택
|
||||
|
||||
- **프레임워크**: Next.js 15 + TypeScript
|
||||
- **스타일링**: Tailwind CSS
|
||||
- **상태관리**: Zustand
|
||||
- **데이터 페칭**: TanStack Query (React Query)
|
||||
- **폼 관리**: React Hook Form + Zod
|
||||
- **테이블**: TanStack Table
|
||||
- **HTTP 클라이언트**: Axios
|
||||
- **날짜 처리**: Day.js
|
||||
|
||||
## 프로젝트 구조 (FSD + Next.js App Router)
|
||||
|
||||
이 프로젝트는 **Feature-Sliced Design v2.1**과 **FSD 공식 Next.js 가이드**에 맞춰 구성되어 있습니다. Next.js `app/`은 라우트만 담당하고, 실제 레이어는 `src/` 아래에 있습니다.
|
||||
|
||||
```
|
||||
_template/
|
||||
├── app/ # Next.js App Router (루트) — 라우트·레이아웃 진입점만
|
||||
│ ├── layout.tsx # 루트 레이아웃 (src/app에서 providers, styles import)
|
||||
│ └── (with-base-layout)/
|
||||
│ ├── layout.tsx # BaseLayout 래퍼 (src/app/layouts에서 import)
|
||||
│ └── page.tsx # re-export: export { MainPage as default } from '@/pages/home'
|
||||
│
|
||||
├── pages/ # 빈 폴더 + README (Next.js가 src/pages를 Pages Router로 쓰지 않도록)
|
||||
│ └── README.md
|
||||
│
|
||||
└── src/ # FSD 레이어 (실제 코드)
|
||||
├── app/ # App 레이어 (슬라이스 없음, 세그먼트만)
|
||||
│ ├── providers/ # 전역 Providers (QueryClient 등)
|
||||
│ ├── styles/ # 글로벌 스타일 (globals.css)
|
||||
│ └── layouts/ # 공통 레이아웃 컴포넌트 (BaseLayoutWrapper)
|
||||
│
|
||||
├── pages/ # Pages 레이어 (페이지 슬라이스)
|
||||
│ └── home/
|
||||
│ ├── ui/
|
||||
│ └── index.ts # Public API
|
||||
│
|
||||
├── widgets/ # Widgets 레이어
|
||||
├── features/ # Features 레이어
|
||||
├── entities/ # Entities 레이어
|
||||
└── shared/ # Shared 레이어
|
||||
├── ui/
|
||||
├── api/
|
||||
├── lib/
|
||||
└── config/
|
||||
```
|
||||
|
||||
### 계층 구조 이해하기
|
||||
|
||||
FSD는 **3단계 계층**으로 구성됩니다:
|
||||
|
||||
1. **Layers (레이어)**: 책임과 의존성에 따른 수평적 분리 (app, pages, widgets, features, entities, shared)
|
||||
2. **Slices (슬라이스)**: 비즈니스 도메인에 따른 수직적 분리 (user, product, auth-login 등)
|
||||
3. **Segments (세그먼트)**: 기술적 목적에 따른 분리 (ui, api, model, lib 등)
|
||||
|
||||
> 📚 각 레이어의 자세한 설명은 해당 폴더의 README.md를 참고하세요.
|
||||
|
||||
## FSD 레이어 설명
|
||||
|
||||
FSD는 계층적 아키텍처로, 각 레이어는 책임의 범위와 의존성의 정도에 따라 구분됩니다. 7개의 표준화된 레이어가 있으며, 프로젝트에 필요한 레이어만 사용하면 됩니다.
|
||||
|
||||
### 레이어 계층 구조 (위에서 아래로)
|
||||
|
||||
```
|
||||
app/ ↑ 가장 높은 책임, 가장 많은 의존성
|
||||
pages/ |
|
||||
widgets/ |
|
||||
features/ |
|
||||
entities/ |
|
||||
shared/ ↓ 가장 낮은 책임, 의존성 없음
|
||||
```
|
||||
|
||||
### 1. App
|
||||
- **목적**: 앱 전체에 영향을 주는 기술적/비즈니스적 사항
|
||||
- **내용**: Context providers, 글로벌 스타일, 스토어 설정, 라우터 설정, 애널리틱스
|
||||
- **특징**: 슬라이스가 없고 세그먼트로만 구성
|
||||
- **의존성**: 모든 하위 레이어 사용 가능
|
||||
|
||||
### 2. Pages (src/pages)
|
||||
- **목적**: 웹사이트나 애플리케이션을 구성하는 페이지/화면
|
||||
- **내용**: 페이지 UI, 로딩 상태, 에러 바운더리, 데이터 fetching
|
||||
- **특징**: 한 페이지당 한 슬라이스 (유사한 페이지는 그룹화 가능). Next.js `app/`의 route 파일에서 re-export
|
||||
- **의존성**: `widgets`, `features`, `entities`, `shared` 사용 가능
|
||||
|
||||
> 💡 **FSD v2.1 권장사항**: "pages-first" 접근 방식을 따라, 재사용되지 않는 큰 UI 블록과 비즈니스 로직은 페이지 슬라이스에 유지하세요.
|
||||
|
||||
### 3. Widgets
|
||||
- **목적**: 큰 규모의 독립적인 UI 블록
|
||||
- **내용**: 여러 features와 entities를 조합한 복합 UI
|
||||
- **사용 시기**: 여러 페이지에서 재사용되거나, 페이지에 여러 개의 큰 독립적 블록이 있을 때
|
||||
- **의존성**: `features`, `entities`, `shared` 사용 가능 (다른 `widgets` 불가)
|
||||
|
||||
### 4. Features
|
||||
- **목적**: 사용자가 수행하는 주요 상호작용과 비즈니스 기능
|
||||
- **내용**: 사용자 시나리오 (예: 로그인, 상품 검색, 댓글 작성)
|
||||
- **사용 시기**: 여러 페이지에서 재사용되는 기능
|
||||
- **의존성**: `entities`, `shared` 사용 가능 (다른 `features` 불가)
|
||||
|
||||
### 5. Entities
|
||||
- **목적**: 비즈니스가 다루는 실제 개념 (User, Product, Order 등)
|
||||
- **내용**: 데이터 모델, 타입, API 요청, 엔티티의 시각적 표현
|
||||
- **특징**: 비즈니스 용어로 명명
|
||||
- **의존성**: 다른 `entities`, `shared` 사용 가능
|
||||
|
||||
### 6. Shared
|
||||
- **목적**: 애플리케이션의 기반 제공
|
||||
- **내용**: API 클라이언트, UI Kit, 유틸리티 라이브러리, 글로벌 설정
|
||||
- **특징**: 비즈니스 로직 없음, 슬라이스가 없고 세그먼트로만 구성
|
||||
- **의존성**: 외부 라이브러리만 사용 가능 (다른 레이어 불가)
|
||||
|
||||
## 시작하기
|
||||
|
||||
```bash
|
||||
# 의존성 설치
|
||||
pnpm install
|
||||
|
||||
# 개발 서버 실행
|
||||
pnpm run dev
|
||||
|
||||
# 프로덕션 빌드
|
||||
pnpm run build
|
||||
|
||||
# 프로덕션 서버 실행
|
||||
pnpm start
|
||||
```
|
||||
|
||||
## 환경 변수
|
||||
|
||||
`.env.local` 파일 생성:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_API_URL=http://localhost:3000/api
|
||||
```
|
||||
|
||||
## FSD 핵심 규칙
|
||||
|
||||
### 1. Import 규칙
|
||||
|
||||
> **슬라이스 내의 모듈(파일)은 오직 하위 레이어에 있는 슬라이스만 import할 수 있습니다.**
|
||||
|
||||
```typescript
|
||||
// ✅ 올바른 import (하위 레이어)
|
||||
// features/auth-login/ui/form.tsx
|
||||
import { User } from "entities/user";
|
||||
import { Button } from "shared/ui/button";
|
||||
|
||||
// ❌ 잘못된 import (같은 레이어)
|
||||
// features/auth-login/ui/form.tsx
|
||||
import { PostForm } from "features/post-create"; // 금지!
|
||||
|
||||
// ❌ 잘못된 import (상위 레이어)
|
||||
// features/auth-login/ui/form.tsx
|
||||
import { Header } from "widgets/header"; // 금지!
|
||||
```
|
||||
|
||||
### 2. Public API 규칙
|
||||
|
||||
> **슬라이스 외부에서는 Public API(index.ts)를 통해서만 접근해야 합니다.**
|
||||
|
||||
```typescript
|
||||
// ✅ 올바른 import (Public API 사용)
|
||||
import { LoginForm } from "features/auth-login";
|
||||
|
||||
// ❌ 잘못된 import (내부 구조 직접 접근)
|
||||
import { LoginForm } from "features/auth-login/ui/login-form";
|
||||
```
|
||||
|
||||
**Public API 작성 시 주의사항**:
|
||||
- 와일드카드 re-export(`export * from`) 사용 지양
|
||||
- 필요한 것만 명시적으로 export
|
||||
- 슬라이스의 인터페이스를 명확하게 표현
|
||||
|
||||
```typescript
|
||||
// ❌ 나쁜 예시
|
||||
export * from "./ui/Comment";
|
||||
export * from "./model/comments";
|
||||
|
||||
// ✅ 좋은 예시
|
||||
export { Comment } from "./ui/comment";
|
||||
export { CommentForm } from "./ui/comment-form";
|
||||
export { useComments } from "./model/use-comments";
|
||||
export type { Comment, CommentFormData } from "./model/types";
|
||||
```
|
||||
@@ -1,13 +0,0 @@
|
||||
import "@/app/styles/globals.css";
|
||||
|
||||
export const metadata = {
|
||||
title: "유역하수도통합플랫폼 Hasuon",
|
||||
};
|
||||
|
||||
export default function AuthLayout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="ko">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
export { ApprovalLineManagementPage as default } from "@/pages/approval-line-management";
|
||||
@@ -1 +0,0 @@
|
||||
export { ChecklistManagementPage as default } from "@/pages/checklist-management";
|
||||
@@ -1 +0,0 @@
|
||||
export { CodeManagementPage as default } from "@/pages/code-management";
|
||||
@@ -1,3 +0,0 @@
|
||||
import { DashboardPage } from "@/pages/dashboard/ui/dashboard-page";
|
||||
|
||||
export default DashboardPage;
|
||||
@@ -1,10 +0,0 @@
|
||||
import { DesignEditPage } from "@/pages/design-cnstn";
|
||||
|
||||
interface PageProps {
|
||||
params: Promise<{ id: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params }: PageProps) {
|
||||
const { id } = await params;
|
||||
return <DesignEditPage id={id} />;
|
||||
}
|
||||
@@ -1,10 +0,0 @@
|
||||
import { DesignDetailGate } from "@/pages/design-cnstn";
|
||||
|
||||
interface PageProps {
|
||||
params: Promise<{ id: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params }: PageProps) {
|
||||
const { id } = await params;
|
||||
return <DesignDetailGate id={id} />;
|
||||
}
|
||||
@@ -1,11 +0,0 @@
|
||||
import { Suspense } from "react";
|
||||
|
||||
import { DesignListPage } from "@/pages/design-cnstn";
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<Suspense>
|
||||
<DesignListPage />
|
||||
</Suspense>
|
||||
);
|
||||
}
|
||||
@@ -1,27 +0,0 @@
|
||||
import { DesignRegistPage } from "@/pages/design-cnstn";
|
||||
import { parseTaskSeComCdFromApi } from "@/pages/design-cnstn/lib/design-cnstn-regist-schema";
|
||||
|
||||
interface PageProps {
|
||||
searchParams: Promise<{
|
||||
taskSeComCd?: string;
|
||||
admdstCd?: string;
|
||||
sido?: string;
|
||||
gugun?: string;
|
||||
}>;
|
||||
}
|
||||
|
||||
export default async function Page({ searchParams }: PageProps) {
|
||||
const params = await searchParams;
|
||||
const taskSeComCd = parseTaskSeComCdFromApi(params.taskSeComCd);
|
||||
|
||||
return (
|
||||
<DesignRegistPage
|
||||
defaults={{
|
||||
taskSeComCd: taskSeComCd.length ? taskSeComCd : undefined,
|
||||
admdstCd: params.admdstCd,
|
||||
sido: params.sido,
|
||||
gugun: params.gugun,
|
||||
}}
|
||||
/>
|
||||
);
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
export { EsntlAtchFileMngPage as default } from "@/pages/esntl-atch-file-mng";
|
||||
@@ -1,10 +0,0 @@
|
||||
import { FnrsEditPage } from "@/pages/fnrs-cnsltn";
|
||||
|
||||
interface PageProps {
|
||||
params: Promise<{ id: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params }: PageProps) {
|
||||
const { id } = await params;
|
||||
return <FnrsEditPage id={id} />;
|
||||
}
|
||||
@@ -1,10 +0,0 @@
|
||||
import { FnrsDetailGate } from "@/pages/fnrs-cnsltn";
|
||||
|
||||
interface PageProps {
|
||||
params: Promise<{ id: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params }: PageProps) {
|
||||
const { id } = await params;
|
||||
return <FnrsDetailGate id={id} />;
|
||||
}
|
||||
@@ -1,11 +0,0 @@
|
||||
import { Suspense } from "react";
|
||||
|
||||
import { FnrsListPage } from "@/pages/fnrs-cnsltn";
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<Suspense>
|
||||
<FnrsListPage />
|
||||
</Suspense>
|
||||
);
|
||||
}
|
||||
@@ -1,27 +0,0 @@
|
||||
import { FnrsRegistPage } from "@/pages/fnrs-cnsltn";
|
||||
import { parseTaskSeComCdFromApi } from "@/pages/fnrs-cnsltn/lib/fnrs-cnsltn-regist-schema";
|
||||
|
||||
interface PageProps {
|
||||
searchParams: Promise<{
|
||||
taskSeComCd?: string;
|
||||
admdstCd?: string;
|
||||
sido?: string;
|
||||
gugun?: string;
|
||||
}>;
|
||||
}
|
||||
|
||||
export default async function Page({ searchParams }: PageProps) {
|
||||
const params = await searchParams;
|
||||
const taskSeComCd = parseTaskSeComCdFromApi(params.taskSeComCd);
|
||||
|
||||
return (
|
||||
<FnrsRegistPage
|
||||
defaults={{
|
||||
taskSeComCd: taskSeComCd.length ? taskSeComCd : undefined,
|
||||
admdstCd: params.admdstCd,
|
||||
sido: params.sido,
|
||||
gugun: params.gugun,
|
||||
}}
|
||||
/>
|
||||
);
|
||||
}
|
||||
@@ -1,10 +0,0 @@
|
||||
import { InstlEditPage } from "@/pages/instl-sncn";
|
||||
|
||||
interface InstlSncnEditRouteProps {
|
||||
params: Promise<{ id: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params }: InstlSncnEditRouteProps) {
|
||||
const { id } = await params;
|
||||
return <InstlEditPage id={id} />;
|
||||
}
|
||||
@@ -1,6 +0,0 @@
|
||||
import { InstlSncnDetailGate } from "@/pages/instl-sncn";
|
||||
|
||||
export default async function InstlSncnDetailPage({ params }: { params: Promise<{ id: string }> }) {
|
||||
const { id } = await params;
|
||||
return <InstlSncnDetailGate id={id} />;
|
||||
}
|
||||
@@ -1,11 +0,0 @@
|
||||
import { Suspense } from "react";
|
||||
|
||||
import { InstlListPage } from "@/pages/instl-sncn";
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<Suspense>
|
||||
<InstlListPage />
|
||||
</Suspense>
|
||||
);
|
||||
}
|
||||
@@ -1,28 +0,0 @@
|
||||
import { InstlRegistPage } from "@/pages/instl-sncn";
|
||||
|
||||
interface InstlSncnRegistRouteProps {
|
||||
searchParams: Promise<{
|
||||
taskSeComCd?: string;
|
||||
admdstCd?: string;
|
||||
sido?: string;
|
||||
gugun?: string;
|
||||
}>;
|
||||
}
|
||||
|
||||
export default async function Page({ searchParams }: InstlSncnRegistRouteProps) {
|
||||
const params = await searchParams;
|
||||
const taskSeComCd = params.taskSeComCd
|
||||
? params.taskSeComCd.split(",").filter(Boolean)
|
||||
: undefined;
|
||||
|
||||
return (
|
||||
<InstlRegistPage
|
||||
defaults={{
|
||||
taskSeComCd,
|
||||
admdstCd: params.admdstCd,
|
||||
sido: params.sido,
|
||||
gugun: params.gugun,
|
||||
}}
|
||||
/>
|
||||
);
|
||||
}
|
||||
@@ -1,11 +0,0 @@
|
||||
import type { ReactNode } from "react";
|
||||
|
||||
import { BaseLayoutWrapper } from "@/app/layouts/base-layout";
|
||||
|
||||
interface WithBaseLayoutProps {
|
||||
children: ReactNode;
|
||||
}
|
||||
|
||||
export default function WithBaseLayout({ children }: WithBaseLayoutProps) {
|
||||
return <BaseLayoutWrapper>{children}</BaseLayoutWrapper>;
|
||||
}
|
||||
@@ -1,3 +0,0 @@
|
||||
import { MyPbadmsSprtListPage } from "@/pages/my-pbadms-sprt";
|
||||
|
||||
export default MyPbadmsSprtListPage;
|
||||
@@ -1,3 +0,0 @@
|
||||
import { NtiHstryListPage } from "@/pages/nti-hstry";
|
||||
|
||||
export default NtiHstryListPage;
|
||||
@@ -1,3 +0,0 @@
|
||||
import { NtitlkSndngPage } from "@/pages/ntitlk-sndng";
|
||||
|
||||
export default NtitlkSndngPage;
|
||||
@@ -1 +0,0 @@
|
||||
export { RvwMnpwMngPage as default } from "@/pages/rvw-mnpw-mng";
|
||||
@@ -1,13 +0,0 @@
|
||||
import { SewerBscPlanEditPage } from "@/pages/sewer-bsc-plan";
|
||||
|
||||
interface PageProps {
|
||||
params: Promise<{ id: string }>;
|
||||
searchParams: Promise<{ chgCycl?: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params, searchParams }: PageProps) {
|
||||
const { id } = await params;
|
||||
const { chgCycl } = await searchParams;
|
||||
const propChgCycl = chgCycl ? Number(chgCycl) : undefined;
|
||||
return <SewerBscPlanEditPage id={id} propChgCycl={propChgCycl} />;
|
||||
}
|
||||
@@ -1,13 +0,0 @@
|
||||
import { SewerBscPlanDetailGate } from "@/pages/sewer-bsc-plan";
|
||||
|
||||
interface PageProps {
|
||||
params: Promise<{ id: string }>;
|
||||
searchParams: Promise<{ chgCycl?: string }>;
|
||||
}
|
||||
|
||||
export default async function Page({ params, searchParams }: PageProps) {
|
||||
const { id } = await params;
|
||||
const { chgCycl } = await searchParams;
|
||||
const propChgCycl = chgCycl ? Number(chgCycl) : undefined;
|
||||
return <SewerBscPlanDetailGate id={id} propChgCycl={propChgCycl} />;
|
||||
}
|
||||
@@ -1,11 +0,0 @@
|
||||
import { Suspense } from "react";
|
||||
|
||||
import { SewerBscPlanListPage } from "@/pages/sewer-bsc-plan";
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<Suspense>
|
||||
<SewerBscPlanListPage />
|
||||
</Suspense>
|
||||
);
|
||||
}
|
||||
@@ -1,19 +0,0 @@
|
||||
import { SewerBscPlanRegistPage } from "@/pages/sewer-bsc-plan";
|
||||
|
||||
interface PageProps {
|
||||
searchParams: Promise<{
|
||||
taskSeComCd?: string;
|
||||
taskSeCdNm?: string;
|
||||
sewerBscPlanSeComCd?: string;
|
||||
sewerBscPlanSeCdNm?: string;
|
||||
admdstCd?: string;
|
||||
sido?: string;
|
||||
gugun?: string;
|
||||
}>;
|
||||
}
|
||||
|
||||
export default async function Page({ searchParams }: PageProps) {
|
||||
const params = await searchParams;
|
||||
|
||||
return <SewerBscPlanRegistPage defaults={params} />;
|
||||
}
|
||||
@@ -1,27 +0,0 @@
|
||||
import type { Metadata } from "next";
|
||||
import { cookies } from "next/headers";
|
||||
|
||||
import { Providers } from "@/app/providers";
|
||||
|
||||
import "@/app/styles/globals.css";
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: "유역하수도통합플랫폼 Hasuon",
|
||||
description: "디지털 행정지원 시스템",
|
||||
};
|
||||
|
||||
interface RootLayoutProps {
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export default async function RootLayout({ children }: RootLayoutProps) {
|
||||
const theme = (await cookies()).get("site-theme-key");
|
||||
|
||||
return (
|
||||
<html lang="ko" data-theme={theme?.value}>
|
||||
<body>
|
||||
<Providers>{children}</Providers>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
@@ -1,169 +0,0 @@
|
||||
# App Layer
|
||||
|
||||
**App**은 애플리케이션 전체에 영향을 미치는 기술적, 비즈니스적 사항을 다루는 최상위 레이어입니다.
|
||||
|
||||
## 목적
|
||||
|
||||
- 애플리케이션의 진입점(entrypoint) 제공
|
||||
- 전역 Context Providers 설정
|
||||
- 라우터 구성
|
||||
- 글로벌 스타일 정의
|
||||
- 전역 상태 저장소 설정
|
||||
- 애널리틱스 및 모니터링 설정
|
||||
|
||||
## 특징
|
||||
|
||||
- **슬라이스 없음**: App 레이어는 Shared처럼 슬라이스가 없고 세그먼트로만 구성됩니다
|
||||
- **전체 앱 관심사**: 특정 비즈니스 도메인이 아닌 앱 전체와 관련된 코드만 포함
|
||||
- **최상위 레이어**: 모든 하위 레이어의 모듈을 자유롭게 import 가능
|
||||
|
||||
## 구조 (Next.js App Router)
|
||||
|
||||
Next.js를 사용하는 경우, App 레이어는 주로 `app/` 디렉토리로 표현됩니다:
|
||||
|
||||
```
|
||||
app/
|
||||
├── (routes)/ # 라우트 그룹 및 페이지
|
||||
│ ├── (auth)/
|
||||
│ │ ├── login/
|
||||
│ │ │ └── page.tsx
|
||||
│ │ └── register/
|
||||
│ │ └── page.tsx
|
||||
│ └── (main)/
|
||||
│ ├── dashboard/
|
||||
│ │ └── page.tsx
|
||||
│ └── settings/
|
||||
│ └── page.tsx
|
||||
├── layout.tsx # 루트 레이아웃
|
||||
├── page.tsx # 홈 페이지
|
||||
├── globals.css # 글로벌 스타일
|
||||
├── providers.tsx # 전역 Providers 설정
|
||||
└── error.tsx # 글로벌 에러 핸들러
|
||||
```
|
||||
|
||||
### 일반적인 FSD 세그먼트 구조
|
||||
|
||||
FSD 표준 세그먼트를 사용하는 경우:
|
||||
|
||||
```
|
||||
app/
|
||||
├── entrypoint/ # 애플리케이션 진입점 (프레임워크별)
|
||||
│ └── index.tsx
|
||||
├── providers/ # Context Providers
|
||||
│ ├── query-provider.tsx
|
||||
│ ├── theme-provider.tsx
|
||||
│ └── index.tsx
|
||||
├── styles/ # 글로벌 스타일
|
||||
│ ├── globals.css
|
||||
│ └── theme.css
|
||||
├── store/ # 글로벌 상태 저장소 설정
|
||||
│ └── index.ts
|
||||
└── routes/ # 라우터 설정
|
||||
└── index.tsx
|
||||
```
|
||||
|
||||
## 예시
|
||||
|
||||
### Next.js Providers 설정
|
||||
|
||||
```typescript
|
||||
// app/providers.tsx
|
||||
'use client';
|
||||
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import { ThemeProvider } from 'next-themes';
|
||||
import { useState } from 'react';
|
||||
|
||||
export function Providers({ children }: { children: React.ReactNode }) {
|
||||
const [queryClient] = useState(() => new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: {
|
||||
staleTime: 60 * 1000,
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
return (
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
|
||||
{children}
|
||||
</ThemeProvider>
|
||||
</QueryClientProvider>
|
||||
);
|
||||
}
|
||||
|
||||
// app/layout.tsx
|
||||
import { Providers } from './providers';
|
||||
import './globals.css';
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
return (
|
||||
<html lang="ko">
|
||||
<body>
|
||||
<Providers>
|
||||
{children}
|
||||
</Providers>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 글로벌 설정
|
||||
|
||||
```typescript
|
||||
// app/config/analytics.ts
|
||||
export function initAnalytics() {
|
||||
if (typeof window !== 'undefined') {
|
||||
// 애널리틱스 초기화
|
||||
}
|
||||
}
|
||||
|
||||
// app/config/monitoring.ts
|
||||
export function initMonitoring() {
|
||||
// 에러 모니터링 설정
|
||||
}
|
||||
```
|
||||
|
||||
## Next.js App Router와 FSD
|
||||
|
||||
Next.js의 `app/` 디렉토리는 FSD의 **App 레이어**와 **Pages 레이어**를 동시에 담당합니다:
|
||||
|
||||
- **루트 레벨 파일들** (`layout.tsx`, `providers.tsx`, `globals.css`): App 레이어
|
||||
- **라우트 폴더들** (`dashboard/`, `login/` 등): Pages 레이어
|
||||
|
||||
각 페이지별 비즈니스 로직은:
|
||||
- 재사용되지 않는 UI는 페이지 슬라이스(`app/dashboard/` 등) 안에 유지
|
||||
- 재사용되는 기능은 `features/` 레이어로 분리
|
||||
- 여러 페이지에서 재사용되는 큰 UI 블록은 `widgets/` 레이어로 분리
|
||||
|
||||
## 레이어 의존성 규칙
|
||||
|
||||
✅ **허용되는 의존성**:
|
||||
- 모든 하위 레이어 (`pages`, `widgets`, `features`, `entities`, `shared`)
|
||||
- 같은 `app` 레이어 내의 다른 세그먼트
|
||||
- 외부 라이브러리
|
||||
|
||||
❌ **금지된 의존성**:
|
||||
- 없음 (App은 최상위 레이어)
|
||||
|
||||
## 주의사항
|
||||
|
||||
1. **비대화 방지**: App 레이어가 너무 커지면 관리가 어려워집니다. 대부분의 로직은 하위 레이어에 배치하세요
|
||||
2. **전역 관심사만**: 특정 페이지나 기능에만 관련된 코드는 해당 레이어로 이동
|
||||
3. **라우터 레벨 로직**: 라우터 및 서버 레벨 로직은 이 레이어에 유지
|
||||
4. **Processes 레이어 사용 지양**: Processes 레이어는 deprecated되었으므로 해당 로직은 `app`이나 `features`에 배치
|
||||
|
||||
## FSD v2.1 권장사항
|
||||
|
||||
최신 FSD 버전(v2.1)은 **"pages-first"** 접근 방식을 권장합니다:
|
||||
|
||||
- 더 많은 코드를 페이지 슬라이스에 유지
|
||||
- 큰 UI 블록과 재사용되지 않는 비즈니스 로직은 즉시 추출하지 말고 페이지에 보관
|
||||
- 실제로 재사용이 필요할 때만 `features`나 `widgets`로 분리
|
||||
|
||||
이 접근 방식은 과도한 추상화를 방지하고 코드를 더 쉽게 탐색할 수 있게 합니다.
|
||||
@@ -1,10 +0,0 @@
|
||||
import { cookies } from "next/headers";
|
||||
import { NextResponse } from "next/server";
|
||||
|
||||
import { COOKIE_DOMAIN, REFRESH_TOKEN } from "@/shared/config";
|
||||
|
||||
export async function POST() {
|
||||
const cookieStore = await cookies();
|
||||
cookieStore.delete({ name: REFRESH_TOKEN, domain: COOKIE_DOMAIN });
|
||||
return NextResponse.json({ message: "Logged out" }, { status: 200 });
|
||||
}
|
||||
@@ -1,94 +0,0 @@
|
||||
import { cookies } from "next/headers";
|
||||
import { NextResponse } from "next/server";
|
||||
|
||||
import {
|
||||
ACCESS_TOKEN,
|
||||
AUTH_USER_ID,
|
||||
CLAIM_NAME,
|
||||
COOKIE_DOMAIN,
|
||||
REFRESH_TOKEN,
|
||||
SERVER_API_URL,
|
||||
SITE_ID,
|
||||
} from "@/shared/config";
|
||||
|
||||
async function handler(
|
||||
request: Request,
|
||||
params: { url: string[] },
|
||||
method: "GET" | "POST" | "PUT" | "DELETE",
|
||||
) {
|
||||
const cookieStore = await cookies();
|
||||
const headers: Record<string, string> = {
|
||||
"Content-Type": "application/json",
|
||||
"X-Site-Id": SITE_ID,
|
||||
};
|
||||
const deviceId = request.headers.get("X-Device-Id");
|
||||
if (deviceId) {
|
||||
headers["X-Device-Id"] = deviceId;
|
||||
}
|
||||
let body = {};
|
||||
const isRefreshHandler = params.url.includes("refresh");
|
||||
|
||||
// silent refresh
|
||||
if (isRefreshHandler) {
|
||||
const refreshToken = cookieStore.get(REFRESH_TOKEN);
|
||||
headers[CLAIM_NAME] = refreshToken?.value ?? "";
|
||||
|
||||
if (!headers[CLAIM_NAME]) {
|
||||
return NextResponse.json({ message: "Can't refresh" }, { status: 401 });
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
if (!isRefreshHandler) {
|
||||
body = await request.json();
|
||||
}
|
||||
|
||||
const targetUrl = `${SERVER_API_URL}/${params.url.join("/")}`;
|
||||
const result = await fetch(targetUrl, {
|
||||
method,
|
||||
headers,
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
|
||||
if (!result.ok) {
|
||||
return NextResponse.json({ message: "Invalid Credentials" }, { status: 401 });
|
||||
}
|
||||
|
||||
const accessToken = result.headers.get(ACCESS_TOKEN);
|
||||
const refreshToken = result.headers.get(REFRESH_TOKEN);
|
||||
const userId = result.headers.get(AUTH_USER_ID);
|
||||
|
||||
if (accessToken && userId) {
|
||||
const response = NextResponse.json({
|
||||
[ACCESS_TOKEN]: accessToken,
|
||||
[AUTH_USER_ID]: userId,
|
||||
});
|
||||
|
||||
if (refreshToken) {
|
||||
cookieStore.set(REFRESH_TOKEN, refreshToken, {
|
||||
httpOnly: true,
|
||||
sameSite: "strict",
|
||||
domain: COOKIE_DOMAIN,
|
||||
path: "/",
|
||||
});
|
||||
}
|
||||
|
||||
return response;
|
||||
}
|
||||
|
||||
return NextResponse.json({ message: "Invalid Credentials" }, { status: 401 });
|
||||
} catch (error) {
|
||||
console.error(`[Proxy API] Error caught in handler:`, error);
|
||||
return NextResponse.json({ message: "Server Error", error }, { status: 500 });
|
||||
}
|
||||
}
|
||||
|
||||
export async function POST(request: Request, props: { params: Promise<{ url: string[] }> }) {
|
||||
const params = await props.params;
|
||||
return handler(request, params, "POST");
|
||||
}
|
||||
|
||||
export async function PUT(request: Request, props: { params: Promise<{ url: string[] }> }) {
|
||||
const params = await props.params;
|
||||
return handler(request, params, "PUT");
|
||||
}
|
||||
@@ -1,38 +0,0 @@
|
||||
import type { Metadata } from "next";
|
||||
import Image from "next/image";
|
||||
|
||||
import "@/app/styles/globals.css";
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: "유역하수도통합플랫폼 Hasuon",
|
||||
description: "페이지가 존재하지 않습니다. 관리자에게 문의하여 주십시오.",
|
||||
};
|
||||
|
||||
export default function GlobalNotFound() {
|
||||
return (
|
||||
<html lang="ko">
|
||||
<body>
|
||||
<main className="flex min-h-screen flex-col items-center justify-center bg-[#f0f4f8] px-4 py-16">
|
||||
<div className="mb-16 text-center">
|
||||
<h1 className="text-[3.2rem] font-bold leading-snug tracking-tight">
|
||||
<span className="text-primary">디지털 행정지원 시스템</span>에 오신 것을 환영합니다.
|
||||
</h1>
|
||||
<p className="mt-6 text-[2rem] text-[#666]">오류가 발생하였습니다.</p>
|
||||
</div>
|
||||
|
||||
<section className="card card-border flex w-full max-w-[72rem] flex-col items-center !rounded-2xl !py-16">
|
||||
<Image
|
||||
src="/images/magnifying-glass-with-warning.png"
|
||||
alt=""
|
||||
width={280}
|
||||
height={280}
|
||||
className="size-[28rem] object-contain"
|
||||
/>
|
||||
<p className="mt-4 text-[2.4rem] font-bold text-[#444]">페이지가 존재하지 않습니다.</p>
|
||||
<p className="mt-2 text-[1.6rem] text-[#666]">관리자에게 문의하여 주십시오</p>
|
||||
</section>
|
||||
</main>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
@@ -1,203 +0,0 @@
|
||||
# PM2 배포 및 프로세스 관리 가이드
|
||||
|
||||
본 문서는 ONA 프론트엔드 모노레포 프로젝트(`frontend_as`)에서 **PM2를 활용한 애플리케이션 배포, 실행, 중지 및 모니터링 명령**을 체계적으로 정리한 가이드입니다.
|
||||
|
||||
---
|
||||
pnpm build:common && pnpm build:as && pm2 reload as2-app
|
||||
pnpm --filter=as... build
|
||||
pnpm --filter=as... build && pm2 reload as2-app
|
||||
## 1. 개요 및 아키텍처
|
||||
|
||||
- **설정 파일**: 프로젝트 루트의 `ecosystem.config.js`
|
||||
- **배포 워크플로우**: `.gitea/workflows/deploy.yml` (Gitea Actions 자동 배포)
|
||||
- **실행 모드**: `cluster` (2개 인스턴스로 로드밸런싱 및 무중단 롤링 배포 지원)
|
||||
- **운영 대상**:
|
||||
- `as2-app` (또는 `as-app`, `cs-app`, `st-app`, `cm-app` 등)
|
||||
|
||||
---
|
||||
|
||||
## 2. CI/CD 자동 배포 흐름
|
||||
|
||||
Gitea 저장소의 `deploy` 브랜치로 푸시될 때 원격 서버(192.168.0.4)에서 다음 스크립트가 순차 실행됩니다:
|
||||
|
||||
```bash
|
||||
cd ~/frontend
|
||||
git restore . # 변경된 로컬 파일 원복
|
||||
git clean -fd # 추적되지 않는 불필요한 파일/디렉터리 정리
|
||||
git pull origin deploy # 최신 deploy 브랜치 코드 반영
|
||||
pnpm install # 의존성 패키지 설치
|
||||
pnpm turbo build # 프로덕션 빌드 (.next 산출물 생성)
|
||||
pm2 reload all # 무중단 서비스 리로드 (클러스터 롤링 재시작)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 수동 배포 (Manual Deploy) 명령어
|
||||
|
||||
서버 터미널에 직접 접속하여 수동으로 최신 코드를 배포할 때 사용하는 명령어입니다.
|
||||
|
||||
### 3.1 전체 애플리케이션 수동 배포
|
||||
```bash
|
||||
# 1. 프로젝트 루트 이동
|
||||
cd ~/frontend
|
||||
|
||||
# 2. 최신 코드 가져오기
|
||||
git pull origin deploy
|
||||
|
||||
# 3. 의존성 설치 및 전체 빌드
|
||||
pnpm install
|
||||
pnpm turbo build
|
||||
|
||||
# 4. PM2 전체 무중단 리로드
|
||||
pm2 reload all
|
||||
```
|
||||
|
||||
### 3.2 `as` (행정지원) 앱만 단독 빌드 및 배포
|
||||
```bash
|
||||
cd ~/frontend
|
||||
|
||||
# as 앱만 타겟 빌드
|
||||
pnpm --filter as build
|
||||
|
||||
# as2-app 프로세스만 무중단 리로드
|
||||
pm2 reload as2-app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. PM2 실행 및 프로세스 등록 (Start & Save)
|
||||
|
||||
최초 서버 환경 구성 시 또는 프로세스 목록에서 삭제된 후 새롭게 등록할 때 실행합니다.
|
||||
|
||||
```bash
|
||||
# 1. 로그 디렉터리 사전 생성 (필수)
|
||||
mkdir -p apps/as/logs
|
||||
|
||||
# 2. ecosystem.config.js 기반 전체 앱 최초 실행
|
||||
pm2 start ecosystem.config.js
|
||||
|
||||
# 3. 특정 앱(as2-app)만 지정하여 최초 실행
|
||||
pm2 start ecosystem.config.js --only as2-app
|
||||
|
||||
# 4. 서버 재부팅 시에도 PM2 프로세스가 자동 복구되도록 현재 상태 저장 (필수!)
|
||||
pm2 save
|
||||
|
||||
# 5. OS 부팅 시 PM2 데몬 자동 등록 (최초 1회 설정)
|
||||
pm2 startup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 중지, 재시작 및 삭제 명령어
|
||||
|
||||
### 5.1 재시작 (Restart vs Reload)
|
||||
> **TIP: 운영 환경에서는 항상 `reload`를 권장합니다.**
|
||||
> - `reload`: 0-second downtime(무중단). 클러스터의 인스턴스를 하나씩 순차적으로 재시작하여 사용자 요청이 끊기지 않음.
|
||||
> - `restart`: 모든 인스턴스를 일시에 강제 종료 후 다시 띄우므로 짧은 다운타임 발생.
|
||||
|
||||
```bash
|
||||
# [권장] 무중단 재로드 (운영 배포 시)
|
||||
pm2 reload as2-app
|
||||
pm2 reload all
|
||||
|
||||
# 강제 재시작 (설정 변경이 반영되지 않거나 프로세스가 비정상일 때)
|
||||
pm2 restart as2-app
|
||||
pm2 restart all
|
||||
```
|
||||
|
||||
### 5.2 프로세스 중지 (Stop)
|
||||
프로세스를 메모리에서 내리고 실행을 일시 중단합니다 (PM2 목록에는 유지됨).
|
||||
|
||||
```bash
|
||||
# 특정 앱 중지
|
||||
pm2 stop as2-app
|
||||
|
||||
# 전체 앱 중지
|
||||
pm2 stop all
|
||||
```
|
||||
|
||||
### 5.3 프로세스 목록에서 제거 (Delete)
|
||||
PM2 관리 대상 목록에서 프로세스를 완전히 삭제합니다.
|
||||
|
||||
```bash
|
||||
# 특정 앱 삭제
|
||||
pm2 delete as2-app
|
||||
|
||||
# 전체 앱 삭제
|
||||
pm2 delete all
|
||||
|
||||
# 삭제 상태를 영구 저장할 경우
|
||||
pm2 save
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 상태 모니터링 및 로그 확인
|
||||
|
||||
### 6.1 프로세스 상태 확인
|
||||
```bash
|
||||
# 간략한 프로세스 상태 표 확인 (online, stopped, cpu, memory 등)
|
||||
pm2 status
|
||||
# 또는
|
||||
pm2 list
|
||||
|
||||
# 특정 앱 상세 정보 확인 (환경변수, 파일 경로, 재시작 횟수 등)
|
||||
pm2 show as2-app
|
||||
```
|
||||
|
||||
### 6.2 실시간 로그 스트리밍 (Logs)
|
||||
```bash
|
||||
# 특정 앱 실시간 로그 확인 (표준 출력 + 에러 출력)
|
||||
pm2 logs as2-app
|
||||
|
||||
# 최근 100줄 출력 후 실시간 스트리밍
|
||||
pm2 logs as2-app --lines 100
|
||||
|
||||
# 에러 로그만 확인
|
||||
pm2 logs as2-app --err
|
||||
|
||||
# 전체 프로세스 로그 확인
|
||||
pm2 logs
|
||||
|
||||
# 이전 로그 비우기(Flush)
|
||||
pm2 flush
|
||||
```
|
||||
|
||||
### 6.3 터미널 대시보드 모니터링 (Monit)
|
||||
CPU 및 메모리 실시간 사용량을 터미널 대시보드로 확인합니다.
|
||||
```bash
|
||||
pm2 monit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 주요 트러블슈팅 (FAQ)
|
||||
|
||||
### Q1. `EADDRINUSE: address already in use :::3004` 포트 충돌 발생
|
||||
- **원인**: 로컬 개발 서버(`pnpm --filter as dev`) 또는 이전 Node 프로세스가 3004번 포트를 계속 점유 중인 상태입니다.
|
||||
- **해결**:
|
||||
```bash
|
||||
# 3004 포트 사용 중인 PID 확인
|
||||
lsof -i :3004
|
||||
|
||||
# 해당 프로세스 종료
|
||||
kill -9 <PID>
|
||||
|
||||
# PM2 리로드
|
||||
pm2 reload as2-app
|
||||
```
|
||||
|
||||
### Q2. `Could not find a production build in the '.next' directory`
|
||||
- **원인**: Next.js 프로덕션 실행 전에 빌드 산출물(`.next`)이 생성되지 않았습니다.
|
||||
- **해결**:
|
||||
```bash
|
||||
pnpm --filter as build
|
||||
pm2 reload as2-app
|
||||
```
|
||||
|
||||
### Q3. `logs` 디렉터리 관련 에러 발생
|
||||
- **원인**: `ecosystem.config.js`의 `cwd: './apps/as'` 설정에 따라 `./logs` 경로가 없을 경우 발생할 수 있습니다.
|
||||
- **해결**:
|
||||
```bash
|
||||
mkdir -p apps/as/logs
|
||||
```
|
||||
@@ -1,181 +0,0 @@
|
||||
# Next.js 프로덕션 빌드 에러 원인 분석 및 조치 보고서
|
||||
|
||||
본 문서는 `apps/as` 프로덕션 빌드(`pnpm build:as` / `next build`) 과정에서 발생한 ESLint Hook 규칙 위반 및 TypeScript 컴파일 에러의 원인과 이를 해결한 조치 내역을 정리한 문서입니다.
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요 및 장애 상황
|
||||
|
||||
- **대상 모듈**: `apps/as` (행정지원 프론트엔드 애플리케이션)
|
||||
- **실행 명령**: `pnpm build:as` (또는 `pnpm --filter as build`)
|
||||
- **발생 시점**: 2026-10-20
|
||||
- **장애 영향**: Next.js 프로덕션 최적화 빌드 실패로 인해 배포 산출물(`.next`) 생성이 중단됨
|
||||
|
||||
### 빌드 실패 로그 요약
|
||||
```text
|
||||
as:build: Failed to compile.
|
||||
|
||||
as:build: ./src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx
|
||||
as:build: 159:35 Error: React Hook "useStore" is called conditionally. React Hooks must be called in the exact same order in every component render. react-hooks/rules-of-hooks
|
||||
|
||||
./src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx:164:5
|
||||
Type error: Type 'boolean' has no properties in common with type '{ enabled?: boolean | undefined; structuralSharing?: boolean | undefined; }'.
|
||||
|
||||
./src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx:215:29
|
||||
Type error: Property 'atrzSeq' does not exist on type 'ElaprDocPrgrsClientResponseDto'. Did you mean 'atrzSeqNo'?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 근본 원인 분석 (Root Cause Analysis)
|
||||
|
||||
### 2.1 React Hook 규칙 위반 (`react-hooks/rules-of-hooks`)
|
||||
- **위치**: `apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx` (158~159라인)
|
||||
- **원인 코드**:
|
||||
```tsx
|
||||
const storeContext = useContext(StoreContext);
|
||||
const userInfo = storeContext ? useStore(storeContext.userStore, (state) => state.userInfo) : null;
|
||||
```
|
||||
- **문제점**:
|
||||
- React Hooks는 조건문, 반복문, 삼항 연산자 내부에서 호출될 수 없으며, 모든 렌더링마다 항상 동일한 순서로 호출되어야 합니다.
|
||||
- 삼항 연산자 내에서 `useStore`를 호출하면서 `react-hooks/rules-of-hooks` 에러가 발생하여 빌드가 즉시 차단되었습니다.
|
||||
- 또한 프로젝트 전역에서 제공하는 표준 훅인 `useUserStore`(`@/shared/lib`)가 이미 존재함에도 불구하고 이를 사용하지 않고 수동으로 컨텍스트를 조회하여 분기 처리하고 있었습니다.
|
||||
|
||||
### 2.2 `useElaprBranchesByDocNo` 훅 옵션 매개변수 타입 불일치
|
||||
- **원인 코드**:
|
||||
```tsx
|
||||
const { data: elaprBranchList = [] } = useElaprBranchesByDocNo(
|
||||
fnrsCnsltnDocNo,
|
||||
open && Boolean(isForkJoin), // boolean 직접 전달
|
||||
);
|
||||
```
|
||||
- **문제점**:
|
||||
- `useElaprBranchesByDocNo`의 시그니처는 `(elaprDocNo, options?: { enabled?: boolean; structuralSharing?: boolean })`로 선언되어 있어, `boolean` 대신 객체 형태(`{ enabled: ... }`)로 전달해야 합니다.
|
||||
|
||||
### 2.3 전자결재 결재선 DTO 필드명 불일치
|
||||
- **원인 코드**:
|
||||
```tsx
|
||||
if (currentUserPrgrs?.atrzSeq && Number(currentUserPrgrs.atrzSeq) > 1) return true;
|
||||
```
|
||||
- **문제점**:
|
||||
- `ElaprDocPrgrsClientResponseDto` 인터페이스(`src/shared/model/pbadms-sprt.ts`)에 선언된 정식 결재 순번 필드명은 `atrzSeqNo?: number`입니다.
|
||||
- 기존 코드가 `atrzSeq`로 접근하여 TypeScript 컴파일 에러가 발생했습니다.
|
||||
|
||||
### 2.4 `PwrkCnsltnDocEvlDialog`의 필수 prop `onSaved` 누락
|
||||
- **원인 코드**:
|
||||
```tsx
|
||||
<PwrkCnsltnDocEvlDialog
|
||||
open={isEvlDialogOpen}
|
||||
pwrkCnsltnDocNo={completedDraft.pwrkCnsltnDocNo}
|
||||
onClose={() => setIsEvlDialogOpen(false)}
|
||||
/>
|
||||
```
|
||||
- **문제점**:
|
||||
- `PwrkCnsltnDocEvlDialogProps`에 `onSaved: () => void;`가 필수로 선언되어 있었으나, 호출부에서 `onSaved` 콜백을 넘기지 않아 `Property 'onSaved' is missing` 컴파일 에러가 발생했습니다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 조치 내역
|
||||
|
||||
### 3.1 컴포넌트 코드 수정 (`pwrk-cnsltn-doc-mng-dialog.tsx`)
|
||||
1. **표준 `useUserStore` 훅 적용**:
|
||||
- `useStore`, `StoreContext`, `useContext`를 제거하고, `@/shared/lib`의 `useUserStore`를 무조건부로 호출하도록 변경.
|
||||
2. **`useElaprBranchesByDocNo` 옵션 객체화**:
|
||||
- `{ enabled: open && Boolean(isForkJoin) }` 형태로 수정.
|
||||
3. **결재 순번 속성 방어적 매핑**:
|
||||
- `atrzSeqNo`를 우선 참조하고 레거시/모의 데이터의 `atrzSeq`도 호환되도록 fallback 처리.
|
||||
4. **`PwrkCnsltnDocEvlDialog`의 `onSaved` prop 연결 및 선택적(Optional) 처리**:
|
||||
- `pwrk-cnsltn-doc-evl-dialog.tsx`: `onSaved?: () => void;`로 변경하고 `onSaved?.()` 호출로 방어.
|
||||
- `pwrk-cnsltn-doc-mng-dialog.tsx`: `<PwrkCnsltnDocEvlDialog ... onSaved={() => setIsEvlDialogOpen(false)} />` 콜백 전달.
|
||||
|
||||
#### 핵심 변경 사항 (Diff)
|
||||
```diff
|
||||
--- a/apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx
|
||||
+++ b/apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx
|
||||
@@ -1,14 +1,11 @@
|
||||
"use client";
|
||||
|
||||
-import { useContext, useEffect, useMemo, useState } from "react";
|
||||
+import { useEffect, useMemo, useState } from "react";
|
||||
import dynamic from "next/dynamic";
|
||||
|
||||
import { useQuery, useQueryClient } from "@tanstack/react-query";
|
||||
import { PanelRightClose, PanelRightOpen } from "lucide-react";
|
||||
-import { useStore } from "zustand";
|
||||
-
|
||||
-import { getDefaultFileKey, useAlertStore, useTus } from "@/shared/lib";
|
||||
-import { StoreContext } from "@/shared/providers";
|
||||
+import { getDefaultFileKey, useAlertStore, useTus, useUserStore } from "@/shared/lib";
|
||||
|
||||
@@ -155,8 +152,7 @@ function PwrkCnsltnDocMngDialog({
|
||||
const queryClient = useQueryClient();
|
||||
const alert = useAlertStore((state) => state.setMessage);
|
||||
- const storeContext = useContext(StoreContext);
|
||||
- const userInfo = storeContext ? useStore(storeContext.userStore, (state) => state.userInfo) : null;
|
||||
+ const userInfo = useUserStore((state) => state.userInfo);
|
||||
|
||||
@@ -165,7 +161,7 @@ function PwrkCnsltnDocMngDialog({
|
||||
const { data: elaprBranchList = [] } = useElaprBranchesByDocNo(
|
||||
fnrsCnsltnDocNo,
|
||||
- open && Boolean(isForkJoin),
|
||||
+ { enabled: open && Boolean(isForkJoin) },
|
||||
);
|
||||
|
||||
@@ -216,11 +212,19 @@ function PwrkCnsltnDocMngDialog({
|
||||
if (effectiveBranchSeCd === "TOTAL_AGG") {
|
||||
if (effectiveAtrzSeList.includes("ATRZ04")) return false;
|
||||
if (effectiveAtrzSeList.some((cd) => APPROVER_ATRZ_SE_COM_CDS.has(cd))) return true;
|
||||
- if (currentUserPrgrs?.atrzSeq && Number(currentUserPrgrs.atrzSeq) > 1) return true;
|
||||
+ const userSeq = currentUserPrgrs?.atrzSeqNo ?? (currentUserPrgrs as Record<string, unknown> | undefined)?.atrzSeq;
|
||||
+ if (userSeq && Number(userSeq) > 1) return true;
|
||||
if (effectiveAtrzSeList.length > 0 && !effectiveAtrzSeList.includes("ATRZ04")) return true;
|
||||
}
|
||||
return false;
|
||||
```
|
||||
|
||||
### 3.2 단위 테스트 모킹 보완 (`pwrk-cnsltn-doc-mng-dialog.test.tsx`)
|
||||
- 단위 테스트 환경에서 `StoreProvider` 미감싸임 에러(`useUserStore must be used within StoreProvider`)가 발생하지 않도록 `@/shared/lib` 모킹 객체에 `useUserStore`를 추가.
|
||||
```tsx
|
||||
let mockUserInfo: any = null;
|
||||
|
||||
vi.mock("@/shared/lib", async (importOriginal) => {
|
||||
const actual = await importOriginal<typeof import("@/shared/lib")>();
|
||||
return {
|
||||
...actual,
|
||||
getDefaultFileKey: () => "mock-key",
|
||||
useAlertStore: () => vi.fn(),
|
||||
useUserStore: (selector: (state: { userInfo: any }) => any) =>
|
||||
selector ? selector({ userInfo: mockUserInfo }) : { userInfo: mockUserInfo },
|
||||
useTus: () => ({
|
||||
uploadFileAsync: vi.fn(),
|
||||
isUploading: {},
|
||||
uploads: {},
|
||||
}),
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 검증 결과
|
||||
|
||||
| 검증 단계 | 명령어 | 결과 | 비고 |
|
||||
|---|---|---|---|
|
||||
| **1. 정적 타입 검사** | `pnpm --filter as exec tsc --noEmit` | **성공 (Exit 0)** | 컴파일 에러 0건 |
|
||||
| **2. ESLint 린트 검사** | `pnpm --filter as lint` | **성공 (Exit 0)** | Hook 위반 에러 해결 |
|
||||
| **3. 단위 테스트 (Vitest)** | `pnpm --filter as exec vitest run` | **전체 통과 (73/73 Tests)** | 14개 테스트 파일 100% Pass |
|
||||
| **4. 프로덕션 빌드** | `pnpm build:as` | **성공 (Exit 0)** | 22/22 정적 페이지 최적화 완료 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 재발 방지 표준 가이드
|
||||
|
||||
1. **React Hook 호출 규칙 준수**:
|
||||
- `useUserStore`, `useQuery`, `useStore` 등 모든 React Hook은 반드시 컴포넌트 함수의 최상단(Top-level)에서 무조건부로 호출해야 합니다.
|
||||
- 사용자 정보가 필요할 경우 개별 컨텍스트 접근 대신 표준 훅인 `useUserStore((state) => state.userInfo)`를 사용합니다.
|
||||
|
||||
2. **React Query 커스텀 훅 매개변수 규칙**:
|
||||
- 조건부 쿼리 실행이 필요한 경우 boolean 값을 단독으로 넘기지 않고 `{ enabled: boolean }` 형태의 옵션 객체 인터페이스를 유지합니다.
|
||||
|
||||
3. **엔티티 DTO 필드명 엄격 확인**:
|
||||
- 전자결재 결재선 DTO는 백엔드 명세에 따라 `atrzSeqNo`를 표준으로 사용하므로 레거시 명칭(`atrzSeq`)을 사용하지 않도록 타입을 확인합니다.
|
||||
@@ -1,160 +0,0 @@
|
||||
# 개발(Dev) 및 운영(Production) 실행 가이드 & 환경변수 관리
|
||||
|
||||
본 문서는 `apps/as` 애플리케이션의 **개발(Dev) 모드** 및 **운영(Production) 모드** 실행 방법과 **환경변수(.env) 변경 시의 재빌드 규칙**을 상세히 정리한 가이드입니다.
|
||||
|
||||
---
|
||||
|
||||
## 1. Dev 모드 vs Production 모드 비교
|
||||
|
||||
| 구분 | 개발 모드 (Dev) | 운영 모드 (Production) |
|
||||
|---|---|---|
|
||||
| **실행 목적** | 로컬 개발, 디버깅, 실시간 코드 수정 | 실서버 운영, 성능 최적화, 안정성 보장 |
|
||||
| **사전 빌드 필요 여부** | **불필요** (즉시 실행) | **필수** (`.next` 번들 생성 선행) |
|
||||
| **코드 반영 방식** | 핫 리로딩(HMR, 저장 즉시 반영) | 빌드 시점의 번들링 코드 고정 서빙 |
|
||||
| **참조 환경변수** | `.env.local` > `.env.development` | `.env.local` > `.env.production` |
|
||||
| **프로세스 관리** | Node 단일 프로세스 (터미널) | **PM2 Cluster 모드** (2개 인스턴스 무중단) |
|
||||
| **서비스 포트** | 기본 `3004` 포트 | 기본 `3004` 포트 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 환경변수(.env) 변경 시 재빌드 필수 여부
|
||||
|
||||
### 2.1 결론: `.env.production` 변경 시 반드시 재빌드 필요
|
||||
Next.js 환경에서는 `.env.production`을 수정했을 때 단순히 PM2 재시작(`pm2 reload` / `pm2 restart`)만으로는 변경 사항이 브라우저에 반영되지 않으며, **반드시 빌드(`next build`)를 다시 수행해야 합니다.**
|
||||
|
||||
### 2.2 이유: Next.js의 환경변수 인라이닝(Inlining) 원리
|
||||
1. **`NEXT_PUBLIC_*` 변수의 빌드타임 주입**:
|
||||
- `NEXT_PUBLIC_SERVER_API_URL`, `NEXT_PUBLIC_PROXY_HOST`, `NEXT_PUBLIC_WEBHYP_CTRL_URL` 등 브라우저에서 참조하는 변수들은 `next build` 시점에 생성되는 클라이언트 JavaScript 파일(`.next/static/...`) 안에 **문자열 값으로 직접 하드코딩(Inlining)**됩니다.
|
||||
- 따라서 코드를 다시 빌드하지 않으면 예전 주소나 설정값이 그대로 유지됩니다.
|
||||
2. **정적 페이지(SSG) 생성 시점의 값 고정**:
|
||||
- 빌드 시 정적 생성된 페이지(`Generating static pages (22/22)`)는 빌드 당시 읽어들인 환경변수 값을 기준으로 생성되므로, 런타임에 환경변수를 바꿔도 페이지가 갱신되지 않습니다.
|
||||
|
||||
### 2.3 환경변수 우선순위 주의사항
|
||||
Next.js의 환경변수 로딩 우선순위는 다음과 같습니다:
|
||||
|
||||
```text
|
||||
[운영 환경: NODE_ENV=production]
|
||||
1순위: .env.production.local
|
||||
2순위: .env.local (NODE_ENV=test 제외 항상 최우선)
|
||||
3순위: .env.production
|
||||
4순위: .env
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> 실서버 환경에 `.env.local` 파일이 존재할 경우 `.env.production`보다 우선 적용됩니다. `.env.production`을 수정했는데도 반영되지 않는다면 같은 경로에 `.env.local`이 존재하는지 확인하십시오.
|
||||
|
||||
---
|
||||
|
||||
## 3. Dev (개발 모드) 실행 방법
|
||||
|
||||
사전 빌드 과정 없이 소스 코드를 실시간으로 수정하며 개발할 때 사용합니다.
|
||||
|
||||
### 3.1 프로젝트 루트 디렉터리에서 실행
|
||||
```bash
|
||||
# 루트 디렉터리: ~/frontend_as
|
||||
pnpm dev:as
|
||||
|
||||
# 또는 pnpm filter 플래그 사용
|
||||
pnpm --filter as dev
|
||||
```
|
||||
|
||||
### 3.2 `apps/as` 디렉터리 내부에서 실행
|
||||
```bash
|
||||
cd ~/frontend_as/apps/as
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
- **접속 주소**: [http://localhost:3004](http://localhost:3004)
|
||||
- **종료**: 터미널에서 `Ctrl + C`
|
||||
|
||||
---
|
||||
|
||||
## 4. Production (운영 모드) 실행 방법
|
||||
|
||||
반드시 **빌드 산출물(`.next`)이 최신 상태로 생성되어 있어야 정상 실행**됩니다.
|
||||
|
||||
### 4.1 1단계: 프로덕션 빌드 (필수)
|
||||
모노레포 전체를 빌드할 필요 없이 `as` 앱만 단독으로 빌드할 수 있습니다:
|
||||
|
||||
```bash
|
||||
# 프로젝트 루트 디렉터리에서 실행 (약 20~30초 소요)
|
||||
pnpm build:as
|
||||
|
||||
# 또는
|
||||
pnpm --filter as build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 2단계: 서버 프로세스 실행
|
||||
|
||||
#### 방법 A: 터미널에서 직접 실행 (로컬 프로덕션 점검용)
|
||||
포그라운드 터미널에서 프로덕션 번들의 빌드 결과와 동작을 직접 테스트할 때 사용합니다:
|
||||
|
||||
```bash
|
||||
# 루트 디렉터리에서 실행
|
||||
pnpm --filter as start
|
||||
|
||||
# 또는 apps/as 디렉터리에서 실행
|
||||
cd apps/as
|
||||
pnpm start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 방법 B: PM2 프로세스 매니저로 실행 (실서버 운영 표준)
|
||||
실제 운영 서버에서는 `ecosystem.config.js` 설정을 통해 무중단 클러스터(2개 인스턴스)로 실행합니다.
|
||||
|
||||
```bash
|
||||
# 1. 프로세스가 아직 등록되지 않은 경우 (최초 기동)
|
||||
pm2 start ecosystem.config.js --only as2-app
|
||||
|
||||
# 2. 이미 실행 중인 경우 (무중단 롤링 리로드 - 권장)
|
||||
# 순차적으로 인스턴스를 재시작하므로 사용자 요청 끊김이 없습니다.
|
||||
pm2 reload as2-app
|
||||
|
||||
# 3. 프로세스 완전 재시작이 필요한 경우
|
||||
pm2 restart as2-app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. PM2 운영 및 모니터링 치트시트
|
||||
|
||||
```bash
|
||||
# 1. 전체 프로세스 상태 확인 (상태, 메모리, CPU 점유율 등)
|
||||
pm2 status
|
||||
# 또는
|
||||
pm2 list
|
||||
|
||||
# 2. as2-app 실시간 로그 모니터링
|
||||
pm2 logs as2-app
|
||||
|
||||
# 3. 최근 로그 100줄 출력
|
||||
pm2 logs as2-app --lines 100
|
||||
|
||||
# 4. 프로세스 일시 중지 및 삭제
|
||||
pm2 stop as2-app # 프로세스 일시 중지
|
||||
pm2 delete as2-app # PM2 목록에서 제거
|
||||
|
||||
# 5. 서버 재부팅 시 자동 실행 등록
|
||||
pm2 save # 현재 실행 중인 프로세스 목록 저장
|
||||
pm2 startup # OS 부팅 스크립트 생성
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 실무 배포 요약 워크플로우
|
||||
|
||||
`.env.production` 수정 또는 프론트엔드 코드 수정 후 배포 시 아래 3단계를 수행합니다:
|
||||
|
||||
```bash
|
||||
# Step 1. 최신 코드 반영 (필요시)
|
||||
git pull origin deploy
|
||||
|
||||
# Step 2. as 앱 단독 프로덕션 재빌드
|
||||
pnpm build:as
|
||||
|
||||
# Step 3. PM2 무중단 롤링 리로드
|
||||
pm2 reload as2-app
|
||||
```
|
||||
@@ -1,302 +0,0 @@
|
||||
# 재원협의(fnrs-cnsltn) 플로팅 액션 버튼(FloatingActionButtons) 호출 메커니즘 분석
|
||||
|
||||
## 1. 개요 (Overview)
|
||||
|
||||
본 문서는 **디지털 행정지원(Administrative Support, AS)** 모듈의 **재원협의 상세 조회 화면(`FnrsViewPage`)** 하단에 위치한 [FloatingActionButtons](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx) 컴포넌트의 액션 처리 메커니즘을 상세히 분석한 기술 문서입니다.
|
||||
|
||||
사용자가 화면 하단 액션바에서 **반려(`rjct`) 버튼**을 클릭했을 때 실행되는 `handleRjctClick()` 함수가 내부적으로 중앙 집중식 디스패처인 `executeAction()`과 룩업 테이블(`buttonActionHandlers`)을 거쳐 최종 API 호출 함수인 `handleRejectPrgrsStts()`로 라우팅되는 전 과정을 추적하고, 적용된 아키텍처 디자인 패턴을 설명합니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 핵심 아키텍처 디자인 패턴
|
||||
|
||||
[FloatingActionButtons](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx)는 수많은 행정 업무 액션(저장, 신청, 삭제, 환경청 제출, 승인, 반려, 검토의견 회신, 보완요청, 기술검토요청 등)을 안전하고 확장 가능하게 관리하기 위해 **전략 패턴(Strategy Pattern)**과 **디스패처(Dispatcher) 패턴**을 결합하여 설계되었습니다.
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ UI 컴포넌트 이벤트 (예: handleRjctClick) │
|
||||
│ - 사용자 Confirm 확인 │
|
||||
│ - 요청 DTO(DocPrgrsUpdateRequestDto) 조립 │
|
||||
└──────────────────────────────────┬─────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ 중앙 액션 디스패처 (executeAction) │
|
||||
│ - 중복 클릭 방지 (isProcessing 상태 관리) │
|
||||
│ - buttonActionHandlers 룩업 테이블에서 적절한 Strategy 함수 검색 │
|
||||
│ - 일원화된 성공 처리 (Alert 메시지, React Query 캐시 무효화) │
|
||||
│ - 일원화된 에러 처리 (Axios 에러 메시지 추출 및 Alert) │
|
||||
└──────────────────────────────────┬─────────────────────────────────────┘
|
||||
│ action: "rjct" 키로 조회
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ 룩업 테이블 (buttonActionHandlers: Record<Action, Handler>) │
|
||||
│ - rjct: handleRejectPrgrsStts │
|
||||
└──────────────────────────────────┬─────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ 개별 액션 핸들러 (handleRejectPrgrsStts) │
|
||||
│ - fnrsCnsltnMngService.rejectPrgrsStts(payload) 백엔드 API 호출 │
|
||||
│ - context.onSuccess() / context.onError() 콜백 트리거 │
|
||||
└────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.1 적용된 핵심 원칙 및 이점
|
||||
1. **단일 책임 원칙 (SRP)**:
|
||||
- 각 UI 이벤트 함수(`handleRjctClick`)는 사용자 확인 및 페이로드 빌드만 담당합니다.
|
||||
- 중앙 디스패처(`executeAction`)는 로딩 상태, 캐시 갱신, 공통 에러 핸들링을 전담합니다.
|
||||
- 실제 비즈니스 통신은 순수 비동기 함수(`handleRejectPrgrsStts`)로 격리됩니다.
|
||||
2. **개방-폐쇄 원칙 (OCP)**:
|
||||
- 신규 액션 버튼이 추가될 경우 `buttonActionHandlers` 레코드에 새로운 키-핸들러 쌍만 등록하면 되며, 공통 에러 처리나 캐시 무효화 로직을 중복 구현할 필요가 없습니다.
|
||||
3. **무결성 및 안정성**:
|
||||
- `setIsProcessing(true)`를 통해 네트워크 요청 진행 중 다중 클릭(Double Submit)을 원천 차단합니다.
|
||||
- 작업 완료 후 `queryClient.invalidateQueries`를 통해 상세 데이터 및 전자결재 분기 상태를 최신 상태로 즉시 동기화합니다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 전체 호출 흐름 시퀀스 다이어그램 (Sequence Diagram)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor User as 사용자
|
||||
participant UI as FloatingActionButtons
|
||||
participant Rjct as handleRjctClick
|
||||
participant Exec as executeAction (디스패처)
|
||||
participant Table as buttonActionHandlers (룩업)
|
||||
participant Handler as handleRejectPrgrsStts
|
||||
participant Service as fnrsCnsltnMngService
|
||||
participant Backend as 백엔드 REST API
|
||||
participant Query as TanStack QueryClient
|
||||
|
||||
User->>UI: [반려] 버튼 클릭
|
||||
UI->>Rjct: handleRjctClick() 트리거
|
||||
Rjct->>User: confirm("해당 신청 건을 반려하시겠습니까?")
|
||||
User-->>Rjct: 확인 (true)
|
||||
|
||||
Note over Rjct: DocPrgrsUpdateRequestDto 생성<br/>{ docNo, docSeComCd, prgrsSttsComCd: "SV", rgtrUuid }
|
||||
|
||||
Rjct->>Exec: executeAction({ action: "rjct", request: payload, successMessage: "반려되었습니다." })
|
||||
|
||||
rect rgb(240, 245, 255)
|
||||
Note over Exec: 1. setIsProcessing(true)<br/>2. const handler = buttonActionHandlers["rjct"]
|
||||
Exec->>Table: buttonActionHandlers["rjct"] 검색
|
||||
Table-->>Exec: handleRejectPrgrsStts 반환
|
||||
end
|
||||
|
||||
Exec->>Handler: handler({ request, data, onSuccess, onError }) 실행
|
||||
|
||||
Handler->>Service: rejectPrgrsStts(context.request) 호출
|
||||
Service->>Backend: PUT /api/v1/as/fnrs-cnsltn-mng/reject-prgrs-stts
|
||||
Backend-->>Service: 200 OK 응답
|
||||
Service-->>Handler: 완료 반환
|
||||
|
||||
Handler->>Exec: context.onSuccess() 콜백 호출
|
||||
|
||||
rect rgb(245, 255, 240)
|
||||
Note over Exec: onSuccess 후속 처리 실행
|
||||
Exec->>User: alert("반려되었습니다.")
|
||||
Exec->>Query: invalidateQueries({ queryKey: fnrsCnsltnKeys.detail(...) })
|
||||
Exec->>Query: invalidateQueries({ queryKey: [ENDPOINT.AS_ELAPR_SERVICE.ELAPR_BRANCH] })
|
||||
Note over Query: 백엔드 최신 상세 데이터 재조회 및 화면 UI 갱신 (상태: ST -> SV)
|
||||
end
|
||||
|
||||
Note over Exec: finally { setIsProcessing(false) }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 단계별 상세 소스 코드 분석
|
||||
|
||||
### 4.1 Step 1: UI 이벤트 트리거 및 페이로드 조립 (`handleRjctClick`)
|
||||
|
||||
사용자가 화면의 반려 버튼을 클릭하면 [handleRjctClick](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx#L474-L489)이 실행됩니다.
|
||||
|
||||
```typescript
|
||||
// apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx (Line 474~489)
|
||||
async function handleRjctClick() {
|
||||
// 1. 사용자 재확인 대화상자 노출
|
||||
if (!(await confirm("해당 신청 건을 반려하시겠습니까?"))) {
|
||||
return;
|
||||
}
|
||||
|
||||
// 2. 백엔드 진행상태 업데이트 DTO 빌드 (임시저장 'SV' 상태로 롤백)
|
||||
const payload: DocPrgrsUpdateRequestDto = {
|
||||
docNo, // 대상 문서번호
|
||||
docSeComCd, // 문서구분 공통코드
|
||||
prgrsSttsComCd: "SV", // 변경할 진행상태: 작성중/임시저장(SV)
|
||||
rgtrUuid: userInfo?.userUnqId, // 처리자 고유 식별자
|
||||
};
|
||||
|
||||
// 3. 중앙 디스패처 호출
|
||||
await executeAction({
|
||||
action: FNRS_CNSLTN_VIEW_BUTTON_ACTION.rjct, // "rjct" 상수
|
||||
request: payload,
|
||||
successMessage: "반려되었습니다.",
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
* **핵심 포인트**: 반려 처리는 문서의 진행 상태를 신청완료(`ST`)에서 작성자(지자체)가 다시 수정할 수 있는 임시저장/작성중(`SV`) 상태로 되돌리는 동작입니다.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Step 2: 중앙 집중식 액션 디스패처 (`executeAction`)
|
||||
|
||||
[executeAction](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx#L370-L408)은 전달받은 액션 식별자에 따라 룩업 테이블에서 핸들러를 찾아 실행하고, 공통 라이프사이클(로딩, 성공 알림, 쿼리 캐시 무효화, 에러 처리)을 관리합니다.
|
||||
|
||||
```typescript
|
||||
// apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx (Line 370~408)
|
||||
async function executeAction({
|
||||
action,
|
||||
request,
|
||||
successMessage,
|
||||
}: {
|
||||
action: FnrsCnsltnViewButtonAction;
|
||||
request?: unknown;
|
||||
successMessage?: string;
|
||||
}) {
|
||||
// 1. 룩업 테이블에서 액션명에 해당하는 실행 함수 조회
|
||||
const handler = buttonActionHandlers[action];
|
||||
if (!handler) return;
|
||||
|
||||
// 2. 비동기 처리 중 중복 호출 방지 플래그 활성화
|
||||
setIsProcessing(true);
|
||||
try {
|
||||
// 3. 전략 핸들러에 Context 주입 및 실행
|
||||
await handler({
|
||||
request,
|
||||
data,
|
||||
onSuccess: () => {
|
||||
// 성공 메시지 출력
|
||||
if (successMessage) alert(successMessage);
|
||||
|
||||
// 상세 데이터 쿼리 캐시 무효화 -> 화면 자동 갱신
|
||||
queryClient.invalidateQueries({
|
||||
queryKey: fnrsCnsltnKeys.detail(fnrsCnsltnDocNo),
|
||||
});
|
||||
|
||||
// 전자결재 분기 상태 쿼리 캐시 무효화
|
||||
queryClient.invalidateQueries({
|
||||
queryKey: [ENDPOINT.AS_ELAPR_SERVICE.ELAPR_BRANCH],
|
||||
});
|
||||
},
|
||||
onError: (error) => {
|
||||
// 통일된 에러 메시지 추출 및 Alert
|
||||
let errorMessage = "";
|
||||
if (error instanceof AxiosError) {
|
||||
errorMessage = error.response?.data?.message ?? "";
|
||||
} else {
|
||||
errorMessage = error.message ?? "처리 중 오류가 발생했습니다.";
|
||||
}
|
||||
alert(errorMessage);
|
||||
},
|
||||
});
|
||||
} finally {
|
||||
// 4. 로딩 플래그 해제
|
||||
setIsProcessing(false);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Step 3: 전략 매핑 룩업 테이블 (`buttonActionHandlers`)
|
||||
|
||||
[buttonActionHandlers](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx#L1215-L1239)는 컴포넌트 파일 하단에 위치하며, 각 액션 문자열과 실행할 실제 비즈니스 함수를 1:1로 매핑합니다.
|
||||
|
||||
```typescript
|
||||
// apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx (Line 1215~1239)
|
||||
const buttonActionHandlers: Record<FnrsCnsltnViewButtonAction, ActionHandler> = {
|
||||
strg: handleSaveApply,
|
||||
aply: handleSaveApply,
|
||||
del: handleDel,
|
||||
envoSbmsn: handleChangePrgrsSttsComCd,
|
||||
rjct: handleRejectPrgrsStts, // <--- "rjct" 액션이 handleRejectPrgrsStts 함수로 바인딩됨
|
||||
sncnAprv: handleChangePrgrsSttsComCd,
|
||||
rvwRply: handleTechReview,
|
||||
rvwOpnnRply: handleTechReview,
|
||||
rqstTechRvw: handleRequestExamine,
|
||||
fileSplmnt: handleDmndSplmnt,
|
||||
fileVrfc: () => Promise.resolve(),
|
||||
dsgntRvwr: handleDsgntRvwr,
|
||||
pwrkCnsltnDocCrt: () => Promise.resolve(),
|
||||
pwrkCnsltnDocMng: () => Promise.resolve(),
|
||||
rvwRsltInq: () => Promise.resolve(),
|
||||
rvwStrg: handleTechReview,
|
||||
rvwCmptn: handleTechReview,
|
||||
dmndSplmnt: handleDmndSplmnt,
|
||||
atrzAprv: () => Promise.resolve(),
|
||||
atrzRply: () => Promise.resolve(),
|
||||
actnCmptn: handleActnCmptn,
|
||||
rqstActnRvw: handleRequestActnReview,
|
||||
costVrfc: () => Promise.resolve(),
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Step 4: 실제 비즈니스 API 호출 핸들러 (`handleRejectPrgrsStts`)
|
||||
|
||||
[handleRejectPrgrsStts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx#L1123-L1132) 함수는 전달받은 Context를 언팩하여 백엔드 REST API 서비스를 호출합니다.
|
||||
|
||||
```typescript
|
||||
// apps/as/src/pages/fnrs-cnsltn/ui/components/floating-action-buttons.tsx (Line 1123~1132)
|
||||
async function handleRejectPrgrsStts(
|
||||
context: ActionHandlerContext<DocPrgrsUpdateRequestDto>,
|
||||
): Promise<void> {
|
||||
try {
|
||||
// 백엔드 엔티티 서비스 호출
|
||||
await fnrsCnsltnMngService.rejectPrgrsStts(context.request);
|
||||
// 성공 시 executeAction의 onSuccess 실행
|
||||
context.onSuccess?.();
|
||||
} catch (error) {
|
||||
// 실패 시 executeAction의 onError 실행
|
||||
context.onError?.(error as Error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 백엔드 서비스 연동부 (`fnrsCnsltnMngService.rejectPrgrsStts`)
|
||||
```typescript
|
||||
// apps/as/src/entities/fnrs-cnsltn/api/fnrs-cnsltn-mng-service.ts
|
||||
async rejectPrgrsStts(body: DocPrgrsUpdateRequestDto): Promise<void> {
|
||||
await this.client.put<CommonResponse<void>>(
|
||||
"/api/v1/as/fnrs-cnsltn-mng/reject-prgrs-stts",
|
||||
body,
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 반려 처리 후 화면 갱신 메커니즘 (Post-Action Reaction)
|
||||
|
||||
`handleRejectPrgrsStts`가 성공적으로 종료된 후 화면이 자동으로 갱신되는 과정은 다음과 같습니다:
|
||||
|
||||
1. **콜백 체인 트리거**:
|
||||
`handleRejectPrgrsStts` -> `context.onSuccess()` 실행.
|
||||
2. **Alert 알림 표시**:
|
||||
사용자에게 `"반려되었습니다."` 안내 메시지 팝업 노출.
|
||||
3. **TanStack Query 캐시 무효화 (`invalidateQueries`)**:
|
||||
- `fnrsCnsltnKeys.detail(fnrsCnsltnDocNo)` 키를 가진 React Query 캐시가 Stale 상태로 마킹되어 백엔드로부터 최신 문서 상세 정보를 즉시 다시 조회합니다.
|
||||
- `[ENDPOINT.AS_ELAPR_SERVICE.ELAPR_BRANCH]` 키의 결재 분기 쿼리도 함께 무효화되어 결재선 및 버튼 상태가 재계산됩니다.
|
||||
4. **버튼 가시성 및 권한 자동 재계산**:
|
||||
- 상세 응답 DTO의 `detDto.prgrsSttsComCd`가 `"ST"`(신청완료)에서 `"SV"`(임시저장/작성중)로 변경됩니다.
|
||||
- [button-config.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/lib/button-config.ts)의 권한-상태 매트릭스(`ROLE_STATUS_BUTTON_ACTIONS`)에 따라 화면 하단 버튼이 반려/접수 모드에서 **수정/신청/삭제 모드**로 자동 전환됩니다.
|
||||
- [InstlSncnDetailGate](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/instl-sncn/ui/instl-detail-gate.tsx) 또는 상세 라우팅 규칙에 의해 지자체 작성자는 수정 페이지(`/edit`)로 접근할 수 있게 권한이 활성화됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 6. 요약 및 권장 개발 가이드라인
|
||||
|
||||
| 항목 | 구현 내용 | 아키텍처적 가치 |
|
||||
| :--- | :--- | :--- |
|
||||
| **액션 트리거** | `handleRjctClick` | 사용자 의사 확인(`confirm`) 및 DTO 캡슐화 |
|
||||
| **공통 처리** | `executeAction` | 로딩 상태(`isProcessing`), 에러 Alert, 캐시 무효화 일원화 |
|
||||
| **동적 디스패치** | `buttonActionHandlers[action]` | 조건문(if-else/switch) 없는 깔끔한 O(1) 룩업 테이블 |
|
||||
| **API 실행** | `handleRejectPrgrsStts` | 도메인 엔티티 서비스(`fnrsCnsltnMngService`)에 통신 위임 |
|
||||
| **화면 동기화** | `invalidateQueries` | 수동 상태 변이 없이 선언적 서버 상태 재동기화 |
|
||||
|
||||
다른 업무 모듈(`instl-sncn`, `pwrk-cnsltn`, `design-cnstn` 등) 개발 시에도 본 메커니즘과 동일하게 **`[ActionHandler] -> [buttonActionHandlers] -> [executeAction]`** 구조를 준수하여 구현하면 일관되고 견고한 엔터프라이즈 UI를 유지할 수 있습니다.
|
||||
@@ -1,183 +0,0 @@
|
||||
# 병합자 실무협의서(MAIN) 웹기안기 탭 전환 시 문서 초기화 이슈 및 해결방안
|
||||
|
||||
> **문서 대상**: `apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx`
|
||||
> **관련 모듈**: 재원협의·실무협의(`fnrs-cnsltn` / `pwrk-cnsltn`), 웹한글기안기(`@/widgets/hangulgiangi`), 전자결재(`elapr`)
|
||||
> **작성일**: 2026-10-23
|
||||
> **상태**: 구현 완료 (`PwrkCnsltnBranchRefPanel` 사이드 패널 Split View 적용 완료)
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요 (Overview)
|
||||
|
||||
재원협의(FNRS)의 하위 실무협의(PWRK) 프로세스 중 병렬 결재(Fork-Join, `TE`/`RK` 상태) 단계에서, **종합병합자(TOTAL_AGG 또는 ATRZ04 권한자)**는 관로(`SP`)와 시설(`SF`) 부서의 초안 및 검토 의견을 종합하여 최종 종합 실무협의서인 **`MAIN` 탭 문서를 편집·반영하고 저장**하는 법적·업무적 책임을 집니다.
|
||||
|
||||
현재 구현된 [PwrkCnsltnDocMngDialog](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx)에서는 병합자가 `MAIN` 문서를 수정하던 중 부서별 작성 내용을 확인하기 위해 `[관로 초안 (SP)]` 또는 `[시설 초안 (SF)]` 탭 버튼을 클릭하고 다시 `[종합 실무협의서 (MAIN)]` 탭으로 돌아왔을 때, **기안기 내부에서 편집 중이던 수정 내용이 모두 사라지고 서버에 저장된 원래 버전으로 초기화(Overwrite)되는 치명적인 데이터 유실 문제**가 발생하고 있습니다.
|
||||
|
||||
본 문서는 해당 현상의 근본 기술 원인을 분석하고, 병합자의 업무 흐름과 시스템 제약사항을 만족하는 실질적 해결 방안을 검토·제시합니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 현상 및 업무적 배경 (Business Context & Issue)
|
||||
|
||||
### 2.1 병합자의 역할 및 책임
|
||||
1. **수정 및 저장의 단일 주체**:
|
||||
- 병렬 결재(`isForkJoin === true`) 환경에서 관로(`SP`) 및 시설(`SF`) 부서의 1차 검토가 완료되면 병합자가 전체 내용을 종합합니다.
|
||||
- 병합자는 오직 **`MAIN` 종합본만 수정·저장**할 수 있으며, `SP`와 `SF` 문서는 수정 권한이 없고 **오직 참조(열람)만 가능**합니다 (`canSaveCurrentBranch` 조건 참조).
|
||||
2. **반영 및 대조(Cross-Check) 업무**:
|
||||
- 병합자는 `SP`의 검토 의견/사업비 조정 결과와 `SF`의 검토 의견/사업비 조정 결과를 문단별·항목별로 대조하며 `MAIN` 문서의 본문과 표를 직접 수기 편집(병합)해야 합니다.
|
||||
|
||||
### 2.2 발생 현상 (Problem Scenario)
|
||||
```
|
||||
[사용자 행동 흐름]
|
||||
1. 병합자가 다이얼로그 진입 시 기본 활성화된 [종합 실무협의서 (MAIN)] 탭에서 한글 문서 수정 시작
|
||||
2. 관로 부서가 수정한 상세 내역을 확인하기 위해 상단 [관로 초안 (SP)] 탭 버튼 클릭
|
||||
3. 관로 초안 확인 후, 다시 상단 [종합 실무협의서 (MAIN)] 탭 버튼 클릭
|
||||
4. 결과: 방금 전까지 작성/수정 중이던 MAIN 한글 문서 내용이 전부 사라지고 서버 원본으로 롤백됨
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 기술적 원인 분석 (Root Cause Analysis)
|
||||
|
||||
### 3.1 단일 웹한글기안기(iframe) 인스턴스 공유 및 무조건 문서 로드 (`HwpCtrl.Open`)
|
||||
[PwrkCnsltnDocMngDialog.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/components/pwrk-cnsltn-doc-mng-dialog.tsx#L357-L383)의 구조:
|
||||
```tsx
|
||||
// 탭 변경 시 targetBranchForApi 변경 -> React Query가 해당 탭의 최신 HWPX Blob 재조회
|
||||
const targetBranchForApi = isForkJoin ? currentBranchSeCd : undefined;
|
||||
const { data: documentBlob } = useQuery({
|
||||
queryKey: ["pwrk-cnsltn-doc-crt-rslt", ..., targetBranchForApi, ...],
|
||||
queryFn: () => pwrkCnsltnDocCrtRsltService.openWebHwpLatest(crtDmndUuid!, targetBranchForApi),
|
||||
});
|
||||
```
|
||||
|
||||
기안기 렌더링부:
|
||||
```tsx
|
||||
<HangulGiangi
|
||||
documentBlob={documentBlob}
|
||||
documentKey={`${completedDraft.crtDmndUuid}_${currentBranchSeCd}_${selectedVerSn ?? "latest"}`}
|
||||
...
|
||||
/>
|
||||
```
|
||||
|
||||
[HangulGiangi.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/widgets/hangulgiangi/ui/hangul-giangi.tsx#L120-L130)의 문서 로드 이펙트:
|
||||
```tsx
|
||||
useEffect(() => {
|
||||
if (!isCtrlReady || ...) return;
|
||||
// documentKey가 변경되면 기존 기안기 컨트롤에 새 Blob을 바로 Open해버림!
|
||||
openHwpxBlob(documentBlob, documentFileName);
|
||||
}, [documentBlob, documentFileName, documentKey, isCtrlReady, openHwpxBlob]);
|
||||
```
|
||||
|
||||
- 사용자가 탭을 전환하면 `currentBranchSeCd`가 바뀌면서 `documentKey`가 달라집니다.
|
||||
- 단일 iframe에 위치한 기안기 컨트롤러(`HwpCtrl`)는 즉시 `HwpCtrl.Open(documentFile)`을 실행하여 새로운 HWPX 문서를 캔버스에 로드합니다.
|
||||
- 이 과정에서 기안기 메모리 버퍼에 존재하던 `MAIN` 문서의 편집 변경사항은 **서버 저장이나 로컬 캐싱 없이 즉시 파기**됩니다.
|
||||
- 다시 `MAIN` 탭을 클릭하면 서버의 최신 저장본(`openWebHwpLatest`)이 다시 `Open`되므로, 작성 중이던 내용이 완전히 날아가게 됩니다.
|
||||
|
||||
### 3.2 변경 감지(Dirty Check) 및 화면 이탈 가드 부재
|
||||
- 한컴 웹기안기는 문서 수정 여부를 판별할 수 있는 프로퍼티(`HwpCtrl.IsModified`)를 제공하지만([ref-webhwp-api.md:L269](file:///Users/changwng/workspace.ona/frontend_as/apps/as/docs/pwrk-cnsltn/ref-webhwp-api.md#L269)), 탭 전환 이벤트 핸들러에서 이를 전혀 검사하지 않고 즉시 state를 변경합니다.
|
||||
- 미저장 변경사항이 있을 때 사용자에게 확인을 요청하는 컨펌/모달 가드가 없습니다.
|
||||
|
||||
### 3.3 UX 설계와 병합자 업무 특성의 불일치
|
||||
- 병합자는 `SP`/`SF`를 보면서 **동시에 `MAIN`에 입력·복사**해야 합니다.
|
||||
- 화면 전체를 `SP` $\leftrightarrow$ `MAIN`으로 번갈아 스위칭하는 단일 캔버스 탭 방식은 초기화 문제 외에도 **"앞서 본 내용을 외우거나 메모장에 복사한 뒤 탭을 넘나들어야 하는" 극심한 업무 비효율**을 초래합니다.
|
||||
|
||||
---
|
||||
|
||||
## 4. 해결 방안 비교 검토 (Solution Analysis)
|
||||
|
||||
| 평가 항목 | [방안 1] 병합자용 참조 문서 분할/별도 창 뷰어 제공 (강력 권장 ★★★★★) | [방안 2] 탭 전환 시 인메모리 Blob 임시 캐싱 | [방안 3] 탭 전환 시 Dirty Check 및 저장 강제 컨펌 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **개념** | `MAIN` 기안기는 항상 화면에 유지하고, `SP`/`SF`는 **별도 새 창(Window) 또는 팝업 모달/우측 패널**로 열람 | 탭 전환 시 `HwpCtrl.SaveAs`로 HWPX Blob을 추출해 React State/Ref에 임시 보관 후 복귀 시 재오픈 | 미저장 변경사항(`IsModified`)이 있을 때 탭 전환을 차단하고 서버에 먼저 저장하도록 유도 |
|
||||
| **초기화 방지** | **원천 차단** (`MAIN` 기안기 인스턴스가 절대 언로드되지 않음) | 해결 가능 (메모리에서 복구) | 해결 가능 (저장 후 이동) |
|
||||
| **병합 업무 편의성** | **최상** (듀얼 모니터 또는 분할 창으로 두 문서를 나란히 대조 가능) | 보통 (여전히 탭을 왔다 갔다 하며 외워서 작업해야 함) | 낮음 (SP 한번 보려면 MAIN 서버 저장 필수, 버전 폭증) |
|
||||
| **시스템 안정성** | **매우 높음** (복잡한 기안기 상태 관리 불필요) | 낮음 ~ 보통 (비동기 콜백 레이스 컨디션 및 메모리 누수 위험) | 보통 (불필요한 `verSn` 이력 증가) |
|
||||
| **구현 복잡도** | 낮음 ~ 보통 | 높음 | 낮음 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 상세 권장 해결책 (Recommended Architecture)
|
||||
|
||||
가장 안전하고 병합자의 업무 생산성을 극대화할 수 있는 **하이브리드 접근법(단계별 적용)**을 권장합니다.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph 병합자(TOTAL_AGG) 화면 구조
|
||||
MAIN_VIEW["MAIN 기안기 (항상 유지, 수정 내용 보존)"]
|
||||
BTN_SP["[관로(SP) 초안 새 창 열기 / 대조]"]
|
||||
BTN_SF["[시설(SF) 초안 새 창 열기 / 대조]"]
|
||||
GUARD{"탭 전환 시도 시<br/>HwpCtrl.IsModified 체크"}
|
||||
end
|
||||
|
||||
subgraph 별도 참조 뷰 (Popup / Window / Split)
|
||||
REF_SP["관로(SP) 읽기 전용 뷰어"]
|
||||
REF_SF["시설(SF) 읽기 전용 뷰어"]
|
||||
end
|
||||
|
||||
BTN_SP -->|독립 실행| REF_SP
|
||||
BTN_SF -->|독립 실행| REF_SF
|
||||
REF_SP -.동시 대조 및 MAIN에 복사/반영.-> MAIN_VIEW
|
||||
REF_SF -.동시 대조 및 MAIN에 복사/반영.-> MAIN_VIEW
|
||||
GUARD -->|미저장 내용 있음| WARN["경고 알림: 저장 후 이동 또는 취소"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 단계 1: 병합자를 위한 "SP / SF 참조 문서 별도 창 열람" 제공 (방안 1 적용 완료)
|
||||
|
||||
병합자에게 `SP`와 `SF`는 편집 대상이 아니라 **참조(열람) 대상**이므로, `MAIN` 기안기 화면을 전환하지 않고 별도 창(Popup Window)으로 띄워 듀얼 모니터나 분할 화면으로 대조할 수 있도록 구현했습니다.
|
||||
|
||||
#### 1) UI 액션 버튼 분기
|
||||
병합자(`isMerger === true`)가 `MAIN` 탭을 보고 있을 때, 상단 탭 영역 우측에 **독립 새 창 열기 버튼**을 배치:
|
||||
- `[관로(SP) 새 창 보기]`
|
||||
- `[시설(SF) 새 창 보기]`
|
||||
|
||||
#### 2) 새 창 열기 및 한컴 라이선스 오류 해결 메커니즘
|
||||
- **라이선스 오류 원인 및 해결**:
|
||||
- 기존 새 창 iframe 호출 시 `/webhwpctrl/index.html`로만 호출하여 `baseurl` 쿼리 파라미터가 누락되었고, 로컬 주소(`localhost:3004`)를 컨트롤 기본 URL로 인식하여 한컴 기안기 스크립트에서 `라이센스 오류` alert이 발생함.
|
||||
- 이를 해결하기 위해 `buildBridgeSrc(DEFAULT_BRIDGE_URL, WEBHYP_CTRL_URL)` 유틸 함수를 통해 `?baseurl=https://hwp.onasys.co.kr/webhwpctrl`이 안전하게 주입되도록 개선.
|
||||
- **HWPX 다운로드 Fallback 지원**:
|
||||
- 새 창 상단 헤더에 `[HWPX 다운로드]` 버튼을 함께 제공하여, 웹기안기 뷰어 외에도 로컬 한컴오피스 프로그램으로 즉시 문서를 내려받아 열람할 수 있도록 이중 보장.
|
||||
|
||||
---
|
||||
|
||||
### 단계 2: 탭 전환 시 Dirty Check 및 데이터 유실 방지 가드 (안전 가드 적용 완료)
|
||||
|
||||
만약 사용자가 기존 탭 버튼(`SP`, `SF`)을 눌러 탭을 전환하려고 시도할 때, 작성 중이던 내용이 소실되지 않도록 확인 가드를 배치했습니다.
|
||||
|
||||
#### 1) `HwpCtrl.IsModified` 감지 함수
|
||||
- `apps/as/src/widgets/hangulgiangi/lib/get-hwp-ctrl.ts`의 `getHwpCtrl(null)`을 통해 현재 활성화된 한컴 기안기 컨트롤의 `IsModified` 플래그를 실시간 확인.
|
||||
|
||||
#### 2) 탭 전환 및 창 닫기 안전 확인
|
||||
```typescript
|
||||
function checkDirtyAndConfirm(targetDesc: string): boolean {
|
||||
if (currentBranchSeCd === "MAIN") {
|
||||
try {
|
||||
const ctrl = getHwpCtrl(null);
|
||||
if (ctrl?.IsModified) {
|
||||
return window.confirm(
|
||||
`종합 실무협의서(MAIN)에 아직 저장되지 않은 수정 내용이 있습니다.\n` +
|
||||
`${targetDesc}(으)로 이동하면 작성 중인 내용이 초기화됩니다.\n\n` +
|
||||
`계속 진행하시겠습니까? (취소 후 [실무협의서 저장]을 권장합니다.)`
|
||||
);
|
||||
}
|
||||
} catch (e) {
|
||||
console.warn("기안기 변경 감지 실패:", e);
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 결론 및 적용 결과
|
||||
|
||||
1. **초기화 버그 원천 해결**:
|
||||
- `MAIN` 탭을 벗어나지 않고도 `[관로(SP) 새 창 보기]`, `[시설(SF) 새 창 보기]`를 통해 독립 팝업으로 각 부서의 원본 문서를 대조할 수 있어 `MAIN` 기안기 인스턴스가 절대 언로드되지 않습니다.
|
||||
- 실수로 탭을 누르거나 창을 닫으려 할 때도 `IsModified` 기반 안전 컨펌 창이 작동하여 데이터 유실을 100% 방지합니다.
|
||||
2. **새 창 웹기안기 라이선스 인증 정상화**:
|
||||
- 새 창 iframe의 브리지 URL에 `WEBHYP_CTRL_URL` 파라미터를 정상 바인딩하여 "라이센스 오류" alert을 근본적으로 제거하였습니다.
|
||||
- 새 창 헤더에 `[HWPX 다운로드]` 버튼을 추가하여 로컬 환경에서도 편리하게 문서를 열어볼 수 있도록 지원합니다.
|
||||
3. **단위 테스트 검증 완료**:
|
||||
- 총 19개 단위 테스트(`pnpm --filter as exec vitest run src/pages/fnrs-cnsltn/ui/__tests__/pwrk-cnsltn-doc-mng-dialog.test.tsx`)가 전체 통과(`19 passed (19)`)함을 검증했습니다.
|
||||
|
||||
@@ -1,236 +0,0 @@
|
||||
# TanStack Query 상세 데이터 캐시 동기화 이슈 및 해결방안
|
||||
|
||||
> **문서 대상**: `apps/as/src/entities/fnrs-cnsltn/api/queries.ts`, `apps/as/src/shared/lib/query-client.ts`
|
||||
> **관련 모듈**: 재원협의(`fnrs-cnsltn`), 실무협의(`pwrk-cnsltn`), 웹한글기안기(`@/widgets/hangulgiangi`), 인허가 공통(`instl-sncn`, `design-cnstn` 등)
|
||||
> **작성일**: 2026-10-23
|
||||
> **상태**: 분석 및 전체 코드 적용 완료 (검증 완료)
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요 (Overview)
|
||||
|
||||
재원협의(`fnrs-cnsltn`) 및 인허가 업무 프로세스는 지자체 담당자(신청자), 한국환경공단 담당자(검토자), 결재권자 등 **다수의 사용자가 실시간으로 문서를 조회·작성·보완·결재하는 다자간 협업 환경**입니다.
|
||||
|
||||
최근 운영 및 테스트 환경에서 **"목록 리스트에서 상세 화면으로 진입했을 때, 다른 사용자가 직전에 입력/수정한 최신 데이터가 바로 조회되지 않고, 브라우저 새로고침(F5, 새로 읽기)을 해야만 화면에 정상 표시되는 현상"**이 보고되었습니다.
|
||||
|
||||
본 문서는 해당 현상의 기술적 원인을 분석하고, TanStack Query(React Query) 캐시 시스템과의 충돌 여부 및 웹한글기안기 등 인접 기능에 미치는 영향을 검토한 뒤 실질적인 해결 방안을 정의합니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 현상 및 재현 시나리오 (Problem Scenario)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor UserA as 사용자 A (공단 검토자)
|
||||
actor UserB as 사용자 B (지자체 신청자)
|
||||
participant ClientA as 사용자 A 브라우저 (React Query)
|
||||
participant Server as 백엔드 API (Spring Boot / DB)
|
||||
|
||||
Note over UserA, ClientA: 1. 문서 1번 상세 조회 (최초 진입)
|
||||
UserA->>ClientA: 목록에서 문서 1번 클릭
|
||||
ClientA->>Server: GET /server/as/v1/fnrs-cnsltn-mng/1
|
||||
Server-->>ClientA: 200 OK (구 데이터 반환)
|
||||
ClientA->>ClientA: React Query 캐시에 저장 (staleTime: 60초 시작)
|
||||
UserA->>ClientA: 목록 화면으로 이동 (SPA 클라이언트 라우팅)
|
||||
|
||||
Note over UserB, Server: 2. 타 사용자의 데이터 수정 및 저장
|
||||
UserB->>Server: POST /server/as/v1/fnrs-cnsltn-mng (데이터 보완/수정 완료)
|
||||
Server-->>UserB: 200 OK (DB 최신화 완료)
|
||||
|
||||
Note over UserA, ClientA: 3. 60초 이내에 문서 1번 상세 재진입 (문제 발생!)
|
||||
UserA->>ClientA: 목록에서 문서 1번 다시 클릭
|
||||
Note over ClientA: ⚠️ staleTime(60초) 미경과로 캐시를 'fresh' 상태로 판단<br/>→ 서버 API 요청 없이 기존 구 캐시 데이터 반환!
|
||||
ClientA-->>UserA: 이전 구 데이터 화면 표시 (수정 내용 미반영)
|
||||
|
||||
Note over UserA, ClientA: 4. 브라우저 새로고침(F5 / 새로 읽기)
|
||||
UserA->>ClientA: 브라우저 새로고침 (F5)
|
||||
Note over ClientA: JS 런타임 메모리 초기화 → 캐시 삭제
|
||||
ClientA->>Server: GET /server/as/v1/fnrs-cnsltn-mng/1
|
||||
Server-->>ClientA: 200 OK (최신 데이터 반환)
|
||||
ClientA-->>UserA: 최신 데이터 정상 표시!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 기술적 근본 원인 분석 (Root Cause Analysis)
|
||||
|
||||
### 3.1 [핵심 원인] 전역 `staleTime: 60초` 캐싱 및 네트워크 요청 생략
|
||||
- **설정 파일**: [query-client.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/shared/lib/query-client.ts#L3-L11)
|
||||
```typescript
|
||||
export const queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: {
|
||||
retry: 1,
|
||||
refetchOnWindowFocus: false,
|
||||
staleTime: 60 * 1000, // 👈 60초(1분) 동안 캐시를 "fresh(신선한)" 상태로 간주
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
- **상세 쿼리**: [queries.ts: useFnrsCnsltnMng](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/entities/fnrs-cnsltn/api/queries.ts#L33-L39)
|
||||
```typescript
|
||||
export function useFnrsCnsltnMng(fnrsCnsltnDocNo: string | null | undefined) {
|
||||
return useQuery({
|
||||
queryKey: fnrsCnsltnKeys.detail(fnrsCnsltnDocNo!),
|
||||
queryFn: () => fnrsCnsltnMngService.findById(fnrsCnsltnDocNo!),
|
||||
enabled: Boolean(fnrsCnsltnDocNo),
|
||||
// ⚠️ staleTime이 지정되지 않아 전역 기본값인 60초가 그대로 상속됨
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### 동작 메커니즘
|
||||
1. TanStack Query는 데이터가 한 번 패칭되면 `staleTime`(60초) 동안 데이터를 `fresh` 상태로 취급합니다.
|
||||
2. 목록 화면에서 상세 화면으로 이동할 때(`router.push()`) 컴포넌트가 다시 마운트되더라도, 데이터가 `fresh` 상태이면 **네트워크 요청(refetch)을 일절 수행하지 않고 메모리 캐시를 그대로 반환**합니다.
|
||||
3. 본인이 직접 저장/수정(`mutation`)을 실행한 경우에는 `queryClient.invalidateQueries`가 호출되어 본인 브라우저 캐시는 무효화되지만, **다른 사용자의 브라우저에는 어떠한 무효화 신호도 전달되지 않습니다.**
|
||||
4. 따라서 다른 사용자가 실시간으로 문서를 변경하더라도 60초 동안은 무조건 구 데이터가 표시됩니다.
|
||||
5. 브라우저 새로고침(F5)을 누르면 SPA 런타임 메모리가 초기화되어 React Query 캐시가 사라지므로, 네트워크 요청을 새로 보내 최신 데이터가 조회되는 것입니다.
|
||||
|
||||
---
|
||||
|
||||
### 3.2 [부차 원인] 브라우저 HTTP GET 캐싱 (Cache-Control 부재)
|
||||
- [packages/common/network/client.ts](file:///Users/changwng/workspace.ona/frontend_as/packages/common/network/client.ts#L20-L27)의 Axios 인스턴스 기본 요청 헤더에 `Cache-Control: no-cache`가 설정되어 있지 않습니다.
|
||||
- 백엔드(Spring Boot / Nginx 프록시) 응답에 `Cache-Control: no-cache, no-store, must-revalidate`가 누락된 경우, 브라우저 엔진이 동일한 GET 요청을 디스크/메모리 캐시(`200 OK from disk cache` 또는 `304 Not Modified`)로 처리할 수 있습니다.
|
||||
- 브라우저 새로고침 시에는 브라우저가 강제로 `Cache-Control: max-age=0`을 포함하여 요청하므로 최신 데이터를 가져오게 됩니다.
|
||||
|
||||
---
|
||||
|
||||
### 3.3 [파생 이슈] 상세 게이트(`FnrsDetailGate`) 및 폼 페이지 영향
|
||||
1. **게이트 권한 판별 오작동**:
|
||||
- [fnrs-detail-gate.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/fnrs-detail-gate.tsx#L16-L21)는 상세 데이터의 진행상태(`prgrsSttsComCd`)를 기반으로 수정 권한(`canEditPbadmsDoc`)을 판별하여 `/edit` 페이지로 보낼지, 뷰 페이지로 보낼지 결정합니다.
|
||||
- 캐시로 인해 다른 사용자가 문서를 제출(`ST`)했음에도 이전 상태(임시저장 `SV`)로 남아있으면, 잘못된 페이지로 분기될 위험이 발생합니다.
|
||||
2. **React Hook Form 초기화 바인딩 문제**:
|
||||
- 수정 모드([fnrs-form-page.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/fnrs-form-page.tsx#L90-L97))에서는 `initialData`로 `useForm({ defaultValues: ... })`를 마운트 시점에 1회 초기화합니다.
|
||||
- 구 캐시 데이터로 폼이 초기화되면 사용자가 구 데이터를 기반으로 수정하여 덮어쓰는 동시성 충돌(Lost Update) 위험이 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 4. TanStack Query 캐시 기능과의 충돌 여부 검토
|
||||
|
||||
### 4.1 기본 캐시 메커니즘(`staleTime` vs `gcTime`)과의 충돌 여부
|
||||
|
||||
> **결론**: 상세 쿼리에 `staleTime: 0`을 설정하더라도 **TanStack Query의 캐시 기능과 전혀 충돌하지 않으며, TanStack Query 고유의 SWR(Stale-While-Revalidate) 아키텍처에 완벽히 부합**합니다.
|
||||
|
||||
- `staleTime`: 데이터가 신선하다고 간주되는 시간 $\rightarrow$ `0`으로 두면 진입 시 항상 최신성 검증(재요청).
|
||||
- `gcTime`(구 cacheTime): 사용되지 않는 캐시를 메모리에 유지하는 시간 $\rightarrow$ 기본 `5분` 유지.
|
||||
- **결과**: `staleTime: 0`이라 하더라도 기존 캐시가 메모리에 존재하므로, 화면 진입 시 **이전 데이터를 먼저 즉시 보여주어 화면 깜빡임(Flicker/Skeleton)을 방지**하고, 백그라운드에서 최신 데이터를 가져와 부드럽게 화면을 갱신합니다.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 인접 기능과의 잠재적 충돌 및 주의사항 3가지
|
||||
|
||||
| 구분 | 잠재적 충돌 위험 | 안전한 해결 규칙 |
|
||||
| :--- | :--- | :--- |
|
||||
| **전역 캐시 vs 개별 쿼리** | `queryClient.ts`의 전역 기본값을 `staleTime: 0`으로 변경 시 공통코드, 조직도, 회계트리 등 마스터 데이터 요청이 폭증함 | 전역 설정은 유지하고, **업무 상세 쿼리(`useFnrsCnsltnMng` 등)에만 국소적으로 `staleTime: 0` 부여** |
|
||||
| **웹한글기안기 (HWPX Blob)** | 기안기 Blob 쿼리에 `staleTime: 0` 또는 `refetchOnWindowFocus: true`가 걸리면, 다른 탭을 다녀올 때 Blob이 재조회되어 **편집 중이던 기안기 캔버스가 서버 원본으로 덮어써짐(데이터 유실)** | **웹기안기 Blob 쿼리는 자동 refetch 대상에서 제외**, 오직 저장 성공 시(`invalidateQueries`)에만 갱신 (분리 원칙) |
|
||||
| **수정 폼 (React Hook Form)** | 캐시 데이터로 `defaultValues`가 바인딩된 후 백그라운드 fetch가 완료되어도 RHF는 입력값 보호를 위해 자동 갱신하지 않음 | 수정 페이지 진입 시 최신 데이터 로딩 완료를 보장하거나, 뷰 페이지 위주로 `staleTime: 0`을 적극 활용 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 단계별 해결 방안 (Recommended Solutions)
|
||||
|
||||
### 단계 1: 상세 조회 쿼리에 도메인 캐시 정책 명시 (필수 적용 ★★★★★)
|
||||
|
||||
[apps/as/src/entities/fnrs-cnsltn/api/queries.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/entities/fnrs-cnsltn/api/queries.ts)의 `useFnrsCnsltnMng`에 업무 특성에 맞춘 옵션을 선언합니다.
|
||||
|
||||
```typescript
|
||||
export function useFnrsCnsltnMng(fnrsCnsltnDocNo: string | null | undefined) {
|
||||
return useQuery({
|
||||
queryKey: fnrsCnsltnKeys.detail(fnrsCnsltnDocNo!),
|
||||
queryFn: () => fnrsCnsltnMngService.findById(fnrsCnsltnDocNo!),
|
||||
enabled: Boolean(fnrsCnsltnDocNo),
|
||||
staleTime: 0, // 상세 화면 진입 시 항상 최신 데이터 조회 (fresh 상태 유지 해제)
|
||||
refetchOnMount: "always", // 마운트 시 항상 백그라운드 재조회 수행
|
||||
refetchOnWindowFocus: false, // 웹기안기 팝업이나 외부 창 이동 중 캔버스 리로드 방지를 위해 false 유지
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 단계 2: 클라이언트 Axios HTTP 캐시 방지 헤더 보강 (안전장치 적용)
|
||||
|
||||
브라우저 레벨의 HTTP 디스크/메모리 캐싱을 원천 방지하기 위해 [packages/common/network/client.ts](file:///Users/changwng/workspace.ona/frontend_as/packages/common/network/client.ts)에 캐시 제어 헤더를 주입합니다.
|
||||
|
||||
```typescript
|
||||
// packages/common/network/client.ts
|
||||
this.axiosInstance = axios.create({
|
||||
baseURL: config.baseURL,
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-Site-Id": config.siteId,
|
||||
"Cache-Control": "no-cache",
|
||||
"Pragma": "no-cache",
|
||||
},
|
||||
withCredentials: true,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 단계 3: 상세 화면 상단에 '새로고침(동기화)' UX 제공 (선택 권장)
|
||||
|
||||
전화나 메신저로 소통하며 실시간 결재/보완 작업을 진행하는 공단-지자체 업무 특성을 고려하여, 브라우저 전체(F5)를 새로고침하지 않고도 상세 데이터만 즉시 동기화할 수 있는 **동기화 버튼**을 상단 바에 배치합니다.
|
||||
|
||||
```tsx
|
||||
// apps/as/src/pages/fnrs-cnsltn/ui/fnrs-view-page.tsx
|
||||
const { data, refetch, isFetching } = useFnrsCnsltnMng(id);
|
||||
|
||||
// SectionCollapsibleToggle 옆에 배치:
|
||||
<Button
|
||||
type="button"
|
||||
variant="outline"
|
||||
size="sm"
|
||||
onClick={() => refetch()}
|
||||
disabled={isFetching}
|
||||
className="flex items-center gap-1"
|
||||
>
|
||||
<RefreshCw className={cn("size-4", isFetching && "animate-spin")} />
|
||||
<span>새로고침</span>
|
||||
</Button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 실제 코드 적용 내역 (Applied Implementation)
|
||||
|
||||
분석된 내용을 바탕으로 프로젝트 코드에 다음 사항들이 100% 적용되었습니다.
|
||||
|
||||
### 5.1 재원협의(`fnrs-cnsltn`) 상세 쿼리 캐시 정책 적용
|
||||
- **적용 파일**: [apps/as/src/entities/fnrs-cnsltn/api/queries.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/entities/fnrs-cnsltn/api/queries.ts)
|
||||
- `useFnrsCnsltnMng`, `useFnrsCnsltnFileVrfcResults`에 `staleTime: 0`, `refetchOnMount: "always"` 옵션 주입 완료.
|
||||
|
||||
### 5.2 타 인허가 모듈 확산 적용
|
||||
1. **설치인가(`instl-sncn`)**:
|
||||
- [apps/as/src/entities/instl-sncn/api/queries.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/entities/instl-sncn/api/queries.ts): `useInstlSncnDetail`에 `staleTime: 0`, `refetchOnMount: "always"` 적용 완료.
|
||||
2. **설계검토(`design-cnstn`)**:
|
||||
- [apps/as/src/entities/design-cnstn/api/queries.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/entities/design-cnstn/api/queries.ts): `useDesignCnstnMng`에 `staleTime: 0`, `refetchOnMount: "always"` 적용 완료.
|
||||
3. **기본계획(`sewer-bsc-plan`)**:
|
||||
- [apps/as/src/entities/sewer-bsc-plan/api/queries.ts](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/entities/sewer-bsc-plan/api/queries.ts): `useSewerBscPlan`, `useSewerBscPlanDetails`에 `staleTime: 0`, `refetchOnMount: "always"` 적용 완료.
|
||||
|
||||
### 5.3 클라이언트 Axios HTTP 캐시 방지 헤더 주입
|
||||
- **적용 파일**: [packages/common/network/client.ts](file:///Users/changwng/workspace.ona/frontend_as/packages/common/network/client.ts)
|
||||
- `axios.create`의 기본 헤더에 `Cache-Control: "no-cache"`, `Pragma: "no-cache"` 주입 완료.
|
||||
|
||||
### 5.4 전체 인허가 상세 조회 화면 상단 '새로 고침' 버튼 UX 적용
|
||||
상단 `sticky` 헤더 영역에 `refetch()`를 트리거하는 `[새로 고침]` 버튼 및 로딩 회전 애니메이션(`animate-spin`)을 일괄 적용 완료했습니다.
|
||||
1. **재원협의(`fnrs-cnsltn`)**: [apps/as/src/pages/fnrs-cnsltn/ui/fnrs-view-page.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/fnrs-cnsltn/ui/fnrs-view-page.tsx)
|
||||
2. **설치인가(`instl-sncn`)**: [apps/as/src/pages/instl-sncn/ui/instl-view-page.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/instl-sncn/ui/instl-view-page.tsx)
|
||||
3. **설계검토(`design-cnstn`)**: [apps/as/src/pages/design-cnstn/ui/design-view-page.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/design-cnstn/ui/design-view-page.tsx)
|
||||
4. **기본계획(`sewer-bsc-plan`)**: [apps/as/src/pages/sewer-bsc-plan/ui/sewer-bsc-plan-view-page.tsx](file:///Users/changwng/workspace.ona/frontend_as/apps/as/src/pages/sewer-bsc-plan/ui/sewer-bsc-plan-view-page.tsx)
|
||||
|
||||
---
|
||||
|
||||
## 6. 검증 및 결과
|
||||
|
||||
1. **TypeScript 컴파일 검증**:
|
||||
- `pnpm --filter as exec tsc --noEmit` $\rightarrow$ 에러 없이 100% 정상 통과.
|
||||
- `pnpm --filter @common/network exec tsc --noEmit` $\rightarrow$ 에러 없이 100% 정상 통과.
|
||||
2. **ESLint 정적 검사 통과**:
|
||||
- `pnpm --filter as lint` 및 `eslint --fix` 적용 완료.
|
||||
3. **적용 효과**:
|
||||
- 사용자가 목록에서 상세로 진입할 때마다 서버로부터 항상 최신 데이터를 재조회하여 화면에 반영.
|
||||
- 이전 캐시가 존재할 경우 SWR 패턴에 따라 깜빡임 없이 즉시 렌더링된 후 백그라운드 최신화 완료.
|
||||
- 웹한글기안기 HWPX Blob 쿼리는 영향받지 않아 캔버스 덮어쓰기 위험 원천 방지.
|
||||
|
||||
@@ -1,250 +0,0 @@
|
||||
# 재원협의·실무협의 프론트엔드 개발 가이드
|
||||
|
||||
> **대상 앱**: `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`.
|
||||
|
||||
---
|
||||
@@ -1,334 +0,0 @@
|
||||
# 레퍼런스 — 상태별 Endpoint
|
||||
|
||||
> 상위: [개발가이드.md](./개발가이드.md)
|
||||
> SoT: `05.재원협의_상태별_endpoint_설계.md` (v1.0, 2026-09-03)
|
||||
> Gateway: `/as-service`, `/as-elapr-service`
|
||||
> Auth: `Authorization`, `X-Site-Id`, `token-id` (기존 `client` 인터셉터)
|
||||
> 날짜: `yyyy-MM-dd HH:mm:ss`
|
||||
|
||||
프론트가 치는 API만 상세히 적는다. AI 콜백·스케줄러·Feign은 [§6 호출 금지](#6-프론트-호출-금지).
|
||||
|
||||
---
|
||||
|
||||
## 1. 총괄 매트릭스 (38 + WebHWP)
|
||||
|
||||
| 순번 | 버튼 | From → To | 서비스 | Method & URI | 구분 |
|
||||
| :---: | --- | --- | --- | --- | --- |
|
||||
| 1 | 저장 | →`SV` | as | `POST /api/v1/fnrs-cnsltn-mng/save-apply` | 기존 |
|
||||
| 2 | 신청완료 | `SV→ST` | as | 동일 (`prgrsSttsComCd=ST`) | 기존 |
|
||||
| 3 | 삭제 | `SV` | as | `DELETE /api/v1/fnrs-cnsltn-mng/{docNo}` | 기존 |
|
||||
| 4 | 환경청제출 | `ST→LE` | as | `POST /api/v1/fnrs-cnsltn-mng/doc/updatePrgrsStts` | 기존 |
|
||||
| 5 | 결과회신(자체종결) | `LE→EP` | as | `POST /api/v1/fnrs-cnsltn-mng/{docNo}/tech-review` | 기존 |
|
||||
| 6 | 기술검토 의뢰 | `LE→FV` | as | `POST /api/v1/fnrs-cnsltn-mng/{docNo}/request-examine` | **신규** |
|
||||
| 7 | 파일검증 콜백 | `FV→ER` | as | `POST /api/v1/dcrag/documents/verify-result` | 서버 |
|
||||
| 8 | 파일보완 팝업 | `ER` | as | `GET /api/v1/fnrs-cnsltn-mng/{docNo}/file-vrfc-results` | 기존 |
|
||||
| 9 | 파일보완요청 | `ER→SL` | as | `POST /api/v1/fnrs-cnsltn-mng/{docNo}/reqsupplement` | 기존 |
|
||||
| 10 | 파일검증 재실행 | `ER` | as | `POST /api/v1/dcrag-to/documents/transfer` | 기존 |
|
||||
| 11 | 검토자지정 | `ER→AC` | elapr | `POST /api/v1/elapr-dmnd` | 기존 |
|
||||
| 12 | 초안 콜백 | `AC→TE` | as | `POST /api/v1/dcrag/draft/complete` | 서버 |
|
||||
| 13 | 실무협의서관리 | `TE` | as | `GET /api/v1/pwrk-cnsltn-mng/updocno/{upDocNo}` | 기존 |
|
||||
| 14 | 검토결과조회 | `TE` | as | `GET /api/v1/pwrk-cnsltn-mng/{pwrkDocNo}` | 기존 |
|
||||
| 15 | 실무협의서생성 | `TE` | as | `POST /api/v1/dcrag-to/documents/draft/generate` | 기존 |
|
||||
| 16 | 저장(실무) | `TE` | as | `POST /api/v1/pwrk-cnsltn-mng/save-apply` | 기존 |
|
||||
| 17 | 검토완료 | `TE` | elapr | `PUT /api/v1/elapr-prgrs-stts/{id}/process` | 기존 |
|
||||
| 18 | 보완요청 | `TE→SL` | as | `POST .../reqsupplement` | 기존 |
|
||||
| 19 | 결재(승인) | `TE` | elapr | `PUT .../process` | 기존 |
|
||||
| 20 | 결재(회신) | `TE→TP` | elapr | `PUT .../process` | 기존 |
|
||||
| 21 | 파일보완완료 | `SL→ER` | as | `POST .../submitsupplement` | 기존 |
|
||||
| 22 | 보완완료(기술) | `SL→TE` | as | 동일 | 기존 |
|
||||
| 23 | 보완완료(조치) | `SL→RK` | as | 동일 | 기존 |
|
||||
| 24 | 재원협의 결과 회신 | `TP→RM` | as | `POST .../{docNo}/tech-review` | 기존 |
|
||||
| 25 | 지자체회신 | `RM→RB` | as | `POST .../doc/updatePrgrsStts` | 기존 |
|
||||
| 26 | 실무협의서 관리 | `RB` | as | `GET .../pwrk-cnsltn-doc-crt-rslt/{uuid}/webhwp/open` | 기존 |
|
||||
| 27 | 조치완료 | `RB→RA` | as | `POST /api/v1/pwrk-cnsltn-mng/{pwrkDocNo}/submit-actn-result` (`isSubmit=true`) | **신규** |
|
||||
| 28 | 조치결과서제출 | `RC→RA` | as | `updatePrgrsStts` | 기존 |
|
||||
| 29 | 조치결과 검토의뢰 | `RA→AV` | as | `POST /api/v1/fnrs-cnsltn-mng/{docNo}/request-actn-review` | **신규** |
|
||||
| 30 | 금액검증 콜백 | `AV→EV` | as | `POST /api/v1/dcrag/cost/verify-result` | 서버 |
|
||||
| 30a | 검토자지정(2차) | `EV→RK` | elapr | `POST /api/v1/elapr-dmnd` (`elaprCycl=2`) | 기존 |
|
||||
| 31 | 실무협의서관리 | `RK` | as | `GET /pwrk-cnsltn-mng/{pwrkDocNo}` | 기존 |
|
||||
| 32 | 금액검증 재실행 | `RK` | as | `POST /api/v1/dcrag-to/documents/cost/verify` | 기존 |
|
||||
| 33 | 보완요청(금액) | `RK→SL` | as | `reqsupplement` | 기존 |
|
||||
| 34 | 결재(승인) | `RK` | elapr | `process` | 기존 |
|
||||
| 35 | 결재(회신) | `RK→RR` | elapr | `process` | 기존 |
|
||||
| 36 | 결과회신 | `RR→EP` | as | `updatePrgrsStts` | 기존 |
|
||||
| 37 | 결과회신 | `EP→TA` | as | `updatePrgrsStts` | 기존 |
|
||||
| 38 | 결과회신(확인) | `TA` | — | 없음 | — |
|
||||
| W1 | 웹기안기 Open | — | as | `GET /api/v1/pwrk-cnsltn-doc-crt-rslt/{uuid}/webhwp/open` | 기존 |
|
||||
| W2 | HWPX 저장 | — | as | `POST /api/v1/pwrk-cnsltn-doc-crt-rslt` multipart | 기존 |
|
||||
| W3 | 다운로드 | — | as | `GET /api/v1/pwrk-cnsltn-doc-crt-rslt/{uuid}/download` | 기존 |
|
||||
| E-N | 결재선 복사 | `AV→RK` 부수 | elapr | `POST /api/v1/elapr-apln/copy-line` | **신규·서버** |
|
||||
|
||||
조회 공통: `GET /fnrs-cnsltn-mng`, `GET /fnrs-cnsltn-mng/{docNo}`, `GET /pwrk-cnsltn-mng`, `GET /dcrag-to/documents/draft/status/{crtDmndUuid}`.
|
||||
|
||||
---
|
||||
|
||||
## 2. 공통 요청
|
||||
|
||||
### `DocPrgrsUpdateRequestDto`
|
||||
|
||||
`POST /fnrs-cnsltn-mng/doc/updatePrgrsStts` — `ST→LE`, `RM→RB`, `RC→RA`, `RR→EP`, `EP→TA`.
|
||||
|
||||
```json
|
||||
{
|
||||
"docNo": "F-20260824-0001",
|
||||
"docSeComCd": "FNRS",
|
||||
"prgrsSttsComCd": "LE",
|
||||
"rgtrUuid": "optional-uuid",
|
||||
"rmrk": "optional"
|
||||
}
|
||||
```
|
||||
|
||||
응답: `204/200` void. 프론트 엔티티: 기존 `changePrgrsSttsComCd`.
|
||||
|
||||
### `FnrsCnsltnApplySaveRequestDto`
|
||||
|
||||
`save-apply`, `tech-review`, `reqsupplement`, `submitsupplement`가 공유. 핵심은 `fnrsCnsltnMng.prgrsSttsComCd`와 중첩 리스트(`bzScaleList`, `bizCstList`, `cklstResultList`, `esntlAtchFileList`, `splmntDmndList`).
|
||||
|
||||
---
|
||||
|
||||
## 3. 단계별 FE API
|
||||
|
||||
### 3-1. `SV → ST → LE`
|
||||
|
||||
**저장 / 신청완료** — `POST /fnrs-cnsltn-mng/save-apply`
|
||||
권한: `ROLE_USER05`. 임시저장은 `prgrsSttsComCd=SV`, 신청은 `ST`.
|
||||
응답: `string` (문서번호). 기존 `fnrsCnsltnMngService.saveApply`.
|
||||
|
||||
**삭제** — `DELETE /fnrs-cnsltn-mng/{docNo}` (`SV`만).
|
||||
|
||||
**환경청제출** — `updatePrgrsStts` `LE`. 권한: `ROLE_USER04`.
|
||||
|
||||
### 3-2. `LE → FV | EP`
|
||||
|
||||
**자체종결** — `POST /fnrs-cnsltn-mng/{docNo}/tech-review`
|
||||
Body: `FnrsCnsltnApplySaveRequestDto` (환경청 의견·체크리스트). `LE→EP`.
|
||||
기존 `techReview`. 현재 화면은 `TP`에서도 이 API를 쓰며 목표 상태를 `EP`로 넣고 있다 → **`TP`는 `RM`으로 바꿔야 함**.
|
||||
|
||||
**기술검토 의뢰 (신규)** — `POST /fnrs-cnsltn-mng/{docNo}/request-examine`
|
||||
|
||||
```json
|
||||
{ "prgrsSttsComCd": "FV" }
|
||||
```
|
||||
|
||||
응답: `string` (docNo). `LE→FV` + AI 파일검증 + 30분 타이머(서버).
|
||||
프론트: `fnrsCnsltnMngService.requestExamine(docNo, body)` 추가. **`updatePrgrsStts("ER")` 금지.**
|
||||
|
||||
### 3-3. `FV → ER → SL → ER`
|
||||
|
||||
파일검증 콜백은 서버. FE는 `FV`에서 상세 refetch.
|
||||
|
||||
**검증결과 목록** — `GET /fnrs-cnsltn-mng/{fnrsCnsltnDocNo}/file-vrfc-results`
|
||||
응답: `FnrsCnsltnFileVrfcRsltResponseDto[]`
|
||||
|
||||
| 필드 | 설명 |
|
||||
| --- | --- |
|
||||
| `fileSeComCd` | `ESSENTIAL` / `ADDITIONAL` |
|
||||
| `fileSeNm` | 구분명 |
|
||||
| `esntlAtchFileId` | 필수첨부 ID |
|
||||
| `atchFileNm` | 파일명 |
|
||||
| `vrfcRsltComCd` | `PASS` / `FAIL` / `WARN` |
|
||||
| `vrfcOpnn` | 검증의견 |
|
||||
|
||||
엔티티에 `findFileVrfcResults` 추가. 첨부 행 배지는 상세 `esntlFileList`/`etcFileList`의 `vrfcSttsComCd`, `vrfcRsltCn`, `vrfcDt`도 사용 (타입 확장 필요).
|
||||
|
||||
**파일보완요청** — `POST .../{docNo}/reqsupplement` (`ER→SL`).
|
||||
**파일보완완료** — `POST .../{docNo}/submitsupplement` (`SL→ER`). 복귀는 서버.
|
||||
|
||||
**파일검증 재실행** — `POST /dcrag-to/documents/transfer`
|
||||
|
||||
```json
|
||||
{ "fnrsCnsltnDocNo": "F-20260824-0001", "taskSeComCd": "SF", "taskSeCdNm": "하수처리시설" }
|
||||
```
|
||||
|
||||
응답: `{ resultCode, message, requestId }`. 상태 유지. 기존 `dcRagApiToService.requestDocumentTransfer`.
|
||||
|
||||
### 3-4. `ER → AC → TE → TP`
|
||||
|
||||
**검토자지정** — `POST /elapr-dmnd`
|
||||
기존 `elaprDmndService.save`.
|
||||
|
||||
| 필드 | 값 |
|
||||
| --- | --- |
|
||||
| `elaprDocNo` | 재원협의 번호 |
|
||||
| `elaprCycl` | `1` |
|
||||
| `docPrgrsSttsComCd` | **`AC`** (현행은 현재 상태 `ER`를 넣고 있음 → 수정) |
|
||||
| `elaprPrgrsSttsList[].atrzOrdr` | 1 검토자, 2 승인자, 3 최종 |
|
||||
|
||||
서버가 실무협의 문서 생성 + RAG 초안 트리거 + 30분 타이머. 응답의 문서번호/`crtDmndUuid`가 있으면 폴링 키로 쓴다. 없으면 `findByUpDocNo`로 복원.
|
||||
|
||||
**초안 상태 폴링** — `GET /dcrag-to/documents/draft/status/{crtDmndUuid}`
|
||||
기존 `getDraftGenerationStatus`. 주기 5~10초. 종료 `COMPLETED`/`FAILED`.
|
||||
|
||||
**수동 초안생성** — `POST /dcrag-to/documents/draft/generate` (`TE` 유지)
|
||||
|
||||
```json
|
||||
{
|
||||
"fnrsCnsltnDocNo": "F-...",
|
||||
"pwrkCnsltnDocNo": "P-...",
|
||||
"crtDmndUuid": "optional"
|
||||
}
|
||||
```
|
||||
|
||||
202 + `DcRagDraftGenerateResponseDto` (`crtDmndUuid`, `crtSttsComCd`, `estimatedMinutes`).
|
||||
v1.0 가이드의 “이 API를 프론트가 치면 안 된다”는 **폐기**. 1차 트리거는 검토자지정이고, 이 API는 Fallback 전용.
|
||||
|
||||
**실무 저장** — `POST /pwrk-cnsltn-mng/save-apply` → `string`.
|
||||
**보완요청/완료** — fnrs `reqsupplement` / `submitsupplement`.
|
||||
|
||||
**결재** — `PUT /elapr-prgrs-stts/{elaprPrgrsId}/process`
|
||||
|
||||
```json
|
||||
{
|
||||
"atrzPrgrsSttsComCd": "ATRZ_PRGRS_003",
|
||||
"atrzOpnnCn": "의견",
|
||||
"finalApprovalYn": false
|
||||
}
|
||||
```
|
||||
|
||||
반려: `ATRZ_PRGRS_004`. 기존 `elaprPrgrsSttsService.process`. 최종 시 서버가 `TP`/`RR` 전이.
|
||||
|
||||
### 3-5. `TP → RM → RB → RA`
|
||||
|
||||
**환경청 1차 회신** — `tech-review` (`TP→RM`).
|
||||
**광역 지자체회신** — `updatePrgrsStts` `RB`.
|
||||
|
||||
**조치완료 (신규)** — `POST /pwrk-cnsltn-mng/{pwrkDocNo}/submit-actn-result`
|
||||
|
||||
```json
|
||||
{
|
||||
"isSubmit": true,
|
||||
"actnList": [
|
||||
{
|
||||
"rvwOpnnSn": 1,
|
||||
"actnRsltCn": "수용 — 관로 연장 재산정",
|
||||
"atchFileGroupId": "optional"
|
||||
}
|
||||
],
|
||||
"totActnSummary": "제출 시 권장",
|
||||
"muniDocNo": "제출 시 권장"
|
||||
}
|
||||
```
|
||||
|
||||
- `isSubmit: false` → `RB` 유지 (API만 존재, **화면 버튼 없음**. HWP·첨부는 실무협의서 관리 다이얼로그에서 저장)
|
||||
- `isSubmit: true` → `RB→RA` (조치완료)
|
||||
응답: `string` (pwrkDocNo). DTO명 `PwrkActnResultSubmitDto`.
|
||||
|
||||
### 3-6. `RA → AV → EV → RK`
|
||||
**2차 의뢰 (신규)** — `POST /fnrs-cnsltn-mng/{docNo}/request-actn-review`
|
||||
|
||||
```json
|
||||
{
|
||||
"specialRqstCn": "중점 검증 요청 (선택)"
|
||||
}
|
||||
```
|
||||
|
||||
`RA→AV`. 응답: `string` (docNo). DTO명 `EnvoActnReviewReqDto`. `specialRqstCn`만 선택.
|
||||
|
||||
금액검증 콜백은 서버 → `AV→EV`.
|
||||
**2차 검토자지정** — `POST /elapr-dmnd` (`elaprCycl: 2`, `docPrgrsSttsComCd: RK`). 1차 결재선(`findDocPrgrsByDocNo`, cycl=1)을 시드로 편집.
|
||||
|
||||
**금액검증 재실행** — `POST /dcrag-to/documents/cost/verify`
|
||||
|
||||
```json
|
||||
{
|
||||
"fnrsCnsltnDocNo": "F-...",
|
||||
"pwrkCnsltnDocNo": "P-..."
|
||||
}
|
||||
```
|
||||
|
||||
202. 기존 `requestCostVerification`. `RK` 유지.
|
||||
|
||||
### 3-7. `RK → RR | SL`
|
||||
|
||||
보완은 3-4와 동일 API. 팝업만 금액 체크.
|
||||
결재 `process` 2차 최종 → 서버가 `RR`.
|
||||
|
||||
### 3-8. `RR → EP → TA`
|
||||
|
||||
둘 다 `updatePrgrsStts`. `TA` 확인은 API 없음.
|
||||
|
||||
---
|
||||
|
||||
## 4. 웹기안기
|
||||
|
||||
설계서 기준 **기존**. 구현 시 컨트롤러 존재 여부를 확인한다.
|
||||
|
||||
| ID | 용도 | URI | 응답 |
|
||||
| --- | --- | --- | --- |
|
||||
| W1 | 웹기안기 Open | `GET .../pwrk-cnsltn-doc-crt-rslt/{crtDmndUuid}/webhwp/open` | `inline` HWPX blob → `HwpCtrl.Open(File)` |
|
||||
| W2 | 편집 저장 | `POST .../pwrk-cnsltn-doc-crt-rslt` multipart `file` + `crtDmndUuid` | 201, `verSn+1` |
|
||||
| W3 | PC 저장 | `GET .../{crtDmndUuid}/download` | `attachment` blob |
|
||||
|
||||
버전 지정: `GET .../{crtDmndUuid}/{verSn}/webhwp/open`, `.../{verSn}/download`.
|
||||
`/{uuid}/latest`, `/{uuid}/download`가 `/{uuid}/{verSn}`보다 우선. path를 섞지 말 것.
|
||||
|
||||
다운로드:
|
||||
|
||||
- axios `responseType: "blob"`
|
||||
- 파일명: `Content-Disposition` `filename*=UTF-8''...` (`parseFilenameFromResponse`)
|
||||
- 서버 파일명: `재원협의 실무협의서({bizNm})_v{verSn}.hwp`
|
||||
- Content-Type은 `application/x-hwp` 또는 `application/haansofthwpx`일 수 있음. 타입에 의존하지 말 것
|
||||
|
||||
Open은 axios `responseType: "blob"`으로 인증된 API를 호출하고, 응답 Blob을 HWPX `File`로 감싸 `HwpCtrl.Open`에 전달한다. `blob:` Object URL은 사용하지 않는다.
|
||||
|
||||
multipart `Content-Type` 헤더를 수동 지정하지 않는다 (boundary). JSON `saveJson`은 UI에서 쓰지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 5. 전자결재 (`as-elapr-service`)
|
||||
|
||||
| API | URI | FE |
|
||||
| --- | --- | --- |
|
||||
| 검토자지정·1차 결재요청 | `POST /elapr-dmnd` | O |
|
||||
| 결재 처리 | `PUT /elapr-prgrs-stts/{id}/process` | O |
|
||||
| 결재선 복사 | `POST /elapr-apln/copy-line` | **X (서버)** |
|
||||
|
||||
`copy-line` body (참고만):
|
||||
|
||||
```json
|
||||
{
|
||||
"docNo": "P-20260827-0001",
|
||||
"sourceElaprCycl": 1,
|
||||
"targetElaprCycl": 2,
|
||||
"rgtrUuid": "system-uuid"
|
||||
}
|
||||
```
|
||||
|
||||
`RK`에서 결재현황은 `findDocPrgrsByDocNo`(전체) 조회 후 `elaprCycl`로 1차/2차 탭 표시.
|
||||
|
||||
---
|
||||
|
||||
## 6. 프론트 호출 금지
|
||||
|
||||
| URI | 이유 |
|
||||
| --- | --- |
|
||||
| `POST /dcrag/documents/verify-result` | AI→AS 콜백 |
|
||||
| `POST /dcrag/draft/complete` | AI→AS 콜백 |
|
||||
| `POST /dcrag/cost/verify-result` | AI→AS 콜백. 여기서 copy-line도 호출 |
|
||||
| `POST /elapr-apln/copy-line` | 콜백 Feign |
|
||||
| `POST /pwrk-cnsltn-mng` (`save` 초안 트리거) | v3.0 1차 트리거는 `elapr-dmnd`. 컨트롤러가 남아 있어도 화면에서 쓰지 않음 |
|
||||
|
||||
`POST /dcrag-to/documents/draft/generate`는 **Fallback에서만** 허용.
|
||||
|
||||
---
|
||||
|
||||
## 7. Gap Analysis (프론트 엔티티)
|
||||
|
||||
### 이미 있는 것
|
||||
|
||||
`fnrsCnsltnMngService`: `findPage`, `findById`, `save`, `saveApply`, `update`, `techReview`, `submitSupplement`, `submitReqSupplement`, `remove`, `changePrgrsSttsComCd`
|
||||
`dcRagApiToService`: `requestDocumentTransfer`, `requestDraftGeneration`, `getDraftGenerationStatus`, `requestCostVerification`
|
||||
`elaprDmndService.save`, `elaprPrgrsSttsService.process`
|
||||
|
||||
### 추가할 것
|
||||
|
||||
| 메서드 | URI |
|
||||
| --- | --- |
|
||||
| `requestExamine` | `POST /fnrs-cnsltn-mng/{id}/request-examine` |
|
||||
| `findFileVrfcResults` | `GET /fnrs-cnsltn-mng/{id}/file-vrfc-results` |
|
||||
| `requestActnReview` | `POST /fnrs-cnsltn-mng/{id}/request-actn-review` |
|
||||
| `pwrkCnsltnMngService.*` | 슬라이스 신규 |
|
||||
| `submitActnResult` | `POST /pwrk-cnsltn-mng/{id}/submit-actn-result` |
|
||||
| `pwrkCnsltnDocCrtRsltService.*` | 슬라이스 신규 |
|
||||
|
||||
`copyLine`은 프론트 서비스에 넣지 않는다.
|
||||
@@ -1,350 +0,0 @@
|
||||
# 레퍼런스 — 프론트 엔티티·DTO
|
||||
|
||||
> 상위: [개발가이드.md](./개발가이드.md)
|
||||
> 엔티티 규칙: `frontend/.cursor/skills/backend-controller-to-entity`
|
||||
|
||||
---
|
||||
|
||||
## 1. ENDPOINT
|
||||
|
||||
`apps/as/src/shared/config/api.ts`
|
||||
|
||||
```ts
|
||||
AS_SERVICE: {
|
||||
// 기존
|
||||
FNRS_CNSLTN_MNG: "/as-service/api/v1/fnrs-cnsltn-mng",
|
||||
DCRAG_TO: "/as-service/api/v1/dcrag-to",
|
||||
// 추가
|
||||
PWRK_CNSLTN_MNG: "/as-service/api/v1/pwrk-cnsltn-mng",
|
||||
PWRK_CNSLTN_DOC_CRT_RSLT: "/as-service/api/v1/pwrk-cnsltn-doc-crt-rslt",
|
||||
}
|
||||
|
||||
AS_ELAPR_SERVICE: {
|
||||
ELAPR_TMPLT: "/as-elapr-service/api/v1/elapr-tmplt",
|
||||
ELAPR_APLN: "/as-elapr-service/api/v1/elapr-apln",
|
||||
ELAPR_DMND: "/as-elapr-service/api/v1/elapr-dmnd",
|
||||
ELAPR_PRGRS_STTS: "/as-elapr-service/api/v1/elapr-prgrs-stts",
|
||||
}
|
||||
```
|
||||
|
||||
`copy-line`은 `ELAPR_APLN` 하위이나 FE에서 호출하지 않음.
|
||||
|
||||
---
|
||||
|
||||
## 2. 슬라이스 배치
|
||||
|
||||
```
|
||||
entities/fnrs-cnsltn/ # 확장
|
||||
entities/dcrag-to/ # 구현됨
|
||||
entities/elapr/ # 구현됨
|
||||
entities/pwrk-cnsltn-mng/ # 신규
|
||||
entities/pwrk-cnsltn-doc-crt-rslt/ # 신규
|
||||
```
|
||||
|
||||
```
|
||||
entities/pwrk-cnsltn-mng/
|
||||
├── model/
|
||||
│ ├── pwrk-cnsltn-mng-interface.ts
|
||||
│ └── pwrk-cnsltn-mng-payload-schema.ts
|
||||
├── api/
|
||||
│ ├── pwrk-cnsltn-mng-service.ts
|
||||
│ └── queries.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
`submit-actn-result` Request는 zod SSOT (`PwrkActnResultSubmitDto`).
|
||||
`request-examine` / `request-actn-review`도 fnrs payload-schema에 추가.
|
||||
|
||||
라우트:
|
||||
|
||||
| 화면 | 경로 |
|
||||
| --- | --- |
|
||||
| 재원협의 목록/상세/작성 | 기존 `app/(main)/(with-base-layout)/fnrs-cnsltn/...` |
|
||||
| 실무협의 목록 | `.../pwrk-cnsltn/page.tsx` (선택) |
|
||||
| 실무협의 상세 | `.../pwrk-cnsltn/[id]/page.tsx` (선택) |
|
||||
| 페이지 UI | `pages/fnrs-cnsltn/`, `pages/pwrk-cnsltn/` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Service 시그니처
|
||||
|
||||
`fnrsCnsltnMngService`에 추가:
|
||||
|
||||
```ts
|
||||
requestExamine(docNo: string, body: FnrsExamineRequestDto): Promise<string>;
|
||||
findFileVrfcResults(fnrsCnsltnDocNo: string): Promise<FnrsCnsltnFileVrfcRsltResponseDto[]>;
|
||||
requestActnReview(docNo: string, body: EnvoActnReviewReqDto): Promise<string>;
|
||||
```
|
||||
|
||||
실무협의:
|
||||
|
||||
```ts
|
||||
export interface PwrkCnsltnMngService {
|
||||
findPage(searchDto: PwrkCnsltnMngSearchDto): Promise<PageResponse<PwrkCnsltnMngResponseDto>>;
|
||||
findById(pwrkCnsltnDocNo: string): Promise<PwrkCnsltnMngDetResponseDto>;
|
||||
findByUpDocNo(upDocNo: string): Promise<PwrkCnsltnMngDetResponseDto>;
|
||||
saveApply(body: PwrkCnsltnApplySaveRequestDto): Promise<string>;
|
||||
submitActnResult(
|
||||
pwrkCnsltnDocNo: string,
|
||||
body: PwrkActnResultSubmitDto,
|
||||
): Promise<string>;
|
||||
update(pwrkCnsltnDocNo: string, body: PwrkCnsltnMngUpdateRequestDto): Promise<string>;
|
||||
remove(pwrkCnsltnDocNo: string): Promise<void>;
|
||||
changePrgrsSttsComCd(body: DocPrgrsUpdateRequestDto): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
v1.0의 `save(): PwrkCnsltnMngSaveResponseDto`(초안 트리거)는 화면에서 사용하지 않는다. 컨트롤러가 남아 있으면 엔티티에 넣더라도 UI 연결 금지.
|
||||
|
||||
생성결과:
|
||||
|
||||
```ts
|
||||
export interface PwrkCnsltnDocCrtRsltService {
|
||||
findPage(
|
||||
searchDto: PwrkCnsltnDocCrtRsltSearchDto,
|
||||
): Promise<PageResponse<PwrkCnsltnDocCrtRsltResponseDto>>;
|
||||
findById(crtDmndUuid: string, verSn: number): Promise<PwrkCnsltnDocCrtRsltResponseDto>;
|
||||
findLatestByCrtDmndUuid(crtDmndUuid: string): Promise<PwrkCnsltnDocCrtRsltResponseDto>;
|
||||
openWebHwpLatest(crtDmndUuid: string): Promise<AxiosResponse<Blob>>;
|
||||
download(crtDmndUuid: string, verSn: number): Promise<AxiosResponse<Blob>>;
|
||||
downloadLatest(crtDmndUuid: string): Promise<AxiosResponse<Blob>>;
|
||||
saveMultipart(formData: FormData): Promise<PwrkCnsltnDocCrtRsltResponseDto>;
|
||||
updateMultipart(
|
||||
crtDmndUuid: string,
|
||||
verSn: number,
|
||||
formData: FormData,
|
||||
): Promise<PwrkCnsltnDocCrtRsltResponseDto>;
|
||||
remove(crtDmndUuid: string, verSn: number): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
`webhwp/open`은 인증된 axios 요청으로 Blob을 조회한다:
|
||||
|
||||
```ts
|
||||
async function openWebHwpLatest(crtDmndUuid: string) {
|
||||
return client.get<Blob>(`${BASE}/${crtDmndUuid}/webhwp/open`, {
|
||||
responseType: "blob",
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
응답 Blob은 HWPX `File`로 감싸 `HwpCtrl.Open(file, "HWPX", ...)`에 전달한다. `blob:` Object URL은 사용하지 않는다.
|
||||
|
||||
DC RAG TO (구현됨, 시그니처 유지):
|
||||
|
||||
```ts
|
||||
requestDocumentTransfer(body: DcRagDocumentTransferRequestDto): Promise<DcRagCommonResponseDto>;
|
||||
requestDraftGeneration(body: DcRagDraftGenerateRequestDto): Promise<DcRagDraftGenerateResponseDto>;
|
||||
getDraftGenerationStatus(crtDmndUuid: string): Promise<DcRagDraftStatusResponseDto>;
|
||||
requestCostVerification(body: DcRagCostVerifyRequestDto): Promise<DcRagCommonResponseDto>;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. DTO
|
||||
|
||||
타입명 = 백엔드 클래스명. Save/Apply는 zod.
|
||||
|
||||
### 4-1. 재원협의 추가
|
||||
|
||||
**`FnrsExamineRequestDto`**
|
||||
|
||||
| 필드 | 필수 | 값 |
|
||||
| --- | --- | --- |
|
||||
| `prgrsSttsComCd` | N | 기본 `FV` |
|
||||
|
||||
**`EnvoActnReviewReqDto`**
|
||||
|
||||
| 필드 | 필수 |
|
||||
| --- | --- |
|
||||
| `specialRqstCn` | N |
|
||||
|
||||
**`FnrsCnsltnFileVrfcRsltResponseDto`**: [ref-endpoint.md](./ref-endpoint.md) §3-3.
|
||||
|
||||
첨부 검증 배지용으로 `AtflMngClientResponseDto` / `EsntlAtchFileMngTreeResponseDto`에 `vrfcDt`, `vrfcRsltCn`, `vrfcSttsComCd` 확장.
|
||||
|
||||
### 4-2. `PwrkActnResultSubmitDto` (zod)
|
||||
|
||||
| 필드 | 필수 | 비고 |
|
||||
| --- | --- | --- |
|
||||
| `isSubmit` | Y | `false` API만(화면 버튼 없음), `true` 조치완료(`RB→RA`) |
|
||||
| `actnList` | N | 조치완료 시 선택 |
|
||||
| `actnList[].rvwOpnnSn` | Y (항목 있을 때) | |
|
||||
| `actnList[].actnRsltCn` | N | |
|
||||
| `actnList[].atchFileGroupId` | N | |
|
||||
| `totActnSummary` | N | 제출 시 권장 |
|
||||
| `muniDocNo` | N | 제출 시 권장 |
|
||||
| `pwrkAtchFileGroupId` | N | |
|
||||
|
||||
### 4-3. `PwrkCnsltnMng*`
|
||||
|
||||
**Search**: `pwrkCnsltnDocNo`, `upDocNo`, `upDocSeComCd`, `prgrsSttsComCd`, `admdstCd`, `envoSeComCd`, `taskSeComCd`, `bizNm`
|
||||
|
||||
**DetResponse 중첩**
|
||||
|
||||
- `cnsltnList`: 협의내역 (`rvwOpnnSn`, `rvwOpnnClsfComCd`, `cnsltnCn`, `rfltYn`, …)
|
||||
- `pjtcoAjmtList`: 사업비조정
|
||||
- `crtDmndList[].crtRslt`: 생성요청 + 최신 결과
|
||||
- `splmntDmndList`: 보완요청
|
||||
- `sttsChgHstryList`: 상태변경이력 — `SL` 복귀 라벨에 사용
|
||||
- `trsmFileList`: 전송파일 (Java Det DTO 확인 후 반영)
|
||||
|
||||
마스터 조인: `bizNm`, `admdstCd`, `envoSeComCd`, `taskSeComCd`, `aplcntNm` 등.
|
||||
|
||||
`crtRslt.orgnlOtptDocCn`은 항상 `null`.
|
||||
|
||||
**상세 예**
|
||||
|
||||
```json
|
||||
{
|
||||
"pwrkCnsltnDocNo": "P-20260827-0001",
|
||||
"upDocNo": "F-20260824-0001",
|
||||
"upDocSeComCd": "FNRS",
|
||||
"prgrsSttsComCd": "TE",
|
||||
"cnsltnList": [],
|
||||
"pjtcoAjmtList": [],
|
||||
"crtDmndList": [
|
||||
{
|
||||
"crtDmndUuid": "d0545bef-735f-4d7b-a781-88e96e03577a",
|
||||
"pwrkCnsltnDocNo": "P-20260827-0001",
|
||||
"rqstrUuid": "...",
|
||||
"rqstrNm": "관리자",
|
||||
"crtSttsComCd": "C",
|
||||
"crtRslt": {
|
||||
"crtDmndUuid": "d0545bef-735f-4d7b-a781-88e96e03577a",
|
||||
"verSn": 1,
|
||||
"rgtrNm": "관리자",
|
||||
"orgnlOtptDocCn": null,
|
||||
"crtCmptnDt": "2026-08-27 10:47:01"
|
||||
}
|
||||
}
|
||||
],
|
||||
"splmntDmndList": [],
|
||||
"sttsChgHstryList": []
|
||||
}
|
||||
```
|
||||
|
||||
### 4-4. `PwrkCnsltnDocCrtRslt*`
|
||||
|
||||
복합 PK: `crtDmndUuid` + `verSn`
|
||||
|
||||
**Response**
|
||||
|
||||
| 필드 | 타입 | 비고 |
|
||||
| --- | --- | --- |
|
||||
| `crtDmndUuid` | `string` | |
|
||||
| `verSn` | `number` | |
|
||||
| `rgtrUuid` / `rgtrNm` | `string` | |
|
||||
| `orgnlOtptDocCn` | `null` | 목록/상세 미포함 |
|
||||
| `crtCmptnDt` | `string` | |
|
||||
|
||||
**Search** (`PageableParams`): `crtDmndUuid`(이력 조회 시 필수), `pwrkCnsltnDocNo`, `verSn`, `rgtrUuid`
|
||||
|
||||
```http
|
||||
GET /as-service/api/v1/pwrk-cnsltn-doc-crt-rslt?page=0&size=10&crtDmndUuid={uuid}&sort=verSn,desc
|
||||
```
|
||||
|
||||
**Save (zod)**: `crtDmndUuid` 필수. `rgtrUuid` 생략 시 서버 로그인 사용자. `file`은 multipart part (DTO 필드 아님).
|
||||
|
||||
### 4-5. DC RAG (구현됨)
|
||||
|
||||
```ts
|
||||
interface DcRagDocumentTransferRequestDto {
|
||||
fnrsCnsltnDocNo: string;
|
||||
taskSeComCd?: string;
|
||||
taskSeCdNm?: string;
|
||||
}
|
||||
|
||||
interface DcRagDraftStatusResponseDto {
|
||||
crtDmndUuid: string;
|
||||
status: DraftStatus;
|
||||
statusName?: string;
|
||||
progressPercent?: number;
|
||||
events?: EventInfoDto[];
|
||||
startedDt?: string;
|
||||
estimatedCompletionDt?: string;
|
||||
errorMessage?: string | null;
|
||||
}
|
||||
|
||||
type DraftStatus =
|
||||
| "REQUESTED"
|
||||
| "DOWNLOADING"
|
||||
| "ANALYZING"
|
||||
| "GENERATING"
|
||||
| "COMPLETED"
|
||||
| "FAILED";
|
||||
```
|
||||
|
||||
`estimatedMinutes`는 초안 응답에 있을 수 있으나 UX 안내는 **30분 Fallback**을 따른다.
|
||||
|
||||
---
|
||||
|
||||
## 5. 폴링 훅
|
||||
|
||||
초안 (`AC` 또는 `TE`이면서 생성 중):
|
||||
|
||||
```ts
|
||||
useQuery({
|
||||
queryKey: [...dcragToKeys.draftStatus(crtDmndUuid)],
|
||||
queryFn: () => dcRagApiToService.getDraftGenerationStatus(crtDmndUuid),
|
||||
enabled: Boolean(crtDmndUuid) && isPolling,
|
||||
refetchInterval: (query) => {
|
||||
const status = query.state.data?.status;
|
||||
if (status === "COMPLETED" || status === "FAILED") return false;
|
||||
return 5_000;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`COMPLETED` 시 `fnrs-cnsltn` 상세·`pwrk-cnsltn-mng` `findByUpDocNo` invalidate.
|
||||
|
||||
`FV`/`AV`는 `findById`를 5~10초 refetch. `prgrsSttsComCd`가 `ER`/`RK`가 되면 중단. 시작 시각 기준 30분 경과 안내 문구.
|
||||
|
||||
`crtDmndUuid` 복원: `findByUpDocNo(fnrsCnsltnDocNo).crtDmndList[0]`.
|
||||
|
||||
---
|
||||
|
||||
## 6. 다운로드
|
||||
|
||||
```ts
|
||||
const response = await client.get<Blob>(url, { responseType: "blob" });
|
||||
const filename = parseFilenameFromResponse(response);
|
||||
const objectUrl = window.URL.createObjectURL(response.data);
|
||||
```
|
||||
|
||||
기존 `attachService`와 동일.
|
||||
|
||||
---
|
||||
|
||||
## 7. 실무협의 목록 컬럼 (선택 화면)
|
||||
|
||||
| 표시명 | Field |
|
||||
| --- | --- |
|
||||
| 실무협의번호 | `pwrkCnsltnDocNo` |
|
||||
| 재원협의번호 | `upDocNo` |
|
||||
| 진행상태 | `prgrsSttsComCdNm` |
|
||||
| 사업명 | `bizNm` |
|
||||
| 시도/구군 | `sido` / `gugun` |
|
||||
| 신청자 | `aplcntNm` |
|
||||
| 등록일 | `regDt` |
|
||||
|
||||
행 클릭 → `/pwrk-cnsltn/{pwrkCnsltnDocNo}` 또는 재원협의 상세로 이동 (화면설계 확정 후).
|
||||
|
||||
---
|
||||
|
||||
## 8. `elapr-dmnd` 저장 시 주의
|
||||
|
||||
현행 `floating-action-buttons.tsx`:
|
||||
|
||||
```ts
|
||||
elaprCycl: data.detDto?.prgrsSttsComCd === "RK" ? 2 : 1,
|
||||
docPrgrsSttsComCd: data.detDto?.prgrsSttsComCd, // ER
|
||||
```
|
||||
|
||||
To-Be:
|
||||
|
||||
- 검토자지정은 **`ER`(1차)** 과 **`EV`(2차)** 에서.
|
||||
- `ER`: `elaprCycl: 1`, `docPrgrsSttsComCd: "AC"`, 서식 선택 다이얼로그
|
||||
- `EV`: `elaprCycl: 2`, `docPrgrsSttsComCd: "RK"`, 1차 결재선 시드 다이얼로그(서식 없음)
|
||||
|
||||
`RK` / ATRZ02 FAB: `findDocPrgrsByDocNo` 전체 조회 후 pending은 `elaprCycl === 2`만 사용. 검토완료 후 `ElaprApprovalDialog`에 `elaprCycl={2}`. 보완요청은 TE와 동일 `SplmntDmndDialog`.
|
||||
@@ -1,246 +0,0 @@
|
||||
# 레퍼런스 — 프로세스·상태 전이
|
||||
|
||||
> 상위: [개발가이드.md](./개발가이드.md)
|
||||
> SoT: `03.재원협의_실무협의_프로세스_통합_v완결.md` (v3.0, 2026-09-03)
|
||||
|
||||
---
|
||||
|
||||
## 1. 프로세스 개요
|
||||
|
||||
| 항목 | 내용 |
|
||||
| --- | --- |
|
||||
| Process No. | PR-AS-003 |
|
||||
| 메뉴 | 행정지원 > 2.2.2 재원협의 > 2.2.2.1 재원협의 관리 |
|
||||
| 목적 | 기초 → 광역(경유) → 환경청(승인) → 공단(기술검토/AI) 4자 협의로 사업규모·국비·분담금을 확정 |
|
||||
|
||||
2-Pass:
|
||||
|
||||
- **Pass 1** 기술 타당성: `SV→ST→LE→FV→ER→AC→TE→TP→RM→RB`
|
||||
- **Pass 2** 조치결과·금액: `RB→RA→AV→EV→RK→RR→EP→TA`
|
||||
|
||||
자체종결(기술검토 생략): `LE→EP→TA`
|
||||
|
||||
---
|
||||
|
||||
## 2. 4-Lane 시퀀스
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor 기초 as 기초 (ROLE_USER05)
|
||||
actor 광역 as 광역 (ROLE_USER04)
|
||||
actor 환경청 as 환경청 (ROLE_USER03)
|
||||
actor 공단 as 공단 (ROLE_USER01)
|
||||
actor AI as AI 엔진
|
||||
|
||||
rect rgb(240, 248, 255)
|
||||
기초->>기초: [저장] SV
|
||||
기초->>광역: [신청완료] ST
|
||||
광역->>환경청: [환경청제출] LE
|
||||
end
|
||||
|
||||
rect rgb(255, 250, 240)
|
||||
alt 자체종결
|
||||
환경청->>광역: [결과회신] LE → EP
|
||||
광역->>기초: [결과회신] EP → TA
|
||||
else 기술검토 의뢰
|
||||
환경청->>AI: [기술검토 의뢰] LE → FV
|
||||
end
|
||||
end
|
||||
|
||||
rect rgb(245, 255, 245)
|
||||
AI-->>공단: 파일검증 콜백 FV → ER
|
||||
Note over 공단: 30분 미응답 시 ER + 수동 [파일검증]
|
||||
alt 파일 미비
|
||||
공단->>기초: [파일보완] ER → SL
|
||||
기초->>공단: [파일보완완료] SL → ER
|
||||
else 적격
|
||||
공단->>AI: [검토자지정] ER → AC
|
||||
end
|
||||
end
|
||||
|
||||
rect rgb(255, 245, 245)
|
||||
AI-->>공단: 초안 콜백 AC → TE
|
||||
Note over 공단: 30분 미응답 시 TE + 수동 [실무협의서생성]
|
||||
alt 설계 미비
|
||||
공단->>기초: [보완요청] TE → SL
|
||||
기초->>공단: [보완완료] SL → TE
|
||||
else 검토 완료
|
||||
공단->>공단: [검토완료] 상신, [결재(승인)] TE 유지
|
||||
공단->>환경청: [결재(회신)] TE → TP
|
||||
end
|
||||
end
|
||||
|
||||
rect rgb(250, 240, 255)
|
||||
환경청->>광역: [재원협의 결과 회신] TP → RM
|
||||
광역->>기초: [지자체회신] RM → RB
|
||||
기초->>환경청: [조치완료] RB → RA
|
||||
end
|
||||
|
||||
rect rgb(240, 255, 255)
|
||||
광역->>환경청: [조치결과서제출] RC → RA
|
||||
환경청->>AI: [조치결과 검토의뢰] RA → AV
|
||||
AI-->>공단: 금액검증 콜백 AV → EV
|
||||
공단->>공단: [검토자지정] EV → RK
|
||||
Note over 공단: EV에서 1차 결재선 시드로 2차 결재선 수동 배정
|
||||
end
|
||||
|
||||
rect rgb(255, 255, 230)
|
||||
alt 소명 미비
|
||||
공단->>기초: [보완요청] RK → SL
|
||||
기초->>공단: [보완완료] SL → RK
|
||||
else 확정
|
||||
공단->>환경청: [결재(회신)] RK → RR
|
||||
end
|
||||
end
|
||||
|
||||
rect rgb(255, 240, 240)
|
||||
환경청->>광역: [결과회신] RR → EP
|
||||
광역->>기초: [결과회신] EP → TA
|
||||
end
|
||||
```
|
||||
|
||||
거버넌스:
|
||||
|
||||
```
|
||||
기초 (USER05) --ST--> 광역 (USER04) --LE--> 환경청 (USER03)
|
||||
기초 <-----TA------ 광역 <-----EP/RM------ 환경청
|
||||
환경청 --FV/ER--> 공단 (USER01) --TP/RR--> 환경청
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Activity 정의 (14)
|
||||
|
||||
| No. | Activity | 주체 | From → To | FE 포인트 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | 재원협의 조회 | 기초 | — | 기본계획·자가점검 대조 |
|
||||
| 2 | 등록 및 제출 | 기초·광역 | `SV→ST`, 광역 `LE` | `save-apply`, `updatePrgrsStts` |
|
||||
| 3 | 접수 및 의뢰 | 환경청 | `LE→FV` / `EP` | 의뢰 vs 자체종결 분기 |
|
||||
| 4 | AI 파일검증 | 공단·AI | `FV→ER` / `SL` | 30분 Fallback, 파일보완 팝업 |
|
||||
| 5 | 자체종결 회신 | 환경청·광역 | `LE→EP→TA` | 공단 레인 없음 |
|
||||
| 6 | 검토자지정·초안 | 공단·AI | `ER→AC→TE` | `elapr-dmnd`, 초안 폴링 |
|
||||
| 7 | 1차 기술검토 | 공단 결재선 | `TE` / `SL` | 웹기안기, HWP 파싱은 서버 |
|
||||
| 8 | 기술검토 회신 | 공단 최종 | `TE→TP` | `process` 최종 |
|
||||
| 9 | 검토결과 회신 | 환경청·광역 | `TP→RM→RB` | 1차 회신. `EP`와 혼동 금지 |
|
||||
| 10 | 조치결과 작성 | 기초 | `RB→RA` | `submit-actn-result` `isSubmit:true` (조치완료) |
|
||||
| 11 | 조치 의뢰 | 환경청 | `RA→AV` | `request-actn-review` |
|
||||
| 12 | AI 금액검증 | AI·공단 | `AV→EV` | 콜백/Fallback 후 접수자 대기 |
|
||||
| 12a | 2차 검토자지정 | 공단 접수 | `EV→RK` | `elapr-dmnd` cycl=2 |
|
||||
| 13 | 2차 검토·결재 | 공단 | `RK→RR` / `SL` | 2차 결재선 |
|
||||
| 14 | 최종 회신 | 환경청·광역·기초 | `RR→EP→TA` | 종결 |
|
||||
|
||||
---
|
||||
|
||||
## 4. `FNRSSTTS` 상세
|
||||
|
||||
관리: `tb_cs_lwpo_cd` / `tb_as_fnrs_cnsltn_mng.prgrs_stts_com_cd`
|
||||
|
||||
| 코드 | 국문 | 영문 | 화면 주체 | 전이 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `SV` | 저장 | Save | 기초 작성 | 신규/`SV` → `SV` |
|
||||
| `ST` | 신청완료 | Submit to Province | 기초→광역 | `SV→ST` |
|
||||
| `LE` | 환경청 검토 | Local Environment Review | 광역→환경청 | `ST→LE` |
|
||||
| `FV` | 파일검증 | File Verification | AI | `LE→FV` |
|
||||
| `ER` | 기술검토 의뢰 | Examine Request | 공단 접수자 | `FV→ER`, `SL→ER` |
|
||||
| `SL` | 보완요청 | Supplement Loop | 공단→기초 | `ER\|TE\|RK → SL` |
|
||||
| `AC` | 초안생성 | AI Auto Creation | AI | `ER→AC` |
|
||||
| `TE` | 기술검토 | Technical Examine | 공단 1차 결재 | `AC→TE`, `SL→TE` |
|
||||
| `TP` | 기술검토 회신 | Technical Pass to Basin | 공단→환경청 | `TE→TP` |
|
||||
| `RM` | 재원협의결과회신 | Result Message to Province | 환경청→광역 | `TP→RM` |
|
||||
| `RB` | 재원협의결과회신(지자체) | Result Back to Municipality | 광역→기초 | `RM→RB` |
|
||||
| `RC` | 조치결과서 제출 | Result Complete | 기초→광역 | `RB→RC` |
|
||||
| `RA` | 조치결과서 제출(환경청) | Result Ask to Basin | 기초→환경청 | `RB→RA` |
|
||||
| `AV` | 금액검증 | Amount Verification | AI | `RA→AV` |
|
||||
| `EV` | 조치결과검토의뢰 | Examine Verify | 공단 접수자 | `AV→EV` |
|
||||
| `RK` | 조치결과서검토 | Result Check | 공단 2차 결재 | `EV→RK`, `SL→RK` |
|
||||
| `RR` | 조치결과서검토 회신 | Result Return to Basin | 공단→환경청 | `RK→RR` |
|
||||
| `EP` | 검토결과 회신 | Examine Pass to Province | 환경청→광역 | `LE→EP`(자체), `RR→EP`(최종) |
|
||||
| `TA` | 검토결과 회신(종료) | Technical Approval | 광역→기초 | `EP→TA` |
|
||||
|
||||
### 4-1. v2.1 → v3.0 대조 (프론트 폐기 대상)
|
||||
|
||||
| 구간 | v2.1 | v3.0 |
|
||||
| --- | --- | --- |
|
||||
| 의뢰 직후 파일검증 | `ER` | **`FV` → `ER`** |
|
||||
| 검토자지정 후 초안 | `EE` → `DV` | **`ER` → `AC` → `TE`** |
|
||||
| 1차 내부 결재 | `TR` → `TP` | **`TE` 유지 → `TP`** |
|
||||
| 환경청→광역 1차 회신 | `EP` | **`RM`** |
|
||||
| 금액검증 | `RA` | **`RA` → `AV` → `RK`** |
|
||||
| 공단 2차 회신 | `TP` | **`RR`** |
|
||||
| 최종 완료 | `TP` / 고시 `TB` | **`TA`** (고시 없음) |
|
||||
|
||||
가이드 v1.0 `PWRKSTTS`(`DV`, `AR`, `TR`, `AA` 등)도 동일하게 폐기.
|
||||
|
||||
---
|
||||
|
||||
## 5. 보완(`SL`) 3루프
|
||||
|
||||
복귀 상태는 `tb_as_doc_stts_chg_hstry` 직전 코드. 프론트는 복귀 코드를 요청에 넣지 않고, 라벨만 이력으로 고른다.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
ER --> SL: 파일보완 팝업(파일리스트)
|
||||
SL --> ER: 파일보완완료
|
||||
TE --> SL: 보완 검토팝업()
|
||||
SL --> TE: 보완완료
|
||||
RK --> SL: 보완 검토팝업(금액)
|
||||
SL --> RK: 보완완료
|
||||
```
|
||||
|
||||
| 루프 | 팝업 | 요청 | 제출 버튼 |
|
||||
| --- | --- | --- | --- |
|
||||
| 파일 무결성 | 파일리스트 + 검증결과 | 공단 접수자 `ER` | [파일보완완료] |
|
||||
| 1차 기술 | 설계 미달·사유 | 공단 검토자 `TE` | [보완완료] |
|
||||
| 2차 금액 | 공종별 금액 체크 | 공단 검토자 `RK` | [보완완료] |
|
||||
|
||||
---
|
||||
|
||||
## 6. AI 3파이프라인·30분 Fallback
|
||||
|
||||
| ID | 단계 | 진입 → 완료 | 프론트 진입 | Fallback | 수동 재실행 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| AI-1 | 파일 무결성 | `FV→ER` | 환경청 [기술검토 의뢰] | 30분 → `ER` + [파일검증] | `POST /dcrag-to/documents/transfer` |
|
||||
| AI-2 | 초안 생성 | `AC→TE` | 공단 [검토자지정] | 30분 → `TE` + [실무협의서생성] | `POST /dcrag-to/documents/draft/generate` |
|
||||
| AI-3 | 금액 검증 | `AV→EV` | 환경청 [조치결과 검토의뢰] | 30분 → `EV` + 수동 [금액검증] | `POST /dcrag-to/documents/cost/verify` |
|
||||
|
||||
- 예상 소요 안내는 **30분** (v1.0의 10분은 폐기).
|
||||
- 콜백 수신·스케줄러 전이는 서버. FE는 상세 refetch / draft status 폴링만.
|
||||
- `AC→TE` 성공 시에만 [실무협의서관리]·[검토결과조회] 활성. 실패·타임아웃이면 [실무협의서생성].
|
||||
|
||||
초안 폴링 이벤트 예:
|
||||
|
||||
| `eventType` | `eventMessage` |
|
||||
| --- | --- |
|
||||
| `REQUESTED` | 요청을 접수했습니다. |
|
||||
| `DOWNLOADING` | 신청서를 수신하는 중입니다. |
|
||||
| `ANALYZING` | 자료 준비가 완료되었습니다. |
|
||||
| `GENERATING` | 문서 저장이 완료되었습니다. |
|
||||
| `COMPLETED` | 문서 생성이 완료되었습니다. |
|
||||
| `FAILED` | `errorMessage` 표시 |
|
||||
|
||||
종료: `status === "COMPLETED" | "FAILED"` 또는 `events`에 해당 `eventType`.
|
||||
|
||||
---
|
||||
|
||||
## 7. 2차 결재선 (수동 검토자지정)
|
||||
|
||||
1. `TE`에서 1차 결재선(`elaprCycl = 1`) 완료.
|
||||
2. 금액검증 콜백/Fallback → `AV→EV`.
|
||||
3. 공단 접수자가 `EV`에서 [검토자지정]: 1차 결재선을 시드로 편집 후 `POST /elapr-dmnd` (`elaprCycl: 2`) → `RK`.
|
||||
4. `copy-line` 자동 복사는 사용하지 않는다.
|
||||
|
||||
결재 `process`:
|
||||
|
||||
- 상신·중간 승인: 문서 상태 `TE` 또는 `RK` 유지.
|
||||
- 1차 최종: 서버가 `TE→TP`.
|
||||
- 2차 최종: 서버가 `RK→RR`.
|
||||
- 반려: 직전 결재자 복귀. 문서 상태 유지.
|
||||
|
||||
---
|
||||
|
||||
## 8. 웹기안기
|
||||
|
||||
- `TE`/`RK` [실무협의서관리] → `webhwp/open` Blob 조회 후 팝업에서 `HwpCtrl.Open(File)`.
|
||||
- [검토완료] 시 HWP 파싱·DB 등재는 **서버**. FE는 결재 `process`만.
|
||||
- 편집본 저장: `POST /pwrk-cnsltn-doc-crt-rslt` multipart. `verSn`은 클라이언트가 보내지 않음.
|
||||
@@ -1,181 +0,0 @@
|
||||
# 레퍼런스 — 화면·버튼 매트릭스
|
||||
|
||||
> 상위: [개발가이드.md](./개발가이드.md)
|
||||
> SoT: `03` §4 화면 및 버튼별 상세 상태전이 명세서 (Row 4~42, 38행)
|
||||
|
||||
구현 위치: `pages/fnrs-cnsltn/lib/button-config.ts` + `ui/components/floating-action-buttons.tsx`
|
||||
|
||||
---
|
||||
|
||||
## 1. 화면 구분
|
||||
|
||||
| 화면 | 소유 | 라우트 (현행) | 비고 |
|
||||
| --- | --- | --- | --- |
|
||||
| 작성화면 | 기초 `ROLE_USER05` | `/fnrs-cnsltn/new`, `/fnrs-cnsltn/{id}/edit` | `SV` |
|
||||
| 수정화면 | 기초 | `/fnrs-cnsltn/{id}/edit` | `SL` 보완 |
|
||||
| 상세화면 | 광역·환경청·공단·기초(`RB`/`TA`) | `/fnrs-cnsltn/{id}` | 조회 + 액션 버튼 |
|
||||
| 자동화 | AI | 버튼 없음 | `FV`/`AC`/`AV` 진행 패널 |
|
||||
|
||||
공단 상세는 결재선 구분으로 같은 상태라도 버튼이 다르다.
|
||||
|
||||
| `atrzSeComCd` | 역할 |
|
||||
| --- | --- |
|
||||
| `ATRZ01` | 접수자 |
|
||||
| `ATRZ02` | 검토자 |
|
||||
| `ATRZ03` | 승인자 |
|
||||
| `ATRZ99` | 최종승인자 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 38행 매트릭스
|
||||
|
||||
API 컬럼은 [ref-endpoint.md](./ref-endpoint.md)와 동일.
|
||||
|
||||
| 순번 | 화면 | 권한 | 결재선 | 상태 | 버튼 | 전이 | 다음 담당 | FE 동작 |
|
||||
| :---: | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| 1 | 작성 | USER05 | - | 빈값, `SV` | 저장 | `SV` | 본인 | `save-apply` `SV` |
|
||||
| 2 | 작성 | USER05 | - | `SV` | 신청완료 | `ST` | 광역 | `save-apply` `ST` |
|
||||
| 3 | 작성 | USER05 | - | `SV` | 삭제 | 삭제 | — | `DELETE` |
|
||||
| 4 | 상세 | USER04 | - | `ST` | 환경청제출 | `LE` | 환경청 | `updatePrgrsStts` |
|
||||
| 5 | 상세 | USER03 | - | `LE` | 결과회신 | `EP` | 광역 | `tech-review` 자체종결 |
|
||||
| 6 | 상세 | USER03 | - | `LE` | 기술검토 의뢰 | `FV` | 공단 접수 | **`request-examine`** |
|
||||
| 7 | 자동화 | AI | - | `FV` | (파일검증) | `ER` | 공단 접수 | FE 호출 없음. 진행 패널 |
|
||||
| 8 | 상세 | USER01 | 접수자 | `ER` | 파일보완 | `SL` | 기초 | 팝업(파일리스트) → `reqsupplement` |
|
||||
| 9 | 상세 | USER01 | 접수자 | `ER` | 파일검증 | `ER` | 본인 | `dcrag-to/transfer` 재실행 |
|
||||
| 10 | 상세 | USER01 | 접수자 | `ER` | 검토자지정 | `AC` | 다음 결재자 | `POST /elapr-dmnd` |
|
||||
| 11 | 자동화 | AI | - | `AC` | (초안생성) | `TE` | 공단 검토 | FE 호출 없음. 폴링 |
|
||||
| 12 | 상세 | USER01 | 검토자 | `TE` | 실무협의서관리 | 유지 | — | 웹기안기 Open. **초안 성공 시만** |
|
||||
| 13 | 상세 | USER01 | 검토자 | `TE` | 검토결과조회 | 유지 | — | 실무협의 상세 |
|
||||
| 14 | 상세 | USER01 | 검토자 | `TE` | 실무협의서생성 | 유지 | — | **실패/타임아웃/초안 없음** 시 |
|
||||
| 15 | 상세 | USER01 | 검토자 | `TE` | 저장 | `TE` | — | `pwrk save-apply` |
|
||||
| 16 | 상세 | USER01 | 검토자 | `TE` | 검토완료 | `TE` | 다음 결재자 | `elapr process` 상신. 반려 시 직전 결재자 |
|
||||
| 17 | 상세 | USER01 | 검토자 | `TE` | 보완요청 | `SL` | 기초 | 보완 팝업() → `reqsupplement` |
|
||||
| 18 | 상세 | USER01 | 승인자 | `TE` | 결재(승인) | `TE` | 다음 결재자 | `process` |
|
||||
| 19 | 상세 | USER01 | 최종승인자 | `TE` | 결재(회신) | `TP` | 환경청 | `process` 최종 |
|
||||
| 20 | 수정 | USER05 | - | `SL` | 파일보완완료 | `ER` | 공단 접수 | `submitsupplement` (직전=`ER`) |
|
||||
| 21 | 수정 | USER05 | - | `SL` | 보완완료 | `TE` | 공단 검토 | `submitsupplement` (직전=`TE`) |
|
||||
| 22 | 수정 | USER05 | - | `SL` | 보완완료 | `RK` | 공단 검토 | `submitsupplement` (직전=`RK`) |
|
||||
| 23 | 상세 | USER03 | - | `TP` | 재원협의 결과 회신 | `RM` | 광역 | `tech-review` |
|
||||
| 24 | 상세 | USER04 | - | `RM` | 지자체회신 | `RB` | 기초 | `updatePrgrsStts` |
|
||||
| 25 | 상세 | USER05 | - | `RB` | 실무협의서 관리 | 유지 | — | 웹기안기 Open |
|
||||
| 26 | 상세 | USER05 | - | `RB` | 조치완료 | `RA` | 환경청 | **`submit-actn-result` `isSubmit:true`** |
|
||||
| 27 | 상세 | USER04 | - | `RC` | 조치결과서제출 | `RA` | 환경청 | `updatePrgrsStts` |
|
||||
| 28 | 상세 | USER03 | - | `RA` | 실무협의서 관리 | 유지 | — | 웹기안기 Open. **저장 불가** |
|
||||
| 28a | 상세 | USER03 | - | `RA` | 조치결과 검토의뢰 | `AV` | 공단 검토 | **`request-actn-review`** |
|
||||
| 29 | 자동화 | AI | - | `AV` | (금액검증) | `EV` | 공단 접수 | FE 호출 없음. 진행 패널 |
|
||||
| 29a | 상세 | USER01 | 접수자 | `EV` | 검토자지정 | `RK` | 공단 검토 | `POST /elapr-dmnd` cycl=2. 1차 결재선 시드 |
|
||||
| 30 | 상세 | USER01 | 검토자 | `RK` | 실무협의서관리 | 유지 | — | 웹기안기 |
|
||||
| 31 | 상세 | USER01 | 검토자 | `RK` | 금액검증 | `RK` | — | `dcrag-to/cost/verify` |
|
||||
| 32 | 상세 | USER01 | 검토자 | `RK` | 저장 | `RK` | — | `pwrk save-apply` |
|
||||
| 33 | 상세 | USER01 | 검토자 | `RK` | 검토완료 | `RK` | 다음 결재자 | `process` |
|
||||
| 34 | 상세 | USER01 | 승인자 | `RK` | 결재(승인) | `RK` | 다음 결재자 | `process` |
|
||||
| 35 | 상세 | USER01 | 최종승인자 | `RK` | 결재(회신) | `RR` | 환경청 | `process` 최종 |
|
||||
| 36 | 상세 | USER03 | - | `RR` | 실무협의서 관리(조회), 검토결과 회신 | `EP` | 광역 | `tech-review` |
|
||||
| 37 | 작성/상세 | USER04 | - | `EP` | 결과회신, 실무협의서 관리(조회) | `TA` | 기초 | `updatePrgrsStts` |
|
||||
| 38 | 상세 | USER05 | - | `TA` | 결과회신, 실무협의서 관리(조회) | — | — | **API 없음. 조회** |
|
||||
|
||||
`SL` 20~22행: 버튼은 직전 상태에 따라 **하나만** 노출. 파일 루프면 [파일보완완료], 그 외 [보완완료].
|
||||
|
||||
---
|
||||
|
||||
## 3. `button-config` 권장 구조
|
||||
|
||||
액션 키는 현행 `FNRS_CNSLTN_VIEW_BUTTON_ACTION`을 확장한다. 신규·이름 변경:
|
||||
|
||||
| 신규/변경 액션 | 라벨 | 비고 |
|
||||
| --- | --- | --- |
|
||||
| `fileSplmnt` | 파일보완 | `ER` 접수자. 현행에 없음 |
|
||||
| `fileVrfc` | 파일검증 | 유지. `ER` 재실행 |
|
||||
| `dsgntRvwr` | 검토자지정 | `ER→AC`(1차), `EV→RK`(2차) |
|
||||
| `pwrkCnsltnDocMng` | 실무협의서관리 | 유지. `TE`·`RK`·`RB`·`RA`(조회 전용) |
|
||||
| `pwrkCnsltnDocCrt` | 실무협의서생성 | 유지. 실패/타임아웃만 |
|
||||
| `rvwRsltInq` | 검토결과조회 | 신규 |
|
||||
| `actnCmptn` | 조치완료 | `RB→RA`. `isSubmit:true` |
|
||||
| `actnSbmsn` | 조치결과서제출 | 광역 `RC→RA` |
|
||||
| `rqstActnRvw` | 조치결과 검토의뢰 | 환경청 `RA→AV` |
|
||||
| `costVrfc` | 금액검증 | `RK` |
|
||||
| `lclRply` | 지자체회신 | 광역 `RM→RB` |
|
||||
| `fnrsRsltRply` | 재원협의 결과 회신 | 환경청 `TP→RM` |
|
||||
| `rsltRply` | 결과회신 | `LE→EP`, `RR→EP`, `EP→TA`, `TA` 조회 |
|
||||
| `fileSplmntCmptn` | 파일보완완료 | `SL←ER` |
|
||||
| `splmntCmptn` | 보완완료 | `SL←TE\|RK` |
|
||||
|
||||
**삭제**: `fnrsCnsltnAncmnt`(고시→`TB`), `sncnAprv`(인가승인). `EP`/`TA`는 `rsltRply`로 통일.
|
||||
|
||||
### 3-1. 역할 × 상태 (공단 제외)
|
||||
|
||||
```
|
||||
ROLE_USER05
|
||||
"" | SV → 저장, 신청완료, 삭제
|
||||
SL → (직전 ER) 파일보완완료 | (직전 TE|RK) 보완완료
|
||||
RB → 실무협의서 관리, 조치완료
|
||||
TA → 결과회신 (조회), 실무협의서 관리(조회)
|
||||
|
||||
ROLE_USER04
|
||||
ST → 환경청제출 // 현행 반려(rjct→SV)는 SoT 38행에 없음. 유지 시 별도 합의
|
||||
RM → 지자체회신
|
||||
RC → 조치결과서제출
|
||||
EP → 결과회신, 실무협의서 관리(조회)
|
||||
|
||||
ROLE_USER03
|
||||
LE → 결과회신(자체종결), 기술검토 의뢰
|
||||
TP → 재원협의 결과 회신
|
||||
RA → 실무협의서 관리(조회), 조치결과 검토의뢰
|
||||
RR → 실무협의서 관리(조회), 검토결과 회신 (`tech-review` → `EP`)
|
||||
```
|
||||
|
||||
### 3-2. 공단 결재선 × 상태
|
||||
|
||||
```
|
||||
ER / ATRZ01 접수자
|
||||
→ 파일보완, 파일검증, 검토자지정
|
||||
|
||||
EV / ATRZ01 접수자
|
||||
→ 검토자지정 (2차 결재선. 1차 결재선 시드, 서식 선택 없음)
|
||||
|
||||
TE / ATRZ02 검토자
|
||||
→ (초안 성공) 실무협의서관리, 검토결과조회, 저장, 검토완료, 보완요청
|
||||
→ (초안 실패·타임아웃) 실무협의서생성 (+ 위 항목 중 관리/조회는 초안 생긴 뒤)
|
||||
|
||||
TE / ATRZ03 승인자 → 결재(승인)
|
||||
TE / ATRZ99 최종 → 결재(회신)
|
||||
|
||||
RK / ATRZ02 검토자
|
||||
→ (초안 완료) 실무협의서관리
|
||||
→ (초안 완료 + 결재 대기 ATRZ_PRGRS_002, cycl2) 보완요청, 검토완료
|
||||
· 보완요청 UI: TE와 동일 SplmntDmndDialog
|
||||
RK / ATRZ03 → (초안 완료) 실무협의서관리, (cycl2 pending) 결재(승인)
|
||||
RK / ATRZ99 → (초안 완료) 실무협의서관리, (cycl2 pending) 결재(회신)
|
||||
· 결재 UI: ElaprApprovalDialog (elaprCycl=2) 승인/반려 → PUT process
|
||||
```
|
||||
|
||||
`FV`, `AC`, `AV`: 액션 빈 배열 + 진행 패널.
|
||||
|
||||
`PENDING_APPROVAL_ACTIONS`: `dmndSplmnt`, `rvwCmptn`, `atrzAprv`, `atrzRply`만.
|
||||
`pwrkCnsltnDocMng`는 결재 대기와 무관(초안 완료만). ATRZ02·ATRZ03·ATRZ99라도 pending 없으면 관리만 노출.
|
||||
|
||||
---
|
||||
|
||||
## 4. 초안 성공 vs 실패 버튼
|
||||
|
||||
`TE`에서 `crtDmndList[].crtSttsComCd` / 폴링 `status`로 분기.
|
||||
|
||||
| 조건 | 노출 |
|
||||
| --- | --- |
|
||||
| `C` / `COMPLETED` | 실무협의서관리, 검토결과조회, 저장, 검토완료, 보완요청 |
|
||||
| `F` / `FAILED` 또는 30분 Fallback 후 초안 없음 | 실무협의서생성 |
|
||||
| `R`/`I` 생성 중 | 진행 패널. 위 버튼 비활성 (`AC`와 동일 UX, 상태가 이미 `TE`면 패널+생성 버튼) |
|
||||
|
||||
`RK`는 금액검증 성공이 기본. Fallback 후 [금액검증] 재실행만 추가 노출.
|
||||
|
||||
---
|
||||
|
||||
## 5. 현행 `button-config.ts`와의 차이
|
||||
|
||||
| 항목 | 현재 | To-Be |
|
||||
| --- | --- | --- |
|
||||
| USER05 | `""/SV/TA(고시)` | `SL`, `RB` 추가. `TA`는 조회 |
|
||||
| USER04 | `ST`(제출+반려), `EP`(인가승인) | `RM/RC/EP` 추가. 인가승인 삭제 |
|
||||
| USER03 | `LE`, `TP`(→EP로 회신) | `RA`, `RR` 추가. `TP`는 `RM` |
|
||||
| USER01 | `ER`(파일검증, 검토자지정), `TE` | `ER`에 파일보완. `RK` 전면 추가 |
|
||||
| USER01 ATRZ | `ER`, `TE`만 `needsRoleUser01AtrzResolve` | `RK` 포함 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,674 +0,0 @@
|
||||
# dmbpRegist.jsp → React 마이그레이션 분석·구현 가이드
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ------------------------------------------------------ |
|
||||
| 원본 JSP | `adssNewOld/.../fnrsc/dmbp/dmbpRegist.jsp` |
|
||||
| 대상 앱 | `frontend/apps/as` |
|
||||
| 도메인 | 하수도기본계획 (구: 기본계획검토 / dmbp) |
|
||||
| API 엔티티 | `@/entities/sewer-bsc-plan` (`SewerBscPlanController`) |
|
||||
| 참조 패턴 | `@/pages/fnrs-cnsltn` + `@/widgets/pbadms-sprt` |
|
||||
| 문서 목적 | contents 영역 **섹션별** UI·상태·API 매핑 및 구현 방향 |
|
||||
| 작성 기준일 | 2026-07-27 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 마이그레이션 범위
|
||||
|
||||
### 1-1. 포함 (contents만)
|
||||
|
||||
JSP `568~1274`행: `<div class="contents">` ~ `<!-- //contents -->`
|
||||
|
||||
| 영역 | JSP 식별 | 개요 |
|
||||
| ---- | ---------------------------------- | --------------------------------------------------------------- |
|
||||
| A | `gTitle1` | 페이지 타이틀·브레드크럼 |
|
||||
| B | `slide_10` | 기본계획변경 신청(마스터·연도·개요) |
|
||||
| C | `slide_15` | 신청자·설계자 정보 |
|
||||
| D | `slide_19` | 개인정보 동의 |
|
||||
| E | `slide_11` | 사업개요(단계별 인구·보급률) |
|
||||
| F | `slide_12` | 총사업비 — `BizCstMatrixFormSection` 전용 |
|
||||
| G | `slide_13` | 재원분담 |
|
||||
| H | `slide_14` | 처리시설별 하수도정비기본계획 (Checkbox + Tabs) |
|
||||
| I | `slide_16` | 체크리스트 + 필수첨부 + 기타첨부 |
|
||||
| J | JSP 상단 `saveBtn` / `presentnBtn` | React: 폼 하단 액션바 (`fnrs-form-page` 279~323과 동일 구성, API만 sewer) |
|
||||
|
||||
### 1-2. 제외
|
||||
|
||||
- `<%@ include %>`: top / sideMenu / footer / `bscPlnPopup.jsp` / `sndrdBzAmnt.jsp`
|
||||
- 레이아웃·메뉴·권한 셸 → 기존 `BaseLayout` / `PageLayout` / AUTH 체계
|
||||
- `mStep1` 진행 단계 표시 (미구현 · 마이그레이션 범위 밖)
|
||||
|
||||
팝업(`이전기본계획조회`)은 **별도 Dialog 컴포넌트**로 재구현하며, include JSP 자체는 포팅하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 목표 아키텍처
|
||||
|
||||
```
|
||||
app/(with-base-layout)/sewer-bsc-plan/regist/page.tsx
|
||||
└─ pages/sewer-bsc-plan/ui/sewer-bsc-plan-regist-page.tsx
|
||||
└─ sewer-bsc-plan-form-page.tsx # FormProvider + 섹션 조립
|
||||
├─ sections/*-form-section.tsx # 도메인 전용
|
||||
└─ widgets/pbadms-sprt/* # 공통 재사용
|
||||
|
||||
entities/sewer-bsc-plan/ # 이미 구현됨
|
||||
saveApply / findDetails / submitSupplement …
|
||||
```
|
||||
|
||||
**폼 스택 (fnrs-cnsltn과 동일)**
|
||||
|
||||
- `react-hook-form` + `zod` (`zodResolver`, `mode: "onChange"`)
|
||||
- 섹션 래퍼: `SectionCollapsible` (Accordion 아님)
|
||||
- UI: `@common/components` (Input, Select, Textarea, Button, Radio, Tabs, Table 등)
|
||||
- 그리드가 필요한 곳만 `@tanstack/react-table` + `DataTable`
|
||||
- 데이터: React Query (`useSaveApplySewerBscPlan` 등) — 목데이터는 API 미연동 구간만 `@faker-js/faker`
|
||||
|
||||
**Vercel React Best Practices (적용 요약)**
|
||||
|
||||
- `client-swr-dedup`: React Query로 체크리스트/필수첨부/코드 조회 중복 제거
|
||||
- `bundle-dynamic-imports`: 처리시설 Tabs 패널·이전계획 Dialog는 `next/dynamic` 후보
|
||||
- `rerender-derived-state`: 단계 연도·합계·진행률은 render 중 파생, 불필요 effect 금지
|
||||
- `async-parallel`: 등록 진입 시 코드/체크리스트트리/필수첨부트리를 병렬 조회
|
||||
|
||||
---
|
||||
|
||||
## 3. 전체 레이아웃
|
||||
|
||||
`fnrs-form-page.tsx`와 동일한 **FormProvider + 세로 섹션 스택** 구조를 따르고,
|
||||
하단 액션바는 **[`fnrs-form-page.tsx` 279~323](../../src/pages/fnrs-cnsltn/ui/fnrs-form-page.tsx)** 과 동일 구성(목록·저장·신청완료·삭제·보완완료)이며 **API/라우트만 sewer** 로 바꾼다.
|
||||
타이틀·브레드크럼은 폼 밖(`PageLayout` / regist·edit·view 셸)에서 처리한다.
|
||||
(상세 View의 sticky FAB·검토/결재 버튼은 본 등록 문서 범위 밖 — `fnrs-view-page` 대응 후속.)
|
||||
|
||||
### 3-1. 컴포넌트 트리 (fnrs 대응)
|
||||
|
||||
```
|
||||
PageLayout (title / breadcrumb)
|
||||
└─ SewerBscPlanRegistPage | SewerBscPlanEditPage | SewerBscPlanViewPage
|
||||
└─ SewerBscPlanFormPage | SewerBscPlanViewPage 본문
|
||||
FormProvider (등록/수정) / 읽기 섹션 (상세)
|
||||
└─ <form|div className="mt-6 space-y-4">
|
||||
├─ BasicInfoFormSection // JSP slide_10
|
||||
├─ ContactInfoFormSection // JSP slide_15 (pbadms-sprt)
|
||||
├─ PrivacyConsentSection // JSP slide_19 (pbadms-sprt, 등록·수정)
|
||||
├─ OutlineFormSection // JSP slide_11 (사업개요, 신규)
|
||||
├─ BizCstMatrixFormSection // JSP slide_12 (총사업비 전용, 신규)
|
||||
├─ FnrsCstFormSection // JSP slide_13 (재원분담, 신규 ※ FnrsShar 아님)
|
||||
├─ TmplntFormSection // JSP slide_14 (처리시설, Tabs로 시설별 패널)
|
||||
├─ ChecklistFormSection // JSP slide_16 (pbadms-sprt)
|
||||
├─ AttachmentsFormSection // JSP 필수·기타첨부 (pbadms-sprt)
|
||||
├─ SplmntDmndFormSection // edit + SL 상태만 (pbadms-sprt)
|
||||
└─ form footer action bar // fnrs-form-page 279~323 동일
|
||||
// [목록] / [저장] / edit시 [신청완료][삭제] / SL시 [보완완료]
|
||||
```
|
||||
|
||||
**폼 하단 액션바 버튼 구성**
|
||||
기준: [`fnrs-form-page.tsx` 279~323](../../src/pages/fnrs-cnsltn/ui/fnrs-form-page.tsx). UI·분기만 동일하고 훅/라우트는 sewer.
|
||||
|
||||
| 순서 | 버튼 | 조건 | sewer 비고 |
|
||||
| ---- | -------- | ----------------------------------------- | ---------------------------------------------------- |
|
||||
| 1 | 목록 | 항상 | `router.push("/sewer-bsc-plan")` |
|
||||
| 2 | 저장 | `!isSplmntPrgrsStts` | `type="submit"` → `saveApply` / 임시저장(SV) |
|
||||
| 3 | 신청완료 | `!isSplmntPrgrsStts && isEditMode` | 체크리스트+필수첨부 검증 → `saveApply` / LE |
|
||||
| 4 | 삭제 | `!isSplmntPrgrsStts && isEditMode` | confirm → `delete` → 목록 |
|
||||
| 5 | 보완완료 | `isSplmntPrgrsStts` (`prgrsSttsComCd=SL`) | `submitSupplement` (fnrs `onSplmntCmptn` 대응) |
|
||||
|
||||
**fnrs와의 차이 (섹션 치환만, 골격 동일)**
|
||||
|
||||
| fnrs-form-page | sewer-bsc-plan |
|
||||
| ---------------------------------------------- | ------------------------------------------------------ |
|
||||
| `BasicInfoFormSection` | 동일 역할 (마스터·연도·개요 필드는 sewer DTO) |
|
||||
| `ContactInfoFormSection` | 동일 (`fieldPrefix="sewerBscPlanDtl"`) |
|
||||
| `PrivacyConsentSection` | 동일 |
|
||||
| `BusinessScaleFormSection` | → `OutlineFormSection` (단계별 인구·보급률) |
|
||||
| `BusinessCostFormSection` | → `BizCstMatrixFormSection` (단계×원가 계층 전용) |
|
||||
| `FnrsSharFormSection` | → `FnrsCstFormSection` (국고·지방비·원인자·기타) |
|
||||
| _(없음)_ | `TmplntFormSection` (체크박스 + Tabs 시설별 매트릭스) |
|
||||
| `ChecklistFormSection` `docSeComCd="FNRS"` | `docSeComCd="SEWER"` (TBD) |
|
||||
| `AttachmentsFormSection` | 동일 패턴 |
|
||||
| `SplmntDmndFormSection` | 동일 (`readOnly={!isSplmntPrgrsStts}`) |
|
||||
| 폼 하단 액션바 (목록·저장·신청완료·삭제·보완완료) | **동일 구성, API·라우트만 sewer** |
|
||||
|
||||
### 3-2. 본문 ASCII (폼 페이지)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ PageLayout: 하수도기본계획 신청/수정 breadcrumb │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ FormProvider │
|
||||
│ <form className="mt-6 space-y-4"> │
|
||||
│ │
|
||||
│ ┌─ SectionCollapsible: 기본계획 신청 ─────────────────────┐ │
|
||||
│ │ BasicInfoFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 신청자 정보 ────────────────────────────────────────────┐ │
|
||||
│ │ ContactInfoFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 개인정보 동의 ──────────────────────────────────────────┐ │
|
||||
│ │ PrivacyConsentSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 사업개요 ────────────── [이전기본계획조회] ─────────────┐ │
|
||||
│ │ OutlineFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 총사업비 (백만원) ──────────────────────────────────────┐ │
|
||||
│ │ BizCstMatrixFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 재원분담 (백만원) ──────────────────────────────────────┐ │
|
||||
│ │ FnrsCstFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 처리시설별 하수도정비기본계획 ──────────────────────────┐ │
|
||||
│ │ TmplntFormSection │ │
|
||||
│ │ ├─ BscFctList Checkbox │ │
|
||||
│ │ └─ Tabs (선택 시설별 TabsTrigger / TabsContent) │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 체크리스트 ─────────────────────────────────────────────┐ │
|
||||
│ │ ChecklistFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 첨부파일 ───────────────────────────────────────────────┐ │
|
||||
│ │ AttachmentsFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ 보완요구 (edit + SL) ───────────────────────────────────┐ │
|
||||
│ │ SplmntDmndFormSection │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─ form footer (fnrs-form-page 279~323 동일) ──────────────┐ │
|
||||
│ │ [목록] [저장] / edit: [신청완료][삭제] / SL: [보완완료] │ │
|
||||
│ │ ※ API·라우트만 sewer — UI 분기는 fnrs와 동일 │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ </form> │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-3. 액션바 동작 (`fnrs-form-page` 279~323 동일, API만 sewer)
|
||||
|
||||
구현 위치: `sewer-bsc-plan-form-page.tsx` 하단
|
||||
(`fnrs-form-page.tsx`의 `mx-4 flex flex-wrap justify-center gap-3` 블록을 그대로 옮기고 훅·path만 교체)
|
||||
|
||||
| 버튼 | 조건 | 대표 동작 |
|
||||
| -------- | ---------------------------- | -------------------------------------------------------------------------- |
|
||||
| 목록 | 항상 | `router.push("/sewer-bsc-plan")` |
|
||||
| 저장 | `!isSplmntPrgrsStts` | `type="submit"` → `saveApply` + 임시저장(`SV`) |
|
||||
| 신청완료 | edit && `!isSplmntPrgrsStts` | 체크리스트 완료 + **필수 첨부 완료** 검증 → `saveApply` + `LE` |
|
||||
| 삭제 | edit && `!isSplmntPrgrsStts` | confirm → `delete` → 목록 |
|
||||
| 보완완료 | `isSplmntPrgrsStts` (SL) | `form.handleSubmit` → `useSubmitSupplementSewerBscPlan` |
|
||||
|
||||
**신청완료 사전 검증** (fnrs `handleApplyClick`과 동일 정책)
|
||||
|
||||
1. **체크리스트**: `isFormChecklistComplete(cklstResultList)` — 미완료 시 `"모든 체크리스트 항목을 체크해야 신청이 가능합니다."`
|
||||
2. **필수 첨부**: `esntlAtchYn === "Y"`인 필수첨부 슬롯마다 `esntlAtchFileList`에 `atchFileGroupId`가 있어야 함
|
||||
- Form: `AttachmentsFormSection`의 트리 + 폼 `esntlAtchFileList`
|
||||
- 미충족 시 예: `"필수 첨부파일을 모두 등록해야 신청이 가능합니다."`
|
||||
- 헬퍼 후보: `isFormEsntlAtchComplete(requiredTree, esntlAtchFileList)` (`pbadms-sprt`에 추가)
|
||||
|
||||
저장에는 위 검증을 적용하지 않는다 (임시저장 허용).
|
||||
|
||||
저장/제출 버튼을 섹션 헤더(`gTitle2 gRt`)에 두지 않는다 — **폼 하단 액션바 단일 진입점** (§4-J).
|
||||
|
||||
### 3-4. 라우트
|
||||
|
||||
| 화면 | path | 셸 → FormPage |
|
||||
| ---- | --------------------------- | ------------------------------------------ |
|
||||
| 등록 | `/sewer-bsc-plan/regist` | `mode="create"` |
|
||||
| 수정 | `/sewer-bsc-plan/[id]/edit` | `mode="edit"` + `useSewerBscPlanDetails` |
|
||||
| 상세 | `/sewer-bsc-plan/[id]` | ViewPage (본 문서 범위 밖, fnrs-view 대응) |
|
||||
|
||||
`docSeComCd` 후보: 백엔드 체크리스트·필수첨부 등록값 확인 후 **`SEWER`** (또는 레거시 `DMBP`) — **TBD, CMS 코드와 맞출 것**.
|
||||
|
||||
---
|
||||
|
||||
## 4. 섹션별 상세 구현
|
||||
|
||||
### 4-0. Hidden / 세션 컨텍스트 (폼 루트)
|
||||
|
||||
JSP hidden → React 폼 기본값·세션 스토어로 흡수.
|
||||
|
||||
| JSP | 의미 | React |
|
||||
| ------------------------------- | --------------- | ------------------------------------------------------- |
|
||||
| `chgSe` / `chgSeSp` / `chgSeCd` | 변경구분 | `sewerBscPlan.sewerBscPlanSeComCd` + 표시용 코드명 |
|
||||
| `progrsSttus` | SAVE / PRESENTN | 저장·제출 시 `prgrsSttsComCd`로 매핑 (임시저장 vs 제출) |
|
||||
| `planSeCd` | 고정 `A` | 필요 시 상수 또는 API 필드 확인 |
|
||||
| `adstDstrCd` / `rgnCd` | 행정구역 | `sewerBscPlan.admdstCd` |
|
||||
| `sidoNm` / `gugunNm` | 표시용 | 읽기 전용 표시 (`detDto.sido`/`gugun`) |
|
||||
|
||||
구현: `getCreateDefaultValues(userInfo)`에서 로그인 사용자·소속 지자체 주입.
|
||||
|
||||
---
|
||||
|
||||
### 4-A. 타이틀·브레드크럼
|
||||
|
||||
| JSP | React |
|
||||
| ------------------------ | ------------------------------------------------------ |
|
||||
| `h3` 기본계획검토 | PageLayout title: **하수도기본계획 신청** (IIPBS 명명) |
|
||||
| 설치인가 및 제원협의 > … | 메뉴 메타 기반 breadcrumb |
|
||||
|
||||
별도 섹션 컴포넌트 불필요. 라우트 `page.tsx` / layout metadata로 처리.
|
||||
|
||||
---
|
||||
|
||||
### 4-B. 기본계획변경 신청 (`slide_10`)
|
||||
|
||||
**파일**: `ui/sections/basic-info-form-section.tsx`
|
||||
**래퍼**: `SectionCollapsible` title=`기본계획 신청`
|
||||
**필드 접두사**: `sewerBscPlan.*` + `sewerBscPlanDtl.*`
|
||||
|
||||
| 표시명 | JSP | API 매핑 | UI | 필수 | 비고 |
|
||||
| ---------------- | ----------------- | ------------------------------- | ------------------ | ---- | ---------------------------------- |
|
||||
| 기본계획명 | `drngMtncPlanNm` | `sewerBscPlan.sewerBscPlanNm` | Input | Y | |
|
||||
| 계획년도 | `planYr` | `sewerBscPlanDtl.planYr` | Select (현재~2005) | Y | |
|
||||
| 기준년도 | `crtrYr` | `sewerBscPlanDtl.crtrYr` | Select | Y | |
|
||||
| 1~4단계 목표연도 | `goalYrStep1~4` | `frlvlGoalYr`~`folvlGoalYr` | Select (현재~+30) | Y | 1단계 변경 시 +5/+10/+15 자동 연동 |
|
||||
| 계획개요 | `bzCn` | `sewerBscPlanDtl.bizOtlnCn` | Textarea | Y | |
|
||||
| 구분 | `#chgSeNm` | `sewerBscPlanSeComCd` (+코드명) | 읽기 또는 Select | | 신규/변경 등 |
|
||||
| 신청 지자체 | `${lclgvrnmntNm}` | `admdstCd` | 읽기 전용 | | |
|
||||
|
||||
**동작**
|
||||
|
||||
- `goalYrStep1` onChange → 2·3·4단계 기본값 세팅 + E/F/G 헤더 연도 span 갱신 (`watch` 파생)
|
||||
- JSP 상단 `gRt` 저장/제출은 사용하지 않음 → FormPage 하단 액션바 (§3-3, §4-J)
|
||||
|
||||
---
|
||||
|
||||
### 4-C. 신청자 정보 (`slide_15`)
|
||||
|
||||
**재사용**: `@/widgets/pbadms-sprt`의 `ContactInfoFormSection`
|
||||
**props**: `fieldPrefix="sewerBscPlanDtl"` (또는 dtl 필드 구조에 맞게)
|
||||
|
||||
| 표시 | JSP | API |
|
||||
| ---------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| 신청자 이름/전화/부서/이메일 | `${UsrNm}` 등 서버렌더 | 로그인 사용자 읽기 전용 → `aplcntNm`, `aplcntMblTelno`, `aplcntOgdpNm`, `aplcntEmlAddr` |
|
||||
| 설계자 | `dsgnrNm/Telno/Psitn/Email` | `dsgnrNm`, `dsgnrTelno`, `dsgnrOgdpNm`, `dsgnrEmlAddr` |
|
||||
|
||||
신청자 4필드는 세션에서 defaultValues에 채우고 Input `disabled`.
|
||||
|
||||
---
|
||||
|
||||
### 4-D. 개인정보 동의 (`slide_19`)
|
||||
|
||||
**재사용**: `PrivacyConsentSection`
|
||||
|
||||
| JSP | React |
|
||||
| ----------------------------- | ------------------------------------------------------------------ |
|
||||
| 고지 textarea + 보유기간 문구 | 동일 문구 상수/마크다운 |
|
||||
| `privacyAgree` Y/N | 폼 필드 `privacyAgree: "Y" \| "N"` (API 미전송, 클라이언트 검증만) |
|
||||
|
||||
**검증**: 제출 시 `Y` 필수 (JSP `presentnBtn`과 동일). 저장(임시)은 동의 없이 허용할지 정책 TBD — 기본은 JSP와 같이 **제출만 강제**.
|
||||
|
||||
---
|
||||
|
||||
### 4-E. 사업개요 (`slide_11`)
|
||||
|
||||
**파일**: `ui/sections/outline-form-section.tsx` (신규, 도메인 전용)
|
||||
**API**: `sewerBscPlanOtlnList: SewerBscPlanOtlnItem[]` (planStpNo 1~4)
|
||||
|
||||
| 행(구분) | JSP name | Item 필드 |
|
||||
| ------------ | --------------- | ------------------- |
|
||||
| 계획인구 | `arrPlanPpltn` | `sewerPlanPpltnCnt` |
|
||||
| 처리인구 | `arrPrcsPpltn` | `sewerPrcsPpltnCnt` |
|
||||
| 하수도보급율 | `arrDrngSplyRt` | `sewerPsplyRt` |
|
||||
|
||||
열: 1~4단계 (헤더에 `frlvlGoalYr` 등 표시).
|
||||
|
||||
**버튼**: `이전기본계획조회` → Dialog (`PreviousPlanLookupDialog`)
|
||||
|
||||
- 레거시: `fnbscPlnPopupToggle` + `bscPlnPopup.jsp`
|
||||
- React: Modal + 조회 API (**TBD**: 이전 계획 조회 엔드포인트; 없으면 1차는 Dialog UI만 + mock)
|
||||
|
||||
숫자 입력: 콤마 제거 후 number 전송 (제출 시 JSP `replaceComma` 대체).
|
||||
|
||||
---
|
||||
|
||||
### 4-F. 총사업비 (`slide_12`)
|
||||
|
||||
**파일**: `ui/sections/biz-cst-matrix-form-section.tsx` (**전용 컴포넌트** — fnrs `BusinessCostFormSection` 재사용 금지)
|
||||
**래퍼**: `SectionCollapsible` title=`총사업비` (단위 `백만원`은 헤더 우측)
|
||||
|
||||
**JSP 현실**: 단계(1~4) × 원가 계층(총사업비, 공사비, 처리시설, 하수관로 신설/보수, 펌프장, 배수설비, 기타, 부대경비, 설계/감리/부대비). 일부 readonly·자동합산 JS.
|
||||
|
||||
**신규 API**: `bizCstList: SewerBscPlanBizCstItem[]` = `{ planStpNo, acntgSeCd, cstrnAmt }`
|
||||
|
||||
**구현 방향 (`BizCstMatrixFormSection` 전용)**
|
||||
|
||||
- 행 = `useAcntgSeMngTree` → `buildAcntgCostItems` (fnrs `BusinessCostFormSection`과 동일 출처)
|
||||
- `costItems` 로드 시 `useEffect`로 `bizCstList`를 `mergeBizCstList(existing, costItems)`로 동기화
|
||||
- 열 = `planStpNo` 1~4 (헤더에 목표연도 표시)
|
||||
- readonly 행(`CostItemDef.readonly=true`)은 children 합산으로 자동계산; Input에 `readOnly` + `bg-muted`
|
||||
- 변경 시 `setAmt` → `recalculateBizCstMatrix(list, costItems)` → `setValue("bizCstList")`
|
||||
- 저장 시 섹션 onChange 합산을 신뢰하여 `bizCstList` 그대로 전송 (`toBizCstSaveList` identity)
|
||||
|
||||
**표준사업비 조회** 버튼은 JSP에서 주석 처리됨 → **미구현**.
|
||||
|
||||
---
|
||||
|
||||
### 4-G. 재원분담 (`slide_13`)
|
||||
|
||||
**주의**: fnrs의 `FnrsSharFormSection`(재원협의 공유구분 트리)과 **다름**.
|
||||
|
||||
| 행 | JSP | `SewerBscPlanFnrsCstItem` |
|
||||
| ------------ | -------------- | ------------------------- |
|
||||
| 총사업비 | `arrTotAmnt` | `sumAmt` (또는 파생) |
|
||||
| 국고 | `arrNlepAmt` | `gvexpAmt` |
|
||||
| 지방비 | `arrLcepAmt` | `lcexpAmt` |
|
||||
| 원인자부담금 | `arrCusrAlotm` | `orgprBdchgAmt` |
|
||||
| 기타 | `arrEtcAmt` | `etcAmt` |
|
||||
|
||||
**파일**: `ui/sections/fnrs-cst-form-section.tsx` (신규)
|
||||
데이터: `fnrsCstList` 길이 4 (`planStpNo` 1~4).
|
||||
|
||||
검증(선택): 단계별 `gvexp+lcexp+orgpr+etc === sumAmt` (JSP `calculateTotalFunding` 참고).
|
||||
|
||||
---
|
||||
|
||||
### 4-H. 처리시설별 하수도정비기본계획 (`slide_14`) — 핵심 복잡도
|
||||
|
||||
**JSP 동작**
|
||||
|
||||
1. `BscFctList` 체크박스로 처리시설 다중 선택 (`arrBscFctCd`)
|
||||
2. 선택 시 `createFormSection(code, name)`로 **당초 4단계 | 현재 | 변경 4단계** 매트릭스 동적 삽입
|
||||
→ **React**: 세로 삽입 대신 `@common/components` `Tabs`로 시설별 패널 관리 (§아래 Tabs 규칙)
|
||||
3. 활성 `formFields`(축소판): 처리구역면적, 하수처리인구, 계획하수량, 시설용량, 분류식 오수/우수, 합류식, 차집, 배수설비, 오수중계/일반/우수 펌프
|
||||
4. 시설별 필수첨부 `createFileAttachmentSection`
|
||||
5. `fetchBasicPlanData`로 당초(이전) 데이터 바인딩
|
||||
|
||||
**API 매핑**
|
||||
|
||||
| UI | DTO |
|
||||
| -------------------- | ------------------------------------------------------------- |
|
||||
| 선택 시설 목록 | `sewerBscPlanTmplntList[].swtrmtFcltCd` (+ `atchFileGroupId`) |
|
||||
| 단계별 수치 (변경측) | `sewerBscPlanTmplntDtlList[]` → `SewerBscPlanTmplntDtlItem` |
|
||||
| 임시저장 | `tmplntTmprStrgList` (편집 중 임시, 필요 시) |
|
||||
|
||||
필드 대응 (변경 단계 기준):
|
||||
|
||||
| UI 라벨 | `SewerBscPlanTmplntDtlItem` |
|
||||
| -------------- | --------------------------- |
|
||||
| 처리구역면적 | `prcsZoneArea` |
|
||||
| 하수처리인구 | `swtrmtPpltnCnt` |
|
||||
| 계획하수량 | `planSwqty` |
|
||||
| 시설용량 | `fcltCpct` |
|
||||
| 분류식 오수 | `sprsysDrtwPplLen` |
|
||||
| 분류식 우수 | `sprsysExlnPplLen` |
|
||||
| 합류식 | `cbsysPplLen` |
|
||||
| 차집관로 | `icptgPplLen` |
|
||||
| 배수설비 | `drgCnt` |
|
||||
| 오수 중계 펌프 | `drtwRlyPumpCnt` |
|
||||
| 오수 일반 펌프 | `drtwPumpCnt` |
|
||||
| 우수 펌프 | `exlnPumpCnt` |
|
||||
|
||||
**구현 구성**
|
||||
|
||||
```
|
||||
ui/sections/tmplnt-form-section.tsx
|
||||
├─ TmplntFacilityPicker # BscFctList Checkbox 목록 (시설 마스터 API TBD)
|
||||
└─ Tabs (@common/components Tabs) # 선택 시설별 동적 패널
|
||||
├─ TabsList / TabsTrigger # value=swtrmtFcltCd, 라벨=시설명
|
||||
└─ TabsContent (시설 1개당)
|
||||
├─ TmplntMatrixTable # 당초|현재|변경 매트릭스 (useFieldArray)
|
||||
└─ TmplntFacilityAttachments # 시설별 필수첨부 (선택)
|
||||
```
|
||||
|
||||
**Tabs 관리 규칙** (`packages/common/components/src/ui/tabs`)
|
||||
|
||||
- `BscFctList` 체크 **선택** → `useFieldArray` append + 해당 시설 `TabsTrigger`/`TabsContent` 추가 → `Tabs` `value`를 신규 시설로 전환
|
||||
- 체크 **해제** → confirm 후 remove + 해당 탭 제거 → 남은 탭 중 하나로 `value` 이동 (없으면 Tabs 영역 비표시)
|
||||
- 선택 시설이 0개면 Tabs UI 숨김; 1개 이상이면 Tabs로 시설별 패널 전환
|
||||
- 매트릭스·첨부는 각 `TabsContent` 안에만 렌더 (JSP의 세로 동적 삽입을 탭 패널로 대체)
|
||||
|
||||
**매트릭스 열**
|
||||
|
||||
- **당초 열**: 이전계획 API 조회 결과 읽기 전용 (없으면 빈 칸)
|
||||
- **현재 열**: 기준년도 시점 값 (API 제공 시)
|
||||
- **변경 열**: 편집 가능 → 저장 payload의 dtl만 전송
|
||||
|
||||
시설 마스터 목록 API: 레거시 `BscFctList` 대체 — **TBD** (`swtrmtFclt` 계열).
|
||||
|
||||
`bundle-dynamic-imports`: `TmplntFormSection`(또는 TabsContent 내부 매트릭스)을 `next/dynamic` 후보.
|
||||
|
||||
---
|
||||
|
||||
### 4-I. 체크리스트 + 첨부 (`slide_16`)
|
||||
|
||||
#### I-1. 체크리스트
|
||||
|
||||
**재사용**: `ChecklistFormSection`
|
||||
`docSeComCd="<SEWER|DMBP TBD>"`
|
||||
`fieldPrefix`: 마스터에서 `taskSeComCd`를 읽는 경로 (예: `sewerBscPlan`)
|
||||
|
||||
| JSP | React |
|
||||
| ----------------------- | ------------------------------------------- |
|
||||
| 업무탭 `ceckEssntlArr` | 코드 `taskSeComCd` 다중 → Tabs |
|
||||
| 진행률 / 전체 예·아니오 | 위젯 내장 로직 |
|
||||
| `exmntResult` Y/N | `cklstResultList[].selected` (+ `picRvwCn`) |
|
||||
|
||||
저장: `cklstResultList: CklstResultItem[]`
|
||||
|
||||
#### I-2. 필수 첨부 (탭별)
|
||||
|
||||
**재사용**: `AttachmentsFormSection`
|
||||
`docSeComCd` 동일, `esntlAtchFileList`
|
||||
|
||||
레거시: 체크리스트 탭마다 `essntlList` + `uploadFile` multipart.
|
||||
신규: TUS/`attach-service` + `esntlAtchFileId` / `atchFileGroupId` (fnrs와 동일).
|
||||
|
||||
#### I-3. 기타 첨부
|
||||
|
||||
`AttachmentsFormSection`의 etc 영역 또는 `atchFileGroupId` on `sewerBscPlanDtl`.
|
||||
JSP `uploadFileETC` multiple → Zip 안내 문구 유지.
|
||||
|
||||
---
|
||||
|
||||
### 4-J. 저장 / 제출
|
||||
|
||||
**UI 구성**: [`fnrs-form-page.tsx` 279~323](../../src/pages/fnrs-cnsltn/ui/fnrs-form-page.tsx) 과 **동일**.
|
||||
마크업·분기(`isSplmntPrgrsStts` / `isEditMode`)·버튼 색상·`disabled={isSubmitting}` 패턴을 그대로 두고, **호출 API·목록 path만 sewer** 로 교체한다.
|
||||
|
||||
```tsx
|
||||
<div className="mx-4 flex flex-wrap justify-center gap-3 sm:gap-4">
|
||||
<Button color="white" type="button" onClick={() => router.push("/sewer-bsc-plan")} disabled={isSubmitting}>
|
||||
목록
|
||||
</Button>
|
||||
{!isSplmntPrgrsStts ? (
|
||||
<>
|
||||
<Button type="submit" disabled={isSubmitting}>저장</Button>
|
||||
{isEditMode && (
|
||||
<>
|
||||
<Button color="green" type="button" onClick={handleApplyClick} disabled={isSubmitting}>
|
||||
신청완료
|
||||
</Button>
|
||||
<Button color="red" type="button" onClick={handleDelClick} disabled={isSubmitting}>
|
||||
삭제
|
||||
</Button>
|
||||
</>
|
||||
)}
|
||||
</>
|
||||
) : (
|
||||
<Button type="button" onClick={form.handleSubmit(onSplmntCmptn)} disabled={isSubmitting}>
|
||||
보완완료
|
||||
</Button>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
| 버튼 | fnrs 대응 | sewer API / 동작 |
|
||||
| -------- | ----------------------------- | ------------------------------------------------------------ |
|
||||
| 목록 | `router.push("/fnrs-cnsltn")` | `router.push("/sewer-bsc-plan")` |
|
||||
| 저장 | `saveApply` + 임시저장 | `useSaveApplySewerBscPlan` + `prgrsSttsComCd`=임시저장(`SV`) |
|
||||
| 신청완료 | `handleApplyClick` → 제출 | 체크리스트+필수첨부 검증 → `saveApply` + `LE` (상태코드 TBD) |
|
||||
| 삭제 | `handleDelClick` | `useDeleteSewerBscPlan`(또는 동등) → 목록 |
|
||||
| 보완완료 | `onSplmntCmptn` | `useSubmitSupplementSewerBscPlan` |
|
||||
|
||||
| JSP | 진행값 | URL | React |
|
||||
| ---- | ---------- | ------------------------- | ---------------------------------------------------------- |
|
||||
| 저장 | `SAVE` | `insertFnrscDmbp.do` | `saveApply` + 임시저장 코드 |
|
||||
| 제출 | `PRESENTN` | `insertFnrscDscss.do` (!) | `saveApply` + 제출 상태코드 — **백엔드 상태코드 확인 TBD** |
|
||||
|
||||
페이로드 조립 (`buildApplyPayload`):
|
||||
|
||||
```ts
|
||||
SewerBscPlanApplySaveRequestDto {
|
||||
sewerBscPlan, sewerBscPlanDtl,
|
||||
sewerBscPlanOtlnList, bizCstList, fnrsCstList,
|
||||
sewerBscPlanTmplntList, tmplntTmprStrgList?,
|
||||
cklstResultList, esntlAtchFileList,
|
||||
splmntDmndList?, rvwOpnnList? // 등록 화면에서는 보통 빈 배열
|
||||
}
|
||||
```
|
||||
|
||||
성공 후: `invalidateQueries(sewerBscPlanBaseKey)` → `router.push('/sewer-bsc-plan')` (신청완료는 상세로 보낼 수 있음 — fnrs와 동일 정책).
|
||||
|
||||
권한: JSP `AUTH3` → 기존 AS 권한 훅/역할로 버튼 `disabled`/`hidden`.
|
||||
|
||||
---
|
||||
|
||||
## 5. API / DTO 연결
|
||||
|
||||
Base: `/as-service/api/v1/sewer-bsc-plans`
|
||||
엔티티: `@/entities/sewer-bsc-plan`
|
||||
|
||||
| 화면 동작 | Hook / Service | 비고 |
|
||||
| -------------- | ---------------------------------------- | ---------------- |
|
||||
| 등록 저장·제출 | `useSaveApplySewerBscPlan` → `saveApply` | 본 문서 핵심 |
|
||||
| 수정 로드 | `useSewerBscPlanDetails(docNo, chgCycl)` | 편집 시 |
|
||||
| 마스터만 | `useSewerBscPlan` | 목록 행 클릭 등 |
|
||||
| 보완 제출 | `useSubmitSupplementSewerBscPlan` | edit + `prgrsSttsComCd=SL` 시 폼 하단 [보완완료] |
|
||||
| 기술검토 | `useTechReviewSewerBscPlan` | 등록 JSP 범위 밖 |
|
||||
|
||||
등록 JSP에 없는 섹션(보완요구·검토의견)은 **상세/검토 화면**에서 `SplmntDmndFormSection` / 검토의견 섹션으로 후속 구현.
|
||||
|
||||
---
|
||||
|
||||
## 6. 권장 파일 배치
|
||||
|
||||
```
|
||||
apps/as/
|
||||
├── app/(with-base-layout)/sewer-bsc-plan/
|
||||
│ └── regist/page.tsx
|
||||
├── src/pages/sewer-bsc-plan/
|
||||
│ ├── lib/
|
||||
│ │ ├── sewer-bsc-plan-regist-schema.ts # zod
|
||||
│ │ └── form-data-mapper.ts # Det ↔ Form, Apply payload
|
||||
│ ├── model/
|
||||
│ │ └── (필요 시 table columns)
|
||||
│ └── ui/
|
||||
│ ├── sewer-bsc-plan-regist-page.tsx
|
||||
│ ├── sewer-bsc-plan-form-page.tsx
|
||||
│ ├── components/
|
||||
│ │ └── previous-plan-lookup-dialog.tsx
|
||||
│ └── sections/
|
||||
│ ├── basic-info-form-section.tsx
|
||||
│ ├── outline-form-section.tsx # 사업개요
|
||||
│ ├── biz-cst-matrix-form-section.tsx # 총사업비 (전용)
|
||||
│ ├── fnrs-cst-form-section.tsx # 재원분담
|
||||
│ └── tmplnt-form-section.tsx # 처리시설 (Checkbox + Tabs)
|
||||
└── docs/sewer-bsc-plan/
|
||||
└── dmbp-regist-migration.md # 본 문서
|
||||
```
|
||||
|
||||
공통 재사용 (신규 작성 최소화):
|
||||
|
||||
- `ContactInfoFormSection`, `PrivacyConsentSection`
|
||||
- `ChecklistFormSection`, `AttachmentsFormSection`
|
||||
- `SectionCollapsible`
|
||||
- `Tabs` / `TabsList` / `TabsTrigger` / `TabsContent` (`@common/components` — 처리시설 패널)
|
||||
|
||||
도메인 전용 (재사용 금지):
|
||||
|
||||
- `BizCstMatrixFormSection` — 총사업비 (fnrs `BusinessCostFormSection` 미사용)
|
||||
- 폼 하단 액션바 — `fnrs-form-page` 279~323 복제, API만 sewer
|
||||
|
||||
---
|
||||
|
||||
## 7. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입 (등록)
|
||||
CALL 로그인사용자조회
|
||||
CALL 코드조회(SEWERBSCPLANSE, SEWER, …) // 병렬
|
||||
CALL 체크리스트트리(docSeComCd) // 병렬
|
||||
CALL 필수첨부트리(docSeComCd) // 병렬
|
||||
CALL 처리시설마스터목록 // TBD (BscFctList)
|
||||
DISPLAY 폼 defaultValues
|
||||
|
||||
ON 1단계목표연도 CHANGE DO
|
||||
SET 2·3·4단계 연도 (+5/+10/+15)
|
||||
DISPLAY E/F/G/H 헤더 연도
|
||||
END ON
|
||||
|
||||
ON 처리시설 체크 DO
|
||||
ADD tmplntList 항목
|
||||
ADD TabsTrigger / TabsContent (시설 패널)
|
||||
SET Tabs value = 신규 시설
|
||||
CALL 이전기본계획수치(시설코드) // 당초열, TBD
|
||||
END ON
|
||||
|
||||
ON 처리시설 체크해제 DO
|
||||
CONFIRM 제거
|
||||
REMOVE tmplntList + 해당 Tabs 패널
|
||||
SET Tabs value = 남은 시설 (없으면 Tabs 숨김)
|
||||
END ON
|
||||
|
||||
ON [이전기본계획조회] CLICK DO
|
||||
OPEN PreviousPlanLookupDialog
|
||||
END ON
|
||||
|
||||
ON [저장] CLICK DO
|
||||
VALIDATE zod (동의 제외 가능)
|
||||
CALL saveApply(payload, 임시저장 상태)
|
||||
NAVIGATE 목록
|
||||
END ON
|
||||
|
||||
ON [신청완료] CLICK DO
|
||||
VALIDATE zod + privacyAgree=Y + 체크리스트 완료 + 필수첨부(esntlAtchYn=Y) 완료
|
||||
CONFIRM 신청 확인
|
||||
CALL saveApply(payload, 제출 상태 LE)
|
||||
NAVIGATE 상세
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. JSP ↔ 신규 갭·리스크
|
||||
|
||||
| # | 이슈 | 대응 |
|
||||
| --- | ---------------------------------------------------- | ------------------------------------------------- |
|
||||
| 1 | JSP 제출 URL이 `dscss`로 분기 (오타/구프로세스 가능) | 신규는 `saveApply` 단일 진입으로 통일 |
|
||||
| 2 | 총사업비 UI 계층 ≠ `BizCstItem` | `BizCstMatrixFormSection` 전용 + `acntgSeCd` 매핑 테이블 |
|
||||
| 3 | 재원분담 ≠ fnrs shar | 전용 `fnrs-cst-form-section` |
|
||||
| 4 | 처리시설 매트릭스(당초/현재/변경) | Checkbox 선택 → Tabs 패널; 저장은 변경 dtl 중심; 당초는 조회 전용 |
|
||||
| 5 | 시설·이전계획 API | TBD — 미정 시 체크박스 목록 mock(`faker`)만 |
|
||||
| 6 | `docSeComCd` 값 | CMS/체크리스트 마스터와 합의 |
|
||||
| 7 | 레거시 multipart vs TUS | fnrs 첨부 패턴 준수 |
|
||||
| 8 | 주석 처리된 상세 `formFields` (자연발생인구 등) | **축소된 formFields만** 이관; 주석 블록 복원 금지 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 구현 순서 (권장)
|
||||
|
||||
1. 라우트 + `FormPage` 골격 + zod 스키마(마스터·dtl·동의) + 폼 하단 액션바(§4-J)
|
||||
2. B·C·D 섹션 (공통 위젯 최대 활용)
|
||||
3. E 사업개요 + G 재원분담 (4열 매트릭스 패턴 공유)
|
||||
4. F 총사업비 (`BizCstMatrixFormSection` 전용)
|
||||
5. I 체크리스트·첨부
|
||||
6. H 처리시설 (`BscFctList` Checkbox + `@common/components` Tabs — 가장 복잡)
|
||||
7. 저장/신청완료/삭제/보완완료 API 연동 (§4-J)
|
||||
8. 이전계획 Dialog (API 확정 후)
|
||||
|
||||
---
|
||||
|
||||
## 10. 체크리스트 (jsp-migration-as)
|
||||
|
||||
- [ ] contents만 이관 (include 제외)
|
||||
- [ ] vercel-react-best-practices 적용 (Query 병렬·파생상태·dynamic)
|
||||
- [ ] `@common/components` + 필요 시 DataTable
|
||||
- [ ] API·모델은 `@/entities/sewer-bsc-plan` 우선
|
||||
- [ ] 목데이터는 `@faker-js/faker`만 (시설 마스터 등 TBD 구간)
|
||||
- [ ] 로딩·빈·에러 상태
|
||||
- [ ] `router.push`로 목록 복귀
|
||||
|
||||
---
|
||||
|
||||
## 11. 후속 문서
|
||||
|
||||
- 목록(`dmbpList.jsp`) / 상세(`dmbpView.jsp`) / 수정(`dmbpModify.jsp`)은 본 문서와 동일 섹션 체계로 별도 확장
|
||||
- 화면설계서 SPEC 형식이 필요하면 `docs/sewer-bsc-plan/SPEC.md`로 분리 (영역 A~J 표 + API 표)
|
||||
@@ -1,407 +0,0 @@
|
||||
# 화면설계서: 결재선 관리
|
||||
|
||||
## 1. 기본 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | -------------------------------------------- |
|
||||
| 버전 | 0.3 |
|
||||
| 프로세스명 | UI설계 |
|
||||
| 화면명 | 결재선 관리 |
|
||||
| 화면 유형 | [v] 조회 [v] 입력 [v] 수정 [v] 삭제 [ ] 출력 |
|
||||
| 메뉴 경로 | 디지털행정지원 > 시스템관리 > 결재선 관리 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 화면 목적
|
||||
|
||||
전자결재 처리에 사용할 **결재서식**(템플릿)을 등록·관리하고, 각 서식별로 **결재선**(결재구분·결재자·순서)을 구성한다. 상단의 결재서식 목록에서 하나를 선택하면 하단 영역에 해당 서식의 결재선이 표시되며, 사용자는 **그리드 인라인 폼**으로 결재자를 등록·수정한다. **행 추가 또는 한 행 수정 중에는 다른 행을 편집할 수 없다**(단일 행 편집 잠금). 드래그로 순서를 변경한 뒤 **[결재선 저장]** 으로 서버에 반영한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 화면 구성
|
||||
|
||||
### 3-1. 전체 레이아웃
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 페이지 타이틀: 결재선 관리 브레드크럼: 디지털행정지원 > … > │
|
||||
├───────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ [영역 A] 전자결재선 관리 목록 [서식 등록] │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 전자결재서식아이디 | 결재서식명 | 문서구분 | 등록일시 | 관리 │ │
|
||||
│ ├──────────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ TMPL-0001 (선택 행 강조) … [수정][삭제] │ │
|
||||
│ └──────────────────────────────────────────────────────────────────────┘ │
|
||||
├───────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ [영역 B] 결재선 관리 선택된 서식: TMPL-0001 [결재선 저장] │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ [영역 B-2] 결재선 그리드 (인라인 편집 + 행 드래그 — @dnd-kit) │ │
|
||||
│ │ ⋮⋮ | 결재선아이디 | 결재순서 | 결재구분 ▼ | 결재자 [선택] | 등록일시 | 관리 │ │
|
||||
│ │ ⋮⋮ | APLN-0001 | [ 1 ] | [검토자 ▼] | [김민수 ][선택] | … | [저장][삭제] │ │
|
||||
│ │ ⋮⋮ | (신규) | [ 2 ] | [승인자 ▼] | [ ][선택] | — | [저장][취소] │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ [행 추가] │
|
||||
│ ※ 결재자 등록·수정은 그리드 셀에서 직접 입력. 검토인력만 [선택] 팝업/다이얼로그 │
|
||||
│ ※ 행 추가·수정 중: 해당 행만 편집 가능, 나머지 행·[행 추가]·드래그 비활성 │
|
||||
└───────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-2. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입
|
||||
CALL GET /as-elapr-service/api/v1/elapr-tmplt
|
||||
DISPLAY 결재서식 그리드 (영역 A)
|
||||
DISPLAY 빈 상태 안내 (영역 B) // 서식 미선택 시 그리드·툴바 비활성
|
||||
|
||||
// 영역 A: 서식 행 선택
|
||||
ON 영역 A 행 CLICK DO
|
||||
SET 선택된 서식 = 행.elaprTmpltId
|
||||
CALL GET /as-elapr-service/api/v1/elapr-apln?elaprTmpltId={id}
|
||||
DISPLAY 결재선 그리드 (영역 B-2) — 조회 모드
|
||||
END ON
|
||||
|
||||
// 영역 A: 신규 서식 등록
|
||||
ON [서식 등록] 버튼 CLICK DO
|
||||
OPEN 결재서식 등록 다이얼로그
|
||||
ON 확인 DO
|
||||
CALL POST /as-elapr-service/api/v1/elapr-tmplt
|
||||
CALL GET /as-elapr-service/api/v1/elapr-tmplt
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 A: 서식 수정·삭제 (다이얼로그 유지)
|
||||
ON 영역 A [수정] / [삭제] DO
|
||||
(기존과 동일 — PUT / DELETE elapr-tmplt)
|
||||
END ON
|
||||
|
||||
// 영역 B: 행 추가 (인라인 신규 행)
|
||||
ON [행 추가] 버튼 CLICK DO
|
||||
VALIDATE 서식 선택됨
|
||||
VALIDATE 편집 중인 행 없음 (editingRowKey == null)
|
||||
ADD 영역 B-2 그리드 맨 아래 편집 가능 행
|
||||
SET editingRowKey = rowKey (draft-{timestamp})
|
||||
SET 편집상태 = 신규
|
||||
SET aplnId = 미설정 (POST 저장 시 서버 fn_gen_apln_id 발급)
|
||||
SET atrzSeqNo = 현재 행 수 + 1
|
||||
SET atrzSeComCd, aprvrUuid = 빈 값
|
||||
DISABLE 나머지 행 편집 · [행 추가] · 드래그 · [결재선 저장](정책에 따라)
|
||||
END ON
|
||||
|
||||
// 영역 B-2: 기존 행 수정 진입
|
||||
ON 행별 [수정] CLICK DO
|
||||
VALIDATE 편집 중인 행 없음
|
||||
SET editingRowId = 행.aplnId
|
||||
SET 해당 행만 편집 모드
|
||||
DISABLE 나머지 행 편집 · [행 추가] · 드래그
|
||||
END ON
|
||||
|
||||
// 영역 B-2: 인라인 편집
|
||||
ON 그리드 셀 변경 DO
|
||||
VALIDATE 변경 대상 행 == editingRowId
|
||||
SET 해당 행 dirty = true
|
||||
END ON
|
||||
|
||||
ON 셀 [선택] (검토인력) CLICK DO
|
||||
OPEN 검토인력 선택 다이얼로그 (단일 선택)
|
||||
ON 선택 DO
|
||||
SET 행.aprvrUuid = 선택인력.uuid
|
||||
SET 행.aprvrNm = 선택인력.성명 // UI 표시용 (응답 DTO에 없음 — 로컬 보조 필드)
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 B-2: 행별 저장
|
||||
ON 행별 [저장] CLICK DO
|
||||
VALIDATE atrzSeComCd, aprvrUuid, atrzSeqNo
|
||||
IF 편집상태 = 신규 THEN
|
||||
CALL POST /as-elapr-service/api/v1/elapr-apln
|
||||
ELSE
|
||||
CALL PUT /as-elapr-service/api/v1/elapr-apln/{aplnId}
|
||||
END IF
|
||||
CALL GET /as-elapr-service/api/v1/elapr-apln?elaprTmpltId={id}
|
||||
CLEAR editingRowId
|
||||
ENABLE 전체 행 조회 모드 · [행 추가] · 드래그
|
||||
END ON
|
||||
|
||||
// 영역 B: 결재선 저장 (드래그 순서 일괄 반영)
|
||||
ON [결재선 저장] 버튼 CLICK DO
|
||||
VALIDATE 서식 선택됨
|
||||
VALIDATE 편집 중인 행 없음
|
||||
REORDER atrzSeqNo = 그리드 행 순서 (1..n)
|
||||
FOR EACH dirty 또는 순서 변경된 행 DO
|
||||
CALL PUT /as-elapr-service/api/v1/elapr-apln/{aplnId} // atrzSeqNo 등 반영
|
||||
END FOR
|
||||
FOR EACH 신규 미저장 행 DO
|
||||
CALL POST /as-elapr-service/api/v1/elapr-apln
|
||||
END FOR
|
||||
CALL GET /as-elapr-service/api/v1/elapr-apln?elaprTmpltId={id}
|
||||
TOAST "결재선이 저장되었습니다."
|
||||
END ON
|
||||
|
||||
// 영역 B-2: 행 드래그
|
||||
ON 영역 B-2 행 DRAG END DO
|
||||
VALIDATE 편집 중인 행 없음
|
||||
REORDER 그리드 행
|
||||
SET 각 행 atrzSeqNo = 행 인덱스 + 1 (UI 즉시 반영, 서버는 [결재선 저장] 또는 행별 [저장])
|
||||
END ON
|
||||
|
||||
// 영역 B-2: 행 삭제
|
||||
ON 행별 [삭제] CLICK DO
|
||||
CONFIRM "선택한 결재선을 삭제하시겠습니까?"
|
||||
IF 서버 저장된 행 THEN
|
||||
CALL DELETE /as-elapr-service/api/v1/elapr-apln/{aplnId}
|
||||
END IF
|
||||
REMOVE 그리드 행 (신규 미저장 행은 API 호출 없이 제거)
|
||||
CALL GET /as-elapr-service/api/v1/elapr-apln?elaprTmpltId={id}
|
||||
END ON
|
||||
|
||||
ON 행별 [취소] CLICK DO // 신규·수정 공통
|
||||
IF 편집상태 = 신규 THEN REMOVE 임시 행
|
||||
ELSE RESTORE 행 스냅샷 (수정 취소)
|
||||
CLEAR editingRowId
|
||||
ENABLE 전체 행 조회 모드 · [행 추가] · 드래그
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 영역 A: 전자결재선 관리 목록
|
||||
|
||||
선택된 결재서식이 영역 B의 작업 대상이 된다. 행 클릭으로 선택 상태를 표시(좌측 컬러 바·배경 강조)한다.
|
||||
|
||||
### 4-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ----------------------------------------------- |
|
||||
| 섹션 타이틀 | 전자결재선 관리 목록 |
|
||||
| 우측 버튼 | **[서식 등록]** — 결재서식 등록 다이얼로그 오픈 |
|
||||
|
||||
### 4-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 타입 | 비고 |
|
||||
| ------------------ | -------------- | ------ | --------------------------------------- |
|
||||
| 전자결재서식아이디 | `elaprTmpltId` | string | 등록 시 서버(DB 함수) 자동 발급 |
|
||||
| 결재서식명 | `elaprTmpltNm` | string | |
|
||||
| 문서구분 | `docSeComNm` | string | 코드 `docSeComCd`, 상위코드 `ASDOCSECD` |
|
||||
| 등록일시 | `regDt` | string | `yyyy-MM-dd HH:mm:ss` |
|
||||
| 관리 | — | — | 행별 **[수정] · [삭제]** 버튼 |
|
||||
|
||||
- 행 클릭 시: `elaprTmpltId` 선택 → 영역 B 라벨·B-2 그리드 갱신.
|
||||
- 페이지네이션: Spring `Pageable` (`page`, `size`, `sort`).
|
||||
|
||||
### 4-3. 버튼
|
||||
|
||||
| 버튼명 | 위치 | 동작 |
|
||||
| --------- | -------------- | ----------------------------------------------- |
|
||||
| 서식 등록 | 섹션 우측 상단 | 결재서식 등록 다이얼로그 오픈 |
|
||||
| 수정 | 행별 | 결재서식 수정 다이얼로그 (기존 값 초기화) |
|
||||
| 삭제 | 행별 | 확인 후 삭제. 선택 중인 서식이면 영역 B 초기화. |
|
||||
|
||||
### 4-4. 다이얼로그(개요)
|
||||
|
||||
| 다이얼로그명 | 트리거 | 입력 항목 | 비고 |
|
||||
| ------------------ | ----------- | ----------------------------------------------- | ----------------------------------------- |
|
||||
| 결재서식 등록 | [서식 등록] | `elaprTmpltNm`, `docSeComCd` | `elaprTmpltExpln` 선택, ID는 저장 후 응답 |
|
||||
| 결재서식 수정 | 행별 [수정] | `elaprTmpltNm`, `docSeComCd`, `elaprTmpltExpln` | ID는 변경 불가 |
|
||||
| 결재서식 삭제 확인 | 행별 [삭제] | (확인/취소) | |
|
||||
|
||||
---
|
||||
|
||||
## 5. 영역 B: 결재선 관리
|
||||
|
||||
영역 A에서 선택된 `elaprTmpltId` 기준으로 결재선을 관리한다. **등록·수정은 B-2 그리드 인라인 폼**으로 수행하며, 검토인력 지정만 **[선택]** 보조 다이얼로그를 사용한다.
|
||||
|
||||
### 5-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 섹션 타이틀 | 결재선 관리 |
|
||||
| 우측 라벨 | `선택된 서식: {elaprTmpltId}` — 미선택 시 영역 B 비활성 |
|
||||
| 우측 버튼 | **[행 추가]** — 편집 중인 행이 없을 때만 활성 · **[결재선 저장]** — 편집 중인 행이 없을 때만 활성(순서·미저장 행 일괄 반영) |
|
||||
|
||||
### 5-2. 영역 B-2: 결재선 그리드 (인라인 편집)
|
||||
|
||||
#### 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 입력 UI (편집 모드) | 비고 |
|
||||
| ------------- | ------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
||||
| (드래그 핸들) | — | — | `useSortable` 연동 |
|
||||
| 결재선아이디 | `aplnId` | 읽기 전용 | 신규 행: `—`, 저장 후 서버 `aplnId` 표시 |
|
||||
| 결재순서번호 | `atrzSeqNo` | 읽기 전용 (그리드 행 순서 1부터 표시) | 저장 시 행 순서 기준 자동 채번 |
|
||||
| 결재구분 | `atrzSeComCd` | Select (`ATRZSECD` 공통코드) | 표시명 `atrzSeComNm` (조회 행) |
|
||||
| 결재자 | `aprvrUuid` | 읽기 전용 이름 + **[선택]** 버튼 | 응답에 성명 없음 — 선택 시 로컬 `aprvrNm` 유지 |
|
||||
| 등록일시 | `regDt` | 읽기 전용 | 신규 행은 `—` |
|
||||
| 관리 | — | 편집 중인 행: **[저장] [취소]** · 조회 행: **[수정] [삭제]** (다른 행 편집 중이면 비활성) |
|
||||
|
||||
#### 인라인 편집 정책
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **단일 행 편집** | **행 추가 또는 한 행 수정 중에는 다른 행을 편집할 수 없다.** `editingRowId` 로 현재 편집 행 1건만 허용. |
|
||||
| 편집 잠금 시 비활성 | 다른 행: 셀·[수정]·[삭제] 비활성 · `[행 추가]` 비활성 · 행 드래그 비활성 · (선택) `[결재선 저장]` 비활성 |
|
||||
| 편집 해제 | 행별 **[저장]** 성공 또는 **[취소]** 시 `editingRowId` 초기화 후 전체 조회 모드 복귀 |
|
||||
| 조회 행 | 편집 중이 아닐 때 읽기 전용. **[수정]** 클릭 시 해당 행만 편집 모드 진입 |
|
||||
| 신규 행 | `[행 추가]` 시 맨 아래 편집 행 1건 생성 (`editingRowId` = 임시 키) |
|
||||
| 필수값 | `atrzSeComCd`, `aprvrUuid` |
|
||||
| 순서 중복 | 저장 시 행 순서로 자동 채번하므로 중복 없음 |
|
||||
| 결재구분 코드 | `ATRZSECD` — 예: `ATRZ01` 검토자, `ATRZ02` 승인자, `ATRZ03` 최종승인자 |
|
||||
| **순서 제약** | `ATRZ01`은 최상단 블록, `ATRZ03`은 최하단 블록. 드래그 종료·저장 시 `validateAtrzOrder`로 검증, 위반 시 적용/저장 불가 (결재구분 변경 시에는 미검증) |
|
||||
| 저장 단위 | 행별 **[저장]** (단건 POST/PUT) 또는 툴바 **[결재선 저장]** (일괄) |
|
||||
|
||||
#### 행 드래그 정렬 (`@dnd-kit` + `useSortable`)
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| 목적 | 결재 단계 순서를 그리드에서 직접 변경 |
|
||||
| 라이브러리 | `@dnd-kit/core`, `@dnd-kit/sortable` — 테이블 행 POC 후 확정 |
|
||||
| 저장 시점 | 드래그는 클라이언트 상태만 변경 → **[결재선 저장]** 또는 행별 **[저장]** 시 `atrzSeqNo` PUT |
|
||||
| 편집 중 | `editingRowKey != null` 이면 드래그 **불가** |
|
||||
| 순서 제약 | 드래그 종료 시 `validateAtrzOrder` — 실패하면 순서 변경 미적용 + 안내. 결재구분 미선택 행은 드래그 불가 |
|
||||
|
||||
### 5-3. 보조 다이얼로그 (검토인력만)
|
||||
|
||||
| 다이얼로그명 | 트리거 | 결과 |
|
||||
| ------------- | ----------------------- | ---------------------------------- |
|
||||
| 검토인력 선택 | 그리드 결재자 셀 [선택] | `aprvrUuid` 및 UI용 `aprvrNm` 반영 |
|
||||
|
||||
> 결재자 **등록·수정 다이얼로그는 사용하지 않음** (v0.2 변경).
|
||||
|
||||
---
|
||||
|
||||
## 6. API/DTO 명세
|
||||
|
||||
### 6-1. 공통
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ------------------------------------------------------------- |
|
||||
| 서비스 | `as-elapr-service` |
|
||||
| Base prefix | `/as-elapr-service/api/v1` (프록시 경유) |
|
||||
| 인증 | JWT (`Authorization` 헤더) |
|
||||
| 페이징 | Spring `Pageable`: `page`, `size`, `sort` → `PageResponse<T>` |
|
||||
| 엔티티 | `@/entities/elapr` (`elaprTmpltService`, `elaprAplnService`) |
|
||||
|
||||
### 6-2. 전자결재서식 (영역 A) — `elapr-tmplt`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| --------- | ------ | ----------------------------- | ------------------------------------------ | ------------------ | ---------------------------- |
|
||||
| 목록 조회 | GET | `/elapr-tmplt` | Query: `ElaprTmpltSearchParams` + Pageable | `Page<ElaprTmplt>` | `elaprTmpltService.findPage` |
|
||||
| 단건 조회 | GET | `/elapr-tmplt/{elaprTmpltId}` | — | `ElaprTmplt` | `elaprTmpltService.findById` |
|
||||
| 등록 | POST | `/elapr-tmplt` | `ElaprTmpltSaveRequest` | `ElaprTmplt` (201) | `elaprTmpltService.create` |
|
||||
| 수정 | PUT | `/elapr-tmplt/{elaprTmpltId}` | `ElaprTmpltUpdateRequest` | `ElaprTmplt` | `elaprTmpltService.update` |
|
||||
| 삭제 | DELETE | `/elapr-tmplt/{elaprTmpltId}` | — | 204 | `elaprTmpltService.remove` |
|
||||
|
||||
**ElaprTmplt (응답)**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| ----------------- | ------- | ------------------ |
|
||||
| `elaprTmpltId` | string | 전자결재서식아이디 |
|
||||
| `elaprTmpltNm` | string | 결재서식명 |
|
||||
| `elaprTmpltExpln` | string? | 서식 설명 |
|
||||
| `docSeComCd` | string? | 문서구분 코드 |
|
||||
| `docSeComNm` | string? | 문서구분명 |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
|
||||
**ElaprTmpltSaveRequest**: `elaprTmpltNm`\_, `elaprTmpltExpln?`, `docSeComCd?`
|
||||
|
||||
**ElaprTmpltUpdateRequest**: `elaprTmpltNm`\*, `elaprTmpltExpln?`, `docSeComCd?`
|
||||
|
||||
**ElaprTmpltSearchParams**: `elaprTmpltNm?`, `docSeComCd?`, `regDtStart?`, `regDtEnd?` + `page`, `size`, `sort`
|
||||
|
||||
### 6-3. 결재선 (영역 B) — `elapr-apln`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| --------- | ------ | ---------------------- | ------------------------------- | ----------------- | --------------------------- |
|
||||
| 목록 조회 | GET | `/elapr-apln` | Query: `elaprTmpltId`, Pageable | `Page<ElaprApln>` | `elaprAplnService.findPage` |
|
||||
| 단건 조회 | GET | `/elapr-apln/{aplnId}` | — | `ElaprApln` | `elaprAplnService.findById` |
|
||||
| 등록 | POST | `/elapr-apln` | `ElaprAplnSaveRequest` | `ElaprApln` (201) | `elaprAplnService.create` |
|
||||
| 수정 | PUT | `/elapr-apln/{aplnId}` | `ElaprAplnUpdateRequest` | `ElaprApln` | `elaprAplnService.update` |
|
||||
| 삭제 | DELETE | `/elapr-apln/{aplnId}` | — | 204 | `elaprAplnService.remove` |
|
||||
|
||||
> **일괄 저장 API 없음** — UI의 [결재선 저장]은 변경된 행에 대해 POST/PUT을 순차(또는 병렬) 호출하는 클라이언트 오케스트레이션으로 구현.
|
||||
|
||||
**ElaprApln (응답)**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| -------------- | ------- | ------------------ |
|
||||
| `aplnId` | string | 결재선아이디 |
|
||||
| `elaprTmpltId` | string | 전자결재서식아이디 |
|
||||
| `aprvrUuid` | string? | 결재자 UUID |
|
||||
| `atrzSeComCd` | string? | 결재구분 코드 |
|
||||
| `atrzSeComNm` | string? | 결재구분명 |
|
||||
| `atrzSeqNo` | number? | 결재순서번호 |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
|
||||
**ElaprAplnSaveRequest**: `elaprTmpltId`\_, `aprvrUuid?`, `atrzSeComCd?`, `atrzSeqNo?`
|
||||
|
||||
**ElaprAplnUpdateRequest**: `elaprTmpltId`\*, `aprvrUuid?`, `atrzSeComCd?`, `atrzSeqNo?`
|
||||
|
||||
### 6-4. 검토인력 (보조)
|
||||
|
||||
| 기능 | Method | URL | 비고 |
|
||||
| ------------------ | ------ | --- | --------------------------- |
|
||||
| 검토인력 목록 조회 | TBD | TBD | 사용자 서비스 또는 별도 API |
|
||||
|
||||
### 6-5. Backend ↔ 화면 필드 매핑 (구 SPEC 대비)
|
||||
|
||||
| 구 SPEC 필드 | 백엔드 필드 |
|
||||
| ----------------- | ---------------------------------------------------- |
|
||||
| `elctAtrzTmpltId` | `elaprTmpltId` |
|
||||
| `atrzTmpltNm` | `elaprTmpltNm` |
|
||||
| `docSeNm` | `docSeComNm` |
|
||||
| `atrzLineId` | `aplnId` |
|
||||
| `atrzSeNm` | `atrzSeComNm` |
|
||||
| `atrzUserNm` | (없음) `aprvrUuid` + 사용자 조회/선택 시 로컬 표시명 |
|
||||
|
||||
---
|
||||
|
||||
## 7. UI 구현 가이드
|
||||
|
||||
### 7-1. 기술 스택·원칙
|
||||
|
||||
- **공통 컴포넌트**: `@common/components`
|
||||
- **테이블**: `@tanstack/react-table` + 인라인 편집 셀 (`Select`, `Input`, `Button`)
|
||||
- **드래그**: `@dnd-kit` — B-2 행 정렬 (POC 필수)
|
||||
- **데이터**: React Query — `@/entities/elapr` hooks
|
||||
- **상태**: 선택된 `elaprTmpltId`, `editingRowId` (단일 행 편집 잠금), B-2 행 배열(dirty·신규·`aprvrNm`·수정 전 스냅샷)
|
||||
- **모의 데이터**: API 연동 전 `@faker-js/faker`
|
||||
|
||||
### 7-2. 모듈·파일 배치(제안)
|
||||
|
||||
| 구분 | 경로 |
|
||||
| ------ | -------------------------------------------------------------------------------------- |
|
||||
| 라우트 | `apps/as/app/(with-base-layout)/approval-line-management/page.tsx` |
|
||||
| 페이지 | `apps/as/src/pages/approval-line-management/` (Public API: page만 export) |
|
||||
| UI | `.../ui/elapr-tmplt-list.tsx`, `elapr-tmplt-form-dialog.tsx`, `elapr-apln-grid.tsx` 등 |
|
||||
| model | `.../model/columns.tsx`, `apln-row-types.ts`, `mock-reviewers.ts` |
|
||||
| lib | `.../lib/use-apln-rows.ts`, `validators.ts`, `use-dnd-sensors.ts` |
|
||||
| 엔티티 | `apps/as/src/entities/elapr/` |
|
||||
|
||||
### 7-3. 영역별 UI 매핑
|
||||
|
||||
| 영역 | 주요 UI |
|
||||
| ------ | -------------------------------------------------------------------------------------------- |
|
||||
| A | DataTable + 행 선택 + 서식 등록/수정 다이얼로그 |
|
||||
| B 헤더 | 상태 라벨 + `행 추가`, `결재선 저장` |
|
||||
| B-2 | 인라인 편집 DataTable + `editingRowId` 단일 행 잠금 + 드래그 핸들 + 행별 수정/저장/삭제/취소 |
|
||||
| 공통 | 서식 Dialog, 검토인력 선택 Dialog만 |
|
||||
|
||||
### 7-4. 데이터 흐름(요약)
|
||||
|
||||
- **진입**: `useElaprTmpltPage` → 영역 A. B 비활성.
|
||||
- **서식 선택**: `useElaprAplnPage({ elaprTmpltId })` → B-2.
|
||||
- **행 추가**: `editingRowId` 없을 때만 가능 → 신규 행 1건 편집 잠금 → 저장/취소 후 해제.
|
||||
- **인라인 수정**: [수정]으로 `editingRowId` 설정 → 해당 행만 편집 → `useUpdateElaprApln` 후 해제.
|
||||
- **드래그**: `editingRowId == null` 일 때만 가능 → 로컬 `atrzSeqNo` 재부여 → 일괄 PUT.
|
||||
- **삭제**: `useDeleteElaprApln` 또는 신규 행 로컬 제거.
|
||||
|
||||
### 7-5. 미확정 / 검증 필요
|
||||
|
||||
- 검토인력 API 경로·DTO.
|
||||
- `@dnd-kit` + react-table 행 인라인 Input 동시 적용 POC.
|
||||
- 결재자 성명 표시: `aprvrUuid` → 사용자명 조회 API.
|
||||
- 영역 A·B 페이지네이션·검색 UI 노출 여부.
|
||||
- 권한(역할별 CRUD).
|
||||
@@ -1,487 +0,0 @@
|
||||
# 화면설계서: 체크리스트관리
|
||||
|
||||
## 1. 기본 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | -------------------------------------------- |
|
||||
| 버전 | 0.1 |
|
||||
| 프로세스명 | UI설계 |
|
||||
| 화면명 | 체크리스트관리 |
|
||||
| 화면 유형 | [v] 조회 [v] 입력 [v] 수정 [v] 삭제 [ ] 출력 |
|
||||
| 메뉴 경로 | 디지털행정지원 > 시스템관리 > 체크리스트관리 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 화면 목적
|
||||
|
||||
업무별·문서별 **점검표**(체크리스트)를 등록·관리하고, **점검항목** 마스터를 유지한다. 상단 좌측에서 점검표를 선택하면 하단 **체크리스트 항목** 영역에 해당 점검표의 검토 구성(계층형 검토내용)을 편집한다. 상단 우측 **점검항목 관리**는 점검표에 연결할 항목 풀을 등록·수정·삭제한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 화면 구성
|
||||
|
||||
### 3-1. 전체 레이아웃
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 페이지 타이틀: 체크리스트관리 브레드크럼: 디지털행정지원 > … > │
|
||||
├──────────────────────────────────────────────┬────────────────────────────────────────────────┤
|
||||
│ [영역 A] 점검표 관리 │ [영역 B] 점검항목 관리 │
|
||||
│ [점검표 추가] │ [점검항목 추가] │
|
||||
│ ┌────────────────────────────────────────┐ │ ┌──────────────────────────────────────────┐ │
|
||||
│ │ 점검표일련번호 | 점검표명 | 문서구분 │ │ │ 점검항목코드 | 점검항목명 | 사용여부 │ │
|
||||
│ │ 업무구분 | 사용여부 | 등록일시 | 관리 │ │ │ 등록일시 | 관리 │ │
|
||||
│ ├────────────────────────────────────────┤ │ ├──────────────────────────────────────────┤ │
|
||||
│ │ 1 (선택 행 강조) [관리] [삭제] │ │ │ ITEM_001 요건검토 … [관리][삭제] │ │
|
||||
│ │ │ │ │ ITEM_002 법령검토 … [관리][삭제] │ │
|
||||
│ └────────────────────────────────────────┘ │ └──────────────────────────────────────────┘ │
|
||||
├──────────────────────────────────────────────┴────────────────────────────────────────────────┤
|
||||
│ [영역 C] 체크리스트 항목 [미리보기] [추가] [저장] │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 점검항목 ▼ | 주요 검토내용 | 사용 여부 | 구분 | 관리 │ │
|
||||
│ │ L1 [요건검토 ▼] | (입력) | ○예 ○아니오 | 1단계 | [하위추가]│ │
|
||||
│ │ L2 [요건검토 ▼] | (입력) | ○예 ○아니오 | 2단계 | [삭제] │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└───────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-2. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입
|
||||
CALL GET /as-checklist-service/api/v1/cklst
|
||||
DISPLAY 점검표 그리드 (영역 A)
|
||||
CALL GET /as-checklist-service/api/v1/cklst-artcl
|
||||
DISPLAY 점검항목 그리드 (영역 B)
|
||||
DISPLAY 빈 상태 안내 (영역 C) // 점검표 미선택 시 C 비활성
|
||||
|
||||
// 영역 A: 점검표 행 선택
|
||||
ON 영역 A 행 CLICK DO
|
||||
SET 선택된 점검표 = 행.cklstSn
|
||||
CALL GET /as-checklist-service/api/v1/cklst-rvw?cklstSn={cklstSn}
|
||||
// TBD: 점검표 단위 전체 검토 트리 조회 API — 현재는 항목별 by-artcl 조합 또는 클라이언트 병합
|
||||
DISPLAY 체크리스트 항목 그리드 (영역 C)
|
||||
END ON
|
||||
|
||||
// 영역 A: 점검표 추가
|
||||
ON [점검표 추가] 버튼 CLICK DO
|
||||
OPEN 점검표 추가 다이얼로그
|
||||
ON [저장] DO
|
||||
VALIDATE cklstNm, taskSeComCd
|
||||
CALL POST /as-checklist-service/api/v1/cklst
|
||||
CALL GET /as-checklist-service/api/v1/cklst
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
ON [취소] / [닫기] DO
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 A: 점검표 수정·삭제
|
||||
ON 영역 A 행 [관리] CLICK DO
|
||||
OPEN 점검표 수정 다이얼로그 (기존 값 초기화)
|
||||
ON [저장] DO
|
||||
CALL PUT /as-checklist-service/api/v1/cklst/{cklstSn}
|
||||
CALL GET /as-checklist-service/api/v1/cklst
|
||||
END ON
|
||||
END ON
|
||||
|
||||
ON 영역 A 행 [삭제] CLICK DO
|
||||
CONFIRM "선택한 점검표를 삭제하시겠습니까?"
|
||||
CALL DELETE /as-checklist-service/api/v1/cklst/{cklstSn}
|
||||
IF 삭제 대상 == 선택된 점검표 THEN RESET 영역 C
|
||||
CALL GET /as-checklist-service/api/v1/cklst
|
||||
END ON
|
||||
|
||||
// 영역 B: 점검항목 추가
|
||||
ON [점검항목 추가] 버튼 CLICK DO
|
||||
OPEN 점검항목 추가 다이얼로그
|
||||
ON [저장] DO
|
||||
VALIDATE cklstArtclNm
|
||||
// TBD: cklstSn 필수 — UI에 소속 점검표 선택 없음. 백엔드 정책 확인
|
||||
CALL POST /as-checklist-service/api/v1/cklst-artcl
|
||||
CALL GET /as-checklist-service/api/v1/cklst-artcl
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 B: 점검항목 수정·삭제
|
||||
ON 영역 B 행 [관리] CLICK DO
|
||||
OPEN 점검항목 수정 다이얼로그
|
||||
ON [저장] DO
|
||||
CALL PUT /as-checklist-service/api/v1/cklst-artcl/{cklstArtclSn}/{cklstSn}
|
||||
END ON
|
||||
END ON
|
||||
|
||||
ON 영역 B 행 [삭제] CLICK DO
|
||||
CONFIRM "선택한 점검항목을 삭제하시겠습니까?"
|
||||
CALL DELETE /as-checklist-service/api/v1/cklst-artcl/{cklstArtclSn}/{cklstSn}
|
||||
CALL GET /as-checklist-service/api/v1/cklst-artcl
|
||||
END ON
|
||||
|
||||
// 영역 C: 검토 행 추가
|
||||
ON [추가] 버튼 CLICK DO
|
||||
VALIDATE 선택된 점검표 존재
|
||||
ADD 영역 C 그리드 맨 아래 편집 가능 행 (1단계, rvwCnLvNo=1)
|
||||
END ON
|
||||
|
||||
// 영역 C: 하위 검토 추가
|
||||
ON 행 [하위추가] CLICK DO
|
||||
ADD 부모행 하위 편집 행 (2단계, upCklstRvwSn=부모.cklstRvwSn, rvwCnLvNo=2)
|
||||
END ON
|
||||
|
||||
// 영역 C: 일괄 저장
|
||||
ON [저장] 버튼 CLICK DO
|
||||
VALIDATE 선택된 점검표 존재
|
||||
FOR EACH 신규·변경된 검토 행 DO
|
||||
IF 신규 THEN
|
||||
CALL POST /as-checklist-service/api/v1/cklst-rvw
|
||||
ELSE
|
||||
CALL PUT /as-checklist-service/api/v1/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}
|
||||
END IF
|
||||
END FOR
|
||||
CALL GET /as-checklist-service/api/v1/cklst-rvw?cklstSn={cklstSn}
|
||||
TOAST "체크리스트 항목이 저장되었습니다."
|
||||
END ON
|
||||
|
||||
// 영역 C: 행 삭제
|
||||
ON 행 [삭제] CLICK DO
|
||||
CONFIRM "선택한 항목을 삭제하시겠습니까?"
|
||||
IF 서버 저장된 행 THEN
|
||||
CALL DELETE /as-checklist-service/api/v1/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}
|
||||
END IF
|
||||
REMOVE 그리드 행 (미저장 행은 API 호출 없이 제거)
|
||||
END ON
|
||||
|
||||
// 영역 C: 미리보기
|
||||
ON [미리보기] 버튼 CLICK DO
|
||||
OPEN 체크리스트 미리보기 다이얼로그 (읽기 전용 트리)
|
||||
// TBD: 미리보기 UI·API
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 영역 A: 점검표 관리
|
||||
|
||||
선택된 점검표가 영역 C의 편집 대상이 된다. 행 클릭으로 선택 상태를 표시한다.
|
||||
|
||||
### 4-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ------------------------------------------ |
|
||||
| 섹션 타이틀 | 점검표 관리 |
|
||||
| 우측 버튼 | **[점검표 추가]** — 점검표 등록 다이얼로그 |
|
||||
|
||||
### 4-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 타입 | 비고 |
|
||||
| ---------------- | ------------- | ------ | ---------------------------------------------------- |
|
||||
| 점검표일련번호 | `cklstSn` | number | PK |
|
||||
| 점검표명 | `cklstNm` | string | |
|
||||
| 문서구분공통코드 | `docSeComCd` | string | 코드명 표시 — `ASDOCSECD` 등 공통코드 (TBD 상위코드) |
|
||||
| 업무구분공통코드 | `taskSeComCd` | string | RE/SF/SP 등 — 공통코드 (TBD 상위코드) |
|
||||
| 사용여부 | `useYn` | string | `Y`→예, `N`→아니오 |
|
||||
| 등록일시 | `regDt` | string | `yyyy-MM-dd HH:mm:ss` |
|
||||
| 관리 | — | — | 행별 **[관리] · [삭제]** |
|
||||
|
||||
- 행 클릭 시: `cklstSn` 선택 → 영역 C 헤더·그리드 갱신.
|
||||
- 페이지네이션: Spring `Pageable` (`page`, `size`, `sort`).
|
||||
|
||||
### 4-3. 버튼
|
||||
|
||||
| 버튼명 | 위치 | 동작 |
|
||||
| ----------- | -------------- | ------------------------------------------------- |
|
||||
| 점검표 추가 | 섹션 우측 상단 | 점검표 추가 다이얼로그 오픈 |
|
||||
| 관리 | 행별 | 점검표 수정 다이얼로그 (기존 값 초기화) |
|
||||
| 삭제 | 행별 | 확인 후 삭제. 선택 중인 점검표이면 영역 C 초기화. |
|
||||
|
||||
### 4-4. 다이얼로그: 점검표 추가 / 수정
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| -------- | ---------------- | ---- | ------ | ----------------- | ------------------------------------------------ |
|
||||
| 점검표명 | Text | Y | — | `cklstNm` | placeholder: "예: 설치인가 체크리스트" |
|
||||
| 문서구분 | Select(공통코드) | N | — | `docSeComCd` | 예: FNRS, INSTL, PWRK, DESIGN |
|
||||
| 업무구분 | Select(공통코드) | Y | — | `taskSeComCd` | 예: RE(재이용수), SF(하수처리시설), SP(하수관로) |
|
||||
| 사용여부 | Select | N | Y | `useYn` | Y/N, UI 표시: 예/아니오 |
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | -------------------------------------- |
|
||||
| 저장 | POST(등록) 또는 PUT(수정) 후 목록 갱신 |
|
||||
| 취소 | 다이얼로그 닫기, 입력값 폐기 |
|
||||
| 닫기 | 다이얼로그 닫기 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 영역 B: 점검항목 관리
|
||||
|
||||
점검표 하단(영역 C)에서 선택할 **점검항목** 마스터를 관리한다.
|
||||
|
||||
### 5-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ---------------------------------------------- |
|
||||
| 섹션 타이틀 | 점검항목 관리 |
|
||||
| 우측 버튼 | **[점검항목 추가]** — 점검항목 등록 다이얼로그 |
|
||||
|
||||
### 5-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 타입 | 비고 |
|
||||
| ------------ | -------------- | ------ | ------------------------------------- |
|
||||
| 점검항목코드 | `cklstArtclSn` | number | UI mock `ITEM_001` 형식 표시 여부 TBD |
|
||||
| 점검항목명 | `cklstArtclNm` | string | |
|
||||
| 사용여부 | `useYn` | string | `Y`→예, `N`→아니오 |
|
||||
| 등록일시 | `regDt` | string | `yyyy-MM-dd HH:mm:ss` |
|
||||
| 관리 | — | — | 행별 **[관리] · [삭제]** |
|
||||
|
||||
> **TBD**: 백엔드 `CklstArtcl`은 복합 PK(`cklstArtclSn`, `cklstSn`)이며 등록 시 `cklstSn` 필수. UI 다이얼로그에는 `cklstSn` 입력이 없음 — 소속 점검표 지정 방식·전역 마스터 여부 백엔드 정책 확인.
|
||||
|
||||
### 5-3. 다이얼로그: 점검항목 추가 / 수정
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| ---------- | --------- | ---- | ------ | ----------------- | --------------------------- |
|
||||
| 점검항목명 | Text | Y | — | `cklstArtclNm` | placeholder: "예: 법령검토" |
|
||||
| 사용여부 | Select | N | Y | `useYn` | Y/N |
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | -------------------------------------- |
|
||||
| 저장 | POST(등록) 또는 PUT(수정) 후 목록 갱신 |
|
||||
| 취소 | 다이얼로그 닫기 |
|
||||
| 닫기 | 다이얼로그 닫기 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 영역 C: 체크리스트 항목 (선택된 점검표)
|
||||
|
||||
영역 A에서 선택된 `cklstSn` 기준으로 **점검표검토**(계층형 검토내용)를 구성한다.
|
||||
|
||||
### 6-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | -------------------------------------------------------------------- |
|
||||
| 섹션 타이틀 | 체크리스트 항목 (선택된 점검표: {cklstNm}) |
|
||||
| 우측 버튼 | **[미리보기]** · **[추가]** · **[저장]** — 점검표 미선택 시 C 비활성 |
|
||||
|
||||
### 6-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 입력 UI | 비고 |
|
||||
| ------------- | -------------- | ------------------------------------- | ------------------------------------ |
|
||||
| 점검항목 | `cklstArtclSn` | Select (영역 B 항목 목록) | L1/L2 접두 표시, `cklstArtclNm` 라벨 |
|
||||
| 주요 검토내용 | `rvwCn` | Text / Textarea | 최대 4000자 |
|
||||
| 사용 여부 | `useYn` | Radio (예/아니오) | `Y` / `N` |
|
||||
| 구분 | `rvwCnLvNo` | 읽기 전용 | 1→1단계, 2→2단계, 3→3단계 |
|
||||
| 관리 | — | **[하위추가]** (1·2단계, 저장 후) · **[삭제]** | 3단계 행은 [하위추가] 미표시 |
|
||||
|
||||
#### 계층 정책
|
||||
|
||||
| 항목 | 내용 |
|
||||
| -------------- | -------------------------------------------------------------------- |
|
||||
| 최대 깊이 | 3단계 (`rvwCnLvNo`: 1, 2, 3) |
|
||||
| 상위-하위 연결 | `upCklstRvwSn` — 2단계 행은 부모 1단계 `cklstRvwSn` 참조 |
|
||||
| 정렬 | `sortSeq` — 동일 레벨 내 순서 (TBD: UI 드래그 정렬 여부) |
|
||||
| 체크 사용 | `bchckUseYn` — 미리보기·실사용 화면 체크박스 노출 여부 (TBD UI 반영) |
|
||||
|
||||
### 6-3. 버튼
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| -------- | ---------------------------------------------------- |
|
||||
| 추가 | 1단계 검토 행 1건 추가 (편집 가능) |
|
||||
| 저장 | 변경·신규 검토 행 일괄 POST/PUT (일괄 저장 API 없음) |
|
||||
| 미리보기 | 선택 점검표 체크리스트 읽기 전용 미리보기 (TBD) |
|
||||
| 하위추가 | 선택 1·2단계 행 아래 하위 단계(2·3단계) 자식 행 추가 |
|
||||
| 삭제 | 확인 후 DELETE 또는 미저장 행 로컬 제거 |
|
||||
|
||||
---
|
||||
|
||||
## 7. API/DTO 명세
|
||||
|
||||
### 7-1. 공통
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ------------- | ------------------------------------------------------------- |
|
||||
| 서비스 | `as-checklist-service` |
|
||||
| Base prefix | `/as-checklist-service/api/v1` (게이트웨이 프록시 경유) |
|
||||
| 인증 | JWT (`Authorization` 헤더), `X-Site-Id`, `token-id` |
|
||||
| 페이징 | Spring `Pageable`: `page`, `size`, `sort` → `PageResponse<T>` |
|
||||
| 엔티티 | `@/entities/cklst` (`cklstMngService`, `cklstArtclService`, `cklstRvwService`) |
|
||||
|
||||
### 7-2. 점검표 (영역 A) — `cklst`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| --------- | ------ | ------------------ | --------------------------------- | ------------------ | -------------------------- |
|
||||
| 목록 조회 | GET | `/cklst` | `CklstMngSearchParams` + Pageable | `Page<CklstMng>` | `cklstMngService.findPage` |
|
||||
| 단건 조회 | GET | `/cklst/{cklstSn}` | — | `CklstMng` | `cklstMngService.findById` |
|
||||
| 등록 | POST | `/cklst` | `CklstMngSaveRequest` | `number` (cklstSn) | `cklstMngService.create` |
|
||||
| 수정 | PUT | `/cklst/{cklstSn}` | `CklstMngSaveRequest` | `number` (cklstSn) | `cklstMngService.update` |
|
||||
| 삭제 | DELETE | `/cklst/{cklstSn}` | — | `number` (cklstSn) | `cklstMngService.remove` |
|
||||
|
||||
**CklstMng (응답)**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| ------------- | ------- | ---------------- |
|
||||
| `cklstSn` | number | 점검표일련번호 |
|
||||
| `cklstNm` | string | 점검표명 |
|
||||
| `taskSeComCd` | string | 업무구분공통코드 |
|
||||
| `useYn` | string? | 사용여부 |
|
||||
| `docSeComCd` | string? | 문서구분공통코드 |
|
||||
| `rgtr` | string? | 등록자 UUID |
|
||||
| `rgtrNm` | string? | 등록자명 |
|
||||
| `mdfr` | string? | 수정자 UUID |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
| `mdfcnDt` | string? | 수정일시 |
|
||||
|
||||
**CklstMngSaveRequest**: `cklstNm`\*, `taskSeComCd`\*, `useYn?`, `docSeComCd?`
|
||||
|
||||
**CklstMngSearchParams**: `cklstNm?`, `taskSeComCd?`, `useYn?`, `docSeComCd?` + `page`, `size`, `sort`
|
||||
|
||||
**React Query hooks**: `useCklstMngPage`, `useCklstMng`, `useCreateCklstMng`, `useUpdateCklstMng`, `useDeleteCklstMng`
|
||||
|
||||
### 7-3. 점검표항목 (영역 B) — `cklst-artcl`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| ------------------ | ------ | --------------------------------------- | ----------------------------------- | ------------------ | --------------------------------- |
|
||||
| 목록 조회 (페이징) | GET | `/cklst-artcl` | `CklstArtclSearchParams` + Pageable | `Page<CklstArtcl>` | `cklstArtclService.findPage` |
|
||||
| 점검표별 전체 목록 | GET | `/cklst-artcl/by-cklst/{cklstSn}` | — | `CklstArtcl[]` | `cklstArtclService.findByCklstSn` |
|
||||
| 단건 조회 | GET | `/cklst-artcl/{cklstArtclSn}/{cklstSn}` | — | `CklstArtcl` | `cklstArtclService.findById` |
|
||||
| 등록 | POST | `/cklst-artcl` | `CklstArtclSaveRequest` | `CklstArtclId` | `cklstArtclService.create` |
|
||||
| 수정 | PUT | `/cklst-artcl/{cklstArtclSn}/{cklstSn}` | `CklstArtclUpdateRequest` | `CklstArtclId` | `cklstArtclService.update` |
|
||||
| 삭제 | DELETE | `/cklst-artcl/{cklstArtclSn}/{cklstSn}` | — | `CklstArtclId` | `cklstArtclService.remove` |
|
||||
|
||||
**CklstArtcl (응답)**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| ----------------- | ------- | ------------------ |
|
||||
| `cklstArtclSn` | number | 점검표항목일련번호 |
|
||||
| `cklstSn` | number | 점검표일련번호 |
|
||||
| `cklstArtclNm` | string? | 점검표항목명 |
|
||||
| `useYn` | string? | 사용여부 |
|
||||
| `rgtr` / `rgtrNm` | string? | 등록자 |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
|
||||
**CklstArtclSaveRequest**: `cklstSn`\*, `cklstArtclNm?`, `useYn?`
|
||||
|
||||
**CklstArtclUpdateRequest**: `cklstArtclNm?`, `useYn?`
|
||||
|
||||
**CklstArtclId**: `{ cklstArtclSn: number; cklstSn: number }`
|
||||
|
||||
**React Query hooks**: `useCklstArtclPage`, `useCklstArtclList`, `useCklstArtcl`, `useCreateCklstArtcl`, `useUpdateCklstArtcl`, `useDeleteCklstArtcl`
|
||||
|
||||
### 7-4. 점검표검토 (영역 C) — `cklst-rvw`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| --------------------- | ------ | -------------------------------------------------- | ------------------------------ | ---------------- | ------------------------------- |
|
||||
| 목록 조회 (페이징) | GET | `/cklst-rvw` | `CklstRvwSearchParams` + Pageable | `Page<CklstRvw>` | `cklstRvwService.findPage` |
|
||||
| 항목별 검토 전체 목록 | GET | `/cklst-rvw/by-artcl/{cklstSn}/{cklstArtclSn}` | — | `CklstRvw[]` | `cklstRvwService.findByArtcl` |
|
||||
| 단건 조회 | GET | `/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}` | — | `CklstRvw` | `cklstRvwService.findById` |
|
||||
| 등록 | POST | `/cklst-rvw` | `CklstRvwSaveRequest` | `CklstRvwId` | `cklstRvwService.create` |
|
||||
| 수정 | PUT | `/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}` | `CklstRvwUpdateRequest` | `CklstRvwId` | `cklstRvwService.update` |
|
||||
| 삭제 | DELETE | `/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}` | — | `CklstRvwId` | `cklstRvwService.remove` |
|
||||
|
||||
**CklstRvw (응답)**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| -------------- | ------- | ---------------------- |
|
||||
| `cklstRvwSn` | number | 점검표검토일련번호 |
|
||||
| `cklstArtclSn` | number | 점검표항목일련번호 |
|
||||
| `cklstSn` | number | 점검표일련번호 |
|
||||
| `upCklstRvwSn` | number? | 상위점검표검토일련번호 |
|
||||
| `rvwCnLvNo` | number? | 검토내용레벨번호 |
|
||||
| `rvwCn` | string? | 검토내용 |
|
||||
| `bchckUseYn` | string? | 체크사용여부 |
|
||||
| `sortSeq` | number? | 정렬순서 |
|
||||
| `useYn` | string? | 사용여부 |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
|
||||
**CklstRvwSaveRequest**: `cklstArtclSn`\*, `cklstSn`\*, `upCklstRvwSn?`, `rvwCnLvNo?`, `rvwCn?`, `bchckUseYn?`, `sortSeq?`, `useYn?`
|
||||
|
||||
**CklstRvwUpdateRequest**: `upCklstRvwSn?`, `rvwCnLvNo?`, `rvwCn?`, `bchckUseYn?`, `sortSeq?`, `useYn?`
|
||||
|
||||
**CklstRvwSearchParams**: `cklstSn?`, `cklstArtclSn?`, `useYn?` + `page`, `size`, `sort`
|
||||
|
||||
**CklstRvwId**: `{ cklstRvwSn: number; cklstArtclSn: number; cklstSn: number }`
|
||||
|
||||
**React Query hooks**: `useCklstRvwPage`, `useCklstRvwByArtcl`, `useCklstRvw`, `useCreateCklstRvw`, `useUpdateCklstRvw`, `useDeleteCklstRvw`
|
||||
|
||||
### 7-5. 공통코드 (보조)
|
||||
|
||||
| UI 필드 | 코드 그룹 (TBD) | 예시 값 |
|
||||
| -------- | --------------- | -------------------------------------------- |
|
||||
| 문서구분 | `ASDOCSECD` 등 | FNRS, INSTL, PWRK, DESIGN |
|
||||
| 업무구분 | TBD | RE(재이용수), SF(하수처리시설), SP(하수관로) |
|
||||
| 사용여부 | 고정 | Y, N |
|
||||
|
||||
공통코드 조회: `@/entities/code` — `codeService`, `CodeSelect`
|
||||
|
||||
---
|
||||
|
||||
## 8. UI 구현 가이드
|
||||
|
||||
### 8-1. 기술 스택·원칙
|
||||
|
||||
- **공통 컴포넌트**: `@common/components` (`Dialog`, `Button`, `Input`, `Select`, `RadioGroup` 등)
|
||||
- **테이블**: `@tanstack/react-table` + `useDataTable`
|
||||
- **데이터**: React Query — `@/entities/cklst` hooks (`useCklstRvwPage` 등 영역 C 포함)
|
||||
- **공통코드**: `@/entities/code` — `CodeSelect`, `findCodeLabel`
|
||||
- **상태**: 선택된 `cklstSn`, 영역 C 검토 행 배열(신규·dirty·계층 트리)
|
||||
- **모의 데이터**: API 연동 전 `@faker-js/faker`
|
||||
|
||||
### 8-2. 모듈·파일 배치(제안)
|
||||
|
||||
| 구분 | 경로 |
|
||||
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 라우트 | `apps/as/app/(with-base-layout)/checklist-management/page.tsx` |
|
||||
| 페이지 | `apps/as/src/pages/checklist-management/` (Public API: page만 export) |
|
||||
| UI | `.../ui/cklst-mng-list.tsx`, `cklst-mng-form-dialog.tsx`, `cklst-artcl-list.tsx`, `cklst-artcl-form-dialog.tsx`, `cklst-rvw-grid.tsx`, `cklst-preview-dialog.tsx` |
|
||||
| model | `.../model/cklst-mng-columns.tsx`, `cklst-artcl-columns.tsx`, `cklst-rvw-row-types.ts` |
|
||||
| lib | `.../lib/use-cklst-rvw-rows.ts`, `validators.ts`, `build-rvw-tree.ts` |
|
||||
| 엔티티 | `apps/as/src/entities/cklst/` (`cklstMng`, `cklstArtcl`, `cklstRvw` 서비스·hooks) |
|
||||
| 페이지 | `apps/as/src/pages/checklist-management/` — `/checklist-management` |
|
||||
| 문서 | `apps/as/docs/checklist-management/SPEC.md` |
|
||||
|
||||
### 8-3. 영역별 UI 매핑
|
||||
|
||||
| 영역 | 주요 UI |
|
||||
| ---- | ---------------------------------------------------------------------------- |
|
||||
| A | DataTable + 행 선택 + 점검표 추가/수정 Dialog |
|
||||
| B | DataTable + 점검항목 추가/수정 Dialog |
|
||||
| C | 계층형 편집 그리드(1·2단계) + [추가][저장][미리보기] + 행별 [하위추가][삭제] |
|
||||
| 공통 | `CodeSelect` (문서구분·업무구분), 사용여부 Y/N Select/Radio |
|
||||
|
||||
### 8-4. 다이얼로그·라우팅
|
||||
|
||||
| 다이얼로그명 | 트리거 | API 연동 |
|
||||
| ------------------- | --------------- | ------------------------- |
|
||||
| 점검표 추가 | [점검표 추가] | `useCreateCklstMng` |
|
||||
| 점검표 수정 | 행 [관리] | `useUpdateCklstMng` |
|
||||
| 점검표 삭제 확인 | 행 [삭제] | `useDeleteCklstMng` |
|
||||
| 점검항목 추가 | [점검항목 추가] | `useCreateCklstArtcl` |
|
||||
| 점검항목 수정 | 행 [관리] | `useUpdateCklstArtcl` |
|
||||
| 체크리스트 미리보기 | [미리보기] | TBD — 읽기 전용 트리 렌더 |
|
||||
|
||||
라우트: `/checklist-management` (메뉴 URL은 CMS 등록값과 일치시킴)
|
||||
|
||||
### 8-5. 데이터 흐름(요약)
|
||||
|
||||
- **진입**: `useCklstMngPage` → 영역 A, `useCklstArtclPage` → 영역 B. C 비활성.
|
||||
- **점검표 선택**: `cklstSn` 설정 → 영역 C 활성 → `useCklstRvwPage({ cklstSn })` → 트리 그리드 표시.
|
||||
- **점검표 CRUD**: Dialog → `useCreateCklstMng` / `useUpdateCklstMng` / `useDeleteCklstMng`.
|
||||
- **점검항목 CRUD**: Dialog → `useCreateCklstArtcl` / `useUpdateCklstArtcl` / `useDeleteCklstArtcl`.
|
||||
- **검토 저장**: [저장] → 신규 POST / 기존 PUT 순차 호출 (일괄 API 없음).
|
||||
- **영역 C 점검항목 Select**: `useCklstArtclList(cklstSn)` 또는 영역 B 전체 목록과 교차 — **TBD**.
|
||||
|
||||
### 8-6. 미확정 / 검증 필요
|
||||
|
||||
- [ ] 영역 B 점검항목 등록 시 `cklstSn` 필수 vs UI 무소속 마스터 — 백엔드·기획 확인
|
||||
- [ ] `점검항목코드`(ITEM_001) 표시 형식 vs `cklstArtclSn` 숫자 PK
|
||||
- [ ] 영역 C 전체 검토 트리 조회: `cklstSn` 단위 일괄 API 부재 — `by-artcl` 다건 호출 또는 백엔드 확장
|
||||
- [x] `@/entities/cklst` — `cklstRvwService`·hooks 구현
|
||||
- [x] `pages/checklist-management` — 영역 A·B·C UI 구현 (`/checklist-management`)
|
||||
- [ ] 문서구분·업무구분 공통코드 상위코드 ID (`ASDOCSECD` 등)
|
||||
- [ ] [미리보기] 다이얼로그 UI·데이터 소스
|
||||
- [ ] `bchckUseYn` UI 반영 여부
|
||||
- [ ] 영역 A·B 페이지네이션·검색 UI 노출 여부
|
||||
- [ ] 권한(역할별 CRUD)
|
||||
@@ -1,385 +0,0 @@
|
||||
# 화면설계서: 코드관리
|
||||
|
||||
## 1. 기본 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | -------------------------------------------- |
|
||||
| 버전 | 0.1 |
|
||||
| 프로세스명 | UI설계 |
|
||||
| 화면명 | 코드관리 |
|
||||
| 화면 유형 | [v] 조회 [v] 입력 [v] 수정 [v] 삭제 [ ] 출력 |
|
||||
| 메뉴 경로 | 디지털행정지원 > 사이트관리 > 코드관리 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 화면 목적
|
||||
|
||||
설치인가 등 AS 업무에서 참조하는 **공종구분코드**(공종코드)와 **회계구분코드**(회계코드)를 한 화면에서 조회·등록·수정·삭제한다. 좌측 **공종코드 관리**와 우측 **회계코드 관리**는 독립된 목록·CRUD 영역이며, 각 섹션은 자체 API(`cnstp-se`, `acntg-se`)와 연동한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 화면 구성
|
||||
|
||||
### 3-1. 전체 레이아웃
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 페이지 타이틀: 코드관리 브레드크럼: 디지털행정지원 > 사이트관리 > 코드관리 │
|
||||
├──────────────────────────────────────────────────┬────────────────────────────────────────────────┤
|
||||
│ [영역 A] 공종코드 관리 │ [영역 B] 회계코드 관리 │
|
||||
│ [등록] │ [등록] │
|
||||
│ ┌────────────────────────────────────────────┐ │ ┌──────────────────────────────────────────┐ │
|
||||
│ │ 코드 | 코드명 | 설명 | 사용여부 | 관리 │ │ │ 코드 | 코드명 | 설명 | 사용여부 | 관리 │ │
|
||||
│ ├────────────────────────────────────────────┤ │ ├──────────────────────────────────────────┤ │
|
||||
│ │ WC001 공공하수처리시설 … 사용 [수정][삭제]│ │ │ AC101 시설비 … 사용 [수정][삭제] │ │
|
||||
│ │ WC002 하수관로정비 … 사용 [수정][삭제]│ │ │ AC102 용역비 … 사용 [수정][삭제] │ │
|
||||
│ │ WC003 재이용시설 … 사용 [수정][삭제]│ │ │ AC103 운영비 … 미사용 [수정][삭제] │ │
|
||||
│ └────────────────────────────────────────────┘ │ └──────────────────────────────────────────┘ │
|
||||
│ « 1 2 3 … » │ « 1 2 3 … » │
|
||||
└──────────────────────────────────────────────────┴────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-2. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입 — 좌·우 독립 조회
|
||||
CALL cnstpSeMngService.findAll({ page, size })
|
||||
DISPLAY 공종코드 그리드 (영역 A)
|
||||
|
||||
CALL acntgSeMngService.findAll({ page, size })
|
||||
DISPLAY 회계코드 그리드 (영역 B)
|
||||
|
||||
// 영역 A: 공종코드 등록
|
||||
ON 영역 A [등록] 버튼 CLICK DO
|
||||
OPEN 공종코드 등록 다이얼로그
|
||||
ON [저장] DO
|
||||
VALIDATE cnstpSeCd
|
||||
CALL cnstpSeMngService.save(CnstpSeMngSaveRequestDto)
|
||||
CALL cnstpSeMngService.findAll
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
ON [취소] / [닫기] DO
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 A: 공종코드 수정
|
||||
ON 영역 A 행 [수정] CLICK DO
|
||||
CALL cnstpSeMngService.findById(cnstpSeCd)
|
||||
OPEN 공종코드 수정 다이얼로그 (기존 값 초기화)
|
||||
ON [저장] DO
|
||||
CALL cnstpSeMngService.update(cnstpSeCd, CnstpSeMngSaveRequestDto)
|
||||
CALL cnstpSeMngService.findAll
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 A: 공종코드 삭제
|
||||
ON 영역 A 행 [삭제] CLICK DO
|
||||
CONFIRM "선택한 공종코드를 삭제하시겠습니까?"
|
||||
CALL cnstpSeMngService.delete(cnstpSeCd)
|
||||
CALL cnstpSeMngService.findAll
|
||||
END ON
|
||||
|
||||
// 영역 B: 회계코드 등록
|
||||
ON 영역 B [등록] 버튼 CLICK DO
|
||||
OPEN 회계코드 등록 다이얼로그
|
||||
ON [저장] DO
|
||||
VALIDATE acntgSeCd, acntgSeCdNm
|
||||
CALL acntgSeMngService.save(AcntgSeMngSaveRequestDto)
|
||||
CALL acntgSeMngService.findAll
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
ON [취소] / [닫기] DO
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 B: 회계코드 수정
|
||||
ON 영역 B 행 [수정] CLICK DO
|
||||
CALL acntgSeMngService.findById(acntgSeCd)
|
||||
OPEN 회계코드 수정 다이얼로그 (기존 값 초기화)
|
||||
ON [저장] DO
|
||||
CALL acntgSeMngService.update(acntgSeCd, AcntgSeMngSaveRequestDto)
|
||||
CALL acntgSeMngService.findAll
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 B: 회계코드 삭제
|
||||
ON 영역 B 행 [삭제] CLICK DO
|
||||
CONFIRM "선택한 회계코드를 삭제하시겠습니까?"
|
||||
CALL acntgSeMngService.delete(acntgSeCd)
|
||||
CALL acntgSeMngService.findAll
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 영역 A: 공종코드 관리
|
||||
|
||||
백엔드 **공종구분코드**(`CnstpSeMng`) CRUD. 계층 구조(`upCnstpCd`, `cdLvNo`)를 지원하나, 본 화면은 **평면 목록**으로 표시.
|
||||
|
||||
### 4-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ------------------------------------- |
|
||||
| 섹션 타이틀 | 공종코드 관리 |
|
||||
| 우측 버튼 | **[등록]** — 공종코드 등록 다이얼로그 |
|
||||
|
||||
### 4-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 타입 | 비고 |
|
||||
| -------- | ------------- | ------ | ------------------------ |
|
||||
| 코드 | `cnstpSeCd` | string | PK, 최대 10자 |
|
||||
| 코드명 | `cnstpSeCdNm` | string | 최대 100자 |
|
||||
| 설명 | `expln` | string | 최대 1000자, 선택 |
|
||||
| 사용여부 | `useYn` | string | `Y`→사용, `N`→미사용 |
|
||||
| 관리 | — | — | 행별 **[수정] · [삭제]** |
|
||||
|
||||
- 행 클릭 시 별도 상세 이동 없음. 수정은 **[수정]** 버튼으로 다이얼로그 진입.
|
||||
- 페이지네이션: Spring `Pageable` (`page`, `size`, `sort`) — **UI 노출**. 기본 `size: 10`, `@common/components` 공통 페이지네이션 컴포넌트 사용.
|
||||
|
||||
### 4-3. 버튼
|
||||
|
||||
| 버튼명 | 위치 | 동작 |
|
||||
| ------ | -------------- | ---------------------------------------- |
|
||||
| 등록 | 섹션 우측 상단 | 공종코드 등록 다이얼로그 오픈 |
|
||||
| 수정 | 행별 | 상세 조회 후 수정 다이얼로그 (값 초기화) |
|
||||
| 삭제 | 행별 | 확인 후 삭제, 목록 갱신 |
|
||||
|
||||
### 4-4. 다이얼로그: 공종코드 등록 / 수정
|
||||
|
||||
다이얼로그 입력 필드는 **코드 · 코드명 · 설명 · 사용여부** 4개만 노출한다.
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| -------- | --------- | ---- | ------ | ----------------- | ------------------------------- |
|
||||
| 코드 | Input | Y | — | `cnstpSeCd` | 등록 시 입력, 수정 시 읽기 전용 |
|
||||
| 코드명 | Input | N | — | `cnstpSeCdNm` | 최대 100자 |
|
||||
| 설명 | Input | N | — | `expln` | 최대 1000자 |
|
||||
| 사용여부 | Radio | N | Y | `useYn` | `Y`→사용, `N`→미사용 |
|
||||
|
||||
> UI에 노출하지 않는 API 필드(`upCnstpCd`, `cdLvNo`): 등록 시 `cdLvNo: 1` 등 기본값 전송, 수정 시 `findById` 응답값 유지.
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | ------------------------------------------------ |
|
||||
| 저장 | POST(등록) 또는 PUT(수정) 후 `findAll` 목록 갱신 |
|
||||
| 취소 | 다이얼로그 닫기, 입력값 폐기 |
|
||||
| 닫기 | 다이얼로그 닫기 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 영역 B: 회계코드 관리
|
||||
|
||||
백엔드 **회계구분관리**(`AcntgSeMng`) CRUD. 영역 A와 동일한 **평면 목록** UI 패턴을 따른다.
|
||||
|
||||
### 5-1. 헤더 / 툴바
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ------------------------------------- |
|
||||
| 섹션 타이틀 | 회계코드 관리 |
|
||||
| 우측 버튼 | **[등록]** — 회계코드 등록 다이얼로그 |
|
||||
|
||||
### 5-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 타입 | 비고 |
|
||||
| -------- | ------------- | ------ | ------------------------ |
|
||||
| 코드 | `acntgSeCd` | string | PK, 최대 10자 |
|
||||
| 코드명 | `acntgSeCdNm` | string | 최대 100자 |
|
||||
| 설명 | `expln` | string | 최대 1000자, 선택 |
|
||||
| 사용여부 | `useYn` | string | `Y`→사용, `N`→미사용 |
|
||||
| 관리 | — | — | 행별 **[수정] · [삭제]** |
|
||||
|
||||
- 페이지네이션: 영역 A와 동일 — **UI 노출**, 기본 `size: 10`.
|
||||
|
||||
### 5-3. 버튼
|
||||
|
||||
| 버튼명 | 위치 | 동작 |
|
||||
| ------ | -------------- | ---------------------------------------- |
|
||||
| 등록 | 섹션 우측 상단 | 회계코드 등록 다이얼로그 오픈 |
|
||||
| 수정 | 행별 | 상세 조회 후 수정 다이얼로그 (값 초기화) |
|
||||
| 삭제 | 행별 | 확인 후 삭제, 목록 갱신 |
|
||||
|
||||
### 5-4. 다이얼로그: 회계코드 등록 / 수정
|
||||
|
||||
다이얼로그 입력 필드는 **코드 · 코드명 · 설명 · 사용여부** 4개만 노출한다. (영역 A와 동일 패턴)
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| -------- | --------- | ---- | ------ | ----------------- | ------------------------------- |
|
||||
| 코드 | Input | Y | — | `acntgSeCd` | 등록 시 입력, 수정 시 읽기 전용 |
|
||||
| 코드명 | Input | Y | — | `acntgSeCdNm` | 최대 100자 |
|
||||
| 설명 | Input | N | — | `expln` | 최대 1000자 |
|
||||
| 사용여부 | Radio | N | Y | `useYn` | `Y`→사용, `N`→미사용 |
|
||||
|
||||
> UI에 노출하지 않는 API 필드(`upAcntgSeCd`, `cdLvNo`): 등록 시 `cdLvNo: 1` 등 기본값 전송, 수정 시 `findById` 응답값 유지.
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | ------------------------------------------------ |
|
||||
| 저장 | POST(등록) 또는 PUT(수정) 후 `findAll` 목록 갱신 |
|
||||
| 취소 | 다이얼로그 닫기, 입력값 폐기 |
|
||||
| 닫기 | 다이얼로그 닫기 |
|
||||
|
||||
---
|
||||
|
||||
## 6. API/DTO 명세
|
||||
|
||||
### 6-1. 공통
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ---------------------------------------------------------------------------------- |
|
||||
| 서비스 | `as-service` |
|
||||
| Base prefix | `/as-service/api/v1` (`ENDPOINT.AS_COMMON_SERVICE`) |
|
||||
| 인증 | JWT (`Authorization` 헤더), `X-Site-Id`, `token-id` |
|
||||
| 페이징 | Spring `Pageable`: `page`, `size`, `sort` → `PageResponse<T>` |
|
||||
| 엔티티 | `@/entities/cnstp` (`cnstpSeMngService`), `@/entities/acntg` (`acntgSeMngService`) |
|
||||
|
||||
**부가 API (본 화면 목록 외 참조용)**
|
||||
|
||||
| 리소스 | Method | URL | Response | 용도 |
|
||||
| ------------ | ------ | --------------------- | --------------------- | --------------------------------- |
|
||||
| 공종구분코드 | GET | `/cnstp-se/list/tree` | `CnstpSeMngTreeDto[]` | 계층 트리 (타 화면·상위코드 선택) |
|
||||
| 회계구분관리 | GET | `/acntg-se/list/tree` | `AcntgSeMngTreeDto[]` | 계층 트리 (타 화면·상위코드 선택) |
|
||||
|
||||
### 6-2. 공종구분코드 (영역 A) — `cnstp-se`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| --------- | ------ | ----------------------- | -------------------------------- | ----------------------------- | ---------------------------- |
|
||||
| 목록 조회 | GET | `/cnstp-se` | `CnstpSeMngSearchDto` + Pageable | `Page<CnstpSeMngResponseDto>` | `cnstpSeMngService.findAll` |
|
||||
| 트리 조회 | GET | `/cnstp-se/list/tree` | — | `CnstpSeMngTreeDto[]` | `cnstpSeMngService.findTree` |
|
||||
| 상세 조회 | GET | `/cnstp-se/{cnstpSeCd}` | — | `CnstpSeMngResponseDto` | `cnstpSeMngService.findById` |
|
||||
| 등록 | POST | `/cnstp-se` | `CnstpSeMngSaveRequestDto` | `string` (cnstpSeCd) | `cnstpSeMngService.save` |
|
||||
| 수정 | PUT | `/cnstp-se/{cnstpSeCd}` | `CnstpSeMngSaveRequestDto` | `string` (cnstpSeCd) | `cnstpSeMngService.update` |
|
||||
| 삭제 | DELETE | `/cnstp-se/{cnstpSeCd}` | — | `string` (cnstpSeCd) | `cnstpSeMngService.delete` |
|
||||
|
||||
**CnstpSeMngResponseDto**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| ------------- | ------- | ------------------ |
|
||||
| `cnstpSeCd` | string | 공종구분코드 |
|
||||
| `cnstpSeCdNm` | string | 공종구분코드명 |
|
||||
| `upCnstpCd` | string? | 상위공종코드 |
|
||||
| `cdLvNo` | number | 코드레벨번호 |
|
||||
| `useYn` | string | 사용여부 |
|
||||
| `expln` | string? | 설명 (최대 1000자) |
|
||||
| `rgtr` | string? | 등록자 UUID |
|
||||
| `rgtrNm` | string? | 등록자명 |
|
||||
| `mdfr` | string? | 수정자 UUID |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
| `mdfcnDt` | string? | 수정일시 |
|
||||
|
||||
**CnstpSeMngSaveRequestDto**: `cnstpSeCd`, `cnstpSeCdNm?`, `upCnstpCd?`, `cdLvNo?`, `useYn?`, `expln?`
|
||||
|
||||
**CnstpSeMngSearchDto**: `cnstpSeCd?`, `cnstpSeCdNm?`, `useYn?` + `page`, `size`, `sort`
|
||||
|
||||
**React Query hooks**: `useCnstpSeMngPage`, `useCnstpSeMngTree`, `useCnstpSeMng`, `useSaveCnstpSeMng`, `useUpdateCnstpSeMng`, `useDeleteCnstpSeMng`
|
||||
|
||||
### 6-3. 회계구분관리 (영역 B) — `acntg-se`
|
||||
|
||||
| 기능 | Method | URL | Request / Query | Response | 클라이언트 |
|
||||
| --------- | ------ | ----------------------- | -------------------------------- | ----------------------------- | ---------------------------- |
|
||||
| 목록 조회 | GET | `/acntg-se` | `AcntgSeMngSearchDto` + Pageable | `Page<AcntgSeMngResponseDto>` | `acntgSeMngService.findAll` |
|
||||
| 트리 조회 | GET | `/acntg-se/list/tree` | — | `AcntgSeMngTreeDto[]` | `acntgSeMngService.findTree` |
|
||||
| 상세 조회 | GET | `/acntg-se/{acntgSeCd}` | — | `AcntgSeMngResponseDto` | `acntgSeMngService.findById` |
|
||||
| 등록 | POST | `/acntg-se` | `AcntgSeMngSaveRequestDto` | `string` (acntgSeCd) | `acntgSeMngService.save` |
|
||||
| 수정 | PUT | `/acntg-se/{acntgSeCd}` | `AcntgSeMngSaveRequestDto` | `string` (acntgSeCd) | `acntgSeMngService.update` |
|
||||
| 삭제 | DELETE | `/acntg-se/{acntgSeCd}` | — | `string` (acntgSeCd) | `acntgSeMngService.delete` |
|
||||
|
||||
**AcntgSeMngResponseDto**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| ------------- | ------- | ------------------ |
|
||||
| `acntgSeCd` | string | 회계구분코드 |
|
||||
| `acntgSeCdNm` | string | 회계구분코드명 |
|
||||
| `upAcntgSeCd` | string? | 상위회계구분코드 |
|
||||
| `cdLvNo` | number | 코드레벨번호 |
|
||||
| `useYn` | string | 사용여부 |
|
||||
| `expln` | string? | 설명 (최대 1000자) |
|
||||
| `rgtr` | string? | 등록자 UUID |
|
||||
| `rgtrNm` | string? | 등록자명 |
|
||||
| `mdfr` | string? | 수정자 UUID |
|
||||
| `regDt` | string? | 등록일시 |
|
||||
| `mdfcnDt` | string? | 수정일시 |
|
||||
|
||||
**AcntgSeMngSaveRequestDto**: `acntgSeCd`, `acntgSeCdNm`, `upAcntgSeCd?`, `cdLvNo`, `useYn?`, `expln?`
|
||||
|
||||
**AcntgSeMngSearchDto**: `acntgSeCd?`, `acntgSeCdNm?`, `useYn?` + `page`, `size`, `sort`
|
||||
|
||||
**React Query hooks**: `useAcntgSeMngPage`, `useAcntgSeMngTree`, `useAcntgSeMng`, `useSaveAcntgSeMng`, `useUpdateAcntgSeMng`, `useDeleteAcntgSeMng`
|
||||
|
||||
---
|
||||
|
||||
## 7. UI 구현 가이드
|
||||
|
||||
### 7-1. 기술 스택·원칙
|
||||
|
||||
- Next.js App Router, React Query (`@tanstack/react-query`)
|
||||
- `@common/components` — `Card`, `Button`, `Dialog`, `DataTable` / `useDataTable`
|
||||
- `@tanstack/react-table` — 컬럼 정의는 `model/*-table-columns.tsx` 분리
|
||||
- 기존 entity 레이어 재사용: `@/entities/cnstp`, `@/entities/acntg` (service·queries·interface 구현 완료)
|
||||
- 좌·우 2열 레이아웃: `grid grid-cols-1 lg:grid-cols-2 gap-4` (모바일 1열 스택)
|
||||
- 삭제 전 `confirm` / Toast 피드백 — 프로젝트 공통 패턴 준수
|
||||
- 목록 하단 **페이지네이션 UI 노출** — 영역 A·B 각각 독립 page state
|
||||
- **검색 필터 UI 미제공** — `findAll` 호출 시 `page`, `size`만 전달
|
||||
- **등록/수정 다이얼로그** — 코드·코드명·설명은 `Input`, 사용여부는 `Radio` (4필드만 노출)
|
||||
- 상위 코드 삭제 시 **하위 코드 연쇄 삭제 UI·로직 미구현** — 단건 삭제만 수행
|
||||
|
||||
### 7-2. 모듈·파일 배치
|
||||
|
||||
| 구분 | 경로 (제안) |
|
||||
| ----------------- | -------------------------------------------------------------------- |
|
||||
| 라우트 | `apps/as/src/app/(authenticated)/site/code-management/page.tsx` |
|
||||
| 페이지 컴포넌트 | `apps/as/src/pages/code-management/ui/code-management-page.tsx` |
|
||||
| 공종 그리드 컬럼 | `apps/as/src/pages/code-management/model/cnstp-se-table-columns.tsx` |
|
||||
| 회계 그리드 컬럼 | `apps/as/src/pages/code-management/model/acntg-se-table-columns.tsx` |
|
||||
| 공종 등록/수정 폼 | `apps/as/src/pages/code-management/ui/cnstp-se-form-dialog.tsx` |
|
||||
| 회계 등록/수정 폼 | `apps/as/src/pages/code-management/ui/acntg-se-form-dialog.tsx` |
|
||||
| API·타입 (기존) | `@/entities/cnstp`, `@/entities/acntg` |
|
||||
|
||||
### 7-3. 영역별 UI 매핑
|
||||
|
||||
| 영역 | UI 컴포넌트 | 데이터 소스 | 비고 |
|
||||
| ------------ | ------------------------------------- | ------------------------------------------- | ------------------------------ |
|
||||
| A | `CnstpSeSection` + Table + Pagination | `useCnstpSeMngPage({ page, size })` | 독립 page state·mutation |
|
||||
| B | `AcntgSeSection` + Table + Pagination | `useAcntgSeMngPage({ page, size })` | A와 상호 의존 없음 |
|
||||
| A 다이얼로그 | `CnstpSeFormDialog` | `useCnstpSeMng`, `useSave/UpdateCnstpSeMng` | Input 4필드 + Radio 사용여부 |
|
||||
| B 다이얼로그 | `AcntgSeFormDialog` | `useAcntgSeMng`, `useSave/UpdateAcntgSeMng` | Input 4필드 + Radio 사용여부 |
|
||||
|
||||
### 7-4. 다이얼로그·라우팅
|
||||
|
||||
| 다이얼로그 | 트리거 | 라우팅 |
|
||||
| ------------- | ---------------- | -------------------- |
|
||||
| 공종코드 등록 | 영역 A [등록] | URL 변경 없음 (모달) |
|
||||
| 공종코드 수정 | 영역 A 행 [수정] | URL 변경 없음 (모달) |
|
||||
| 회계코드 등록 | 영역 B [등록] | URL 변경 없음 (모달) |
|
||||
| 회계코드 수정 | 영역 B 행 [수정] | URL 변경 없음 (모달) |
|
||||
|
||||
### 7-5. 데이터 흐름 (구현 관점)
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 페이지 마운트 — 검색 조건 없이 page·size만 전달
|
||||
const cnstpQuery = useCnstpSeMngPage({ page: 0, size: 20 })
|
||||
const acntgQuery = useAcntgSeMngPage({ page: 0, size: 20 })
|
||||
|
||||
DISPLAY CodeManagementPage
|
||||
├─ CnstpSeSection(data=cnstpQuery.data, pagination)
|
||||
└─ AcntgSeSection(data=acntgQuery.data, pagination)
|
||||
|
||||
// 페이지 변경
|
||||
ON pagination page/size CHANGE DO
|
||||
refetch cnstpQuery | acntgQuery with new page, size
|
||||
END ON
|
||||
|
||||
// mutation 성공 시
|
||||
ON save/update/delete SUCCESS DO
|
||||
invalidateQueries cnstp-se | acntg-se baseKey
|
||||
TOAST "저장되었습니다." | "삭제되었습니다."
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
@@ -1,498 +0,0 @@
|
||||
# 화면설계서: 전국 행정지원 지도 (대시보드 메인)
|
||||
|
||||
## 1. 기본 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | -------------------------------------------- |
|
||||
| 버전 | 1.2 |
|
||||
| 프로세스명 | UI설계 |
|
||||
| 화면명 | 전국 행정지원 지도 (대시보드 메인) |
|
||||
| 화면 ID | TBD |
|
||||
| 화면 유형 | [v] 조회 [ ] 입력 [ ] 수정 [ ] 삭제 [ ] 출력 |
|
||||
| 메뉴 경로 | 메인 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 화면 목적
|
||||
|
||||
로그인 사용자의 **기관 권한·당해 연도** 기준으로 문서별 진행상태 통계와 행정지원 알림을 한 화면에서 조회한다. 좌측 지도에서 전국 행정지원 현황을 보고, 우측에서 진행상황 카드·알림이력·공지사항을 확인한 뒤 알림 [처리하기]로 연계 업무 화면으로 이동한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 화면 구성
|
||||
|
||||
### 3-1. 전체 레이아웃
|
||||
|
||||
브레드크럼·페이지 타이틀은 스크린샷에 없음. 홈(`/`) 메인 콘텐츠로 구성한다.
|
||||
|
||||
```
|
||||
┌────────────────────────────────┬─────────────────────────────────────────────────┐
|
||||
│ [영역 A] 전국 행정지원 지도 │ [영역 B] 문서별 진행상황 카드 (2×2) │
|
||||
│ 타이틀: 전국 행정지원 지도 │ ┌────────────────┐ ┌────────────────┐ │
|
||||
│ │ │ 재원협의 │ │ 설치인가 │ │
|
||||
│ (대한민국 시도·시군구 경계) │ │ 신청/진행/완료 │ │ 신청/진행/완료 │ │
|
||||
│ 마커: 서울 강남구, │ ├────────────────┤ ├────────────────┤ │
|
||||
│ 대전 유성구, │ │ 설계자문 │ │ 기본계획 │ │
|
||||
│ 부산 해운대구 │ │ 신청/진행/완료 │ │ 신청/진행/완료 │ │
|
||||
│ │ └────────────────┘ └────────────────┘ │
|
||||
│ ├─────────────────────────────────────────────────┤
|
||||
│ │ [영역 C] 알림이력 │
|
||||
│ │ 알림이력 업데이트 HH:mm [전체보기] │
|
||||
│ │ [오늘 N건] [지연 N건] [완료대기 N건] │
|
||||
│ │ [뱃지] [일자] 제목 [처리하기] │
|
||||
│ │ … (최대 5건) │
|
||||
│ ├─────────────────────────────────────────────────┤
|
||||
│ │ [영역 D] 공지사항 [더보기] │
|
||||
│ │ ┌────┬────────┬────────┬────────┬──────┐ │
|
||||
│ │ │번호│ 제목 │ 작성자 │ 작성일 │조회수│ │
|
||||
│ │ └────┴────────┴────────┴────────┴──────┘ │
|
||||
└────────────────────────────────┴─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-2. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입
|
||||
// searchYear 미전달 → 서버가 당해 연도로 고정. 알림 목록은 최신 5건
|
||||
CALL getMainDashboard(DashboardMainSearchDto) // Authorization은 client 인터셉터
|
||||
DISPLAY 진행상황 카드 (영역 B) // docPrgrsSttsList, TOTAL 행 제외
|
||||
DISPLAY 알림 통계 칩 · 알림 목록 (영역 C) // notiStats, notiList
|
||||
|
||||
CALL getUserPostList(UserPostSearchParams) // board-service, AS_DASHBOARD_BBS_ID
|
||||
DISPLAY 공지사항 그리드 (영역 D)
|
||||
|
||||
CALL 지도 마커/음영 조회(…) // TBD — 대시보드 API에 없음
|
||||
DISPLAY 전국 지도 (영역 A)
|
||||
|
||||
ON 영역 C [전체보기] 버튼 CLICK DO
|
||||
NAVIGATE /nti-hstry
|
||||
END ON
|
||||
|
||||
ON 영역 C [처리하기] 버튼 CLICK DO
|
||||
CALL readNoti(notiId) // entities/noti
|
||||
NAVIGATE notiUrl // 비어 있으면 이동하지 않음
|
||||
CALL getMainDashboard(…) // → 영역 C 갱신 (invalidate)
|
||||
END ON
|
||||
|
||||
ON 영역 D [더보기] 버튼 CLICK DO
|
||||
NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID} // as 앱 공지 목록 라우트 미구현. st/cm 관례
|
||||
END ON
|
||||
|
||||
ON 영역 D 행 CLICK DO
|
||||
NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}
|
||||
END ON
|
||||
|
||||
ON 영역 B 카드 CLICK DO
|
||||
NAVIGATE 해당 문서 목록 // §5-3
|
||||
END ON
|
||||
|
||||
ON 영역 A 마커 CLICK DO
|
||||
// TBD — 팝업/필터/이동 여부 미확정
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 영역 A — 전국 행정지원 지도
|
||||
|
||||
스크린샷 타이틀: **전국 행정지원 지도**.
|
||||
|
||||
`getMainDashboard` 응답에 지도·좌표·행정구역 음영 데이터는 **없다**. 마커·음영 소스 API는 **TBD**.
|
||||
|
||||
### 4-1. 표시 요소
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| ----------- | --------- | ---- | ------ | ----------------- | ----------------------------------------------------------------- |
|
||||
| 섹션 타이틀 | Text | — | — | — | 고정 문구 `전국 행정지원 지도` |
|
||||
| 전국 지도 | Map | — | — | TBD | 시도·시군구 경계. 북·동부 음영(청) / 남서부 비음영(백) — 의미 TBD |
|
||||
| 마커 라벨 | Marker | — | — | TBD | 스크린샷 샘플: `서울 강남구`, `대전 유성구`, `부산 해운대구` |
|
||||
|
||||
### 4-2. 상호작용
|
||||
|
||||
| 동작 | 설명 |
|
||||
| ---------- | ----------------------------------------- |
|
||||
| 마커 클릭 | TBD (상세 팝업 / 해당 지자체 필터 / 이동) |
|
||||
| 지도 줌·팬 | TBD (스크린샷에 컨트롤 없음) |
|
||||
|
||||
`entities/adstdstr`는 시도·구군 **콤보**만 제공하며 좌표를 주지 않는다. 지도 라이브러리도 as 앱에 없음 — 선정 TBD.
|
||||
|
||||
---
|
||||
|
||||
## 5. 영역 B — 문서별 진행상황 카드
|
||||
|
||||
`DashboardMainResponseDto.docPrgrsSttsList`를 **`docSeComCd`로 매핑**해 4장 카드를 그린다. 배열 순서에 의존하지 않는다.
|
||||
|
||||
스크린샷 배치(좌→우, 상→하):
|
||||
|
||||
| 화면 카드 타이틀 | `docSeComCd` | API `docSeNm` |
|
||||
| ----------------- | ------------ | -------------- |
|
||||
| 재원협의 진행상황 | `FNRS` | 재원협의 |
|
||||
| 설치인가 진행상황 | `INSTL` | 설치인가 |
|
||||
| 설계자문 진행상황 | `CNFM` | 설계자문 |
|
||||
| 기본계획 진행상황 | `SEWER` | 하수도기본계획 |
|
||||
|
||||
서버 SQL `ORDER BY`는 `INSTL → FNRS → SEWER → CNFM` 이며, `GROUP BY ROLLUP`으로 **`docSeComCd = TOTAL`** 합계 행이 추가된다. 카드에는 TOTAL 행을 **표시하지 않는다**.
|
||||
|
||||
카드 타이틀은 스크린샷 문구(`… 진행상황`)를 쓴다. `SEWER`의 API명 `하수도기본계획`은 화면에서 `기본계획`으로 축약한다.
|
||||
|
||||
### 5-1. 카드 내부 필드
|
||||
|
||||
각 카드 공통 구조. `totCnt`는 화면에 없음.
|
||||
|
||||
| 표시명 | Field | 비고 |
|
||||
| ------ | ---------- | ------------------ |
|
||||
| 신청 | `reqCnt` | 파란 아이콘 + 건수 |
|
||||
| 진행 | `prgrsCnt` | 초록 아이콘 + 건수 |
|
||||
| 완료 | `cmptnCnt` | 주황 아이콘 + 건수 |
|
||||
|
||||
상태 그룹(서버): 임시저장(`SV`/`CV`) 제외. 문서별 `prgrs_stts_com_cd` → `REQ`/`PRG`/`CMP`.
|
||||
|
||||
### 5-2. 검색 파라미터 (화면 미표시)
|
||||
|
||||
영역 B에 연도·필터 UI는 없다. 서버 기본값을 따른다.
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| ------ | --------- | ---- | --------- | ----------------- | --------------------------------------------------------------------- |
|
||||
| (없음) | — | — | 당해 연도 | `searchYear` | 미전달 시 서버 `LocalDate.now().getYear()`. 연도 셀렉터 추가 여부 TBD |
|
||||
|
||||
`docSeComCd` 쿼리는 **알림 목록 필터**에만 쓰이며, 진행상황 SQL에는 전달되지 않는다. 카드 4종은 항상 전원 집계한다.
|
||||
|
||||
### 5-3. 상호작용
|
||||
|
||||
카드 클릭 시 **해당 문서 목록 페이지**로 이동한다. `docSeComCd` → 라우트 고정 매핑.
|
||||
|
||||
| 동작 | `docSeComCd` | 이동 경로 |
|
||||
| --------- | ------------ | ----------------- |
|
||||
| 카드 클릭 | `FNRS` | `/fnrs-cnsltn` |
|
||||
| 카드 클릭 | `INSTL` | `/instl-sncn` |
|
||||
| 카드 클릭 | `CNFM` | `/design-cnstn` |
|
||||
| 카드 클릭 | `SEWER` | `/sewer-bsc-plan` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 영역 C — 알림이력
|
||||
|
||||
서버가 cms-service 알림을 대시보드 응답에 합친다. 목록은 **page=0, size=5** (최신 5건). 페이지네이션 없음.
|
||||
|
||||
### 6-1. 헤더
|
||||
|
||||
| 표시명 | Field / 소스 | 비고 |
|
||||
| ------------- | ------------ | --------------------------------------------------------------------------------------- |
|
||||
| 섹션 타이틀 | — | 고정 문구 `알림이력` |
|
||||
| 업데이트 시각 | (client) | 스크린샷 `업데이트 10:32`. API 필드 없음. `getMainDashboard` 마지막 fetch 시각(`HH:mm`) |
|
||||
| 전체보기 | Button | `/nti-hstry`로 이동 |
|
||||
|
||||
### 6-2. 통계 칩
|
||||
|
||||
`NotiAsStatResponseDto`.
|
||||
|
||||
| 표시명 | Field | 비고 |
|
||||
| ------------ | -------------- | -------------------------------------- |
|
||||
| 오늘 N건 | `todayCount` | 당일 00:00 이후 수신 |
|
||||
| 지연 N건 | `delayCount` | `notReadYn=N` 이고 수신 후 3일 이상 |
|
||||
| 완료대기 N건 | `pendingCount` | `notReadYn=Y` 이고 `notiPrcsCmptnYn=N` |
|
||||
|
||||
### 6-3. 목록 행
|
||||
|
||||
| 표시명 | Field | 비고 |
|
||||
| ------ | --------- | --------------------------------------------- |
|
||||
| 일자 | `regDt` | 표시 `YYYY-MM-DD`. 응답 `yyyy-MM-dd HH:mm:ss` |
|
||||
| 제목 | `notiTtl` | 알림 제목 |
|
||||
| 처리 | (action) | 스크린샷 라벨 `처리하기`. 클릭 §6-4 |
|
||||
|
||||
응답에 있으나 이 목록에 **표시하지 않음**:
|
||||
|
||||
| Field | 비고 |
|
||||
| ----------------- | ----------------------------------------- |
|
||||
| `notiId` | 행 키 · `readNoti` 파라미터 |
|
||||
| `recvUnqId` | 수신 회원 UUID (서버 로그인 사용자 고정) |
|
||||
| `senderUnqId` | 발신 회원 UUID |
|
||||
| `notiType` | `ADSS` |
|
||||
| `notiCn` | 본문 |
|
||||
| `notiUrl` | 처리 후 이동 URL. 컬럼 미표시 |
|
||||
| `notiLnkgUnqNo` | 알림연결고유번호 |
|
||||
| `docSeComCd` | 문서구분 코드 |
|
||||
| `docSeComNm` | 문서구분명 (알림이력 화면에서는 연계업무) |
|
||||
| `notReadYn` | 뱃지 판정 TBD에 사용 가능 |
|
||||
| `notiIdntyYn` | 확인 여부 |
|
||||
| `notiIdntyDt` | 확인 일시 |
|
||||
| `notiPrcsCmptnYn` | 처리 완료 여부 |
|
||||
| `notiPrcsCmptnDt` | 처리 완료 일시 |
|
||||
|
||||
### 6-4. 행 상호작용
|
||||
|
||||
| 동작 | 설명 |
|
||||
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| [전체보기] 클릭 | `/nti-hstry` (알림이력 목록)로 이동 |
|
||||
| [처리하기] 클릭 | `readNoti(notiId)` 후 `notiUrl`로 이동. URL이 비면 이동하지 않음(읽음 처리는 수행). `dashboardBaseKey` invalidate |
|
||||
|
||||
`DashboardController`에 읽음 API는 없다. **`entities/noti`의 `readNoti`** 를 쓴다. 알림이력 화면과 동일 (`PUT /cms-service/api/v1/noti/{notiId}/read`).
|
||||
|
||||
### 6-5. 검색 파라미터 (화면 미표시)
|
||||
|
||||
서버 `toNotiSearchDto()` 기본: `notiType = ADSS`. 화면 필터 없음.
|
||||
|
||||
| DashboardMainSearchDto | 화면 | 비고 |
|
||||
| ---------------------- | ---- | --------------------------------- |
|
||||
| `notiType` | 없음 | 서버 기본 `ADSS` |
|
||||
| `notReadYn` | 없음 | 통계 칩 클릭 필터 시 후보 (TBD) |
|
||||
| `startDt` / `endDt` | 없음 | 대시보드 기본 미전달 |
|
||||
| `docSeComCd` | 없음 | 알림만 필터. 진행상황 카드와 무관 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 영역 D — 공지사항
|
||||
|
||||
`getMainDashboard`에 공지 필드는 없다. **board-service** `getUserPostList`로 별도 조회한다.
|
||||
|
||||
- Base: `GET /board-service/api/v1/posts/user/{AS_DASHBOARD_BBS_ID}`
|
||||
- `AS_DASHBOARD_BBS_ID` = `NEXT_PUBLIC_AS_DASHBOARD_BBS_ID` (로컬 예: `7`)
|
||||
- 클라이언트: `@/entities/board` — `postApi.getUserPostList` / `useUserPostList`
|
||||
|
||||
페이지네이션 컨트롤은 없다. 요약 목록만 표시한다 (`page=0`, `size=3`).
|
||||
|
||||
### 7-1. 헤더·버튼
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | ------------------------------------------------------------------------------------------- |
|
||||
| 더보기 | `/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}` 로 이동. as 앱에 공지 목록 라우트는 없음(st/cm 관례) |
|
||||
|
||||
### 7-2. 그리드 컬럼
|
||||
|
||||
스크린샷 헤더 순서. `UserPost`.
|
||||
|
||||
| 표시명 | Field | 비고 |
|
||||
| ------ | --------- | ---------------------------------------------------- |
|
||||
| 번호 | `rowNo` | `upndFixYn` = `Y` 이면 `[공지]` Badge, 그 외 `rowNo` |
|
||||
| 제목 | `pstTtl` | truncate |
|
||||
| 작성자 | `wrtrNm` | |
|
||||
| 작성일 | `regDt` | 표시 `YYYY-MM-DD` (응답 datetime) |
|
||||
| 조회수 | `inqNocs` | 숫자 |
|
||||
|
||||
조회 파라미터 (`UserPostSearchParams`):
|
||||
|
||||
| 필드 | 값 | 비고 |
|
||||
| ------------- | ----------- | ------------------------------------------ |
|
||||
| `page` | `0` | Spring 0-based |
|
||||
| `size` | `3` | 대시보드 요약. 스크린샷 3행 |
|
||||
| `keywordType` | `bbsTypeCd` | st 대시보드 공지 패널과 동일 |
|
||||
| `keyword` | `BBSNOTICE` | 게시판 유형. path의 bbsId와 함께 공지 한정 |
|
||||
|
||||
응답에 있으나 그리드에 **표시하지 않음**: `bbsId`, `pstNo`(행 키·상세 이동), `pstCn`, `upndFixYn`(번호 열 판정만), `rgtrNm`, `atflCd` 등.
|
||||
|
||||
### 7-3. 행 상호작용
|
||||
|
||||
| 동작 | 설명 |
|
||||
| ------- | ------------------------------------------------------------------------------ |
|
||||
| 행 클릭 | `/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}` (as 앱 공지 상세 라우트 미구현) |
|
||||
|
||||
---
|
||||
|
||||
## 8. API/DTO 명세
|
||||
|
||||
### 8-1. 공통
|
||||
|
||||
| 항목 | 값 |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| Base prefix | `/as-service/api/v1/dashboard` (`ENDPOINT.AS_SERVICE.DASHBOARD`) |
|
||||
| 인증 | `Authorization` 헤더. 프론트는 `client` 인터셉터. 로그인 기관 권한은 서버가 사용자 캐시로 적용 |
|
||||
| 클라이언트 모듈 | `@/entities/dashboard` — `dashboardService` / `useGetMainDashboard` |
|
||||
| 알림 읽음 | `@/entities/noti` — `notiService.readNoti` / `useReadNoti` |
|
||||
| 공지사항 | `@/entities/board` — `postApi.getUserPostList` / `useUserPostList` |
|
||||
|
||||
영역 A(지도)는 본 컨트롤러·board-service 범위 밖 → **TBD**.
|
||||
|
||||
### 8-2. 대시보드 메인 조회 — `getMainDashboard`
|
||||
|
||||
| 기능 | Method | URL | Request DTO | Response DTO | API |
|
||||
| -------------------------------------------- | ------ | ------------- | ------------------------------- | -------------------------- | ----------------------------------------------------------- |
|
||||
| 대시보드 메인 통합진행상태 및 알림 정보 조회 | GET | `{BASE}/main` | Query: `DashboardMainSearchDto` | `DashboardMainResponseDto` | `dashboardService.getMainDashboard` / `useGetMainDashboard` |
|
||||
|
||||
**Request (`DashboardMainSearchDto`)**
|
||||
|
||||
| 필드 | 필수 | 설명 |
|
||||
| ------------ | ---- | ---------------------------------------------------------------------- |
|
||||
| `searchYear` | N | 검색 연도. 미전달 시 서버 당해 연도. 영역 B 집계 기간 |
|
||||
| `notiType` | N | 알림 종류. 미전달 시 서버 `ADSS` |
|
||||
| `notReadYn` | N | 알림 확인 여부 `Y`/`N`. 본 화면 미사용 |
|
||||
| `startDt` | N | 알림 시작일 `YYYY-MM-DD`. 본 화면 미사용 |
|
||||
| `endDt` | N | 알림 종료일 `YYYY-MM-DD`. 본 화면 미사용 |
|
||||
| `docSeComCd` | N | 알림 문서구분 (`INSTL`/`FNRS`/`SEWER`/`CNFM` 등). 진행상황 집계와 무관 |
|
||||
|
||||
`Authorization`은 service 시그니처에 넣지 않는다.
|
||||
|
||||
**Response (`DashboardMainResponseDto`)**
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
| ------------------ | --------------------------- | --------------------------- |
|
||||
| `docPrgrsSttsList` | `DocPrgrsSttsResponseDto[]` | 문서별 진행상태 + TOTAL 행 |
|
||||
| `notiList` | `NotiAsUserResponseDto[]` | 최신 최대 5건 |
|
||||
| `notiStats` | `NotiAsStatResponseDto` | 오늘 / 지연 / 완료대기 건수 |
|
||||
|
||||
**`DocPrgrsSttsResponseDto`**
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
| ------------ | ------ | --------------------------------------------- |
|
||||
| `docSeNm` | string | 문서 구분 명칭 |
|
||||
| `docSeComCd` | string | `INSTL` / `FNRS` / `SEWER` / `CNFM` / `TOTAL` |
|
||||
| `reqCnt` | number | 신청 건수 |
|
||||
| `prgrsCnt` | number | 진행 건수 |
|
||||
| `cmptnCnt` | number | 완료 건수 |
|
||||
| `totCnt` | number | 총 건수 (화면 미표시) |
|
||||
|
||||
**`NotiAsStatResponseDto`**
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
| -------------- | ------ | --------- |
|
||||
| `todayCount` | number | 오늘 알림 |
|
||||
| `delayCount` | number | 지연 알림 |
|
||||
| `pendingCount` | number | 완료대기 |
|
||||
|
||||
**`NotiAsUserResponseDto`** — 필드 상세는 `docs/spec/nti-hstry` §6-2와 동일 (`notiId`, `notiTtl`, `regDt`, `notiUrl`, `notReadYn`, `notiPrcsCmptnYn` 등).
|
||||
|
||||
### 8-3. 알림 읽음 처리 — `readNoti`
|
||||
|
||||
대시보드 컨트롤러가 아니라 cms-service. 영역 C [처리하기]에서 호출.
|
||||
|
||||
| 기능 | Method | URL | Request DTO | Response DTO | API |
|
||||
| -------------- | ------ | ---------------------------------------- | ----------------------- | ---------------- | -------------------------------------- |
|
||||
| 알림 읽음 처리 | PUT | `/cms-service/api/v1/noti/{notiId}/read` | Path: `notiId` (`Long`) | `Long` (알림 ID) | `notiService.readNoti` / `useReadNoti` |
|
||||
|
||||
Body 없음. 성공 시 `dashboardBaseKey`(및 필요 시 `notiBaseKey`) invalidate.
|
||||
|
||||
### 8-4. 전국 행정지원 지도 — TBD
|
||||
|
||||
| 기능 | Method | URL | Request DTO | Response DTO | API |
|
||||
| ------------------- | ------ | --- | ----------- | ------------ | --- |
|
||||
| 지도 마커·음영 조회 | TBD | TBD | TBD | TBD | TBD |
|
||||
|
||||
### 8-5. 공지사항 — `getUserPostList`
|
||||
|
||||
board-service. bbsId는 환경변수 `AS_DASHBOARD_BBS_ID`로 path에 고정한다.
|
||||
|
||||
| 기능 | Method | URL | Request DTO | Response DTO | API |
|
||||
| ----------------------- | ------ | ------------------------------------------ | ----------------------------- | ------------------------ | --------------------------------------------- |
|
||||
| 대시보드 공지 요약 목록 | GET | `/board-service/api/v1/posts/user/{bbsId}` | Query: `UserPostSearchParams` | `PageResponse<UserPost>` | `postApi.getUserPostList` / `useUserPostList` |
|
||||
|
||||
**Request (`UserPostSearchParams`)** — 본 화면 고정값
|
||||
|
||||
| 필드 | 필수 | 설명 |
|
||||
| ------------- | ---- | -------------- |
|
||||
| `page` | N | `0` |
|
||||
| `size` | N | `3` |
|
||||
| `keywordType` | N | `bbsTypeCd` |
|
||||
| `keyword` | N | `BBSNOTICE` |
|
||||
| `popupYn` 등 | N | 본 화면 미사용 |
|
||||
|
||||
**Response (`UserPost`) — 화면 매핑 필드**
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
| ----------- | ------ | --------------------------- |
|
||||
| `rowNo` | number | 번호. 고정글이 아니면 표시 |
|
||||
| `pstNo` | number | 게시 번호. 상세 이동 키 |
|
||||
| `bbsId` | number | 게시판 ID |
|
||||
| `pstTtl` | string | 제목 |
|
||||
| `wrtrNm` | string | 작성자 |
|
||||
| `regDt` | string | 작성일 |
|
||||
| `inqNocs` | number | 조회수 |
|
||||
| `upndFixYn` | string | 상단고정 `Y`/`N` → `[공지]` |
|
||||
|
||||
---
|
||||
|
||||
## 9. UI 구현 가이드
|
||||
|
||||
### 9-1. 기술 스택·원칙
|
||||
|
||||
- 라우트: 기존 홈 `app/(main)/(with-base-layout)/page.tsx` → `pages/home` (현재 `MainPage` 플레이스홀더)
|
||||
- UI: `@common/components` — Card, Badge, Button, Table(공지). 지도 라이브러리 TBD
|
||||
- 데이터: React Query `useGetMainDashboard()`. 처리하기는 `useReadNoti()`. 공지는 `useUserPostList()`
|
||||
- 진행상황 카드: `docSeComCd`로 4슬롯 매핑. `TOTAL` 제외
|
||||
- 알림 목록: 테이블이 아닌 행 리스트(뱃지 + 일자 + 제목 + 버튼)
|
||||
- 공지: `@tanstack/react-table` + `useDataTable`, 페이지네이션 없음
|
||||
- 검색 조건 URL 동기화: 본 화면 필터 없음. `searchYear` UI가 생기면 그때 검토
|
||||
|
||||
### 9-2. 모듈·파일 배치
|
||||
|
||||
| 구분 | 경로 |
|
||||
| ------------- | ------------------------------------------------------------ |
|
||||
| 라우트 | `app/(main)/(with-base-layout)/page.tsx` |
|
||||
| 페이지 | `pages/dashboard/ui/dashboard-page.tsx` |
|
||||
| 지도 | `pages/dashboard/ui/national-as-map.tsx` (API TBD, Skeleton) |
|
||||
| 진행상황 카드 | `pages/dashboard/ui/doc-prgrs-stts-cards.tsx` |
|
||||
| 알림이력 | `pages/dashboard/ui/dashboard-noti-list.tsx` |
|
||||
| 공지사항 | `pages/dashboard/ui/dashboard-notice-table.tsx` |
|
||||
| 공지 컬럼 | `pages/dashboard/model/dashboard-notice-table-columns.tsx` |
|
||||
| Entity API | `entities/dashboard/api/dashboard-service.ts` |
|
||||
| Entity Hook | `entities/dashboard/api/queries.ts` → `useGetMainDashboard` |
|
||||
| Entity Model | `entities/dashboard/model/dashboard-interface.ts` |
|
||||
| 알림 읽음 | `entities/noti` → `useReadNoti` |
|
||||
| 공지 Entity | `entities/board` → `useUserPostList` |
|
||||
|
||||
Entity(`getMainDashboard`, `getUserPostList`) 구현됨. 영역 B·C·D 화면 구현. 영역 A는 Skeleton.
|
||||
|
||||
### 9-3. 영역별 UI 매핑
|
||||
|
||||
| 영역 | 컴포넌트 | 데이터 |
|
||||
| ---- | ------------------------ | ---------------------------------------------------------------------------- |
|
||||
| A | `national-as-map` | Skeleton (지도 API TBD) |
|
||||
| B | `doc-prgrs-stts-cards` | `useGetMainDashboard` → `docPrgrsSttsList` (`TOTAL` 제외, 코드 매핑) |
|
||||
| C | `dashboard-noti-list` | 동 훅 → `notiStats`, `notiList`. 처리 → `useReadNoti`. 전체보기 `/nti-hstry` |
|
||||
| D | `dashboard-notice-table` | `useUserPostList` → `content[]`. [더보기]·행 클릭 → `/cms/bbsnotice/...` |
|
||||
|
||||
### 9-4. 다이얼로그·라우팅
|
||||
|
||||
| 항목 | 내용 |
|
||||
| -------------- | -------------------------------------------------------------------------------------- |
|
||||
| 다이얼로그 | 없음 |
|
||||
| 본 화면 라우트 | `/` (홈) |
|
||||
| 알림 처리 이동 | [처리하기] → `readNoti` 후 `notiUrl` (알림이력과 동일, SEWER URL은 상세 세그먼트 제거) |
|
||||
| 알림 전체보기 | `/nti-hstry` |
|
||||
| 공지 더보기 | `/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}` (as 앱 공지 라우트 미구현, st/cm 관례) |
|
||||
| 공지 행 클릭 | `/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}` |
|
||||
| 진행상황 카드 | §5-3 목록 라우트 (`/fnrs-cnsltn`, `/instl-sncn`, `/design-cnstn`, `/sewer-bsc-plan`) |
|
||||
|
||||
### 9-5. 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입 (홈)
|
||||
CALL getMainDashboard({})
|
||||
DISPLAY 영역 B // docPrgrsSttsList — FNRS/INSTL/CNFM/SEWER 슬롯
|
||||
DISPLAY 영역 C // notiStats + notiList(≤5)
|
||||
|
||||
CALL getUserPostList({ page: 0, size: 3, keywordType: "bbsTypeCd", keyword: "BBSNOTICE" })
|
||||
DISPLAY 영역 D
|
||||
|
||||
CALL 지도 데이터 // TBD → 영역 A
|
||||
|
||||
ON 영역 C [전체보기] CLICK DO
|
||||
NAVIGATE /nti-hstry
|
||||
END ON
|
||||
|
||||
ON 영역 C [처리하기] CLICK DO
|
||||
CALL readNoti(notiId)
|
||||
IF notiUrl THEN
|
||||
NAVIGATE notiUrl
|
||||
END IF
|
||||
CALL getMainDashboard // invalidate dashboardBaseKey
|
||||
END ON
|
||||
|
||||
ON 영역 B 카드 CLICK DO
|
||||
NAVIGATE 문서 목록 // §5-3
|
||||
END ON
|
||||
|
||||
ON 영역 D [더보기] CLICK DO
|
||||
NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}
|
||||
END ON
|
||||
|
||||
ON 영역 D 행 CLICK DO
|
||||
NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
@@ -1,292 +0,0 @@
|
||||
# 화면설계서: 필수첨부파일관리
|
||||
|
||||
## 1. 기본 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | ---------------------------------------------- |
|
||||
| 버전 | 0.1 |
|
||||
| 프로세스명 | UI설계 |
|
||||
| 화면명 | 필수첨부파일관리 |
|
||||
| 화면 유형 | [v] 조회 [v] 입력 [v] 수정 [v] 삭제 [ ] 출력 |
|
||||
| 메뉴 경로 | 디지털행정지원 > 사이트관리 > 필수첨부파일관리 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 화면 목적
|
||||
|
||||
문서(업무) 구분별로 **필수 첨부파일** 항목을 등록·조회·수정·삭제한다. 상단 검색 영역에서 **문서구분**으로 목록을 필터링하고, **등록** 또는 행별 **수정**·**삭제**로 마스터 데이터를 유지한다. 등록·수정 시 **필수첨부파일아이디**는 클라이언트에서 입력(또는 생성)하여 요청 본문에 포함한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 화면 구성
|
||||
|
||||
### 3-1. 전체 레이아웃
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 페이지 타이틀: 필수첨부파일관리 브레드크럼: 디지털행정지원 > … > │
|
||||
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ [영역 A] 검색 / 액션 │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 문서구분 [전체 ▼] [조회] [등록] │ │
|
||||
│ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
|
||||
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ [영역 B] 필수첨부파일 목록 │
|
||||
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 필수첨부파일아이디 | 문서구분 | 필수첨부파일명 | 필수첨부여부 | 필수파일검토내용 | 비고 | 관리 │ │
|
||||
│ ├────────────────────────────────────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ EAF-0001 | 설치인가 | 사업계획서 | 예 | 사업비 내역 검토 | 서명본 첨부 | [수정][삭제] │ │
|
||||
│ │ EAF-0002 | 기본계획 | 변경사유서 | 예 | 변경 전후 비교표 | — | [수정][삭제] │ │
|
||||
│ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
(모달) [다이얼로그 C] 필수첨부파일 등록 / 수정
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ 필수첨부파일 등록 [닫기] │
|
||||
├──────────────────────────────────────────────────────┤
|
||||
│ 필수첨부파일아이디(자동발급) [EAF-0004] │
|
||||
│ 문서구분 [설치인가 ▼] │
|
||||
│ 필수첨부파일명 [예: 사업계획서] │
|
||||
│ 양식파일 [파일 선택] │
|
||||
│ 필수첨부여부 [ ] 예 [ ] 아니오 │
|
||||
│ 필수파일검토내용 [검토내용을 입력하세요]│
|
||||
│ 비고 [비고를 입력하세요] │
|
||||
├──────────────────────────────────────────────────────┤
|
||||
│ [취소] [저장] │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-2. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입
|
||||
CALL 필수첨부파일 목록 조회 (findPage)
|
||||
DISPLAY 필수첨부파일 그리드 (영역 B)
|
||||
|
||||
// 영역 A: 검색
|
||||
ON [조회] 버튼 CLICK DO
|
||||
CALL 필수첨부파일 목록 조회 (문서구분 = 선택값, findPage)
|
||||
DISPLAY 필수첨부파일 그리드 (영역 B)
|
||||
END ON
|
||||
|
||||
// 영역 A: 등록
|
||||
ON [등록] 버튼 CLICK DO
|
||||
OPEN 필수첨부파일 등록 다이얼로그 (다이얼로그 C)
|
||||
ON [저장] DO
|
||||
CONFIRM "등록하시겠습니까?"
|
||||
VALIDATE 문서구분, 필수첨부파일명, 필수첨부여부
|
||||
CALL 필수첨부파일 등록 (create)
|
||||
CALL 필수첨부파일 목록 조회
|
||||
CLOSE 다이얼로그
|
||||
TOAST "저장되었습니다."
|
||||
END ON
|
||||
ON [취소] / [닫기] DO
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 B: 수정
|
||||
ON 행 [수정] CLICK DO
|
||||
OPEN 필수첨부파일 수정 다이얼로그 (기존 값 초기화)
|
||||
ON [저장] DO
|
||||
VALIDATE 문서구분, 필수첨부파일명, 필수첨부여부
|
||||
CALL 필수첨부파일 수정 (update)
|
||||
CALL 필수첨부파일 목록 조회
|
||||
CLOSE 다이얼로그
|
||||
END ON
|
||||
END ON
|
||||
|
||||
// 영역 B: 삭제
|
||||
ON 행 [삭제] CLICK DO
|
||||
CONFIRM "삭제하시겠습니까?"
|
||||
CALL 필수첨부파일 삭제 (remove)
|
||||
CALL 필수첨부파일 목록 조회
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 영역 A: 검색 / 액션
|
||||
|
||||
문서구분 조건으로 목록을 조회하고, 신규 등록 다이얼로그를 연다.
|
||||
|
||||
### 4-1. 검색 필드
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| -------- | ---------- | ---- | ------ | ----------------- | ------------------------------ |
|
||||
| 문서구분 | CodeSelect | N | 전체 | `docSeComCd?` | "전체" 선택 시 파라미터 미전송 |
|
||||
|
||||
### 4-2. 버튼
|
||||
|
||||
| 버튼명 | 위치 | 동작 |
|
||||
| ------ | -------------- | ----------------------------------------------- |
|
||||
| 조회 | 검색 필드 우측 | 현재 검색 조건으로 영역 B 목록 갱신 |
|
||||
| 등록 | 영역 우측 끝 | 필수첨부파일 등록 다이얼로그(다이얼로그 C) 오픈 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 영역 B: 필수첨부파일 목록
|
||||
|
||||
필수 첨부파일 마스터를 테이블로 표시한다. 페이지네이션 UI 적용.
|
||||
|
||||
### 5-1. 헤더
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ----------------- |
|
||||
| 섹션 타이틀 | 필수첨부파일 목록 |
|
||||
|
||||
### 5-2. 그리드 컬럼
|
||||
|
||||
| 컬럼명 | Field | 타입 | 비고 |
|
||||
| ------------------ | -------------------- | ------ | ------------------------------------- |
|
||||
| 필수첨부파일아이디 | `esntlAtchFileId` | string | 예: `EAF-0001`, 클라이언트 생성/입력 |
|
||||
| 문서구분 | `docSeComCd` | string | 코드명 표시 — 공통코드 (TBD 상위코드) |
|
||||
| 필수첨부파일명 | `esntlAtchFileNm` | string | |
|
||||
| 필수첨부여부 | `esntlAtchYn` | string | `Y`→예, `N`→아니오 |
|
||||
| 필수파일검토내용 | `esntlAtchFileRvwCn` | string | 없으면 `—` 표시, 최대 2줄 clamp |
|
||||
| 비고 | `esntlAtchFileRmrk` | string | 없으면 `—` 표시 |
|
||||
| 양식 내려받기 | `atchFileGroupId` | string | 양식파일 다운로드 버튼 |
|
||||
| 관리 | — | — | 행별 **[수정] · [삭제]** |
|
||||
|
||||
- 행 클릭 시 별도 상세 화면 없음. 편집은 **[수정]** 버튼으로 다이얼로그 C를 연다.
|
||||
|
||||
### 5-3. 버튼
|
||||
|
||||
| 버튼명 | 위치 | 동작 |
|
||||
| ------ | ---- | -------------------------------------- |
|
||||
| 수정 | 행별 | 필수첨부파일 수정 다이얼로그 (기존 값) |
|
||||
| 삭제 | 행별 | 확인 후 삭제 API 호출 → 목록 갱신 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 다이얼로그 C: 필수첨부파일 등록 / 수정
|
||||
|
||||
등록·수정 공용 폼 다이얼로그. 등록 시 제목 **「필수첨부파일 등록」**, 수정 시 **「필수첨부파일 수정」**.
|
||||
|
||||
### 6-1. 폼 필드
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| ------------------ | ------------------- | ---- | ------ | -------------------- | ---------------------------------- |
|
||||
| 필수첨부파일아이디 | (Readonly) | Y | — | `esntlAtchFileId` | 등록 시 미노출 |
|
||||
| 문서구분 | CodeSelect | Y | — | `docSeComCd` | 예: 설치인가, 기본계획 |
|
||||
| 필수첨부파일명 | Text | Y | — | `esntlAtchFileNm` | placeholder: "예: 사업계획서" |
|
||||
| 양식파일 | AttachmentFileField | N | — | `atchFileGroupId` | TUS 파일 업로드 |
|
||||
| 필수첨부여부 | RadioGroup | Y | Y | `esntlAtchYn` | Y/N, UI 표시: 예/아니오 |
|
||||
| 필수파일검토내용 | Textarea | N | — | `esntlAtchFileRvwCn` | placeholder: "검토내용을 입력하세요"|
|
||||
| 비고 | Textarea | N | — | `esntlAtchFileRmrk` | placeholder: "비고를 입력하세요" |
|
||||
|
||||
### 6-2. 버튼
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | -------------------------------------- |
|
||||
| 저장 | POST(등록) 또는 PUT(수정) 후 목록 갱신 |
|
||||
| 취소 | 다이얼로그 닫기, 입력값 폐기 |
|
||||
| 닫기 | 다이얼로그 닫기 (헤더 우측) |
|
||||
|
||||
---
|
||||
|
||||
## 7. API/DTO 명세
|
||||
|
||||
### 7-1. 공통
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | ----------------------------------------------------- |
|
||||
| 서비스 | AS Common Service |
|
||||
| Base prefix | `/as-service/api/v1/esntl-atch-file` |
|
||||
| 인증 | JWT (`Authorization`), `X-Site-Id` 등 |
|
||||
| 페이징 | Spring `Pageable` 사용 (`page`, `size`, `sort`) |
|
||||
| 엔티티 | `@/entities/esntl` (`esntl-service.ts`, `queries.ts`) |
|
||||
|
||||
### 7-2. 필수첨부파일 API
|
||||
|
||||
| 기능 | Method | URL | Request DTO | Response DTO | API (클라이언트 함수명) |
|
||||
| --------- | ------ | -------------------- | ----------------------------- | ----------------------------------- | ----------------------- |
|
||||
| 트리 조회 | GET | `/list/tree` | Query: `docSeComCd`(필수) | `EsntlAtchFileMngTreeResponseDto[]` | `findTree` |
|
||||
| 목록 조회 | GET | `/` | Query: Search + Pageable | `PageResponse<EsntlAtchFileMng>` | `findPage` |
|
||||
| 단건 조회 | GET | `/{esntlAtchFileId}` | Path: `esntlAtchFileId` | `EsntlAtchFileMng` | `findById` |
|
||||
| 등록 | POST | `/` | `EsntlAtchFileMngSaveRequest` | `string` (생성된 ID) | `create` |
|
||||
| 수정 | PUT | `/{esntlAtchFileId}` | `EsntlAtchFileMngSaveRequest` | `string` (수정된 ID) | `update` |
|
||||
| 삭제 | DELETE | `/{esntlAtchFileId}` | Path: `esntlAtchFileId` | `string` (삭제된 ID) | `remove` |
|
||||
|
||||
**응답 DTO**
|
||||
|
||||
| Field | 타입 | 설명 |
|
||||
| -------------------- | -------------------------- | -------------------------------- |
|
||||
| `esntlAtchFileId` | string | 필수첨부파일아이디 |
|
||||
| `docSeComCd` | string | 문서구분공통코드 |
|
||||
| `esntlAtchFileNm` | string | 필수첨부파일명 |
|
||||
| `esntlAtchYn` | string | 필수첨부여부 (Y/N) |
|
||||
| `esntlAtchFileRvwCn` | string? | 필수첨부파일검토내용 |
|
||||
| `esntlAtchFileRmrk` | string? | 필수첨부파일비고 |
|
||||
| `atchFileGroupId` | string? | 첨부파일그룹아이디 (양식파일) |
|
||||
| `atchFileList` | AtflMngClientResponseDto[]?| 첨부파일 목록 |
|
||||
| `rgtr` | string? | 등록자 UUID |
|
||||
| `rgtrNm` | string? | 등록자명 |
|
||||
| `mdfr` | string? | 수정자 UUID |
|
||||
| `regDt` | string? | 등록일시 (`yyyy-MM-dd HH:mm:ss`) |
|
||||
| `mdfcnDt` | string? | 수정일시 |
|
||||
|
||||
**저장 Request**
|
||||
|
||||
| Field | 필수 | 설명 |
|
||||
| -------------------- | ---- | -------------------- |
|
||||
| `docSeComCd` | Y | 문서구분 |
|
||||
| `esntlAtchFileNm` | N | 필수첨부파일명 |
|
||||
| `esntlAtchYn` | N | 필수첨부여부 |
|
||||
| `esntlAtchFileRvwCn` | N | 필수첨부파일검토내용 |
|
||||
| `esntlAtchFileRmrk` | N | 비고 |
|
||||
| `atchFileGroupId` | N | 첨부파일그룹아이디 |
|
||||
|
||||
**검색 Query**
|
||||
|
||||
| Field | 필수 | 설명 |
|
||||
| ----------------- | ---- | ----------------------------- |
|
||||
| `docSeComCd` | N | 문서구분 (전체 시 미전송) |
|
||||
| `esntlAtchFileNm` | N | 필수첨부파일명 부분/일치 검색 |
|
||||
| `esntlAtchYn` | N | 필수첨부여부 (`Y`/`N`) |
|
||||
| `page` | N | 페이지 번호 (0-base) |
|
||||
| `size` | N | 페이지 크기 (기본값: 100) |
|
||||
| `sort` | N | 정렬 조건 (예: `regDt,desc`) |
|
||||
|
||||
### 7-3. 공통코드
|
||||
|
||||
| UI 필드 | 코드 그룹 | 예시 값 |
|
||||
| ------------ | --------- | ------------------ |
|
||||
| 문서구분 | ASDOCSECD | 설치인가, 기본계획 |
|
||||
| 필수첨부여부 | 고정 | Y(예), N(아니오) |
|
||||
|
||||
---
|
||||
|
||||
## 8. UI 구현 가이드
|
||||
|
||||
### 8-1. 기술 스택·원칙
|
||||
|
||||
- **공통 컴포넌트**: `@common/components` (`Dialog`, `Button`, `Input`, `Select`, `Textarea`, `Label` 등)
|
||||
- **테이블**: `@tanstack/react-table` + `useDataTable`
|
||||
- **폼**: `react-hook-form`
|
||||
- **데이터**: React Query — `@/entities/esntl/api/queries.ts` 훅 사용
|
||||
- **공통코드**: `@/entities/code` — `CodeSelect`, `findCodeLabel`
|
||||
- **확인**: `@frontend-opensource/use-react-hooks` — `useConfirm` (등록·삭제 확인)
|
||||
|
||||
### 8-2. 모듈·파일 배치
|
||||
|
||||
| 구분 | 경로 |
|
||||
| ------ | ---------------------------------------------------------------------------------------------------- |
|
||||
| 라우트 | `apps/as/app/(with-base-layout)/esntl-atch-file-mng/page.tsx` |
|
||||
| 페이지 | `apps/as/src/pages/esntl-atch-file-mng/` (Public API: page만 export) |
|
||||
| UI | `.../ui/esntl-atch-file-mng-page.tsx`, `esntl-atch-file-list.tsx`, `esntl-atch-file-form-dialog.tsx` |
|
||||
| model | `.../model/esntl-atch-file-columns.tsx`, `esntl-atch-file-search-params.ts` |
|
||||
| 엔티티 | `apps/as/src/entities/esntl/` (`esntl-service.ts`, `queries.ts`, `esntl-interface.ts`) |
|
||||
| 문서 | `apps/as/docs/essential-attachment-file-management/SPEC.md` |
|
||||
|
||||
### 8-3. 데이터 흐름(요약)
|
||||
|
||||
- **진입**: 검색 params 기본값(`docSeComCd` = 전체) → 목록 query → 영역 B DataTable.
|
||||
- **조회**: [조회] 클릭 시 search state 반영 → 목록 query refetch.
|
||||
- **등록**: [등록] → Dialog `mode=create` → [저장] → POST → 목록 invalidate.
|
||||
- **수정**: [수정] → Dialog `mode=edit` + row 초기값 → [저장] → PUT → 목록 invalidate.
|
||||
- **삭제**: confirm → DELETE → 목록 invalidate.
|
||||
@@ -1,285 +0,0 @@
|
||||
# 화면설계서: 내 행정지원
|
||||
|
||||
## 1. 기본 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ---------- | -------------------------------------------- |
|
||||
| 버전 | 1.0 |
|
||||
| 프로세스명 | UI설계 |
|
||||
| 화면명 | 내 행정지원 |
|
||||
| 화면 ID | AS_SC0204011 |
|
||||
| 화면 유형 | [v] 조회 [ ] 입력 [ ] 수정 [ ] 삭제 [ ] 출력 |
|
||||
| 메뉴 경로 | 메인 > 행정지원서비스 > 내 행정지원 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 화면 목적
|
||||
|
||||
로그인한 사용자가 **본인이 신청한 행정지원 문서**를 기간·구분·진행상태로 조회한다. 목록에서 행을 선택하면 해당 문서 상세 화면으로 이동한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. 화면 구성
|
||||
|
||||
### 3-1. 전체 레이아웃
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 브레드크럼: 메인 > 행정지원서비스 > 내 행정지원 │
|
||||
│ 페이지 타이틀: 내 행정지원 │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ [영역 A] 검색 필터 │
|
||||
│ 기간 [시작일] ~ [종료일] 구분 ▼ 진행상태 ▼ [검색] │
|
||||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ [영역 B] 내 신청 목록 │
|
||||
│ 타이틀: 내 신청 목록 N개 │
|
||||
│ ┌────┬──────┬────────┬──────────────┬────────────┬────────┬──────────────┐ │
|
||||
│ │ No │ 구분 │ 신청일 │ 진행상태 │ 완료(예정)일│ 담당자 │ 담당자연락처 │ │
|
||||
│ ├────┼──────┼────────┼──────────────┼────────────┼────────┼──────────────┤ │
|
||||
│ │ … │ … │ … │ prgrsSttsComNm│ … │ … │ … │ │
|
||||
│ └────┴──────┴────────┴──────────────┴────────────┴────────┴──────────────┘ │
|
||||
│ [페이지네이션] │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3-2. 화면 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입
|
||||
// 기간 기본값: 오늘 기준 최근 1개월 (startDate = today-1M, endDate = today)
|
||||
CALL findMyElaperDocList(ElaprMyDocSearchDto + pageable)
|
||||
DISPLAY 내 신청 목록 그리드 (영역 B)
|
||||
|
||||
ON [검색] 버튼 CLICK DO
|
||||
CALL findMyElaperDocList(영역 A 조건 + page=0)
|
||||
DISPLAY 내 신청 목록 그리드 (영역 B)
|
||||
END ON
|
||||
|
||||
ON 페이지네이션 CHANGE DO
|
||||
CALL findMyElaperDocList(영역 A 조건 + page/size)
|
||||
DISPLAY 내 신청 목록 그리드 (영역 B)
|
||||
END ON
|
||||
|
||||
ON 영역 B 행 CLICK DO
|
||||
// docSeComCd·prgrsSttsComCd·rgtr → view/edit
|
||||
NAVIGATE 문서 상세 또는 수정 화면
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 영역 A — 검색 필터
|
||||
|
||||
구성: **기간 · 구분 · 진행상태** (+ 검색).
|
||||
|
||||
> UI설계 상세설명의 `docSecs` / `docStatusCd`는 레거시·설계 문서 명칭이다.
|
||||
> **API SoT**는 `ElaprMyDocSearchDto`의 `docSeComCd` / `prgrsSttsComCd`를 사용한다.
|
||||
|
||||
### 4-1. 필드 정의
|
||||
|
||||
| 표시명 | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑 | 비고 |
|
||||
| ---------- | ---------------- | ---- | --------------------------- | ----------------- | --------------------------------------------------------------------- |
|
||||
| 기간(시작) | DatePicker | N | 오늘 − 1개월 (`YYYY-MM-DD`) | `startDate` | 신청일(`reqDt`) 기준 검색으로 가정 |
|
||||
| 기간(종료) | DatePicker | N | 오늘 (`YYYY-MM-DD`) | `endDate` | |
|
||||
| 구분 | Select(공통코드) | N | 전체(미선택) | `docSeComCd` | 상위코드 `ASDOCSE`. UI설계 `docSecs` → API `docSeComCd` |
|
||||
| 진행상태 | Select(공통코드) | N | 전체(미선택) | `prgrsSttsComCd` | 상위코드 = `{docSeComCd}STTS` (예: `INSTL` → `INSTLSTTS`). UI설계 `docStatusCd` → API 필드명 |
|
||||
|
||||
### 4-2. 버튼
|
||||
|
||||
| 버튼명 | 동작 |
|
||||
| ------ | ----------------------------------------------------------------- |
|
||||
| 검색 | 영역 A 조건으로 `findMyElaperDocList` 호출 → 영역 B 갱신 (page=0) |
|
||||
|
||||
### 4-3. 콤보 의존
|
||||
|
||||
| 트리거 | 동작 |
|
||||
| ----------- | ------------------------------------------------------------------- |
|
||||
| 구분 변경 | 진행상태 옵션을 `upCd = docSeComCd + "STTS"`로 재조회. 진행상태 선택값 RESET |
|
||||
| 구분 미선택 | 진행상태 비활성(옵션 비움). `upCd` 조합 불가이므로 조회하지 않음 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 영역 B — 내 신청 목록
|
||||
|
||||
### 5-1. 그리드 컬럼
|
||||
|
||||
| 표시명 | Field | 비고 |
|
||||
| ------------ | ---------------- | ------------------------------------------------- |
|
||||
| No | (row index) | 페이지 오프셋 반영 |
|
||||
| 구분 | `docSeComNm` | 코드 `docSeComCd` (`ASDOCSE`) |
|
||||
| 신청일 | `reqDt` | 표시 `YYYY-MM-DD` (응답은 `yyyy-MM-dd HH:mm:ss`) |
|
||||
| 진행상태 | `prgrsSttsComNm` | 텍스트 렌더링 (단계형 프로그레스 미사용) |
|
||||
| 완료(예정)일 | `cmptnExpctDt` | 표시 `YYYY-MM-DD` |
|
||||
| 담당자 | `picNm` | |
|
||||
| 담당자연락처 | `picTelno` | |
|
||||
|
||||
응답에 있으나 그리드에 **표시하지 않음**:
|
||||
|
||||
| Field | 비고 |
|
||||
| ---------------- | ----------------------------------------------------------------- |
|
||||
| `docNo` | 문서번호 — 행 클릭 라우팅 키 |
|
||||
| `docTtl` | 문서명/사업명 — 미표시 |
|
||||
| `chgCycl` | 변경차수 — 그리드 미표시. SEWER 이동 시 query 파라미터로 사용 |
|
||||
| `prgrsSttsComCd` | 진행상태 코드 — 컬럼 표시는 `prgrsSttsComNm` |
|
||||
| `rgtr` | 등록자 UUID — edit 판정용 (`rgtr === userUnqId`) |
|
||||
|
||||
### 5-2. 목록 메타·페이지네이션
|
||||
|
||||
| 항목 | 매핑 |
|
||||
| ------------- | ------------------------------------------- |
|
||||
| 건수 `N개` | `PageResponse.totalElements` |
|
||||
| page / size | `ElaprMyDocSearchDto`의 `PageableParams` |
|
||||
| 페이지 컨트롤 | Spring `Page` 표준 (`number`, `totalPages`) |
|
||||
|
||||
### 5-3. 행 상호작용
|
||||
|
||||
| 동작 | 설명 |
|
||||
| ------- | -------------------------------------------------------------------------------------------- |
|
||||
| 행 클릭 | `docSeComCd`·`prgrsSttsComCd`·`rgtr`로 view/edit 분기 후 이동 (`resolveMyPbadmsSprtDetailPath`) |
|
||||
|
||||
**edit 조건** (기존 도메인 목록과 동일):
|
||||
|
||||
| `docSeComCd` | edit 조건 |
|
||||
| ------------------------ | ---------------------------------------------------------------------- |
|
||||
| `INSTL` / `FNRS` / `SEWER` | `(prgrsSttsComCd === "SV" \|\| "SL") && rgtr === loggedInUserUnqId` |
|
||||
| `CNFM` | `prgrsSttsComCd === "CV" && rgtr === loggedInUserUnqId` |
|
||||
|
||||
| `docSeComCd` | edit 경로 | view 경로 |
|
||||
| ------------ | -------------------------------------------- | --------------------------------------- |
|
||||
| `FNRS` | `/fnrs-cnsltn/{docNo}/edit` | `/fnrs-cnsltn/{docNo}` |
|
||||
| `INSTL` | `/instl-sncn/{docNo}/edit` | `/instl-sncn/{docNo}` |
|
||||
| `CNFM` | `/design-cnstn/{docNo}/edit` | `/design-cnstn/{docNo}` |
|
||||
| `SEWER` | `/sewer-bsc-plan/{docNo}/edit?chgCycl={n}` | `/sewer-bsc-plan/{docNo}?chgCycl={n}` |
|
||||
| 그 외 | 이동하지 않음 | |
|
||||
|
||||
- SEWER `chgCycl`: `row.chgCycl ?? 1`
|
||||
- 조건 불충족 시 항상 view
|
||||
|
||||
---
|
||||
|
||||
## 6. API/DTO 명세
|
||||
|
||||
### 6-1. 공통
|
||||
|
||||
| 항목 | 값 |
|
||||
| --------------- | ------------------------------------------------------------------------------------------ |
|
||||
| Base prefix | `/as-elapr-service/api/v1/elapr-prgrs-stts` (`ENDPOINT.AS_ELAPR_SERVICE.ELAPR_PRGRS_STTS`) |
|
||||
| 인증 | 로그인 사용자 UUID — 서버 `SecurityUtils.getLoggedInUserUnqIdUUID()` (클라이언트 미전달) |
|
||||
| 클라이언트 모듈 | `@/entities/elapr` — `elaprPrgrsSttsService` / `useElaprPrgrsSttsMyDocPage` |
|
||||
|
||||
### 6-2. 내 행정지원 목록 — `findMyElaperDocList`
|
||||
|
||||
| 기능 | Method | URL | Request DTO | Response DTO | API |
|
||||
| ----------------- | ------ | --------------- | --------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------- |
|
||||
| 내 신청 목록 조회 | GET | `{BASE}/my/doc` | Query: `ElaprMyDocSearchDto` + Pageable | `PageResponse<MyAdssDocResponseDto>` | `elaprPrgrsSttsService.findMyElaperDocList` / `useElaprPrgrsSttsMyDocPage` |
|
||||
|
||||
**Request (`ElaprMyDocSearchDto` + Pageable)**
|
||||
|
||||
| 필드 | 필수 | 설명 |
|
||||
| ------------------------ | ---- | ------------------------------------------------------------ |
|
||||
| `startDate` | N | 검색 시작일 `YYYY-MM-DD` |
|
||||
| `endDate` | N | 검색 종료일 `YYYY-MM-DD` |
|
||||
| `docSeComCd` | N | 문서구분 (`INSTL` / `FNRS` / `DESIGN` / `SEWER` / `PWRK` 등) |
|
||||
| `prgrsSttsComCd` | N | 문서진행상태공통코드 |
|
||||
| `page` / `size` / `sort` | N | Spring Pageable |
|
||||
|
||||
**Response (`MyAdssDocResponseDto`)**
|
||||
|
||||
| 필드 | 타입 | 설명 |
|
||||
| ---------------- | ------- | ------------------------------------------- |
|
||||
| `docNo` | string | 문서번호 |
|
||||
| `docTtl` | string? | 문서명/사업명 |
|
||||
| `docSeComCd` | string? | 문서구분 코드 |
|
||||
| `docSeComNm` | string? | 문서구분 코드명 (`ASDOCSE`) |
|
||||
| `reqDt` | string? | 신청일시 `yyyy-MM-dd HH:mm:ss` |
|
||||
| `prgrsSttsComCd` | string? | 문서진행상태 코드 |
|
||||
| `prgrsSttsComNm` | string? | 문서진행상태 코드명 |
|
||||
| `cmptnExpctDt` | string? | 완료(예정)일 `yyyy-MM-dd` |
|
||||
| `picNm` | string? | 담당자 성명 |
|
||||
| `picTelno` | string? | 담당자 연락처 |
|
||||
| `chgCycl` | number? | 변경차수 |
|
||||
| `rgtr` | string? | 등록자 UUID |
|
||||
|
||||
### 6-3. 공통코드 (콤보)
|
||||
|
||||
| 용도 | 상위코드 | API | 비고 |
|
||||
| -------- | ------------ | --------------------------- | ----------------------------- |
|
||||
| 구분 | `ASDOCSE` | `useCodeList("ASDOCSE")` 등 | 기존 관리 화면과 동일 |
|
||||
| 진행상태 | `{docSeComCd}STTS` | `useCodeList(docSeComCd + "STTS")` | 예: `INSTLSTTS`, `FNRSSTTS`, `SEWERSTTS`. 구분 미선택 시 미호출 |
|
||||
|
||||
---
|
||||
|
||||
## 7. UI 구현 가이드
|
||||
|
||||
### 7-1. 기술 스택·원칙
|
||||
|
||||
- UI: `@common/components` — DatePicker, Select/`CodeSelect`, Button, DataTable, Pagination
|
||||
- 목록: `@tanstack/react-table` + `useDataTable` (기존 `instl-list` / `fnrs-list` 패턴)
|
||||
- 데이터: React Query `useElaprPrgrsSttsMyDocPage(params)`
|
||||
- 검색 조건·페이지: URL `searchParams` 동기화 권장 (`useSearchParamsState` 스킬)
|
||||
- 진행상태 컬럼: `prgrsSttsComNm` 텍스트 렌더링 (단계형 프로그레스 미사용)
|
||||
- 행 클릭: `docSeComCd` + `prgrsSttsComCd` + `rgtr`로 view/edit 분기 (`SEWER`는 `chgCycl` query 포함)
|
||||
|
||||
### 7-2. 앱·파일 배치
|
||||
|
||||
| 구분 | 경로 |
|
||||
| ------------ | -------------------------------------------------------------- |
|
||||
| 라우트 | `app/(main)/(with-base-layout)/my-pbadms-sprt/page.tsx` |
|
||||
| 페이지 | `pages/my-pbadms-sprt/ui/my-pbadms-sprt-list-page.tsx` |
|
||||
| 목록 그리드 | `pages/my-pbadms-sprt/ui/my-pbadms-sprt-list.tsx` |
|
||||
| 경로 해석 | `pages/my-pbadms-sprt/lib/resolve-detail-path.ts` |
|
||||
| 테이블 컬럼 | `pages/my-pbadms-sprt/model/my-pbadms-sprt-table-columns.tsx` |
|
||||
| Entity API | `entities/elapr/api/elapr-prgrs-stts-service.ts` |
|
||||
| Entity Hook | `entities/elapr/api/queries.ts` → `useElaprPrgrsSttsMyDocPage` |
|
||||
| Entity Model | `entities/elapr/model/elapr-prgrs-stts-interface.ts` |
|
||||
|
||||
### 7-3. 영역별 UI 매핑
|
||||
|
||||
| 영역 | 컴포넌트 | 데이터 |
|
||||
| ---- | -------------------------- | ------------------------------------------ |
|
||||
| A | `my-pbadms-sprt-list-page` | 로컬 state → `ElaprMyDocSearchDto` |
|
||||
| B | DataTable + columns | `useElaprPrgrsSttsMyDocPage` → `content[]` |
|
||||
|
||||
### 7-4. 다이얼로그·라우팅
|
||||
|
||||
| 항목 | 내용 |
|
||||
| ----------- | -------------------------------------------------------------------- |
|
||||
| 다이얼로그 | 없음 (목록 전용) |
|
||||
| 목록 라우트 | `/my-pbadms-sprt` |
|
||||
| 상세 이동 | §5-3 표와 동일 (view/edit + `rgtr` 소유자 검사, SEWER `chgCycl`) |
|
||||
|
||||
### 7-5. 데이터 흐름
|
||||
|
||||
```
|
||||
BEGIN
|
||||
|
||||
// 최초 진입
|
||||
SET 기간 = 최근 1개월
|
||||
CALL findMyElaperDocList
|
||||
DISPLAY 영역 B
|
||||
|
||||
ON [검색] CLICK DO
|
||||
CALL findMyElaperDocList // → 영역 B 갱신
|
||||
END ON
|
||||
|
||||
ON 페이지 CHANGE DO
|
||||
CALL findMyElaperDocList
|
||||
END ON
|
||||
|
||||
ON 영역 B 행 CLICK DO
|
||||
IF NOT docNo OR unsupported docSeComCd THEN
|
||||
// no-op
|
||||
ELSE IF canEdit(prgrsSttsComCd, rgtr === userUnqId) THEN
|
||||
NAVIGATE edit 경로 // SEWER면 ?chgCycl=
|
||||
ELSE
|
||||
NAVIGATE view 경로
|
||||
END IF
|
||||
END ON
|
||||
|
||||
END
|
||||
```
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user