# Team Guide

이 문서는 이 저장소에서 작업할 때 가장 먼저 읽는 기준 문서다.

목표는 세 가지다.

- 어디를 수정해야 하는지 바로 알 수 있게 하기
- `8080`과 `8081`을 헷갈리지 않게 하기
- 작업 순서와 검증 기준을 하나의 문서로 시작하게 하기

## 1. 먼저 이해할 구조

- `frontend/apps/*`
  - 화면별 source-of-truth
- `incoming-files/served/*`
  - integration 화면의 실제 런타임 파일
- `legacy/static/*`
  - 조직현황 레거시 런타임 파일
- `incoming-files/reference/*`
  - 원본 참고 자산
- `backend/app/routes/*`
  - API 엔드포인트 등록
- `backend/app/services/*`
  - 비즈니스 로직
- `backend/app/repositories/*`
  - DB 읽기 쿼리

원칙:

- source를 먼저 수정하고 runtime은 publish로 반영한다.
- reference 파일은 비교/복구용이지 직접 수정 기준이 아니다.

## 2. 환경 원칙

- `8080`
  - 공개 기준 환경
  - 기준 데이터가 있는 쪽
- `8081`
  - 개발/검증 환경
  - 먼저 수정하고 검증하는 쪽

중요:

- 새 작업은 항상 `.dev-worktree-8081` 기준으로 시작한다.
- `8081`에서 검증되지 않은 변경을 바로 `8080`에 올리지 않는다.
- `8081` DB는 독립 정본이 아니라 검증용 복제본처럼 다룬다.

자세한 DB 운영 원칙은 [DEV_PROD_DB_PROTOCOL.md](DEV_PROD_DB_PROTOCOL.md)를 따른다.

## 3. 작업 시작 순서

1. 현재 브랜치와 변경 파일을 확인한다.
2. 연결된 이슈 또는 작업 목적을 확인한다.
3. 이번 작업의 source 파일과 runtime 파일을 구분한다.
4. 필요한 경우 `8081` 개발 환경을 띄운다.
5. 필요한 DB 동기화 범위를 결정한다.
6. 수정 후 관련 시나리오를 검증한다.

핵심 질문:

- 지금 고치는 파일이 실제 source-of-truth가 맞는가?
- 이 작업은 `8081`에서 먼저 검증해야 하는가?
- DB 차이 때문에 생긴 문제는 아닌가?

## 4. 수정 원칙

- 한 작업은 한 기능 또는 한 버그 단위로 작게 나눈다.
- 완료 기능은 관련 이슈 없이 함부로 건드리지 않는다.
- 임시 우회 로직은 이유와 제거 계획이 있어야 한다.
- 구조를 정리하더라도 기존 동작을 바꾸면 안 된다.

고위험 영역:

- `members`
- `seat_maps`
- `seat_slots`
- `seat_positions`
- `auth.*`
- 동기화 스크립트
- 스키마 변경

이 영역은 변경 이유, 영향 범위, 검증 결과를 반드시 남긴다.

## 5. 화면별 수정 기준

### 조직현황

- source: `frontend/apps/organization`
- runtime: `DashBoard-organization.html`, `legacy/static/*`
- publish: `./scripts/publish_organization_app.sh`

### 프로젝트별 분석

- source: `frontend/apps/payment/index.html`
- runtime: `incoming-files/served/payment.html`
- publish: `./scripts/publish_payment_app.sh`

### 팀/개인별 분석

- source: `frontend/apps/team/index.html`
- runtime: `incoming-files/served/mh.html`
- publish: `./scripts/publish_team_app.sh`

### 사업관리대장

- source: `frontend/apps/ledger/*`
- runtime: `incoming-files/served/ledger/*`
- publish: `./scripts/publish_ledger_app.sh`

### DB 상태

- source: `frontend/apps/db-status/index.html`
- runtime: `incoming-files/served/db-status/index.html`
- publish: `./scripts/publish_db_status_app.sh`

실제 서빙 책임은 [architecture/8081_SERVING_MAP.md](architecture/8081_SERVING_MAP.md)에서 확인한다.

## 6. 디자인 수정 원칙

- 먼저 `frontend/public/design-tokens.css`
- 다음 `frontend/public/design-patterns.css`
- 그 다음 [architecture/DESIGN_SSOT.md](architecture/DESIGN_SSOT.md)
- 마지막으로 화면별 파일

금지:

- reference 파일부터 수정하기
- 토큰/패턴으로 해결 가능한 것을 화면별 하드코딩으로 처리하기
- 예전 색 체계를 새 기본값으로 다시 넣기

## 7. 검증 원칙

- 완료 기준은 “코드를 썼다”가 아니라 “실제 동작을 검증했다”이다.
- 구조 정리나 라우트 분리 후에는 `./scripts/check_8081_smoke.sh`를 먼저 본다.
- 기능 수정 후에는 관련 화면만 보지 말고 주변 연동까지 확인한다.

검증 세부 항목은 [REGRESSION_CHECKLIST.md](REGRESSION_CHECKLIST.md)를 따른다.

자주 쓰는 DB 동기화:

- 조직현황/멤버/자리배치: `./scripts/sync_prod_db_to_dev.sh minimal`
- 분석 화면: `./scripts/sync_prod_db_to_dev.sh analysis`
- 전체 재검증: `./scripts/sync_prod_db_to_dev.sh full`

## 8. 커밋과 PR

- 커밋은 한 주제만 담는다.
- PR 본문에는 작업 목적, 변경 범위, 검증 방법, DB 영향 여부를 적는다.
- 공용 구조 파일을 수정했으면 영향 화면을 명시한다.

자세한 팀 작업 규칙은 [../CONTRIBUTING.md](../CONTRIBUTING.md)를 따른다.

## 9. 이 문서 다음에 읽을 것

- 협업 방식: [../CONTRIBUTING.md](../CONTRIBUTING.md)
- DB 운영 원칙: [DEV_PROD_DB_PROTOCOL.md](DEV_PROD_DB_PROTOCOL.md)
- 회귀 검증: [REGRESSION_CHECKLIST.md](REGRESSION_CHECKLIST.md)
- 실제 서빙 책임: [architecture/8081_SERVING_MAP.md](architecture/8081_SERVING_MAP.md)
- 디자인 기준: [architecture/DESIGN_SSOT.md](architecture/DESIGN_SSOT.md)