MH-DashBoard-organization/docs/WORK_EXECUTION_FLOW.md

# Work Execution Flow

## 목적

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

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

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

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

- 작업 도중 기준이 바뀌지 않게 하기
- 임시 연결이 누적되지 않게 하기
- 나중에 봐도 왜 이렇게 했는지 알 수 있게 하기
- `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개가 있어야 한다.

1. 배경
2. 목표
3. 현재 상태
4. 남은 작업

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

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

## 3. 완료조건 먼저 적기

이 단계가 중요하다.

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

좋은 완료조건 예시:

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

나쁜 완료조건 예시:

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

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

즉:

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

## 4. 실행 계획 적기

계획은 길 필요 없다.

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

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

핵심은:

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

## 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 동기화
- 구조 정리나 서빙 경로 수정 직후에는 `./scripts/check_8081_smoke.sh` 로 핵심 런타임을 먼저 확인

## 6. 실제 실행

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

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

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

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

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

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

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

## 7. 가드레일 테스트

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

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

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

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

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

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

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

## 8. 기록 남기기

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

남겨야 하는 것:

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

남길 위치:

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

## 이 프로젝트용 한 줄 버전

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

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

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

작업 시작 전에 아래 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 유지`, `조직현황 탭`, `프로젝트/팀 탭`