# Contributing

## 기본 규칙

- `main`은 팀 기준 브랜치로 사용합니다.
- `dev`는 팀 개발 통합 브랜치로 사용합니다.
- `main`, `dev`는 브랜치이고 `8080`, `8081`은 실행 환경입니다.
- 권장 운영은 `main -> 8080`, `dev 또는 작업 브랜치 -> 8081`입니다.
- 기능 개발과 버그 수정은 각자 작업 브랜치에서 진행합니다.
- 직접 `8080` 기준 파일을 수정하지 않습니다.
- 검증은 먼저 `8081` 개발 환경에서 수행합니다.
- 커밋은 한 기능 또는 한 버그 단위로 작게 나눕니다.
- 작업 시작 전 [docs/TEAM_GUIDE.md](docs/TEAM_GUIDE.md)를 먼저 읽습니다.

## 권장 브랜치 이름

- `feature/<name>-<topic>`
- `fix/<name>-<topic>`
- `chore/<name>-<topic>`

예:

- `fix/alex-organization-save`
- `feature/minsu-ledger-filter`

## 작업 순서

1. `main` 최신 상태를 받습니다.
2. 작업 브랜치를 만듭니다.
3. `.env.example`을 `.env`로 복사합니다.
4. 필요한 경우 `./scripts/prepare_dev_worktree.sh`로 격리된 개발 워크스페이스를 준비합니다.
5. `8081`에서 수정과 검증을 진행합니다.
6. 관련 publish 스크립트가 있는 화면은 publish 후 실제 런타임 파일까지 확인합니다.
7. `docs/REGRESSION_CHECKLIST.md` 기준으로 필요한 시나리오를 점검합니다.
8. 커밋 후 PR을 생성합니다.

## PR 규칙

- PR 하나에는 한 주제만 담습니다.
- PR 본문에 아래 내용을 포함합니다.
  - 작업 목적
  - 변경 범위
  - 검증 방법
  - DB 영향 여부
- 공용 구조 파일 수정 시 영향 화면을 명시합니다.

## 파일 수정 기준

- 탭 화면 수정은 먼저 `frontend/apps/*`를 봅니다.
- 조직현황은 `frontend/apps/organization`와 `legacy/static/*` 구조를 함께 확인합니다.
- integration 화면 런타임은 `incoming-files/served/*`지만, 직접 수정 원본은 `frontend/apps/*`입니다.
- 원본 참고 파일은 `incoming-files/reference/*`에만 둡니다.

## 문서 기준

- 저장소 진입: [README.md](README.md)
- 작업 시작 기준: [docs/TEAM_GUIDE.md](docs/TEAM_GUIDE.md)
- 개발/운영 DB 원칙: [docs/DEV_PROD_DB_PROTOCOL.md](docs/DEV_PROD_DB_PROTOCOL.md)
- 실제 서빙 책임 맵: [docs/architecture/8081_SERVING_MAP.md](docs/architecture/8081_SERVING_MAP.md)