md 구조 설계중1

2026-04-24 16:55:11 +09:00
parent 1d3272f836
commit e0a6410c37
27 changed files with 227 additions and 402 deletions
@@ -166,7 +166,8 @@ Codex 작업 루트는 가능하면 `D:\workspace`로 잡고, 공통 시작 기

 - 경로: `apps/sn/app/html`
 - 이 디렉터리는 퍼블리싱/정적 HTML/로직 검토 목적의 별도 영역으로 본다.
- `html` 하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다.
+- 공식 HTML 시안은 기본적으로 `D:\workspace\IIPBS\docs\작업계획\<작업폴더>\` 아래 단일 `.html` 파일로 만든다.
+- `apps/sn/app/html` 작업은 사용자가 앱 라우트 기반 미리보기를 명시적으로 요청한 경우에만 사용한다.
 - `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다.
 - `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.

@@ -229,6 +230,8 @@ pnpm turbo run build --filter="...[origin/main]"

 - 파일 인코딩은 UTF-8로 유지한다.
 - 한글 주석이 깨진 상태로 저장하지 않는다.
+- `.md`, `.toml` 같은 한글 포함 텍스트 파일은 저장 직후 다시 열어 한글이 정상인지 확인한다.
+- 한글이 많은 문서는 셸 리다이렉션(`>`, `>>`)이나 검증 없는 `Set-Content`, `Out-File`로 바로 덮어쓰지 않는다.
 - 기존 주석은 정당한 이유 없이 삭제하지 않는다.
 - 복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.

@@ -240,13 +243,23 @@ pnpm turbo run build --filter="...[origin/main]"

 권장 경로:

- `apps/sn/docs/`
- `apps/sn/docs/AI코딩하네스/`
- `apps/sn/docs/응답표준화/`
+- `apps/sn/docs/기준문서/`
+- `apps/sn/docs/작업계획/`
 - `apps/sn/docs/검증/`

 1차 프로젝트 당시에는 AI 코딩 문서 체계를 사용하지 않았으므로, 신규 문서를 `phase2`처럼 별도 단계 폴더로 분리하지 않고 `apps/sn/docs/` 바로 아래 주제별 한글 폴더로 관리한다.

+작업계획 문서는 아래 원칙으로 관리한다.
+
+- `apps/sn/docs/작업계획/000-작업카드-템플릿.md`는 최상위에 유지한다.
+- 실제 기능 문서는 `apps/sn/docs/작업계획/<기능ID-기능명>/` 폴더 단위로 관리한다.
+- 같은 기능의 FE 작업카드, 관련 메모, 추가 계획 문서는 같은 기능 폴더 안에 함께 둔다.
+- 역할이 있는 문서 파일명은 `<순번>-<역할>-<프로젝트>-<기능명>-<문서종류>.md` 형식을 우선 사용한다.
+- 날짜는 파일명 보조 정보로만 사용하고, `apps/sn/docs/작업계획/` 아래에 날짜 파일을 평면으로 계속 쌓지 않는다.
+- 기존 `md` 문서의 경로와 파일명은 사용자 요청이나 승인된 구조 개편 없이 임의로 바꾸지 않는다.
+- 기존 문서를 수정할 때는 현재 경로와 파일명을 유지한 채 내용을 갱신하는 것을 기본으로 한다.
+- 공통 기준은 `D:\workspace\IIPBS\docs\작업계획\작업계획-폴더규칙.md`를 함께 참고한다.
+
 문서 작업 시에도 `sn` 범위를 벗어나는 앱 문서는 임의로 수정하지 않는다.

 루트 `docs/**`는 다른 회사/서비스 리소스를 포함할 수 있으므로 `sn` 작업 중 임의로 수정하지 않는다. 루트 `docs/**` 변경이 필요해 보이면 변경 이유, 영향 범위, `apps/sn/docs/**` 대체 가능 여부를 먼저 정리하고 사용자 승인을 받는다.
@@ -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`에 남긴다.
@@ -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 |  |  |  |  |  |  |  |
@@ -1,5 +0,0 @@
-# 2026-04-16 개선 기록
-
-## 반복 개선점
- 추정: 기능별 작업이 누적되면 `작업목록.md`에 화면, API, 검증 상태 컬럼을 추가해 진행률을 더 쉽게 볼 수 있다.
- 추정: 브라우저 테스트 절차가 반복되면 `기준문서/007-브라우저점검목록.md`를 추가해 공통 체크리스트로 분리할 수 있다.
@@ -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`에서 문서 파일이 추적 대상 상태로 표시되는지 확인한다.
@@ -1,8 +0,0 @@
-# 2026-04-16 이슈
-
-## 외부 범위 이슈
- 확인 필요: 현재 등록된 외부 범위 이슈는 없다.
-
-## 미확정 항목
- 확인 필요: 2차사업 최종 화면명, 메뉴명, URL은 화면설계서와 실행 환경 기준으로 확정해야 한다.
- 확인 필요: 기능별 테스트 계정, 권한, 데이터는 환경별로 별도 확인해야 한다.
@@ -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 스키마는 변경하지 않았다. 근거: 작업 변경 범위
@@ -1,5 +0,0 @@
-# 2026-04-16 제안
-
-## 후속 제안
- 추정: 기능 개발 착수 전 `작업계획/SN-P2-001-*.md` 형식으로 작업카드를 먼저 작성하면 백엔드와 프론트엔드 변경 범위를 분리해서 추적하기 쉽다.
- 추정: 백엔드 API 변경이 동반되는 작업은 백엔드 작업카드 ID와 프론트 작업카드 ID를 서로 참조하는 방식이 좋다.
@@ -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와 문서 예시 전체가 완전히 일치하는지는 별도 코드 기준 검증이 필요하다.
- 로그인, 권한, 테스트 데이터가 확정되지 않은 기능은 브라우저 검증 항목을 작업카드에서 다시 확정해야 한다.
@@ -1,16 +0,0 @@
-# 작업 기록
-
-## 목적
-이 디렉터리는 `sn` 2차사업 작업의 일자별 진행 기록을 남긴다.
-
-## 파일 구성
- `작업목록.md`: 해당 일자의 작업 항목과 상태
- `결과보고.md`: 수행 결과와 검증 결과
- `이슈.md`: 외부 범위, 미확정, 차단 이슈
- `제안.md`: 후속 제안
- `개선사항.md`: 반복 작업 개선점
-
-## 기록 원칙
- 확인됨: 작업 결과는 변경 파일, 영향 범위, 검증 방법, 롤백 방법을 포함한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 권한 밖 경로 문제는 직접 수정하지 않고 이슈로 기록한다. 근거: `apps/sn/AGENTS.md`
- 추정: 백엔드와 함께 진행하는 기능은 백엔드 작업 기록과 프론트 작업 기록을 서로 참조하면 회귀 추적에 유리하다. 근거: 백엔드 `docs/AI코딩하네스` 구조
@@ -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` 전달 방식과 사용자명 보강은 인증/권한 상태에 따라 결과가 달라질 수 있다.
- 등록/삭제/다운로드는 데이터 변경과 첨부 서비스 의존이 있어 수동 검증 전 테스트 데이터가 필요하다.
@@ -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`
- 기능명은 화면명 또는 업무명을 기준으로 작성한다.
- 한 작업카드에 여러 화면을 무리하게 묶지 않는다.
@@ -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`
@@ -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` 같은 단계 분리 폴더는 사용하지 않음
@@ -19,4 +19,4 @@
 - 확인됨: `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`
+- 추정: 백엔드와 함께 진행되는 기능은 백엔드 `docs/AI코딩하네스/작업계획/` 작업카드와 프론트 `apps/sn/docs/AI코딩하네스/작업계획/` 작업카드를 서로 참조하는 방식이 안전하다. 근거: `apps/sn/AGENTS.md`, 백엔드 `AGENTS.md`
@@ -16,4 +16,4 @@

 ## 확인 필요 항목
 - 확인 필요: 2차사업 최종 화면명과 메뉴 트리는 화면설계서 기준으로 확정해야 한다. 근거: 2차사업 화면설계서
- 확인 필요: 실제 운영 메뉴 권한과 라우팅 정책은 실행 환경에서 확인해야 한다. 근거: `apps/sn` 소스, 브라우저 검증
+- 확인 필요: 실제 운영 메뉴 권한과 라우팅 정책은 실행 환경에서 확인해야 한다. 근거: `apps/sn` 소스, 브라우저 검증
@@ -21,4 +21,4 @@

 ## 금지 기준
 - 확인됨: 프론트엔드에서 백엔드 API 계약 변경을 전제로 구현하지 않는다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 백엔드 응답을 임시로 우회하기 위한 화면 전용 하드코딩을 추가하지 않는다. 근거: `apps/sn/AGENTS.md`
+- 확인됨: 백엔드 응답을 임시로 우회하기 위한 화면 전용 하드코딩을 추가하지 않는다. 근거: `apps/sn/AGENTS.md`
@@ -19,4 +19,4 @@
 - 확인 필요: 브라우저 확인 화면

 ## 외부 범위 이슈
- 확인됨: 권한 밖 공통 패키지 수정이 필요해 보이면 직접 고치지 않고 문제 원인, 수정 필요 경로, `sn` 영향 범위, 타 앱 영향 가능성을 문서화한다. 근거: `apps/sn/AGENTS.md`
+- 확인됨: 권한 밖 공통 패키지 수정이 필요해 보이면 직접 고치지 않고 문제 원인, 수정 필요 경로, `sn` 영향 범위, 타 앱 영향 가능성을 문서화한다. 근거: `apps/sn/AGENTS.md`
@@ -16,4 +16,4 @@

 ## 주의 사항
 - 확인됨: 요구사항 근거 없는 기능 추가는 금지한다. 근거: `apps/sn/AGENTS.md`
- 확인됨: 다른 앱에서 사용하는 공통 상태 로직을 `sn` 문제 해결 목적으로 직접 바꾸지 않는다. 근거: `apps/sn/AGENTS.md`
+- 확인됨: 다른 앱에서 사용하는 공통 상태 로직을 `sn` 문제 해결 목적으로 직접 바꾸지 않는다. 근거: `apps/sn/AGENTS.md`
@@ -31,4 +31,4 @@ pnpm turbo run build --filter="...[origin/main]"

 ## 검증 기록
 - 확인됨: 검증 결과는 `보고/YYYY-MM-DD/결과보고.md`에 기록한다. 근거: 이 하네스 운영 문서
- 확인됨: 외부 범위 오류는 `보고/YYYY-MM-DD/이슈.md`에 기록한다. 근거: 이 하네스 운영 문서
+- 확인됨: 외부 범위 오류는 `보고/YYYY-MM-DD/이슈.md`에 기록한다. 근거: 이 하네스 운영 문서
@@ -42,4 +42,4 @@
 ## 검증 보고 기준
 - FE는 빌드 명령, 화면 URL, 사용자 조작, 기대 결과, 네트워크 응답 확인 기준을 남김
 - BE는 API 요청/응답 예시와 DB 영향 여부를 남김
- QA는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김
+- QA는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김
@@ -0,0 +1,25 @@
+# 008. 설계정책
+
+## 1. 목적
+- `sn` 앱 화면, 상태, API 연동 설계를 변경할 때 판단 기준을 통일한다.
+- 프론트 단독 변경과 백엔드 계약 변경을 구분해서 영향 범위를 명확히 한다.
+
+## 2. 기본 원칙
+- 화면 요구사항, 화면 흐름, API 응답 구조를 함께 보고 설계한다.
+- `apps/sn/**` 안에서 해결 가능한 변경을 우선한다.
+- 공통 컴포넌트 수정이 필요하면 `packages/common/business_components/**` 범위만 검토한다.
+- 그 밖의 공통 패키지 수정이 필요해 보이면 직접 수정하지 말고 원인과 영향 범위를 먼저 문서화한다.
+
+## 3. 화면 설계 원칙
+- 화면 상태는 조회 조건, 목록 데이터, 상세 데이터, 로딩/에러 상태를 분리한다.
+- 폼과 조회 조건은 화면 컴포넌트 내부에서 뒤섞지 말고 역할 단위로 분리한다.
+- 지도, 표, 팝업이 함께 있는 화면은 사용자 흐름 기준으로 이벤트 책임을 나눈다.
+
+## 4. API 연동 원칙
+- 프론트는 실제 백엔드 DTO, API 명세, 에러 응답을 기준으로 맞춘다.
+- 필드명 해석이 애매하면 프론트에서 임의 변환 규칙을 늘리기보다 계약을 먼저 확인한다.
+- 목록/상세/다운로드 API는 요청 파라미터와 응답 구조를 문서에 남긴다.
+
+## 5. 공통 문서 참조
+- 공통 용어는 `D:\workspace\IIPBS\docs\기준문서\003-공통용어사전.md`를 우선 참조한다.
+- 공통 환경/빌드 이슈는 `D:\workspace\IIPBS\docs\기준문서\004-환경빌드문제대응.md`를 함께 본다.
@@ -0,0 +1,24 @@
+# 009. 네이밍규칙
+
+## 1. 목적
+- `sn` 앱에서 화면, 컴포넌트, 상태, API 관련 이름을 일관되게 유지한다.
+
+## 2. 파일/폴더
+- 화면 파일과 폴더는 기능 기준으로 묶고, 한 화면에서 여러 역할이 섞이면 하위 폴더로 분리한다.
+- 문서 파일은 현재처럼 한글 제목을 사용할 수 있지만, 코드 파일은 기존 프로젝트 관례를 우선 따른다.
+- 임시 파일명, `new`, `temp`, `test2` 같은 이름은 커밋 전에 정리한다.
+
+## 3. 컴포넌트
+- React 컴포넌트는 역할이 드러나는 명사를 사용한다.
+- 화면 루트는 `Page`, 팝업은 `Dialog` 또는 `Modal`, 표는 `Table` 또는 `Grid`처럼 일관된 접미사를 사용한다.
+- 공통화가 되지 않은 로컬 화면 조각에 과도하게 `Common` 접두사를 붙이지 않는다.
+
+## 4. 상태/함수
+- 조회 조건은 `search`, `filter`, `params`처럼 의미가 드러나는 이름을 사용한다.
+- 이벤트 핸들러는 `handle*`, 파생 계산은 `get*` 또는 의미 있는 명사형으로 구분한다.
+- 비동기 함수는 목적이 드러나도록 `fetch*`, `load*`, `download*` 등을 사용한다.
+
+## 5. API/데이터
+- 백엔드 계약 필드명은 임의 축약하지 않는다.
+- 화면 표시용 변환 값은 원본 DTO와 구분되게 이름을 짓는다.
+- Boolean 값은 `is`, `has`, `can` 접두사를 우선 사용한다.
@@ -0,0 +1,105 @@
+# 010. 용어사전
+
+## 1. 목적
+- `sn` 프론트 코드에서 실제로 사용되는 용어를 기준으로 화면 라벨, 라우트명, 컴포넌트명, API 필드명을 정리한다.
+- 같은 의미에 여러 이름이 섞여 있는 부분을 드러내고, 작업 시 어떤 이름을 기준으로 삼아야 하는지 고정한다.
+
+## 2. 참조 기준
+- 공통 용어: `D:/workspace/docs/기준문서/003-공통용어사전.md`
+- 백엔드 원본 용어: `D:/workspace/IIPBS/sewerage-service/docs/기준문서/004-용어.csv`
+- 프론트 네이밍 규칙: `D:/workspace/IIPBS-FRONTEND/frontend/apps/sn/docs/기준문서/009-네이밍규칙.md`
+
+## 3. 정리 원칙
+- 화면 라벨은 사용자에게 익숙한 한글 업무 용어를 사용한다.
+- API/DTO/DB와 직접 연결되는 식별자는 백엔드 계약 이름을 우선한다.
+- 라우트나 로컬 컴포넌트에 이미 굳은 이름은 즉시 바꾸지 않고 `별칭`으로 관리한다.
+- 신규 작업에서는 `기준 용어`만 새 이름으로 사용한다.
+- `별칭`은 기존 코드 해석용으로만 남기고, 신규 파일/함수/변수에는 사용하지 않는다.
+
+## 4. 코드 분석으로 확인된 주요 용어군
+이번 검토에서 실제 `apps/sn` 코드에서 확인한 대표 용어군은 아래와 같다.
+
+- 사업/운영 화면
+  - `oldPp`, `dcrpPpl`, `agedPipe`
+  - `floodPre`, `sbmrgPrevnt`
+  - `bizInfo`
+- 지도/시설 화면
+  - `swagePpl`, `swageMhl`, `swagePmstn`, `stofcbr`
+  - `swagePrcsFclt`, `swagePrcsZone`, `SwtrmtFclt`
+  - `WaterDepth`
+- 분석 화면
+  - `rdii`, `rdiiResult`, `result`
+  - `irsetting`, `fileupload`
+  - `infilChart`, `rdiiChart`
+- 공통 기술 용어
+  - `lyrStng`, `lyrTyNm`, `basicType`, `featureData`
+
+## 5. 프론트 기준 용어 매핑
+| 업무 의미 | 기준 용어 | 현재 코드 별칭 | 화면 라벨 | 사용 기준 | 상태 |
+| --- | --- | --- | --- | --- | --- |
+| 노후관로정비사업 | `dcrpPpl` | `oldPp` | 노후관로정비사업 | API/DTO/BE 계약은 `dcrpPpl`, 기존 route는 `oldPp` 유지 | 혼재 |
+| 노후관로 지도 시나리오 | `agedPipe` | `oldPpl`, `dcrpPpl` | 노후관로 | HTML 시안/전용 화면 이름은 `agedPipe` 사용 가능, API 연동 이름으로 직접 쓰지 않음 | 혼재 |
+| 침수예방사업 | `sbmrgPrevnt` | `floodPre` | 침수예방사업 | API/DTO는 `sbmrgPrevnt`, 기존 route는 `floodPre` 유지 | 혼재 |
+| 사업정보 | `bizInfo` | 없음 | 사업정보 | API/화면 모두 `bizInfo` 사용 | 기준 확정 |
+| 관로 | `swagePpl` | `ppl` | 하수관로 | 화면/컴포넌트는 `swagePpl`, 백엔드 필드/약어는 `ppl` 허용 | 기준 후보 |
+| 맨홀 | `swageMhl` | `mhl`, `smh` | 하수맨홀 | 검색/표 컬럼은 `swageMhl`, 축약 내부 변수만 `mhl` 허용 | 혼재 |
+| 펌프장 | `swagePmstn` | `pump`, `sewagePump`, `stormWaterPump` | 하수펌프장 | 화면/검색 기준은 `swagePmstn`, 로컬 컴포넌트 `sewagePump`는 기존 파일명 별칭 | 혼재 |
+| 우수토실 | `stofcbr` | 없음 | 우수토실 | 기존 코드/DB 기준 `stofcbr` 유지 | 기준 확정 |
+| 하수처리시설 | `swtrmtFclt` | `swagePrcsFclt` | 하수처리시설 | 시설 실체/응답 필드는 `swtrmtFclt`, 기존 검색 모달 `swagePrcsFclt`는 별칭 | 혼재 |
+| 하수처리구역 | `swtrmtZone` | `swagePrcsZone` | 하수처리구역 | 응답/화면 기준은 `swtrmtZone`, 기존 검색 모달 `swagePrcsZone`는 별칭 | 혼재 |
+| 수심 레이어 | `waterDepth` | 없음 | 수심 | UI/컴포넌트 기준 `waterDepth` 사용 | 기준 확정 |
+| 레이어 설정 | `lyrStng` | `treeData` | 레이어 설정 | API/도메인 기준은 `lyrStng`, 화면 상태값은 `treeData` 허용 | 기준 후보 |
+| RDII 분석 | `rdii` | `rdiiResult` | RDII 분석 / RDII 분석결과 | 기능명은 `rdii`, 결과 화면은 `rdiiResult` 분리 | 기준 확정 |
+| 침입수 분석 | `inftwt` | `irsetting`, `infilChart` | 침입수 분석 | API/백엔드 계약은 `inftwt`, 기존 route `irsetting`과 차트명 `infilChart`는 별칭 | 혼재 |
+| 수용가 | `rcptr` | 없음 | 수용가정보 | API/BE 계약 기준 `rcptr` 사용 | 기준 확정 |
+
+## 6. 신규 작업에서 사용할 기준
+신규 코드에서는 아래 이름을 우선 사용한다.
+
+### 6.1 사업/운영
+- `dcrpPpl`
+- `sbmrgPrevnt`
+- `bizInfo`
+
+### 6.2 지도/시설
+- `swagePpl`
+- `swageMhl`
+- `swagePmstn`
+- `stofcbr`
+- `swtrmtFclt`
+- `swtrmtZone`
+- `waterDepth`
+- `lyrStng`
+
+### 6.3 분석
+- `inftwt`
+- `rdii`
+- `rcptr`
+
+## 7. 신규 작업에서 피할 별칭
+아래 이름은 기존 코드 해석용으로만 두고, 신규 파일/함수/변수명으로는 우선 사용하지 않는다.
+
+- `oldPp`를 API/DTO 이름으로 사용하는 것
+- `floodPre`를 API 계약 이름으로 사용하는 것
+- `sewagePump`를 신규 화면/컴포넌트 기준 이름으로 사용하는 것
+- `swagePrcsFclt`, `swagePrcsZone`를 신규 API/DTO 기준 이름으로 사용하는 것
+- `irsetting`을 신규 기능명으로 사용하는 것
+- `infilChart`를 침입수 분석 전체 기능명으로 사용하는 것
+
+## 8. 확인 필요 항목
+- `oldPp` route를 장기적으로 `dcrpPpl` 또는 한글 route 명으로 정리할지
+- `swagePmstn`와 `sewagePump` 중 화면 컴포넌트 기준 이름을 통일할지
+- `swtrmtFclt`와 `swagePrcsFclt`를 같은 개념으로 볼지 분리할지
+- `swtrmtZone`와 `swagePrcsZone`를 같은 개념으로 볼지 분리할지
+- `irsetting` route를 `inftwt` 의미에 맞춰 정리할지
+
+## 9. 작업카드 반영 규칙
+신규 화면/컴포넌트/API 작업 시 아래를 반드시 기록한다.
+- 화면 라벨
+- 라우트명
+- API 필드명
+- 프론트 변수명
+- 기준 용어
+- 기존 별칭 사용 여부
+- 용어사전 갱신 여부
+
@@ -0,0 +1,23 @@
+# 011. 환경빌드문제대응
+
+## 1. 공통 기준
+- 공통 환경/빌드 이슈는 `D:\workspace\IIPBS\docs\기준문서\004-환경빌드문제대응.md`를 함께 본다.
+
+## 2. 프론트 기본 점검
+- `pnpm -v`, `node -v` 버전을 먼저 확인한다.
+- 작업 루트는 기본적으로 `D:\workspace\IIPBS-FRONTEND\frontend`를 사용한다.
+- 의존성 문제 의심 시 `pnpm install` 상태와 lockfile 변경 여부를 함께 본다.
+
+## 3. 기본 빌드 명령
+- `pnpm --filter sn run build`
+- `pnpm turbo run build --filter=sn`
+- `pnpm --filter @common/business_components run build`
+
+## 4. 점검 순서
+- 에디터 타입 오류인지 실제 빌드 오류인지 먼저 구분한다.
+- `sn`만의 오류인지 공통 패키지 영향인지 구분한다.
+- 한글 경로, 캐시, Node 버전, pnpm workspace 인식 문제를 순서대로 확인한다.
+
+## 5. 대응 원칙
+- 원인 확인 전 광범위한 삭제나 재설치는 마지막 수단으로 둔다.
+- 공통 패키지 문제면 `sn` 영향 범위를 함께 기록한다.
@@ -0,0 +1,25 @@
+# 012. 코드리뷰체크리스트
+
+## 1. 화면 동작
+- 조회, 상세, 다운로드, 팝업 흐름이 요구사항대로 동작하는가
+- 로딩/빈 화면/에러 상태가 빠지지 않았는가
+- 기존 화면 동작을 깨는 회귀가 없는가
+
+## 2. API 연동
+- 실제 백엔드 요청 파라미터와 응답 필드를 기준으로 구현했는가
+- 에러 응답 또는 예외 케이스를 화면에서 처리하는가
+- 프론트 임의 가공 로직이 계약 불일치를 숨기고 있지 않은가
+
+## 3. 범위 준수
+- 수정 범위가 `apps/sn/**` 또는 `packages/common/business_components/**` 안에 머무르는가
+- 다른 공통 패키지 수정이 필요하면 원인과 영향 범위를 먼저 정리했는가
+
+## 4. 코드 품질
+- 컴포넌트 책임이 과도하게 섞이지 않았는가
+- 상태, 이벤트, 비동기 호출이 읽기 쉽게 분리되어 있는가
+- 이름이 역할을 설명하고 있는가
+
+## 5. 검증
+- 빌드 명령 또는 필요한 로컬 검증을 수행했는가
+- 브라우저에서 핵심 시나리오를 확인했는가
+- 변경 이유, 영향 범위, 남은 리스크를 결과 보고에 남겼는가
@@ -71,4 +71,4 @@
 - 확인 필요:

 ## 10. 완료 기준
- 확인 필요:
+- 확인 필요: