frontend/apps/sn/AGENTS.md

# AGENTS.md

## 목적
이 앱은 하수관로 운영관리 시스템 프론트엔드 `sn` 프로젝트이다.

현재 목표는 리팩토링 전용 작업이 아니라, 하수관로 운영관리 시스템 2차사업 고도화를 수행하는 것이다.
즉, 기존 `sn` 화면과 흐름을 안정적으로 유지하면서 2차 요구사항에 해당하는 화면 개발, 기능 확장, 백엔드 연동 보완을 수행해야 한다.

---

## 공통 시작 기준

Codex 작업 루트는 가능하면 `../../../../../`로 잡고, 공통 시작 기준은 `AGENTS.md`를 따른다.

이 파일은 프론트엔드 `sn` 앱 세부 기준이다.

백엔드(`sewerage-service`)와 함께 수정하거나 API/응답/DB/인증/권한 연동 영향이 있는 작업은 아래 파일을 함께 확인한다.

- 공통 시작 기준: `AGENTS.md`
- 백엔드 세부 기준: `BE_REPO_ROOT/AGENTS.md`
- 프론트엔드 `sn` 앱 기준: `FE_APP_ROOT/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. 신규/수정 함수, 주요 상수, 주요 변수, `useState`, `useRef`, `useMemo`, `useCallback`에는 화면/API/상태 흐름에서 맡는 역할을 알 수 있는 주석을 작성한다.
9. 한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다.
11. 백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다.
12. 작업 문서는 `apps/sn/docs/` 하위에 작업 단위 폴더를 만들어 기록한다.
13. 신규 화면이나 UI 변경은 먼저 기존 `sn` 화면과 공통 컴포넌트/레이아웃 패턴을 따르는 방향으로 설계한다.
14. `BaseLayout`, `NoFooterLayout`, `PageLayout`, `SearchDiv`, `SearchFormLeft/Right`, `ListDiv`, `UiTable`, `UiModal`, `Gis` 조합을 우선 재사용한다.
15. 새 UI 구조가 꼭 필요하면 기존 패턴으로 해결되지 않는 이유를 먼저 설명한다.

---

## 허용 작업

- `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 시안은 기본적으로 `COMMON_DOCS_ROOT/작업계획/<작업폴더>/` 아래 단일 `.html` 파일로 만든다.
- `apps/sn/app/html` 작업은 사용자가 앱 라우트 기반 미리보기를 명시적으로 요청한 경우에만 사용한다.
- `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다.
- `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.

---

## 빌드 및 검증 기준

VSCode나 별도 터미널에서 `sn` Next 개발 서버가 실행 중이면 `next build`, `pnpm --filter sn run build`, `pnpm turbo run build --filter=sn` 같은 빌드 명령을 실행하지 않는다.
개발 서버와 빌드가 동시에 `.next` 산출물을 갱신하면 개발 서버가 종료되거나 꼬일 수 있으므로, 빌드 검증은 사용자에게 확인한 뒤 개발 서버를 끄고 수행한다.

이 저장소는 `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로 유지한다.
- 한글 주석이 깨진 상태로 저장하지 않는다.
- `.md`, `.toml` 같은 한글 포함 텍스트 파일은 저장 직후 다시 열어 한글이 정상인지 확인한다.
- 한글이 많은 문서는 셸 리다이렉션(`>`, `>>`)이나 검증 없는 `Set-Content`, `Out-File`로 바로 덮어쓰지 않는다.
- 기존 주석은 정당한 이유 없이 삭제하지 않는다.
- 복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.
- 신규/수정 상수와 변수는 이름만으로 의도가 충분히 드러나지 않으면 선언부 근처에 역할, 단위, 백엔드 계약, 화면 상태와의 관계를 주석으로 남긴다.
- `useRef`로 비동기 요청, 팝업 창, 지도 객체, 체크 상태를 보관하는 경우에는 왜 state가 아니라 ref를 쓰는지 주석으로 남긴다.

---

## 문서 경로 기준

`sn` 관련 문서는 앱 내부 문서로 관리하는 것을 기본으로 한다.

권장 경로:

- `apps/sn/docs/기준문서/`
- `apps/sn/docs/작업계획/`
- `apps/sn/docs/검증/`

공통 개발 흐름과 멀티에이전트 기준은 아래 공통 문서를 우선 참조한다.

- `COMMON_DOCS_ROOT/기준문서/010-AI개발작업흐름.md`
- `COMMON_DOCS_ROOT/기준문서/011-멀티에이전트운영.md`

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

작업계획 문서는 아래 원칙으로 관리한다.

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

문서 작업 시에도 `sn` 범위를 벗어나는 앱 문서는 임의로 수정하지 않는다.

루트 `docs/**`는 다른 회사/서비스 리소스를 포함할 수 있으므로 `sn` 작업 중 임의로 수정하지 않는다. 루트 `docs/**` 변경이 필요해 보이면 변경 이유, 영향 범위, `apps/sn/docs/**` 대체 가능 여부를 먼저 정리하고 사용자 승인을 받는다.

---

## 결과 보고 형식

모든 작업 결과는 아래 형식을 따른다.

- 작업 목적
- 수정 대상 파일
- 변경 내용 요약
- 영향 범위
- 테스트 / 검증 방법
- 롤백 방법
- 남은 리스크

---

## 중요

이 모노레포는 여러 회사/서비스가 함께 사용하는 저장소다.
이번 작업에서 직접 수정 가능한 범위는 `apps/sn`과 `packages/common/business_components` 두 곳뿐이다.

하지만 이번 프로젝트의 성격은 리팩토링 전용이 아니라 `sn` 2차사업 고도화 개발이다.
따라서 요구사항 구현은 적극적으로 수행하되, 범위를 넘는 변경은 먼저 설명하고 승인 없이 수정하지 않는다.