Clarify branch and environment rules

CONTRIBUTING.md

@@ -3,6 +3,9 @@
 ## 기본 규칙
 
 - `main`은 팀 기준 브랜치로 사용합니다.
+- `dev`는 팀 개발 통합 브랜치로 사용합니다.
+- `main`, `dev`는 브랜치이고 `8080`, `8081`은 실행 환경입니다.
+- 권장 운영은 `main -> 8080`, `dev 또는 작업 브랜치 -> 8081`입니다.
 - 기능 개발과 버그 수정은 각자 작업 브랜치에서 진행합니다.
 - 직접 `8080` 기준 파일을 수정하지 않습니다.
 - 검증은 먼저 `8081` 개발 환경에서 수행합니다.
@@ -24,11 +27,12 @@
 
 1. `main` 최신 상태를 받습니다.
 2. 작업 브랜치를 만듭니다.
-3. 필요한 경우 `./scripts/prepare_dev_worktree.sh`로 격리된 개발 워크스페이스를 준비합니다.
+3. `.env.example`을 `.env`로 복사합니다.
-4. `8081`에서 수정과 검증을 진행합니다.
+4. 필요한 경우 `./scripts/prepare_dev_worktree.sh`로 격리된 개발 워크스페이스를 준비합니다.
-5. 관련 publish 스크립트가 있는 화면은 publish 후 실제 런타임 파일까지 확인합니다.
+5. `8081`에서 수정과 검증을 진행합니다.
-6. `docs/REGRESSION_CHECKLIST.md` 기준으로 필요한 시나리오를 점검합니다.
+6. 관련 publish 스크립트가 있는 화면은 publish 후 실제 런타임 파일까지 확인합니다.
-7. 커밋 후 PR을 생성합니다.
+7. `docs/REGRESSION_CHECKLIST.md` 기준으로 필요한 시나리오를 점검합니다.
+8. 커밋 후 PR을 생성합니다.
 
 ## PR 규칙
 

README.md

@@ -25,6 +25,8 @@
 - `incoming-files/served/*`와 `legacy/static/*`는 런타임 자산입니다.
 - 조직현황/멤버/자리배치 관련 검증은 `8081` 개발 환경에서 먼저 수행합니다.
 - `8080`은 기준 데이터와 공개 환경, `8081`은 검증 환경으로 다룹니다.
+- `main`, `dev`는 Git 브랜치이고 `8080`, `8081`은 실행 환경입니다.
+- 권장 운영은 `main -> 8080`, `dev 또는 작업 브랜치 -> 8081`입니다.
 
 ## 시작 문서
 
@@ -39,12 +41,14 @@
 기본 공개 환경:
 
 ```bash
+cp .env.example .env
 docker compose up -d --build
 ```
 
 격리된 `8081` 개발 환경:
 
 ```bash
+cp .env.example .env
 ./scripts/prepare_dev_worktree.sh
 cd .dev-worktree-8081
 docker compose -p mh-dashboard-organization-dev --env-file .env -f docker-compose.8081.yml up -d --build

docs/TEAM_GUIDE.md

@@ -32,6 +32,14 @@
 
 ## 2. 환경 원칙
 
+팀 규칙 문장:
+
+- `main`과 `dev`는 코드 브랜치다.
+- `8080`과 `8081`은 실행 환경이다.
+- 브랜치 이름을 포트와 같은 뜻으로 쓰지 않는다.
+- 기본 운영은 `main`을 `8080` 기준 브랜치로 본다.
+- 개발 검증은 `dev` 또는 작업 브랜치를 `8081`에서 먼저 확인한다.
+
 - `8080`
   - 공개 기준 환경
   - 기준 데이터가 있는 쪽
@@ -56,6 +64,11 @@
 5. 필요한 DB 동기화 범위를 결정한다.
 6. 수정 후 관련 시나리오를 검증한다.
 
+환경 준비:
+
+- 최초 실행 전 `.env.example`을 `.env`로 복사한다.
+- `./scripts/prepare_dev_worktree.sh`는 dev worktree에 `.env`가 없으면 `.env.example`로 기본 파일을 만든다.
+
 핵심 질문:
 
 - 지금 고치는 파일이 실제 source-of-truth가 맞는가?

docs/architecture/8081_SERVING_MAP.md

@@ -94,8 +94,8 @@
 
 - `260320.html`
 - `sample style.css`
-- `opayment.html`
+- `reference/opayment.html`
-- `omh.html`
+- `reference/omh.html`
 - `reference/ledger/MH 통합 대시보드_260320.html`
 - `reference/ledger/MH 통합 대시보드_260320.css`
 - 원본 xlsx/csv

incoming-files/README.md

@@ -29,6 +29,8 @@
 - 샘플 스타일 파일
 - 원본/백업 HTML
 - 디자인 비교용 파일
+- `reference/omh.html`
+- `reference/opayment.html`
 - `reference/ledger/MH 통합 대시보드_260320.html`
 - `reference/ledger/MH 통합 대시보드_260320.css`
 - `reference/ledger/사업관리대장-1.xlsx`

scripts/prepare_dev_worktree.sh

@@ -38,6 +38,10 @@ fi
 
 echo "[4/6] Copying local runtime env when available"
 copy_optional_path ".env"
+if [[ ! -f "${DEV_DIR}/.env" && -f "${DEV_DIR}/.env.example" ]]; then
+  cp "${DEV_DIR}/.env.example" "${DEV_DIR}/.env"
+  echo "Created ${DEV_DIR}/.env from .env.example"
+fi
 
 echo "[5/6] Copying local-only incoming design assets when available"
 copy_optional_path "incoming-files/1.png"