Merge branch 'main' of https://www.onasys.co.kr:3000/ONAANDALL/frontend into deploy

apps/sn/.env.local

@@ -12,8 +12,7 @@ NEXT_PUBLIC_LX_GEOSERVER_URL = http://con.mind-one.co.kr:11306/geoserver
 NEXT_PUBLIC_NGII_URL = https://map.ngii.go.kr
 NEXT_PUBLIC_NGII_PARAM = 04trYP9_xwLAfALjwZ-B8g&service=WMTS&request=GetTile&version=1.0.0&format=image/png&layer=korean_map&style=korean&tilematrixset=korean&tilematrix={z}&tilecol={x}&tilerow={y}
 NEXT_PUBLIC_SERVER_API_URL = http://dev.onasys.co.kr:8000
-NEXT_PUBLIC_SEWERAGE_API_URL = http://con.mind-one.co.kr:11083
 NEXT_PUBLIC_DC_URL     = https://apigateway.apps.rsonesoft.com
 # NEXT_PUBLIC_CM_LOGIN_PAGE_URL = http://dev.onasys.co.kr:3000/auth/login
 NEXT_PUBLIC_CM_LOGIN_PAGE_URL = /
-# NEXT_PUBLIC_SEWERAGE_API_URL=http://192.168.1.66:8883
+NEXT_PUBLIC_SEWERAGE_API_URL=http://localhost:8883

apps/sn/AGENTS.md

@@ -1,43 +1,276 @@
-## Project
-This repository contains a Next.js web application.
+# AGENTS.md
 
-Main technologies:
-- Next.js
-- TypeScript
-- pnpm workspace
-- turborepo
+## 목적
+이 앱은 하수관로 운영관리 시스템 프론트엔드 `sn` 프로젝트이다.
 
-이 저장소는 pnpm workspace + Turborepo 기반 monorepo이다.
+현재 목표는 리팩토링 전용 작업이 아니라, 하수관로 운영관리 시스템 2차사업 고도화를 수행하는 것이다.
+즉, 기존 `sn` 화면과 흐름을 안정적으로 유지하면서 2차 요구사항에 해당하는 화면 개발, 기능 확장, 백엔드 연동 보완을 수행해야 한다.
 
-- 워크스페이스 범위는 `apps/*`, `apps/common/*`, `packages/*`, `packages/common/*`
-- 루트 스크립트는 `turbo run build`, `turbo run dev` 를 사용한다
-- `build` 작업은 의존 패키지의 `build` 를 먼저 수행한다 (`dependsOn: ["^build"]`)
-- `dev` 는 캐시하지 않는 지속 실행 작업이다
-- 변경 범위만 선택 실행할 수 있으므로, 전체 빌드보다 `--filter` 사용을 우선한다
+---
 
-## Encoding 
-- UTF-8 
-- 한글이 깨지지 않도록 주의할 것
+## 공통 시작 기준
 
-## 주석 comment
-- 한글 주석을 삭제하지 말 것
+Codex 작업 루트는 가능하면 `D:\workspace`로 잡고, 공통 시작 기준은 `D:\workspace\AGENTS.md`를 따른다.
 
-## html 디렉토리
-- apps/sn/app/html
-- 이 디렉토리의 목적은 코드를 화면 publishing과 로직 설정을 위한 폴더이다.
-- html 하위 *.md 요청 작업시 html 디렉토리 이외의 수정이 되지 않도록 해야 한다.
+이 파일은 프론트엔드 `sn` 앱 세부 기준이다.
 
-## Monorepo structure
-apps/
-  _template
-  as
-  cm
-  cs
-  dc
-  dm
-  dm_new
-  fo
-  sn
-  st
-  wr
+백엔드(`sewerage-service`)와 함께 수정하거나 API/응답/DB/인증/권한 연동 영향이 있는 작업은 아래 파일을 함께 확인한다.
 
