hyunho/MH-DashBoard-organization

Fork 0

Files

hyunho fb5b0f00c2 feat: unify 8081 dashboard design system and views

2026-04-01 14:02:05 +09:00

7.9 KiB

Raw Blame History

Work Execution Flow

목적

이 문서는 앞으로 이 프로젝트에서 작업을 어떤 순서로 진행해야 하는지 아주 쉽게 고정하기 위한 문서다.

세미나에서 들은 흐름을 이 프로젝트 기준으로 다시 쓰면 아래 순서다.

SSOT 먼저 확인
이슈 생성 또는 연결
완료조건 먼저 적기
실행 계획 적기
필요한 동기화 먼저 하기
코드 수정 / 화면 작업 수행
가드레일 테스트
기록 남기기

이 순서를 지키는 이유는 하나다.

작업 도중 기준이 바뀌지 않게 하기
임시 연결이 누적되지 않게 하기
나중에 봐도 왜 이렇게 했는지 알 수 있게 하기
8081 작업이 8080을 망가뜨리지 않게 하기

1. SSOT 먼저 확인

SSOT는 Single Source Of Truth 의 줄임말이다.

쉬운 말로:

"무엇을 기준 진실로 볼 것인가"

이걸 먼저 정하지 않으면 작업 중간에 기준이 계속 바뀌어서 코드가 꼬인다.

이 프로젝트에서 자주 쓰는 SSOT:

공개용 코드 기준: /home/hyunho/projects/mh-dashboard-organization
작업용 코드 기준: /home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081
데이터 정본 기준: 8080 DB
기능 검증 기준: 8081
사업관리대장 디자인 기준: MH 통합 대시보드_260320.html
허브 공통 시각 언어 기준: sample style.css
런타임 디자인 토큰 기준: frontend/public/design-tokens.css
런타임 디자인 패턴 기준: frontend/public/design-patterns.css
현재 작업 지시 기준: 연결된 Gitea 이슈

작업 시작 전에 먼저 정해야 하는 질문:

이번 작업의 코드 기준은 어디인가?
이번 작업의 데이터 기준은 어디인가?
이번 화면의 디자인 기준 파일은 무엇인가?
지금 바꾸려는 화면이 실제로 어떤 파일에서 렌더링되는가?

이걸 모르고 코드를 건드리면 높은 확률로 엉뚱한 파일을 수정하게 된다.

디자인 작업 추가 규칙:

디자인 수정은 항상 design-tokens.css와 design-patterns.css를 먼저 확인한다.
색/패널/버튼/테이블/팝업이 공통 규칙으로 해결 가능한지 먼저 본다.
해결 가능하면 화면별 파일을 고치지 않고 토큰/패턴 파일에서 수정한다.
화면별 실제 서빙 파일은 마지막 단계에서만 조정한다.
원본/reference 파일은 비교용이지 직접 수정 우선 대상이 아니다.

2. 이슈 생성 또는 연결

작업은 이슈 없이 하지 않는다.

이유:

왜 하는 작업인지 남기기 위해
중간에 범위가 커지는 걸 막기 위해
다음 세션에서 바로 이어가기 위해

좋은 이슈는 아래 4개가 있어야 한다.

배경
목표
현재 상태
남은 작업

이슈는 길게 쓸 필요는 없다. 하지만 최소한 아래는 있어야 한다.

왜 이 작업을 하는지
어디까지가 이번 범위인지
무엇을 완료로 볼지

3. 완료조건 먼저 적기

이 단계가 중요하다.

완료조건이 없으면 "대충 된 것 같음" 상태에서 끝나기 쉽다.

좋은 완료조건 예시:

8081이 .dev-worktree-8081를 실제로 마운트한다
사업관리대장 탭이 원본 기준 레이아웃으로 열린다
8080은 영향 없이 유지된다
관련 회귀 검증을 통과한다

나쁜 완료조건 예시:

화면이 좀 괜찮아 보인다
아마 될 것 같다
코드 정리함

완료조건은 반드시 확인 가능한 문장이어야 한다.

즉:

"봤을 때 예쁨"이 아니라
"어떤 URL에서 어떤 동작이 확인됨"이어야 한다

4. 실행 계획 적기

계획은 길 필요 없다.

이 프로젝트에서는 보통 아래 정도면 충분하다.

기준 파일과 현재 연결 구조 확인
8081 worktree 기준으로만 수정
필요한 데이터 동기화
화면/기능 수정
회귀 검증
이슈 코멘트와 체크포인트 기록

