ONAANDALL/frontend

Fork 0

Files

T

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

2026-04-23 17:27:19 +09:00

15 KiB

Raw Blame History

AGENTS.md

목적

이 앱은 하수관로 운영관리 시스템 프론트엔드 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/**

문서 작업은 예외적으로 프론트엔드 AI 개발 공통 문서에 한해 FE_REPO_ROOT/docs/**를 수정할 수 있다. 단, 특정 sn 화면/기능 산출물은 기본적으로 apps/sn/docs/**에 작성하고, 여러 앱이 함께 보는 기준 문서만 FE_REPO_ROOT/docs/**에 작성한다.

위 두 경로를 제외한 나머지 경로는 모두 기본적으로 읽기 전용으로 간주한다.

예를 들어 아래 경로는 직접 수정하면 안 된다.

apps/as/**
apps/cm/**
apps/cs/**
apps/dc/**
apps/dm/**
apps/dm_new/**
apps/fo/**
apps/st/**
apps/wr/**
apps/common/**
docs/** (단, 프론트엔드 AI 개발 공통 문서 예외는 위 기준을 따른다)
packages/common/assets/**
packages/common/auth/**
packages/common/components/**
packages/common/config/**
packages/common/network/**
packages/mindone/**
packages/oneandall/**
packages/rsone/**

수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 아래 내용을 먼저 정리해서 공유한다.

문제 원인
수정 필요 경로
sn 영향 범위
타 앱 영향 가능성

경로 및 참조 기준

문서와 작업 지시에서는 개발자별 로컬 절대경로 대신 아래 기준 변수를 우선 사용한다.

WORKSPACE_ROOT: 백엔드와 프론트엔드를 함께 두는 공통 작업 루트
FE_REPO_ROOT: WORKSPACE_ROOT/frontend
SN_APP_ROOT: FE_REPO_ROOT/apps/sn
BUSINESS_COMPONENTS_ROOT: FE_REPO_ROOT/packages/common/business_components

화면, 페이지, 컴포넌트 참조는 아래 기준을 따른다.

실제 sn 페이지/라우트: SN_APP_ROOT/app/**
sn 앱 내부 전용 모듈: SN_APP_ROOT/app/**, SN_APP_ROOT/src/**
sn 내부 검토용 HTML/시안: SN_APP_ROOT/app/html/**
공통 비즈니스 UI 컴포넌트: BUSINESS_COMPONENTS_ROOT/src/**
직접 수정 금지 공통 패키지: FE_REPO_ROOT/packages/common/components/**, FE_REPO_ROOT/packages/common/auth/**, FE_REPO_ROOT/packages/common/network/**

코드 import 경로를 설명할 때는 실제 코드의 alias를 함께 확인한다. 예를 들어 sn 앱 내부는 @/..., 공통 비즈니스 컴포넌트는 @common/business_components 참조를 우선 확인한다.

Monorepo 이해

이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다.

워크스페이스 구조는 아래와 같다.

apps/*
apps/common/*
packages/*
packages/common/*

현재 작업 대상은 아래 두 축이다.

서비스 앱: apps/sn
공통 비즈니스 UI 패키지: packages/common/business_components

sn 앱은 아래 공통 패키지들을 사용하지만, 이번 권한 범위상 직접 수정 가능한 공통 패키지는 business_components만이다.

@common/assets
@common/business_components
@common/components
@common/config

즉, sn에서 문제가 보이더라도 원인이 @common/components, @common/auth, @common/network 등에 있으면 직접 수정하지 말고 보고만 한다.

작업 목표

2차사업 요구사항을 sn 화면과 흐름에 반영한다.
sn 앱의 기존 사용자 동작을 가능한 한 유지하면서 기능을 확장한다.
백엔드(sewerage-service)와의 연동을 기준으로 화면, 폼, 조회/저장 흐름을 정확히 맞춘다.
business_components 수정이 필요할 때는 sn 요구사항을 만족하는 최소 범위로 수행한다.
monorepo 내 타 앱 영향은 최소화한다.
1차 개발 화면의 레이아웃, 컴포넌트 조합, 테이블/모달/폼/지도 패턴을 우선 재사용한다.

작업 원칙

모든 변경은 2차 요구사항, 화면설계, 기능 명세 또는 승인된 작업 문서를 근거로 한다.
apps/sn과 packages/common/business_components 범위를 넘는 수정은 하지 않는다.
공통 패키지 수정은 sn 요구사항을 충족하기 위한 최소 범위로 제한한다.
다른 앱 전용 로직을 business_components에 넣지 않는다.
신규 화면을 만들더라도 먼저 기존 sn 페이지와 business_components에서 동일하거나 유사한 컴포넌트, 레이아웃, 테이블, 모달, 입력 폼, 지도 패널 패턴을 찾는다.
기존 1차 디자인과 다른 독립 UI 스타일, 별도 디자인 시스템, 임의 색상/간격/컴포넌트 구조를 새로 만들지 않는다.
기존 컴포넌트로 표현이 어려운 경우에는 먼저 어떤 컴포넌트가 부족한지, SN_APP_ROOT에서 조합 가능한지, BUSINESS_COMPONENTS_ROOT 수정이 필요한지 구분해서 보고한다.
불확실한 경우 먼저 계획을 제시한다.
변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다.
기존 주석은 임의로 제거하지 않는다.
복잡한 컴포넌트, 훅, 분기 로직, 상태 흐름, 데이터 변환 로직은 함수/메서드 단위 설명 주석을 충분히 작성한다.
한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
작업 범위를 넓히기보다 sn 내부 해결을 우선한다.
백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다.
작업 문서는 apps/sn/docs/ 하위에 작업 단위 폴더를 만들어 기록한다.

기존 컴포넌트 사용 기준

2차 고도화 화면은 1차 개발 산출물을 기반으로 확장한다. 따라서 화면을 새로 디자인하기보다 기존 컴포넌트를 조합하고 필요한 데이터/API 연동만 보강한다.

우선 재사용 대상은 아래 순서로 확인한다.

SN_APP_ROOT/app/**에 이미 존재하는 동일 업무 화면, 지도 화면, 검색 모달, 상세 패널, 상태 관리 패턴
SN_APP_ROOT/src/**에 있는 앱 내부 공통 모듈, feature/shared 구조
BUSINESS_COMPONENTS_ROOT/src/**에 있는 공통 비즈니스 UI, 지도, 테이블, 엑셀, 폼 관련 컴포넌트

아래 작업은 금지한다.

실제 서비스 화면에 독립 정적 HTML 디자인을 그대로 반영
기존 테이블/모달/폼/버튼/지도 패널이 있는데 별도 UI를 새로 구현
기존 1차 화면과 다른 신규 색상 체계, 카드형 레이아웃, 랜딩형 디자인을 임의 적용
@common/components, @common/auth, @common/network 등 수정 금지 패키지를 직접 변경

apps/sn/app/html/**의 정적 HTML은 요구사항 해석, 퍼블리싱 비교, 로직 검토용으로만 사용한다. 실제 개발로 전환할 때는 반드시 기존 React/Next 페이지와 business_components 기반 컴포넌트 조합으로 다시 구현한다.

허용 작업

apps/sn 내부 신규 화면/기능 개발
apps/sn 내부 화면/컴포넌트/훅/상태관리 코드 보완 및 리팩토링
apps/sn 내부 API 호출부 정리
apps/sn 내부 타입 정리
apps/sn 내부 라우팅/화면 구조 보완
packages/common/business_components 내부 공통 비즈니스 컴포넌트 개선
sn이 사용하는 business_components의 타입/렌더링/구조 개선
요구사항 반영을 위한 UI/UX 보완
문서 업데이트
타입 오류 수정
빌드 오류 수정
테스트/검증 코드 또는 검증용 산출물 작성

금지 작업

sn과 무관한 타 앱 수정
packages/common/business_components 외의 공통 패키지 수정
요구사항 근거 없는 기능 추가
백엔드 응답 구조를 프론트에서 임의 가정하여 계약을 바꾸는 작업
다른 회사/앱 전용 분기 추가
권한 범위를 넘어서는 전역 리팩토링
근거 없는 대량 수정

우선 판단 기준

문제가 발생했을 때 아래 순서로 해결 범위를 판단한다.

apps/sn 내부에서 해결 가능한가
packages/common/business_components 수정으로 해결 가능한가
그 외 공통 패키지 수정이 필요한가

3번에 해당하면 직접 수정하지 말고, 아래 내용을 정리해서 먼저 공유한다.

문제 원인
수정 필요 경로
sn 영향 범위
타 앱 영향 가능성

html 디렉터리 규칙

경로: apps/sn/app/html
이 디렉터리는 퍼블리싱/정적 HTML/로직 검토 목적의 별도 영역으로 본다.
html 하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다.
html 하위 요청이라고 해서 sn의 실제 앱 코드 전체를 함께 수정하지 않는다.
html 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.

빌드 및 검증 기준

이 저장소는 main 브랜치 push 전에 .husky/pre-push에서 아래 빌드를 수행한다.

pnpm turbo run build --filter="...[origin/$BRANCH]"

따라서 로컬 검증도 아래 순서로 수행하는 것을 기본으로 한다.

`sn`만 수정한 경우

pnpm --filter sn run build
pnpm turbo run build --filter=sn

`business_components`를 수정한 경우

pnpm --filter @common/business_components run build
pnpm --filter sn run build
pnpm turbo run build --filter="...[origin/main]"

pre-push와 동일한 최종 확인

git fetch origin
pnpm turbo run build --filter="...[origin/main]" --dry-run
pnpm turbo run build --filter="...[origin/main]"

business_components를 수정했는데 이 빌드가 깨지면, sn뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다.

가능하면 아래 검증도 함께 수행한다.

sn 개발 서버 실행
백엔드 연동 확인
브라우저 화면 동작 확인
네트워크 응답 확인

타입 오류 처리 기준

push 실패 원인이 타입 오류라면 먼저 현재 수정 범위 안에서 해결 가능한지 확인한다.
sn 내부 타입 오류면 apps/sn에서 해결한다.
business_components 타입 오류면 그 패키지 안에서 해결한다.
다른 공통 패키지 타입 오류가 원인이면 직접 고치지 말고 보고한다.

주석 및 인코딩 규칙

파일 인코딩은 UTF-8로 유지한다.
한글 주석이 깨진 상태로 저장하지 않는다.
기존 주석은 정당한 이유 없이 삭제하지 않는다.
복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.

문서 경로 기준

프론트엔드 AI 개발 공통 문서는 백엔드 문서 구조와 동일한 방식으로 FE_REPO_ROOT/docs/**에서 관리할 수 있다. sn 특정 화면/기능 산출물은 앱 내부 문서로 관리하는 것을 기본으로 한다.

프론트엔드 공통 AI 개발 문서 권장 경로:

FE_REPO_ROOT/docs/README.md
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/구조/99-미확인사항.md
FE_REPO_ROOT/docs/실행명세/
FE_REPO_ROOT/docs/응답표준화/
FE_REPO_ROOT/docs/검증/
FE_REPO_ROOT/docs/템플릿/
FE_REPO_ROOT/docs/AI코딩하네스/

프론트엔드 공통 문서는 백엔드 문서 체계처럼 주제별 디렉터리로 나눈다. 예를 들어 화면 실행/브라우저 검증 흐름은 실행명세, API 응답 사용/표시/오류 처리 기준은 응답표준화, 저장소와 화면 구조 기준은 구조에 둔다. 단, FE_REPO_ROOT/docs/**에는 프론트엔드 공통 기준만 작성하고, 백엔드 Controller/Service/Repository/DB 상세는 작성하지 않는다.

sn 관련 문서 권장 경로:

apps/sn/docs/
apps/sn/docs/README.md
apps/sn/docs/AI코딩하네스/
apps/sn/docs/응답표준화/
apps/sn/docs/검증/
apps/sn/docs/{기능명}/README.md
apps/sn/docs/{기능명}/00-범위.md
apps/sn/docs/{기능명}/01-기존화면기반-컴포넌트분해.md
apps/sn/docs/{기능명}/02-컴포넌트별-작업목록.md
apps/sn/docs/{기능명}/03-API응답필드매핑표.md
apps/sn/docs/{기능명}/04-화면흐름.md
apps/sn/docs/{기능명}/05-검증계획.md
apps/sn/docs/{기능명}/06-검증결과.md
apps/sn/docs/{기능명}/99-미확인사항.md

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

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

FE_REPO_ROOT/docs/**는 여러 앱이 함께 보는 프론트엔드 AI 개발 기준 문서로만 사용한다. 특정 회사/서비스 앱의 구현 상세, 화면별 산출물, 검증 결과는 해당 앱 문서 위치에 작성한다. FE_REPO_ROOT/docs/** 변경이 필요한 경우에는 백엔드 문서 구조와 맞추기 위한 목적, 영향 범위, apps/sn/docs/** 대체 가능 여부를 먼저 판단한다.

결과 보고 형식

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

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

중요

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

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

15 KiB Raw Blame History