근태관리 설계 문서를 분리해 정산 흐름과 용어를 정돈한 과정

근태관리 SaaS 상세 설계 문서를 따로 뽑아낸 이유

처음엔 그냥 PLAN.md 한 장에 다 욱여넣으려고 했음. 근데 막상 출퇴근, 휴가, 시프트, 정산 흐름까지 그리다 보니 한 문서에서 스크롤이 끝도 없이 늘어나서 결국 PLAN_ATTENDANCE_DETAIL 로 분리함. 상위 PLAN 은 "무엇을 만든다"만 남기고, 디테일 문서는 "어떻게 동작하느냐"에 집중하게 나눴음.

문서 분리 자체가 별 게 아닌 것 같지만, 후속 작업자(=미래의 나)한테 컨텍스트 폭탄을 던지지 않으려면 꽤 중요한 작업임. 한 문서가 800줄 넘어가는 순간 검색으로만 읽게 되고, 결국 큰 그림을 잃음.

정리하면서 다시 잡힌 설계 포인트

도메인 언어가 흔들리고 있었음. "근태"인데 어떤 페이지는 "출퇴근", 어떤 곳은 "타임시트", 또 어떤 곳은 "스케줄"이라 부르고 있어서 정의를 강제로 못박음.

용어	정의	단위
근무 일정	사전에 배정된 시프트	일
근태 기록	실제 체크인/체크아웃 이벤트	분
근무 시간	기록을 일정에 맞춰 환산한 결과	분
정산	월/주 단위 합산 결과	시간

이 표를 문서 맨 앞에 박아두니까 그 뒤 챕터들이 자연스럽게 정렬됨. 같은 이벤트를 두 번 다른 이름으로 부르는 곳이 한참 있었다는 뜻이라, 표 만들면서 코드 네이밍도 같이 정리 대상으로 적어둠.

도메인 이벤트를 의사코드로 한 번에 그려봄

상태 전이를 글로만 적으면 사람마다 다르게 읽혀서, 디테일 문서엔 의사코드 블록을 넣었음.

on check_in(user, ts):
  shift = find_shift(user, ts.date)
  if not shift: create_unscheduled_attendance(user, ts)
  else:         open_attendance(user, shift, ts)

on check_out(user, ts):
  att = current_open_attendance(user)
  close_attendance(att, ts)
  enqueue_settlement(att)  # 비동기, 정산은 별도 워커

체크아웃 시점에 동기 정산을 돌리지 않고 큐로 넘기는 게 핵심. 출퇴근 트래픽은 출근시간 9시 부근에 몰리는데, 동기로 묶어두면 그 5분이 그대로 장애 시간이 됨. 이커머스 결제 플랫폼 짤 때 배웠던 패턴 그대로 가져옴.