결제 플랫폼에 근태관리 모듈 추가하고 메뉴얼 자동 생성 도입

배경

이커머스 결제 플랫폼에 근태관리 SaaS 모듈을 끼워 넣는 작업 시작. 파트너들이 "정산도 여기서 보는데 직원 출퇴근까지 한 화면에서 보면 안 되냐"라고 계속 요청해서 결국 사이드 모듈로 붙이기로 결정함.

테이블 구조

근태 도메인은 본업이 아니라서 최소한으로 잘랐음. 일단 5개만 만듬.

파트너 단위로 격리되도록 모든 테이블에 파트너 식별자 칼럼을 박아 넣음. 결제 모듈이랑 같은 DB 쓰니까 행 수준 분리는 인증 가드에서 막기로 함.

인증 가드에서 막힌 부분

기존 인증 가드가 결제 권한 기준으로만 짜여 있어서, 근태 모듈 URL이 들어오면 무조건 401 뱉음. 모듈별 권한 매트릭스를 새로 끼워 넣어야 했음.

요청 URL → 모듈 식별 → 파트너 권한 룩업 → 통과/거부

처음에는 가드 두 개를 체인으로 걸었는데 우선순위 꼬여서 멀쩡한 결제 화면도 같이 막혔음. 결국 단일 가드에서 모듈 분기하는 식으로 통합. 권한 모델은 처음부터 한 줄로 흐르게 짜는 게 답이라는 걸 또 배움.

메뉴얼 자동 생성

사실 이번 커밋의 진짜 핵심. 새 모듈 만들 때마다 운영팀이 "사용법 좀"이라고 찾아오는데, 매번 워드 쓰는 게 너무 귀찮음. 그래서 메뉴얼을 자동으로 토해내는 라우트를 하나 만듬.

• 테이블 스키마 + 컬럼 코멘트 → 마크다운 표
• 라우트 + 파라미터 → API 섹션
• 시드 데이터 → 샘플 시나리오

운영팀이 URL만 치면 그 자리에서 메뉴얼을 받아갈 수 있음. 모듈을 처음부터 "메뉴얼 자동화 가능한 형태"로 짜야 한다는 걸 체감함. 컬럼 코멘트 비워두면 빈칸으로 그대로 출력되니 강제 정책이 필요해 보임.

삽질 메모

• 초기 데이터 시드 넣을 때 휴일 코드가 기존 결제용 코드랑 키 충돌. 네임스페이스 prefix 붙여서 회피.
• 가드 우선순위 디버깅에 두 시간 날림. 다음엔 등록 순서를 로그로 먼저 찍는다.
• 월 집계 테이블은 일단 NULL 허용으로 깔아뒀는데, 배치 붙이고 나면 NOT NULL로 조이는 게 맞을 듯.

회고

근태 모듈 자체는 작은데 권한·메뉴얼·시드 세 갈래로 영향 범위가 퍼져서 생각보다 오래 걸림. 사이드 모듈을 본 시스템에 끼울 때는 항상 권한 모델부터 다시 그려야 한다는 걸 매번 까먹고 매번 다시 배움. 메뉴얼 자동 생성기는 다른 모듈에도 다 적용할 만한 가치가 있어서 다음 모듈 작업 때 우선 붙여볼 생각.

다음