+- 공통 시작 기준: `D:\workspace\AGENTS.md`
+- 백엔드 세부 기준: `D:\workspace\IIPBS\sewerage-service\AGENTS.md`
+- 프론트엔드 `sn` 앱 기준: `D:\workspace\IIPBS-FRONTEND\frontend\apps\sn\AGENTS.md`
+
+---
+
+## 작업 대상
+
+이번 작업에서 직접 수정 가능한 경로는 아래 두 곳만 허용한다.
+
+- `apps/sn/**`
+- `packages/common/business_components/**`
+
+위 두 경로를 제외한 나머지 경로는 모두 기본적으로 읽기 전용으로 간주한다.
+
+예를 들어 아래 경로는 직접 수정하면 안 된다.
+
+- `apps/as/**`
+- `apps/cm/**`
+- `apps/cs/**`
+- `apps/dc/**`
+- `apps/dm/**`
+- `apps/dm_new/**`
+- `apps/fo/**`
+- `apps/st/**`
+- `apps/wr/**`
+- `apps/common/**`
+- `docs/**`
+- `packages/common/assets/**`
+- `packages/common/auth/**`
+- `packages/common/components/**`
+- `packages/common/config/**`
+- `packages/common/network/**`
+- `packages/mindone/**`
+- `packages/oneandall/**`
+- `packages/rsone/**`
+
+수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 아래 내용을 먼저 정리해서 공유한다.
+
+- 문제 원인
+- 수정 필요 경로
+- `sn` 영향 범위
+- 타 앱 영향 가능성
+
+---
+
+## Monorepo 이해
+
+이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다.
+
+워크스페이스 구조는 아래와 같다.
+
+- `apps/*`
+- `apps/common/*`
+- `packages/*`
+- `packages/common/*`
+
+현재 작업 대상은 아래 두 축이다.
+
+- 서비스 앱: `apps/sn`
+- 공통 비즈니스 UI 패키지: `packages/common/business_components`
+
+`sn` 앱은 아래 공통 패키지들을 사용하지만, 이번 권한 범위상 직접 수정 가능한 공통 패키지는 `business_components`만이다.
+
+- `@common/assets`
+- `@common/business_components`
+- `@common/components`
+- `@common/config`
+
+즉, `sn`에서 문제가 보이더라도 원인이 `@common/components`, `@common/auth`, `@common/network` 등에 있으면 직접 수정하지 말고 보고만 한다.
+
+---
+
+## 작업 목표
+
+- 2차사업 요구사항을 `sn` 화면과 흐름에 반영한다.
+- `sn` 앱의 기존 사용자 동작을 가능한 한 유지하면서 기능을 확장한다.
+- 백엔드(`sewerage-service`)와의 연동을 기준으로 화면, 폼, 조회/저장 흐름을 정확히 맞춘다.
+- `business_components` 수정이 필요할 때는 `sn` 요구사항을 만족하는 최소 범위로 수행한다.
+- monorepo 내 타 앱 영향은 최소화한다.
+
+---
+
+## 작업 원칙
+
+1. 모든 변경은 2차 요구사항, 화면설계, 기능 명세 또는 승인된 작업 문서를 근거로 한다.
+2. `apps/sn`과 `packages/common/business_components` 범위를 넘는 수정은 하지 않는다.
+3. 공통 패키지 수정은 `sn` 요구사항을 충족하기 위한 최소 범위로 제한한다.
+4. 다른 앱 전용 로직을 `business_components`에 넣지 않는다.
+5. 불확실한 경우 먼저 계획을 제시한다.
+6. 변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다.
+7. 기존 주석은 임의로 제거하지 않는다.
+8. 복잡한 컴포넌트, 훅, 분기 로직, 상태 흐름, 데이터 변환 로직은 함수/메서드 단위 설명 주석을 충분히 작성한다.
+9. 한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
+10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다.
+11. 백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다.
+12. 작업 문서는 `apps/sn/docs/` 하위에 작업 단위 폴더를 만들어 기록한다.
+
+---
+
+## 허용 작업
+
+- `apps/sn` 내부 신규 화면/기능 개발
+- `apps/sn` 내부 화면/컴포넌트/훅/상태관리 코드 보완 및 리팩토링
+- `apps/sn` 내부 API 호출부 정리
+- `apps/sn` 내부 타입 정리
+- `apps/sn` 내부 라우팅/화면 구조 보완
+- `packages/common/business_components` 내부 공통 비즈니스 컴포넌트 개선
+- `sn`이 사용하는 `business_components`의 타입/렌더링/구조 개선
+- 요구사항 반영을 위한 UI/UX 보완
+- 문서 업데이트
+- 타입 오류 수정
+- 빌드 오류 수정
+- 테스트/검증 코드 또는 검증용 산출물 작성
+
+---
+
+## 금지 작업
+
+- `sn`과 무관한 타 앱 수정
+- `packages/common/business_components` 외의 공통 패키지 수정
+- 요구사항 근거 없는 기능 추가
+- 백엔드 응답 구조를 프론트에서 임의 가정하여 계약을 바꾸는 작업
+- 다른 회사/앱 전용 분기 추가
+- 권한 범위를 넘어서는 전역 리팩토링
+- 근거 없는 대량 수정
+
+---
+
+## 우선 판단 기준
+
+문제가 발생했을 때 아래 순서로 해결 범위를 판단한다.
+
+1. `apps/sn` 내부에서 해결 가능한가
+2. `packages/common/business_components` 수정으로 해결 가능한가
+3. 그 외 공통 패키지 수정이 필요한가
+
+3번에 해당하면 직접 수정하지 말고, 아래 내용을 정리해서 먼저 공유한다.
+
+- 문제 원인
+- 수정 필요 경로
+- `sn` 영향 범위
+- 타 앱 영향 가능성
+
+---
+
+## html 디렉터리 규칙
+
+- 경로: `apps/sn/app/html`
+- 이 디렉터리는 퍼블리싱/정적 HTML/로직 검토 목적의 별도 영역으로 본다.
+- `html` 하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다.
+- `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다.
+- `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.
+
+---
+
+## 빌드 및 검증 기준
+
+이 저장소는 `main` 브랜치 push 전에 `.husky/pre-push`에서 아래 빌드를 수행한다.
+
+```sh
+pnpm turbo run build --filter="...[origin/$BRANCH]"
+```
+
+따라서 로컬 검증도 아래 순서로 수행하는 것을 기본으로 한다.
+
+### `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
+pnpm turbo run build --filter="...[origin/main]"
+```
+
+### pre-push와 동일한 최종 확인
+
+```powershell
+git fetch origin
+pnpm turbo run build --filter="...[origin/main]" --dry-run
+pnpm turbo run build --filter="...[origin/main]"
+```
+
+`business_components`를 수정했는데 이 빌드가 깨지면, `sn`뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다.
+
+가능하면 아래 검증도 함께 수행한다.
+
+- `sn` 개발 서버 실행
+- 백엔드 연동 확인
+- 브라우저 화면 동작 확인
+- 네트워크 응답 확인
+
+---
+
+## 타입 오류 처리 기준
+
+- push 실패 원인이 타입 오류라면 먼저 현재 수정 범위 안에서 해결 가능한지 확인한다.
+- `sn` 내부 타입 오류면 `apps/sn`에서 해결한다.
+- `business_components` 타입 오류면 그 패키지 안에서 해결한다.
+- 다른 공통 패키지 타입 오류가 원인이면 직접 고치지 말고 보고한다.
+
+---
+
+## 주석 및 인코딩 규칙
+
+- 파일 인코딩은 UTF-8로 유지한다.
+- 한글 주석이 깨진 상태로 저장하지 않는다.
+- 기존 주석은 정당한 이유 없이 삭제하지 않는다.
+- 복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.
+
+---
+
+## 문서 경로 기준
+
+`sn` 관련 문서는 앱 내부 문서로 관리하는 것을 기본으로 한다.
+
+권장 경로:
+
+- `apps/sn/docs/`
+- `apps/sn/docs/AI코딩하네스/`
+- `apps/sn/docs/응답표준화/`
+- `apps/sn/docs/검증/`
+
+1차 프로젝트 당시에는 AI 코딩 문서 체계를 사용하지 않았으므로, 신규 문서를 `phase2`처럼 별도 단계 폴더로 분리하지 않고 `apps/sn/docs/` 바로 아래 주제별 한글 폴더로 관리한다.
+
+문서 작업 시에도 `sn` 범위를 벗어나는 앱 문서는 임의로 수정하지 않는다.
+
+루트 `docs/**`는 다른 회사/서비스 리소스를 포함할 수 있으므로 `sn` 작업 중 임의로 수정하지 않는다. 루트 `docs/**` 변경이 필요해 보이면 변경 이유, 영향 범위, `apps/sn/docs/**` 대체 가능 여부를 먼저 정리하고 사용자 승인을 받는다.
+
+---
+
+## 결과 보고 형식
+
+모든 작업 결과는 아래 형식을 따른다.
+
+- 작업 목적
+- 수정 대상 파일
+- 변경 내용 요약
+- 영향 범위
+- 테스트 / 검증 방법
+- 롤백 방법
+- 남은 리스크
+
+---
+
+## 중요
+
+이 모노레포는 여러 회사/서비스가 함께 사용하는 저장소다.
+이번 작업에서 직접 수정 가능한 범위는 `apps/sn`과 `packages/common/business_components` 두 곳뿐이다.
+
+하지만 이번 프로젝트의 성격은 리팩토링 전용이 아니라 `sn` 2차사업 고도화 개발이다.
+따라서 요구사항 구현은 적극적으로 수행하되, 범위를 넘는 변경은 먼저 설명하고 승인 없이 수정하지 않는다.

apps/sn/app/html/AGENTS.md

@@ -1,17 +1,29 @@
-## html 디렉토리
-- 이 디렉토리의 목적은 코드를 화면 publishing과 로직 설정을 위한 폴더이다.
-- 작업시 html 디렉토리 이외의 수정이 되지 않도록 해야 한다.
-- 추가 *.md 파일의 요청대로 만들되 상위의 <Gis>를 건드리지 않고 apps\sn\app\html 에 추가파일을 만들어서 처리한다.
-- 기존의 package/common/component 와 package/common/business_component를 잘 활용한다.
-- <Gis> 의 시설물 layer는 api 호출 결과 값 설정된 대로 zoom level에 따라 모두 보여야 한다.
-## Encoding 
-- UTF-8 
+## html 디렉터리
+
+- 이 디렉터리는 하수관로 운영관리 시스템 `sn` 2차사업 고도화 과정에서 퍼블리싱, 정적 HTML 시안, 로직 검토용 화면을 다루는 영역이다.
+- 작업 시 `apps/sn/app/html` 이외의 수정이 되지 않도록 해야 한다.
+- 추가 `*.md` 파일의 요청대로 만들되 상위 앱 전체를 건드리지 않고 `apps/sn/app/html` 하위에 필요한 파일을 만들어서 처리한다.
+- 기존 `packages/common/components`, `packages/common/business_components`는 활용할 수 있지만, 직접 수정 권한은 상위 `apps/sn/AGENTS.md` 기준을 따른다.
+- 지도/html 시안에서 `<Gis>` 시설물 layer를 다루는 작업은 API 호출 결과 값이 설정된 대로 zoom level에 따라 모두 보이는지 확인한다.
+
+## 2차사업 원칙
+
+- 작업은 리팩토링 전용이 아니라 2차사업 화면 고도화 목적에 맞춰 수행한다.
+- 화면 변경은 요구사항, 화면설계, 기능 명세를 근거로 한다.
+- html 시안 작업과 실제 앱 로직 작업이 함께 필요해 보이면 먼저 구분해서 설명한다.
+
+## Encoding
+
+- UTF-8
 - 한글이 깨지지 않도록 주의할 것
 
 ## 주석 comment
+
 - 한글 주석을 삭제하지 말 것
+- 복잡한 화면 흐름이나 데이터 바인딩 로직은 함수/메서드 단위 설명을 충분히 작성할 것
 
 ## Monorepo structure
+
 apps/
   _template
   as
@@ -24,4 +36,3 @@ apps/
   sn
   st
   wr
-

apps/sn/docs/AI코딩하네스/개요.md

@@ -0,0 +1,41 @@
+# 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

@@ -0,0 +1,62 @@
+# 노후관로관리 브라우저 수동 검증 체크리스트 및 네트워크 증적 양식
+
+## 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

@@ -0,0 +1,22 @@
+# 프로젝트 기준
+
+## 프로젝트 식별
+- 확인됨: 프론트엔드 저장소는 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

@@ -0,0 +1,19 @@
+# 화면 기준
+
+## 화면 분석 원칙
+- 확인됨: `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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,22 @@
+# 컴포넌트 기준
+
+## 수정 범위
+- 확인됨: `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

@@ -0,0 +1,19 @@
+# 상태관리와 화면 흐름 기준
+
+## 상태관리 원칙
+- 확인됨: 기존 `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

@@ -0,0 +1,34 @@
+# 검증 기준
+
+## 기본 빌드 검증
+- 확인됨: `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

@@ -0,0 +1,45 @@
+# 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코딩하네스/보고/2026-04-16/개선사항.md

@@ -0,0 +1,5 @@
+# 2026-04-16 개선 기록
+
+## 반복 개선점
+- 추정: 기능별 작업이 누적되면 `작업목록.md`에 화면, API, 검증 상태 컬럼을 추가해 진행률을 더 쉽게 볼 수 있다.
+- 추정: 브라우저 테스트 절차가 반복되면 `기준문서/007-브라우저점검목록.md`를 추가해 공통 체크리스트로 분리할 수 있다.

apps/sn/docs/AI코딩하네스/보고/2026-04-16/결과보고.md

@@ -0,0 +1,51 @@
+# 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

@@ -0,0 +1,8 @@
+# 2026-04-16 이슈
+
+## 외부 범위 이슈
+- 확인 필요: 현재 등록된 외부 범위 이슈는 없다.
+
+## 미확정 항목
+- 확인 필요: 2차사업 최종 화면명, 메뉴명, URL은 화면설계서와 실행 환경 기준으로 확정해야 한다.
+- 확인 필요: 기능별 테스트 계정, 권한, 데이터는 환경별로 별도 확인해야 한다.

apps/sn/docs/AI코딩하네스/보고/2026-04-16/작업목록.md

@@ -0,0 +1,10 @@
+# 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

@@ -0,0 +1,5 @@
+# 2026-04-16 제안
+
+## 후속 제안
+- 추정: 기능 개발 착수 전 `작업계획/SN-P2-001-*.md` 형식으로 작업카드를 먼저 작성하면 백엔드와 프론트엔드 변경 범위를 분리해서 추적하기 쉽다.
+- 추정: 백엔드 API 변경이 동반되는 작업은 백엔드 작업카드 ID와 프론트 작업카드 ID를 서로 참조하는 방식이 좋다.

apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,16 @@
+# 작업 기록
+
+## 목적
+이 디렉터리는 `sn` 2차사업 작업의 일자별 진행 기록을 남긴다.
+
+## 파일 구성
+- `작업목록.md`: 해당 일자의 작업 항목과 상태
+- `결과보고.md`: 수행 결과와 검증 결과
+- `이슈.md`: 외부 범위, 미확정, 차단 이슈
+- `제안.md`: 후속 제안
+- `개선사항.md`: 반복 작업 개선점
+
+## 기록 원칙
+- 확인됨: 작업 결과는 변경 파일, 영향 범위, 검증 방법, 롤백 방법을 포함한다. 근거: `apps/sn/AGENTS.md`
+- 확인됨: 권한 밖 경로 문제는 직접 수정하지 않고 이슈로 기록한다. 근거: `apps/sn/AGENTS.md`
+- 추정: 백엔드와 함께 진행하는 기능은 백엔드 작업 기록과 프론트 작업 기록을 서로 참조하면 회귀 추적에 유리하다. 근거: 백엔드 `docs/AI코딩하네스` 구조

apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md

@@ -0,0 +1,74 @@
+# 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

@@ -0,0 +1,55 @@
+# 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

@@ -0,0 +1,17 @@
+# 작업카드 관리
+
+## 목적
+이 디렉터리는 `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

@@ -0,0 +1,19 @@
+# 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

@@ -0,0 +1,56 @@
+# 한글 폴더 및 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` 같은 단계 분리 폴더는 사용하지 않음

packages/common/business_components/README.md

@@ -1,5 +1,8 @@
 ## business_components 패키지
-### 원앤올에서 제공받는 컴포넌트 외에 업무 파트에서 사용할 수 있는 별도 components 패키지지
+### 원앤올에서 제공받는 컴포넌트 외에 업무 파트에서 사용할 수 있는 별도 components 패키지
+
+> 하수관로 운영관리 시스템 `sn` 작업에서는 이 패키지만 직접 수정 가능한 공통 비즈니스 컴포넌트 범위이다. `@common/components`, `@common/network`, `@common/auth`, `@common/config` 수정이 필요해 보이면 직접 수정하지 말고 원인과 영향 범위를 먼저 정리한다.
+
   1) 환경설정
 
     (1) tsconfig.json 'path'에 '@common/business_components' 변수를 추가
@@ -17,7 +20,7 @@
 ```json
 "dependencies": {
   "@common/business_components": "workspace:*",
-  "next": "15.3.6"
+  "next": "15.3.8"
 },
 ```
 

packages/common/business_components/src/chart.md

@@ -31,14 +31,14 @@ const chartData = [
   { label: "June", val: 214},
 ]
 ```
-      (4) Chart생성에 필요한 chartConfig 정의
+      (4) Chart 생성에 필요한 chartConfig 정의
 ``` js
 /**
  * 차트 Config
  */
