md 구조 잡기

2026-04-27 15:51:36 +09:00
parent e0a6410c37
commit 8689b0a8a6
8 changed files with 145 additions and 59 deletions
@@ -10,15 +10,15 @@

 ## 공통 시작 기준

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

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

 백엔드(`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`
+- 공통 시작 기준: `AGENTS.md`
+- 백엔드 세부 기준: `BE_REPO_ROOT/AGENTS.md`
+- 프론트엔드 `sn` 앱 기준: `FE_APP_ROOT/AGENTS.md`

 ---

@@ -113,6 +113,9 @@ Codex 작업 루트는 가능하면 `D:\workspace`로 잡고, 공통 시작 기
 10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다.
 11. 백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다.
 12. 작업 문서는 `apps/sn/docs/` 하위에 작업 단위 폴더를 만들어 기록한다.
+13. 신규 화면이나 UI 변경은 먼저 기존 `sn` 화면과 공통 컴포넌트/레이아웃 패턴을 따르는 방향으로 설계한다.
+14. `BaseLayout`, `NoFooterLayout`, `PageLayout`, `SearchDiv`, `SearchFormLeft/Right`, `ListDiv`, `UiTable`, `UiModal`, `Gis` 조합을 우선 재사용한다.
+15. 새 UI 구조가 꼭 필요하면 기존 패턴으로 해결되지 않는 이유를 먼저 설명한다.

 ---

@@ -166,7 +169,7 @@ Codex 작업 루트는 가능하면 `D:\workspace`로 잡고, 공통 시작 기

 - 경로: `apps/sn/app/html`
 - 이 디렉터리는 퍼블리싱/정적 HTML/로직 검토 목적의 별도 영역으로 본다.
- 공식 HTML 시안은 기본적으로 `D:\workspace\IIPBS\docs\작업계획\<작업폴더>\` 아래 단일 `.html` 파일로 만든다.
+- 공식 HTML 시안은 기본적으로 `COMMON_DOCS_ROOT/작업계획/<작업폴더>/` 아래 단일 `.html` 파일로 만든다.
 - `apps/sn/app/html` 작업은 사용자가 앱 라우트 기반 미리보기를 명시적으로 요청한 경우에만 사용한다.
 - `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다.
 - `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.
@@ -247,18 +250,24 @@ pnpm turbo run build --filter="...[origin/main]"
 - `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/작업계획/000-작업카드-템플릿.md`는 최상위에 유지한다.
+- `apps/sn/docs/작업계획/작업카드-템플릿.md`는 최상위에 유지한다.
 - 실제 기능 문서는 `apps/sn/docs/작업계획/<기능ID-기능명>/` 폴더 단위로 관리한다.
 - 같은 기능의 FE 작업카드, 관련 메모, 추가 계획 문서는 같은 기능 폴더 안에 함께 둔다.
 - 역할이 있는 문서 파일명은 `<순번>-<역할>-<프로젝트>-<기능명>-<문서종류>.md` 형식을 우선 사용한다.
 - 날짜는 파일명 보조 정보로만 사용하고, `apps/sn/docs/작업계획/` 아래에 날짜 파일을 평면으로 계속 쌓지 않는다.
 - 기존 `md` 문서의 경로와 파일명은 사용자 요청이나 승인된 구조 개편 없이 임의로 바꾸지 않는다.
 - 기존 문서를 수정할 때는 현재 경로와 파일명을 유지한 채 내용을 갱신하는 것을 기본으로 한다.
- 공통 기준은 `D:\workspace\IIPBS\docs\작업계획\작업계획-폴더규칙.md`를 함께 참고한다.
+- 공통 기준은 `COMMON_DOCS_ROOT/작업계획/작업계획-폴더규칙.md`를 함께 참고한다.
+- UI/레이아웃 기준은 `FE_APP_DOCS_ROOT/기준문서/013-UI레이아웃가이드.md`를 함께 참고한다.

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

@@ -17,6 +17,13 @@

 ## 문서 기준
 - 확인됨: `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/작업계획/작업카드-템플릿.md`를 기준으로 기능 폴더 아래에 작성한다. 근거: `apps/sn/AGENTS.md`
+- 확인됨: `phase2` 같은 별도 단계 폴더는 신규 문서 경로로 사용하지 않는다. 근거: `apps/sn/AGENTS.md`
+- 추정: 백엔드와 함께 진행되는 기능은 백엔드 `docs/작업계획/작업카드-템플릿.md`와 프론트 `apps/sn/docs/작업계획/작업카드-템플릿.md`를 각각 기능 폴더 아래에서 서로 참조하는 방식이 안전하다. 근거: `apps/sn/AGENTS.md`, 백엔드 `AGENTS.md`
+
+## 공통 동기화 기준
+- 새 채팅방에서 프론트 작업을 시작할 때는 아래 문서를 먼저 확인한다.
+  - `COMMON_DOCS_ROOT/작업계획/공통-작업동기화/002-공통-작업현황판.md`
+  - `COMMON_DOCS_ROOT/작업계획/공통-작업동기화/003-공통-파일점유현황.md`
+  - `COMMON_DOCS_ROOT/작업계획/공통-작업동기화/004-공통-결정로그.md`
+- 같은 기능을 다른 채팅방에서 이어받는 경우 작업 ID, 현재 상태, 점유 파일을 먼저 갱신한다.
@@ -1,45 +1,13 @@
-# 007. 멀티에이전트 운영 기준
+# 007. 멀티에이전트운영

 ## 목적
- `sn` 2차사업 프론트 작업을 BE, FE, QA 역할과 안전하게 연결하기 위한 기준임
- AI_SAM `refactoring` 브랜치의 병렬 분업 구조를 참고하되, `sn` 앱과 허용된 `business_components` 범위를 우선함
+- 프론트 `sn` 앱 관점에서 멀티에이전트 작업 시 `fe` 역할이 따라야 하는 보조 기준을 정리한다.

-## 프론트 역할 범위
-| 역할 | 주 책임 | 직접 수정 가능 범위 | 직접 수정 금지 범위 |
-| --- | --- | --- | --- |
-| FE | 화면, 컴포넌트, 훅, 상태관리, API 호출부, 타입 | `apps/sn/**`, `packages/common/business_components/**` | 타 앱, `business_components` 외 공통 패키지, 루트 `docs/**` |
-| BE | API 계약, 요청/응답 DTO, 서비스 흐름, DB 영향 | 백엔드 저장소 기준 | 프론트 저장소 직접 수정은 별도 합류 기준 필요 |
-| QA | 빌드, 브라우저 조작, 네트워크 응답, 회귀 포인트 확인 | 검증 문서, 결과보고 | 기능 코드 임의 수정 |
+## 공통 기준
+- 공통 역할/합류/검증 기준은 `COMMON_DOCS_ROOT/기준문서\011-멀티에이전트운영.md`를 우선 따른다.
+- 공통 개발 흐름은 `COMMON_DOCS_ROOT/기준문서\010-AI개발작업흐름.md`를 우선 따른다.

-## 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는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김
+## 프론트 보조 기준
+- `fe` 역할의 직접 수정 범위는 `apps/sn/**`, `packages/common/business_components/**` 이다.
+- `@common/components`, `@common/network`, `@common/auth`, `@common/config`, 타 앱은 직접 수정하지 않는다.
+- 프론트 결과 보고에는 화면 진입 경로, 사용자 조작, 빌드 결과, 네트워크 확인 기준, BE/QA 합류 필요사항을 포함한다.
@@ -21,5 +21,5 @@
 - 목록/상세/다운로드 API는 요청 파라미터와 응답 구조를 문서에 남긴다.

 ## 5. 공통 문서 참조
- 공통 용어는 `D:\workspace\IIPBS\docs\기준문서\003-공통용어사전.md`를 우선 참조한다.
- 공통 환경/빌드 이슈는 `D:\workspace\IIPBS\docs\기준문서\004-환경빌드문제대응.md`를 함께 본다.
+- 공통 용어는 `COMMON_DOCS_ROOT/기준문서/003-공통용어사전.md`를 우선 참조한다.
+- 공통 환경/빌드 이슈는 `COMMON_DOCS_ROOT/기준문서/004-환경빌드문제대응.md`를 함께 본다.
@@ -5,9 +5,9 @@
 - 같은 의미에 여러 이름이 섞여 있는 부분을 드러내고, 작업 시 어떤 이름을 기준으로 삼아야 하는지 고정한다.

 ## 2. 참조 기준
- 공통 용어: `D:/workspace/docs/기준문서/003-공통용어사전.md`
- 백엔드 원본 용어: `D:/workspace/IIPBS/sewerage-service/docs/기준문서/004-용어.csv`
- 프론트 네이밍 규칙: `D:/workspace/IIPBS-FRONTEND/frontend/apps/sn/docs/기준문서/009-네이밍규칙.md`
+- 공통 용어: `COMMON_DOCS_ROOT/기준문서/003-공통용어사전.md`
+- 백엔드 원본 용어: `BE_DOCS_ROOT/기준문서/004-용어.csv`
+- 프론트 네이밍 규칙: `FE_APP_DOCS_ROOT/기준문서/009-네이밍규칙.md`

 ## 3. 정리 원칙
 - 화면 라벨은 사용자에게 익숙한 한글 업무 용어를 사용한다.
@@ -1,11 +1,11 @@
 # 011. 환경빌드문제대응

 ## 1. 공통 기준
- 공통 환경/빌드 이슈는 `D:\workspace\IIPBS\docs\기준문서\004-환경빌드문제대응.md`를 함께 본다.
+- 공통 환경/빌드 이슈는 `COMMON_DOCS_ROOT/기준문서/004-환경빌드문제대응.md`를 함께 본다.

 ## 2. 프론트 기본 점검
 - `pnpm -v`, `node -v` 버전을 먼저 확인한다.
- 작업 루트는 기본적으로 `D:\workspace\IIPBS-FRONTEND\frontend`를 사용한다.
+- 작업 루트는 기본적으로 `FE_REPO_ROOT/`를 사용한다.
 - 의존성 문제 의심 시 `pnpm install` 상태와 lockfile 변경 여부를 함께 본다.

 ## 3. 기본 빌드 명령
@@ -0,0 +1,90 @@
+# 013. UI레이아웃가이드
+
+## 1. 목적
+- `sn` 앱 화면 작업 시 기존 하수관로시스템 UI 패턴을 그대로 따르기 위한 구현 기준을 정리한다.
+- 이후 기능 추가나 화면 개선 시 “무엇을 재사용해야 하는지”를 빠르게 판단할 수 있게 한다.
+
+## 2. 이번 분석에서 확인한 기준 화면
+- 업무형 조회/등록 화면
+  - `apps/sn/app/(with-base-layout)/oper/oldPp/page.tsx`
+  - `apps/sn/app/(with-base-layout)/oper/floodPre/page.tsx`
+  - `apps/sn/app/(with-base-layout)/ii/rdii/page.tsx`
+- 지도형 화면
+  - `apps/sn/app/(map-layout)/map/page.tsx`
+- 공통 레이아웃/구성
+  - `packages/common/components/src/ui/layout/base.tsx`
+  - `packages/common/components/src/ui/layout/nofooter.tsx`
+  - `apps/sn/src/shared/ui/page-layout.tsx`
+  - `packages/common/components/src/ui/layout/common.css`
+- 공통 비즈니스 컴포넌트
+  - `packages/common/business_components/src/ui/search_form/index.tsx`
+  - `packages/common/business_components/src/ui/search_form_left/index.tsx`
+  - `packages/common/business_components/src/ui/search_form_right/index.tsx`
+  - `packages/common/business_components/src/ui/list_div/index.tsx`
+  - `packages/common/business_components/src/ui/table/index.tsx`
+  - `packages/common/business_components/src/ui/map/Gis.js`
+
+## 3. 레이아웃 선택 기준
+
+### 3.1 업무형 화면
+- 대상: 등록현황, 분석 조건 입력, 조회/목록/업로드/모달 중심 화면
+- 기본 구조:
+  - `BaseLayout`
+  - `PageLayout`
+  - 상단 검색영역: `SearchDiv`
+  - 좌측 검색조건: `SearchFormLeft`
+  - 우측 액션 버튼: `SearchFormRight`
+  - 본문 카드: `ListDiv`
+  - 목록: `UiTable`
+  - 팝업: `UiModal`
+
+### 3.2 지도형 화면
+- 대상: 레이어 트리, 피처 선택, 상세 팝업, 검색 모달, 지도 도구 중심 화면
+- 기본 구조:
+  - `NoFooterLayout`
+  - `Gis`
+  - `ProcSearchBar` 또는 지도 전용 검색 UI
+  - 우측 상세 팝업: 지도 피처 상세 컴포넌트
+  - 레이어 트리/툴바/줌레벨: `Gis` 내부 패턴 유지
+
+## 4. 시각 패턴
+- 기본 카드 스타일은 `common.css`의 `card`, `card-border`, `card-header`, `card-footer`를 우선 따른다.
+- 글자 크기는 업무 화면에서 `text-2xl`, `text-xl` 계열을 많이 사용하므로, 신규 화면도 이 리듬을 우선 유지한다.
+- 버튼은 화면마다 새 변형을 만들기보다 기존 `Button` 스타일과 색상 조합을 우선 사용한다.
+- 리스트/테이블/검색영역은 유리질 카드나 대시보드형 실험적 스타일보다 현재 반투명 카드 + 경계선 + 표 구조를 우선 유지한다.
+
+## 5. 검색영역 규칙
+- 검색영역은 상단 1행 구조를 기본으로 한다.
+- 왼쪽에는 조회 조건, 오른쪽에는 `조회`, `등록`, `다운로드` 같은 액션 버튼을 둔다.
+- 검색 필드는 `Label + Input/DatePicker/Select` 조합을 유지한다.
+- 새 화면도 가능하면 “등록기간/조건입력/조회버튼” 패턴을 크게 벗어나지 않는다.
+
+## 6. 목록/테이블 규칙
+- 데이터 목록은 `UiTable`을 우선 사용한다.
+- 카드 헤더에는 제목과 총 건수, 우측 액션 버튼을 배치한다.
+- 페이징, 선택 초기화, 셀 클릭 동작은 기존 `UiTable` 사용 패턴을 따른다.
+- 새 테이블을 만들 때는 먼저 `headlist` 설정 파일로 컬럼 구조를 분리하는 방식을 검토한다.
+
+## 7. 모달/상세 규칙
+- 상세 보기, 등록, 엑셀 미리보기는 `UiModal` 패턴을 우선 사용한다.
+- 지도형 화면 상세는 우측 고정 패널 또는 기존 지도 상세 팝업 위치를 우선 유지한다.
+- 같은 기능에서 목록 선택 후 상세/모달이 열리는 흐름은 기존 `oldPp`, `floodPre`, `map` 패턴을 참고한다.
+
+## 8. 상태관리/API 연동 규칙
+- 화면 내부 로컬 상태로 충분한 것은 로컬 state를 우선 사용한다.
+- 사용자/공통 코드/메뉴/검색 모달 상태는 기존 store 패턴을 우선 따른다.
+- API 호출은 기존 `searchData`, `getData`, `postData`, `deleteData` 계열을 우선 사용한다.
+- 프론트에서 백엔드 응답 구조를 임의 가정하지 않고, 현재 화면이 실제로 쓰는 필드 기준으로 맞춘다.
+
+## 9. 새 화면 설계 시 체크리스트
+- 이 화면이 업무형인지 지도형인지 먼저 구분했는가
+- 기존 레이아웃(`BaseLayout` / `NoFooterLayout`) 중 하나를 선택했는가
+- 검색영역을 `SearchDiv + SearchFormLeft/Right` 패턴으로 풀 수 있는가
+- 목록을 `UiTable`로 처리할 수 있는가
+- 상세/등록 흐름을 `UiModal` 또는 기존 상세 패널 패턴으로 맞출 수 있는가
+- 새 스타일을 만들기 전에 `@common/components`, `@common/business_components` 재사용 가능성을 확인했는가
+
+## 10. 예외 처리 원칙
+- 기존 패턴으로 해결되지 않는 요구사항일 때만 새 UI 구조를 제안한다.
+- 그 경우에도 “왜 기존 패턴으로 해결되지 않는지”를 먼저 설계 문서에 남긴다.
+- 예외 구조를 만들 때는 이후 다른 화면에도 재사용 가능한지 같이 검토한다.
@@ -10,6 +10,12 @@
 - 담당 범위:
 - 근거 문서:

+## 1-1. 공통 동기화 확인
+- 공통 작업현황판 확인 여부:
+- 파일점유현황 확인 여부:
+- 결정로그 확인 여부:
+- 기존 진행 중 작업과의 관계:
+
 ## 2. 작업 목적
 - 확인 필요:

@@ -31,6 +37,7 @@

 - 충돌 주의 파일:
 - 인수인계 메모:
+- 파일점유 등록 여부:

 ## 4. 화면 흐름
 - 확인 필요: 진입 경로
@@ -57,6 +64,11 @@
 - 병렬 진행 가능 항목:
 - 순차 진행 필요 항목:

+## 6-2. 채팅방 간 충돌 방지
+- 같은 기능을 다른 채팅방에서 진행 중인지:
+- 겹치는 파일 또는 폴더:
+- 점유 충돌 시 처리 방식:
+
 ## 7. 검증 방법
 - 확인 필요: 빌드 명령
 - 확인 필요: 브라우저 URL
@@ -71,4 +83,4 @@
 - 확인 필요:

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