ONAANDALL/frontend
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

merge전 md 파일 삭제

Browse Source
This commit is contained in:
kiminchan
2026-04-27 16:42:47 +09:00
parent 9d573e6ad1
commit 3293893b7f
35 changed files with 0 additions and 1903 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/sn/app/(map-layout)/map/aged-pipe-popup/page.tsx → apps/sn/app/(map-layout)/map/agedPipePopup/page.tsx
View File
apps/sn/docs/AI코딩하네스/개요.md
-41
View File
@@ -1,41 +0,0 @@
# sn 2차사업 하네스 운영 문서
## 목적
이 문서는 하수관로 운영관리 시스템 `sn` 프론트엔드 2차사업 작업을 기능 단위로 안전하게 진행하기 위한 경량 하네스 기준이다.
AI_SAM `refactoring` 브랜치의 하네스 운영 방식 중 우리 프로젝트에 필요한 부분만 수용한다.
- 작업카드로 범위와 검증 방법을 먼저 고정한다.
- 실행 기록을 남겨 중간에 작업자가 바뀌어도 이어서 진행할 수 있게 한다.
- `sn` 앱과 허용된 공통 비즈니스 컴포넌트 범위를 벗어나는 수정을 방지한다.
- 백엔드 API 계약과 화면 설계 근거를 연결해서 브라우저 검증까지 추적한다.
## 적용 범위
- 확인됨: `apps/sn/**`은 이번 작업의 주 프론트엔드 범위이다. 근거: `apps/sn/AGENTS.md`
- 확인됨: `packages/common/business_components/**`만 수정 가능한 공통 비즈니스 컴포넌트 범위이다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 그 외 앱과 공통 패키지는 기본적으로 읽기/분석 대상이며 직접 수정하지 않는다. 근거: `apps/sn/AGENTS.md`
- 추정: 기능 구현 시 백엔드 `sewerage-service` API와 함께 브라우저 동작을 확인해야 한다. 근거: `apps/sn/AGENTS.md`
## 문서 구조
- `작업목록.md`: 2차사업 프론트엔드 작업 목록과 상태
- `기준문서/`: 프로젝트, 화면, API, 컴포넌트, 상태관리, 검증 기준
- `작업계획/`: 작업카드 템플릿과 기능별 실행 계획
- `보고/`: 일자별 작업 결과, 이슈, 제안, 개선 기록
## 멀티에이전트 기준
- `sn` 작업에서 BE/FE/QA 역할 분리와 합류 기준은 `기준문서/007-멀티에이전트운영.md`를 따른다.
- 백엔드 API, DB, 서비스 흐름과 함께 작업하는 경우 백엔드 기준문서 `D:\workspace\IIPBS\sewerage-service\docs\AI코딩하네스\기준문서\009-멀티에이전트운영.md`도 함께 확인한다.
## 운영 원칙
- 기능 단위로 작업카드를 먼저 작성한다.
- 수정 전 영향 범위와 롤백 방법을 문서에 남긴다.
- API 계약 변경이 필요한 경우 프론트에서 임의로 처리하지 않고 백엔드 작업으로 분리한다.
- `packages/common/business_components` 수정은 `sn` 화면에서 실제로 재사용되는 범위로 제한한다.
- 브라우저 테스트가 필요한 작업은 URL, 사용자 조작, 기대 결과를 함께 기록한다.
## 사용 순서
1. `기준문서/` 문서에서 현재 기준을 확인한다.
2. `작업목록.md`에서 작업 상태를 확인한다.
3. `작업계획/000-작업카드-템플릿.md`를 복사해 기능별 계획을 작성한다.
4. 구현 또는 수정 후 `보고/YYYY-MM-DD/`에 결과를 기록한다.
5. 외부 범위 이슈는 `이슈.md`, 개선 제안은 `제안.md`, 반복 개선점은 `개선사항.md`에 남긴다.
apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md
-62
View File
@@ -1,62 +0,0 @@
# 노후관로관리 브라우저 수동 검증 체크리스트 및 네트워크 증적 양식
## 1. 대상 화면
- 화면명: 노후관로정비사업 / 노후관로관리
- 우선 검증 라우트: `/oper/oldPp`
- 관련 구현: `apps/sn/app/(with-base-layout)/oper/oldPp/page.tsx`
- 관련 BE API: `GET /sewerage-service/api/v1/dcrpPpl`
- 관련 요구사항 근거: `apps/sn/app/html/06. 노후관로관리_시나리오_v1.0.md`
## 2. 사전 조건
| 항목 | 값 |
| --- | --- |
| 검증 일시 | |
| 검증자 | |
| 브라우저 | Chrome / Edge |
| FE URL | |
| BE URL | |
| 로그인 계정/권한 | |
| 테스트 데이터 기준 | |
## 3. 수동 검증 체크리스트
| 번호 | 단계 | 조작 | 기대 결과 | 결과 | 증적 |
| --- | --- | --- | --- | --- | --- |
| 1 | 화면 진입 | `/oper/oldPp` 또는 메뉴로 진입 | 검색 영역, 조회/등록 버튼, 목록 영역이 표시된다. | | 스크린샷 |
| 2 | 초기 조회 | 화면 로드 후 기본 조회 완료 대기 | 로딩이 종료되고 목록 또는 빈 목록이 표시된다. | | Network |
| 3 | 기간 조회 | 등록기간을 변경하고 조회 클릭 | `fromRegDt`, `toRegDt`가 Query String에 반영된다. | | Network |
| 4 | 명칭 조회 | 파일명/사업명 입력 후 Enter 또는 조회 클릭 | `dcrpPplMtncBizNm`이 Query String에 반영된다. | | Network |
| 5 | 페이지 이동 | 페이지네이션 클릭 | `page`가 변경되고 목록이 갱신된다. | | Network |
| 6 | 행 선택 | 목록 행 클릭 | 선택 행의 첨부 식별자가 상태에 반영되고 표 모달이 열린다. | | 스크린샷 |
| 7 | 데이터 없음 | 결과가 없는 조건으로 조회 | 오류 없이 빈 목록/0건 상태가 표시된다. | | 스크린샷 |
| 8 | 오류 응답 | BE 중지 또는 권한 오류 환경에서 조회 | 무한 로딩 없이 오류 로그/안내를 확인한다. | | Console/Network |
## 4. 네트워크 응답 증적 양식
| 항목 | 기록 |
| --- | --- |
| Request Name | |
| Method | `GET` |
| Request URL | `/sewerage-service/api/v1/dcrpPpl` |
| Query String | `fromRegDt=`, `toRegDt=`, `dcrpPplMtncBizNm=`, `auth=`, `page=`, `size=` |
| Status Code | |
| Response Headers 주요값 | `content-type`, `cache-control` |
| Response Body 주요 필드 | `content`, `totalElements`, `number`, `size`, `sort` |
| content 첫 행 주요 필드 | `dcrpPplMtncBizSn`, `mngYr`, `mngQu`, `atflId`, `dcrpPplMtncBizNm`, `rgtrNm` |
| 기대 결과 | Page 구조가 유지되고 JSON 파싱 오류가 없어야 한다. |
| 실제 결과 | |
| HAR/스크린샷 경로 | |
## 5. 네트워크 증적 예시
```text
GET /sewerage-service/api/v1/dcrpPpl?fromRegDt=2026-04-10&toRegDt=2026-04-17&dcrpPplMtncBizNm=&auth=<masked>&page=0&size=10
Status: 200
Response check:
- content: array
- totalElements: number
- number: 0
- size: 10
```
## 6. 이슈 기록 양식
| 번호 | 증상 | 재현 단계 | 기대 | 실제 | 우선순위 | 담당 | 링크 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | | | | | | | |
apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md
-22
View File
@@ -1,22 +0,0 @@
# 프로젝트 기준
## 프로젝트 식별
- 확인됨: 프론트엔드 저장소는 pnpm workspace와 Turborepo 기반 모노레포이다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 하수관로 운영관리 시스템 프론트엔드 작업 대상 앱은 `apps/sn`이다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 직접 수정 가능한 공통 패키지는 `packages/common/business_components`이다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 백엔드 기준 프로젝트는 `sewerage-service`이다. 근거: `apps/sn/AGENTS.md`
## 작업 목적
- 확인됨: 현재 목적은 리팩토링 전용이 아니라 하수관로 운영관리 시스템 2차사업 고도화 개발이다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 기존 `sn` 화면의 안정성을 유지하면서 2차 요구사항에 맞는 화면 개발, 기능 확장, 백엔드 연동 보완을 수행한다. 근거: `apps/sn/AGENTS.md`
## 직접 수정 허용 범위
- 확인됨: `apps/sn/**`은 직접 수정 가능하다. 근거: `apps/sn/AGENTS.md`
- 확인됨: `packages/common/business_components/**`은 직접 수정 가능하다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 위 두 경로 밖은 기본적으로 읽기 전용이며, 수정 필요성이 있으면 먼저 문제 원인과 영향 범위를 문서화한다. 근거: `apps/sn/AGENTS.md`
## 문서 기준
- 확인됨: `sn` 관련 2차사업 작업 문서는 `apps/sn/docs/` 바로 아래 주제별 한글 폴더로 관리한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: AI 코딩 하네스 작업카드는 `apps/sn/docs/AI코딩하네스/작업계획/` 하위에 둔다. 근거: `apps/sn/AGENTS.md`, `apps/sn/docs/AI코딩하네스/개요.md`
- 확인됨: `phase2` 같은 별도 단계 폴더는 신규 문서 경로로 사용하지 않는다. 근거: `apps/sn/AGENTS.md`, `apps/sn/docs/AI코딩하네스/한글경로-영향.md`
- 추정: 백엔드와 함께 진행되는 기능은 백엔드 `docs/AI코딩하네스/작업계획/` 작업카드와 프론트 `apps/sn/docs/AI코딩하네스/작업계획/` 작업카드를 서로 참조하는 방식이 안전하다. 근거: `apps/sn/AGENTS.md`, 백엔드 `AGENTS.md`
apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md
-19
View File
@@ -1,19 +0,0 @@
# 화면 기준
## 화면 분석 원칙
- 확인됨: `apps/sn` 내부 화면과 라우팅, 컴포넌트를 우선 분석한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: `apps/sn/app/html`은 퍼블리싱, 정적 HTML, 로직 검토 목적의 별도 영역으로 본다. 근거: `apps/sn/AGENTS.md`, `apps/sn/app/html/AGENTS.md`
- 확인됨: `html` 하위 요청만으로 실제 `sn` 앱 코드 전체를 함께 수정하지 않는다. 근거: `apps/sn/AGENTS.md`, `apps/sn/app/html/AGENTS.md`
## 화면 작업카드에 남길 항목
- 확인 필요: 화면명
- 확인 필요: 라우트 또는 접근 URL
- 확인 필요: 주요 사용자 조작
- 확인 필요: 조회, 등록, 수정, 삭제, 엑셀, 지도, 팝업 등 기능 구분
- 확인 필요: 호출 API
- 확인 필요: 사용 컴포넌트와 공통 비즈니스 컴포넌트 여부
- 확인 필요: 브라우저 검증 절차
## 확인 필요 항목
- 확인 필요: 2차사업 최종 화면명과 메뉴 트리는 화면설계서 기준으로 확정해야 한다. 근거: 2차사업 화면설계서
- 확인 필요: 실제 운영 메뉴 권한과 라우팅 정책은 실행 환경에서 확인해야 한다. 근거: `apps/sn` 소스, 브라우저 검증
apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md
-24
View File
@@ -1,24 +0,0 @@
# API 연동 기준
## 기본 원칙
- 확인됨: 프론트엔드는 백엔드 `sewerage-service` API와 연동한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 백엔드 응답 구조나 API 계약을 프론트엔드에서 임의로 변경했다고 가정하지 않는다. 근거: `apps/sn/AGENTS.md`
- 확인됨: API 계약 변경이 필요하면 백엔드 작업으로 분리하고 영향 범위를 먼저 정리한다. 근거: `apps/sn/AGENTS.md`
## 응답 처리 기준
- 확인됨: 백엔드 공통 응답은 `status`, `message`, `data`, `timestamp` 형태로 내려오는 API가 존재한다. 근거: 사용자 확인 응답 예시, 백엔드 `docs/응답표준화/02-백엔드응답규칙.md`
- 추정: `ResponseEntity` 적용 여부는 프론트엔드 수신 JSON 구조보다 HTTP 상태 코드와 헤더 제어에 더 직접적인 영향을 준다. 근거: 백엔드 응답 표준화 문서
- 확인 필요: 각 화면의 API 클라이언트가 공통 응답 래퍼를 어디서 해제하는지는 `apps/sn` 소스에서 화면별로 확인해야 한다. 근거: `apps/sn` 소스 분석 필요
## 작업카드에 남길 항목
- 확인 필요: HTTP method
- 확인 필요: URL
- 확인 필요: query/body 파라미터
- 확인 필요: 정상 응답 예시
- 확인 필요: 오류 응답 처리 방식
- 확인 필요: 화면에서 사용하는 `data` 경로
- 확인 필요: 로딩, 빈 결과, 권한 오류, 서버 오류 표시 방식
## 금지 기준
- 확인됨: 프론트엔드에서 백엔드 API 계약 변경을 전제로 구현하지 않는다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 백엔드 응답을 임시로 우회하기 위한 화면 전용 하드코딩을 추가하지 않는다. 근거: `apps/sn/AGENTS.md`
apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md
-22
View File
@@ -1,22 +0,0 @@
# 컴포넌트 기준
## 수정 범위
- 확인됨: `apps/sn` 내부 컴포넌트는 직접 수정 가능하다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 공통 비즈니스 컴포넌트는 `packages/common/business_components`만 직접 수정 가능하다. 근거: `apps/sn/AGENTS.md`
- 확인됨: `packages/common/components`, `packages/common/auth`, `packages/common/network` 등은 직접 수정하지 않는다. 근거: `apps/sn/AGENTS.md`
## 컴포넌트 변경 원칙
- 확인됨: `sn` 요구사항을 만족하기 위한 최소 범위로 수정한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 공통 컴포넌트 수정은 `sn`에 실제로 필요한 범위로 제한한다. 근거: `apps/sn/AGENTS.md`
- 추정: 여러 화면에서 반복되는 `sn` 전용 로직은 먼저 `apps/sn` 내부 공통화로 해결하고, 여러 업무 화면에서 공유되는 비즈니스 UI일 때만 `business_components`를 검토하는 것이 안전하다. 근거: `apps/sn/AGENTS.md`
## 작업카드에 남길 항목
- 확인 필요: 신규 또는 수정 컴포넌트 경로
- 확인 필요: 호출하는 화면 경로
- 확인 필요: props 변경 여부
- 확인 필요: 기존 화면 영향 여부
- 확인 필요: 공통 컴포넌트 수정 필요 여부
- 확인 필요: 브라우저 확인 화면
## 외부 범위 이슈
- 확인됨: 권한 밖 공통 패키지 수정이 필요해 보이면 직접 고치지 않고 문제 원인, 수정 필요 경로, `sn` 영향 범위, 타 앱 영향 가능성을 문서화한다. 근거: `apps/sn/AGENTS.md`
apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md
-19
View File
@@ -1,19 +0,0 @@
# 상태관리와 화면 흐름 기준
## 상태관리 원칙
- 확인됨: 기존 `sn` 화면 흐름과 사용자 동작을 가능한 유지하면서 2차 요구사항을 반영한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 복잡한 컴포넌트, 탭 분기, 폼 처리, 데이터 변환, 지도 연동, 공통 컴포넌트 조합 로직은 함수 또는 메서드 단위 주석을 상세히 작성한다. 근거: `apps/sn/AGENTS.md`
- 추정: 화면별 상태는 기존 패턴을 우선 따르고, 새 전역 상태 구조는 필요성이 확인된 경우에만 검토해야 한다. 근거: `apps/sn/AGENTS.md`
## 화면 흐름 기록 항목
- 확인 필요: 초기 진입 시 호출되는 API
- 확인 필요: 검색 조건 초기값
- 확인 필요: 페이지네이션 또는 무한스크롤 방식
- 확인 필요: 선택 행 또는 상세 패널 상태
- 확인 필요: 등록, 수정, 삭제 후 재조회 방식
- 확인 필요: 팝업, 모달, 지도, 파일, 엑셀 흐름
- 확인 필요: 에러 메시지 표시 위치
## 주의 사항
- 확인됨: 요구사항 근거 없는 기능 추가는 금지한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 다른 앱에서 사용하는 공통 상태 로직을 `sn` 문제 해결 목적으로 직접 바꾸지 않는다. 근거: `apps/sn/AGENTS.md`
apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md
-34
View File
@@ -1,34 +0,0 @@
# 검증 기준
## 기본 빌드 검증
- 확인됨: `sn`만 수정한 경우 아래 명령으로 로컬 빌드를 확인한다. 근거: `apps/sn/AGENTS.md`
```powershell
pnpm --filter sn run build
pnpm turbo run build --filter=sn
```
- 확인됨: `business_components`를 수정한 경우 아래 명령을 함께 확인한다. 근거: `apps/sn/AGENTS.md`
```powershell
pnpm --filter @common/business_components run build
pnpm --filter sn run build
pnpm turbo run build --filter="...[origin/main]"
```
## pre-push 기준 검증
- 확인됨: `main` 브랜치 push 전 `.husky/pre-push`에서 아래 형식의 빌드가 수행된다. 근거: `.husky/pre-push`, `apps/sn/AGENTS.md`
```powershell
git fetch origin
pnpm turbo run build --filter="...[origin/main]" --dry-run
pnpm turbo run build --filter="...[origin/main]"
```
## 브라우저 검증
- 확인됨: 백엔드 API 응답과 실제 브라우저 화면 동작을 함께 확인하는 것을 기본으로 한다. 근거: `apps/sn/AGENTS.md`
- 확인 필요: 각 기능별 URL, 로그인 계정, 권한, 테스트 데이터는 작업카드에서 확정한다. 근거: 실행 환경 확인 필요
## 검증 기록
- 확인됨: 검증 결과는 `보고/YYYY-MM-DD/결과보고.md`에 기록한다. 근거: 이 하네스 운영 문서
- 확인됨: 외부 범위 오류는 `보고/YYYY-MM-DD/이슈.md`에 기록한다. 근거: 이 하네스 운영 문서
apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md
-45
View File
@@ -1,45 +0,0 @@
# 007. 멀티에이전트 운영 기준
## 목적
- `sn` 2차사업 프론트 작업을 BE, FE, QA 역할과 안전하게 연결하기 위한 기준임
- AI_SAM `refactoring` 브랜치의 병렬 분업 구조를 참고하되, `sn` 앱과 허용된 `business_components` 범위를 우선함
## 프론트 역할 범위
| 역할 | 주 책임 | 직접 수정 가능 범위 | 직접 수정 금지 범위 |
| --- | --- | --- | --- |
| FE | 화면, 컴포넌트, 훅, 상태관리, API 호출부, 타입 | `apps/sn/**`, `packages/common/business_components/**` | 타 앱, `business_components` 외 공통 패키지, 루트 `docs/**` |
| BE | API 계약, 요청/응답 DTO, 서비스 흐름, DB 영향 | 백엔드 저장소 기준 | 프론트 저장소 직접 수정은 별도 합류 기준 필요 |
| QA | 빌드, 브라우저 조작, 네트워크 응답, 회귀 포인트 확인 | 검증 문서, 결과보고 | 기능 코드 임의 수정 |
## FE 작업 시작 입력
- 화면명과 진입 경로
- 사용자 조작 흐름
- 호출 API와 응답 필드
- `apps/sn` 수정 파일 후보
- `business_components` 수정 필요 여부
- 허용 범위 밖 수정 필요 여부
- 브라우저 검증 URL과 테스트 데이터
- 완료 조건
## BE 합류 필요 조건
- API 경로, method, 요청 파라미터, 응답 필드가 화면 요구사항과 불일치함
- 오류 응답 구조 또는 HTTP 상태 코드 처리가 화면 요구사항과 충돌함
- 저장/삭제/분석 실행이 DB 스키마 또는 데이터 보정에 의존함
- 권한, 인증, 외부 연동 기준 확인이 필요함
## QA 합류 필요 조건
- `sn` 빌드 확인 필요
- `business_components` 변경으로 타 앱 영향 가능성이 있음
- 브라우저 화면 조작 또는 네트워크 응답 확인이 완료 조건에 포함됨
- 로그인, 권한, 테스트 데이터 제약으로 수동 확인 절차가 필요함
## 병렬 작업 기준
- `apps/sn` 화면 구현과 백엔드 API 구현은 API 계약 초안이 고정된 뒤 병렬 진행 가능함
- `business_components` 변경은 `sn` 화면 요구사항을 만족하는 최소 범위로 제한함
- `@common/components`, `@common/network`, `@common/auth`, `@common/config` 문제가 원인으로 보여도 직접 수정하지 않고 이슈로 기록함
- 같은 파일은 한 역할만 수정함
## 검증 보고 기준
- FE는 빌드 명령, 화면 URL, 사용자 조작, 기대 결과, 네트워크 응답 확인 기준을 남김
- BE는 API 요청/응답 예시와 DB 영향 여부를 남김
- QA는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김
apps/sn/docs/AI코딩하네스/기준문서/008-문서구조기준.md
-160
View File
@@ -1,160 +0,0 @@
# 프론트 AI 문서 구조 기준
## 1. 목적
이 문서는 `sn` 프론트엔드 작업에서 AI와 개발자가 같은 기준으로 문서를 읽고 작성하기 위한 문서 구조 기준이다.
프론트 문서는 단순 기록이 아니라, 화면 구현 전에 요구사항, 컴포넌트, API 사용, 상태 흐름, 브라우저 검증 기준을 빠르게 파악하기 위한 작업 입력이다.
## 2. 적용 범위
| 구분 | 기준 경로 | 역할 |
| --- | --- | --- |
| 프론트 앱 기준 | `SN_APP_ROOT/AGENTS.md` | `sn` 작업 규칙과 수정 가능 범위 |
| AI 기준문서 | `SN_APP_ROOT/docs/AI코딩하네스/기준문서/` | 앱 작업 정책 |
| 작업계획 | `SN_APP_ROOT/docs/AI코딩하네스/작업계획/` | 화면/기능별 작업카드 |
| 검증 | `SN_APP_ROOT/docs/AI코딩하네스/검증/` | 브라우저/빌드/네트워크 검증 기준 |
| 보고 | `SN_APP_ROOT/docs/AI코딩하네스/보고/` | 작업 결과와 이슈 기록 |
| 기능 문서 | `SN_APP_ROOT/docs/{기능명}/` | 화면별 구현 산출물 |
| 프론트 공통 문서 | `FE_REPO_ROOT/docs/` | 여러 앱이 공유하는 FE 기준 |
## 3. 기준문서 구조
경로:
```text
SN_APP_ROOT/docs/AI코딩하네스/기준문서/
```
현재 기준:
```text
001-프로젝트.md
002-화면맵.md
003-API사용.md
004-컴포넌트정책.md
005-상태관리정책.md
006-검증정책.md
007-멀티에이전트운영.md
008-문서구조기준.md
009-AI개발작업흐름.md
```
역할:
- `sn` 앱의 작업 대상과 금지 경로 확인
- 화면/라우트 구조 확인
- API 호출 방식 확인
- 기존 컴포넌트 재사용 기준 확인
- 상태관리 기준 확인
- 검증 기준 확인
- BE/FE 역할 분리 기준 확인
## 4. 기능 문서 구조
기능별 문서는 아래 위치에 둔다.
```text
SN_APP_ROOT/docs/{기능명}/
```
권장 구조:
```text
README.md
00-범위.md
01-기존화면기반-컴포넌트분해.md
02-컴포넌트별-작업목록.md
03-API응답필드매핑표.md
04-화면흐름.md
05-검증계획.md
06-검증결과.md
99-미확인사항.md
```
문서별 역할:
| 문서 | 역할 |
| --- | --- |
| `README.md` | 기능 문서 진입점 |
| `00-범위.md` | 구현 대상과 제외 범위 |
| `01-기존화면기반-컴포넌트분해.md` | 기존 화면/컴포넌트 재사용 후보 |
| `02-컴포넌트별-작업목록.md` | 컴포넌트 단위 작업 목록 |
| `03-API응답필드매핑표.md` | 화면에서 사용하는 API와 응답 필드 |
| `04-화면흐름.md` | 사용자 동작과 화면 상태 흐름 |
| `05-검증계획.md` | 브라우저/네트워크/빌드 검증 계획 |
| `06-검증결과.md` | 실제 검증 결과 |
| `99-미확인사항.md` | BE/FE/API/DB 미확정 이슈 |
## 5. 프론트 공통 문서와 `sn` 문서 구분
`SN_APP_ROOT/docs/**`는 `sn` 앱 특정 화면과 기능을 다룬다.
`FE_REPO_ROOT/docs/**`는 여러 앱이 함께 보는 공통 기준만 다룬다.
| 상황 | 문서 위치 |
| --- | --- |
| `sn` 특정 화면 구현 | `SN_APP_ROOT/docs/{기능명}/` |
| `sn` API 필드 매핑 | `SN_APP_ROOT/docs/{기능명}/03-API응답필드매핑표.md` |
| `sn` 검증 결과 | `SN_APP_ROOT/docs/{기능명}/06-검증결과.md` |
| 여러 앱 공통 상태관리 기준 | `FE_REPO_ROOT/docs/구조/` |
| 여러 앱 공통 응답 처리 기준 | `FE_REPO_ROOT/docs/응답표준화/` |
## 6. 백엔드 문서와 연결 기준
프론트 기능이 백엔드 계약에 의존하면 아래 문서를 함께 본다.
```text
BE_SERVICE_ROOT/docs/AI코딩하네스/작업계획/{작업카드}.md
BE_SERVICE_ROOT/docs/AI코딩하네스/DB/{DB문서}.md
BE_SERVICE_ROOT/docs/실행명세/**
```
연결 방식:
| 프론트 문서 | 연결되는 백엔드 문서 |
| --- | --- |
| API 응답 필드 매핑표 | BE 작업카드, API 정책 |
| 화면흐름 | BE API 처리 흐름 |
| 미확인사항 | BE 작업계획, DB 문서 |
| 검증계획 | QA 카드, BE 테스트/실행명세 |
## 7. 작성 원칙
1. 화면 구현 전에 기능 문서를 먼저 확인한다.
2. 기존 컴포넌트 재사용 가능성을 먼저 기록한다.
3. API 응답 필드는 화면 표시명과 실제 필드명을 함께 적는다.
4. 미확정 API/DB 이슈는 `99-미확인사항.md`에 남긴다.
5. 검증 결과는 실제 브라우저 동작 기준으로 남긴다.
6. 정적 HTML은 참고 자료이고 실제 구현은 `apps/sn` 코드와 기존 컴포넌트 조합으로 한다.
7. 공통 패키지 수정이 필요하면 영향 범위를 먼저 정리한다.
## 8. 적용 예시: 노후관로관리
노후관로관리 문서는 아래 역할로 사용한다.
```text
SN_APP_ROOT/app/html/06. 노후관로관리_시나리오_v1.0.md
→ 화면 요구사항과 사용자 동작 확인
SN_APP_ROOT/docs/노후관로관리/03-API응답필드매핑표.md
→ 목록/상세/위치 이동에 필요한 API 필드 확인
SN_APP_ROOT/docs/노후관로관리/99-미확인사항.md
→ 백엔드 확인 이슈 관리
BE_SERVICE_ROOT/docs/AI코딩하네스/DB/001-노후관로-레이어설정.md
→ 레이어 트리 DB 기준 데이터 반영안 확인
```
## 9. 유지보수 기준
아래 상황에서는 문서를 갱신한다.
- 화면 흐름 변경
- API endpoint 또는 응답 필드 변경
- 컴포넌트 구조 변경
- 상태관리 방식 변경
- 브라우저 검증 결과 확정
- 미확인사항 해결
- 백엔드 계약 변경
apps/sn/docs/AI코딩하네스/기준문서/009-AI개발작업흐름.md
-244
View File
@@ -1,244 +0,0 @@
# 프론트 AI 개발 작업 흐름
## 1. 목적
이 문서는 `sn` 프론트엔드 기능 개발을 AI와 함께 진행할 때 따르는 표준 작업 흐름이다.
기능마다 화면과 API는 달라질 수 있지만, 작업 기준 확인, 기존 화면/컴포넌트 확인, API 계약 확인, 최소 구현, 브라우저 검증, 결과 기록의 큰 흐름은 유지한다.
## 2. 기본 원칙
1. `AGENTS.md`와 `sn` 기준문서를 먼저 확인한다.
2. 기존 화면과 컴포넌트를 먼저 찾는다.
3. `apps/sn` 내부 해결을 우선한다.
4. 공통 패키지는 `business_components`만 허용 범위에서 수정한다.
5. `@common/components`, `@common/network`, `@common/auth` 등 금지 범위는 직접 수정하지 않는다.
6. 백엔드 응답을 임의로 가정하지 않고 API 문서와 실제 응답을 확인한다.
7. 구현 후 브라우저 동작과 네트워크 응답을 확인한다.
## 3. 표준 작업 흐름
```text
1. 작업 기준 확인
2. 기능 문서 확인
3. 기존 화면/컴포넌트 탐색
4. API 사용부와 응답 필드 확인
5. 상태관리와 화면 흐름 확인
6. 구현 방향 결정
7. 최소 범위 구현
8. 빌드/브라우저/네트워크 검증
9. 검증 결과와 남은 리스크 기록
```
## 4. 단계별 기준
### 4.1 작업 기준 확인
먼저 아래 문서를 확인한다.
```text
WORKSPACE_ROOT/AGENTS.md
SN_APP_ROOT/AGENTS.md
BE_SERVICE_ROOT/AGENTS.md
```
확인할 내용:
- 수정 가능한 경로
- `apps/sn` 내부 해결 가능 여부
- `business_components` 수정 가능 여부
- 공통 패키지 수정 금지 범위
- 백엔드 연동 영향 여부
### 4.2 기능 문서 확인
확인 대상:
```text
SN_APP_ROOT/docs/{기능명}/00-범위.md
SN_APP_ROOT/docs/{기능명}/03-API응답필드매핑표.md
SN_APP_ROOT/docs/{기능명}/04-화면흐름.md
SN_APP_ROOT/docs/{기능명}/99-미확인사항.md
```
확인할 내용:
- 화면 목적
- 사용자 동작 흐름
- 호출 API
- 필요한 응답 필드
- 미확정 백엔드 계약
- 검증해야 할 브라우저 동작
### 4.3 기존 화면/컴포넌트 탐색
새 UI를 만들기 전에 기존 구현을 찾는다.
우선순위:
```text
1. SN_APP_ROOT/app/**
2. SN_APP_ROOT/src/**
3. BUSINESS_COMPONENTS_ROOT/src/**
```
확인할 내용:
- 유사 화면
- 기존 테이블/모달/검색/상세 패널
- 지도 레이어/트리/팝업 패턴
- 기존 상태관리 store
- 기존 API 유틸
### 4.4 API 사용부와 응답 필드 확인
확인할 내용:
- API 호출 함수
- 요청 파라미터
- 응답 wrapper 구조
- 화면 표시 필드
- 코드값 매핑
- 오류 처리
백엔드와 계약이 불명확하면 `99-미확인사항.md`에 기록하고 BE 작업카드와 연결한다.
### 4.5 상태관리와 화면 흐름 확인
확인할 내용:
- local state로 충분한가
- 기존 Zustand store를 써야 하는가
- URL/query state가 필요한가
- 모달/패널/지도 선택 상태가 어떻게 연결되는가
- API 재조회 시점은 언제인가
### 4.6 구현 방향 결정
가능한 방향:
```text
1. 기존 화면/컴포넌트 조합만으로 구현
2. apps/sn 내부 컴포넌트 추가
3. business_components 최소 보강
4. 백엔드 API 계약 확인 요청
5. 백엔드 변경 필요 사항 정리
```
기본 방침:
```text
기존 컴포넌트로 가능하면 재사용한다.
apps/sn 내부 해결을 우선한다.
공통 패키지 수정은 마지막에 판단한다.
백엔드 응답 구조를 프론트에서 임의로 바꾸지 않는다.
```
### 4.7 최소 범위 구현
구현 원칙:
- 기존 디자인과 컴포넌트 패턴을 따른다.
- 신규 스타일은 최소화한다.
- 화면 전체 구조를 불필요하게 바꾸지 않는다.
- 텍스트/버튼/테이블이 모바일과 데스크톱에서 넘치지 않게 한다.
- 지도 화면은 전체 페이지 스크롤보다 내부 패널 스크롤을 우선한다.
- API 변환 로직은 한 곳에 모은다.
### 4.8 빌드/브라우저/네트워크 검증
수정 범위에 따라 검증한다.
`apps/sn`만 수정한 경우:
```powershell
pnpm --filter sn run build
pnpm turbo run build --filter=sn
```
`business_components` 수정 시:
```powershell
pnpm --filter @common/business_components run build
pnpm --filter sn run build
```
브라우저 검증:
- 화면 진입
- 검색/조회
- 모달/패널 열림
- 테이블 표시
- 지도 레이어 표시
- 네트워크 요청/응답
- 오류 처리
- 스크롤/레이아웃 깨짐 여부
### 4.9 결과 기록
작업 후 아래 항목을 기록한다.
- 작업 목적
- 수정 대상 파일
- 변경 내용 요약
- 영향 범위
- 검증 방법
- 롤백 방법
- 남은 리스크
기능 문서가 있다면 `06-검증결과.md` 또는 `99-미확인사항.md`를 갱신한다.
## 5. BE/FE 연동 작업 흐름
프론트가 백엔드 계약에 의존하는 경우 아래 순서로 진행한다.
```text
1. FE 화면흐름 확인
2. FE API 응답 필드 매핑표 확인
3. FE 미확인사항 확인
4. BE 작업카드/API/DB 문서 확인
5. 실제 API 응답 확인
6. 프론트 구현
7. 브라우저와 네트워크 응답 검증
8. 미확인사항 해결 여부 갱신
```
## 6. 적용 예시: 노후관로관리
노후관로관리 작업에서는 이 흐름을 아래처럼 적용했다.
```text
시나리오 문서 확인
→ API 응답 필드 매핑표 확인
→ 미확인사항 확인
→ 기존 GIS/레이어 트리 패턴 확인
→ 기존 /api/v1/fclts 재사용 결정
→ 노후관로 가상 노드 fallback 구현
→ DB 정식 노드 반영 후 중복 방지
→ 목록/지도 강조선/상세 패널 검증
```
프론트 최종 방향:
```text
노후관로 목록: 기존 v1/fclts 재사용
노후관로 트리 노드: DB 노드 우선, 없으면 프론트 fallback
노후관로 강조선: tb_ms_swage_ppl WFS 조건 레이어 추가
상세 패널: 기존 하수관로 상세 패널 재사용
```
## 7. 고정할 큰 틀
기능이 달라져도 아래 흐름은 유지한다.
```text
문서 확인
→ 기존 화면/컴포넌트 확인
→ API 계약 확인
→ 재사용 가능 여부 판단
→ 최소 구현
→ 브라우저 검증
→ 결과 기록
```
세부 구현은 상황에 맞게 조정하되, 기존 화면 패턴 재사용과 실제 브라우저 검증은 항상 유지한다.
apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md
-5
View File
@@ -1,5 +0,0 @@
# 2026-04-16 개선 기록
## 반복 개선점
- 추정: 기능별 작업이 누적되면 `작업목록.md`에 화면, API, 검증 상태 컬럼을 추가해 진행률을 더 쉽게 볼 수 있다.
- 추정: 브라우저 테스트 절차가 반복되면 `기준문서/007-브라우저점검목록.md`를 추가해 공통 체크리스트로 분리할 수 있다.
apps/sn/docs/AI코딩하네스/보고/2026-04-16/결과보고.md
-51
View File
@@ -1,51 +0,0 @@
# 2026-04-16 작업 보고
## SN-P2-HARNESS-001
### 작업 목적
- 확인됨: `sn` 2차사업 작업을 기능 단위 작업카드와 일자별 기록으로 관리하기 위한 경량 하네스 문서 구조를 만든다. 근거: `apps/sn/AGENTS.md`
### 수정 파일 목록
- 확인됨: `apps/sn/docs/AI코딩하네스/개요.md`
- 확인됨: `apps/sn/docs/AI코딩하네스/작업목록.md`
- 확인됨: `apps/sn/docs/AI코딩하네스/기준문서/*`
- 확인됨: `apps/sn/docs/AI코딩하네스/작업계획/*`
- 확인됨: `apps/sn/docs/AI코딩하네스/보고/*`
### 변경 요약
- 확인됨: 프로젝트 기준, 화면 기준, API 연동 기준, 컴포넌트 기준, 상태관리 기준, 검증 기준 문서를 추가했다.
- 확인됨: 기능별 작업카드 템플릿과 일자별 기록 파일을 추가했다.
### 영향 범위
- 확인됨: 문서만 추가했으므로 런타임 동작에는 영향이 없다.
- 확인됨: `apps/sn` 하위 문서만 추가했으며 `packages/common/business_components`는 변경하지 않았다.
### 검증 방법
- 확인됨: 문서 파일 생성 여부를 확인한다.
- 확인됨: 코드 변경이 없으므로 빌드 검증은 수행하지 않아도 된다.
### 롤백 방법
- 확인됨: `apps/sn/docs/AI코딩하네스` 하위에서 이번에 추가한 문서 파일을 제거하면 된다.
### 남은 리스크
- 확인 필요: 2차사업 기능별 실제 작업카드는 요구사항과 화면설계서 기준으로 별도 작성해야 한다.
- 확인 필요: 브라우저 검증 URL과 테스트 계정은 실행 환경 기준으로 확정해야 한다.
## SN-DOC-KO-001
### 작업 목적
- 확인됨: 프론트엔드 문서 폴더와 Markdown 파일명을 한글 기준으로 정리하고 팀 공유를 위해 Git 추적 대상에 포함한다.
### 변경 요약
- 확인됨: 루트 `docs`의 기존 문서 파일명을 한글명으로 변경했다.
- 확인됨: `docs/bbs`는 `docs/게시판`, `docs/dockerbuild`는 `docs/도커빌드`로 변경했다.
- 확인됨: `apps/sn/docs/phase2`는 `apps/sn/docs/AI코딩하네스`로 변경했다.
- 확인됨: 문서 전용 파일명은 한글로 변경하되, `docs/도커빌드/Dockerfile`, `front_docker_build.sh`, `next.config.ts`는 실행 의미가 있어 파일명을 유지했다.
### 영향 범위
- 확인됨: 문서 경로와 문서 내부 참조만 변경했다.
- 확인됨: 프론트 런타임, 빌드 설정, API 계약에는 영향이 없다.
### 검증 방법
- 확인됨: 문서 파일 경로를 조회해 한글 경로로 이동된 것을 확인한다.
- 확인됨: `git status --short`에서 문서 파일이 추적 대상 상태로 표시되는지 확인한다.
apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md
-8
View File
@@ -1,8 +0,0 @@
# 2026-04-16 이슈
## 외부 범위 이슈
- 확인 필요: 현재 등록된 외부 범위 이슈는 없다.
## 미확정 항목
- 확인 필요: 2차사업 최종 화면명, 메뉴명, URL은 화면설계서와 실행 환경 기준으로 확정해야 한다.
- 확인 필요: 기능별 테스트 계정, 권한, 데이터는 환경별로 별도 확인해야 한다.
apps/sn/docs/AI코딩하네스/보고/2026-04-16/작업목록.md
-10
View File
@@ -1,10 +0,0 @@
# 2026-04-16 작업 항목
| ID | 상태 | 작업명 | 범위 | 결과 |
| --- | --- | --- | --- | --- |
| SN-P2-HARNESS-001 | 완료 | `sn` 2차사업 경량 하네스 문서 구조 생성 | `apps/sn/docs/AI코딩하네스` | 문서 골격 생성 |
| SN-DOC-KO-001 | 완료 | 프론트 문서 폴더/파일명 한글화 | `docs`, `apps/sn/docs` | 문서 경로 한글화 및 Git 추적 확인 |
## 확인 사항
- 확인됨: 프론트엔드 하네스 문서는 `apps/sn/docs/AI코딩하네스` 하위에 생성했다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 소스 코드, API 계약, DB 스키마는 변경하지 않았다. 근거: 작업 변경 범위
apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md
-5
View File
@@ -1,5 +0,0 @@
# 2026-04-16 제안
## 후속 제안
- 추정: 기능 개발 착수 전 `작업계획/SN-P2-001-*.md` 형식으로 작업카드를 먼저 작성하면 백엔드와 프론트엔드 변경 범위를 분리해서 추적하기 쉽다.
- 추정: 백엔드 API 변경이 동반되는 작업은 백엔드 작업카드 ID와 프론트 작업카드 ID를 서로 참조하는 방식이 좋다.
apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md
-45
View File
@@ -1,45 +0,0 @@
# 2026-04-17 결과보고
## 작업 목적
- `sn` 2차사업 고도화 작업을 멀티에이전트로 진행하기 전에 프론트 문서 기준과 공통 비즈니스 컴포넌트 문서의 오해 요소를 정리한다.
## 수정 대상 파일
- `apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md`
- `apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md`
- `apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md`
- `apps/sn/docs/AI코딩하네스/개요.md`
- `apps/sn/docs/AI코딩하네스/작업목록.md`
- `apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md`
- `apps/sn/docs/AI코딩하네스/한글경로-영향.md`
- `apps/sn/app/html/AGENTS.md`
- `packages/common/business_components/README.md`
- `packages/common/business_components/src/form.md`
- `packages/common/business_components/src/chart.md`
- `packages/common/business_components/src/ui/search_form_left/searchFormLeft.md`
- `apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md`
## 변경 내용 요약
- 폐기된 `phase2` 문서 경로를 `apps/sn/docs/AI코딩하네스/작업계획/` 및 `apps/sn/docs/` 하위 주제별 폴더 기준으로 수정했다.
- 백엔드 응답표준화 문서 참조를 실제 한글 경로로 수정했다.
- 프론트 작업카드 템플릿에 쓰기 허용/금지 범위, 충돌 주의 파일, BE/FE/QA 산출물 항목을 추가했다.
- 프론트 기준문서에 `sn` 작업용 멀티에이전트 운영 기준을 추가하고, 하네스 개요와 작업목록에 연결했다.
- 한글 경로 영향 문서가 과거 기록임을 명시하고, 루트 `docs/**`를 승인 없이 수정하지 않는 기준을 덧붙였다.
- `business_components` 문서의 오타, 잘못된 form 설명, 깨진 chart 예시, `fo` 기준 예시의 적용 주의 문구를 보완했다.
## 영향 범위
- 코드, API, DB 스키마 영향은 없다.
- `sn` 작업자가 문서 기준을 따라 작업할 때 수정 가능 범위와 작업카드 작성 기준이 더 명확해진다.
- `business_components` 문서 예시를 참고할 때 타 앱 기준을 `sn`에 그대로 적용하는 위험이 줄어든다.
- 백엔드 API/DB 영향이 있는 화면 작업에서 BE/FE/QA 합류 조건을 더 빨리 판단할 수 있다.
## 테스트 / 검증 방법
- Markdown 문서의 주요 참조 경로와 문구를 수동 확인했다.
- 빌드 또는 테스트는 코드 변경이 아니므로 수행하지 않았다.
## 롤백 방법
- 각 Markdown 파일을 이전 문구로 되돌린다.
- `apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md`를 삭제한다.
## 남은 리스크
- `business_components`의 실제 컴포넌트 API와 문서 예시 전체가 완전히 일치하는지는 별도 코드 기준 검증이 필요하다.
- 로그인, 권한, 테스트 데이터가 확정되지 않은 기능은 브라우저 검증 항목을 작업카드에서 다시 확정해야 한다.
apps/sn/docs/AI코딩하네스/보고/개요.md
-16
View File
@@ -1,16 +0,0 @@
# 작업 기록
## 목적
이 디렉터리는 `sn` 2차사업 작업의 일자별 진행 기록을 남긴다.
## 파일 구성
- `작업목록.md`: 해당 일자의 작업 항목과 상태
- `결과보고.md`: 수행 결과와 검증 결과
- `이슈.md`: 외부 범위, 미확정, 차단 이슈
- `제안.md`: 후속 제안
- `개선사항.md`: 반복 작업 개선점
## 기록 원칙
- 확인됨: 작업 결과는 변경 파일, 영향 범위, 검증 방법, 롤백 방법을 포함한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 권한 밖 경로 문제는 직접 수정하지 않고 이슈로 기록한다. 근거: `apps/sn/AGENTS.md`
- 추정: 백엔드와 함께 진행하는 기능은 백엔드 작업 기록과 프론트 작업 기록을 서로 참조하면 회귀 추적에 유리하다. 근거: 백엔드 `docs/AI코딩하네스` 구조
apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md
-74
View File
@@ -1,74 +0,0 @@
# SN-P2-000 작업카드 템플릿
## 1. 작업 개요
- 작업 ID:
- 작업명:
- 상태: 대기
- 작성일:
- 담당 역할: FE
- 관련 역할: BE, QA
- 담당 범위:
- 근거 문서:
## 2. 작업 목적
- 확인 필요:
## 3. 수정 대상 파일
| 구분 | 파일 경로 | 수정 여부 | 근거 |
| --- | --- | --- | --- |
| 화면 | 확인 필요 | 확인 필요 | 확인 필요 |
| 컴포넌트 | 확인 필요 | 확인 필요 | 확인 필요 |
| API 호출 | 확인 필요 | 확인 필요 | 확인 필요 |
| 공통 비즈니스 컴포넌트 | 확인 필요 | 확인 필요 | 확인 필요 |
## 3-1. 쓰기 범위와 충돌 주의
| 구분 | 경로 | 담당 역할 | 처리 기준 |
| --- | --- | --- | --- |
| 쓰기 허용 | `apps/sn/**` | FE | `sn` 화면/상태/API 호출 작업 |
| 쓰기 허용 | `packages/common/business_components/**` | FE | `sn` 요구사항에 필요한 최소 공통 컴포넌트 작업 |
| 쓰기 금지 | `packages/common/business_components` 외 공통 패키지 | FE | 문제 원인과 영향 범위만 기록 |
| 쓰기 금지 | 타 앱 `apps/*` | FE | 문제 원인과 영향 범위만 기록 |
- 충돌 주의 파일:
- 인수인계 메모:
## 4. 화면 흐름
- 확인 필요: 진입 경로
- 확인 필요: 사용자 조작
- 확인 필요: 정상 흐름
- 확인 필요: 빈 결과 흐름
- 확인 필요: 오류 흐름
## 5. API 연동
| 기능 | Method | URL | 요청 | 응답 | 확인 상태 |
| --- | --- | --- | --- | --- | --- |
| 확인 필요 | 확인 필요 | 확인 필요 | 확인 필요 | 확인 필요 | 확인 필요 |
## 6. 영향 범위
- 확인 필요: `apps/sn` 화면 영향
- 확인 필요: `business_components` 영향
- 확인 필요: 백엔드 API 영향
- 확인 필요: 다른 앱 영향 가능성
## 6-1. 멀티에이전트 작업 분리
- FE 담당 산출물:
- BE 담당 산출물:
- QA 담당 산출물:
- 병렬 진행 가능 항목:
- 순차 진행 필요 항목:
## 7. 검증 방법
- 확인 필요: 빌드 명령
- 확인 필요: 브라우저 URL
- 확인 필요: 사용자 조작
- 확인 필요: 기대 결과
- 확인 필요: 네트워크 응답 확인 기준
## 8. 롤백 방법
- 확인 필요:
## 9. 예상 위험
- 확인 필요:
## 10. 완료 기준
- 확인 필요:
apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md
-55
View File
@@ -1,55 +0,0 @@
# SN-P2-001 노후관로관리 작업카드 샘플
## 1. 작업 개요
- 작업 ID: `SN-P2-001`
- 작업명: 노후관로관리 화면 조회/증적 기준 정리
- 상태: 샘플 작성
- 담당 역할: FE
- 관련 역할: BE, QA
- 대상 범위: `apps/sn/**`
- 근거 문서:
- `apps/sn/app/html/06. 노후관로관리_시나리오_v1.0.md`
- `D:/workspace/IIPBS/sewerage-service/docs/실행명세/기능/21-dcrp-ppl-관리.md`
- `D:/workspace/IIPBS/sewerage-service/docs/실행명세/기능/60-관로통계.md`
## 2. 작업 목적
- 노후관로정비사업 화면의 조회 조건과 백엔드 `GET /api/v1/dcrpPpl` 계약을 카드에 고정한다.
- GIS 노후관로관리 시나리오가 본 화면으로 확장될 때 필요한 API/브라우저 증적 항목을 미리 둔다.
## 3. 수정 대상 파일
| 구분 | 파일 경로 | 수정 여부 | 근거 |
| --- | --- | --- | --- |
| 화면 | `apps/sn/app/(with-base-layout)/oper/oldPp/page.tsx` | 필요 시 최소 수정 | 노후관로정비사업 조회 화면 |
| 테이블 | `apps/sn/app/(with-base-layout)/oper/oldPp/tableModal.tsx` | 필요 시 최소 수정 | 행 선택 후 표 모달 |
| API 호출 | `apps/sn/app/components/lib/common/apiHelpers.ts` | 원칙상 변경 없음 | 기존 `searchData` 사용 |
| 공통 컴포넌트 | `packages/common/business_components/**` | 변경 없음 | 이번 카드에서는 직접 수정 금지 |
## 4. 화면 흐름
- 진입: `노후관로정비사업` 화면 또는 라우트 `/oper/oldPp`
- 기본 조회: 등록기간 기본값으로 `GET /api/v1/dcrpPpl` 호출
- 검색 조건: 등록기간, 등록자 입력값, 파일명/사업명 입력값
- 결과: 목록 테이블, 총 건수, 페이지 이동
- 행 선택: 첨부 파일명과 식별자를 상태에 보관하고 표 모달을 연다.
- 파일 작업: 다운로드/삭제/등록은 외부 첨부 서비스와 데이터 변경이 있으므로 QA 승인 데이터가 필요하다.
## 5. API 연동
| 기능 | Method | URL | 요청 | 응답 | 확인 상태 |
| --- | --- | --- | --- | --- | --- |
| 목록 조회 | GET | `/sewerage-service/api/v1/dcrpPpl` | `fromRegDt`, `toRegDt`, `dcrpPplMtncBizNm`, `auth`, `page`, `size` | Page 구조 | 확인됨 |
| 등록 | POST | `/sewerage-service/api/v1/dcrpPpl` | `mngYr`, `mngQu`, `atflCd`, `atflId`, `rgtr`, `dcrpPplMtncBizNm` | 단건 DTO | 미검증 |
| 삭제 | DELETE | `/sewerage-service/api/v1/dcrpPpl/{dcrpPplMtncBizSn}` | path id | 200 empty | 미검증 |
| 파일 다운로드 | GET | `/attach-service/api/v1/download/{atflId}` | path id | 파일 | 미검증 |
## 6. 검증 방법
- 빌드: `pnpm --filter sn run build`
- 브라우저: `/oper/oldPp` 진입 후 조회 버튼, 페이지 이동, 행 선택, 모달 확인
- 네트워크: `GET /sewerage-service/api/v1/dcrpPpl` 요청 URL, Query String, Status, Response JSON 기록
- 상세 양식: `apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md`
## 7. 롤백 방법
- 이번 카드에서 화면 코드가 변경되지 않았다면 문서만 제거한다.
- 화면 코드 변경이 발생한 경우 `oldPp/page.tsx`와 관련 모달 변경분을 되돌리고 빌드를 재실행한다.
## 8. 예상 위험
- `auth` 전달 방식과 사용자명 보강은 인증/권한 상태에 따라 결과가 달라질 수 있다.
- 등록/삭제/다운로드는 데이터 변경과 첨부 서비스 의존이 있어 수동 검증 전 테스트 데이터가 필요하다.
apps/sn/docs/AI코딩하네스/작업계획/개요.md
-17
View File
@@ -1,17 +0,0 @@
# 작업카드 관리
## 목적
이 디렉터리는 `sn` 2차사업 기능별 실행 계획을 보관한다.
작업카드는 구현 전에 작성하며, 수정 범위, API 영향, 화면 영향, 검증 방법, 롤백 방법을 먼저 고정한다.
## 작성 규칙
- 확인됨: 기능 단위로 문서를 만든다. 근거: 이 하네스 운영 문서
- 확인됨: 직접 수정 대상은 `apps/sn/**`와 `packages/common/business_components/**`로 제한한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 권한 밖 수정 필요성은 작업카드에 직접 구현 항목으로 넣지 않고 외부 이슈로 기록한다. 근거: `apps/sn/AGENTS.md`
- 추정: 백엔드 동시 변경이 필요한 기능은 백엔드 `docs/AI코딩하네스/작업계획` 작업카드 번호를 함께 적는 것이 추적에 유리하다. 근거: 백엔드 `docs/AI코딩하네스` 구조
## 파일명 규칙
- 권장 형식: `SN-P2-001-기능명.md`
- 기능명은 화면명 또는 업무명을 기준으로 작성한다.
- 한 작업카드에 여러 화면을 무리하게 묶지 않는다.
apps/sn/docs/AI코딩하네스/작업목록.md
-19
View File
@@ -1,19 +0,0 @@
# sn 2차사업 작업 목록
## 상태 값
- `대기`: 아직 착수하지 않은 작업
- `진행`: 현재 분석 또는 구현 중인 작업
- `검증`: 구현 후 빌드, 브라우저, API 응답을 확인하는 작업
- `완료`: 검증과 기록이 끝난 작업
- `보류`: 외부 범위 또는 추가 확인이 필요한 작업
## 작업 목록
| ID | 상태 | 작업명 | 범위 | 근거 | 비고 |
| --- | --- | --- | --- | --- | --- |
| SN-P2-000 | 대기 | 2차사업 기능 작업카드 등록 | `apps/sn/docs/AI코딩하네스/작업계획` | 확인됨: `apps/sn/AGENTS.md` | 기능별 작업 착수 전 작성 |
| SN-P2-HARNESS-002 | 완료 | AI_SAM 최신 하네스 구조 재확인 및 멀티에이전트 운영 기준 반영 | `apps/sn/docs/AI코딩하네스/기준문서` | 확인됨: AI_SAM `refactoring` 최신 HEAD | BE/FE/QA 합류 기준 추가 |
## 운영 규칙
- 확인됨: 작업은 `apps/sn/**`와 `packages/common/business_components/**` 범위 안에서만 직접 수정한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 다른 앱 또는 공통 패키지 문제가 발견되면 이 파일에 직접 작업으로 넣지 않고 `보고/YYYY-MM-DD/이슈.md`에 기록한다. 근거: `apps/sn/AGENTS.md`
- 추정: 실제 기능 작업은 2차사업 요구사항, 화면설계서, 백엔드 API 응답 근거를 함께 연결해야 한다. 근거: `apps/sn/AGENTS.md`
apps/sn/docs/AI코딩하네스/한글경로-영향.md
-56
View File
@@ -1,56 +0,0 @@
# 한글 폴더 및 Markdown 파일명 영향 검토
> 이 문서는 2026-04-16 문서 경로 정리 당시의 영향 검토 기록이다. 이후 `sn` 작업에서 새 문서를 만들 때는 `apps/sn/AGENTS.md` 기준에 따라 `apps/sn/docs/` 하위만 사용하고, 프론트엔드 루트 `docs/**`는 사용자 승인 없이 수정하지 않는다.
> 이 문서는 2026-04-16 문서 경로 정리 당시의 영향 검토 기록이다. 이후 `sn` 작업에서 새 문서를 만들 때는 `apps/sn/AGENTS.md` 기준에 따라 `apps/sn/docs/` 하위만 사용하고, 프론트엔드 루트 `docs/**`는 사용자 승인 없이 수정하지 않는다.
## 1. 결론
- 프론트엔드 문서 전용 경로는 한글 폴더명과 한글 `.md` 파일명을 사용해도 Codex 작업 이해에는 문제가 없음
- 현재 변경 범위는 루트 `docs/`와 `apps/sn/docs/` 하위 문서 경로에 한정되므로 프론트 런타임 영향은 없음
- 빌드, 배포, 앱 라우팅, API 호출 경로는 변경하지 않음
## 2. 적용한 한글 경로
- `docs/게시판/`
- `docs/도커빌드/`
- `docs/앱라우트.md`
- `docs/인증서비스-리팩토링가이드.md`
- `docs/CS프로젝트구조.md`
- `docs/프론트디버깅.md`
- `docs/개선계획.md`
- `docs/요구사항.md`
- `apps/sn/docs/AI코딩하네스/`
- `apps/sn/docs/AI코딩하네스/기준문서/`
- `apps/sn/docs/AI코딩하네스/작업계획/`
- `apps/sn/docs/AI코딩하네스/보고/`
## 3. 파일명을 유지한 항목
- `docs/도커빌드/Dockerfile`
- `docs/도커빌드/front_docker_build.sh`
- `docs/도커빌드/next.config.ts`
- `docs/IIPBS_단어목록.md`
## 4. 영향 없음
- Next.js 앱 실행
- Turborepo 빌드
- pnpm workspace 설정
- Dockerfile, PM2, Gitea workflow
- API 계약과 백엔드 연동 경로
- `apps/sn` 화면 라우팅
## 5. 주의 필요
- 외부 문서 링크가 기존 영문 경로를 직접 참조하는 경우 새 한글 경로로 수정 필요
- CI 또는 배포 스크립트가 `docs/dockerbuild`를 직접 참조하는 경우 새 `docs/도커빌드` 경로로 수정 필요
- 일부 콘솔에서는 한글 경로가 이스케이프 문자열로 보일 수 있음
- URL로 공유되는 Markdown 링크는 한글 경로가 퍼센트 인코딩되어 길게 표시될 수 있음
## 6. 운영 기준
- 코드, 라우팅, 빌드, 배포 스크립트가 직접 참조하는 파일명은 영문 유지 권장
- 문서 전용 폴더와 `.md` 파일명은 한글 사용 가능
- 신규 `sn` 문서는 `apps/sn/docs/` 바로 아래 주제별 한글 폴더로 관리
- `phase2` 같은 단계 분리 폴더는 사용하지 않음
apps/sn/docs/README.md
-40
View File
@@ -1,40 +0,0 @@
# `sn` 앱 문서
## 목적
이 디렉터리는 하수관로 운영관리 시스템 `sn` 앱의 화면/기능별 산출물을 관리한다.
프론트엔드 공통 기준은 `FE_REPO_ROOT/docs/**`에 두고, `sn` 특정 화면과 기능 상세는 이 디렉터리에 둔다.
## 작성 범위
- `sn` 화면별 요구사항 해석
- 기존 화면 기반 컴포넌트 분해
- 컴포넌트별 작업 목록
- API 응답 필드 매핑
- 화면 흐름
- 검증 계획과 결과
- 기능별 미확인사항
## 작성 금지 범위
- 다른 앱 전용 기능 상세
- 백엔드 내부 구현 상세
- 공통 프론트엔드 규칙 전체
## 기능별 문서 구조
기능별 문서는 아래 형식을 권장한다.
```text
apps/sn/docs/{기능명}/
README.md
00-범위.md
01-기존화면기반-컴포넌트분해.md
02-컴포넌트별-작업목록.md
03-API응답필드매핑표.md
04-화면흐름.md
05-검증계획.md
06-검증결과.md
99-미확인사항.md
```
apps/sn/docs/노후관로관리/00-범위.md
-32
View File
@@ -1,32 +0,0 @@
# 노후관로관리 범위
## 목적
노후관로관리 및 노후관로분석 화면의 프론트엔드 구현 범위를 정의한다.
## 포함 범위
- 노후관로 레이어 체크/표출
- 좌측 하단 경과년도 설정 영역
- 노후관로 목록 모달
- 목록 행 더블클릭과 지도/상세 연동
- 관로 상세정보 표시
- 하수처리구역 기준 매설년도 분석정보 표시
- 보수이력 진입 버튼 또는 링크
- 엑셀 다운로드 버튼 연결
## 제외 범위
- 백엔드 API 신규 구현
- DB 스키마 변경
- 백엔드 공통 응답 구조 변경
- `sn` 외 다른 앱 화면 변경
- `business_components` 외 공통 패키지 직접 수정
## 기준 문서
- 기능 요구사항 명세서 v2.0
- 시나리오 v2.0
- `01-기존화면기반-컴포넌트분해.md`
- `02-컴포넌트별-작업목록.md`
apps/sn/docs/노후관로관리/01-기존화면기반-컴포넌트분해.md
-158
View File
@@ -1,158 +0,0 @@
# 노후관로관리 기존 화면 기반 컴포넌트 분해
## 목적
노후관로관리 2차 고도화 화면은 신규 디자인을 만들지 않고, 1차 개발 화면의 레이아웃과 컴포넌트 톤을 유지한다.
이 문서는 실제 `sn` 화면 코드 기준으로 화면을 어떤 단위로 나누어 개발해야 하는지 정리한다.
## 기준 화면 구조
실제 화면은 아래 계층으로 구성된다.
```text
NoFooterLayout
Header
LNB
MapLayout children
Gis
GisTree
GisMapToggle
GisToolBar
GisZoomLevel
ProcSearchBar
FeatureClickEventPopup
```
## 실제 참조 파일
| 구분 | 기준 파일 | 개발 기준 |
|---|---|---|
| 전체 레이아웃 | `packages/common/components/src/ui/layout/nofooter.tsx` | `Header` + `LNB` + 본문 3단 구조 유지 |
| 상단 헤더 | `packages/common/components/src/ui/header/index.tsx` | 흰색 헤더, 로고, 상단 시스템 메뉴, 검색, 사용자 영역 유지 |
| 좌측 메뉴 | `packages/common/components/src/ui/lnb/index.tsx` | `하수관망도`, `I/I 분석`, `운영정보` 계층 유지 |
| 지도 컴포넌트 | `packages/common/business_components/src/ui/map/Gis.js` | OpenLayers 기반 `Gis` 사용 |
| 시설물 트리 | `packages/common/business_components/src/ui/map/GisTree.js` | 폭 250px, 제목 `시설물`, 체크박스 트리 유지 |
| 지도 도구 | `packages/common/business_components/src/ui/map/GisToolBar.js` | 기존 우측 도구 버튼 위치/크기 유지 |
| 검색 바 | `packages/common/business_components/src/ui/map/searchBar` | 기존 지도 상단 검색 조건 영역 유지 |
| 상세 팝업 | `apps/sn/app/html/(map-layout)/map/components/popupComponent/featureClickEventPopup.tsx` | 우측 350px 팝업, 파란 헤더, `VerticalTable` 유지 |
| 세로 테이블 | `apps/sn/app/components/ui/verticalTable.tsx` | `bg-blue-100` 라벨셀, 2열 세로 테이블 유지 |
| 목록 그리드 | `packages/common/business_components/src/ui/table/index.tsx` | `UiTable` 기반 목록/페이징 유지 |
## 레이아웃 기준값
| 영역 | 기준 |
|---|---|
| Header | 높이 `6rem`, 흰색 배경, 하단 border |
| LNB | 폭 `22rem`, 흰색 배경, `하수관망도` active |
| GisTree | 폭 `250px`, 지도 내부 좌측 absolute. 상단 레이어 트리와 하단 설정 영역을 같은 패널 안에서 자연스럽게 분리 |
| Map body | `calc(100vh - 50px)` 계열, `Gis` 영역 full |
| Detail popup | 우측 absolute, 폭 `350px`, 높이 `calc(100vh - 5rem)` |
| Detail header | `bg-primary`, 흰색 글자, 닫기 `✕` |
| Detail table | `VerticalTable`, 왼쪽 라벨셀 `bg-blue-100`, 오른쪽 값셀 흰색 |
## 색상 및 폰트 기준
노후관로관리 추가 UI는 기존 우측 상세정보의 `FeatureClickEventPopup` + `VerticalTable` 색상과 폰트 톤을 따른다.
좌측 하단 설정 영역도 별도 신규 색을 쓰지 않고 같은 토큰을 사용한다.
| 항목 | 기준값 | 사용 위치 |
|---|---|---|
| 기본 폰트 | `Noto Sans KR`, `Malgun Gothic` fallback | 전체 화면 |
| 기본 글자색 | `#111`, `#333`, `#555` | 본문, 트리, 입력 라벨 |
| Primary blue | `#258eea` | 우측 상세 헤더, 조회 버튼 등 기존 primary 영역 |
| Dark navy | `#152346` | 기존 강조 버튼 또는 별도 강조 영역이 필요한 경우만 사용 |
| Download green | `#1fd078` | 목록/엑셀 다운로드 버튼 |
| Label cell blue | `#dbeafe` | `VerticalTable` 왼쪽 라벨셀 |
| Table border | `#dbe2e6`, `#e5e7eb` | 세로 테이블/목록 테이블 구분선 |
| Panel border | `#d1d5db`, `#d7dde3` | 좌측 패널, 설정 영역 외곽 |
| Panel background | `#fff` | LNB, GisTree, 설정 영역, 상세 팝업 |
| Apply green | `#31a83b` | 좌측 하단 설정 영역의 적용 아이콘 |
### 좌측 하단 설정 영역 색상 기준
- 외곽은 `Panel border`를 사용한다.
- 헤더는 진한 남색 바를 쓰지 않고, 위 `시설물` 패널처럼 흰 배경의 제목 행을 사용한다.
- 입력 라벨, 값, 적용 아이콘 폰트는 기존 `Noto Sans KR` 계열과 동일하게 둔다.
- 적용은 텍스트 버튼이 아니라 녹색 원형 체크 아이콘 형태로 표현한다.
- 트리 영역과 설정 영역 사이에는 굵은 검정선 대신 `#d1d5db` 계열의 얇은 경계와 여백을 사용한다.
- 목적은 강한 분리선이 아니라, 같은 좌측 패널 안에서 서로 다른 기능 영역임을 자연스럽게 구분하는 것이다.
### 목록 모달 버튼 색상 기준
- `조회`는 공통 `Button`의 `primary` 톤을 따른다.
- `다운로드`는 공통 `Button`의 `green` 톤을 따른다.
- 모달 안에서 임의의 남색 버튼이나 흰색 outline 다운로드 버튼을 새로 만들지 않는다.
- 정적 HTML 샘플에서도 `조회=#258eea`, `다운로드=#1fd078` 조합으로 표현한다.
## 화면설계서 번호 기준 영역
노후관로관리 화면은 화면설계서의 번호 기준대로 영역을 분리해서 봐야 한다.
특히 `경과년도(년)` 입력 영역은 지도 위에 뜨는 독립 팝업이 아니라, 좌측 `시설물` 트리 하단에 붙는 별도 설정 영역으로 본다.
| 번호 | 화면 영역 | 위치 | 기존 컴포넌트 기준 | 동작 |
|---|---|---|---|---|
| ① | 노후관로 레이어 체크박스 | 좌측 `시설물` 트리 내부, `노후관로` 행 | `GisTree` 노드 | 체크 ON/OFF로 노후관로 레이어 표출 제어 |
| ② | 경과년도 설정 영역 | 좌측 `시설물` 트리 하단, 트리 목록 아래 별도 접힘/펼침 박스로 자연스럽게 분리 | `GisTree` 하단 확장 영역 또는 지도 오버레이가 아닌 좌측 설정 블록 | `경과년도(년)` 단일 입력 후 초록 체크 적용 |
| ③ | 지도 관로 선택 영역 | 지도 본문 | `Gis`, `GisSelect`, `onFeatureSelect` | 관로 클릭 시 우측 상세 팝업 표출 |
| ④ | 노후관로 목록 아이콘 | 좌측 `시설물` 트리 내부, `노후관로` 행 우측 | `GisTree`의 `onLayerIconClick`/`onOpenPopup` | 노후관로 현황 목록 모달 호출 |
### 좌측 영역 분리 원칙
```text
GisTree (좌측 250px)
시설물 제목
레이어 트리 영역
시설
하수관로
...
노후관로 체크박스 ①
노후관로 목록 아이콘 ④
(여백)
레이어별 설정 영역 ②
제목 행: 지반침하정보 또는 대상 레이어명
입력 행: 경과년도(년) [30] [초록 체크]
```
이 구조를 따르면 화면설계서의 ①, ②, ④가 모두 좌측 `GisTree` 계열 안에서 구분된다.
따라서 노후관로 기준 패널을 지도 중앙이나 지도 좌하단의 독립 카드처럼 띄우지 않는다.
또한 트리와 설정 영역 사이를 검정 굵은 선으로 끊지 않고, 실제 화면처럼 여백과 연한 경계선으로 자연스럽게 구분한다.
### 접힘/펼침 기준
- 상단 `시설물` 영역과 하단 설정 영역은 각각 접힘/펼침이 가능해야 한다.
- 접힘 상태에서는 제목 행만 남기고 내부 행은 숨긴다.
- 하단 설정 영역은 사용자가 현재 조정할 수 있는 입력만 보여준다.
- 화면설계서 예시처럼 `지반침하정보` 설정이면 `경과년도(년) [30] [초록 체크]`만 표시한다.
- 노후관로 기준을 같은 패턴으로 적용할 때도 입력 필드를 과도하게 늘리지 않고, 대상 레이어명과 경과년도 입력만 노출한다.
## 노후관로관리 추가 시 분해
| 요구사항 | 기존 컴포넌트 기반 구현 위치 |
|---|---|
| 노후관로 레이어 ON/OFF | `GisTree` 레이어 노드 추가 또는 기존 하수관로 레이어 스타일 보강 |
| 경과년도 조건 | `GisTree` 하단의 접힘/펼침 가능한 레이어별 설정 영역으로 구성. `경과년도(년)` 단일 입력만 노출 |
| 목록 아이콘 | `GisTree`의 `노후관로` 행 우측 아이콘으로 배치하고 `onLayerIconClick`/`onOpenPopup` 흐름 활용 |
| 목록 팝업 | `UiTable` 기반 모달로 구성 |
| 지도-그리드 연동 | 기존 `onFeatureSelect`, `GisApp.Module.layer.showSearchResultsFromGeoJSON` 흐름 활용 |
| 상세정보 | `FeatureClickEventPopup` 또는 동일한 `VerticalTable` 구조로 확장 |
| 노후관로분석 | 하수처리구역 피처 클릭 시 기존 상세 팝업에 분석정보 섹션 추가 |
## 금지 방향
- 별도 전체 화면 레이아웃을 새로 만들지 않는다.
- 어두운 헤더/새 사이드바/카드형 상세 패널 등 기존과 다른 디자인을 넣지 않는다.
- `경과년도(년)` 설정을 지도 위 플로팅 카드로 분리하지 않는다.
- 트리와 설정 영역 사이에 굵은 검정 구분선을 사용하지 않는다.
- 좌측 하단 설정 영역에 남색 헤더 바와 남색 텍스트 적용 버튼을 사용하지 않는다.
- 하단 설정 영역에 시도/시군구/목록 버튼을 넣지 않는다.
- `apps/sn/app/html/**` 정적 샘플을 실제 서비스 코드로 그대로 옮기지 않는다.
- 기존 `FeatureClickEventPopup`, `VerticalTable`, `UiTable`, `GisTree`로 가능한 UI를 별도 컴포넌트로 새로 만들지 않는다.
## 개발 전 확인 순서
1. 실제 메뉴/라우트가 `NoFooterLayout` 하위에서 열리는지 확인한다.
2. 노후관로 레이어가 기존 `SN_NETWORK` 레이어 설정에 포함되는지 확인한다.
3. 하수관로 속성명(`instl_ymd`, `fclt_mng_no`, `mqlt_cd`, `usg_cd`)을 실제 API 응답과 맞춘다.
4. 상세 패널은 기존 `FeatureClickEventPopup` 확장 가능성을 먼저 검토한다.
5. 목록 팝업은 `UiTable`과 기존 검색 모달 패턴으로 구성한다.
6. `business_components` 수정이 필요한 경우 타 앱 영향 범위를 먼저 정리한다.
apps/sn/docs/노후관로관리/02-컴포넌트별-작업목록.md
-240
View File
@@ -1,240 +0,0 @@
# 노후관로관리 컴포넌트별 작업 목록
## 목적
이 문서는 노후관로관리 화면을 실제 React 코드로 옮기기 전에, 어떤 기존 컴포넌트를 재사용하고 어떤 컴포넌트만 최소 확장할지 정리한 작업 목록이다.
기준은 `01-기존화면기반-컴포넌트분해.md`와 `old-pipe-component-sample/index.html`의 최종 확인 화면이다.
## 구현 원칙
- 새 디자인 시스템을 만들지 않는다.
- 실제 화면은 `NoFooterLayout > Header/LNB > Gis > GisTree/FeatureClickEventPopup/UiTable` 흐름을 따른다.
- 좌측 하단 설정 영역은 지도 위 플로팅 카드가 아니라, `GisTree` 내부 또는 `GisTree`와 붙은 좌측 패널 영역으로 구현한다.
- 좌측 하단 설정 영역에는 `경과년도(년)` 단일 입력과 초록 적용 아이콘만 둔다.
- 노후관로 현황 목록의 `조회`는 `Button color="primary"`, `다운로드`는 `Button color="green"` 톤을 따른다.
- 우측 상세정보는 기존 `FeatureClickEventPopup` + `VerticalTable` 톤을 우선한다.
## 작업 단위 요약
| 순서 | 작업 단위 | 주요 파일 | 구분 | 목적 |
|---|---|---|---|---|
| 1 | 좌측 하단 설정 영역 확장 지점 확보 | `BUSINESS_COMPONENTS_ROOT/src/ui/map/Gis.js`, `GisTree.js` | 최소 공통 확장 후보 | `GisTree` 아래에 설정 패널을 넣을 수 있는 optional slot 확보 |
| 2 | 노후관로 설정 패널 정리 | `SN_APP_ROOT/app/(map-layout)/map/components/agedPipe/AgedPipeLayerSettingPanel.tsx` | 구조 변경 | 지도 오버레이/시도/시군구 제거, 경과년도 단일 입력 + 초록 체크로 변경 |
| 3 | 노후관로 페이지 상태/이벤트 정리 | `SN_APP_ROOT/app/(map-layout)/map/page.tsx` | 구조 변경 | `Gis`, `GisTree`, 윈도우 팝업, 상세 팝업 연동의 중심 상태 관리 |
| 4 | 목록 윈도우 팝업 정리 | `AgedPipePopupPage.tsx`, `/map/aged-pipe-popup` | 스타일/동작 보완 | 기존 `UiTable`, `Button primary/green`, 목록 아이콘 호출 흐름 정리 |
| 5 | 상세 패널 기존화 | `AgedPipeDetailPanel.tsx`, `FeatureClickEventPopup.tsx`, `VerticalTable` | 대체/확장 검토 | 별도 slate 카드형 상세를 제거하고 기존 세로 테이블 톤으로 통합 |
| 6 | 유틸/필터 정리 | `agedPipeUtils.ts` | 유지/보완 | 경과년도 산정, CQL 필터, 표시값 매핑 유지 |
| 7 | 처리구역 분석 확장 | `FeatureClickEventPopup.tsx` 또는 신규 `AgedPipeAreaAnalysisSection.tsx` | 추가 | 하수처리구역 클릭 시 평균/최장/최신 매설년도 섹션 추가 |
| 8 | 검증 | 브라우저, build, 네트워크 | 검증 | 화면/지도/목록/상세/다운로드 회귀 확인 |
## 1. `Gis` / `GisTree` 확장 후보
### 현재 상태
- `Gis.js`는 내부에서 `GisTree`를 직접 렌더링한다.
- `GisTree.js`는 좌측 250px 패널 전체를 `grow overflow-y-auto` 트리 영역으로 사용한다.
- 현재 구조만으로는 트리 하단에 `경과년도(년) [30] [초록 체크]` 설정 박스를 자연스럽게 넣기 어렵다.
### 적용 결정
- `sn` 전용 임시 overlay가 아니라 `Gis`/`GisTree`의 optional slot 방식으로 진행한다.
- prop 이름은 `layerSettingView`를 사용한다.
- prop을 넘기지 않는 기존 사용처는 기존과 동일하게 동작한다.
### 작업 내용
- `Gis.js`에 optional prop을 추가한다.
- 이름: `layerSettingView`
- 기본값은 `undefined`로 두어 기존 앱 영향이 없게 한다.
- `GisTree.js`에 optional footer 영역을 렌더링한다.
- 상단 `시설물` 트리 영역과 하단 설정 영역을 같은 250px 패널 안에서 분리한다.
- 상단/하단 영역 모두 접힘/펼침 가능해야 한다.
- 기존 사용처는 prop을 넘기지 않으면 기존과 동일하게 동작해야 한다.
### 주의사항
- `business_components` 수정이므로 타 앱 영향 가능성을 반드시 점검한다.
- className 변경은 최소화하고, optional footer가 없을 때 기존 DOM 구조/스타일을 최대한 유지한다.
- 이 공통 확장이 부담되면 `sn` 전용으로 `Gis` 주변에 좌측 하단 패널을 겹쳐 배치하는 대안을 검토할 수 있으나, 화면설계서처럼 같은 좌측 패널 안에서 보이려면 optional slot 방식이 더 자연스럽다.
## 2. `AgedPipeFilterPanel.tsx`
### 현재 상태
- 지도 위 플로팅 카드 형태다.
- `경과년수`, `시도`, `시군구`, `GIS 반영` 버튼을 갖고 있다.
- 최종 확인 기준과 다르다.
### 변경 방향
- 이름은 유지하거나 `AgedPipeLayerSettingPanel.tsx`로 변경한다.
- 화면 구성은 아래처럼 단순화한다.
```text
지반침하정보 또는 노후관로
경과년도(년) [30] [초록 체크]
```
### 작업 내용
- `ctpvCd`, `sggCd` 선택 UI 제거.
- `GIS 반영` 텍스트 버튼 제거.
- 초록 원형 체크 아이콘 버튼으로 적용 액션 처리.
- `title` prop을 받아 `지반침하정보`, `노후관로` 등 대상 레이어명을 표시할 수 있게 한다.
- `elapsedYears` 값만 직접 입력받는다.
- Enter 입력과 체크 버튼 클릭 모두 `onApply`를 호출한다.
### props 후보
```ts
type AgedPipeLayerSettingPanelProps = {
title: string;
elapsedYears: number;
onElapsedYearsChange: (value: number) => void;
onApply: () => void;
defaultCollapsed?: boolean;
};
```
## 3. `page.tsx`
### 현재 상태
- `AgedPipeFilterPanel`을 `waterDepth` prop으로 넘겨 지도 오버레이처럼 표시한다.
- `AgedPipeDetailPanel`을 `detailView`로 사용한다.
- `getData`를 사용하지만 import가 보이지 않으므로 실제 빌드 전 확인이 필요하다.
- 샘플용 `DESIGN_PREVIEW_FEATURE`, 기본 목록 오픈 상태 등이 남아 있다.
### 변경 방향
- `Gis`에 `treeFooterView` 또는 `layerSettingView`를 넘겨 좌측 하단 설정 영역으로 렌더링한다.
- `waterDepth` prop은 침수심 애니메이션 목적이므로 노후관로 설정 패널 용도로 쓰지 않는다.
- 상세는 `AgedPipeDetailPanel` 단독 사용보다 기존 `FeatureClickEventPopup` 확장 또는 동일 `VerticalTable` 구조를 우선한다.
### 작업 내용
- `draftFilters`와 `appliedFilters`는 유지하되, 좌측 하단 패널에서는 `elapsedYears`만 수정한다.
- 시도/시군구는 목록 모달 조회조건에만 남긴다.
- 노후관로 목록 아이콘 클릭은 `GisTree`의 `onLayerIconClick`/`onOpenPopup` 흐름으로 연결한다.
- `handleTreePopup`은 `layerNm` 문자열 대신 실제 노드 정보 또는 `lyrTyNm` 기준으로 판정하는 방향을 검토한다.
- `DESIGN_PREVIEW_FEATURE`, 기본 `isListOpen=true`, 기본 `isDetailOpen=true`는 개발 완료 전 제거한다.
- `getData` import 누락 여부를 확인하고 실제 API 유틸 경로를 맞춘다.
## 4. 노후관로 현황 윈도우 팝업
### 현재 상태
- 노후관로 현황은 `/map/aged-pipe-popup` Next 라우트를 별도 윈도우 팝업으로 연다.
- 기존 `about:blank`에 React/CSS를 주입하던 방식은 dev CSS/chunk 404 위험 때문에 사용하지 않는다.
- 팝업 페이지는 자체적으로 목록 API를 조회하고 `UiTable`로 렌더링한다.
- 행 선택은 `window.opener.postMessage`로 부모 `/map`에 전달하여 지도 이동/상세 패널 표시를 수행한다.
### 변경 방향
- 지도 내부 Dialog/modal이 아니라 브라우저 밖 윈도우 팝업을 기본 동작으로 고정한다.
- 테이블은 현재처럼 `UiTable`을 계속 사용한다.
- 버튼 색상은 아래 기준으로 고정한다.
- 조회: `Button color="primary"`
- 다운로드: `Button color="green"`
- 팝업 내부 앱 버튼은 `최소화`만 유지한다. 닫기는 브라우저 창 X를 사용한다.
### 작업 내용
- 헤더 색상을 기존 primary blue 톤과 맞춘다.
- `/map/aged-pipe-popup`는 공통 `NoFooterLayout` 없이 목록 화면만 렌더링한다.
- 조회조건은 명세서대로 `경과년도`, `시도`, `시군구` 유지.
- 그리드 기본 정렬은 `경과년도 DESC`.
- 행 클릭은 부모 `/map`에 row를 전달하고 기존 `showSearchResultsFromGeoJSON` 위치 이동 흐름을 사용한다.
- 좌측 `노후관로 설정` 적용 시 열린 팝업에는 `SN_AGED_PIPE_FILTER_SYNC` 메시지를 보내 필터와 목록을 동기화한다.
- 팝업 `최소화` 클릭 시 부모 `/map`에 최소화 메시지를 보내고, 부모는 지도 위 최소화 카드를 표시한다.
- 최소화 카드의 `열기`는 다시 `/map/aged-pipe-popup` 윈도우 팝업을 실행한다.
- 다운로드는 `downloadExcelWithKoreanHeaders` 호출 유지하되, 5만 건 이상 비동기 처리 여부는 백엔드 API 매핑 단계에서 확정한다.
## 5. 상세 패널
### 현재 상태
- `AgedPipeDetailPanel.tsx`는 별도 slate 카드형 UI다.
- 실제 화면은 `FeatureClickEventPopup`의 파란 헤더 + `VerticalTable` 구조다.
### 변경 방향
- 우선순위 1: `FeatureClickEventPopup`에 노후관로 경과년도 필드만 추가해서 재사용한다.
- 우선순위 2: `FeatureClickEventPopup` 재사용이 어렵다면 `AgedPipeDetailPanel`을 `VerticalTable`과 동일한 구조로 다시 만든다.
### 작업 내용
- `AGED_PIPE_DETAIL_FIELDS`는 기존 `MsSwagePplCol` 기반을 유지한다.
- `경과년도` 계산 필드를 상세 테이블 마지막에 추가한다.
- 상세 헤더는 `하수관로 정보 / 관리번호 : {시설관리번호}` 흐름을 따른다.
- `침입수분석`, `RDII분석` 버튼은 기존 `FeatureClickEventPopup`의 하수관로 조건부 버튼을 그대로 사용한다.
## 6. `agedPipeUtils.ts`
### 유지할 항목
- `getElapsedYears`
- `getCutoffYmd`
- `buildAgedPipeCqlFilters`
- `matchesAgedPipeFilters`
- `toDisplayPipeRow`
- 코드 매핑: `MS_SWAGE_PPL_USE_CODES`, `MS_SWAGE_PPL_CODES`
### 보완할 항목
- `AgedPipeFilters`는 전체 상태로는 `elapsedYears`, `ctpvCd`, `sggCd`를 유지하되 좌측 하단 설정 패널에서는 `elapsedYears`만 다룬다.
- 설치일자 NULL이면 `확인불가` 그룹으로 분류할 수 있는 유틸을 추가한다.
- 미래 설치일자 방어 로직을 추가한다.
- 엑셀 다운로드용 전체 필드 매핑은 API 매핑 단계에서 확정한다.
## 7. 노후관로분석 화면
### 구현 위치 후보
- 기존 하수처리구역 클릭 상세: `FeatureClickEventPopup`
- 처리구역 전용 부가 섹션: 신규 `AgedPipeAreaAnalysisSection.tsx`
### 작업 내용
- 하수처리구역 피처 클릭 시 기존 기본정보는 유지한다.
- 기본정보 아래에 `하수관로 분석정보` 섹션을 추가한다.
- 평균/최장/최신 매설년도는 `VerticalTable` 또는 기존 테이블 톤으로 표시한다.
- `보수이력` 링크/버튼은 기존 `Button` 톤을 사용한다.
- 처리구역 내 관로 0건이면 명세서 문구를 표시한다.
## 8. 검증 목록
| 구분 | 확인 내용 |
|---|---|
| 화면 | Header/LNB/GisTree/상세 팝업이 기존 화면과 같은 위치와 톤인지 확인 |
| 좌측 설정 | `시설물` 영역과 하단 설정 영역이 각각 접힘/펼침 되는지 확인 |
| 입력 | 하단 설정 영역은 `경과년도(년)` 단일 입력만 노출되는지 확인 |
| 레이어 | 노후관로 체크 ON/OFF 시 지도 스타일만 바뀌고 기존 하수관로 레이어가 사라지지 않는지 확인 |
| 목록 | 노후관로 목록 아이콘 클릭 시 `/map/aged-pipe-popup` 윈도우 팝업이 열리는지 확인 |
| 버튼 | 목록 윈도우 팝업 `조회=primary`, `다운로드=green`인지 확인 |
| 상세 | 지도 관로 클릭 및 팝업 목록 행 클릭 시 기존 상세 팝업 톤으로 표시되는지 확인 |
| 다운로드 | 조회 결과 엑셀 다운로드가 동작하는지 확인 |
| 빌드 | `pnpm --filter @common/business_components run build`, `pnpm --filter sn run build` |
## 권장 구현 순서
1. `AgedPipeFilterPanel`을 단일 입력 설정 패널로 먼저 정리한다.
2. `Gis`/`GisTree`에 optional footer slot을 추가할지, `sn` 전용 좌측 패널 조합으로 갈지 결정한다.
3. `page.tsx`에서 지도 오버레이 방식(`waterDepth`)을 제거하고 좌측 설정 영역으로 연결한다.
4. `/map/aged-pipe-popup` 윈도우 팝업을 기존 버튼/테이블 톤에 맞춘다.
5. 상세는 `FeatureClickEventPopup` 재사용 가능성을 먼저 구현 검토한다.
6. 노후관로분석의 처리구역 분석 섹션을 추가한다.
7. 브라우저에서 화면설계서 기준 ①~④ 동작을 확인한다.
## 2026-04-23 추가 보완 작업
| 순서 | 보완 항목 | 주요 파일 | 처리 방향 |
|---|---|---|---|
| 1 | 상세 기본정보 헤더 경과년도 표시 | `FeatureClickEventPopup.tsx`, `agedPipeUtils.ts` | 하수관로 상세의 `기본정보` 옆에 `경과년도 n년` 배지를 표시한다. |
| 2 | 경과년도 인라인 입력 안정화 | `page.tsx`, `AgedPipeLayerSettingPanel.tsx`, `GisTree.js` | 입력 중 컴포넌트 재마운트로 포커스가 끊기지 않도록 inline setting 렌더링을 React node 방식으로 안정화한다. |
| 3 | 목록을 윈도우 팝업으로 변경 | `AgedPipePopupPage.tsx`, `/map/aged-pipe-popup` | Dialog modal 또는 지도 내부 fixed popup 대신 별도 Next 라우트를 브라우저 윈도우 팝업으로 표시한다. |
| 4 | 오수관/노후관로 색상 분리 | `tb_sn_lyr_stng`, `DB/001-노후관로-레이어설정.md` | 오수관은 주황색, 노후관로 강조선은 빨간색으로 구분한다. |
| 5 | sentinel 설치일자 제외 | `agedPipeUtils.ts` | `1900-01-01`, `1999-01-01`로 등록된 설치일자는 조회 CQL과 경과년도 계산에서 제외한다. |
| 6 | 노후관로 줌 레벨 기준 명시 | `page.tsx`, `agedPipeUtils.ts` | 노후관로 강조 레이어 표출 기준은 `minViewSize = 14`로 관리한다. |
| 7 | 윈도우 팝업 상태 연동 | `page.tsx`, `AgedPipePopupPage.tsx` | 좌측 설정 적용, 목록 행 선택, 최소화 상태를 `postMessage`로 부모 지도와 팝업 사이에 동기화한다. |
| 8 | 선택 관로 시각 강조 | `BUSINESS_COMPONENTS_ROOT/src/ui/map/lib/gis.select.js` | 선택된 선 피처에 다중 stroke(soft glow, white halo, violet core, highlight)를 적용한다. |
apps/sn/docs/노후관로관리/03-API응답필드매핑표.md
-73
View File
@@ -1,73 +0,0 @@
# 노후관로관리 API 응답 필드 매핑표
## 목적
노후관로관리 화면에서 사용할 API와 응답 필드를 화면 컴포넌트 기준으로 매핑한다.
이 문서는 다음 단계에서 상세 작성한다.
## API 목록
| 구분 | Method | Endpoint | 사용 컴포넌트 | 상태 |
|---|---|---|---|---|
| 레이어 설정 | GET | `/sewerage-service/api/v1/map/lyrStngs/SN_NETWORK` | `Gis`, `GisTree` | 기존 |
| 관로 목록 | GET | `v1/fclts?lyrTypeNm=tb_ms_swage_ppl&cqlFiter=...` | `AgedPipePopupPage`, `UiTable` | 기존 재사용, 백엔드 검증 필요 |
| 관로 상세 | GET | `v1/fcltppl/{fcltMngNo}/{mngInstCd}` | `FeatureClickEventPopup`, `VerticalTable` | 기존 재사용 |
| 엑셀 다운로드 | GET + 프론트 생성 | `v1/fclts?lyrTypeNm=tb_ms_swage_ppl&cqlFiter=...` | `AgedPipePopupPage` | 임시 재사용 |
| 위치 이동 | WFS/GeoServer | `tb_ms_swage_ppl.{fid}` | `GisApp.Module.layer.showSearchResultsFromGeoJSON` | `fid` 계약 검증 필요 |
| 처리구역 분석 | - | 미확정 | 분석정보 섹션 | 확인 필요 |
| 보수이력 | - | 미확정 | 보수이력 버튼/팝업 | 확인 필요 |
## 조회 조건 매핑
| 조건 | 화면 기본값 | API 전달 방식 | 비고 |
|---|---:|---|---|
| 경과년도 | 30 | `instl_ymd <= '{오늘 기준 경과년도 차감일자}'` CQL | 사용자 지시 기준. 요구사항 원문/기존 문서의 20년과 차이가 있어 30년으로 보정 |
| 시도 | 전체 | `pbadms_emd_cd LIKE '{ctpvCd}%'` | 시군구가 전체일 때만 적용 |
| 시군구 | 전체 | `pbadms_emd_cd LIKE '{sggCd}%'` | 시군구 선택 시 시도 조건보다 우선 |
### 제외 조건
설치일자가 실제 null 대신 sentinel 값으로 적재된 데이터는 노후관로 목록/강조선 조회에서 제외한다.
| 제외 대상 | API 전달 방식 | 비고 |
|---|---|---|
| 설치일자 없음 | `instl_ymd IS NOT NULL` | CQL 기본 조건 |
| `1900-01-01` | `instl_ymd NOT LIKE '19000101%'` | 원본 `19000101 ` 형태 대응 |
| `1999-01-01` | `instl_ymd NOT LIKE '19990101%'` | null 대체값으로 등록된 데이터 제외 요청 반영 |
## 필드 매핑
| 화면 영역 | 표시명 | 응답 필드 | 변환/코드매핑 | 빈 값 처리 | 비고 |
|---|---|---|---|---|---|
| 목록 | 시설관리번호 | `fclt_mng_no`, `fcltMngNo` | 문자열 | `-` | |
| 목록 | 관리기관코드 | `mng_inst_cd`, `mngInstCd` | 문자열 | `-` | 상세 API path 변수 |
| 목록 | GeoServer Feature ID | `fid` | 문자열 | 필수 | 목록 행 클릭 위치 이동 기준 |
| 목록 | 설치일자 | `instl_ymd`, `instlYmd` | 날짜 표시 | `확인불가` | 경과년도 산정 기준 |
| 목록 | 관경(mm) | `pdmt_vl`, `pdmtVl` | 숫자 | `-` | |
| 목록 | 연장(m) | `prlg_vl`, `prlgVl` | 숫자 | `-` | |
| 목록 | 용도 | `usg_cd`, `usgCd` | `MS_SWAGE_PPL_USE_CODES` | `-` | |
| 목록 | 재질 | `mqlt_cd`, `mqltCd` | `MS_SWAGE_PPL_CODES` | `-` | |
| 목록/상세 | 경과년도 | 설치일자 기반 계산 | `현재연도 - 설치연도` | `확인불가` | 백엔드 필드 여부 확인 필요 |
## 현재 확정
- 노후관로 목록은 기존 `GET v1/fclts?lyrTypeNm=tb_ms_swage_ppl&cqlFiter=...`를 재사용한다.
- `cqlFiter` 오탈자 파라미터를 유지하되, 백엔드는 `cqlFilter`도 호환한다.
- 노후관로 전용 신규 API는 만들지 않는다.
- 상세 기본정보 헤더에는 설치일자 기반 경과년도를 배지 형태로 함께 표시한다.
- 노후관로 현황은 `/map/aged-pipe-popup` 윈도우 팝업에서 자체 조회한다.
- 부모 지도와 팝업 간 상태 동기화는 API가 아니라 `postMessage`로 처리한다.
- `SN_AGED_PIPE_ROW_SELECT`: 팝업 목록 행 선택 row를 부모 지도에 전달
- `SN_AGED_PIPE_FILTER_SYNC`: 부모 좌측 설정의 적용 필터를 열린 팝업에 전달
- `SN_AGED_PIPE_POPUP_MINIMIZE`: 팝업 최소화 상태를 부모 지도에 전달
## 미확인사항
- 기존 `v1/fclts`로 1차 구현은 가능하나 운영 기준 전용 API가 필요한지 백엔드에서 판단 필요
- `cqlFiter` 파라미터명 오탈자 호환 여부 확인 필요
- `cqlFiter`를 문자열로 받는 경우 허용 필드와 연산자 제한 필요
- 경과년도 계산을 프론트에서 계속 할지, 백엔드 응답 필드로 받을지 확인 필요
- `fid`가 GeoServer `FEATUREID`와 항상 일치하는지 확인 필요
- `mngInstCd`가 없는 노후관로 행에서 상세 API를 어떻게 처리할지 확인 필요
- 엑셀 다운로드는 현재 프론트 유틸로 1만 건까지 생성하며, 5만 건 이상 서버 비동기 파일 API 필요 여부 확인 필요
- 처리구역 분석 통계를 프론트 계산으로 할지, 백엔드 API로 받을지
apps/sn/docs/노후관로관리/04-화면흐름.md
-40
View File
@@ -1,40 +0,0 @@
# 노후관로관리 화면흐름
## 목적
사용자 이벤트와 화면 상태 변화를 정리한다.
## SN_MN010102 노후관로관리
| 트리거 | 동작 | 결과 |
|---|---|---|
| 화면 진입 | `Gis` 초기화, `SN_NETWORK` 레이어 설정 조회 | 지도와 시설물 트리 표시 |
| 노후관로 체크 ON | 경과년도 기준에 맞는 관로 스타일 강조 | 지도에 노후관로 표출 |
| 좌측 하단 경과년도 적용 | 기준값 갱신, 레이어 스타일 재적용, 열린 윈도우 팝업에 필터 동기화 메시지 전송 | 지도/목록 조건 갱신 |
| 노후관로 목록 아이콘 클릭 | `/map/aged-pipe-popup` 윈도우 팝업 오픈 | `UiTable` 목록 표시 |
| 목록 조회 | 경과년도/시도/시군구 조건 조회 | 목록 갱신 |
| 목록 다운로드 | 조회 결과 다운로드 | 엑셀 또는 파일 응답 |
| 목록 행 클릭 | `postMessage`로 부모 지도에 row 전달 | 지도 위치 이동, `FeatureClickEventPopup` 표시 |
| 팝업 최소화 | 팝업에서 최소화 메시지 전송 후 창 닫기 | 지도 위 최소화 카드 표시 |
| 최소화 카드 열기 | `/map/aged-pipe-popup` 윈도우 팝업 재오픈 | 동일 조건의 목록 표시 |
| 지도 관로 클릭 | 피처 선택 | 상세정보 표시 |
## 2026-04-23 보완 흐름
| 트리거 | 동작 | 결과 |
|---|---|---|
| 경과년도 입력 | 로컬 입력 상태만 변경 | 입력 중 포커스 유지 |
| 경과년도 적용 버튼 또는 Enter | 적용 조건 확정, CQL 재생성, 열린 팝업 목록 재조회 | 노후관로 강조 레이어와 윈도우 팝업 목록 갱신 |
| 목록 팝업 열기 | 실제 Next 라우트 `/map/aged-pipe-popup` 실행 | 브라우저 밖 윈도우 팝업으로 동작 |
| 상세 패널 표시 | 설치일자 기반 경과년도 계산 | `기본정보` 옆에 경과년도 배지 표시 |
| 노후관로 조회 | sentinel 설치일자 제외 조건 추가 | `1900-01-01`, `1999-01-01` 데이터 제외 |
| 노후관로 체크 ON | `minViewSize = 14` 기준 강조 레이어 추가 | 줌 레벨 14 이상에서 일반 노후관로 강조선 확인 |
| 선택 관로 표시 | 선 피처 선택 스타일 적용 | 다중 stroke로 보라색 선택선 강조 |
## SN_MN010103 노후관로분석
| 트리거 | 동작 | 결과 |
|---|---|---|
| 화면 진입 | 하수처리구역 레이어 표시 | 분석 대상 구역 확인 |
| 처리구역 클릭 | 구역 기본정보 및 관로 분석정보 조회/계산 | 우측 상세 패널 표시 |
| 보수이력 클릭 | 보수이력 팝업 또는 화면 호출 | 이력 목록 표시 |
apps/sn/docs/노후관로관리/05-검증계획.md
-39
View File
@@ -1,39 +0,0 @@
# 노후관로관리 검증계획
## 브라우저 검증
| 항목 | 확인 내용 | 상태 |
|---|---|---|
| 기존 레이아웃 | Header/LNB/GisTree/상세 패널 위치가 기존 화면과 같은지 확인 | 대기 |
| 좌측 설정 | 하단 경과년도 설정 영역이 좌측 패널 내부에 표시되는지 확인 | 대기 |
| 접힘/펼침 | 시설물 영역과 설정 영역이 각각 접히고 펼쳐지는지 확인 | 대기 |
| 노후관로 체크 | 체크 ON/OFF 시 레이어 강조가 바뀌는지 확인 | 대기 |
| 목록 윈도우 팝업 | 목록 아이콘 클릭 시 `/map/aged-pipe-popup`이 브라우저 밖 윈도우 팝업으로 열리는지 확인 | 대기 |
| 버튼 색상 | 조회 primary, 다운로드 green 톤인지 확인 | 대기 |
| 상세 연동 | 지도 클릭/팝업 목록 행 클릭 시 상세 패널 표시 | 대기 |
| 상세 경과년도 | 하수관로 상세 `기본정보` 옆에 경과년도 배지가 표시되는지 확인 | 대기 |
| 경과년도 입력 안정성 | 숫자 연속 입력 중 포커스가 유지되고 적용/Enter 후 조건이 반영되는지 확인 | 대기 |
| 설정-팝업 동기화 | 좌측 `노후관로 설정` 적용 시 열린 윈도우 팝업의 경과년도/목록이 같이 갱신되는지 확인 | 대기 |
| 팝업 최소화 | 윈도우 팝업의 `최소화` 클릭 시 지도 위 최소화 카드가 표시되고 `열기`로 다시 윈도우 팝업이 열리는지 확인 | 대기 |
| 설치일자 제외 | `1900-01-01`, `1999-01-01` 데이터가 목록/강조선 조회에서 제외되는지 확인 | 대기 |
| 색상 구분 | 오수관은 주황색, 노후관로 강조선은 빨간색으로 구분되는지 확인 | 대기 |
| 줌 레벨 | 줌 레벨 14 이상에서 노후관로 강조선이 표시되는지 확인 | 대기 |
| 선택 관로 강조 | 선택된 관로가 soft glow/white halo/violet core 다중 stroke로 지도 위에서 명확히 보이는지 확인 | 대기 |
| dev CSS/chunk 404 | 팝업 실행 후 `/_next/static/css/app/layout.css?...` 404 반복 호출이 발생하지 않는지 확인 | 대기 |
## 빌드 검증
```powershell
pnpm --filter @common/business_components run build
pnpm --filter sn run build
```
`business_components`를 수정하지 않는 경우 `sn` 빌드만 우선 수행한다.
## 네트워크 검증
- 레이어 설정 조회
- 관로 목록 조회
- 관로 상세 조회
- 다운로드 요청
- 처리구역 분석 요청 또는 계산용 데이터 조회
apps/sn/docs/노후관로관리/06-검증결과.md
-114
View File
@@ -1,114 +0,0 @@
# 노후관로관리 검증결과
## 2026-04-22 구현 후 빌드 검증
| 구분 | 명령 | 결과 | 비고 |
|---|---|---|---|
| 공통 비즈니스 컴포넌트 | `pnpm --filter @common/business_components run build` | 성공 | `Gis`, `GisTree` optional 확장 포함 |
| sn 앱 | `pnpm --filter sn run build` | 성공 | Next 컴파일/페이지 생성 성공 |
## 남은 검증
- 브라우저에서 `/map` 진입 후 실제 `SN_NETWORK` 응답에 `노후관로` 노드가 내려오는지 확인
- 노후관로 체크 ON/OFF 시 좌측 하단 설정 컴포넌트 표시/숨김 확인
- 노후관로 목록 아이콘 클릭 시 현황 모달 표시 확인
- `v1/fclts`의 `cqlFiter` 조건이 경과년도/시도/시군구 조합대로 동작하는지 네트워크 확인
- 지도 halo 강조가 기존 하수관로 선 색상을 덮지 않는지 브라우저 확인
- 목록 행 더블클릭 시 지도 이동과 `FeatureClickEventPopup` 상세 표시 확인
## 특이사항
- `sn` 빌드 마지막 단계에서 Windows symlink 권한으로 standalone trace 복사 경고가 발생했지만, Next 빌드 자체는 성공했다.
## 2026-04-23 보완 검증
| 구분 | 확인 내용 | 결과 | 비고 |
|---|---|---|---|
| 상세 경과년도 | 하수관로 상세 `기본정보` 헤더 옆 경과년도 배지 추가 | 반영 | `FeatureClickEventPopup`에서 `elapsedYears` 계산값 표시 |
| 경과년도 입력 안정화 | 좌측 인라인 설정 입력 중 재마운트 방지 | 반영 | `GisTree`가 React node inline view를 렌더링하도록 보완 |
| 목록 윈도우 팝업 | 노후관로 현황을 Dialog modal 대신 드래그 가능한 fixed popup으로 표시 | 반영 | `AgedPipeListModal`에서 헤더 pointer drag 처리 |
| sentinel 설치일자 제외 | `1900-01-01`, `1999-01-01` 데이터 제외 | 성공 | CQL 조건 API 200, 결과 첫 5건 sentinel 미포함 |
| 오수관 색상 | 일반 오수관 색상을 주황색으로 변경 | 성공 | `lyr_sn=6`, `line_colr=rgba(255, 128, 0, 1)` 확인 |
| 노후관로 줌 레벨 | 노후관로 강조 레이어 최소 줌 기준 | 확인 | `AGED_PIPE_MIN_ZOOM=14`, `minViewSize=14` |
| 공통 컴포넌트 빌드 | `business_components` 빌드 | 성공 | `pnpm --filter @common/business_components run build` |
| `sn` 앱 빌드 | `sn` 빌드 | 성공 | Next 컴파일/페이지 생성 성공. standalone symlink 권한 경고 발생 |
## 2026-04-23 추가 UX 보완 검증
| 구분 | 확인 내용 | 결과 | 비고 |
|---|---|---|---|
| 브라우저 밖 팝업 | 노후관로 현황을 열 때 처음부터 별도 창으로 표시 | 반영 | 사용자 클릭 시점에 `/map/aged-pipe-popup` Next 페이지를 `window.open`으로 실행 |
| 새 창 렌더링 | 별도 창을 실제 Next 라우트로 분리 | 반영 | `about:blank`에 React/CSS를 주입하던 방식 제거. `/map/aged-pipe-popup`에서 목록 자체 조회/렌더링 |
| 팝업 동작 기준 | 노후관로 현황 기본 동작을 별도 윈도우 팝업으로 고정 | 반영 | `새 창`/`지도 안으로` 전환 버튼 제거. 팝업 내부 앱 버튼은 `최소화`만 유지 |
| 새 창 CSS 404 방지 | 새 창 CSS 복제 방식 제거 | 반영 | `/_next/static/css/app/layout.css?...` dev 404 반복 호출 방지를 위해 stylesheet 복사/주입 구조 제거 |
| 목록 행 선택 연동 | 새 창 목록 행 클릭 시 부모 지도 화면으로 선택 row 전달 | 반영 | `window.opener.postMessage`로 row를 전달하고 부모 `/map`에서 위치 이동/상세 패널 표시 |
| 최소화 카드 기준 | 팝업에서 `최소화` 클릭 시 지도 위 최소화 카드 표시 | 반영 | 최소화 카드의 `열기`는 다시 `/map/aged-pipe-popup` 윈도우 팝업을 실행 |
| 지도 설정-팝업 필터 동기화 | 좌측 `노후관로 설정` 적용 시 열린 윈도우 팝업 목록도 재조회 | 반영 | 부모 `/map`에서 `SN_AGED_PIPE_FILTER_SYNC` 메시지 전송, 팝업에서 필터/목록 1페이지 갱신 |
| 선택 관로 시각 강조 | 선택된 선 피처 스타일 개선 | 반영 | soft violet glow, white halo, violet core, lavender highlight 다중 stroke 적용 |
| dev CSS/chunk 404 복구 | dev 서버 중 `next build` 실행으로 `.next` 산출물 혼재 발생 | 조치 | `apps/sn/.next` 삭제 후 dev 서버 재시작 필요. dev 실행 중에는 `next build` 병행 금지 |
| 줌 레벨 기준 | 노후관로 강조 레이어 표시 시작 줌 레벨 | 확인 | `AGED_PIPE_MIN_ZOOM=14`, `minViewSize=14` |
| 지도 표시 원복 | 추가 안내 배지/범례/강조선 스타일 변경 제거 | 반영 | `lnWdth=4`, `lnColor=rgba(235, 40, 40, 0.82)` 유지 |
| 서버 상태 | 백엔드/프론트 포트 확인 | 성공 | `localhost:8883`, `localhost:3002` TCP 연결 성공 |
| `/map` 응답 | 프론트 `/map` HTTP 응답 확인 | 성공 | `GET http://localhost:3002/map` 200 OK |
| `sn` 앱 빌드 | 변경 후 `sn` 빌드 | 성공 | Next 컴파일/페이지 생성 성공. standalone symlink 권한 경고 발생 |
| TypeScript 검사 | `pnpm --filter sn exec tsc --noEmit --pretty false` | 기존 오류 잔존 | 이번 변경 신규 오류는 해소. 기존 `common/index.ts`, `html/(with-base-layout)`, chart implicit any 오류 잔존 |
### 브라우저 검증 제약
- 현재 workspace에 Playwright CLI가 설치되어 있지 않아 자동 브라우저 조작 검증은 수행하지 못했다.
- 실행 중인 Chrome은 remote debugging port가 열려 있지 않았다.
- Headless Chrome 스크린샷은 임시 브라우저 세션 특성상 사용자 로그인/지도 리소스 상태를 재현하지 못해 최종 UI 증적으로 사용하지 않았다.
### API 검증
```text
GET /sewerage-service/api/v1/fclts
?lyrTypeNm=tb_ms_swage_ppl
&cqlFiter=instl_ymd IS NOT NULL
and instl_ymd NOT LIKE '19000101%'
and instl_ymd NOT LIKE '19990101%'
and instl_ymd <= '19960423'
&page=0
&size=5
```
결과:
```text
status=200
count=735119
첫 5건 설치일자: 19730731, 19830331, 19690630, 19870509, 19841020
```
### DB 검증
```text
lyr_sn=6
lyr_nm=오수관
line_colr=rgba(255, 128, 0, 1)
```
## 검증 개요
| 항목 | 내용 |
|---|---|
| 검증 일자 | 2026-04-22 |
| 검증자 | Codex |
| 대상 화면 | SN_MN010102, SN_MN010103 |
| 실행 URL | 빌드 검증 기준 |
| 브라우저 | 미수행 |
## 검증 결과
| 항목 | 결과 | 증적 | 비고 |
|---|---|---|---|
| 공통 비즈니스 컴포넌트 빌드 | 성공 | `pnpm --filter @common/business_components run build` | `startOfMonth` unused 경고는 기존 빌드 경고로 보임 |
| `sn` 앱 빌드 | 성공 | `pnpm --filter sn run build` | 종료 코드 0. Windows symlink 권한 경고 발생 |
| 타입 검사 | 부분 실패 | `pnpm --filter sn exec tsc --noEmit` | 신규 `layerSettingView` 관련 오류는 해소. 기존 `SwtrmtFclt`, `with-base-layout`, chart implicit any 오류 잔존 |
| HTML/코드 공백 검사 | 성공 | `git diff --check` | 관련 수정 파일 기준 |
## 남은 리스크
- 브라우저에서 `/map` 실제 화면 조작 검증은 사용자가 최종 확인해야 한다.
- `tsc --noEmit`의 기존 타입 오류는 별도 정리가 필요하다.
- Next standalone trace 중 symlink 권한 경고가 있어 Windows 개발 환경 권한 확인이 필요하다.
apps/sn/docs/노후관로관리/07-백엔드-착수프롬프트.md
-55
View File
@@ -1,55 +0,0 @@
# 노후관로관리 백엔드 착수 프롬프트
아래 프롬프트는 새 스레드에서 백엔드 작업을 시작할 때 그대로 사용한다.
```text
WORKSPACE_ROOT=C:\mindone_project\iipbs-workspace 기준으로 작업해줘.
프론트 노후관로관리 1차 구현은 마무리했고, 이제 sewerage-service 백엔드 계약 정리와 보강을 시작하려고 한다.
반드시 먼저 아래 AGENTS.md를 확인해줘.
- WORKSPACE_ROOT/AGENTS.md
- WORKSPACE_ROOT/IIPBS/sewerage-service/AGENTS.md
- WORKSPACE_ROOT/frontend/apps/sn/AGENTS.md
이번 백엔드 작업의 기준 문서는 아래야.
- IIPBS/sewerage-service/docs/AI코딩하네스/작업계획/001-BE-P2-노후관로관리-작업카드.md
- frontend/apps/sn/app/html/06. 노후관로관리_시나리오_v1.0.md
- frontend/apps/sn/docs/노후관로관리/03-API응답필드매핑표.md
- frontend/apps/sn/docs/노후관로관리/99-미확인사항.md
현재 프론트에서 확정된 동작은 다음과 같아.
1. /map 좌측 레이어 트리 최상위 순서는 시설, 침수위험지도(중점관리지역), 도시침수지도(정보제공포털), 노후관로 순서다.
2. 노후관로는 기존 하수관로 시설물 레이어와 별도 제어 항목이다.
3. 노후관로 체크 시 경과년도/지역 조건에 맞는 하수관로를 지도에 빨간 강조선으로 표출한다.
4. 노후관로 항목 바로 아래 인라인 설정으로 경과년도(기본 30년)를 입력한다.
5. 노후관로 목록은 GET v1/fclts?lyrTypeNm=tb_ms_swage_ppl&cqlFiter=... 를 현재 재사용한다.
6. 목록 행 클릭 시 GeoServer FEATUREID(fid)로 위치 이동하고, GET v1/fcltppl/{fcltMngNo}/{mngInstCd} 상세를 우측 패널에 표시한다.
7. 목록 필수 필드는 fid, fcltMngNo/fclt_mng_no, mngInstCd/mng_inst_cd, instlYmd/instl_ymd, pdmtVl/pdmt_vl, prlgVl/prlg_vl, usgCd/usg_cd, mqltCd/mqlt_cd 이다.
백엔드에서 우선 확인/정리할 것은 다음이야.
1. GET /api/v1/fclts 구현 위치와 파라미터 처리 방식 확인
2. cqlFiter 파라미터명 오탈자 호환 여부 확인 또는 cqlFilter와의 호환 처리 방안 제안
3. CQL 문자열 직접 전달 시 허용 필드/연산자 제한 또는 안전한 검색 DTO로 전환 가능성 검토
4. instl_ymd <= cutoff, pbadms_emd_cd LIKE 조건이 tb_ms_swage_ppl 기준으로 정상 동작하는지 확인
5. 목록 응답 fid가 GeoServer FEATUREID로 사용 가능한지 확인
6. mngInstCd 누락 행이 있을 때 상세 API 처리 방식 확인
7. tb_sn_lyr_stng에 정식 노후관로 레이어 설정을 넣는 것이 맞는지 분석
8. 필요하면 노후관로 전용 read-only API를 설계하되 기존 프론트/기존 API 계약은 깨지 않게 해줘.
작업 방식:
- 먼저 코드와 문서를 읽고 영향 범위를 정리해줘.
- DB 스키마 변경은 기본적으로 하지 말고, 필요한 경우 이유/영향/롤백을 먼저 정리해줘.
- 백엔드 변경이 필요하면 최소 범위로 구현해줘.
- 가능한 테스트나 API 검증 방법을 함께 제시해줘.
결과 보고는 아래 형식으로 해줘.
- 작업 목적
- 수정 대상 파일
- 변경 내용 요약
- 영향 범위
- 테스트 / 검증 방법
- 롤백 방법
- 남은 리스크
```
apps/sn/docs/노후관로관리/99-미확인사항.md
-27
View File
@@ -1,27 +0,0 @@
# 노후관로관리 미확인사항
| 일자 | 구분 | 내용 | 확인 필요 대상 | 상태 |
|---|---|---|---|---|
| 2026-04-22 | BE | `v1/fclts`의 `cqlFiter` 파라미터명 오탈자 호환 여부 | BE | 확인 필요 |
| 2026-04-22 | BE | CQL 문자열 직접 전달 방식의 허용 필드/연산자 제한 여부 | BE | 확인 필요 |
| 2026-04-22 | BE | 목록 응답 `fid`가 GeoServer `FEATUREID` 위치 이동에 항상 사용 가능한지 | BE/GeoServer | 확인 필요 |
| 2026-04-22 | BE | `mngInstCd` 누락 행의 상세 API 처리 방식 | BE | 확인 필요 |
| 2026-04-22 | BE | `tb_sn_lyr_stng`에 정식 노후관로 레이어 설정을 추가할지 여부 | BE/DB | 확인 필요 |
| 2026-04-22 | BE | 대량 엑셀 다운로드를 프론트 생성으로 유지할지 서버 파일 API로 전환할지 | BE/FE | 확인 필요 |
| 2026-04-23 | FE | 상세 패널 기본정보 헤더에 노후관로 경과년도 표시 | FE | 반영 |
| 2026-04-23 | FE | 경과년도 입력 중 포커스 끊김/적용 누락 문제 | FE | 반영, 브라우저 검증 필요 |
| 2026-04-23 | FE | 노후관로 현황 목록을 모달이 아닌 윈도우형 팝업으로 표시 | FE | 반영, 브라우저 검증 필요 |
| 2026-04-23 | DB/FE | 오수관 색상을 주황색으로 변경하고 노후관로 빨간 강조선과 구분 | DB/FE | DB 반영 |
| 2026-04-23 | FE | `1900-01-01`, `1999-01-01` sentinel 설치일자 제외 | FE | 반영, API 검증 필요 |
| 2026-04-23 | FE | 노후관로 강조 레이어 표출 줌 레벨 기준 | FE | `minViewSize=14` 확인 |
| 2026-04-23 | FE | 윈도우 팝업과 지도 좌측 설정의 경과년도 조건 동기화 | FE | 반영, 브라우저 검증 필요 |
| 2026-04-23 | FE | 팝업 최소화/복원 기준 | FE | 팝업 `최소화` 클릭 시만 최소화 카드 표시로 반영 |
| 2026-04-23 | FE | 선택 관로 보라색 강조선 시각 개선 | FE/공통컴포넌트 | 반영, 브라우저 검증 필요 |
## 우선 확인 대상
- 기존 `v1/fclts`의 필터 조건으로 경과년도/지역 조회를 모두 처리할 수 있는지
- 경과년도 기준값 저장/로그 API가 필요한지
- 처리구역 분석 통계를 프론트 계산으로 할지 백엔드 API로 받을지
- 엑셀 다운로드 5만 건 이상 처리 방식
- 지반침하정보도 노후관로와 같은 인라인 설정 확장 포인트를 사용하되, 백엔드 API/레이어 설정은 별도 확정 필요
apps/sn/docs/노후관로관리/README.md
-32
View File
@@ -1,32 +0,0 @@
# 노후관로관리 문서
## 목적
노후관로관리 및 노후관로분석 화면을 `sn` 기존 화면/컴포넌트 기준으로 구현하기 위한 기능별 산출물 묶음이다.
## 대상 화면
| 화면 ID | 화면명 | 메뉴 경로 |
|---|---|---|
| `SN_MN010102` | 노후관로관리 | 하수관망도 > 노후관로관리 |
| `SN_MN010103` | 노후관로분석 | 하수관망도 > 노후관로분석 |
## 문서 순서
| 문서 | 역할 |
|---|---|
| `00-범위.md` | 기능 범위와 제외 범위 |
| `01-기존화면기반-컴포넌트분해.md` | 기존 화면 기준 영역/컴포넌트/색상 분해 |
| `02-컴포넌트별-작업목록.md` | 실제 구현 전 작업 단위 목록 |
| `03-API응답필드매핑표.md` | API와 화면 표시 필드 매핑 |
| `04-화면흐름.md` | 사용자 이벤트와 화면 상태 흐름 |
| `05-검증계획.md` | 구현 후 검증 계획 |
| `06-검증결과.md` | 검증 수행 결과 |
| `99-미확인사항.md` | 남은 질문과 의사결정 대기 항목 |
## 작성 기준
- 실제 React 구현은 기존 `NoFooterLayout`, `Gis`, `GisTree`, `FeatureClickEventPopup`, `VerticalTable`, `UiTable` 흐름을 우선한다.
- 백엔드 상세 구현은 작성하지 않고, 필요한 API/필드/응답 사용 방식만 매핑한다.
- 화면설계서와 다른 독립 디자인을 만들지 않는다.