-const chartConfig = chartData.reduce((config,>>element) => {
-      label: element.label,
+const chartConfig = chartData.reduce((config, element) => {
     config[element.label] = {
+      label: element.label,
       color : "hsl(var(--chart-1))"
     };
     return config;
@@ -51,4 +51,4 @@ return (
       <MainChart chartConfig={chartConfig} chartForm={chartForm} chartData={chartData}></MainChart>
     </div>
   );
-```
+```

packages/common/business_components/src/form.md

@@ -1,6 +1,6 @@
 ## form 모듈
 
-### 공통 모듈 중 chart를 다양한 테마로 적용시킬 수 있도록 해주는 모듈
+### 공통 모듈 중 업무 화면의 입력 폼과 검증 흐름을 구성할 수 있도록 해주는 모듈
 
   1. 폼 모듈 사용법
 
@@ -11,7 +11,7 @@ https://zod.dev/?id=introduction
 
     1-2) 호출방법
 
-      (1) form에 필요한 Form,FormField,useForm useForm,z, zodResolver import
+      (1) form에 필요한 Form, FormField, useForm, z, zodResolver import
 
 ```js
 import {

packages/common/business_components/src/ui/search_form_left/searchFormLeft.md

@@ -1,5 +1,8 @@
 ## SearchFormLeft 모듈
 #### 검색영역 좌측 모듈로 행정별, 유역별, 환경청을 선택했을 때 검색 영역을 세팅해주고 childnode를 붙여서 출력해주는 모듈
+
+> 아래 예시는 기존 `fo` 기준 API/store 사용 예시이다. `sn` 작업에서 사용할 때는 `apps/sn`의 API 호출 방식, store 구조, 백엔드 `sewerage-service` 계약을 먼저 확인한 뒤 필요한 값과 타입만 맞춰 적용한다.
+
 #### 1. 컴포넌트 호출방법
 ```js
 import { SearchFormLeft } from "@common/business_components";