핵심은:

수정 전에 먼저 구조를 파악하고
범위를 정하고
검증까지 포함해서 끝내는 것

5. 실행 전 동기화

이 프로젝트는 코드만 맞아도 안 되고, 데이터도 맞아야 한다.

그래서 실행 전에 동기화가 필요할 수 있다.

무슨 뜻이냐면:

8081에서 기능 확인을 하더라도
데이터가 8080과 다르면 검증 결과를 신뢰하면 안 된다

자주 쓰는 규칙:

조직도 / 멤버 / 자리배치 검증 전
- ./scripts/sync_prod_db_to_dev.sh minimal
분석 화면까지 공개용 기준으로 맞춰야 할 때
- ./scripts/sync_prod_db_to_dev.sh full

또 코드 동기화도 중요하다.

8081은 메인 workspace에서 직접 띄우지 않는다
먼저 ./scripts/prepare_dev_worktree.sh
그 다음 .dev-worktree-8081에서 실행

즉 이 프로젝트의 동기화는 두 종류다.

DB 동기화
코드/worktree 동기화

6. 실제 실행

이 단계가 코드를 고치는 단계다.

하지만 여기서도 규칙이 있다.

8081에서 먼저 작업
기준 파일이 아닌 곳은 건드리지 않기
임시 우회 연결을 만들었으면 반드시 기록 남기기
연결 구조가 난잡해지면 바로 이슈에 코드 정리 필요를 남기기

특히 이 프로젝트는 아래가 자주 꼬인다.

frontend/public
legacy/static
incoming-files
정적 HTML
iframe 연결
버전 쿼리스트링

그래서 실행 중 계속 확인해야 한다.

지금 내가 고친 파일이 실제 서빙 파일이 맞는가?
지금 수정이 8081 전용인가, 8080 공통인가?
이 연결은 임시인가, 기준 구조인가?

7. 가드레일 테스트

가드레일 테스트는 쉬운 말로:

"이 수정 때문에 같이 망가지면 안 되는 것들을 확인하는 테스트"

즉 핵심 기능만 보는 게 아니라, 같이 깨지기 쉬운 주변 기능까지 확인하는 것이다.

이 프로젝트에서 가드레일 테스트 예시:

8081 디자인 수정 후
- 8080은 그대로인지 확인
조직현황 수정 후
- 조직도 iframe, 모달, 리스트뷰, seat preview 확인
자리배치 수정 후
- 관리자 저장
- 비관리자 조회
- 조직도 상세 seat preview
분석 화면 수정 후
- 기간 필터
- 프로젝트/팀 전환
- 빈 데이터 상태
- 스타일 깨짐 여부

가드레일 테스트는 "다 테스트한다"가 아니다.

이번 수정 때문에 같이 깨질 가능성이 높은 것만 빠르게 확인하는 것이다.

8. 기록 남기기

작업은 기록까지 남겨야 끝난다.

남겨야 하는 것:

무엇을 바꿨는지
무엇을 기준으로 했는지
무엇을 검증했는지
무엇이 아직 안 끝났는지
다음에 어디서 이어야 하는지

남길 위치:

Gitea 이슈 코멘트
체크포인트 문서
필요하면 룰북/프로토콜 문서

이 프로젝트용 한 줄 버전

앞으로는 아래 순서로 생각하면 된다.

기준 진실부터 정한다
이슈에 작업 목적과 완료조건을 적는다
실행 전에 코드/DB 동기화를 맞춘다
8081에서만 수정한다
같이 깨지면 안 되는 것까지 확인한다
결과를 기록한다

시작할 때 바로 쓰는 짧은 템플릿

작업 시작 전에 아래 6줄만 적어도 된다.

SSOT:
- 코드 기준:
- 데이터 기준:
- 디자인 기준:
이슈:
완료조건:
계획:
필요한 동기화:
가드레일 테스트:

예시:

SSOT:
- 코드 기준: /home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081
- 데이터 기준: 8080 DB를 sync한 8081
- 디자인 기준: MH 통합 대시보드_260320.html
이슈: #16
완료조건: 8081에서 사업관리대장 메인이 원본 톤으로 열리고 8080은 안 바뀜
계획: 연결 확인 → worktree 수정 → 검증 → 이슈 기록
필요한 동기화: minimal
가드레일 테스트: 8080 유지, 조직현황 탭, 프로젝트/팀 탭

7.9 KiB Raw Blame History