From 3641a21fc5bb93ee03718b959e64d280f8209b58 Mon Sep 17 00:00:00 2001 From: mind-one001 Date: Fri, 17 Apr 2026 11:28:03 +0900 Subject: [PATCH] =?UTF-8?q?=ED=95=98=EC=88=98=EA=B4=80=EB=A1=9C=20md=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/sn/AGENTS.md | 92 +++++++++++++------ apps/sn/app/html/AGENTS.md | 29 ++++-- apps/sn/docs/AI코딩하네스/개요.md | 41 +++++++++ .../001-노후관로관리-브라우저-네트워크-증적.md | 62 +++++++++++++ .../AI코딩하네스/기준문서/001-프로젝트.md | 22 +++++ .../docs/AI코딩하네스/기준문서/002-화면맵.md | 19 ++++ .../docs/AI코딩하네스/기준문서/003-API사용.md | 24 +++++ .../AI코딩하네스/기준문서/004-컴포넌트정책.md | 22 +++++ .../AI코딩하네스/기준문서/005-상태관리정책.md | 19 ++++ .../AI코딩하네스/기준문서/006-검증정책.md | 34 +++++++ .../기준문서/007-멀티에이전트운영.md | 45 +++++++++ .../AI코딩하네스/보고/2026-04-16/개선사항.md | 5 + .../AI코딩하네스/보고/2026-04-16/결과보고.md | 51 ++++++++++ .../docs/AI코딩하네스/보고/2026-04-16/이슈.md | 8 ++ .../AI코딩하네스/보고/2026-04-16/작업목록.md | 10 ++ .../docs/AI코딩하네스/보고/2026-04-16/제안.md | 5 + .../AI코딩하네스/보고/2026-04-17/결과보고.md | 45 +++++++++ apps/sn/docs/AI코딩하네스/보고/개요.md | 16 ++++ .../작업계획/000-작업카드-템플릿.md | 74 +++++++++++++++ .../작업계획/001-SN-P2-노후관로관리-작업카드.md | 55 +++++++++++ apps/sn/docs/AI코딩하네스/작업계획/개요.md | 17 ++++ apps/sn/docs/AI코딩하네스/작업목록.md | 19 ++++ apps/sn/docs/AI코딩하네스/한글경로-영향.md | 56 +++++++++++ packages/common/business_components/README.md | 7 +- .../common/business_components/src/chart.md | 8 +- .../common/business_components/src/form.md | 4 +- .../src/ui/search_form_left/searchFormLeft.md | 3 + 27 files changed, 748 insertions(+), 44 deletions(-) create mode 100644 apps/sn/docs/AI코딩하네스/개요.md create mode 100644 apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md create mode 100644 apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/2026-04-16/결과보고.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/2026-04-16/작업목록.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md create mode 100644 apps/sn/docs/AI코딩하네스/보고/개요.md create mode 100644 apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md create mode 100644 apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md create mode 100644 apps/sn/docs/AI코딩하네스/작업계획/개요.md create mode 100644 apps/sn/docs/AI코딩하네스/작업목록.md create mode 100644 apps/sn/docs/AI코딩하네스/한글경로-영향.md diff --git a/apps/sn/AGENTS.md b/apps/sn/AGENTS.md index 3780bece8..ba16d7f48 100644 --- a/apps/sn/AGENTS.md +++ b/apps/sn/AGENTS.md @@ -3,15 +3,28 @@ ## 목적 이 앱은 하수관로 운영관리 시스템 프론트엔드 `sn` 프로젝트이다. -이 문서는 `apps/sn` 작업 시 따라야 할 전용 작업 기준을 정의한다. -이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다. -따라서 `sn` 작업 시에는 작업 가능 범위와 수정 금지 범위를 엄격하게 지켜야 한다. +현재 목표는 리팩토링 전용 작업이 아니라, 하수관로 운영관리 시스템 2차사업 고도화를 수행하는 것이다. +즉, 기존 `sn` 화면과 흐름을 안정적으로 유지하면서 2차 요구사항에 해당하는 화면 개발, 기능 확장, 백엔드 연동 보완을 수행해야 한다. + +--- + +## 공통 시작 기준 + +Codex 작업 루트는 가능하면 `D:\workspace`로 잡고, 공통 시작 기준은 `D:\workspace\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` --- ## 작업 대상 -이번 작업에서 수정 가능한 경로는 아래 두 곳만 허용한다. +이번 작업에서 직접 수정 가능한 경로는 아래 두 곳만 허용한다. - `apps/sn/**` - `packages/common/business_components/**` @@ -30,6 +43,7 @@ - `apps/st/**` - `apps/wr/**` - `apps/common/**` +- `docs/**` - `packages/common/assets/**` - `packages/common/auth/**` - `packages/common/components/**` @@ -39,20 +53,27 @@ - `packages/oneandall/**` - `packages/rsone/**` -수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 영향 범위를 정리해서 먼저 보고해야 한다. +수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 아래 내용을 먼저 정리해서 공유한다. + +- 문제 원인 +- 수정 필요 경로 +- `sn` 영향 범위 +- 타 앱 영향 가능성 --- ## Monorepo 이해 -이 저장소는 아래 워크스페이스 구조를 가진다. +이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다. + +워크스페이스 구조는 아래와 같다. - `apps/*` - `apps/common/*` - `packages/*` - `packages/common/*` -현재 작업 대상은 이 중 아래 두 축이다. +현재 작업 대상은 아래 두 축이다. - 서비스 앱: `apps/sn` - 공통 비즈니스 UI 패키지: `packages/common/business_components` @@ -70,41 +91,45 @@ ## 작업 목표 -- 하수관로 운영관리 시스템 `sn`의 기존 화면 동작 유지 -- `sn` 내부 코드 가독성 향상 -- `sn` 화면/기능에 필요한 범위에서만 공통 비즈니스 UI 정리 -- `packages/common/business_components` 변경 시 `sn` 영향 범위 명확화 -- monorepo 내 타 앱 영향 최소화 +- 2차사업 요구사항을 `sn` 화면과 흐름에 반영한다. +- `sn` 앱의 기존 사용자 동작을 가능한 한 유지하면서 기능을 확장한다. +- 백엔드(`sewerage-service`)와의 연동을 기준으로 화면, 폼, 조회/저장 흐름을 정확히 맞춘다. +- `business_components` 수정이 필요할 때는 `sn` 요구사항을 만족하는 최소 범위로 수행한다. +- monorepo 내 타 앱 영향은 최소화한다. --- ## 작업 원칙 -1. 기존 외부 동작을 변경하지 않는다. -2. `sn` 범위와 `business_components` 범위를 넘는 수정은 하지 않는다. +1. 모든 변경은 2차 요구사항, 화면설계, 기능 명세 또는 승인된 작업 문서를 근거로 한다. +2. `apps/sn`과 `packages/common/business_components` 범위를 넘는 수정은 하지 않는다. 3. 공통 패키지 수정은 `sn` 요구사항을 충족하기 위한 최소 범위로 제한한다. 4. 다른 앱 전용 로직을 `business_components`에 넣지 않는다. 5. 불확실한 경우 먼저 계획을 제시한다. 6. 변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다. 7. 기존 주석은 임의로 제거하지 않는다. -8. 복잡한 컴포넌트, 훅, 분기 로직을 수정할 때는 클래스/메서드/함수 단위 설명 주석을 충분히 작성한다. +8. 복잡한 컴포넌트, 훅, 분기 로직, 상태 흐름, 데이터 변환 로직은 함수/메서드 단위 설명 주석을 충분히 작성한다. 9. 한글이 깨지지 않도록 반드시 UTF-8로 유지한다. 10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다. -11. 작업 문서를 작성할때는 `apps/sn/docs` 폴더에 작업단위로 폴더를 생성해서 기록한다. +11. 백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다. +12. 작업 문서는 `apps/sn/docs/` 하위에 작업 단위 폴더를 만들어 기록한다. --- ## 허용 작업 -- `apps/sn` 내부 화면/컴포넌트/훅/상태관리 코드 리팩토링 +- `apps/sn` 내부 신규 화면/기능 개발 +- `apps/sn` 내부 화면/컴포넌트/훅/상태관리 코드 보완 및 리팩토링 - `apps/sn` 내부 API 호출부 정리 - `apps/sn` 내부 타입 정리 - `apps/sn` 내부 라우팅/화면 구조 보완 - `packages/common/business_components` 내부 공통 비즈니스 컴포넌트 개선 -- `sn`이 사용하는 `business_components`의 타입/렌더링/구조 정리 -- 관련 문서 업데이트 +- `sn`이 사용하는 `business_components`의 타입/렌더링/구조 개선 +- 요구사항 반영을 위한 UI/UX 보완 +- 문서 업데이트 - 타입 오류 수정 - 빌드 오류 수정 +- 테스트/검증 코드 또는 검증용 산출물 작성 --- @@ -112,8 +137,8 @@ - `sn`과 무관한 타 앱 수정 - `packages/common/business_components` 외의 공통 패키지 수정 -- API 계약 임의 변경 -- 백엔드 응답 구조를 프론트에서 임의 가정하여 데이터 구조를 바꾸는 작업 +- 요구사항 근거 없는 기능 추가 +- 백엔드 응답 구조를 프론트에서 임의 가정하여 계약을 바꾸는 작업 - 다른 회사/앱 전용 분기 추가 - 권한 범위를 넘어서는 전역 리팩토링 - 근거 없는 대량 수정 @@ -140,7 +165,7 @@ ## html 디렉터리 규칙 - 경로: `apps/sn/app/html` -- 이 디렉터리는 퍼블리싱/정적 HTML/로직 확인 목적의 별도 영역으로 본다. +- 이 디렉터리는 퍼블리싱/정적 HTML/로직 검토 목적의 별도 영역으로 본다. - `html` 하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다. - `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다. - `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다. @@ -182,6 +207,13 @@ pnpm turbo run build --filter="...[origin/main]" `business_components`를 수정했는데 이 빌드가 깨지면, `sn`뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다. +가능하면 아래 검증도 함께 수행한다. + +- `sn` 개발 서버 실행 +- 백엔드 연동 확인 +- 브라우저 화면 동작 확인 +- 네트워크 응답 확인 + --- ## 타입 오류 처리 기준 @@ -204,16 +236,21 @@ pnpm turbo run build --filter="...[origin/main]" ## 문서 경로 기준 -`sn` 관련 문서는 프론트 루트 `docs` 아래에서 별도 트랙으로 관리하는 것을 기본으로 한다. +`sn` 관련 문서는 앱 내부 문서로 관리하는 것을 기본으로 한다. 권장 경로: -- `docs/sn/` -- `docs/sn/refactoring/` -- `docs/sn/response-standardization/` +- `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/**` 대체 가능 여부를 먼저 정리하고 사용자 승인을 받는다. + --- ## 결과 보고 형식 @@ -235,4 +272,5 @@ pnpm turbo run build --filter="...[origin/main]" 이 모노레포는 여러 회사/서비스가 함께 사용하는 저장소다. 이번 작업에서 직접 수정 가능한 범위는 `apps/sn`과 `packages/common/business_components` 두 곳뿐이다. -이 범위를 넘는 변경이 필요해 보이더라도, 먼저 설명하고 승인을 받기 전에는 수정하지 않는다. +하지만 이번 프로젝트의 성격은 리팩토링 전용이 아니라 `sn` 2차사업 고도화 개발이다. +따라서 요구사항 구현은 적극적으로 수행하되, 범위를 넘는 변경은 먼저 설명하고 승인 없이 수정하지 않는다. diff --git a/apps/sn/app/html/AGENTS.md b/apps/sn/app/html/AGENTS.md index 348d1c2d1..1d79419e2 100644 --- a/apps/sn/app/html/AGENTS.md +++ b/apps/sn/app/html/AGENTS.md @@ -1,17 +1,29 @@ -## html 디렉토리 -- 이 디렉토리의 목적은 코드를 화면 publishing과 로직 설정을 위한 폴더이다. -- 작업시 html 디렉토리 이외의 수정이 되지 않도록 해야 한다. -- 추가 *.md 파일의 요청대로 만들되 상위의 를 건드리지 않고 apps\sn\app\html 에 추가파일을 만들어서 처리한다. -- 기존의 package/common/component 와 package/common/business_component를 잘 활용한다. -- 의 시설물 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 시안에서 `` 시설물 layer를 다루는 작업은 API 호출 결과 값이 설정된 대로 zoom level에 따라 모두 보이는지 확인한다. + +## 2차사업 원칙 + +- 작업은 리팩토링 전용이 아니라 2차사업 화면 고도화 목적에 맞춰 수행한다. +- 화면 변경은 요구사항, 화면설계, 기능 명세를 근거로 한다. +- html 시안 작업과 실제 앱 로직 작업이 함께 필요해 보이면 먼저 구분해서 설명한다. + +## Encoding + +- UTF-8 - 한글이 깨지지 않도록 주의할 것 ## 주석 comment + - 한글 주석을 삭제하지 말 것 +- 복잡한 화면 흐름이나 데이터 바인딩 로직은 함수/메서드 단위 설명을 충분히 작성할 것 ## Monorepo structure + apps/ _template as @@ -24,4 +36,3 @@ apps/ sn st wr - diff --git a/apps/sn/docs/AI코딩하네스/개요.md b/apps/sn/docs/AI코딩하네스/개요.md new file mode 100644 index 000000000..1f26ebdd2 --- /dev/null +++ b/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`에 남긴다. diff --git a/apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md b/apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md new file mode 100644 index 000000000..5997c0649 --- /dev/null +++ b/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=&page=0&size=10 +Status: 200 +Response check: +- content: array +- totalElements: number +- number: 0 +- size: 10 +``` + +## 6. 이슈 기록 양식 +| 번호 | 증상 | 재현 단계 | 기대 | 실제 | 우선순위 | 담당 | 링크 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | | | | | | | | diff --git a/apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md b/apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md new file mode 100644 index 000000000..be374d764 --- /dev/null +++ b/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` diff --git a/apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md b/apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md new file mode 100644 index 000000000..b7b8868e4 --- /dev/null +++ b/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` 소스, 브라우저 검증 diff --git a/apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md b/apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md new file mode 100644 index 000000000..1c3471116 --- /dev/null +++ b/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` diff --git a/apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md b/apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md new file mode 100644 index 000000000..51c76c4c1 --- /dev/null +++ b/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` diff --git a/apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md b/apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md new file mode 100644 index 000000000..a6192d573 --- /dev/null +++ b/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` diff --git a/apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md b/apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md new file mode 100644 index 000000000..0796edd18 --- /dev/null +++ b/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`에 기록한다. 근거: 이 하네스 운영 문서 diff --git a/apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md b/apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md new file mode 100644 index 000000000..cd3d9c231 --- /dev/null +++ b/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는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김 diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md new file mode 100644 index 000000000..bbf213bbb --- /dev/null +++ b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md @@ -0,0 +1,5 @@ +# 2026-04-16 개선 기록 + +## 반복 개선점 +- 추정: 기능별 작업이 누적되면 `작업목록.md`에 화면, API, 검증 상태 컬럼을 추가해 진행률을 더 쉽게 볼 수 있다. +- 추정: 브라우저 테스트 절차가 반복되면 `기준문서/007-브라우저점검목록.md`를 추가해 공통 체크리스트로 분리할 수 있다. diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/결과보고.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/결과보고.md new file mode 100644 index 000000000..a325e1585 --- /dev/null +++ b/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`에서 문서 파일이 추적 대상 상태로 표시되는지 확인한다. diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md new file mode 100644 index 000000000..25f52e360 --- /dev/null +++ b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md @@ -0,0 +1,8 @@ +# 2026-04-16 이슈 + +## 외부 범위 이슈 +- 확인 필요: 현재 등록된 외부 범위 이슈는 없다. + +## 미확정 항목 +- 확인 필요: 2차사업 최종 화면명, 메뉴명, URL은 화면설계서와 실행 환경 기준으로 확정해야 한다. +- 확인 필요: 기능별 테스트 계정, 권한, 데이터는 환경별로 별도 확인해야 한다. diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/작업목록.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/작업목록.md new file mode 100644 index 000000000..c8c90bac6 --- /dev/null +++ b/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 스키마는 변경하지 않았다. 근거: 작업 변경 범위 diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md new file mode 100644 index 000000000..be6ea5853 --- /dev/null +++ b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md @@ -0,0 +1,5 @@ +# 2026-04-16 제안 + +## 후속 제안 +- 추정: 기능 개발 착수 전 `작업계획/SN-P2-001-*.md` 형식으로 작업카드를 먼저 작성하면 백엔드와 프론트엔드 변경 범위를 분리해서 추적하기 쉽다. +- 추정: 백엔드 API 변경이 동반되는 작업은 백엔드 작업카드 ID와 프론트 작업카드 ID를 서로 참조하는 방식이 좋다. diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md new file mode 100644 index 000000000..05b870571 --- /dev/null +++ b/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와 문서 예시 전체가 완전히 일치하는지는 별도 코드 기준 검증이 필요하다. +- 로그인, 권한, 테스트 데이터가 확정되지 않은 기능은 브라우저 검증 항목을 작업카드에서 다시 확정해야 한다. diff --git a/apps/sn/docs/AI코딩하네스/보고/개요.md b/apps/sn/docs/AI코딩하네스/보고/개요.md new file mode 100644 index 000000000..599676d4a --- /dev/null +++ b/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코딩하네스` 구조 diff --git a/apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md b/apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md new file mode 100644 index 000000000..6e0417aa3 --- /dev/null +++ b/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. 완료 기준 +- 확인 필요: diff --git a/apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md b/apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md new file mode 100644 index 000000000..5b6bb4ce1 --- /dev/null +++ b/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` 전달 방식과 사용자명 보강은 인증/권한 상태에 따라 결과가 달라질 수 있다. +- 등록/삭제/다운로드는 데이터 변경과 첨부 서비스 의존이 있어 수동 검증 전 테스트 데이터가 필요하다. diff --git a/apps/sn/docs/AI코딩하네스/작업계획/개요.md b/apps/sn/docs/AI코딩하네스/작업계획/개요.md new file mode 100644 index 000000000..c9900ae47 --- /dev/null +++ b/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` +- 기능명은 화면명 또는 업무명을 기준으로 작성한다. +- 한 작업카드에 여러 화면을 무리하게 묶지 않는다. diff --git a/apps/sn/docs/AI코딩하네스/작업목록.md b/apps/sn/docs/AI코딩하네스/작업목록.md new file mode 100644 index 000000000..133371799 --- /dev/null +++ b/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` diff --git a/apps/sn/docs/AI코딩하네스/한글경로-영향.md b/apps/sn/docs/AI코딩하네스/한글경로-영향.md new file mode 100644 index 000000000..f2da3ec0b --- /dev/null +++ b/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` 같은 단계 분리 폴더는 사용하지 않음 diff --git a/packages/common/business_components/README.md b/packages/common/business_components/README.md index 3cda94c58..7b4765ce2 100644 --- a/packages/common/business_components/README.md +++ b/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" }, ``` diff --git a/packages/common/business_components/src/chart.md b/packages/common/business_components/src/chart.md index f2d989375..f8ade24b7 100644 --- a/packages/common/business_components/src/chart.md +++ b/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 ( ); -``` \ No newline at end of file +``` diff --git a/packages/common/business_components/src/form.md b/packages/common/business_components/src/form.md index 4e9b786cf..0d1ff92fe 100644 --- a/packages/common/business_components/src/form.md +++ b/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 { diff --git a/packages/common/business_components/src/ui/search_form_left/searchFormLeft.md b/packages/common/business_components/src/ui/search_form_left/searchFormLeft.md index 04531c27f..d820f1d03 100644 --- a/packages/common/business_components/src/ui/search_form_left/searchFormLeft.md +++ b/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";