노후관로 ai 개발 기능 테스트_V1.0

2026-04-23 17:27:19 +09:00
parent e30d62b429
commit 9d573e6ad1
66 changed files with 4568 additions and 188 deletions
@@ -0,0 +1,35 @@
+# 프론트엔드 AI 개발 문서
+
+## 목적
+
+이 디렉터리는 `FE_REPO_ROOT` 전체에 적용되는 프론트엔드 공통 개발 기준을 관리한다.
+특정 앱의 화면/기능 상세가 아니라, 여러 프론트엔드 앱에서 함께 참고할 수 있는 구조, 실행, 응답 처리, 검증, 템플릿 기준을 둔다.
+
+## 디렉터리 구조
+
+| 경로 | 역할 |
+|---|---|
+| `구조/` | 저장소 구조, 폴더 구조, 상태관리, 화면흐름 같은 공통 구조 기준 |
+| `실행명세/` | 프론트엔드 실행 흐름, 기능 목록, 증적, 진행 로그 기준 |
+| `응답표준화/` | API 응답을 프론트에서 호출, 변환, 표시, 오류 처리하는 기준 |
+| `검증/` | 브라우저, 빌드, 네트워크 검증 기준과 로그 |
+| `템플릿/` | 기능별 문서 작성에 재사용할 표준 템플릿 |
+
+## 작성 범위
+
+- 프론트엔드 앱 공통 구조
+- 공통 컴포넌트 사용 기준
+- 화면 실행/브라우저 검증 기준
+- API 응답 사용/표시/오류 처리 기준
+- 기능별 산출물 템플릿
+
+## 작성 금지 범위
+
+- 백엔드 Controller, Service, Repository 구현 상세
+- DB 스키마 상세
+- 특정 앱에만 해당하는 화면별 구현 상세
+- `sn` 전용 기능 산출물
+
+특정 앱 기능 문서는 해당 앱의 `docs/` 아래에 둔다.
+예: `SN_APP_ROOT/docs/노후관로관리/**`
+
@@ -0,0 +1,17 @@
+# 프론트엔드 검증 기준
+
+## 기본 원칙
+
+- 화면 변경은 브라우저에서 실제로 확인한다.
+- API 연동 화면은 네트워크 요청과 응답을 함께 확인한다.
+- 공통 패키지를 수정하면 해당 패키지 빌드와 사용 앱 빌드를 모두 확인한다.
+- 검증하지 못한 항목은 결과 보고에 남긴다.
+
+## 검증 구분
+
+| 구분 | 목적 |
+|---|---|
+| 브라우저 검증 | 화면 배치, 상호작용, 모달, 상세 패널 확인 |
+| 빌드 검증 | 타입, 번들, 패키지 의존성 확인 |
+| 네트워크 검증 | 요청 파라미터, 응답 필드, 오류 처리 확인 |
+
@@ -0,0 +1,19 @@
+# 브라우저 검증
+
+## 확인 항목
+
+- 화면이 기존 레이아웃과 같은 위치/톤을 유지하는가
+- 버튼, 체크박스, 토글, 모달, 상세 패널이 동작하는가
+- 텍스트가 겹치거나 잘리지 않는가
+- 지도 화면은 레이어 표시/선택/확대 이동이 동작하는가
+- 목록 행 선택과 상세 패널이 연동되는가
+
+## 기록 항목
+
+- 확인 일시
+- 확인 URL
+- 브라우저
+- 주요 동작
+- 캡처 또는 증적 경로
+- 남은 이슈
+
@@ -0,0 +1,27 @@
+# 빌드 검증
+
+## 기본 명령
+
+`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]"
+```
+
+## 기록 항목
+
+- 실행 명령
+- 성공/실패
+- 실패 로그 핵심
+- 영향 범위
+- 후속 조치
+
@@ -0,0 +1,17 @@
+# 네트워크 검증
+
+## 확인 항목
+
+- 요청 URL
+- HTTP method
+- query/body 파라미터
+- 응답 상태 코드
+- 화면 표시 필드와 응답 필드 매핑
+- 오류 응답 처리
+- 다운로드 응답 처리
+
+## 기록 기준
+
+특정 기능의 상세 네트워크 검증 결과는 앱 기능 문서에 작성한다.
+공통 규칙은 이 문서에 유지한다.
+
@@ -0,0 +1,6 @@
+# 프론트엔드 검증로그
+
+| 일자 | 대상 | 검증 유형 | 결과 | 후속 조치 |
+|---|---|---|---|---|
+| - | - | - | - | - |
+
@@ -0,0 +1,23 @@
+# 검증 문서
+
+## 목적
+
+프론트엔드 작업의 공통 검증 기준을 관리한다.
+브라우저, 빌드, 네트워크 검증을 분리해 기록한다.
+
+## 포함 문서
+
+| 문서 | 역할 |
+|---|---|
+| `00-검증기준.md` | 공통 검증 원칙 |
+| `01-브라우저검증.md` | 화면/상호작용 검증 기준 |
+| `02-빌드검증.md` | 빌드 명령과 실패 처리 기준 |
+| `03-네트워크검증.md` | API 요청/응답 확인 기준 |
+| `99-검증로그.md` | 검증 수행 기록 |
+
+## 작성 기준
+
+- 앱 공통 검증 기준만 작성한다.
+- 기능별 구체 검증 결과는 해당 앱 기능 문서에 작성한다.
+- 검증 실패 시 원인, 영향 범위, 재현 방법을 함께 기록한다.
+
@@ -0,0 +1,27 @@
+# 프론트엔드 시스템맵
+
+## 목적
+
+프론트엔드 저장소의 앱, 공통 패키지, 백엔드 연동 지점을 한눈에 파악하기 위한 AI 개발 기준 문서이다.
+백엔드 `sewerage-service/docs/00-시스템맵.md`와 같은 역할을 한다.
+
+## 주요 기준 경로
+
+- `FE_REPO_ROOT`: `WORKSPACE_ROOT/frontend`
+- `SN_APP_ROOT`: `FE_REPO_ROOT/apps/sn`
+- `BUSINESS_COMPONENTS_ROOT`: `FE_REPO_ROOT/packages/common/business_components`
+
+## 시스템 구성
+
+- `apps/sn`: 하수관로 운영관리 시스템 `sn` 서비스 앱
+- `packages/common/business_components`: 여러 앱에서 사용하는 공통 비즈니스 UI 컴포넌트
+- `packages/common/components`: 공통 UI 컴포넌트 패키지. `sn` 작업 중 직접 수정하지 않는다.
+- `packages/common/auth`: 인증/권한 관련 공통 패키지. `sn` 작업 중 직접 수정하지 않는다.
+- `packages/common/network`: 네트워크 관련 공통 패키지. `sn` 작업 중 직접 수정하지 않는다.
+
+## 2차사업 개발 원칙
+
+- 1차 개발 화면의 디자인, 레이아웃, 컴포넌트 조합을 우선 유지한다.
+- 신규 화면도 기존 `SN_APP_ROOT` 화면 구조와 `BUSINESS_COMPONENTS_ROOT` 컴포넌트 조합으로 구현한다.
+- 독립 HTML 시안은 요구사항 검토용으로만 사용하고 실제 서비스 화면에는 그대로 반영하지 않는다.
+- 백엔드 API 계약, 응답 구조, 권한, 지도 레이어 영향이 있으면 백엔드 문서와 함께 확인한다.
@@ -0,0 +1,42 @@
+# 프론트엔드 폴더구조
+
+## 목적
+
+프론트엔드 저장소에서 AI 개발자가 읽고 수정할 수 있는 범위와 참조해야 하는 경로를 정의한다.
+
+## 저장소 구조
+
+```text
+FE_REPO_ROOT/
+  apps/
+    sn/
+      app/
+      src/
+      docs/
+      AGENTS.md
+  packages/
+    common/
+      business_components/
+        src/
+```
+
+## 직접 수정 가능 범위
+
+- `SN_APP_ROOT/app/**`
+- `SN_APP_ROOT/src/**`
+- `SN_APP_ROOT/docs/**`
+- `BUSINESS_COMPONENTS_ROOT/src/**`
+- `FE_REPO_ROOT/docs/**` 중 프론트엔드 AI 개발 공통 문서
+
+## 직접 수정 금지 범위
+
+- `FE_REPO_ROOT/apps/sn` 외 다른 앱
+- `FE_REPO_ROOT/packages/common/business_components` 외 공통 패키지
+- 인증, 네트워크, 공통 컴포넌트 패키지
+
+## 화면 개발 참조 순서
+
+1. 동일 업무 또는 유사 화면이 `SN_APP_ROOT/app/**`에 있는지 확인한다.
+2. 앱 내부 feature/shared 구조가 `SN_APP_ROOT/src/**`에 있는지 확인한다.
+3. 공통 비즈니스 컴포넌트가 `BUSINESS_COMPONENTS_ROOT/src/**`에 있는지 확인한다.
+4. 기존 컴포넌트로 불가능한 경우에만 최소 범위의 컴포넌트 보완을 검토한다.
@@ -0,0 +1,28 @@
+# 프론트엔드 상태관리 구조
+
+## 목적
+
+`sn` 앱의 화면 상태, 조회 조건, 지도 선택 객체, 모달 상태를 일관되게 다루기 위한 기준 문서이다.
+
+## 기본 원칙
+
+- 기존 `sn` 앱에서 사용하는 상태 관리 방식과 훅 구조를 먼저 확인한다.
+- 화면 단위 상태는 가능하면 해당 화면 또는 feature 범위 안에서 관리한다.
+- 여러 컴포넌트가 공유하는 상태는 기존 store 또는 공통 훅 패턴을 따른다.
+- 지도 선택 객체, 목록 선택 행, 상세 패널 표시 상태는 서로 불일치하지 않도록 한 흐름에서 갱신한다.
+
+## 확인 대상
+
+- `SN_APP_ROOT/app/store/**`
+- `SN_APP_ROOT/src/**`
+- 기존 지도 화면의 선택 객체, 레이어 표시, 검색 모달 상태 흐름
+
+## 문서화 기준
+
+상태 흐름을 새로 추가하거나 변경할 때는 아래 내용을 작업 문서에 남긴다.
+
+- 상태 이름과 소유 컴포넌트
+- 상태 변경 트리거
+- 백엔드/API 응답과의 관계
+- 지도, 그리드, 상세 패널 간 동기화 방식
+- 초기화와 오류 처리 방식
@@ -0,0 +1,29 @@
+# 프론트엔드 화면흐름
+
+## 목적
+
+프론트엔드 화면 이동, 지도 상호작용, 모달/상세 패널 표시 흐름을 정리하기 위한 기준 문서이다.
+
+## 기본 원칙
+
+- 신규 화면은 기존 1차 화면의 레이아웃과 조작 방식을 우선 따른다.
+- 디자인을 새로 만드는 대신 기존 페이지, 모달, 테이블, 지도 패널 컴포넌트 조합을 재사용한다.
+- 화면 ID, 메뉴 경로, API 계약, 권한 조건을 함께 기록한다.
+
+## 화면흐름 기록 항목
+
+- 화면 ID
+- 메뉴 경로
+- 진입 조건
+- 주요 조회 조건
+- 지도/그리드/상세 패널 연동
+- 모달 또는 팝업 호출 조건
+- 다운로드/저장/삭제 같은 주요 액션
+- 권한별 노출 차이
+- 오류/빈 데이터 처리
+
+## `sn` 화면 개발 기준
+
+- 실제 페이지는 `SN_APP_ROOT/app/**`를 기준으로 확인한다.
+- 지도 기반 화면은 기존 `(map-layout)` 구조와 `Gis` 관련 컴포넌트 사용 방식을 먼저 확인한다.
+- 공통 비즈니스 UI가 필요하면 `BUSINESS_COMPONENTS_ROOT/src/**`를 우선 검토한다.
@@ -0,0 +1,20 @@
+# 프론트엔드 미확인사항
+
+## 목적
+
+프론트엔드 2차사업 개발 중 아직 확정되지 않은 계약, 화면, 권한, 공통 컴포넌트 이슈를 기록한다.
+
+## 기록 형식
+
+| 일자 | 구분 | 내용 | 영향 범위 | 확인 필요 대상 | 상태 |
+|---|---|---|---|---|---|
+| - | - | - | - | - | - |
+
+## 주요 확인 대상
+
+- 백엔드 API 요청/응답 계약
+- 지도 레이어명, 속성명, zoom level별 표시 조건
+- 1차 화면과 다른 UI 변경 필요 여부
+- `BUSINESS_COMPONENTS_ROOT` 수정 시 타 앱 영향 가능성
+- 대용량 목록/엑셀 다운로드 처리 방식
+- 권한별 조회 범위와 버튼 노출 기준
@@ -0,0 +1,23 @@
+# 구조 문서
+
+## 목적
+
+프론트엔드 저장소의 공통 구조를 설명한다.
+여기에는 특정 화면의 구현 세부가 아니라, 여러 앱에서 공유할 수 있는 구조 기준만 작성한다.
+
+## 포함 문서
+
+| 문서 | 역할 |
+|---|---|
+| `00-시스템맵.md` | 앱과 공통 패키지, 백엔드 연동 지점의 큰 그림 |
+| `01-폴더구조.md` | 저장소 폴더와 수정 가능 범위 |
+| `03-상태관리구조.md` | 상태관리 기준 |
+| `04-화면흐름.md` | 화면 진입, 이동, 모달, 상세 패널 흐름 기준 |
+| `99-미확인사항.md` | 구조 관련 미확인사항 |
+
+## 작성 기준
+
+- `FE_REPO_ROOT` 전체에 적용되는 기준만 작성한다.
+- 특정 앱의 기능 상세는 앱 내부 문서에 작성한다.
+- 백엔드 구현 상세는 작성하지 않는다.
+
@@ -0,0 +1,31 @@
+# 프론트엔드 실행명세 범위
+
+## 목적
+
+프론트엔드 실행명세는 `FE_REPO_ROOT` 안에서 실제 화면, 상태, API 호출, 브라우저 동작을 확인하기 위한 문서 묶음이다.
+백엔드 실행명세처럼 서버, DB, Repository를 다루지 않고 프론트엔드 관점만 다룬다.
+
+## 작성 범위
+
+- `SN_APP_ROOT` 화면 실행 흐름
+- 기존 컴포넌트 재사용 기준
+- 화면별 상태와 이벤트 흐름
+- 브라우저 동작 확인 방법
+- API 호출 위치와 응답 사용 방식
+- 빌드/실행/검증 증적
+
+## 제외 범위
+
+- 백엔드 Controller, Service, Repository 상세
+- DB 스키마 상세
+- 백엔드 공통 응답 구조 변경안
+- 타 앱 전용 화면 구현 상세
+
+## 관련 문서
+
+- `FE_REPO_ROOT/docs/구조/00-시스템맵.md`
+- `FE_REPO_ROOT/docs/구조/01-폴더구조.md`
+- `FE_REPO_ROOT/docs/구조/03-상태관리구조.md`
+- `FE_REPO_ROOT/docs/구조/04-화면흐름.md`
+- `FE_REPO_ROOT/docs/응답표준화/01-API구조.md`
+
@@ -0,0 +1,27 @@
+# 프론트엔드 기능명세 계획
+
+## 목적
+
+프론트엔드 기능명세 작성 전에 화면 단위로 어떤 산출물을 만들지 정리한다.
+
+## 작성 단위
+
+- 화면 ID
+- 메뉴 경로
+- 주요 컴포넌트
+- 상태 관리
+- API 호출부
+- 사용자 이벤트
+- 브라우저 검증 방법
+
+## 작성 위치 기준
+
+- 여러 앱 공통 기준: `FE_REPO_ROOT/docs/실행명세/**`
+- `sn` 특정 기능: `SN_APP_ROOT/docs/**`
+
+## 노후관로관리 적용 예
+
+- `SN_MN010102`: 노후관로관리
+- `SN_MN010103`: 노후관로분석
+- 세부 문서 위치: `SN_APP_ROOT/docs/노후관로관리/**`
+
@@ -0,0 +1,11 @@
+# 프론트엔드 기능목록
+
+## 목적
+
+프론트엔드에서 구현하거나 검증해야 하는 기능을 화면 기준으로 추적한다.
+
+| 화면 ID | 기능 | 주요 컴포넌트 | 상태 | 문서 위치 |
+|---|---|---|---|---|
+| SN_MN010102 | 노후관로관리 | `Gis`, `GisTree`, `UiTable`, `FeatureClickEventPopup` | 정리 중 | `SN_APP_ROOT/docs/노후관로관리/**` |
+| SN_MN010103 | 노후관로분석 | `Gis`, `FeatureClickEventPopup`, `VerticalTable` | 정리 중 | `SN_APP_ROOT/docs/노후관로관리/**` |
+
@@ -0,0 +1,18 @@
+# 프론트엔드 증적목록
+
+## 목적
+
+프론트엔드 작업의 실행, 빌드, 브라우저 확인 증적을 추적한다.
+
+| 일자 | 기능 | 증적 유형 | 경로/내용 | 상태 |
+|---|---|---|---|---|
+| - | - | - | - | - |
+
+## 증적 유형
+
+- 정적 HTML 샘플
+- 브라우저 캡처
+- 빌드 로그
+- 네트워크 응답 확인
+- 수동 테스트 결과
+
@@ -0,0 +1,6 @@
+# 프론트엔드 실행명세 진행로그
+
+| 일자 | 작업 | 결과 | 후속 작업 |
+|---|---|---|---|
+| 2026-04-21 | 노후관로관리 화면 기준 정리 | 기존 화면 기반 컴포넌트 분해 및 작업 목록 작성 | API/응답 필드 매핑표 작성 |
+
@@ -0,0 +1,22 @@
+# 실행명세 문서
+
+## 목적
+
+프론트엔드 화면을 실제로 실행하고 검증하기 위한 기준과 진행 기록을 관리한다.
+
+## 포함 문서
+
+| 문서 | 역할 |
+|---|---|
+| `00-범위.md` | 실행명세의 범위와 제외 범위 |
+| `02-기능명세계획.md` | 화면/기능 단위 산출물 계획 |
+| `03-기능목록.md` | 추적할 기능 목록 |
+| `04-증적목록.md` | 캡처, 로그, 빌드 결과 같은 증적 목록 |
+| `99-진행로그.md` | 실행명세 진행 기록 |
+
+## 작성 기준
+
+- 프론트엔드 실행과 브라우저 동작 기준만 작성한다.
+- 서버 실행 로그를 인용할 수는 있지만, 백엔드 내부 구현 분석은 쓰지 않는다.
+- 특정 앱 기능의 상세 실행 결과는 앱 내부 문서에 작성한다.
+
@@ -0,0 +1,23 @@
+# 프론트엔드 응답표준화 범위
+
+## 목적
+
+프론트엔드 응답표준화 문서는 백엔드 응답을 화면에서 어떻게 호출, 변환, 표시, 오류 처리할지 정리한다.
+백엔드 응답 구조 자체를 바꾸는 문서가 아니라, 프론트엔드 사용 기준을 정의한다.
+
+## 작성 범위
+
+- API 호출 위치
+- 요청 파라미터
+- 응답 필드 사용처
+- 화면 표시 필드 매핑
+- 오류/빈 데이터 처리
+- 다운로드/파일 응답 처리
+- 기존 응답과 신규 후보 API 비교
+
+## 제외 범위
+
+- 백엔드 공통 응답 포맷 변경
+- DB 컬럼 설계
+- Repository/Service 구현 상세
+
@@ -0,0 +1,24 @@
+# 프론트엔드 API 구조
+
+## 목적
+
+프론트엔드에서 백엔드 API를 호출하고 화면에 반영하는 흐름을 정리하기 위한 기준 문서이다.
+
+## 기본 원칙
+
+- 백엔드 API 계약은 `BE_SERVICE_ROOT/docs`와 실제 Controller/DTO/Service 흐름을 함께 확인한다.
+- 프론트엔드에서 백엔드 응답 구조를 임의로 바꾸거나 가정하지 않는다.
+- API 응답 변경이 필요하면 영향 화면, 요청 파라미터, 응답 필드, 오류 처리 방식을 먼저 정리한다.
+- 지도/GIS 레이어 호출은 실제 레이어 설정, zoom level, 표시 조건을 함께 확인한다.
+
+## `sn` API 연동 기준
+
+- `SN_APP_ROOT/app/api/**`: Next 앱 내부 API 관련 코드
+- `SN_APP_ROOT/app/components/**`: 화면 컴포넌트에서 사용하는 API 유틸 참조 가능
+- `SN_APP_ROOT/src/**`: feature/shared 구조가 있는 경우 해당 구조를 우선 따른다.
+
+## 검증 기준
+
+- 브라우저에서 실제 요청 파라미터와 네트워크 응답을 확인한다.
+- 목록, 상세, 다운로드, 지도 이동처럼 UI와 API가 연결되는 흐름은 화면 동작까지 확인한다.
+- 백엔드 실패, 권한 부족, 데이터 없음, 대용량 다운로드 같은 예외 흐름을 함께 점검한다.
@@ -0,0 +1,22 @@
+# 프론트엔드 응답 처리 규칙
+
+## 기본 원칙
+
+- 백엔드 응답 구조를 프론트에서 임의로 바꾸어 가정하지 않는다.
+- 화면에서 필요한 필드는 실제 API 응답과 DTO를 확인해 매핑한다.
+- 코드값은 기존 코드 매핑 유틸 또는 공통 코드 목록을 우선 사용한다.
+- 빈 값, NULL, 권한 오류, 네트워크 오류는 화면별로 표시 기준을 둔다.
+
+## 표시 규칙
+
+- 값 없음: `-`
+- 설치일자 없음: `확인불가`
+- 숫자: 기존 테이블 포맷 규칙을 따른다.
+- 코드값: 기존 `codeMapper`, `MS_SWAGE_PPL_CODES`, `MS_SWAGE_PPL_USE_CODES` 등을 우선 확인한다.
+
+## 오류 처리
+
+- 조회 실패: 기존 toast/alert 패턴을 따른다.
+- 다운로드 실패: 사용자에게 실패 메시지를 표시한다.
+- 권한 오류: 버튼/조회 범위 노출 조건을 백엔드 권한과 맞춘다.
+
@@ -0,0 +1,22 @@
+# 프론트엔드 응답 전환 계획
+
+## 목적
+
+기존 API 호출 방식과 신규 후보 API를 비교해 화면별 전환 필요성을 판단한다.
+
+## 전환 기준
+
+| 구분 | 기준 |
+|---|---|
+| 기존 API 재사용 | 현재 화면 필드와 동작을 충족하는 경우 |
+| 프론트 변환 추가 | 응답은 충분하지만 화면 표시 필드 변환이 필요한 경우 |
+| 신규 API 요청 | 기존 API로 성능, 필드, 권한, 다운로드 요구사항을 충족하지 못하는 경우 |
+
+## 작업 순서
+
+1. 현재 호출 API 확인
+2. 화면 표시 필드 매핑
+3. 누락 필드 정리
+4. 오류/빈 데이터 처리 정리
+5. 신규 API 필요 여부 판단
+
@@ -0,0 +1,11 @@
+# 프론트엔드 응답 회귀점검목록
+
+| 항목 | 확인 내용 | 상태 |
+|---|---|---|
+| 목록 조회 | 요청 파라미터와 응답 목록이 화면에 맞는지 확인 | 대기 |
+| 상세 조회 | 상세 패널 필드가 기존 화면과 동일한 톤으로 표시되는지 확인 | 대기 |
+| 코드 매핑 | 용도/재질 코드가 한글명으로 표시되는지 확인 | 대기 |
+| 빈 데이터 | 데이터 없음/NULL이 표시 규칙을 따르는지 확인 | 대기 |
+| 다운로드 | 조회 조건과 다운로드 결과가 일치하는지 확인 | 대기 |
+| 오류 처리 | API 실패 시 사용자 메시지가 표시되는지 확인 | 대기 |
+
@@ -0,0 +1,14 @@
+# 프론트엔드 응답표준화 미확인사항
+
+| 일자 | 구분 | 내용 | 확인 필요 대상 | 상태 |
+|---|---|---|---|---|
+| - | - | - | - | - |
+
+## 노후관로관리 우선 확인 대상
+
+- 기존 `v1/fclts`로 노후관로 목록 조건을 충분히 처리할 수 있는지
+- 경과년도 계산을 프론트에서 할지, 백엔드 응답 필드로 받을지
+- 설치일자 NULL/미래일자 처리 기준
+- 엑셀 다운로드를 기존 프론트 유틸로 처리할지, 백엔드 파일 API로 처리할지
+- 하수처리구역 분석 통계를 프론트 계산으로 할지, 백엔드 API로 받을지
+
@@ -0,0 +1,23 @@
+# 응답표준화 문서
+
+## 목적
+
+프론트엔드가 백엔드 API 응답을 어떻게 호출, 변환, 표시, 오류 처리하는지에 대한 공통 기준을 관리한다.
+
+## 포함 문서
+
+| 문서 | 역할 |
+|---|---|
+| `00-범위.md` | 프론트엔드 응답표준화의 범위 |
+| `01-API구조.md` | 프론트엔드 API 호출 구조 |
+| `02-프론트엔드응답처리규칙.md` | 값 표시, 코드 매핑, 오류 처리 규칙 |
+| `03-프론트엔드전환계획.md` | 기존 API와 신규 후보 API 비교 기준 |
+| `04-프론트엔드회귀점검목록.md` | 응답 처리 회귀 점검 항목 |
+| `99-미확인사항.md` | 응답 관련 미확인사항 |
+
+## 작성 기준
+
+- 백엔드 응답 구조 자체를 바꾸는 문서가 아니다.
+- 프론트 화면에서 응답을 어떻게 사용하는지에 집중한다.
+- 특정 기능의 API 필드 매핑표는 해당 앱 기능 문서에 작성한다.
+
@@ -0,0 +1,28 @@
+# API 응답 필드 매핑표
+
+## 목적
+
+- 
+
+## API 목록
+
+| 구분 | Method | Endpoint | 사용 화면/컴포넌트 | 상태 |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## 필드 매핑
+
+| 화면 영역 | 표시명 | 응답 필드 | 변환/코드매핑 | 빈 값 처리 | 비고 |
+|---|---|---|---|---|---|
+|  |  |  |  |  |  |
+
+## 오류 처리
+
+| 상황 | 처리 방식 |
+|---|---|
+|  |  |
+
+## 미확인사항
+
+- 
+
@@ -0,0 +1,12 @@
+# 문서 템플릿
+
+## 목적
+
+기능별 프론트엔드 문서를 일관된 형식으로 작성하기 위한 템플릿을 제공한다.
+
+## 사용 기준
+
+- 새 기능 문서 폴더를 만들 때 필요한 템플릿을 복사해 사용한다.
+- 템플릿은 공통 형식만 제공한다.
+- 기능별 구체 내용은 각 앱의 `docs/{기능명}/` 아래에 작성한다.
+
@@ -0,0 +1,22 @@
+# 검증 결과
+
+## 검증 개요
+
+| 항목 | 내용 |
+|---|---|
+| 검증 일자 |  |
+| 검증자 |  |
+| 대상 화면 |  |
+| 실행 URL |  |
+| 브라우저 |  |
+
+## 검증 항목
+
+| 항목 | 결과 | 증적 | 비고 |
+|---|---|---|---|
+|  |  |  |  |
+
+## 남은 리스크
+
+- 
+
@@ -0,0 +1,33 @@
+# 기능명
+
+## 목적
+
+- 
+
+## 화면 정보
+
+| 항목 | 내용 |
+|---|---|
+| 화면 ID |  |
+| 메뉴 경로 |  |
+| 대상 앱 |  |
+| 관련 요구사항 |  |
+
+## 범위
+
+### 포함
+
+- 
+
+### 제외
+
+- 
+
+## 관련 문서
+
+- 
+
+## 남은 이슈
+
+- 
+
@@ -0,0 +1,28 @@
+# 컴포넌트별 작업 목록
+
+## 목적
+
+- 
+
+## 작업 단위 요약
+
+| 순서 | 작업 단위 | 주요 파일 | 구분 | 목적 |
+|---|---|---|---|---|
+| 1 |  |  |  |  |
+
+## 컴포넌트별 상세
+
+### 컴포넌트명
+
+#### 현재 상태
+
+- 
+
+#### 변경 방향
+
+- 
+
+#### 검증 항목
+
+- 
+