MH-DashBoard-organization/docs/NEXT_SESSION_CHECKPOINT.md

# Next Session Checkpoint

## Current Base

- branch: `total`
- latest checked commit: `24852d4`
- main history doc: [DEVELOPMENT_HISTORY.md](/home/hyunho/projects/mh-dashboard-organization/docs/DEVELOPMENT_HISTORY.md)
- work rulebook: [WORK_RULEBOOK.md](/home/hyunho/projects/mh-dashboard-organization/docs/WORK_RULEBOOK.md)
- execution flow: [WORK_EXECUTION_FLOW.md](/home/hyunho/projects/mh-dashboard-organization/docs/WORK_EXECUTION_FLOW.md)
- dev/prod protocol: [DEV_PROD_DB_PROTOCOL.md](/home/hyunho/projects/mh-dashboard-organization/docs/DEV_PROD_DB_PROTOCOL.md)
- regression checklist: [REGRESSION_CHECKLIST.md](/home/hyunho/projects/mh-dashboard-organization/docs/REGRESSION_CHECKLIST.md)
- today prep note: [TODAY_WORK_PREP_2026-03-30.md](/home/hyunho/projects/mh-dashboard-organization/docs/TODAY_WORK_PREP_2026-03-30.md)

## Mandatory Start Rule

매일 아침 또는 그날의 첫 작업을 시작할 때는 코드를 수정하기 전에 반드시 아래 순서를 먼저 수행해야 한다.

1. Gitea 브랜치 상태 확인
2. 열린 이슈 확인
3. [WORK_RULEBOOK.md](/home/hyunho/projects/mh-dashboard-organization/docs/WORK_RULEBOOK.md) 확인
4. 이 문서 확인
5. 현재 워크트리의 미푸시 커밋, 변경 파일, 미추적 파일 확인

주의:

- 위 절차를 확인하기 전에는 새 코드 작성이나 기존 코드 수정부터 시작하지 않는다.
- 커밋과 푸시는 자동으로 하지 않고, 사용자 지시가 있을 때만 수행한다.

## What Was Finished

### Dashboard Integration

- `조직 현황`, `프로젝트별 분석`, `팀/개인별 분석`, `자리배치도`를 하나의 허브에 통합
- `payment.html`, `mh.html`을 현재 프로젝트에 편입
- 공통 헤더, 탭, 로그인 정보, 공통 기간 제어 구성

### Integrated DB

- `organization.xlsx`, `MH.xlsx`, `payment.csv`, `ptj.csv` 기반 통합 DB 구성
- raw/staging/standard 성격의 구조를 PostgreSQL에 반영
- `members`, `seat_maps`, `seat_slots`, `seat_positions`
- `integration_raw_*`, `integration_work_logs`, `integration_work_log_segments`, `integration_vouchers`
- 프로젝트 카테고리 매핑 반영

### Team / Member Analysis

- `omh.html` 원본 기준으로 계산식/카테고리/디자인 복원
- DB raw MH 데이터를 원본 입력 구조처럼 다시 공급하는 방식으로 정리

### Project Analysis

- `opayment.html` 원본 기준으로 화면 복원
- `payment.csv` 분류 우선, `ptj.csv` fallback 적용
- 연장근무는 `연장근무 시간(가공)` 기준으로 반영

### Organization / Seat Map

- 조직도 상세 프로필에 `재석위치` preview 연결
- 관리자/비관리자 자리배치도 화면 분리
- 저장 후 조직도와 비관리자 열람에 반영되도록 seat save 흐름 정리
- seat persistence bug 수정
  - 원인: `seat_positions_map_cell_idx`가 slot 기반 도면에도 적용됨
  - 조치: `seat_slot_id IS NULL`인 grid map에만 적용되도록 수정

### Member Data Governance

- 이름 alias, 퇴사 제외, 조직 override를 DB 테이블 기반으로 전환
- 사용 테이블:
  - `member_aliases`
  - `member_retirements`
  - `member_overrides`

### Auth Baseline

- 실제 로그인 API 연결 완료
- 프런트 로그인 화면이 `/api/auth/login` 사용
- 세션/로그아웃/세션 조회 API 구성 완료
- 사용 테이블:
  - `auth.users`
  - `auth.sessions`
  - `auth.login_audit_logs`
- 현재 남은 범위:
  - mock login 정리
  - 역할별 권한 체크 적용
  - 쓰기 API 보호 범위 정리

### External Access

- WSL 내부 8080 리슨 확인
- 현재 다른 PC에서 접속 확인
- 현재 기준 주소:
  - `http://172.16.40.144:8080`

## Important Runtime Notes

### Dev / Prod Protocol

