# 회귀 검증 체크리스트

## 목적

- 새 기능을 추가하거나 기존 기능을 수정할 때, 이전에 되던 핵심 기능이 깨졌는지 빠르게 확인한다.
- `8081` 작업용에서 검증한 결과를 신뢰할 수 있도록 `환경`, `데이터`, `핵심 시나리오`를 고정한다.
- 완료 판단을 감이 아니라 반복 가능한 체크 절차로 바꾼다.

## 적용 원칙

- 코드 수정은 먼저 `8081`에서 수행한다.
- 데이터 기준은 항상 `8080` 공개용 DB를 따른다.
- 검증 전에는 작업 범위에 맞는 DB 동기화를 먼저 수행한다.
- 기능 수정 후에는 관련 화면만 보지 말고, 이 문서의 핵심 시나리오를 함께 확인한다.

관련 문서:

- [DEV_PROD_DB_PROTOCOL.md](/home/hyunho/projects/mh-dashboard-organization/docs/DEV_PROD_DB_PROTOCOL.md)
- [INFRA_VALIDATION_CHECKLIST.md](/home/hyunho/projects/mh-dashboard-organization/docs/INFRA_VALIDATION_CHECKLIST.md)

## 작업 시작 전

### 1. 서버 상태 확인

- `8081` 작업용 접속 확인
- `8080` 공개용 접속 확인
- `docker compose ps`에서 `backend`, `frontend`, `proxy`, `db`가 정상인지 확인
- `8081`은 기본적으로 `./scripts/prepare_dev_worktree.sh` 후 `/tmp/mh-dashboard-organization-dev-worktree` 에서 `docker compose -p mh-dashboard-organization-dev --env-file .env -f docker-compose.8081.yml up -d --build` 로 기동
- `8081` 기동 후 `docker inspect mh-dashboard-organization-dev-backend-1`에서 마운트 경로가 `/tmp/mh-dashboard-organization-dev-worktree/...`인지 확인

### 2. 데이터 동기화 범위 결정

- 조직도, 관리자모드, 자리배치도 작업 전:
  - `./scripts/sync_prod_db_to_dev.sh minimal`
- 프로젝트별 분석, 팀/개인별 분석 작업 전:
  - `./scripts/sync_prod_db_to_dev.sh analysis`
- 공개용 기준 전체 데이터 재검증이 필요한 경우만:
  - `./scripts/sync_prod_db_to_dev.sh full`

### 3. 기준 고정

- 어느 서버에서 재현했는지 기록
- 어떤 데이터 동기화 범위로 검증했는지 기록
- 브라우저 캐시 영향을 피하려면 강력 새로고침 후 확인

## 공통 회귀 시나리오

기능 수정 후 아래 항목을 최소한 확인한다.

### A. 허브 및 공통 진입

- 메인 허브가 정상 렌더링된다.
- 상단 탭 이동이 정상 동작한다.
- 로그인 상태가 비정상적으로 풀리지 않는다.

### B. 조직현황

- 조직도 트리가 정상 표시된다.
- 관리자모드 진입이 가능하다.
- 대상인원 클릭 시 기본정보 모달이 열린다.
- `+` 신규 구성원 추가 모달이 열린다.
- 기본정보 저장이 정상 동작한다.

### C. 자리배치도

- `기술개발센터`, `한맥빌딩 6층`, `한맥빌딩 7층` 도면이 모두 열린다.
- 미배치 인원 목록이 정상 표시된다.
- 미배치 인원을 chair에 드래그앤드롭할 수 있다.
- 드롭 후:
  - 미배치 목록에서 사라진다.
  - chair에 배치 상태가 표시된다.
  - 이름/직급 표기가 보인다.
- 배치된 좌석 클릭 후 해제 또는 수정 흐름이 정상 동작한다.

### D. 조직도와 자리배치 연동

- 조직도에서 인원 클릭 시 상세 정보가 열린다.
- 재석위치 미리보기가 표시된다.
- 좌석이 배정된 인원은 해당 자리로 줌인된다.

### E. 프로젝트별 분석

- 월 선택이 정상 동작한다.
- 프로젝트 목록과 합계가 비어 있지 않다.
- `1월`, `2월` 데이터가 현재 기준값과 일치한다.

현재 기준 검증값:

- `2026-01`
  - 시간 `37,342.39`
  - 인건비 `1,391,966,625`
- `2026-02`
  - 시간 `29,060.59`
  - 인건비 `1,078,337,651`

### F. 팀/개인별 분석

- `전체`, `GPD`, `TDC` 버튼이 순서대로 보인다.
- `전체`에서 모든 팀이 노출된다.
- `GPD`, `TDC` 선택 시 각 소속 범위만 버튼 기준으로 보인다.
- 검색은 버튼 상태와 무관하게 전체 데이터를 검색한다.

## 작업 유형별 필수 추가 확인

### 조직도 / 관리자모드 수정 시

- 대상인원 수정 모달 레이아웃이 깨지지 않는지 확인
- 신규 구성원 추가 모달도 같은 레이아웃으로 보이는지 확인
- 저장 후 목록 반영이 정상인지 확인

### 자리배치도 수정 시

- viewer iframe 로드 여부 확인
- 드래그앤드롭 이후 배치 상태가 즉시 반영되는지 확인
- 조직도 상세 재석위치 preview까지 같이 확인

### 분석 로직 수정 시

- 작업 전에 반드시 `analysis` 또는 `full` 동기화 수행
- 월별 합계 검증값 재확인
- 원본 기준과 차이가 있으면 반올림, 제외 인원, 가공시간 규칙부터 점검

## 완료 처리 기준

수정 사항을 완료로 판단하려면 아래를 모두 만족해야 한다.

- 수정한 기능이 의도대로 동작한다.
- 관련 공통 회귀 시나리오가 깨지지 않는다.
- 필요한 경우 `8081`에서 검증 결과를 숫자 또는 화면 기준으로 기록한다.
- 이후에만 `8080` 공개용 반영 여부를 판단한다.

## 장애 원인 분류 기준

문제가 생기면 먼저 아래 셋 중 어디인지 분리한다.

- 코드 차이
  - `8080`, `8081`의 정적 파일 또는 백엔드 로직이 다름
- DB 차이
  - `members`, `seat_maps`, `integration_*` 등 기준 데이터가 다름
- 캐시 또는 런타임 상태
  - 정적 파일 캐시, 컨테이너 재시작 미반영, 브라우저 세션 상태 문제

이 분류를 먼저 해야 원인을 잘못 짚지 않는다.

## 권장 기록 방식

작업 종료 시 아래 형식으로 남긴다.

```text
작업 범위:
- 예: 조직현황 관리자모드 기본정보 모달 레이아웃 변경

검증 환경:
- 서버: 8081
- DB 동기화: minimal / analysis / full 중 무엇을 사용했는지

검증 결과:
- 조직도: 정상
- 관리자모드 모달: 정상
- 자리배치도 연동: 정상 또는 미검증
- 프로젝트별 분석: 정상 또는 미검증
```