MH-DashBoard-organization/docs/NEXT_SESSION_CHECKPOINT.md

Next Session Checkpoint

Current Base

• 8080 공개 기준 브랜치: total
• 8081 작업 기준 브랜치: work-8081
• 8080 공개 기준 커밋: 637b390
• 8081 worktree 경로: /home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081
• 8081 실제 서빙 책임 맵: architecture/8081_SERVING_MAP.md
• 메인 히스토리: DEVELOPMENT_HISTORY.md
• 작업 룰북: WORK_RULEBOOK.md
• 실행 플로우: WORK_EXECUTION_FLOW.md
• dev/prod DB 프로토콜: DEV_PROD_DB_PROTOCOL.md
• 회귀 체크리스트: REGRESSION_CHECKLIST.md

Mandatory Start Rule

당일 첫 작업 전에는 아래 순서를 먼저 확인한다.

1. 브랜치 기준 확인
2. 열린 이슈 확인
3. WORK_RULEBOOK.md 확인
4. 이 문서 확인
5. git status, 변경 파일, 미추적 파일 확인

주의:

• 8080 기준 코드는 직접 수정하지 않는다.
• 새 작업은 항상 .dev-worktree-8081에서 진행한다.
• 커밋과 푸시는 사용자 지시가 있을 때만 수행한다.

Confirmed Runtime Rule

• 8080은 루트 workspace의 total 기준으로 유지한다.
• 8081은 .dev-worktree-8081 + work-8081 기준으로만 수정한다.
• main, hyunho는 보류 브랜치이며 현재 작업에 사용하지 않는다.
• 8081 변경을 8080에 올릴 때는 reviewed file diff 기준으로만 반영한다.
• 8081 DB는 운영 정본이 아니라 8080 기준 검증용 복제본처럼 다룬다.

What Was Stabilized

Branch / Worktree Safety

• 기존 8081 작업본은 .dev-worktree-8081-backup-2026-04-01로 보존
• 현재 .dev-worktree-8081는 work-8081 기준으로 재생성
• 8080 루트 workspace는 그대로 두고 분리 운영

8081 Design / Serving Baseline

• 디자인 SSOT 토큰:
  • frontend/public/design-tokens.css
• 디자인 SSOT 패턴:
  • frontend/public/design-patterns.css
• 디자인 기준 문서:
  • architecture/DESIGN_SSOT.md
• DB 테이블 분류 기준 문서:
  • architecture/DB_TABLE_CATALOG.md
• 로그인 기본 스타일은 frontend/public/styles.css 기준으로 유지
• 8081 허브 전용 디자인은 frontend/public/styles-8081-design.css에서만 덮어씀
• 조직현황은 legacy/static/common.css, legacy/static/organization.css, legacy/static/organization.js를 사용
• 프로젝트별 분석 디자인은 incoming-files/served/payment.html 내부에서 design-tokens.css + design-patterns.css를 참조
• 프로젝트별 분석 수정 원본은 frontend/apps/payment/index.html 이고, 반영은 scripts/publish_payment_app.sh로 한다.
• 팀/개인별 분석 수정 원본은 frontend/apps/team/index.html 이고, 반영은 scripts/publish_team_app.sh로 한다.
• DB 상태 화면 수정 원본은 frontend/apps/db-status/index.html 이고, 반영은 scripts/publish_db_status_app.sh로 한다.
• 사업관리대장 실제 서비스 코드는 incoming-files/served/ledger 기준으로 본다.
• 사업관리대장 앱 소스 기준은 frontend/apps/ledger 이고, 반영은 scripts/publish_ledger_app.sh로 한다.
• 사업관리대장 상세 팝업 디자인 수정 원본은 frontend/apps/ledger/assets/ledger-override.js 기준으로 본다.

디자인 수정 우선순위:

1. frontend/public/design-tokens.css
2. frontend/public/design-patterns.css
3. 화면별 실제 서빙 파일

주의:

• incoming-files/sample style.css는 참고 기준이지만 직접 런타임 수정 파일이 아니다.
• incoming-files 원본/reference 파일을 먼저 고치지 않는다.
• 새 디자인 수정은 먼저 토큰/패턴 파일에서 해결 가능한지 확인한 뒤, 불가피할 때만 화면별 파일에 내린다.

1차 구조 정리 진행분

• 이슈 기준:
  • #14 전체 구조 정리 umbrella
  • #18 1차: 파일 책임 맵 정리 및 프런트 서빙 경로 정돈
  • #19 2차: 백엔드 라우터/서빙 책임 분리
  • #20 3차: worktree/스크립트/문서 정리
• 책임 맵 문서 추가:
  • architecture/8081_SERVING_MAP.md
• /integrations/payment, /integrations/mh의 실제 서빙 파일을 분리:
  • incoming-files/served/payment.html
  • incoming-files/served/mh.html