- 코드 선행은 `8081`, 공개 반영은 `8080`
- 데이터 정본은 `8080` DB
- `8081` DB는 독립 정본이 아니라 `8080` 기준 복제본처럼 관리해야 함
- `8081` 코드는 `.dev-worktree-8081` 기준으로 유지
- 조직도, 멤버, 자리배치 검증 전에는 `DEV_PROD_DB_PROTOCOL.md`를 먼저 확인
- 기능 수정 후 완료 판단은 `REGRESSION_CHECKLIST.md`를 기준으로 해야 함
- 빠른 재시작은 `./scripts/start_local_dashboards.sh`

### Seat Map Save

- 저장이 안 되면 먼저 backend 로그에서 `PUT /api/seat-maps/{id}/layout` 상태코드 확인
- 과거 핵심 장애는 DB 인덱스 충돌이었다
- 현재 저장 구조는:
  - `seat_positions`
  - `members.seat_label`
  둘 다 같이 갱신

### External Access

- Windows LAN IP가 바뀌면 접속 주소가 바뀔 수 있음
- WSL IP가 바뀌면 `portproxy connectaddress`를 다시 맞춰야 함
- 다음 확인 명령:
  - Windows: `ipconfig`
  - WSL: `hostname -I`
  - Windows: `netsh interface portproxy show all`

## Open Issues

- `#2` 백엔드 영속 저장 구조 운영 마무리
- `#3` 사무실 좌석 배치도 조회 및 관리자 편집 기능 고도화
- `#5` 실제 인증 체계 전환
- `#7` 자리배치도 팀별 색상 오버레이 표시
- `#8` 자리배치도 좌석 클릭 시 개인 상위 조직 트리 표시
- `#9` 조직도·자리배치도 변경 이력 버전 누적 저장

현재 해석:
- `#6`은 코드 기준 사실상 완료 상태이며 Gitea 정리 대상
- `#5`는 "로그인 구현"보다 "권한 제어 마무리"가 핵심
- `#2`의 기존 "스냅샷 검증" 범위는 현재 코드와 불일치하므로 범위 재정의 필요

## Unfinished Ideas Discussed Today

### Seat Map UX

- 자리배치도 내 인원 등록 시 팀별 색상 표시
- 좌석 클릭 시 본인까지의 상위 조직 트리 표시
- 나머지 사무실 2개 도면 추가
  - `한맥빌딩 7층`
  - `한맥빌딩 6층`
- 비관리자 열람 화면 품질 추가 점검

### History / Versioning

- 조직도와 자리배치도 수정 이력을 버전 누적형으로 저장
- 원본 DB와 별도의 history/version 구조 설계
- `valid_from`, `valid_to` 기반 시점 조회(as-of date) 구조 적용
- 날짜 또는 revision label 기준으로 버전 묶음 관리
- 상세 설계 문서:
  - [HISTORY_ASOF_DB_PLAN.md](/home/hyunho/projects/mh-dashboard-organization/docs/HISTORY_ASOF_DB_PLAN.md)

주의:
- 현재 코드에는 조직도/자리배치도 버전 이력 기능이 아직 없음
- 월간 스냅샷 방향은 범위에서 제외

### Project Analysis Accuracy

- 총합은 거의 맞았지만 일부 프로젝트 단위 소수점/분류 오차는 추가 정밀 보정 필요
- `opayment` 기준으로 특정 프로젝트 차이를 계속 줄여야 함

### Auth / Permission

- mock login을 개발용 fallback 수준으로 제한하거나 제거
- 역할별 접근 제어 정리
- 조직도/자리배치도/분석 화면 권한 경계 재정리

## Recommended Next Work Order

1. `#2` 범위를 현재 코드 기준으로 재정의하고 영속성 운영 검증 완료
2. `#5`에서 권한 체크, mock login 정리, 쓰기 API 보호 적용
3. `8081` DB를 `8080` 정본 기준으로 동기화하는 반복 가능한 절차 마련
4. `#9`를 as-of date 기반 history 구조로 설계 후 `members`, `seat_positions` 부터 이력화
5. 그 다음 `#8`, 나머지 도면 추가, `#7`, 프로젝트 분석 오차 보정 순으로 진행

## Quick Resume Prompt

다음 세션 시작 시 아래 기준으로 이어가면 된다.

- 브랜치 `total`에서 시작
- 최근 커밋 `1d15cf9` 확인
- `docs/DEVELOPMENT_HISTORY.md`
- `docs/NEXT_SESSION_CHECKPOINT.md`
- `docs/DEV_PROD_DB_PROTOCOL.md`
- `docs/REGRESSION_CHECKLIST.md`
- `docs/HISTORY_ASOF_DB_PLAN.md`
- Gitea 이슈 `#2`, `#5`, `#9`

그리고 먼저 현재 외부 접속, 자리배치 저장, 실제 로그인 동작을 확인한 뒤 다음 기능 개발로 넘어간다.