본문으로 건너뛰기

설계/기술적 의사결정

설계 결정(기획/아키텍처)​

1. 회사 테이블 생성 방식(대표 가입 시 자동 생성)​

  • 배경: 회사 생성 시점을 어디에 둘지 결정이 필요했습니다.
  • 결정: CEO 회원가입(POST /api/users/ceo) 시 role=CEO로 유저를 생성하면서 회사도 함께 생성되도록 했습니다. (회사 생성 + CEO 계정 생성/연결을 트랜잭션으로 처리했습니다.)
  • 기대 효과: “대표 가입 = 회사 생성” 흐름이 고정되어 초기 온보딩이 단순해졌습니다.

2. 회원가입 플로우 정리(회사 선택 + 승인)​

  • 배경: 직원 가입 시 회사 중복과 가입 완료 기준(승인 여부)을 명확히 해야 했습니다.
  • 결정:
    1. 프론트에서 회사 목록을 조회하고 사용자가 회사를 선택합니다.
    2. 직원이 가입하면 users에 저장되지만 active=PENDING(승인대기)로 생성됩니다.
    3. CEO/인사 권한자가 승인하면 active=ACTIVE(재직중)로 전환되어 가입이 완료됩니다.
  • 기대 효과: 승인 전 단계가 분리되어 회사 단위 사용자 관리가 쉬워졌습니다.

3. 근무시간 정책 다양성 대응(Company Rule 테이블 도입)​

  • 배경: 회사별로 고정(9~18) / 유연근무 / 자율출퇴근 등 정책이 달라 단일 규칙으로 계산이 어려웠습니다.
  • 결정: company_rule 테이블을 별도로 두고 회사 정책을 구성요소로 관리했습니다.
    • 근무 유형(고정/유연)
    • 기준 출근/퇴근 시간
    • 유연근무 시 최소 근무시간
    • 지각/조퇴 허용분, 주말 근무 허용 여부 등
  • 기대 효과: 근태 계산 로직이 “회사 정책(규칙)”과 분리되어 확장 가능해졌습니다.

4. 야근/주말 등 추가근무 범위(스코프 결정)​

  • 배경: 기능 범위를 어디까지 잡을지(추가근무를 먼저 넣을지, 핵심 플로우 완성 후 확장할지) 결정이 필요했습니다.
  • 결정: 핵심 플로우(가입/승인/근태/휴가)를 먼저 완성한 뒤, 정책 필드(weekendWorkAllowed 등) 기반으로 확장하기로 했습니다.
  • 기대 효과: MVP 완성도를 먼저 확보하고 이후 확장 리스크를 낮췄습니다.

5. CEO/사원 DTO 분리​

  • 배경: CEO 가입은 회사 생성까지 포함하지만, 사원 가입은 “회사 선택 후 가입”이라 입력 구조가 달랐습니다.
  • 결정: CEO용 DTO와 사원용 DTO를 분리하여 요청 스키마를 명확히 했습니다.
  • 기대 효과: 컨트롤러/서비스 분기 처리가 줄고, Swagger에서 테스트도 직관적이었습니다.

6. 유저 정보 업데이트 시 null(부분 수정) 처리​

  • 배경: 일부 필드만 수정할 때 null을 “미수정”으로 볼지 “삭제”로 볼지 기준이 필요했습니다.
  • 결정: 부분 수정은 null=미수정 기준으로 정하고, 엔티티 도메인 메서드(updateProfile)에서 null 값은 반영하지 않도록 처리했습니다.
  • 기대 효과: 기존 값이 불필요하게 덮어쓰이지 않아 부분 수정 동작이 예측 가능해졌습니다.
  • 참고: 빈 문자열("")은 null이 아니므로, 클라이언트가 ""를 보내면 값이 ""로 갱신될 수 있습니다(정책/명세로 통일 필요).

기술적 의사결정​

1. 인증/인가를 JWT + Stateless로 결정​

  • 도입 이유
    1. REST API 기반이라 세션 상태를 서버에 두지 않고 인증을 처리하려고 했습니다.
    2. 배포/스케일 시 서버 간 세션 동기화 부담을 피하려고 했습니다.
  • 기대 효과
    1. 서버가 무상태(stateless)로 운영되어 확장/재배포가 단순해졌습니다.
    2. 요청 단위로 토큰을 검증하여 권한(Role) 제어가 명확해졌습니다.

2. 요청 단위 쿼리 카운팅/관측(성능 지표 헤더 제공)​

  • 도입 이유
    1. N+1 같은 성능 이슈를 “숫자”로 빠르게 발견/비교하려고 했습니다.
    2. 엔드포인트별 성능을 개발/리뷰 단계에서 객관적으로 확인하려고 했습니다.
  • 기대 효과
    1. 응답 헤더로 쿼리 수/시간이 노출되어 병목을 빠르게 추적할 수 있었습니다.
    2. 개선 전후(기준치 대비) 성능 변화를 쉽게 공유하고 검증할 수 있었습니다.

3. 에러 응답 표준화(전역 예외 처리)​

  • 도입 이유
    1. 예외마다 응답 형태가 달라지면 클라이언트 처리 비용이 커져서 통일이 필요했습니다.
    2. 운영 중 문제 분석을 위해 상태코드/메시지/경로 등을 일관되게 남기고자 했습니다.
  • 기대 효과
    1. 프론트엔드에서 에러 처리가 단순해져 사용자 경험이 안정적이었습니다.
    2. 로그/응답 포맷이 고정되어 디버깅과 장애 대응이 빨라졌습니다.

4. Swagger(OpenAPI) + BearerAuth 문서화​

  • 도입 이유
    1. API 명세와 테스트를 한 곳에서 관리하여 협업/검증을 빠르게 하려고 했습니다.
    2. JWT가 필요한 API도 Swagger에서 바로 호출 가능하도록 하려고 했습니다.
  • 기대 효과
    1. 프론트/QA에서 문서를 보고 즉시 호출·검증할 수 있어 커뮤니케이션이 원활했습니다.
    2. 변경된 API가 문서에 자동 반영되어 문서 유지보수 비용이 줄었습니다.