refactor: promote 8081 design system and served app structure

docs/NEXT_SESSION_CHECKPOINT.md

@@ -2,193 +2,152 @@
 
 ## 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)
+- `8080` 공개 기준 브랜치: `total`
+- `8081` 작업 기준 브랜치: `work-8081`
+- `8080` 공개 기준 커밋: `637b390`
+- `8081` worktree 경로: `/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081`
+- `8081` 실제 서빙 책임 맵: [architecture/8081_SERVING_MAP.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/architecture/8081_SERVING_MAP.md)
+- 메인 히스토리: [DEVELOPMENT_HISTORY.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/DEVELOPMENT_HISTORY.md)
+- 작업 룰북: [WORK_RULEBOOK.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/WORK_RULEBOOK.md)
+- 실행 플로우: [WORK_EXECUTION_FLOW.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/WORK_EXECUTION_FLOW.md)
+- dev/prod DB 프로토콜: [DEV_PROD_DB_PROTOCOL.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/DEV_PROD_DB_PROTOCOL.md)
+- 회귀 체크리스트: [REGRESSION_CHECKLIST.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/REGRESSION_CHECKLIST.md)
 
 ## Mandatory Start Rule
 
-매일 아침 또는 그날의 첫 작업을 시작할 때는 코드를 수정하기 전에 반드시 아래 순서를 먼저 수행해야 한다.
+당일 첫 작업 전에는 아래 순서를 먼저 확인한다.
 
-1. Gitea 브랜치 상태 확인
+1. 브랜치 기준 확인
 2. 열린 이슈 확인
-3. [WORK_RULEBOOK.md](/home/hyunho/projects/mh-dashboard-organization/docs/WORK_RULEBOOK.md) 확인
+3. [WORK_RULEBOOK.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/WORK_RULEBOOK.md) 확인
 4. 이 문서 확인
-5. 현재 워크트리의 미푸시 커밋, 변경 파일, 미추적 파일 확인
+5. `git status`, 변경 파일, 미추적 파일 확인
 
 주의:
 
-- 위 절차를 확인하기 전에는 새 코드 작성이나 기존 코드 수정부터 시작하지 않는다.
-- 커밋과 푸시는 자동으로 하지 않고, 사용자 지시가 있을 때만 수행한다.
+- `8080` 기준 코드는 직접 수정하지 않는다.
+- 새 작업은 항상 `.dev-worktree-8081`에서 진행한다.
+- 커밋과 푸시는 사용자 지시가 있을 때만 수행한다.
 
-## What Was Finished
+## Confirmed Runtime Rule
 
-### Dashboard Integration
+- `8080`은 루트 workspace의 `total` 기준으로 유지한다.
+- `8081`은 `.dev-worktree-8081` + `work-8081` 기준으로만 수정한다.
+- `main`, `hyunho`는 보류 브랜치이며 현재 작업에 사용하지 않는다.
+- `8081` 변경을 `8080`에 올릴 때는 reviewed file diff 기준으로만 반영한다.
+- `8081` DB는 운영 정본이 아니라 `8080` 기준 검증용 복제본처럼 다룬다.
 
-- `조직 현황`, `프로젝트별 분석`, `팀/개인별 분석`, `자리배치도`를 하나의 허브에 통합
-- `payment.html`, `mh.html`을 현재 프로젝트에 편입
-- 공통 헤더, 탭, 로그인 정보, 공통 기간 제어 구성
+## What Was Stabilized
 
-### Integrated DB
+### Branch / Worktree Safety
 
-- `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`
-- 프로젝트 카테고리 매핑 반영
+- 기존 `8081` 작업본은 [`.dev-worktree-8081-backup-2026-04-01`](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081-backup-2026-04-01)로 보존
+- 현재 [`.dev-worktree-8081`](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081)는 `work-8081` 기준으로 재생성
+- `8080` 루트 workspace는 그대로 두고 분리 운영
 
-### Team / Member Analysis
+### 8081 Design / Serving Baseline
 
-- `omh.html` 원본 기준으로 계산식/카테고리/디자인 복원
-- DB raw MH 데이터를 원본 입력 구조처럼 다시 공급하는 방식으로 정리
+- 디자인 SSOT 토큰:
+  - [frontend/public/design-tokens.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-tokens.css)
+- 디자인 SSOT 패턴:
+  - [frontend/public/design-patterns.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-patterns.css)
+- 디자인 기준 문서:
+  - [architecture/DESIGN_SSOT.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/architecture/DESIGN_SSOT.md)
+- 로그인 기본 스타일은 [frontend/public/styles.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/styles.css) 기준으로 유지
+- `8081` 허브 전용 디자인은 [frontend/public/styles-8081-design.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/styles-8081-design.css)에서만 덮어씀
+- 조직현황은 [legacy/static/common.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/legacy/static/common.css), [legacy/static/organization.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/legacy/static/organization.css), [legacy/static/organization.js](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/legacy/static/organization.js)를 사용
+- 프로젝트별 분석 디자인은 [incoming-files/served/payment.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/served/payment.html) 내부에서 `design-tokens.css` + `design-patterns.css`를 참조
+- 프로젝트별 분석 수정 원본은 [frontend/apps/payment/index.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/apps/payment/index.html) 이고, 반영은 [scripts/publish_payment_app.sh](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/scripts/publish_payment_app.sh)로 한다.
+- 팀/개인별 분석 수정 원본은 [frontend/apps/team/index.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/apps/team/index.html) 이고, 반영은 [scripts/publish_team_app.sh](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/scripts/publish_team_app.sh)로 한다.
+- 사업관리대장 실제 서비스 코드는 [incoming-files/served/ledger](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/served/ledger) 기준으로 본다.
+- 사업관리대장 앱 소스 기준은 [frontend/apps/ledger](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/apps/ledger) 이고, 반영은 [scripts/publish_ledger_app.sh](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/scripts/publish_ledger_app.sh)로 한다.
+- 사업관리대장 상세 팝업 디자인 수정 원본은 [frontend/apps/ledger/assets/ledger-override.js](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/apps/ledger/assets/ledger-override.js) 기준으로 본다.
 
