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
• 로그인 기본 스타일은 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로 한다.
• 사업관리대장 실제 서비스 코드는 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

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

• #14 누적된 임시 로직 정리 및 중복 코드 제거
• #16 사업관리대장 메인 연동 및 기본 원본 DB화
• #17 8081 분리 worktree 기동 절차와 로컬 디자인 자산 복제 고정
• #18 8081 파일 책임 맵 정리 및 프런트 서빙 경로 정돈
• #19 8081 백엔드 라우터/서빙 책임 분리
• #20 8081 worktree 준비 스크립트·문서·운영 규칙 정리
• #21 reference 의존 제거 및 8081 실제 서비스 코드 독립화

Recommended Next Work Order

1. #21 이후 기준으로 실제 서비스 파일과 reference 파일 경계를 유지
2. 사업관리대장 세부 데이터 정합성 보정
3. 그 다음 화면별 앱 구조 승격 검토
4. 필요 시 #19, #20 잔여 정리 항목 재평가

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
• 작업 전 git status, dev 컨테이너 상태, /api/health, /legacy/organization, /integrations/payment, /integrations/ledger, /integrations/mh를 먼저 확인