docs: record 2026-04-01 refactor and db work

docs/DEVELOPMENT_HISTORY.md

@@ -228,10 +228,354 @@
 
 - [HISTORY_ASOF_DB_PLAN.md](/home/hyunho/projects/mh-dashboard-organization/docs/HISTORY_ASOF_DB_PLAN.md)
 
+## 12. 2026-04-01 구조 안정화, DB 가시화, 자리배치도 정리
+
+### 왜 이 작업을 했는가
+
+이번 작업의 목적은 새 기능을 더 붙이기 전에, 지금까지 쌓인 구조를 먼저 안정적으로 정리하는 것이었다.
+겉으로 보기에는 화면이 어느 정도 동작하고 있었지만, 실제 내부는 다음과 같은 위험이 있었다.
+
+- 화면마다 구현 방식이 달라서 어디를 수정해야 하는지 바로 알기 어려움
+- 원본 참고 파일과 실제 서비스 파일이 섞여 있어, 작업할수록 다시 꼬일 가능성이 큼
+- DB는 이미 중요한 역할을 하고 있었지만, 비개발자 입장에서는 "정말 저장이 되고 있는가", "무엇이 들어 있는가"를 직접 확인하기 어려움
+- 구조를 건드릴 때 사업관리대장처럼 예상하지 못한 회귀가 생길 수 있었음
+
+즉, 이번 작업은 "새 기능 추가"보다 "앞으로 기능을 안전하게 추가할 수 있는 바닥공사"에 가까웠다.
+
+### 무엇을 바꿨는가
+
+이번에는 크게 다섯 가지 축으로 정리했다.
+
+1. 디자인과 화면 구조 기준 정리
+2. 실제 서비스 코드와 참고 원본 파일 분리
+3. 백엔드 라우트 구조 분리
+4. DB 상태를 눈으로 볼 수 있는 운영 화면 추가
+5. 자리배치도 실사용성 개선과 회귀 방지 장치 추가
+
+이 작업은 단순 정리처럼 보일 수 있지만, 실제로는 "어디가 진짜 기준인지"를 다시 세우는 과정이었다.
+
+추가로, 사용자가 실제로 가장 자주 보는 상단 탭 경험도 함께 다시 손봤다.
+이번에 정리한 상단 주요 화면은 다음과 같다.
+
+- 사업관리대장
+- 프로젝트별 분석
+- 팀/개인별 분석
+- 조직현황
+
+이 네 화면은 이전까지는 각각 따로 발전해 온 흔적이 강했다.
+즉, 같은 시스템 안에 있지만 화면마다 표정이 달랐고, 어떤 화면은 오래된 파란 톤이 남아 있었고, 어떤 화면은 새 스타일이 일부만 적용되어 있었다.
+이번에는 이 네 화면을 "각자 따로 만들어진 페이지"가 아니라 "하나의 대시보드 안에 있는 연결된 기능"처럼 보이도록 맞추는 작업도 함께 진행했다.
+
+### 리팩토링을 왜 했는가
+
+기존에는 하나의 파일이나 하나의 화면이 너무 많은 역할을 동시에 맡고 있었다.
+예를 들어 백엔드 메인 파일은 인증, 멤버, 통합 데이터, 정적 파일 서빙, 자리배치도까지 한곳에 몰려 있었고, 프런트도 화면에 따라 원본 파일을 직접 쓰는 곳과 override를 덧씌우는 곳이 섞여 있었다.
+
+이 구조는 처음엔 빠르게 화면을 올리는 데 도움이 되지만, 일정 시점이 지나면 문제가 생긴다.
+
+- 작은 수정이 예상치 못한 다른 화면에 영향을 줄 수 있음
+- 회귀 원인을 찾는 데 시간이 오래 걸림
+- 새 작업자가 들어오면 전체 구조를 이해하기 어려움
+- 특정 파일이 "원본인지", "실행본인지", "참고용 복사본인지" 헷갈리게 됨
+
+그래서 이번에는 "기능을 더 붙이기 전에 구조를 분리하는 것"을 우선했다.
+
+### 리팩토링을 어떻게 진행했는가
+
+#### 1. 실제 서비스 코드와 참고 원본을 분리
+
+사업관리대장, 프로젝트별 분석, 팀/개인별 분석은 처음엔 원본 파일, 참고 파일, 실제 서비스 파일이 섞여 있는 상태였다.
+이 상태에서는 수정할 때마다 "지금 내가 만지는 파일이 실제 서비스에 반영되는 파일이 맞는가"를 계속 확인해야 했다.
+
+그래서 다음 기준으로 재정리했다.
+
+- `reference`: 비교와 복구를 위한 참고 원본
+- `served`: 실제 서비스가 읽는 런타임 파일
+- `frontend/apps/*`: 앞으로 수정해야 하는 앱 소스
+
+특히 `ledger`, `payment`, `team` 화면은 모두 `app source -> publish -> served` 구조로 다시 맞췄다.
+이 의미는 다음과 같다.
+
+- 작업자는 원본 참고 파일을 직접 수정하지 않는다
+- 앱 소스에서 수정한다
+- publish 스크립트로 실제 서비스 파일을 만든다
+- 백엔드는 이 실제 서비스 파일만 서빙한다
+
+이렇게 하면 나중에 유지보수할 때 "수정 원본"과 "실행 결과물"이 명확히 나뉜다.
+
+#### 2. 디자인 기준을 공통 SSOT로 승격
+
+이전에는 각 화면에 과거 파란 톤, 임시 색상, override 스타일이 섞여 있었다.
+그래서 어떤 화면은 새 디자인 규칙을 따르는데, 어떤 화면은 예전 색이 다시 튀어나오는 문제가 반복됐다.
+
+이번에는 이를 막기 위해 다음 기준을 승격했다.
+
+- `design-tokens.css`
+- `design-patterns.css`
+- `DESIGN_SSOT.md`
+
+즉, 앞으로 디자인 수정은 "이 화면만 예쁘게"가 아니라 "공통 디자인 규칙 안에서 일관되게" 하는 방향으로 정리했다.
+비개발자 관점에서는 "화면마다 조금씩 다른 앱"처럼 보이던 것을, "하나의 시스템처럼 보이게" 만드는 작업이었다고 볼 수 있다.
+
+이 과정에서 실제로 한 작업은 다음과 같다.
+
+- 사업관리대장, 프로젝트별 분석, 팀/개인별 분석, 조직현황의 메인 폭을 같은 기준으로 맞춤
+- 공통 카드, 버튼, KPI, 표, 팝업의 색과 대비를 비슷한 문법으로 정리
+- 과거 파란 계열이 다시 드러나는 부분을 찾아 공통 토큰 기준으로 재정리
+- 각 화면에서 "지금 당장 보기 좋게" 끝내지 않고, 앞으로도 같은 규칙을 따라갈 수 있도록 공통 패턴으로 승격
+
+특히 프로젝트별 분석과 팀/개인별 분석은 원래 화면 내부에 이전 스타일 흔적이 많이 남아 있었는데, 이번에는 이 부분을 단순 덮어쓰기보다 "기준 디자인을 바라보게 만드는 방향"으로 손봤다.
+
+#### 2-1. 왜 네 개 탭을 먼저 다시 맞췄는가
+
+이번 세션에서는 단순 리팩토링만 한 것이 아니다.
+사용자가 실제로 매일 보는 네 개 주요 탭의 경험을 먼저 안정화하는 것이 중요했다.
+
+그 이유는 다음과 같다.
+
+- 화면마다 스타일이 다르면 사용자는 기능이 다른 것보다 "시스템이 불안정하다"는 인상을 먼저 받음
+- 새 기능을 추가할 때마다 이전 스타일이 다시 나타나면, 작업 결과가 누적되지 않고 계속 되돌아감
+- 세미나나 설명 자리에서도 "정리되고 있다"는 느낌을 전달하려면, 먼저 눈에 보이는 화면이 하나의 제품처럼 보여야 함
+
+그래서 이번에는 단순히 코드 구조를 정리하는 것과 함께, 네 개 탭의 인상과 문법을 맞추는 작업도 같이 진행했다.
+
+#### 2-2. 사업관리대장은 어디까지 손봤는가
+
+사업관리대장은 이번 세션에서 가장 많은 변화가 있었던 화면 중 하나다.
+
+- 상단 탭에서 직접 열리도록 연결
+- 기본 로우데이터 엑셀과 연동
+- 원본 화면 구조를 참고해 연도 버튼, KPI, 본문 표, 상세 팝업까지 단계적으로 복원
+- 클릭 시 프로젝트 상세 정보를 열 수 있게 연결
+- 메인 화면과 상세 팝업 디자인을 현재 디자인 큐에 맞게 정리
+
+다만 중요한 점은, 이번에 맞춘 것은 "보이는 구조와 기본 기능"까지라는 것이다.
+세부 숫자와 집계 기준, 어떤 값이 어떻게 계산되는지는 원본 작성자 기준 확인이 필요해 후속으로 남겨 두었다.
+
+즉, 이번에는 사업관리대장을 "쓸 수 있는 상태"까지 올렸고, 다음 단계에서 "정확한 상태"로 맞출 준비를 끝낸 것이다.
+
+#### 2-3. 프로젝트별 분석과 팀/개인별 분석은 무엇이 바뀌었는가
+
+두 화면은 모두 이미 기능은 있었지만, 디자인과 유지보수 구조가 흔들리는 상태였다.
+
+이번에 바뀐 점은 다음과 같다.
+
+- 프로젝트별 분석
+  - 메인 표, KPI, 필터, 패널, 상세 강조 색을 공통 디자인 기준으로 재정리
+  - 실제 서비스 파일과 수정 원본의 기준을 명확히 분리
+- 팀/개인별 분석
+  - 배경, 카드, 보조 정보, 캘린더 note, 상태 표현 등을 공통 디자인 기준으로 재정리
+  - 과거 스타일 흔적을 줄이고, 앞으로도 같은 방식으로 고칠 수 있는 구조로 이동
+
+즉, 두 화면 모두 "이번 한 번 예쁘게 고친" 것이 아니라 "앞으로도 같은 기준으로 유지될 수 있게" 손봤다는 점이 중요하다.
+
+#### 2-4. 조직현황은 무엇이 바뀌었는가
+
+조직현황은 기존에도 중요한 화면이었지만, 스타일과 인터랙션이 다소 오래된 느낌으로 남아 있었다.
+
+이번에는 다음을 정리했다.
+
+- 상세 프로필, 수정 모달, 버튼, 카드, 탭, 통계 영역의 색과 대비 조정
+- 관리자 모드 버튼, 추가 버튼, 상세 정보 패널의 톤 정리
+- 자리배치도와 연결되는 미리보기 카드, 조직 구조 표현 가독성 개선
+
+즉, 조직현황은 단순 디자인 수정이 아니라 "관리자가 실제로 쓰는 화면"으로서 읽기 편하게 정리하는 방향으로 손봤다.
+
+#### 3. 백엔드 메인 파일의 역할 분리
+
+백엔드도 한 파일에 너무 많은 기능이 몰려 있었다.
+그래서 메인 파일에서 기능별 라우트를 분리했다.
+
+이번에 분리한 범위는 다음과 같다.
+
+- 시스템/서빙 라우트
+- 인증 라우트
+- 멤버/히스토리 라우트
+- 통합 데이터 라우트
+- 자리배치도/업로드 라우트
+
+이 작업을 통해 얻은 가장 큰 장점은 "문제가 났을 때 어디를 봐야 하는지가 빨라졌다"는 점이다.
+예전에는 메인 파일을 전체 검색해야 했다면, الآن은 인증 문제면 인증 파일을, 자리배치도 문제면 자리배치도 라우트 파일을 먼저 보면 된다.
+
+### DB 작업을 왜 했는가
+
+이번 세션에서 DB 작업을 한 이유는 "DB가 이상해서"가 아니라, "DB가 이미 중요한 역할을 하고 있는데 너무 안 보였다"는 점 때문이다.
+
+실제로는 이미 많은 데이터가 DB에 저장되고 있었다.
+
+- 구성원 정보
+- 자리배치도 정보
+- 통합 원본 적재 정보
+- 인증 정보
+- 이력 관련 테이블
+
+하지만 비개발자 입장에서는 이것이 잘 보이지 않았다.
+즉, "DB가 있다"고만 듣고 실제로 어떤 테이블이 있고 무슨 역할인지 보지 못하면, 운영 기준을 잡기 어렵다.
+
+그래서 이번에는 DB를 "보이지 않는 저장소"에서 "운영자가 확인할 수 있는 대상"으로 바꾸는 작업을 했다.
+
+### DB 작업을 어떻게 했는가
+
+#### 1. DB 상태 탭 추가
+
+허브 안에 `DB 상태` 탭을 만들었다.
+이 화면에서는 다음을 확인할 수 있다.
+
+- 전체 테이블 수
+- 등록 인원/재직 인원
+- 자리배치도 도면 현황
+- 핵심 운영 테이블과 전체 테이블 목록
+- 테이블별 간단 설명
+- 테이블 클릭 시 컬럼과 샘플 데이터 미리보기
+- CSV 다운로드
+
+즉, 이제는 SQL을 직접 몰라도 "어떤 데이터가 어디에 저장되는지"를 눈으로 볼 수 있다.
+
+#### 2. 테이블 역할 분류
+
+전체 테이블을 그냥 나열만 하면 오히려 더 복잡해 보이기 때문에, 역할별로 다시 분류했다.
+
+- 유지
+- 주의
+- 원본/추적
+- 정리 후보
+
+이 분류를 통해 "지금 DB가 너무 큰가?"라는 질문에 대해, 단순 개수 대신 역할 기준으로 판단할 수 있게 만들었다.
+
+#### 3. 불필요한 테이블과 과거 실험 흔적 정리
+
+이번에 실제로 확인해보니, 현재 코드에서 쓰지 않는 테이블이 하나 있었고, 과거 DXF 시도본도 많이 쌓여 있었다.
+
+그래서 다음 정리를 진행했다.
+
+- 미사용 테이블 `entity_change_events` 삭제
+- 과거 DXF 시도본 정리
+- 최신 DXF 1개와 실제 운영용 고정 도면 3개만 유지
+
+이 작업은 "DB를 줄였다"기보다 "운영에 필요한 것과 과거 흔적을 분리했다"는 의미에 가깝다.
+
+#### 4. 8080과 8081의 역할도 다시 정리
+
+이번 세션에서는 개발용 `8081`에서 검증된 코드 중, 안정적으로 승격 가능한 부분만 `8080` 기준 코드로 올리는 작업도 진행했다.
+
+여기서 중요한 원칙은 "통째로 덮어쓰기"가 아니라 "검증된 것만 선별 승격"이었다.
+
+즉 다음 원칙을 지켰다.
+
+- `8081`은 계속 작업과 검증을 위한 공간으로 유지
+- `8080`은 공개 기준으로 유지
+- 디자인 SSOT, 앱 소스 구조, 런타임 서빙 구조처럼 안정성이 확인된 부분만 `total`로 승격
+- DB 자체는 함부로 합치지 않고, 코드와 구조만 먼저 정리
+
+이렇게 해야 운영 기준을 흔들지 않으면서도, 개선된 구조를 실제 기준 코드에 반영할 수 있다.
+
+### 무엇이 개선되었는가
+
+이번 작업으로 개선된 점은 매우 명확하다.
+
+#### 1. 유지보수 포인트가 분명해졌다
+
+예전에는 같은 기능을 수정해도 어디를 건드려야 하는지 여러 파일을 동시에 의심해야 했다.
+지금은 앱 소스, 서비스 파일, 참고 원본의 역할이 나뉘어서 수정 위치가 명확해졌다.
+
+#### 2. 화면 회귀를 더 빨리 잡을 수 있게 됐다
+
+사업관리대장 데이터가 한 번 끊겼을 때 원인은 DB 문제가 아니라, 한글 파일명을 응답 헤더에 그대로 넣으면서 생긴 인코딩 오류였다.
+이런 문제는 구조가 정리돼 있지 않으면 찾는 데 오래 걸린다.
+
+이번에는 원인을 빠르게 좁혀서 복구했고, 같은 문제가 다시 생기지 않도록 `8081` smoke check 스크립트도 추가했다.
+즉, 이제는 구조를 바꾼 뒤 바로 핵심 화면과 API를 빠르게 점검할 수 있다.
+
+#### 3. DB를 설명 가능한 상태로 만들었다
+
+이전에는 "DB가 있다"는 사실만 있었고, 실제로 어떤 상태인지 보기 어려웠다.
+이제는 운영자가 DB 상태를 화면으로 확인하고, 테이블을 눌러 실제 샘플 데이터를 볼 수 있다.
+세미나나 내부 설명 자리에서도 훨씬 설명하기 쉬운 상태가 됐다.
+
+#### 4. 자리배치도 기능이 실사용 방향으로 조금 더 진전됐다
+
+자리배치도에서는 다음이 개선됐다.
+
+- 클릭한 인원의 상위 조직 트리 표시
+- 검색 카드 동작 정리
+- 인원 카드 정보 구조 정리
+- 비관리자 모드 재렌더 안정화
+- 미배치/배치 상태 시각화 기준 정리 준비
+- 팀 구역 오버레이 기능 시도와 요구사항 정리
+
+즉, 단순히 "보이는 화면"이 아니라, 실제 조직과 사람을 읽기 쉬운 화면으로 한 걸음 더 나아갔다.
+
+#### 5. 회귀 방지 체계를 붙였다
+
+이번 세션에서 중요한 개선 중 하나는 "문제가 생긴 뒤 찾는 방식"에서 "문제가 생겼는지 바로 확인하는 방식"으로 한 걸음 이동한 점이다.
+
+이를 위해 `8081` smoke check 스크립트를 추가했다.
+이 스크립트는 다음을 한 번에 점검한다.
+
+- 서버 health
+- DB 상태 화면
+- 사업관리대장 기본 원본 API
+- 프로젝트별 분석
+- 팀/개인별 분석
+- 사업관리대장
+- 조직현황 연결
+
+즉, 구조를 고친 뒤 "겉으로는 멀쩡해 보이는데 실제로는 한 기능이 깨져 있는 상태"를 빨리 잡을 수 있게 된 것이다.
+
+### 오늘 확인된 문제와 한계
+
+이번 작업이 모든 것을 끝낸 것은 아니다.
+오히려 구조를 정리하면서, 앞으로 무엇을 더 손봐야 하는지도 더 분명해졌다.
+
+#### 1. 사업관리대장 세부 데이터 정합성은 아직 보류
+
+사업관리대장은 디자인과 기본 기능 연결은 올라왔지만, 세부 수치와 표출 규칙은 원본 작성자와 기준을 맞춰야 한다.
+즉, "대충 맞아 보이는 수준"이 아니라 "원본 의도와 동일한 수준"으로 맞추려면 담당자 확인이 필요하다.
+
+#### 2. 자리배치도 `#7`은 아직 재작업 필요
+
+팀 구역 오버레이 기능은 의도 자체는 맞게 해석했고 데이터도 들어가지만, 화면에서 반짝 나타났다가 사라지는 문제가 남아 있다.
+즉, 기능 방향은 맞지만 렌더링 타이밍이나 레이어 처리에서 다시 손봐야 한다.
+
+#### 3. 조직현황은 아직 앱 구조로 완전히 승격되지 않음
+
+`ledger`, `payment`, `team`은 앱 소스 구조로 정리했지만, 조직현황은 아직 레거시 구조를 유지하고 있다.
+장기적으로는 이것도 같은 기준으로 승격하는 것이 맞다.
+
+### 앞으로 남은 목표
+
+이번 작업 이후의 목표는 다음과 같다.
+
+#### 1. 사업관리대장 기준 정렬 후 정합성 보정
+
+원본 작성자와 함께 세부 데이터 표출 규칙, KPI 집계 방식, 상세 팝업 기준을 확인한 뒤 정확도를 맞춘다.
+
+#### 2. 자리배치도 `#7`, `#8` 완성
+
+- 팀 구역 오버레이를 안정적으로 보이게 수정
+- 배치/미배치 시각 규칙 정리
+- 검색과 클릭 시 정보 노출 방식 마무리
+
+#### 3. 백엔드 정리 후속
+
+라우트 분리는 많이 진행됐지만, 장기적으로는 도메인 로직까지 더 분리해서 유지보수성을 높일 필요가 있다.
+
+#### 4. DB 운영 문서와 상태 화면 고도화
+
+지금은 DB를 "볼 수 있게 만든" 단계다.
+앞으로는 화면별 데이터 흐름, 적재 이력, 원본 로우데이터 확인 기능까지 더 강화하면 운영 설명력이 더 올라간다.
+
+#### 5. 네 개 주요 탭의 공통 문법을 계속 지켜야 한다
+
+이번에 디자인과 구조를 다시 맞췄다고 해서 끝난 것은 아니다.
+앞으로 새 기능을 넣을 때도 각 화면이 제각각 다른 방식으로 다시 흩어지지 않게 유지해야 한다.
+
+즉, 이번 작업의 진짜 성과는 "한 번 예쁘게 고쳤다"가 아니라 "앞으로도 같은 방식으로 고칠 수 있는 기준을 세웠다"는 데 있다.
+
 ## Next Focus
 
-- `#2` 영속성 운영 검증과 문서 기준 정리
+- 사업관리대장 원본 담당자와 세부 데이터 규칙 정렬
+- 자리배치도 `#7`, `#8` 재작업 및 마무리
 - 권한 제어와 mock login 정리
 - `#9` as-of date 기반 history 구조 설계 및 점진적 도입
-- 자리배치도 조직 트리, 나머지 사무실 도면 등 실사용 기능 고도화
-- 프로젝트별 분석의 남은 소수점/분류 오차 정리
+- 조직현황의 장기적 앱 구조 승격 검토