-### 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)
+1. [frontend/public/design-tokens.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-tokens.css)
+2. [frontend/public/design-patterns.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-patterns.css)
+3. 화면별 실제 서빙 파일
 
 주의:
-- 현재 코드에는 조직도/자리배치도 버전 이력 기능이 아직 없음
-- 월간 스냅샷 방향은 범위에서 제외
 
-### Project Analysis Accuracy
+- `incoming-files/sample style.css`는 참고 기준이지만 직접 런타임 수정 파일이 아니다.
+- `incoming-files` 원본/reference 파일을 먼저 고치지 않는다.
+- 새 디자인 수정은 먼저 토큰/패턴 파일에서 해결 가능한지 확인한 뒤, 불가피할 때만 화면별 파일에 내린다.
 
-- 총합은 거의 맞았지만 일부 프로젝트 단위 소수점/분류 오차는 추가 정밀 보정 필요
-- `opayment` 기준으로 특정 프로젝트 차이를 계속 줄여야 함
+### 1차 구조 정리 진행분
 
-### Auth / Permission
+- 이슈 기준:
+  - `#14` 전체 구조 정리 umbrella
+  - `#18` 1차: 파일 책임 맵 정리 및 프런트 서빙 경로 정돈
+  - `#19` 2차: 백엔드 라우터/서빙 책임 분리
+  - `#20` 3차: worktree/스크립트/문서 정리
+- 책임 맵 문서 추가:
+  - [architecture/8081_SERVING_MAP.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/architecture/8081_SERVING_MAP.md)
+- `/integrations/payment`, `/integrations/mh`의 실제 서빙 파일을 분리:
+  - [incoming-files/served/payment.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/served/payment.html)
+  - [incoming-files/served/mh.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/served/mh.html)
+- 기존 [incoming-files/payment.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/payment.html), [incoming-files/mh.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/mh.html)은 비교/복구용 복사본으로 당분간 유지
+- backend 서빙 경로는 [backend/app/main.py](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/backend/app/main.py)에서 `incoming-files/served/*`를 보도록 정리 시작
 
-- mock login을 개발용 fallback 수준으로 제한하거나 제거
-- 역할별 접근 제어 정리
-- 조직도/자리배치도/분석 화면 권한 경계 재정리
+## Current Actual Serving Map
+
+- `/`:
+  - [frontend/public/index.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/index.html)
+- `/styles.css`:
+  - [frontend/public/styles.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/styles.css)
+- `/styles-8081-design.css`:
+  - [frontend/public/styles-8081-design.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/styles-8081-design.css)
+- `/legacy/organization`:
+  - [legacy/static/DashBoard-organization.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/legacy/static/DashBoard-organization.html)
+- `/integrations/payment`:
+  - [incoming-files/served/payment.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/served/payment.html)
+- `/integrations/ledger`:
+  - [incoming-files/served/ledger/index.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/served/ledger/index.html)
+- `/integrations/mh`:
+  - [incoming-files/served/mh.html](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/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. `#2` 범위를 현재 코드 기준으로 재정의하고 영속성 운영 검증 완료
-2. `#5`에서 권한 체크, mock login 정리, 쓰기 API 보호 적용
-3. `8081` DB를 `8080` 정본 기준으로 동기화하는 반복 가능한 절차 마련
-4. `#9`를 as-of date 기반 history 구조로 설계 후 `members`, `seat_positions` 부터 이력화
-5. 그 다음 `#8`, 나머지 도면 추가, `#7`, 프로젝트 분석 오차 보정 순으로 진행
+1. `#21` 이후 기준으로 실제 서비스 파일과 reference 파일 경계를 유지
+2. 사업관리대장 세부 데이터 정합성 보정
+3. 그 다음 화면별 앱 구조 승격 검토
+4. 필요 시 `#19`, `#20` 잔여 정리 항목 재평가
 
 ## 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`
-
-그리고 먼저 현재 외부 접속, 자리배치 저장, 실제 로그인 동작을 확인한 뒤 다음 기능 개발로 넘어간다.
+- `8080` 기준은 `total`
+- `8081` 작업은 `work-8081` + `.dev-worktree-8081`
+- 먼저 [WORK_RULEBOOK.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/WORK_RULEBOOK.md), [NEXT_SESSION_CHECKPOINT.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/NEXT_SESSION_CHECKPOINT.md), [architecture/8081_SERVING_MAP.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/architecture/8081_SERVING_MAP.md) 확인
+- 디자인 수정이면 [frontend/public/design-tokens.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-tokens.css), [frontend/public/design-patterns.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-patterns.css), [architecture/DESIGN_SSOT.md](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/docs/architecture/DESIGN_SSOT.md) 먼저 확인
+- 현재 구조 독립화 기준 이슈는 `#21`
+- 작업 전 `git status`, dev 컨테이너 상태, `/api/health`, `/legacy/organization`, `/integrations/payment`, `/integrations/ledger`, `/integrations/mh`를 먼저 확인