🎯 백엔드 개발자를 위한 요구사항 명세서 작성 가이드

백엔드 개발자가 단순히 코드를 작성하는 것을 넘어, 비즈니스의 성공에 기여하는 시스템을 만들기 위해 반드시 이해해야 할 핵심 개념들입니다.

요구사항 명세서의 비즈니스 규칙, 예외 상황 처리, 데이터 생명주기 정책에 대해 베스트 프랙티스와 ‘온라인 슈퍼마켓’ 프로젝트에 바로 적용할 수 있는 실무 예시를 중심으로 명확하게 설명합니다.

1. 비즈니스 규칙 (Business Rules)

개념 정의

비즈니스 규칙은 “특정 조건에서 시스템이 따라야 하는 명시적인 지침이나 제약사항”을 의미합니다.

‘무엇을’ 개발할지 정의하는 기능 요구사항과 달리, 비즈니스 규칙은 ‘어떻게’ 또는 ‘어떤 조건에서’ 기능이 동작해야 하는지를 구체적으로 정의합니다.

핵심 역할:

• 데이터의 무결성 보장
• 정책 강제 적용
• 비즈니스 의사결정 자동화

베스트 프랙티스

명확하고 원자적 작성

• 하나의 규칙에는 하나의 조건과 결과만 포함
• 복합 조건은 개별 규칙으로 분리

❌ 잘못된 예시:
"14세 이상이고, 마케팅 수신에 동의한 회원에게만 할인 쿠폰을 발급한다"

✅ 올바른 예시:
- [BR-001] 만 14세 이상만 회원가입 가능
- [BR-002] 마케팅 수신 동의 회원에게만 쿠폰 발급

고유 ID 부여

각 규칙에 BR-001, BR-002 와 같은 고유 식별자를 부여하여:

• 기획서에서 코드까지 추적 가능
• 팀 간 소통 시 명확한 참조
• 테스트 케이스와 연결

중앙 집중식 관리

• 설정 파일(configuration)
• 데이터베이스 테이블
• Rule Engine 도구 활용
• 코드 여러 곳에 분산 금지

비즈니스 언어 사용

❌ 개발자 관점:
"User 테이블의 age 컬럼 값이 14 미만이면 INSERT를 막는다"

✅ 비즈니스 관점:
"만 14세 미만 사용자는 회원으로 가입할 수 없다"

실무 예시: 온라인 슈퍼마켓 프로젝트

회원 관리 규칙

[BR-SIGNUP-001] 회원가입 연령 제한
- 조건: 사용자의 나이가 만 14세 미만
- 결과: 회원가입 절차를 중단하고 "만 14세 이상만 가입 가능합니다." 메시지 반환

주문 관리 규칙

[BR-ORDER-002] 최소 주문 금액
- 조건: 장바구니 총 상품 금액(할인 적용 전)이 15,000원 미만
- 결과: 주문 진행 불가, "최소 주문 금액은 15,000원입니다." 안내 표시

프로모션 규칙

[BR-PROMO-003] 신규가입 쿠폰 중복 방지
- 조건: 신규가입 웰컴 쿠폰 발급 요청
- 결과: 계정 생성 후 1회만 발급, 타 쿠폰과 중복 사용 불가

리뷰 관리 규칙

[BR-REVIEW-004] 리뷰 작성 자격
- 조건: 상품 리뷰 작성 요청
- 결과: 해당 상품을 '구매 확정' 상태인 회원만 작성 가능

2. 예외 상황 처리 방안 (Exception Handling)

개념 정의

예외 상황 처리는 소프트웨어가 정상적인 흐름을 벗어나는 예기치 못한 문제가 발생했을 때, 시스템이 중단되지 않고 상황을 적절하게 처리하고 복구하는 메커니즘입니다.

대표적인 예외 상황:

• 존재하지 않는 리소스 접근
• 네트워크 연결 장애
• 외부 서비스 응답 지연
• 데이터 검증 실패

베스트 프랙티스

구체적인 에러 코드 정의

❌ 일반적인 응답:
500 Internal Server Error

✅ 구체적인 응답:
{
  "errorCode": "ITEM_OUT_OF_STOCK",
  "message": "요청하신 상품의 재고가 부족합니다.",
  "timestamp": "2024-03-15T10:30:00Z"
}

사용자 친화적 메시지

• 시스템 내부 오류(NullPointerException 등) 노출 금지
• 사용자가 이해할 수 있는 명확한 안내
• 해결 방법 또는 대안 제시

상세한 로깅

사용자에게는 간단한 메시지, 서버 로그에는 상세 정보 기록:

• 사용자 식별 정보
• 요청 내용 (Request Body, Parameters)
• 발생 위치 (Stack Trace)
• 발생 시간 및 환경 정보

트랜잭션 안전성

• 부분적 실행 상태 방지
• 실패 시 모든 작업 롤백
• 데이터 일관성 유지

실무 예시: 온라인 슈퍼마켓 프로젝트

주문 프로세스 예외 처리

[EH-ORDER-001] 주문 시 재고 부족
상황: 결제 요청 순간 장바구니 상품이 품절된 경우

처리 방법:
- HTTP 상태: 409 Conflict
- 응답 형식:
{
  "errorCode": "ITEM_OUT_OF_STOCK",
  "message": "'[상품명]'의 재고가 부족하여 주문할 수 없습니다.",
  "data": {
    "productId": "PROD_12345",
    "requestedQuantity": 3,
    "availableQuantity": 0
  }
}
- 후속 조치: 결제 프로세스 즉시 중단, 장바구니 상태 업데이트

결제 시스템 예외 처리

[EH-PAYMENT-002] PG사 연동 실패
상황: Payment Gateway 서버 장애로 결제 승인 요청 실패

