diff --git a/apps/sn/AGENTS.md b/apps/sn/AGENTS.md index 45f49f296..3780bece8 100644 --- a/apps/sn/AGENTS.md +++ b/apps/sn/AGENTS.md @@ -1,43 +1,238 @@ -## Project -This repository contains a Next.js web application. +# AGENTS.md -Main technologies: -- Next.js -- TypeScript -- pnpm workspace -- turborepo +## 목적 +이 앱은 하수관로 운영관리 시스템 프론트엔드 `sn` 프로젝트이다. -이 저장소는 pnpm workspace + Turborepo 기반 monorepo이다. +이 문서는 `apps/sn` 작업 시 따라야 할 전용 작업 기준을 정의한다. +이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다. +따라서 `sn` 작업 시에는 작업 가능 범위와 수정 금지 범위를 엄격하게 지켜야 한다. -- 워크스페이스 범위는 `apps/*`, `apps/common/*`, `packages/*`, `packages/common/*` -- 루트 스크립트는 `turbo run build`, `turbo run dev` 를 사용한다 -- `build` 작업은 의존 패키지의 `build` 를 먼저 수행한다 (`dependsOn: ["^build"]`) -- `dev` 는 캐시하지 않는 지속 실행 작업이다 -- 변경 범위만 선택 실행할 수 있으므로, 전체 빌드보다 `--filter` 사용을 우선한다 +--- -## Encoding -- UTF-8 -- 한글이 깨지지 않도록 주의할 것 +## 작업 대상 -## 주석 comment -- 한글 주석을 삭제하지 말 것 +이번 작업에서 수정 가능한 경로는 아래 두 곳만 허용한다. -## html 디렉토리 -- apps/sn/app/html -- 이 디렉토리의 목적은 코드를 화면 publishing과 로직 설정을 위한 폴더이다. -- html 하위 *.md 요청 작업시 html 디렉토리 이외의 수정이 되지 않도록 해야 한다. +- `apps/sn/**` +- `packages/common/business_components/**` -## Monorepo structure -apps/ - _template - as - cm - cs - dc - dm - dm_new - fo - sn - st - wr +위 두 경로를 제외한 나머지 경로는 모두 기본적으로 읽기 전용으로 간주한다. +예를 들어 아래 경로는 직접 수정하면 안 된다. + +- `apps/as/**` +- `apps/cm/**` +- `apps/cs/**` +- `apps/dc/**` +- `apps/dm/**` +- `apps/dm_new/**` +- `apps/fo/**` +- `apps/st/**` +- `apps/wr/**` +- `apps/common/**` +- `packages/common/assets/**` +- `packages/common/auth/**` +- `packages/common/components/**` +- `packages/common/config/**` +- `packages/common/network/**` +- `packages/mindone/**` +- `packages/oneandall/**` +- `packages/rsone/**` + +수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 영향 범위를 정리해서 먼저 보고해야 한다. + +--- + +## 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` 등에 있으면 직접 수정하지 말고 보고만 한다. + +--- + +## 작업 목표 + +- 하수관로 운영관리 시스템 `sn`의 기존 화면 동작 유지 +- `sn` 내부 코드 가독성 향상 +- `sn` 화면/기능에 필요한 범위에서만 공통 비즈니스 UI 정리 +- `packages/common/business_components` 변경 시 `sn` 영향 범위 명확화 +- monorepo 내 타 앱 영향 최소화 + +--- + +## 작업 원칙 + +1. 기존 외부 동작을 변경하지 않는다. +2. `sn` 범위와 `business_components` 범위를 넘는 수정은 하지 않는다. +3. 공통 패키지 수정은 `sn` 요구사항을 충족하기 위한 최소 범위로 제한한다. +4. 다른 앱 전용 로직을 `business_components`에 넣지 않는다. +5. 불확실한 경우 먼저 계획을 제시한다. +6. 변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다. +7. 기존 주석은 임의로 제거하지 않는다. +8. 복잡한 컴포넌트, 훅, 분기 로직을 수정할 때는 클래스/메서드/함수 단위 설명 주석을 충분히 작성한다. +9. 한글이 깨지지 않도록 반드시 UTF-8로 유지한다. +10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다. +11. 작업 문서를 작성할때는 `apps/sn/docs` 폴더에 작업단위로 폴더를 생성해서 기록한다. + +--- + +## 허용 작업 + +- `apps/sn` 내부 화면/컴포넌트/훅/상태관리 코드 리팩토링 +- `apps/sn` 내부 API 호출부 정리 +- `apps/sn` 내부 타입 정리 +- `apps/sn` 내부 라우팅/화면 구조 보완 +- `packages/common/business_components` 내부 공통 비즈니스 컴포넌트 개선 +- `sn`이 사용하는 `business_components`의 타입/렌더링/구조 정리 +- 관련 문서 업데이트 +- 타입 오류 수정 +- 빌드 오류 수정 + +--- + +## 금지 작업 + +- `sn`과 무관한 타 앱 수정 +- `packages/common/business_components` 외의 공통 패키지 수정 +- API 계약 임의 변경 +- 백엔드 응답 구조를 프론트에서 임의 가정하여 데이터 구조를 바꾸는 작업 +- 다른 회사/앱 전용 분기 추가 +- 권한 범위를 넘어서는 전역 리팩토링 +- 근거 없는 대량 수정 + +--- + +## 우선 판단 기준 + +문제가 발생했을 때 아래 순서로 해결 범위를 판단한다. + +1. `apps/sn` 내부에서 해결 가능한가 +2. `packages/common/business_components` 수정으로 해결 가능한가 +3. 그 외 공통 패키지 수정이 필요한가 + +3번에 해당하면 직접 수정하지 말고, 아래 내용을 정리해서 먼저 공유한다. + +- 문제 원인 +- 수정 필요 경로 +- `sn` 영향 범위 +- 타 앱 영향 가능성 + +--- + +## html 디렉터리 규칙 + +- 경로: `apps/sn/app/html` +- 이 디렉터리는 퍼블리싱/정적 HTML/로직 확인 목적의 별도 영역으로 본다. +- `html` 하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다. +- `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다. +- `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다. + +--- + +## 빌드 및 검증 기준 + +이 저장소는 `main` 브랜치 push 전에 `.husky/pre-push`에서 아래 빌드를 수행한다. + +```sh +pnpm turbo run build --filter="...[origin/$BRANCH]" +``` + +따라서 로컬 검증도 아래 순서로 수행하는 것을 기본으로 한다. + +### `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]" +``` + +### pre-push와 동일한 최종 확인 + +```powershell +git fetch origin +pnpm turbo run build --filter="...[origin/main]" --dry-run +pnpm turbo run build --filter="...[origin/main]" +``` + +`business_components`를 수정했는데 이 빌드가 깨지면, `sn`뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다. + +--- + +## 타입 오류 처리 기준 + +- push 실패 원인이 타입 오류라면 먼저 현재 수정 범위 안에서 해결 가능한지 확인한다. +- `sn` 내부 타입 오류면 `apps/sn`에서 해결한다. +- `business_components` 타입 오류면 그 패키지 안에서 해결한다. +- 다른 공통 패키지 타입 오류가 원인이면 직접 고치지 말고 보고한다. + +--- + +## 주석 및 인코딩 규칙 + +- 파일 인코딩은 UTF-8로 유지한다. +- 한글 주석이 깨진 상태로 저장하지 않는다. +- 기존 주석은 정당한 이유 없이 삭제하지 않는다. +- 복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다. + +--- + +## 문서 경로 기준 + +`sn` 관련 문서는 프론트 루트 `docs` 아래에서 별도 트랙으로 관리하는 것을 기본으로 한다. + +권장 경로: + +- `docs/sn/` +- `docs/sn/refactoring/` +- `docs/sn/response-standardization/` + +문서 작업 시에도 `sn` 범위를 벗어나는 앱 문서는 임의로 수정하지 않는다. + +--- + +## 결과 보고 형식 + +모든 작업 결과는 아래 형식을 따른다. + +- 작업 목적 +- 수정 대상 파일 +- 변경 내용 요약 +- 영향 범위 +- 테스트 / 검증 방법 +- 롤백 방법 +- 남은 리스크 + +--- + +## 중요 + +이 모노레포는 여러 회사/서비스가 함께 사용하는 저장소다. +이번 작업에서 직접 수정 가능한 범위는 `apps/sn`과 `packages/common/business_components` 두 곳뿐이다. + +이 범위를 넘는 변경이 필요해 보이더라도, 먼저 설명하고 승인을 받기 전에는 수정하지 않는다.