diff --git a/apps/sn/AGENTS.md b/apps/sn/AGENTS.md index ba16d7f48..6ca968981 100644 --- a/apps/sn/AGENTS.md +++ b/apps/sn/AGENTS.md @@ -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/**` 대체 가능 여부를 먼저 정리하고 사용자 승인을 받는다. diff --git a/apps/sn/docs/AI코딩하네스/개요.md b/apps/sn/docs/AI코딩하네스/개요.md deleted file mode 100644 index 1f26ebdd2..000000000 --- a/apps/sn/docs/AI코딩하네스/개요.md +++ /dev/null @@ -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`에 남긴다. diff --git a/apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md b/apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md deleted file mode 100644 index 5997c0649..000000000 --- a/apps/sn/docs/AI코딩하네스/검증/001-노후관로관리-브라우저-네트워크-증적.md +++ /dev/null @@ -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=&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코딩하네스/보고/2026-04-16/개선사항.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md deleted file mode 100644 index bbf213bbb..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/개선사항.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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 deleted file mode 100644 index a325e1585..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/결과보고.md +++ /dev/null @@ -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`에서 문서 파일이 추적 대상 상태로 표시되는지 확인한다. diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md deleted file mode 100644 index 25f52e360..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/이슈.md +++ /dev/null @@ -1,8 +0,0 @@ -# 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 deleted file mode 100644 index c8c90bac6..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/작업목록.md +++ /dev/null @@ -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 스키마는 변경하지 않았다. 근거: 작업 변경 범위 diff --git a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md b/apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md deleted file mode 100644 index be6ea5853..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/2026-04-16/제안.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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 deleted file mode 100644 index 05b870571..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/2026-04-17/결과보고.md +++ /dev/null @@ -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와 문서 예시 전체가 완전히 일치하는지는 별도 코드 기준 검증이 필요하다. -- 로그인, 권한, 테스트 데이터가 확정되지 않은 기능은 브라우저 검증 항목을 작업카드에서 다시 확정해야 한다. diff --git a/apps/sn/docs/AI코딩하네스/보고/개요.md b/apps/sn/docs/AI코딩하네스/보고/개요.md deleted file mode 100644 index 599676d4a..000000000 --- a/apps/sn/docs/AI코딩하네스/보고/개요.md +++ /dev/null @@ -1,16 +0,0 @@ -# 작업 기록 - -## 목적 -이 디렉터리는 `sn` 2차사업 작업의 일자별 진행 기록을 남긴다. - -## 파일 구성 -- `작업목록.md`: 해당 일자의 작업 항목과 상태 -- `결과보고.md`: 수행 결과와 검증 결과 -- `이슈.md`: 외부 범위, 미확정, 차단 이슈 -- `제안.md`: 후속 제안 -- `개선사항.md`: 반복 작업 개선점 - -## 기록 원칙 -- 확인됨: 작업 결과는 변경 파일, 영향 범위, 검증 방법, 롤백 방법을 포함한다. 근거: `apps/sn/AGENTS.md` -- 확인됨: 권한 밖 경로 문제는 직접 수정하지 않고 이슈로 기록한다. 근거: `apps/sn/AGENTS.md` -- 추정: 백엔드와 함께 진행하는 기능은 백엔드 작업 기록과 프론트 작업 기록을 서로 참조하면 회귀 추적에 유리하다. 근거: 백엔드 `docs/AI코딩하네스` 구조 diff --git a/apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md b/apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md deleted file mode 100644 index 5b6bb4ce1..000000000 --- a/apps/sn/docs/AI코딩하네스/작업계획/001-SN-P2-노후관로관리-작업카드.md +++ /dev/null @@ -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` 전달 방식과 사용자명 보강은 인증/권한 상태에 따라 결과가 달라질 수 있다. -- 등록/삭제/다운로드는 데이터 변경과 첨부 서비스 의존이 있어 수동 검증 전 테스트 데이터가 필요하다. diff --git a/apps/sn/docs/AI코딩하네스/작업계획/개요.md b/apps/sn/docs/AI코딩하네스/작업계획/개요.md deleted file mode 100644 index c9900ae47..000000000 --- a/apps/sn/docs/AI코딩하네스/작업계획/개요.md +++ /dev/null @@ -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` -- 기능명은 화면명 또는 업무명을 기준으로 작성한다. -- 한 작업카드에 여러 화면을 무리하게 묶지 않는다. diff --git a/apps/sn/docs/AI코딩하네스/작업목록.md b/apps/sn/docs/AI코딩하네스/작업목록.md deleted file mode 100644 index 133371799..000000000 --- a/apps/sn/docs/AI코딩하네스/작업목록.md +++ /dev/null @@ -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` diff --git a/apps/sn/docs/AI코딩하네스/한글경로-영향.md b/apps/sn/docs/AI코딩하네스/한글경로-영향.md deleted file mode 100644 index f2da3ec0b..000000000 --- a/apps/sn/docs/AI코딩하네스/한글경로-영향.md +++ /dev/null @@ -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` 같은 단계 분리 폴더는 사용하지 않음 diff --git a/apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md b/apps/sn/docs/기준문서/001-프로젝트.md similarity index 98% rename from apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md rename to apps/sn/docs/기준문서/001-프로젝트.md index be374d764..0b06a37e5 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/001-프로젝트.md +++ b/apps/sn/docs/기준문서/001-프로젝트.md @@ -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` \ No newline at end of file diff --git a/apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md b/apps/sn/docs/기준문서/002-화면맵.md similarity index 97% rename from apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md rename to apps/sn/docs/기준문서/002-화면맵.md index b7b8868e4..d65e883c6 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/002-화면맵.md +++ b/apps/sn/docs/기준문서/002-화면맵.md @@ -16,4 +16,4 @@ ## 확인 필요 항목 - 확인 필요: 2차사업 최종 화면명과 메뉴 트리는 화면설계서 기준으로 확정해야 한다. 근거: 2차사업 화면설계서 -- 확인 필요: 실제 운영 메뉴 권한과 라우팅 정책은 실행 환경에서 확인해야 한다. 근거: `apps/sn` 소스, 브라우저 검증 +- 확인 필요: 실제 운영 메뉴 권한과 라우팅 정책은 실행 환경에서 확인해야 한다. 근거: `apps/sn` 소스, 브라우저 검증 \ No newline at end of file diff --git a/apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md b/apps/sn/docs/기준문서/003-API사용.md similarity index 99% rename from apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md rename to apps/sn/docs/기준문서/003-API사용.md index 1c3471116..bd17b1bde 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/003-API사용.md +++ b/apps/sn/docs/기준문서/003-API사용.md @@ -21,4 +21,4 @@ ## 금지 기준 - 확인됨: 프론트엔드에서 백엔드 API 계약 변경을 전제로 구현하지 않는다. 근거: `apps/sn/AGENTS.md` -- 확인됨: 백엔드 응답을 임시로 우회하기 위한 화면 전용 하드코딩을 추가하지 않는다. 근거: `apps/sn/AGENTS.md` +- 확인됨: 백엔드 응답을 임시로 우회하기 위한 화면 전용 하드코딩을 추가하지 않는다. 근거: `apps/sn/AGENTS.md` \ No newline at end of file diff --git a/apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md b/apps/sn/docs/기준문서/004-컴포넌트정책.md similarity index 97% rename from apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md rename to apps/sn/docs/기준문서/004-컴포넌트정책.md index 51c76c4c1..864726d4a 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/004-컴포넌트정책.md +++ b/apps/sn/docs/기준문서/004-컴포넌트정책.md @@ -19,4 +19,4 @@ - 확인 필요: 브라우저 확인 화면 ## 외부 범위 이슈 -- 확인됨: 권한 밖 공통 패키지 수정이 필요해 보이면 직접 고치지 않고 문제 원인, 수정 필요 경로, `sn` 영향 범위, 타 앱 영향 가능성을 문서화한다. 근거: `apps/sn/AGENTS.md` +- 확인됨: 권한 밖 공통 패키지 수정이 필요해 보이면 직접 고치지 않고 문제 원인, 수정 필요 경로, `sn` 영향 범위, 타 앱 영향 가능성을 문서화한다. 근거: `apps/sn/AGENTS.md` \ No newline at end of file diff --git a/apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md b/apps/sn/docs/기준문서/005-상태관리정책.md similarity index 97% rename from apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md rename to apps/sn/docs/기준문서/005-상태관리정책.md index a6192d573..6bc7d99a3 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/005-상태관리정책.md +++ b/apps/sn/docs/기준문서/005-상태관리정책.md @@ -16,4 +16,4 @@ ## 주의 사항 - 확인됨: 요구사항 근거 없는 기능 추가는 금지한다. 근거: `apps/sn/AGENTS.md` -- 확인됨: 다른 앱에서 사용하는 공통 상태 로직을 `sn` 문제 해결 목적으로 직접 바꾸지 않는다. 근거: `apps/sn/AGENTS.md` +- 확인됨: 다른 앱에서 사용하는 공통 상태 로직을 `sn` 문제 해결 목적으로 직접 바꾸지 않는다. 근거: `apps/sn/AGENTS.md` \ No newline at end of file diff --git a/apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md b/apps/sn/docs/기준문서/006-검증정책.md similarity index 96% rename from apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md rename to apps/sn/docs/기준문서/006-검증정책.md index 0796edd18..833d33a4a 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/006-검증정책.md +++ b/apps/sn/docs/기준문서/006-검증정책.md @@ -31,4 +31,4 @@ pnpm turbo run build --filter="...[origin/main]" ## 검증 기록 - 확인됨: 검증 결과는 `보고/YYYY-MM-DD/결과보고.md`에 기록한다. 근거: 이 하네스 운영 문서 -- 확인됨: 외부 범위 오류는 `보고/YYYY-MM-DD/이슈.md`에 기록한다. 근거: 이 하네스 운영 문서 +- 확인됨: 외부 범위 오류는 `보고/YYYY-MM-DD/이슈.md`에 기록한다. 근거: 이 하네스 운영 문서 \ No newline at end of file diff --git a/apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md b/apps/sn/docs/기준문서/007-멀티에이전트운영.md similarity index 99% rename from apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md rename to apps/sn/docs/기준문서/007-멀티에이전트운영.md index cd3d9c231..1fb38be82 100644 --- a/apps/sn/docs/AI코딩하네스/기준문서/007-멀티에이전트운영.md +++ b/apps/sn/docs/기준문서/007-멀티에이전트운영.md @@ -42,4 +42,4 @@ ## 검증 보고 기준 - FE는 빌드 명령, 화면 URL, 사용자 조작, 기대 결과, 네트워크 응답 확인 기준을 남김 - BE는 API 요청/응답 예시와 DB 영향 여부를 남김 -- QA는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김 +- QA는 실행한 명령, 통과/실패 여부, 재현 절차, 남은 위험을 남김 \ No newline at end of file diff --git a/apps/sn/docs/기준문서/008-설계정책.md b/apps/sn/docs/기준문서/008-설계정책.md new file mode 100644 index 000000000..34016b5be --- /dev/null +++ b/apps/sn/docs/기준문서/008-설계정책.md @@ -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`를 함께 본다. diff --git a/apps/sn/docs/기준문서/009-네이밍규칙.md b/apps/sn/docs/기준문서/009-네이밍규칙.md new file mode 100644 index 000000000..39626ba75 --- /dev/null +++ b/apps/sn/docs/기준문서/009-네이밍규칙.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` 접두사를 우선 사용한다. diff --git a/apps/sn/docs/기준문서/010-용어사전.md b/apps/sn/docs/기준문서/010-용어사전.md new file mode 100644 index 000000000..0ff835c76 --- /dev/null +++ b/apps/sn/docs/기준문서/010-용어사전.md @@ -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 필드명 +- 프론트 변수명 +- 기준 용어 +- 기존 별칭 사용 여부 +- 용어사전 갱신 여부 + diff --git a/apps/sn/docs/기준문서/011-환경빌드문제대응.md b/apps/sn/docs/기준문서/011-환경빌드문제대응.md new file mode 100644 index 000000000..c9620246e --- /dev/null +++ b/apps/sn/docs/기준문서/011-환경빌드문제대응.md @@ -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` 영향 범위를 함께 기록한다. diff --git a/apps/sn/docs/기준문서/012-코드리뷰체크리스트.md b/apps/sn/docs/기준문서/012-코드리뷰체크리스트.md new file mode 100644 index 000000000..ddf6698db --- /dev/null +++ b/apps/sn/docs/기준문서/012-코드리뷰체크리스트.md @@ -0,0 +1,25 @@ +# 012. 코드리뷰체크리스트 + +## 1. 화면 동작 +- 조회, 상세, 다운로드, 팝업 흐름이 요구사항대로 동작하는가 +- 로딩/빈 화면/에러 상태가 빠지지 않았는가 +- 기존 화면 동작을 깨는 회귀가 없는가 + +## 2. API 연동 +- 실제 백엔드 요청 파라미터와 응답 필드를 기준으로 구현했는가 +- 에러 응답 또는 예외 케이스를 화면에서 처리하는가 +- 프론트 임의 가공 로직이 계약 불일치를 숨기고 있지 않은가 + +## 3. 범위 준수 +- 수정 범위가 `apps/sn/**` 또는 `packages/common/business_components/**` 안에 머무르는가 +- 다른 공통 패키지 수정이 필요하면 원인과 영향 범위를 먼저 정리했는가 + +## 4. 코드 품질 +- 컴포넌트 책임이 과도하게 섞이지 않았는가 +- 상태, 이벤트, 비동기 호출이 읽기 쉽게 분리되어 있는가 +- 이름이 역할을 설명하고 있는가 + +## 5. 검증 +- 빌드 명령 또는 필요한 로컬 검증을 수행했는가 +- 브라우저에서 핵심 시나리오를 확인했는가 +- 변경 이유, 영향 범위, 남은 리스크를 결과 보고에 남겼는가 diff --git a/apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md b/apps/sn/docs/작업계획/000-작업카드-템플릿.md similarity index 99% rename from apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md rename to apps/sn/docs/작업계획/000-작업카드-템플릿.md index 6e0417aa3..0527d861e 100644 --- a/apps/sn/docs/AI코딩하네스/작업계획/000-작업카드-템플릿.md +++ b/apps/sn/docs/작업계획/000-작업카드-템플릿.md @@ -71,4 +71,4 @@ - 확인 필요: ## 10. 완료 기준 -- 확인 필요: +- 확인 필요: \ No newline at end of file