처리 방법:
- 주문 상태: '결제 실패'로 기록
- 사용자 메시지: "결제 서비스 장애로 주문에 실패했습니다. 잠시 후 다시 시도해주세요."
- 서버 로그: PG사 원본 에러 메시지 전체 기록
- 복구 전략: 자동 재시도 (최대 3회), 관리자 알림 발송

인증/인가 예외 처리

[EH-AUTH-003] 유효하지 않은 쿠폰 사용
상황: 이미 사용했거나 만료된 쿠폰 코드 적용 시도

처리 방법:
- HTTP 상태: 400 Bad Request
- 응답 형식:
{
  "errorCode": "INVALID_COUPON",
  "message": "사용할 수 없는 쿠폰입니다.",
  "details": {
    "couponCode": "WELCOME2024",
    "reason": "ALREADY_USED",
    "usedDate": "2024-03-10T14:20:00Z"
  }
}

3. 데이터 생명주기 정책 (Data Lifecycle Policy)

개념 정의

데이터 생명주기 정책은 데이터가 생성(Creation)되고, 사용(Usage)되며, 보관(Archive)되고, 최종적으로 파기(Destruction)되기까지의 전 과정을 관리하는 규정입니다.

정책 수립 이유:

• 법적 규제 준수 (개인정보보호법, GDPR 등)
• 스토리지 비용 최적화
• 데이터 보안 유지
• 비즈니스 연속성 보장

베스트 프랙티스

데이터 분류 체계

| 분류 | 설명 | 보관 기간 | 처리 방법 |
|——|——|———|———-|
| 개인 식별 정보 (PII) | 이름, 주소, 연락처 등 | 법정 기간 | 암호화 저장, 엄격한 접근 제어 |
| 거래 정보 | 주문, 결제, 배송 기록 | 5년 (전자상거래법) | 백업 보관, 감사 로그 |
| 서비스 로그 | 접속, 행동 패턴 분석 | 1년 | 통계 처리 후 익명화 |
| 마케팅 데이터 | 선호도, 쿠폰 사용 이력 | 동의 철회 시까지 | 동의 범위 내 활용 |

명확한 보관 기간

❌ 모호한 정책:
"오래된 데이터는 삭제한다"

✅ 명확한 정책:
"주문 데이터는 전자상거래법 제6조에 따라 5년간 보관 후 파기한다"

파기 방법 정의

• Soft Delete: 논리적 삭제 (복구 가능)
• Hard Delete: 물리적 삭제 (복구 불가능)
• 암호화 키 파기: 데이터 접근 불가능하게 만듦

휴면 정책 수립

정보통신망법상 ‘개인정보 유효기간제’ 준수:

• 1년 이상 미접속 시 휴면 전환
• 사전 통지 (30일 전)
• 별도 분리 보관

실무 예시: 온라인 슈퍼마켓 프로젝트

회원 데이터 관리

[DLP-USER-001] 휴면 회원 처리 정책

대상: 최종 로그인 후 1년 이상 접속 기록이 없는 회원

프로세스:
1. 사전 통지: 전환 30일 전 이메일 발송
2. 휴면 전환: 개인정보를 별도 분리된 DB 테이블로 이관
3. 데이터 처리: 
   - 이름, 주소, 연락처 → 암호화 후 분리 보관
   - 주문 이력 → 개인정보 제거 후 통계 목적으로 보관
4. 복구 절차: 본인인증 완료 시 휴면 해제 및 데이터 복원

회원 탈퇴 처리

[DLP-USER-002] 회원 탈퇴 시 데이터 처리

즉시 파기 대상:
- 개인 식별 정보 (이름, 주소, 연락처)
- 마케팅 관련 데이터 (선호도, 쿠폰 이력)

보관 대상 (5년간):
- 주문/결제 기록 (전자상거래법 준수)
- 분쟁 해결 관련 데이터

특별 처리:
- 이메일/ID: 재가입 방지를 위해 해시화하여 보관
- 리뷰 데이터: "탈퇴한 회원"으로 익명화 처리

비회원 데이터 관리

[DLP-CART-003] 비회원 장바구니 데이터

보관 기간: 마지막 활동 후 24시간

자동 삭제 조건:
- 세션 종료 시
- 24시간 비활성 상태
- 브라우저 쿠키 만료 시

데이터 처리:
- 개인정보 수집 최소화
- 암호화되지 않은 평문 저장 금지
- 정기적 배치 작업으로 만료 데이터 정리

적용 체크리스트

비즈니스 규칙 검증

• 각 규칙이 명확하고 원자적으로 정의되었는가?
• 고유 ID가 부여되어 추적 가능한가?
• 비즈니스 언어로 작성되어 이해하기 쉬운가?
• 중앙에서 관리 가능한 구조인가?

예외 처리 검증

• 구체적인 에러 코드가 정의되었는가?
• 사용자 친화적인 메시지를 제공하는가?
• 상세한 로그가 기록되는가?
• 트랜잭션 안전성이 보장되는가?

데이터 생명주기 검증

• 데이터가 민감도별로 분류되었는가?
• 법적 근거에 기반한 보관 기간이 명시되었는가?
• 파기 방법이 구체적으로 정의되었는가?
• 휴면 정책이 수립되었는가?

결론

성공적인 백엔드 시스템 구축을 위해서는 기능 구현뿐만 아니라 비즈니스 규칙, 예외 처리, 데이터 관리 정책을 체계적으로 설계해야 합니다.

이러한 요소들이 제대로 정의되고 구현되었을 때, 안정적이고 확장 가능하며 법적 요구사항을 만족하는 시스템을 만들 수 있습니다.