• 기존 incoming-files/payment.html, incoming-files/mh.html은 비교/복구용 복사본으로 당분간 유지
• backend 서빙 경로는 backend/app/main.py에서 incoming-files/served/*를 보도록 정리 시작

Current Actual Serving Map

• /:
  • frontend/public/index.html
• /styles.css:
  • frontend/public/styles.css
• /styles-8081-design.css:
  • frontend/public/styles-8081-design.css
• /legacy/organization:
  • legacy/static/DashBoard-organization.html
• /integrations/payment:
  • incoming-files/served/payment.html
• /integrations/ledger:
  • incoming-files/served/ledger/index.html
• /integrations/mh:
  • incoming-files/served/mh.html
• /db-status.html:
  • incoming-files/served/db-status/index.html

Cross Checks Last Confirmed

• 8080: curl http://localhost:8080/api/health 정상
• 8081 dev 컨테이너: proxy/backend/frontend/db healthy
• 8081 backend 내부 확인:
  • /api/health 200
  • /legacy/organization 200
  • /integrations/payment 200
  • /integrations/ledger 200
  • /integrations/mh 200
• incoming-files/served 내 실제 서빙 파일 존재 확인

주의:

• Codex 터미널 세션에서는 curl http://localhost:8081가 간헐적으로 실패할 수 있다.
• 이 경우 브라우저 확인 또는 컨테이너 내부 라우트 확인을 기준으로 판단한다.

Open Issues Relevant Now

• #2 백엔드 영속 저장 구조 운영 마무리
• #7 자리배치도 팀별 구역 색상 오버레이
• #8 자리배치도 좌석 클릭 시 개인 상위 조직 트리 표시
• #14 누적된 임시 로직 정리 및 중복 코드 제거
• #16 사업관리대장 메인 후속 정리 및 기준 분석
• #19 8081 백엔드 라우터/서빙 deeper 모듈 분리
• #21 organization 레거시 구조 승격 및 장기 고도화

Current Seatmap Work Note

• #8:
  • 자리배치도 우측 패널에 선택 인원 상위 조직 트리 표시 로직을 추가했다.
  • 좌석 클릭 / 구성원 카드 클릭 / fixed viewer 선택 이벤트가 부모 화면으로 올라오도록 연결했다.
  • 검색 카드 클릭은 상단 패널을 띄우지 않고 좌석 포커스만 하도록 분리했다.
• #7:
  • 해석 기준은 개별 좌석 색칠이 아니라 팀이 모여 있는 좌석 군집을 하나의 구역처럼 보여주는 오버레이다.
  • grid 배치도와 fixed/DXF viewer 양쪽에 팀 구역 오버레이 코드를 넣었다.
  • 현재 증상은 처음 반짝 보였다가 사라지는 현상이며, 데이터 부재가 아니라 viewer draw/layer 타이밍 문제로 보인다.
  • 다음 작업 시작 시 #7을 먼저 재확인한다.
• 자리배치도 카드 텍스트 규칙:
  • 이름 - 직급 - 팀(또는 다음 조직 fallback) 순서
  • 검색 목록 카드에는 chair-00 같은 좌석 배지를 노출하지 않음
  • 미배치 인원 카드는 외곽선만 사용하고 내부 채움색은 사용하지 않음
• 사업관리대장 기본 원본 API 오류:
  • 원인은 DB가 아니라 X-Original-Filename 한글 헤더 인코딩 오류였음
  • backend/app/ledger_runtime.py 에서 URL-encoded 헤더로 수정
  • ./scripts/check_8081_smoke.sh 에 ledger-default-api 체크를 넣음

Recommended Next Work Order

1. #2 기준으로 DB 상태 화면과 저장 구조 검증 흐름 고도화
2. #21 이후 기준으로 실제 서비스 파일과 reference 파일 경계를 유지
3. 사업관리대장 세부 데이터 정합성 보정은 원본 규칙 분석 후 진행
4. 필요 시 #19 잔여 정리 항목 재평가

Quick Resume Prompt

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

• 8080 기준은 total
• 8081 작업은 work-8081 + .dev-worktree-8081
• 먼저 WORK_RULEBOOK.md, NEXT_SESSION_CHECKPOINT.md, architecture/8081_SERVING_MAP.md 확인
• 디자인 수정이면 frontend/public/design-tokens.css, frontend/public/design-patterns.css, architecture/DESIGN_SSOT.md 먼저 확인
• 현재 구조 독립화 기준 이슈는 #21
• #2 기준 DB 상태 확인은 /api/admin/db-status 또는 허브의 DB 상태 탭(/db-status.html)을 먼저 본다.
• DB 테이블 유지/주의/원본·추적/정리 후보 분류는 architecture/DB_TABLE_CATALOG.md 기준으로 본다.
• 작업 전 git status, dev 컨테이너 상태, /api/health, /legacy/organization, /integrations/payment, /integrations/ledger, /integrations/mh, /api/admin/db-status를 먼저 확인
• 구조 정리나 라우트 변경 직후에는 ./scripts/check_8081_smoke.sh 를 먼저 실행해 ledger-default-api 까지 확인