문제
풀이

💡 Idea

완전 탐색을 하는 쉬운 문제이다. 그런데 애먹은 부분이 있다면, 점수 계산을 끝낸 뒤에, 가장 높은 점수인 학생들을 모으는 과정이었다. 이 부분이 이 문제의 핵심 부분이 아닌데, 아래와 같이 코드가 길어지는 게 싫었다.

ArrayList<Integer> winners_list = new ArrayList<>();

int max_score = 0;

for(int i = 0; i < 3; i++){
	max_score = Math.max(scores[i], max_score);
}

for(int i = 0; i < 3; i++){
	if(scores[i] == max_score) winners_list.add(i+1);
}

int[] winners_array = new int[winners_list.size()];

for(int i = 0; i < winners_list.size(); i++){
	winners_array[i] = winners_list.get(i);
}

return winners_array;

그래서 문제를 푼 이후에 stream을 이용하여 코드를 줄여보았다. 아직 stream으로 생각하는 방식이 익숙하지 않아 바로 떠올리기가 쉽지 않았다.

int max_score = Arrays.stream(scores).max().orElse(0);
		
int[] winners = IntStream.range(0,3).filter(i -> scores[i] == max_score).map(i -> i+1).toArray();

return winners;

🔑 Code

import java.util.*;
import java.util.stream.IntStream;

class Solution {
    private static final int[][] rules = {
        {1, 2, 3, 4, 5},
        {2, 1, 2, 3, 2, 4, 2, 5},
        {3, 3, 1, 1, 2, 2, 4, 4, 5, 5}
    };
    
    public int[] solution(int[] answers) {
        int scores[] = {0,0,0};
        for(int i = 0; i < answers.length; i++){
            for(int j = 0; j < 3; j++){
                if(rules[j][i % rules[j].length] == answers[i]) scores[j]++;
            }
        }

        int max_score = Arrays.stream(scores).max().orElse(0);
                
        int[] winners = IntStream.range(0,3).filter(i -> scores[i] == max_score).map(i -> i+1).toArray();
        
        return winners;
    }
}

🗨️ Side Notes

람다식 내부에서 지역 변수를 사용하려면 그 변수는 final이거나 effectively final이어야 한다.

현재 코드는 가능하다.

int maxScore = Arrays.stream(scores)
        .max()
        .orElse(0);

return IntStream.range(0, scores.length)
        .filter(i -> scores[i] == maxScore)
        .toArray();

maxScore를 선언한 이후 다시 바꾸지 않았기 때문이다.

이런 변수를 effectively final이라고 한다.

다음 코드는 컴파일되지 않는다.

int maxScore = 0;

for (int score : scores) {
    maxScore = Math.max(maxScore, score);
}

return IntStream.range(0, scores.length)
        .filter(i -> scores[i] == maxScore)
        .toArray();

왜냐하면 maxScore가 반복문에서 계속 변경되기 때문이다.

컴파일러는 대략 다음과 같은 오류를 낸다.

Local variable maxScore defined in an enclosing scope
must be final or effectively final

이 경우 중간 변수를 하나 더 만들 수 있다.

int max = 0;

for (int score : scores) {
    max = Math.max(max, score);
}

int maxScore = max;

return IntStream.range(0, scores.length)
        .filter(i -> scores[i] == maxScore)
        .map(i -> i + 1)
        .toArray();

maxScore는 선언 후 변경되지 않으므로 람다에서 사용할 수 있다.

하지만 이 문제에서는 Stream으로 최댓값까지 구하면 더 간단하다.

int maxScore = Arrays.stream(scores)
        .max()
        .orElse(0);

문제
풀이

📝 Problem Summary

문제를 한두 문장으로 요약합니다.

💡 Idea

명함을 순회하며, 가장 작은 넓이가 되는 가로 세로 길이를 갱신해 가는 완전 탐색 문제이다.

처음에는 직관적으로 코드를 작성했다. 새로운 명함을 추가할 때 확장된 넓이가 작은 방향으로 추가를 해 갔다.

• 첫 번째 방식

  class Solution {
    public int solution(int[][] sizes) {
        int w = 0, h = 0;   
          
        for(int[] size : sizes){
            int w1 = Math.max(w, size[0]);
            int h1 = Math.max(h, size[1]);
            int area1 = w1 * h1;
              
            int w2 = Math.max(w, size[1]);
            int h2 = Math.max(h, size[0]);
            int area2 = w2 * h2;
              
            if(area1 < area2){
                w = w1; h = h1;
            } else {
                w = w2; h = h2;
            }
        }
  
        return w*h;
    }
  }
  

하지만 살짝 관점을 바꿔서, 각 명함들의 긴 쪽 방향과 짧은 쪽 방향을 일치 시켜 준다면 넓이를 비교하지 않고도 가장 작은 넓이의 지갑을 구할 수 있겠다.

• 두 번째 방식

  class Solution {
    public int solution(int[][] sizes) {
        int max_longSide = 0, max_shortSide = 0;   
          
        for(int[] size : sizes){
            int cur_longSide = Math.max(size[0],size[1]);
            int cur_shortSide = Math.min(size[0],size[1]);
              
            max_longSide = Math.max(max_longSide, cur_longSide);
            max_shortSide = Math.max(max_shortSide, cur_shortSide);
        }
  
        return max_longSide*max_shortSide;
    }
  }
  

  🔑 Code

class Solution {
    public int solution(int[][] sizes) {
        int max_longSide = 0, max_shortSide = 0;   
        
        for(int[] size : sizes){
            int cur_longSide = Math.max(size[0],size[1]);
            int cur_shortSide = Math.min(size[0],size[1]);
            
            max_longSide = Math.max(max_longSide, cur_longSide);
            max_shortSide = Math.max(max_shortSide, cur_shortSide);
        }

        return max_longSide*max_shortSide;
    }
}

🗨️ Side Notes

주요 링크

프로젝트 한눈에 보기

실행 화면

프로젝트 요약

한 줄 소개 개발자가 서비스명, 컨테이너 이미지, 자원 정보와 외부 공개 여부만 입력하면, 플랫폼이 Namespace·ResourceQuota·Deployment·Service·Ingress를 표준 규칙에 따라 생성하고 Pod 상태·Kubernetes Event·작업 이력까지 보여주는 배포·운영 플랫폼입니다.

플랫폼의 주요 흐름

개발자 편의와 운영 통제 사이: Kubernetes 기반 애플리케이션 배포·운영 플랫폼

애플리케이션 개발자가 Kubernetes에 서비스를 배포하려면 컨테이너 이미지만 준비해서는 부족하다.

Namespace와 Deployment를 정의하고, CPU와 Memory를 설정해야 한다. 애플리케이션에 접근하려면 Service가 필요하고, 외부에 공개하려면 Ingress와 도메인도 구성해야 한다. 배포가 실패하면 Pod 상태와 Kubernetes Event를 직접 확인해야 한다.

Kubernetes를 잘 아는 개발자에게는 익숙한 과정일 수 있지만, 서비스를 개발하는 모든 사람이 이런 세부사항을 직접 다루어야 할 필요가 있을까?

반대로 모든 과정을 버튼 하나로 감추면 또 다른 문제가 생긴다.

개발자는 편리해지지만 운영자는 리소스 이름, 격리 기준, 자원 제한, 외부 공개 정책을 통제하기 어려워진다. 자동화 내부에서 실패가 발생했을 때 사용자는 무엇이 잘못되었는지 알 수 없고, 결국 다시 플랫폼 운영자에게 문의해야 한다.

이 프로젝트는 이 두 문제 사이에서 시작했다.

개발자가 인프라의 복잡성을 덜 느끼면서도, 플랫폼 운영자는 표준과 통제 가능성을 유지하려면 어떻게 해야 할까?

이 질문을 풀기 위해 Kubernetes 기반 애플리케이션 배포·운영 플랫폼을 개발했다.

사용자가 서비스명, 컨테이너 이미지, 필요한 자원과 외부 공개 여부를 입력하면 플랫폼이 Kubernetes 리소스를 표준 규칙에 따라 생성한다. 생성 이후에는 Pod 상태와 Event를 조회해 배포 결과와 실패 원인을 확인할 수 있고, 삭제 과정과 작업 이력도 추적할 수 있도록 했다.

이 글에서는 프로젝트를 진행하며 가장 중요하게 고민했던 세 가지 문제를 중심으로 정리한다.

1. 어디까지 숨기고 무엇을 사용자에게 입력받을 것인가?
2. 셀프서비스가 운영 표준을 무너뜨리지 않게 하려면 어떻게 해야 하는가?
3. 편리한 자동화가 블랙박스가 되지 않게 하려면 어떻게 해야 하는가?

1. 프로젝트의 출발점: 배포 자동화만으로 충분한가

처음에는 Kubernetes 리소스를 자동 생성하는 것이 프로젝트의 핵심이라고 생각했다.

API 요청
→ Namespace 생성
→ Deployment 생성
→ Service 생성

하지만 실제 사용자의 흐름을 생각하자 생성 기능만으로는 부족했다.

개발자는 애플리케이션을 배포한 뒤 다음 질문을 하게 된다.

• 배포 요청이 정상적으로 접수되었는가?
• 실제 Pod가 실행되고 있는가?
• 외부에서 접근할 수 있는가?
• 실패했다면 어느 단계에서 실패했는가?
• 필요 없어졌을 때 모든 리소스가 정리되는가?

운영자에게도 다른 질문이 생긴다.

• 모든 프로젝트가 동일한 이름 규칙을 따르는가?
• 한 프로젝트가 자원을 과도하게 사용하지 않는가?
• 어떤 리소스가 플랫폼에서 생성된 것인지 구분할 수 있는가?
• 누가 언제 생성하고 삭제했는가?
• DB의 상태와 Kubernetes의 실제 상태가 다르면 어떻게 확인할 것인가?

따라서 이 프로젝트의 범위를 단순한 배포 자동화에서 다음 전체 생명주기로 확장했다.

신청
→ 입력 검증
→ 표준 리소스 생성
→ 상태 확인
→ 실패 원인 조회
→ 외부 접근
→ 삭제
→ 이력 보존

이 과정에서 프로젝트를 관통하는 세 가지 설계 문제가 구체화됐다.

2. 고민 1: 어디까지 숨기고 무엇을 사용자에게 입력받을 것인가

모든 설정을 보여주면 플랫폼을 만드는 의미가 없다

Kubernetes Deployment 하나에도 설정할 수 있는 항목은 많다.

• Replica 수
• Image
• Port
• Label
• Selector
• Resource Request와 Limit
• Probe
• Affinity
• Toleration
• Security Context
• Update Strategy

Service와 Ingress까지 포함하면 선택지는 더욱 많아진다.

사용자에게 Kubernetes의 모든 설정을 입력하도록 하면 자유도는 높아진다. 그러나 사용자가 결국 YAML 대신 긴 웹 양식을 작성하게 된다면 플랫폼을 사용하는 의미가 줄어든다.

반대로 모든 값을 고정하면 사용은 간단하지만 서비스마다 다른 요구를 수용할 수 없다.

따라서 먼저 다음 질문에 답해야 했다.

사용자가 표현해야 하는 것은 Kubernetes 리소스인가, 아니면 실행하려는 애플리케이션의 의도인가?

사용자는 인프라 구성이 아니라 실행 의도를 입력한다

사용자에게 필요한 것은 Namespace나 Deployment 자체가 아니다.

사용자가 표현하려는 의도는 다음에 가깝다.

이 이미지를 staging 환경에서 실행하고 싶다. Pod는 2개가 필요하고, 일정한 CPU와 Memory를 사용하며 외부에서도 접근할 수 있어야 한다.

따라서 입력값을 애플리케이션 실행 의도를 표현하는 최소 정보로 제한했다.

서비스명
실행 환경
컨테이너 이미지
Replica 수
CPU Request / Limit
Memory Request / Limit
컨테이너 포트
외부 공개 여부

반면 다음 항목은 플랫폼이 결정하도록 했다.

Namespace 이름
Deployment 이름
Service 이름
Ingress 이름
Label과 Selector
ResourceQuota 이름
Ingress Host 규칙
리소스 생성 순서
삭제 순서

이를 표로 정리하면 다음과 같다.

입력을 줄이는 것이 아니라 책임을 재배치했다

사용자 입력을 줄이는 목적은 단순히 화면을 간단하게 만드는 것이 아니었다.

Kubernetes 리소스 구조와 운영 규칙을 플랫폼의 책임으로 이동시킨 것이다.

사용자 요청
“demo-api를 staging 환경에 배포하고 싶다.”

플랫폼 해석
- Namespace: demo-api-staging
- Deployment: demo-api-deployment
- Service: demo-api-service
- Ingress: demo-api-ingress
- Replica: 2
- 공통 Label 적용
- ResourceQuota 적용

이 구조를 통해 사용자는 자신의 애플리케이션에 필요한 값에 집중하고, 플랫폼은 인프라 구현 방식을 일관되게 관리할 수 있다.

추상화에는 탈출구도 필요하다

모든 사용자에게 동일한 고정값만 강제하면 실제 활용도가 떨어질 수 있다.

그래서 다음 값은 기본값을 제공하되 사용자가 변경할 수 있도록 했다.

• Replica 수
• CPU Request와 Limit
• Memory Request와 Limit
• Container Port
• 외부 공개 여부

반면 리소스 이름과 Label처럼 운영 추적에 필요한 규칙은 사용자가 변경할 수 없게 했다.

이를 통해 다음 기준을 세웠다.

서비스 특성에 따라 달라질 수 있는 값은 입력받고, 조직 전체에서 일관되어야 하는 값은 플랫폼이 관리한다.

이것이 이 프로젝트에서 설정한 첫 번째 추상화 경계였다.

3. 고민 2: 셀프서비스가 운영 표준을 무너뜨리지 않게 하려면 어떻게 해야 하는가

셀프서비스는 무제한 권한 제공이 아니다

개발자가 Kubernetes API에 직접 접근할 수 있다면 원하는 리소스를 자유롭게 만들 수 있다.

그러나 이런 방식은 장기적으로 다음 문제를 만들 수 있다.

team-a-service
team_a_service
TeamA-Service
service-staging
staging-service

리소스 이름만 달라지는 것이 아니다.

• 팀마다 다른 Label 사용
• Resource Request와 Limit 누락
• Service Selector 불일치
• 외부 공개가 필요하지 않은 서비스까지 노출
• 프로젝트 소유자를 알 수 없는 리소스 생성
• 삭제 대상과 유지 대상 구분 어려움

셀프서비스를 단순히 사용자가 직접 모든 것을 할 수 있게 만드는 것으로 이해하면, 편의성은 높아지지만 운영 통제는 약해진다.

따라서 이 프로젝트에서는 셀프서비스를 다음과 같이 정의했다.

사용자가 필요한 자원을 스스로 요청할 수 있지만, 실제 생성은 플랫폼의 규칙과 제한 안에서 이루어지는 것.

플랫폼이 Guardrail을 제공하도록 설계했다

사용자에게 Kubernetes 리소스 생성 권한을 직접 주는 대신, 플랫폼이 요청을 받아 리소스를 생성한다.

이 과정에서 다음 운영 규칙을 자동으로 적용했다.

프로젝트별 Namespace

서비스명과 환경을 조합해 Namespace를 생성했다.

{service-name}-{environment}

예시:

demo-api-staging
order-api-dev
movie-service-prod

이를 통해 서비스와 환경 단위로 리소스를 격리하고, 조회와 삭제 범위도 명확하게 만들었다.

공통 Naming Convention

리소스 이름은 플랫폼이 예측 가능한 규칙으로 생성한다.

Namespace       demo-api-staging
Deployment      demo-api-deployment
Service         demo-api-service
Ingress         demo-api-ingress
ResourceQuota   demo-api-quota

공통 Label

모든 리소스에는 프로젝트와 플랫폼 관리 여부를 식별할 수 있는 Label을 적용했다.

app.kubernetes.io/managed-by: application-platform
app.kubernetes.io/name: demo-api
app.kubernetes.io/instance: demo-api-staging
platform.local/project-id: "1"
platform.local/environment: staging

Label은 단순한 메타데이터가 아니다.

• Service와 Pod 연결
• 프로젝트 리소스 조회
• 플랫폼 관리 대상 식별
• 삭제 대상 검증
• DB 프로젝트와 Kubernetes 리소스 연결

에 활용했다.

ResourceQuota

사용자가 입력한 CPU와 Memory 값만으로는 Namespace 전체의 자원 소비를 통제할 수 없다.

따라서 Namespace에 ResourceQuota를 적용해 프로젝트 전체가 사용할 수 있는 자원의 상한을 설정했다.

컨테이너 Request / Limit
= 개별 컨테이너의 자원 요청과 제한

ResourceQuota
= Namespace 전체의 자원 사용 상한

외부 공개 정책

모든 Service를 외부에 공개하지 않았다.

Service는 ClusterIP로 생성하고, 사용자가 외부 공개를 선택한 경우에만 Ingress를 생성했다.

expose_external = false
→ Cluster 내부에서만 접근

expose_external = true
→ Ingress 생성 및 외부 Host 제공

편의성과 통제는 반대 개념이 아니었다

처음에는 사용자의 자유를 제한하면 편의성도 줄어든다고 생각할 수 있었다.

그러나 반복적으로 필요한 규칙을 플랫폼이 대신 적용하면 사용자는 오히려 더 적은 판단으로 안전한 결과를 얻을 수 있다.

사용자 편의
- YAML 작성 불필요
- 리소스 간 연결 규칙을 알 필요 없음
- 이름 규칙을 직접 관리할 필요 없음

운영 통제
- 동일한 Naming Convention
- 공통 Label
- ResourceQuota
- 외부 공개 정책
- 추적 가능한 리소스

즉, 플랫폼의 역할은 사용자에게 모든 선택지를 제공하는 것이 아니라 안전한 선택 경로를 제공하는 것이라고 판단했다.

4. 고민 3: 편리한 자동화가 블랙박스가 되지 않게 하려면 어떻게 해야 하는가

API가 성공했다고 배포가 성공한 것은 아니다

Kubernetes API가 Deployment 생성을 수락했다고 해서 애플리케이션이 정상적으로 실행된 것은 아니다.

다음 요청은 모두 HTTP 수준에서는 정상적으로 처리될 수 있다.

Namespace 생성 성공
Deployment 생성 성공
Service 생성 성공

그 이후 Pod에서는 다음 문제가 발생할 수 있다.

• 존재하지 않는 이미지
• Private Registry 인증 실패
• ResourceQuota 초과
• Container 실행 실패
• 잘못된 Port
• Readiness 실패
• Node 자원 부족

따라서 POST /projects가 성공했다는 사실만 사용자에게 보여주면 자동화가 블랙박스가 된다.

사용자는 버튼을 눌렀지만 실제로 애플리케이션이 실행되었는지 알 수 없다.

Pod Phase만으로도 충분하지 않았다

Pod의 상태가 Pending이라고 표시되더라도 그 이유는 여러 가지일 수 있다.

Pending
├── 이미지 다운로드 중
├── ImagePullBackOff
├── 스케줄링 대기
├── ResourceQuota 초과
└── Volume 연결 대기

따라서 다음 정보를 함께 조회했다.

• Pod Phase
• Ready 여부
• Container State
• Waiting Reason
• Restart Count
• Node
• Pod IP
• Kubernetes Event

실패 시나리오를 일부러 만들었다

정상 이미지인 nginx:latest만 배포하면 Kubernetes 리소스가 생성되는 성공 경로만 확인할 수 있다.

하지만 플랫폼에서 더 중요한 것은 리소스 생성 요청이 수락된 이후, 실제 애플리케이션이 실행되지 않는 상황을 사용자가 이해할 수 있게 보여주는 것이다.

이를 검증하기 위해 서로 원인이 다른 두 가지 실패 시나리오를 의도적으로 만들었다.

1. 컨테이너 이미지를 가져오지 못하는 경우

첫 번째 시나리오에서는 존재하지 않는 이미지 주소를 입력했다.

does-not-exist.local/broken/nginx:missing

Kubernetes는 Deployment와 Pod를 생성했지만, 컨테이너 이미지를 찾을 수 없어 다음 상태로 전이됐다.

Pod 생성
→ 이미지 Pull 시도
→ ErrImagePull
→ 재시도
→ ImagePullBackOff

플랫폼에서는 단순히 프로젝트를 FAILED로 표시하는 데 그치지 않고 다음 정보를 함께 제공했다.

Pod Phase       Pending
Container State waiting
Waiting Reason  ImagePullBackOff
Event Reason    Failed / BackOff
Event Message   이미지 조회 및 Pull 실패

화면의 Kubernetes Event를 통해 이미지 저장소의 이름이나 Tag가 잘못되었는지, Registry 접근 자체가 불가능한지 확인할 수 있다.

2. 이미지는 실행됐지만 컨테이너가 반복 종료되는 경우

두 번째 시나리오에서는 이미지 자체는 정상적으로 로드되지만, 컨테이너 프로세스가 실행 직후 종료되도록 구성했다.

이 경우 Kubernetes는 컨테이너를 다시 실행하려고 반복적으로 시도하며 CrashLoopBackOff 상태가 발생한다.

이미지 로드 성공
→ 컨테이너 생성
→ 컨테이너 시작
→ 프로세스 종료
→ 재시작
→ CrashLoopBackOff

이 시나리오는 이미지 다운로드 실패와 달리 Pod의 Phase가 Running으로 보일 수 있다는 점도 확인할 수 있었다.

따라서 Pod Phase만으로 성공 여부를 판단하지 않고 다음 정보를 함께 분석해야 했다.

Pod Phase
Container State
Waiting Reason
Restart Count
Kubernetes Event

플랫폼은 BackOff restarting failed container Event와 CrashLoopBackOff 상태를 확인해 프로젝트 상태를 FAILED로 동기화했다.

두 실패는 사용자에게는 모두 “애플리케이션이 실행되지 않는다”는 동일한 결과로 보이지만, 원인과 대응 방법은 다르다.

또한 두 화면의 Audit Log에서는 Kubernetes 리소스 생성이 완료된 뒤에도 실제 워크로드 상태를 다시 조회해 프로젝트 상태가 RUNNING 또는 PROVISIONING에서 FAILED로 변경되는 과정을 확인할 수 있다.

이를 통해 다음 두 상태를 구분해야 한다는 점을 확인했다.

리소스 생성 성공
≠
애플리케이션 실행 성공

따라서 플랫폼은 API 요청과 리소스 생성 결과만 보여주는 것이 아니라, Pod와 Container의 실제 상태를 지속적으로 확인하고 실패 원인을 사용자에게 전달하도록 설계했다.

Kubernetes의 실제 상태와 플랫폼 상태를 분리했다

Kubernetes에는 Pod와 Deployment의 실제 상태가 있다.

플랫폼 DB에는 사용자의 요청과 업무 생명주기 상태가 있다.

플랫폼 상태
REQUESTED
PROVISIONING
RUNNING
FAILED
DELETING
DELETED

Kubernetes 상태
Pending
Running
ImagePullBackOff
CrashLoopBackOff
Terminated

두 상태는 같지 않다.

예를 들어 프로젝트가 PROVISIONING인 동안 Pod는 Pending일 수 있다. 모든 Pod가 Ready가 되면 플랫폼 상태를 RUNNING으로 변경할 수 있다. ImagePullBackOff가 확인되면 FAILED로 판단할 수 있다.

Kubernetes 상태 조회
→ Pod와 Container 상태 분석
→ 플랫폼 상태 판단
→ DB 상태 변경
→ 상태 이력 저장

생성뿐 아니라 삭제와 이력까지 보여주었다

자동화가 투명하려면 생성 이후의 과정도 확인할 수 있어야 한다.

프로젝트 삭제 시 다음 리소스를 정리한다.

Ingress
→ Service
→ Deployment
→ ResourceQuota
→ Namespace

삭제 후 DB 레코드를 완전히 제거하지 않고 상태를 DELETED로 변경했다.

또한 다음 작업을 Audit Log에 기록했다.

• 프로젝트 생성
• Namespace 생성
• Deployment 생성
• Service 생성
• Ingress 생성
• 상태 변경
• 오류 발생
• 프로젝트 삭제

누가 무엇을 요청했는가
→ 어떤 리소스가 생성되었는가
→ 결과가 성공했는가
→ 언제 삭제되었는가

이력까지 남김으로써 자동화를 단순히 편리한 기능이 아니라 추적 가능한 운영 과정으로 만들고자 했다.

프로젝트 요구사항 역시 정상 배포뿐 아니라 실패 원인 확인, 리소스 삭제, Audit Log를 핵심 사용자 시나리오로 정의하고 있다.

5. 세 가지 고민을 시스템 구조로 연결하기

세 가지 고민은 각각 독립된 기능이 아니라 전체 아키텍처에 반영됐다.

1. 사용자의 의도만 입력받는다.
            |
            v
React 프로젝트 생성 화면
            |
            v
2. 플랫폼 규칙을 적용한다.
            |
            v
FastAPI 입력 검증 및 Kubernetes 리소스 생성
            |
            v
Namespace / Quota / Deployment / Service / Ingress
            |
            v
3. 결과와 실패를 다시 사용자에게 보여준다.
            |
            v
Pod / Event 조회, 상태 이력, Audit Log

React Dashboard

사용자가 애플리케이션 실행에 필요한 값만 입력하도록 화면을 구성했다.

주요 화면은 다음과 같다.

• 프로젝트 목록
• 프로젝트 생성
• 프로젝트 상세
• Pod 상태
• Kubernetes Event
• 삭제 결과
• Audit Log

FastAPI Backend

FastAPI는 단순 CRUD 서버가 아니라 사용자 요청과 Kubernetes 사이의 제어 계층으로 동작한다.

주요 책임은 다음과 같다.

• 입력 검증
• Naming Convention 적용
• 프로젝트 상태 관리
• Kubernetes 리소스 생성
• Pod와 Event 조회
• 오류 변환
• 리소스 삭제
• Audit Log 저장

MariaDB

DB에는 Kubernetes의 현재 상태만으로 알 수 없는 정보를 저장한다.

• 사용자가 요청한 값
• 프로젝트 현재 상태
• 상태 변경 이력
• 생성된 Kubernetes 리소스 메타데이터
• 최근 오류
• 생성·삭제 Audit Log

DB 모델은 프로젝트, 상태 이력, Kubernetes 리소스 메타데이터, Audit Log를 분리해 생명주기를 추적하도록 설계했다.

Kubernetes

Kubernetes는 실제 애플리케이션을 실행한다.

• Namespace를 통한 격리
• ResourceQuota를 통한 자원 제한
• Deployment를 통한 Pod 관리
• Service를 통한 내부 접근
• Ingress를 통한 외부 접근
• Pod와 Event를 통한 실행 상태 제공

6. 구현 흐름

프로젝트 생성

1. 사용자가 서비스 정보를 입력한다.
2. FastAPI가 입력값을 검증한다.
3. MariaDB에 프로젝트를 REQUESTED 상태로 저장한다.
4. Namespace를 생성한다.
5. ResourceQuota를 생성한다.
6. Deployment를 생성한다.
7. Service를 생성한다.
8. 외부 공개 요청이면 Ingress를 생성한다.
9. 생성된 리소스 정보를 DB에 저장한다.
10. Audit Log를 기록한다.

상태 조회

1. 사용자가 프로젝트 상세 화면에 접근한다.
2. DB에서 신청 정보와 플랫폼 상태를 조회한다.
3. Kubernetes API에서 Pod를 조회한다.
4. Container State와 Waiting Reason을 분석한다.
5. Namespace의 최근 Event를 조회한다.
6. 결과를 프로젝트 상세 화면에 표시한다.

삭제

1. 사용자가 프로젝트 삭제를 요청한다.
2. 프로젝트 상태를 DELETING으로 변경한다.
3. 플랫폼이 생성한 리소스인지 Label로 확인한다.
4. Ingress부터 Namespace까지 순차적으로 삭제한다.
5. 프로젝트 상태를 DELETED로 변경한다.
6. 삭제 시각과 Audit Log를 저장한다.

7. 로컬에서 검증한 뒤 GKE로 확장하기

Kubernetes 연동 기능을 개발할 때마다 클라우드 환경을 사용하면 반복 테스트가 느리고 비용이 발생할 수 있다.

따라서 개발 초기에는 Docker 위에 kind 클러스터를 구성해 로컬에서 빠르게 검증했다.

Local Machine
├── Docker Desktop
│   ├── MariaDB
│   └── kind Kubernetes Cluster
├── FastAPI
└── React

kind 환경에서는 다음 기능을 실제로 검증했다.

• Namespace 생성
• Deployment와 Pod 생성
• Service 연결
• ResourceQuota 적용
• Ingress 생성
• Pod 상태 조회
• ImagePullBackOff 재현
• Kubernetes Event 조회
• 리소스 삭제

로컬에서 정상·실패·삭제 시나리오를 반복 검증한 뒤에는 플랫폼 자체를 GKE에 배포했다.

이때 단순히 애플리케이션을 클러스터에 올리는 데 그치지 않고, 포털 접근 경로와 사용자가 생성한 애플리케이션의 외부 접근 경로를 분리했다.

포털 접근 경로

포털은 portal.la-coruna.xyz 도메인으로 접근하도록 구성했다.

External User
      |
      v
portal.la-coruna.xyz
      |
      v
GCE Ingress
      |
      v
portal-frontend / portal-backend
      |
      v
GKE Kubernetes API
      |
      v
사용자 애플리케이션 Namespace

포털 백엔드는 클러스터 내부에서 Kubernetes API를 호출해 Namespace, ResourceQuota, Deployment, Service와 Ingress를 생성한다.

사용자 애플리케이션 접근 경로

사용자가 외부 공개를 선택한 애플리케이션에는 다음 도메인 규칙을 적용했다.

{service-name}-{environment}.apps.la-coruna.xyz

예를 들어 demo-api 서비스를 staging 환경에 생성하면 다음 주소로 접근할 수 있다.

demo-api-staging.apps.la-coruna.xyz

초기에는 프로젝트마다 GKE 기본 Ingress를 생성했다. 이 구조에서는 각 프로젝트 Ingress가 별도의 Load Balancer IP를 사용하므로, 테스트 프로젝트가 늘어날수록 DNS 설정과 비용 관리가 복잡해질 수 있었다.

이를 해결하기 위해 사용자 애플리케이션용 Ingress를 하나의 shared ingress-nginx controller로 통합했다.

External User
      |
      v
*.apps.la-coruna.xyz
      |
      v
shared ingress-nginx LoadBalancer
      |
      v
Project Ingress
      |
      v
Service
      |
      v
Pod

접근 경로를 정리하면 다음과 같다.

이 구조를 통해 포털 운영 트래픽과 사용자 애플리케이션 트래픽을 구분했다. 또한 프로젝트가 늘어나더라도 하나의 shared ingress-nginx 진입점과 Wildcard DNS를 통해 외부 접근을 일관되게 관리할 수 있게 했다.

단순히 GKE에 배포하는 데 그치지 않고, 도메인과 Ingress 구조를 운영 관점에서 다시 설계했다.

8. 검증한 시나리오

정상 배포

입력 이미지: nginx:latest
Replica: 1
외부 공개: true

확인한 결과:

• Namespace 생성
• ResourceQuota 생성
• Deployment 생성
• Pod Running
• Container Ready
• Service 생성
• Ingress 생성
• 외부 도메인 접근 성공

실패 배포

입력 이미지: 존재하지 않는 이미지

확인한 결과:

• Deployment와 Pod 생성
• Pod Pending
• Container Waiting
• ImagePullBackOff 확인
• Kubernetes Event에서 이미지 Pull 실패 원인 확인
• 플랫폼 화면에서 실패 정보 조회

삭제

확인한 결과:

• 관련 Kubernetes 리소스 정리
• 프로젝트 상태 DELETED 반영
• 삭제 시각 보존
• Audit Log 기록
• 중복 삭제 요청 방지

상태 추적

확인한 결과:

• 신청 정보와 실제 Kubernetes 상태 분리
• Pod와 Event 정보 조회
• 프로젝트 상태 변화 저장
• 생성·실패·삭제 이력 확인

10. 현재 구조의 한계

이 프로젝트는 애플리케이션 배포·운영의 핵심 흐름을 검증하기 위한 MVP다.

실제 조직에서 사용하려면 다음 기능이 추가로 필요하다.

인증과 권한

현재보다 사용자와 팀을 명확히 구분하고, 프로젝트별 조회·생성·삭제 권한을 적용해야 한다.

Kubernetes 접근도 운영 환경에서는 ServiceAccount와 RBAC 최소 권한으로 제한해야 한다.

비동기 Provisioning

현재 구조보다 규모가 커지면 HTTP 요청 안에서 모든 리소스를 생성하는 대신 작업 Queue와 Worker를 이용해 비동기로 처리하는 것이 적합하다.

생성 요청
→ REQUESTED 저장
→ Queue 등록
→ Worker Provisioning
→ 상태 갱신

Reconciliation

DB의 목표 상태와 Kubernetes의 실제 상태가 달라질 수 있다.

주기적으로 두 상태를 비교하고 누락되거나 변경된 리소스를 감지하는 Reconciliation 과정이 필요하다.

GitOps

현재는 FastAPI가 Kubernetes API에 직접 리소스를 반영한다.

운영 환경에서는 Helm Values를 Git에 저장하고 ArgoCD가 반영하는 구조로 확장할 수 있다.

사용자 요청
→ FastAPI
→ Helm Values 생성
→ Git Commit
→ ArgoCD Sync
→ Kubernetes 반영

이를 통해 변경 이력, Diff, Rollback과 Drift 감지를 강화할 수 있다.

관측성

Provisioning 소요 시간, 실패율, 오류 유형과 API 상태를 수집하기 위해 Prometheus, Grafana와 중앙 로그 시스템을 연결할 수 있다.

현재 구현한 Direct Apply와 향후 GitOps 확장 구조는 아키텍처 단계에서 명확히 분리했다.

11. 프로젝트를 통해 배운 점

플랫폼은 복잡성을 없애는 것이 아니라, 적절한 곳으로 옮기는 일이다

플랫폼을 만든다고 해서 Kubernetes의 복잡성 자체가 사라지는 것은 아니었다.

기존에는 사용자가 직접 처리해야 했던 리소스 이름 규칙, Label과 Selector, ResourceQuota, 리소스 생성 순서 등을 플랫폼이 대신 책임지게 된 것이다.

좋은 플랫폼은 복잡성을 무조건 감추는 것이 아니라, 사용자가 알 필요 없는 부분은 내부에서 처리하고, 배포 상태와 실패 원인처럼 사용자가 판단에 필요한 정보는 다시 명확하게 전달해야 한다.

셀프서비스와 운영 통제는 함께 설계할 수 있다

처음에는 사용자의 자유도를 높이는 것과 운영자의 통제를 유지하는 것이 서로 충돌할 수 있다고 생각했다.

하지만 플랫폼이 안전한 기본값과 명확한 제한을 제공하면 두 가지를 함께 만족시킬 수 있었다.

사용자는 복잡한 설정을 반복해서 판단하지 않아도 더 빠르고 안전하게 작업할 수 있고, 운영자는 일관된 규칙으로 생성된 리소스를 관리할 수 있다.

정상 동작뿐 아니라 실패 상황을 검증하는 일이 중요했다

정상적인 이미지를 배포하는 기능만으로는 플랫폼의 운영 가치를 충분히 검증하기 어려웠다.

존재하지 않는 이미지, 컨테이너 반복 종료, 중복 요청, 삭제와 같은 실패·예외 상황을 직접 구현하고 검증하면서 상태 관리와 관측성의 중요성을 체감했다.

특히 단순히 실패했다는 결과만 보여주는 것이 아니라, 사용자가 원인을 이해하고 다음 행동을 결정할 수 있도록 Pod 상태와 Kubernetes Event를 함께 제공해야 한다는 점을 배웠다.

리소스 생성보다 전체 생명주기를 관리하는 일이 더 중요하다

처음에는 Kubernetes 리소스를 생성하는 코드가 프로젝트의 핵심이라고 생각했다.

하지만 실제로는 생성 전후의 전체 과정을 관리하는 데 더 많은 고민이 필요했다.

요청을 어떻게 검증할 것인가
→ 생성 과정을 어떤 상태로 표현할 것인가
→ 실패 원인을 어떻게 전달할 것인가
→ 플랫폼이 생성한 리소스만 어떻게 식별하고 삭제할 것인가
→ 삭제 이후의 이력을 어떻게 보존할 것인가

이 경험을 통해 플랫폼 개발은 단순히 인프라 명령을 대신 실행하는 일이 아니라, 사용자의 의도를 안전한 시스템 동작으로 변환하고 그 결과를 전체 생명주기에 걸쳐 관리하는 일이라는 점을 배웠다.

12. 마치며

Kubernetes 기반 애플리케이션 배포·운영 플랫폼은 다음 질문에서 출발했다.

개발자가 Kubernetes의 모든 세부사항을 직접 다루지 않고도 애플리케이션을 배포할 수 있을까?

그러나 프로젝트를 진행하며 질문은 다음과 같이 확장됐다.

개발자에게 편리한 경험을 제공하면서, 운영 표준과 실패에 대한 가시성까지 함께 보장할 수 있을까?

이 질문에 답하기 위해 세 가지 원칙을 세웠다.

1. 사용자는 인프라가 아니라 애플리케이션 실행 의도를 입력한다.
2. 플랫폼은 Naming, 격리, 자원과 네트워크 정책을 표준화한다.
3. 복잡성은 숨기되 상태와 실패 원인까지 숨기지는 않는다.

이 원칙을 바탕으로 신청부터 생성, 상태 확인, 실패 분석, 외부 공개, 삭제와 이력 보존까지 하나의 흐름으로 구현했다.

완성된 상용 플랫폼과 비교하면 인증, 멀티 클러스터, Reconciliation, GitOps와 관측성 등 보완할 부분이 남아 있다.

그럼에도 이번 프로젝트를 통해 Kubernetes를 사용하는 경험을 넘어, 복잡한 인프라를 개발자가 반복해서 사용할 수 있는 제품 인터페이스로 바꾸는 과정을 경험할 수 있었다.

플랫폼 개발은 명령을 대신 실행하는 일이 아니라, 사용자 편의와 운영 통제 사이의 경계를 설계하는 일이다.

프로젝트 링크

• 서비스
• GitHub

StoreOps Platform 시리즈

• 1편: 프로젝트 배경
• 2편: 도메인 설계
• 3편: 재고 트랜잭션
• 4편: 대규모 Inventory 확장
• 전체 글 목록

1. 왜 이 글을 쓰는가

StoreOps Platform은 편의점 운영 흐름을 작게 구현해보기 위한 MVP 프로젝트다.

지금까지 이 프로젝트에서는 POS 판매, PDA 입고, 고객 재고조회, 관리자 재고/발주 기능을 하나의 재고 데이터를 중심으로 연결했다.

MVP에서의 핵심 구조는 단순하다.

POS 판매  → Inventory 감소
PDA 입고  → Inventory 증가
고객 조회 → Inventory 조회
관리자    → Inventory + Sale 이력 기반 운영 판단

이 구조는 학습용 프로젝트에서 장점이 분명하다. POS, PDA, 고객 앱, 관리자 WEB이 서로 다른 시스템처럼 보이지만 결국 점포별 상품 재고라는 같은 데이터를 기준으로 연결된다는 메시지를 보여주기 좋다.

하지만 프로젝트를 구현하면서 자연스럽게 다음 질문이 생겼다.

실제 대규모 운영 시스템에서도 Inventory 테이블 하나만으로 충분할까?
고객 앱 조회 트래픽이 많아지면 어떻게 해야 할까?
동시에 여러 POS 판매 요청이 들어오면 초과 판매를 어떻게 막을까?
입고와 판매 외에 폐기, 반품, 조정, 점포 간 이동은 어떻게 기록할까?
픽업 예약처럼 아직 판매 확정은 아니지만 재고를 잡아둬야 하는 상황은 어떻게 처리할까?
네트워크 장애로 POS 이벤트가 중복 전송되면 재고가 두 번 줄어들지 않을까?

물론 실제 편의점 기업의 내부 시스템 구조를 알 수는 없다. 따라서 이 글은 특정 회사의 실제 구조를 단정하는 글이 아니다.

대신 내가 구현한 MVP 재고 시스템을 출발점으로, 대규모 운영 시스템으로 확장한다고 가정했을 때 어떤 문제를 고려할 수 있는지 정리해보려 한다.

이번 글의 핵심 메시지는 다음과 같다.

MVP에서는 Inventory를 단일 기준 데이터로 단순화했다.
하지만 대규모 운영 시스템에서는 재고 정합성, 운영 추적성, 고객 조회 성능, 예약 재고, 장애 복구를 위해
StockMovement, InventoryBalance, Reservation, CustomerAvailabilityView 같은 역할 분리가 필요할 수 있다.

2. MVP Inventory 구조 다시 보기

먼저 현재 MVP 구조를 다시 정리해보자.

현재 프로젝트에서는 재고를 다음과 같이 단순하게 표현했다.

inventories
- id
- store_id
- product_id
- quantity
- created_at
- updated_at

그리고 재고 변동 이력은 판매와 입고로 나누어 저장했다.

sales
- id
- store_id
- product_id
- quantity
- sold_at

receipts
- id
- store_id
- product_id
- quantity
- received_at

이 구조에서 주요 흐름은 다음과 같다.

POS 판매
→ inventories.quantity 감소
→ sales 이력 저장

PDA 입고
→ inventories.quantity 증가
→ receipts 이력 저장

고객 재고조회
→ inventories.quantity 조회

관리자 발주 추천
→ inventories.quantity + sales 이력 기반 계산

이 구조는 MVP 단계에서 충분히 의미가 있다.

첫째, 구조가 단순하다. 점포별 상품 재고를 Inventory 하나로 표현하기 때문에 프로젝트의 핵심 메시지가 명확하다.

둘째, 트랜잭션 처리가 쉽다. POS 판매 시 재고 차감과 판매 이력 저장을 하나의 @Transactional 안에서 처리할 수 있고, PDA 입고도 재고 증가와 입고 이력 저장을 하나의 트랜잭션으로 묶을 수 있다.

셋째, 구현 범위가 적절하다. 학습용 프로젝트에서 너무 복잡한 구조를 처음부터 적용하면 오히려 핵심 기능 완성도가 떨어질 수 있다. MVP에서는 재고 흐름을 끝까지 구현하는 것이 더 중요했다.

하지만 이 구조에는 한계도 있다.

재고 변동 사유가 Sale, Receipt로만 제한된다.
폐기, 반품, 재고 조정, 점포 간 이동을 표현하기 어렵다.
고객 조회 트래픽이 많아지면 Inventory 직접 조회가 부담될 수 있다.
예약 재고와 실제 보유 재고를 구분하지 않는다.
동시 판매 상황에서 초과 판매 문제가 발생할 수 있다.
오프라인 POS나 중복 이벤트 처리까지 고려하지 않는다.

따라서 실제 대규모 시스템으로 확장한다고 가정하면, Inventory를 단일 테이블로만 보기보다 여러 책임으로 나누어 생각할 필요가 있다.

3. 대규모 Inventory에서 새로 생기는 문제

대규모 운영 환경에서 재고는 단순히 “현재 몇 개 남았는가”를 저장하는 데이터가 아니다.

재고는 고객 경험, 점포 운영, 물류, 발주, 정산, 장애 대응과 모두 연결된다.

MVP에서는 다음 정도의 흐름만 다루었다.

판매
입고
조회
발주 추천

하지만 실제 운영 규모를 가정하면 다음과 같은 상황들이 추가된다.

고객 앱에서 특정 상품의 점포별 재고조회 요청이 많이 발생한다.
동일 상품에 대해 여러 POS 판매 요청이 동시에 들어온다.
PDA 입고 외에도 폐기, 반품, 재고 조정, 점포 간 이동이 발생한다.
픽업 예약이나 배달 주문으로 재고를 미리 잡아둬야 한다.
점포 POS가 네트워크 장애를 겪은 뒤 판매 이벤트를 재전송할 수 있다.
고객 앱에는 실제 재고 수량을 그대로 보여주기 어려울 수 있다.
운영자는 현재 재고뿐 아니라 재고가 왜 변했는지도 추적해야 한다.

이 문제들을 모두 inventories.quantity 하나로 처리하려고 하면 한계가 생긴다.

그래서 대규모 Inventory 설계에서는 다음 질문을 나누어 생각해야 한다.

1. 재고가 왜 변했는가?
2. 현재 재고는 얼마인가?
3. 판매 가능한 재고는 얼마인가?
4. 고객에게 어떤 상태로 보여줄 것인가?
5. 조회 성능을 어떻게 확보할 것인가?
6. 중복 이벤트와 동시 요청을 어떻게 처리할 것인가?

이 질문에 맞춰 Inventory를 여러 층으로 나누면 다음과 같은 구조를 생각할 수 있다.

StockMovement
→ 재고 변동 원장

InventoryBalance
→ 현재 재고 상태

Reservation
→ 예약/홀드 재고

CustomerAvailabilityView
→ 고객 앱 조회용 재고 상태

Cache/Search/Analytics
→ 빠른 조회와 분석을 위한 파생 데이터

각 층은 같은 재고를 다루지만 목적이 다르다.

StockMovement는 “왜 변했는가”를 기록한다. InventoryBalance는 “현재 얼마인가”를 빠르게 보여준다. Reservation은 “아직 판매 확정은 아니지만 잡혀 있는 재고”를 관리한다. CustomerAvailabilityView는 “고객에게 어떻게 보여줄 것인가”를 담당한다. Cache나 검색 인덱스는 “어떻게 빠르게 조회할 것인가”를 담당한다.

4. 주요 확장 요소 간단히 정리

앞에서 정리한 구조를 실제 테이블 수준까지 자세히 풀어낼 수도 있지만, 이 글에서는 개념의 역할만 간단히 짚고 넘어가는 정도가 적절하다고 생각했다.

MVP에서 사용한 Inventory, Sale, Receipt 구조를 대규모 시스템으로 확장한다면 다음과 같이 역할을 나눠볼 수 있다.

StockMovement는 판매, 입고뿐 아니라 폐기, 반품, 재고 조정, 점포 간 이동처럼 다양한 재고 변동 사유를 하나의 원장으로 남기기 위한 구조다. MVP에서는 Sale과 Receipt를 분리했지만, 규모가 커지면 모든 재고 변동을 하나의 기준으로 추적하는 편이 운영 분석에 더 유리할 수 있다.

InventoryBalance는 현재 재고를 빠르게 조회하기 위한 상태 데이터다. 모든 변동 이력을 매번 합산해서 현재 재고를 계산하면 비용이 커질 수 있기 때문에, 현재 보유 재고와 판매 가능 재고를 별도로 관리하는 구조를 생각할 수 있다.

available_quantity = on_hand_quantity - reserved_quantity - safety_stock

Reservation은 픽업 예약이나 배달 주문처럼 아직 판매가 확정되지는 않았지만 다른 고객에게 팔면 안 되는 수량을 관리한다. 이 개념이 없으면 앱에서 예약된 상품과 매장 판매가 겹쳐 초과 판매가 발생할 수 있다.

CustomerAvailabilityView는 고객 앱 조회를 위한 가공 데이터다. 고객에게는 실제 수량을 그대로 보여주기보다 AVAILABLE, LOW_STOCK, SOLD_OUT 같은 상태값으로 제공하는 편이 더 안전할 수 있다.

즉, 대규모 Inventory 설계에서는 하나의 quantity만 보는 것이 아니라 다음 질문을 나누어 생각해야 한다.

재고가 왜 변했는가?
현재 시스템상 재고는 얼마인가?
그중 실제 판매 가능한 재고는 얼마인가?
고객에게는 어떤 상태로 보여줄 것인가?

MVP는 이 구조를 모두 구현하지는 않았지만, Inventory, Sale, Receipt, 고객 재고조회 API를 통해 이 확장 구조의 가장 작은 형태를 구현했다고 볼 수 있다.

5. Redis Cache와 조회용 파생 데이터

고객 재고조회는 조회 트래픽이 많을 수 있다.

예를 들어 인기 상품이나 행사 상품의 경우, 많은 고객이 주변 점포 재고를 동시에 조회할 수 있다. 이때 매번 운영 DB의 InventoryBalance를 직접 조회하면 부담이 커질 수 있다.

그래서 Redis 캐시나 검색 인덱스를 사용할 수 있다.

예를 들어 Redis key를 다음과 같이 둘 수 있다.

availability:product:1001:region:seoul-hanyang

value는 다음과 같은 형태가 될 수 있다.

[
  {
    "storeId": 1,
    "status": "AVAILABLE",
    "displayQuantityRange": "3개 이상"
  },
  {
    "storeId": 2,
    "status": "LOW_STOCK",
    "displayQuantityRange": "1~2개"
  },
  {
    "storeId": 3,
    "status": "SOLD_OUT",
    "displayQuantityRange": "0개"
  }
]

하지만 재고 데이터 캐싱은 조심해야 한다. 재고는 POS 판매와 PDA 입고에 따라 자주 바뀐다.

POS 판매 → 재고 감소
PDA 입고 → 재고 증가
예약 생성 → 판매 가능 재고 감소
예약 취소 → 판매 가능 재고 증가
폐기 처리 → 재고 감소

따라서 단순히 “Redis를 쓰면 빠르다”로 접근하면 위험하다. 캐시가 오래 남아 있으면 실제 재고와 고객 앱 조회 결과가 달라질 수 있기 때문이다.

그래서 캐시를 적용한다면 다음 전략을 함께 고려해야 한다.

TTL을 짧게 둔다.
POS 판매나 PDA 입고 이벤트 발생 시 캐시를 무효화한다.
정확한 수량이 아니라 AVAILABLE/LOW_STOCK/SOLD_OUT 상태만 캐시한다.
고객에게 last_synced_at을 함께 제공한다.
재고 수량이 적은 상품은 더 보수적으로 표시한다.

대규모 구조에서는 다음과 같은 흐름을 생각할 수 있다.

InventoryBalance 변경
→ InventoryUpdated 이벤트 발행
→ CustomerAvailabilityView 갱신
→ Redis 캐시 무효화 또는 갱신
→ 고객 앱 조회 결과 반영

이 구조에서 Redis는 기준 데이터가 아니다. 기준 데이터는 InventoryBalance와 StockMovement이고, Redis는 빠른 조회를 위한 파생 데이터다.

이 점이 중요하다.

Redis는 재고의 원본 데이터가 아니라, 고객 조회 성능을 높이기 위한 캐시다.

6. 동시성 제어: 초과 판매를 어떻게 막을 것인가

재고 시스템에서 가장 중요한 문제 중 하나는 동시성이다.

예를 들어 현재 판매 가능 재고가 1개 남았다고 하자.

available_quantity = 1

그런데 동시에 두 POS에서 판매 요청이 들어온다.

요청 A: 1개 판매
요청 B: 1개 판매

두 요청이 모두 현재 재고 1개를 보고 판매 가능하다고 판단하면, 총 2개가 판매되는 문제가 발생할 수 있다.

이를 막기 위한 방식은 여러 가지가 있다.

6.1 조건부 UPDATE

가장 직관적인 방식 중 하나는 조건부 UPDATE다.

UPDATE inventory_balances
SET available_quantity = available_quantity - :quantity
WHERE store_id = :storeId
  AND product_id = :productId
  AND available_quantity >= :quantity;

이 쿼리는 available_quantity가 요청 수량 이상일 때만 차감된다.

업데이트된 row 수가 1이면 성공이고, 0이면 재고 부족으로 처리할 수 있다.

updated row count = 1 → 판매 성공
updated row count = 0 → 재고 부족

이 방식의 장점은 재고 부족 검증과 차감을 DB의 단일 UPDATE로 처리할 수 있다는 점이다.

6.2 낙관적 락

두 번째 방식은 낙관적 락이다.

InventoryBalance에 version 컬럼을 두고, 업데이트 시점에 내가 읽은 version과 현재 version이 같은지 확인한다.

조회 시 version = 10
업데이트하려고 보니 version = 11
→ 누군가 먼저 수정함
→ 업데이트 실패 후 재시도 또는 실패 응답

JPA에서는 @Version을 사용할 수 있다.

@Version
private Long version;

낙관적 락은 충돌이 많지 않은 상황에서는 효율적이다. 하지만 인기 상품처럼 동시에 많은 요청이 몰리는 경우에는 충돌과 재시도가 많아질 수 있다.

6.3 비관적 락

세 번째 방식은 비관적 락이다.

재고 row를 먼저 잠근 뒤 처리하는 방식이다.

SELECT *
FROM inventory_balances
WHERE store_id = :storeId
  AND product_id = :productId
FOR UPDATE;

이 방식은 정합성을 강하게 보장할 수 있다.

하지만 동시에 요청이 많이 몰리면 대기 시간이 증가할 수 있다. 즉, 정확성은 높지만 성능 부담이 생길 수 있다.

6.4 어떤 방식을 선택할 것인가

정답은 상황에 따라 달라진다.

충돌이 적은 상품 → 낙관적 락
인기 상품처럼 충돌이 많은 상품 → 조건부 UPDATE 또는 비관적 락
강한 정합성이 필요한 예약/결제 흐름 → 더 엄격한 락 전략
조회 중심 기능 → 캐시와 read model 활용

MVP에서는 기본 트랜잭션과 재고 음수 방지까지만 구현했다. 하지만 대규모 시스템으로 확장한다면 조건부 UPDATE, 낙관적 락, 비관적 락 중 하나를 상황에 맞게 선택해야 한다.

이 지점에서 중요한 것은 “무조건 어떤 기술을 쓴다”가 아니라, 재고 정합성과 처리량 사이의 균형을 어떻게 잡을 것인가다.

7. 오프라인 POS와 idempotency key

편의점 점포 시스템에서는 네트워크가 항상 안정적이라고 가정하기 어렵다.

점포 POS가 일시적으로 서버와 연결되지 않을 수 있다. 하지만 네트워크가 잠깐 불안정하다고 해서 모든 판매를 중단하기는 어렵다.

그래서 POS는 판매 이벤트를 로컬에 저장했다가, 네트워크가 복구되면 서버로 다시 전송하는 구조를 가질 수 있다.

이때 문제가 되는 것은 중복 전송이다.

예를 들어 다음 상황을 생각해보자.

1. POS가 판매 이벤트 S-1001을 서버로 전송한다.
2. 서버는 정상 처리했지만 응답 중 네트워크가 끊긴다.
3. POS는 실패했다고 판단하고 같은 이벤트 S-1001을 다시 전송한다.
4. 서버가 이를 새로운 이벤트로 처리하면 재고가 두 번 차감된다.

이 문제를 막기 위해 idempotency_key가 필요하다.

idempotency는 같은 요청이 여러 번 들어와도 결과가 한 번 처리된 것과 같도록 만드는 성질이다.

POS 판매 이벤트에서는 다음과 같은 값을 idempotency key로 사용할 수 있다.

pos_terminal_id + receipt_number + sold_at

또는 POS 시스템에서 생성한 고유 판매 이벤트 ID를 사용할 수도 있다.

StockMovement에 idempotency_key를 저장하면, 같은 이벤트가 다시 들어왔을 때 중복 처리를 막을 수 있다.

이미 처리된 idempotency_key
→ 재고 차감하지 않음
→ 기존 처리 결과 반환 또는 중복 이벤트로 무시

이 구조는 개발운영 관점에서 중요하다.

네트워크 장애나 재시도는 운영 환경에서 충분히 발생할 수 있기 때문이다. 따라서 대규모 재고 시스템에서는 “정상 요청”뿐 아니라 “중복 요청, 지연 요청, 재전송 요청”도 고려해야 한다.

8. 재고 조정과 실사

실제 재고는 시스템 재고와 항상 일치하지 않을 수 있다.

이유는 다양하다.

도난
파손
폐기 누락
입고 검수 오류
POS 처리 실수
수기 조정
네트워크 장애
점포 간 이동 오류

따라서 대규모 재고 시스템에서는 재고 실사와 조정 기능이 필요하다.

예를 들어 시스템상 재고는 10개인데 실제 매장에는 7개만 있다면, 관리자는 재고를 -3 조정해야 한다.

이때 단순히 InventoryBalance의 수량만 바꾸면 안 된다. 왜 조정했는지 기록해야 한다.

stock_movements
- movement_type = ADJUSTMENT_MINUS
- quantity_delta = -3
- reason = "실사 결과 재고 불일치"
- occurred_at = 2026-07-08 22:00

이렇게 기록하면 나중에 재고가 왜 줄었는지 추적할 수 있다.

MVP에서는 판매와 입고만 다뤘지만, 실제 운영에서는 조정과 실사가 매우 중요하다.

재고 시스템은 결국 현실 세계의 상품 수량을 소프트웨어로 표현하는 시스템이다. 현실 세계에서는 분실, 파손, 폐기, 실수 같은 일이 발생하기 때문에, 시스템도 이를 보정할 수 있는 구조를 가져야 한다.

9. 대규모 Inventory 테이블 구조 예시

지금까지의 내용을 바탕으로 대규모 Inventory 구조를 단순화해보면 다음과 같다.

products
- id
- name
- category
- status

stores
- id
- name
- region
- status

inventory_balances
- store_id
- product_id
- on_hand_quantity
- reserved_quantity
- available_quantity
- safety_stock
- version
- updated_at

stock_movements
- id
- store_id
- product_id
- movement_type
- quantity_delta
- source_type
- source_id
- idempotency_key
- occurred_at
- created_at

inventory_reservations
- id
- store_id
- product_id
- order_id
- quantity
- status
- expires_at
- created_at
- updated_at

customer_inventory_view
- store_id
- product_id
- availability_status
- display_quantity_range
- last_synced_at

inventory_snapshots
- store_id
- product_id
- snapshot_date
- opening_quantity
- closing_quantity

각 테이블의 역할은 다음과 같다.

MVP에서는 이 중 일부만 구현했다.

MVP 구현
- stores
- products
- inventories
- sales
- receipts
- order_recommendations

대규모로 확장한다면 다음과 같이 바꿀 수 있다.

inventories → inventory_balances
sales/receipts → stock_movements로 일반화
customer API → customer_inventory_view 또는 Redis 캐시 사용
reservation → 픽업/예약 주문 기능과 연결
order recommendation → stock_movements와 inventory_snapshots 기반 분석

이렇게 보면 현재 MVP는 대규모 구조의 축소판이라고 볼 수 있다.

10. MVP와 대규모 설계 비교

현재 MVP와 대규모 확장 구조를 비교하면 다음과 같다.

이 비교를 통해 MVP가 어떤 점을 단순화했고, 대규모 시스템에서는 어떤 부분을 보강해야 하는지 명확히 볼 수 있다.

중요한 것은 MVP가 부족하다는 뜻이 아니다.

MVP는 의도적으로 단순화한 구조다. 프로젝트의 목적은 대규모 운영 시스템을 완전히 재현하는 것이 아니라, 핵심 흐름을 이해하고 구현하는 것이었다.

다만 MVP 이후의 확장 방향을 고민함으로써, 내가 만든 구조의 한계와 발전 가능성을 함께 이해할 수 있었다.

11. 이번 고민을 통해 얻은 것

이 글을 정리하면서 Inventory 설계가 단순히 수량 컬럼 하나의 문제가 아니라는 것을 더 명확히 이해하게 되었다.

재고 시스템의 핵심은 다음 다섯 가지라고 생각한다.

1. 현재 재고를 빠르게 알 수 있어야 한다.
2. 재고가 왜 변했는지 추적할 수 있어야 한다.
3. 동시에 판매/예약이 들어와도 초과 판매가 발생하면 안 된다.
4. 고객 앱에는 빠르고 안전한 조회 결과를 제공해야 한다.
5. 장애나 중복 이벤트가 발생해도 원인을 추적하고 보정할 수 있어야 한다.

MVP에서는 Inventory를 단일 기준 데이터로 두고, Sale과 Receipt 이력을 통해 판매/입고 흐름을 추적했다.

하지만 대규모 시스템에서는 역할을 더 세분화할 필요가 있다.

StockMovement
→ 재고 변동의 이유와 이력

InventoryBalance
→ 현재 재고 상태

Reservation
→ 예약 또는 홀드된 재고

CustomerAvailabilityView
→ 고객 앱 조회용 가공 데이터

Cache/Search
→ 빠른 조회를 위한 파생 데이터

이 구조를 이해하면, 왜 실제 운영 시스템에서 단순 CRUD보다 데이터 정합성, 이벤트 처리, 캐시 무효화, 장애 복구가 중요한지 더 잘 보인다.

12. 포트폴리오에 어떻게 정리할 수 있을까

이 고민은 포트폴리오에서도 짧게 정리할 수 있다.

예를 들어 다음과 같이 쓸 수 있다.

MVP에서는 Inventory를 단일 기준 데이터로 두어 POS/PDA/고객/관리자 기능이 하나의 재고 흐름으로 연결되도록 구현했습니다. 다만 실제 대규모 운영 시스템에서는 판매, 입고, 폐기, 반품, 조정 등 다양한 재고 변동 사유를 추적해야 하므로 StockMovement 원장과 InventoryBalance를 분리하는 구조로 확장할 수 있다고 정리했습니다. 또한 예약 재고, 고객 조회용 AvailabilityView, Redis 캐시 무효화, 동시 판매 제어, idempotency key까지 고려하며 MVP 이후의 확장 방향을 고민했습니다.

이 문장은 내가 구현한 프로젝트의 범위를 솔직하게 인정하면서도, 실제 규모에서 고려해야 할 문제를 이해하고 있다는 점을 보여준다.

학습용 프로젝트에서 중요한 것은 “내가 실제 기업 시스템을 그대로 만들었다”가 아니다. 중요한 것은 작은 프로젝트를 통해 업무 흐름을 이해했고, 그 흐름이 커졌을 때 어떤 문제가 생길 수 있는지 고민해봤다는 점이다.

13. 정리

이번 글에서는 StoreOps Platform의 MVP Inventory 구조를 출발점으로, 확장형 Inventory 설계를 어떻게 확장할 수 있을지 고민해보았다.

핵심 내용은 다음과 같다.

1. MVP에서는 inventories.quantity를 단일 기준 데이터로 두었다.
2. POS 판매는 재고 감소와 Sale 이력 저장으로 처리했다.
3. PDA 입고는 재고 증가와 Receipt 이력 저장으로 처리했다.
4. 대규모 시스템에서는 재고 변동 사유가 많아지므로 StockMovement 원장이 필요할 수 있다.
5. 현재 재고를 빠르게 조회하기 위해 InventoryBalance를 둘 수 있다.
6. 픽업 예약이나 주문을 고려하면 Reservation과 reserved_quantity가 필요하다.
7. 고객 앱에는 정확한 수량보다 Availability 상태값을 제공하는 것이 더 안전할 수 있다.
8. 고객 조회 트래픽이 많아지면 CustomerAvailabilityView와 Redis 캐시를 활용할 수 있다.
9. 동시 판매를 막기 위해 조건부 UPDATE, 낙관적 락, 비관적 락을 고려할 수 있다.
10. 오프라인 POS나 재시도 상황을 위해 idempotency key가 필요할 수 있다.
11. 실사와 재고 조정을 위해 모든 변동은 원장에 남기는 것이 좋다.

결국 대규모 Inventory 설계의 핵심은 단순히 수량을 저장하는 것이 아니다.

현재 재고를 빠르게 보여주는 것
재고 변경 이유를 추적하는 것
초과 판매를 막는 것
고객에게 안전한 조회 결과를 제공하는 것
장애나 중복 이벤트에도 복구 가능한 구조를 만드는 것

이 모든 것을 함께 고려해야 한다.

내가 만든 MVP는 이 구조의 가장 작은 버전이다.

Inventory = 현재 재고
Sale = 판매로 인한 재고 감소 이력
Receipt = 입고로 인한 재고 증가 이력
Customer API = 고객 조회
Admin API = 운영 조회

이번 프로젝트를 통해 재고 시스템의 기본 흐름을 구현했고, 이번 글을 통해 그 구조가 대규모 시스템에서는 어떻게 확장될 수 있을지 고민해볼 수 있었다.

앞으로 프로젝트를 더 발전시킨다면 가장 먼저 적용해보고 싶은 것은 다음 세 가지다.

1. Sale/Receipt를 StockMovement로 일반화하기
2. Inventory에 @Version을 적용해 낙관적 락 실험하기
3. 고객 재고조회용 CustomerAvailabilityView와 캐시 무효화 전략 설계하기

이 세 가지를 추가하면 현재 MVP는 단순 재고 CRUD를 넘어, 실제 운영 시스템의 고민을 더 많이 담은 프로젝트로 발전할 수 있을 것이다.

시리즈 이어보기
이전 글: 3. 재고 정합성을 위한 POS 판매·PDA 입고 트랜잭션 구현 | 전체 글 목록

StoreOps Platform 시리즈

• 1편: 프로젝트 배경
• 2편: 도메인 설계
• 3편: 재고 트랜잭션
• 4편: 대규모 Inventory 확장
• 전체 글 목록

1. 이번 글에서 다룰 내용

이전 글에서는 StoreOps Platform의 도메인 모델을 설계하면서, 이 프로젝트의 중심 도메인을 Inventory, 즉 점포별 상품 재고로 잡은 이유를 정리했다.

이번 글에서는 그 다음 단계로, 실제 재고가 변경되는 두 가지 핵심 흐름을 구현하면서 고민한 내용을 정리하려고 한다.

두 가지 핵심 흐름은 다음과 같다.

POS 판매 처리 → 재고 감소
PDA 입고 처리 → 재고 증가

처음 보기에는 단순히 숫자를 빼고 더하는 기능처럼 보일 수 있다. 하지만 편의점 운영 시스템에서 재고는 고객 앱, POS, PDA, 관리자 화면, 발주 추천이 모두 의존하는 핵심 데이터다.

따라서 재고 변경 로직을 단순한 수량 변경으로만 보면 안 된다고 판단했다.

이번 구현에서 가장 중요하게 본 질문은 다음과 같았다.

판매 이력은 저장됐는데 재고가 줄지 않으면 어떻게 될까?
재고는 줄었는데 판매 이력이 저장되지 않으면 어떻게 될까?
입고 이력은 저장됐는데 재고가 늘지 않으면 어떻게 될까?
재고가 음수가 되는 상황은 어디에서 막아야 할까?

이 질문들을 해결하기 위해 POS 판매와 PDA 입고 처리를 각각 하나의 트랜잭션으로 묶고, 재고 증감 규칙은 Inventory 도메인 객체 내부에 두는 방식으로 구현했다.

2. POS 판매와 PDA 입고가 중요한 이유

StoreOps Platform은 개념적으로 네 종류의 클라이언트를 가진다.

POS
PDA
고객 앱
관리자 WEB

이 중 POS와 PDA는 재고 데이터를 직접 변경하는 클라이언트다.

POS는 고객이 상품을 구매했을 때 판매 이벤트를 발생시킨다. 이때 해당 점포의 상품 재고는 줄어야 한다.

PDA는 물류 입고가 발생했을 때 입고 이벤트를 발생시킨다. 이때 해당 점포의 상품 재고는 늘어야 한다.

반면 고객 앱과 관리자 WEB은 재고 데이터를 조회하는 쪽에 가깝다.

POS 판매 → Inventory 감소
PDA 입고 → Inventory 증가
고객 앱 → Inventory 조회
관리자 WEB → Inventory 조회

따라서 POS와 PDA에서 발생한 재고 변경이 정확하지 않으면, 고객 앱과 관리자 화면도 잘못된 정보를 보여주게 된다.

예를 들어 고객 앱에서 재고가 있다고 표시되었지만 실제 점포에는 재고가 없다면 고객은 헛걸음을 하게 된다. 반대로 실제 점포에는 상품이 있는데 앱에는 품절로 표시된다면 판매 기회를 잃게 된다.

이런 이유로 POS 판매와 PDA 입고는 이 프로젝트에서 단순 기능이 아니라, 전체 시스템의 신뢰도를 결정하는 핵심 흐름이라고 판단했다.

3. 재고 정합성이 깨지는 상황

먼저 재고 정합성이 깨질 수 있는 상황을 정리했다.

3.1 재고는 줄었는데 판매 이력이 저장되지 않는 경우

POS 판매 처리에서 재고 차감은 성공했지만 판매 이력 저장에 실패하는 상황을 생각해볼 수 있다.

현재 재고: 10개
판매 요청: 2개
재고 차감 성공: 8개
판매 이력 저장 실패

이 경우 시스템에는 재고가 8개로 줄어든 결과만 남고, 왜 재고가 줄었는지 추적할 수 없다.

운영 중 관리자가 “왜 이 상품의 재고가 줄었는가?”를 확인하려고 할 때 판매 이력이 없다면 원인 파악이 어렵다.

3.2 판매 이력은 저장됐는데 재고가 줄지 않는 경우

반대로 판매 이력은 저장됐지만 재고 차감이 실패하는 경우도 문제가 된다.

현재 재고: 10개
판매 요청: 2개
판매 이력 저장 성공
재고 차감 실패
현재 재고: 여전히 10개

이 경우 판매 데이터상으로는 상품이 팔렸지만, 재고는 줄지 않는다.

그러면 고객 앱에서는 실제보다 많은 재고가 표시될 수 있고, 관리자 화면에서도 잘못된 재고 현황을 보게 된다.

3.3 입고 이력은 저장됐는데 재고가 늘지 않는 경우

PDA 입고 처리에서도 비슷한 문제가 발생할 수 있다.

현재 재고: 8개
입고 요청: 20개
입고 이력 저장 성공
재고 증가 실패
현재 재고: 여전히 8개

이 경우 실제로는 입고가 처리되었지만 시스템 재고에는 반영되지 않는다.

관리자 입장에서는 물류가 들어왔는데 재고가 늘지 않은 것처럼 보이고, 고객 앱에서도 재고 없음으로 표시될 수 있다.

3.4 재고가 음수가 되는 경우

가장 기본적이지만 중요한 문제는 재고가 음수가 되는 상황이다.

예를 들어 현재 재고가 1개인데 POS에서 2개 판매 요청이 들어오면, 시스템은 이 요청을 거부해야 한다.

현재 재고: 1개
판매 요청: 2개
결과: 판매 실패

만약 단순히 현재 재고 - 판매 수량으로 처리하면 재고가 -1개가 될 수 있다.

실제 운영 시스템에서 재고가 음수로 내려가는 것은 이후 고객 재고조회, 발주 추천, 관리자 재고 현황에 모두 영향을 줄 수 있다.

따라서 재고 음수 방지는 반드시 도메인 규칙으로 관리해야 한다고 판단했다.

4. 트랜잭션으로 묶어야 하는 이유

위 문제들의 공통점은 “함께 성공해야 하는 작업이 따로 처리되었을 때” 발생한다는 것이다.

POS 판매 처리는 다음 두 작업이 함께 성공해야 한다.

1. 재고 차감
2. 판매 이력 저장

PDA 입고 처리는 다음 두 작업이 함께 성공해야 한다.

1. 재고 증가
2. 입고 이력 저장

둘 중 하나만 성공하면 데이터 불일치가 발생한다.

그래서 POS 판매와 PDA 입고는 각각 하나의 트랜잭션으로 처리해야 한다고 판단했다.

Spring에서는 Service 계층의 메서드에 @Transactional을 적용해 하나의 작업 단위로 묶을 수 있다. 트랜잭션 안에서 예외가 발생하면, 그 안에서 수행된 DB 변경 작업이 롤백된다.

이 프로젝트에서는 다음 기준으로 트랜잭션 경계를 잡았다.

POS 판매 API 1회 호출 = 하나의 트랜잭션
PDA 입고 API 1회 호출 = 하나의 트랜잭션

즉, 판매 요청이 들어오면 재고 차감과 판매 이력 저장이 함께 성공하거나 함께 실패해야 한다. 입고 요청도 마찬가지로 재고 증가와 입고 이력 저장이 함께 성공하거나 함께 실패해야 한다.

5. Inventory에 재고 증감 규칙을 둔 이유

재고 차감 로직을 구현할 때 또 하나 고민한 부분은 “재고 증감 규칙을 어디에 둘 것인가”였다.

가장 단순한 방식은 Service에서 직접 수량을 수정하는 것이다.

inventory.setQuantity(inventory.getQuantity() - request.quantity());

하지만 이 방식은 좋지 않다고 판단했다.

이유는 재고가 음수가 되면 안 된다는 규칙이 Service마다 흩어질 수 있기 때문이다. POS 판매 Service에서도 검사해야 하고, 나중에 재고 조정 기능이 생기면 또 다른 Service에서도 검사해야 한다.

재고 수량은 Inventory의 상태이고, 재고가 음수가 되면 안 된다는 규칙 역시 Inventory의 핵심 규칙이다.

그래서 재고 증감은 Inventory 도메인 객체 내부의 메서드로 처리하기로 했다.

@Getter
@Entity
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@Table(
        name = "inventories",
        uniqueConstraints = {
                @UniqueConstraint(
                        name = "uk_inventory_store_product",
                        columnNames = {"store_id", "product_id"}
                )
        }
)
public class Inventory {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "store_id", nullable = false)
    private Store store;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "product_id", nullable = false)
    private Product product;

    @Column(nullable = false)
    private Integer quantity;

    public Inventory(Store store, Product product, Integer quantity) {
        validateInitialQuantity(quantity);
        this.store = store;
        this.product = product;
        this.quantity = quantity;
    }

    public void decrease(int quantity) {
        validatePositiveQuantity(quantity);

        if (this.quantity < quantity) {
            throw new BusinessException(ErrorCode.INSUFFICIENT_STOCK);
        }

        this.quantity -= quantity;
    }

    public void increase(int quantity) {
        validatePositiveQuantity(quantity);
        this.quantity += quantity;
    }

    private void validatePositiveQuantity(Integer quantity) {
        if (quantity == null || quantity <= 0) {
            throw new BusinessException(ErrorCode.INVALID_QUANTITY);
        }
    }

    private void validateInitialQuantity(Integer quantity) {
        if (quantity == null || quantity < 0) {
            throw new BusinessException(ErrorCode.INVALID_INITIAL_QUANTITY);
        }
    }
}

이렇게 설계하면 Service는 “판매 흐름”이나 “입고 흐름”을 조율하고, Inventory는 “재고가 어떻게 변경될 수 있는지”를 책임진다.

즉, 역할이 다음과 같이 나뉜다.

Service → 유스케이스 흐름 조율
Inventory → 재고 변경 규칙 관리
Repository → 데이터 조회와 저장

이 구조가 작은 프로젝트에서도 더 명확하다고 판단했다.

6. POS 판매 처리 구현

POS 판매 API의 처리 흐름은 다음과 같다.

1. 판매 요청 수신
2. 점포 조회
3. 상품 조회
4. 점포별 상품 재고 조회
5. 재고 차감
6. 판매 이력 저장
7. 남은 재고와 판매 결과 응답

Service 코드는 다음과 같은 형태로 구현했다.

@Slf4j
@Service
@RequiredArgsConstructor
public class PosSaleService {

    private final InventoryRepository inventoryRepository;
    private final SaleRepository saleRepository;

    @Transactional
    public PosSaleResponse sell(PosSaleRequest request) {
        Inventory inventory = inventoryRepository.findByStoreIdAndProductId(
                        request.storeId(),
                        request.productId()
                )
                .orElseThrow(() -> new BusinessException(
                        ErrorCode.INVENTORY_NOT_FOUND,
                        "해당 점포에 등록된 상품 재고가 없습니다. storeId="
                                + request.storeId()
                                + ", productId="
                                + request.productId()
                ));

        inventory.decrease(request.quantity());

        Sale sale = new Sale(
                inventory.getStore(),
                inventory.getProduct(),
                request.quantity()
        );
        Sale savedSale = saleRepository.save(sale);

        log.info("[POS_SALE] storeId={} productId={} quantity={} remainingStock={}",
                request.storeId(),
                request.productId(),
                request.quantity(),
                inventory.getQuantity()
        );

        return PosSaleResponse.of(savedSale, inventory);
    }
}

여기서 중요한 부분은 두 가지다.

첫째, @Transactional을 적용했다.

@Transactional
public PosSaleResponse sell(PosSaleRequest request) {
    ...
}

둘째, Service에서 직접 수량을 빼지 않고 inventory.decrease()를 호출했다.

inventory.decrease(request.quantity());

이렇게 하면 판매 수량이 잘못되었거나 재고가 부족한 경우 Inventory 내부에서 예외가 발생하고, 트랜잭션은 롤백된다.

즉, 판매 이력이 저장되기 전에 재고 검증이 실패하면 판매 이력도 저장되지 않는다.

7. PDA 입고 처리 구현

PDA 입고 API의 처리 흐름은 다음과 같다.

1. 입고 요청 수신
2. 점포 조회
3. 상품 조회
4. 점포별 상품 재고 조회
5. 재고 증가
6. 입고 이력 저장
7. 현재 재고와 입고 결과 응답

Service 코드는 다음과 같은 형태로 구현했다.

@Slf4j
@Service
@RequiredArgsConstructor
public class PdaReceiptService {

    private final StoreRepository storeRepository;
    private final ProductRepository productRepository;
    private final InventoryRepository inventoryRepository;
    private final ReceiptRepository receiptRepository;

    @Transactional
    public PdaReceiptResponse receive(PdaReceiptRequest request) {
        Store store = storeRepository.findById(request.storeId())
                .orElseThrow(() -> new BusinessException(ErrorCode.STORE_NOT_FOUND));

        Product product = productRepository.findById(request.productId())
                .orElseThrow(() -> new BusinessException(ErrorCode.PRODUCT_NOT_FOUND));

        Inventory inventory = inventoryRepository.findByStoreIdAndProductId(
                        request.storeId(),
                        request.productId()
                )
                .orElseGet(() -> new Inventory(store, product, 0));

        inventory.increase(request.quantity());
        Inventory savedInventory = inventoryRepository.save(inventory);

        Receipt receipt = new Receipt(
                store,
                product,
                request.quantity()
        );
        Receipt savedReceipt = receiptRepository.save(receipt);

        log.info("[PDA_RECEIPT] storeId={} productId={} quantity={} currentStock={}",
                request.storeId(),
                request.productId(),
                request.quantity(),
                savedInventory.getQuantity()
        );

        return PdaReceiptResponse.of(savedReceipt, savedInventory);
    }
}

PDA 입고에서는 POS 판매와 달리, 해당 점포에 아직 상품 재고가 없을 수도 있다고 보았다.

예를 들어 신규 상품이 처음 입고되는 경우라면 Inventory가 존재하지 않을 수 있다. 이 경우에는 초기 수량 0의 Inventory를 생성한 뒤 입고 수량만큼 증가시키도록 했다.

Inventory inventory = inventoryRepository.findByStoreIdAndProductId(
                request.storeId(),
                request.productId()
        )
        .orElseGet(() -> new Inventory(store, product, 0));

이후 재고 증가는 Inventory의 increase() 메서드로 처리했다.

inventory.increase(request.quantity());

입고 처리 역시 @Transactional 안에서 수행되므로, 입고 이력 저장이나 재고 증가 중 하나가 실패하면 전체 작업이 롤백된다.

8. 판매 이력과 입고 이력을 남기는 이유

재고만 정확하면 되는 것처럼 보일 수 있지만, 운영 관점에서는 “재고가 왜 변했는지”도 중요하다.

현재 재고만 저장하면 다음과 같은 질문에 답하기 어렵다.

왜 재고가 30개에서 8개로 줄었는가?
오늘 입고가 정상적으로 반영되었는가?
특정 상품의 판매량은 어느 정도인가?
발주 추천은 어떤 판매 데이터를 기준으로 계산되었는가?

그래서 이번 프로젝트에서는 현재 재고는 Inventory에 저장하고, 재고가 변한 이유는 Sale과 Receipt 이력으로 남겼다.

Inventory → 현재 재고 상태
Sale → POS 판매로 인한 재고 감소 이력
Receipt → PDA 입고로 인한 재고 증가 이력

이 구조는 발주 추천 기능을 구현할 때도 필요하다.

발주 추천은 최근 판매량을 기반으로 계산할 예정이기 때문에, Sale 이력이 있어야 최근 7일 평균 판매량을 구할 수 있다.

즉, 판매 이력은 단순 기록이 아니라 이후 관리자 운영 기능의 기반 데이터가 된다.

9. 테스트 코드로 검증한 것

재고 변경 로직은 고객 재고조회와 발주 추천의 기반이 되기 때문에 테스트 코드로 검증할 필요가 있다고 판단했다.

이번 단계에서 최소한으로 검증해야 할 테스트는 다음과 같다.

1. POS 판매 성공 시 재고가 감소한다.
2. 재고보다 많은 수량을 판매하려 하면 예외가 발생한다.
3. 판매 실패 시 재고는 기존 수량으로 유지된다.
4. PDA 입고 성공 시 재고가 증가한다.
5. 잘못된 입고 수량은 예외가 발생한다.

예를 들어 POS 판매 성공 테스트는 다음과 같이 작성할 수 있다.

@Test
void sellDecreasesInventoryQuantityAndSavesSale() {
    Store store = storeRepository.save(new Store(
            "서초점",
            "서울 서초구",
            StoreStatus.OPEN
    ));
    Product product = productRepository.save(new Product(
            "참치마요 삼각김밥",
            ProductCategory.FOOD,
            1200,
            ProductStatus.ON_SALE
    ));
    inventoryRepository.save(new Inventory(store, product, 10));
    PosSaleRequest request = new PosSaleRequest(store.getId(), product.getId(), 2);

    PosSaleResponse response = posSaleService.sell(request);

    assertThat(response.saleId()).isNotNull();
    assertThat(response.soldQuantity()).isEqualTo(2);
    assertThat(response.remainingQuantity()).isEqualTo(8);
    assertThat(saleRepository.count()).isEqualTo(1);
}

재고 부족 테스트는 다음과 같이 작성할 수 있다.

@Test
void sellFailsWhenStockIsInsufficient() {
    Store store = storeRepository.save(new Store(
            "서초점",
            "서울 서초구",
            StoreStatus.OPEN
    ));
    Product product = productRepository.save(new Product(
            "참치마요 삼각김밥",
            ProductCategory.FOOD,
            1200,
            ProductStatus.ON_SALE
    ));
    inventoryRepository.save(new Inventory(store, product, 1));
    PosSaleRequest request = new PosSaleRequest(store.getId(), product.getId(), 2);

    assertThatThrownBy(() -> posSaleService.sell(request))
            .isInstanceOf(BusinessException.class)
            .hasMessage("재고가 부족합니다.");
    assertThat(saleRepository.count()).isZero();
}

입고 성공 테스트는 다음과 같이 작성할 수 있다.

@Test
void receiveIncreasesExistingInventoryQuantityAndSavesReceipt() {
    Store store = storeRepository.save(new Store("서초점", "서울 서초구", StoreStatus.OPEN));
    Product product = productRepository.save(new Product(
            "참치마요 삼각김밥",
            ProductCategory.FOOD,
            1200,
            ProductStatus.ON_SALE
    ));
    inventoryRepository.save(new Inventory(store, product, 8));
    PdaReceiptRequest request = new PdaReceiptRequest(store.getId(), product.getId(), 20);

    PdaReceiptResponse response = pdaReceiptService.receive(request);

    assertThat(response.receiptId()).isNotNull();
    assertThat(response.receivedQuantity()).isEqualTo(20);
    assertThat(response.currentQuantity()).isEqualTo(28);
    assertThat(receiptRepository.count()).isEqualTo(1);
}

이 테스트들은 단순히 코드가 동작하는지 확인하는 수준을 넘어서, 이 프로젝트에서 가장 중요한 도메인 규칙을 검증한다.

재고는 음수가 되면 안 된다.
판매되면 재고가 줄어야 한다.
입고되면 재고가 늘어야 한다.
실패한 판매는 재고에 영향을 주면 안 된다.

10. 동시 판매 문제는 어떻게 볼 것인가

이번 단계에서는 기본적인 트랜잭션과 재고 음수 방지를 우선 구현했다. 하지만 실제 운영 시스템이라면 동시 판매 문제도 고려해야 한다.

예를 들어 현재 재고가 1개 남았을 때, POS 두 대에서 동시에 같은 상품을 1개씩 판매 요청하는 상황을 생각해볼 수 있다.

현재 재고: 1개

요청 A: 1개 판매
요청 B: 1개 판매

두 요청이 동시에 현재 재고 1개를 조회하고 모두 판매 가능하다고 판단하면 재고 정합성이 깨질 수 있다.

이 문제를 해결하기 위한 선택지는 여러 가지다.

1. 낙관적 락을 적용한다.
2. 비관적 락을 적용한다.
3. Redis 분산락을 적용한다.
4. 재고 변경 이벤트를 큐로 직렬화한다.

이번 MVP에서는 프로젝트 범위와 기간을 고려해 동시성 제어까지 구현 범위에 포함하지는 않았다. 대신 재고 변경 로직을 Inventory 도메인에 모으고, POS 판매와 PDA 입고를 트랜잭션으로 묶는 것을 우선순위로 두었다.

추후 개선한다면 Inventory에 @Version을 추가해 낙관적 락을 적용하는 방식을 먼저 검토할 수 있다.

@Version
private Long version;

이 방식은 동시에 같은 Inventory를 수정할 때 버전 충돌을 감지할 수 있어, 과판매 문제를 줄이는 데 도움이 될 수 있다.

이번 프로젝트에서는 동시성 제어를 완성 구현하지는 않았지만, POS 판매가 많은 환경에서는 반드시 고려해야 할 문제임을 설계 기록에 남기기로 했다.

11. 이번 구현에서 얻은 설계 기준

POS 판매와 PDA 입고를 구현하면서, 단순히 API를 만드는 것보다 다음 기준이 더 중요하다는 것을 정리할 수 있었다.

1. 재고는 여러 클라이언트가 공유하는 기준 데이터다.
2. 재고 변경과 이력 저장은 함께 성공하거나 함께 실패해야 한다.
3. 재고 음수 방지는 Inventory 도메인 자체의 규칙이다.
4. 판매/입고 이력은 운영 중 원인 추적과 발주 추천의 기반 데이터다.
5. 작은 프로젝트라도 트랜잭션 경계를 명확히 잡으면 운영 시스템에 가까운 설계를 할 수 있다.

이 기준을 바탕으로 앞으로 고객 재고조회와 관리자 발주 추천 기능을 구현할 수 있다.

고객 재고조회는 Inventory를 조회하고, 관리자 발주 추천은 Inventory와 Sale 이력을 함께 사용하게 된다.

즉, 이번 단계에서 구현한 POS/PDA 흐름은 이후 기능의 기반이 된다.

12. 정리

이번 글에서는 StoreOps Platform에서 POS 판매와 PDA 입고를 구현하면서, 재고 데이터 정합성을 어떻게 지키려고 했는지 정리했다.

핵심은 다음과 같다.

POS 판매 처리
→ 재고 차감 + 판매 이력 저장을 하나의 트랜잭션으로 처리

PDA 입고 처리
→ 재고 증가 + 입고 이력 저장을 하나의 트랜잭션으로 처리

Inventory 도메인
→ decrease(), increase() 메서드로 재고 증감 규칙 관리

테스트 코드
→ 판매 성공, 재고 부족 실패, 입고 성공 검증

이번 구현에서 가장 중요하게 생각한 점은, 재고 변경이 단순 숫자 변경이 아니라는 것이다.

편의점 운영 시스템에서 재고는 고객 앱, POS, PDA, 관리자 WEB을 연결하는 핵심 데이터다. 따라서 재고가 잘못 변경되면 고객 경험과 점포 운영 모두에 영향을 줄 수 있다.

그래서 판매와 입고를 구현할 때도 “일단 동작하는 API”가 아니라, 데이터 정합성과 운영 추적 가능성을 우선으로 고려했다.

다음 글에서는 이 재고 데이터를 기반으로 고객이 상품별 점포 재고를 조회하는 기능과, 관리자가 결품 위험 및 발주 추천을 확인하는 기능을 구현한 과정을 정리할 예정이다.

시리즈 이어보기
이전 글: 2. POS/PDA/고객 앱/관리자 WEB을 잇는 도메인 설계 | 전체 글 목록 | 다음 글: 4. MVP 재고 시스템을 확장 가능한 Inventory 구조로 발전시켜보기

StoreOps Platform 시리즈

• 1편: 프로젝트 배경
• 2편: 도메인 설계
• 3편: 재고 트랜잭션
• 4편: 대규모 Inventory 확장
• 전체 글 목록

1. 설계를 시작하며

이전 글에서는 편의점 운영 시스템를 분석하고, 그에 맞춰 StoreOps Platform이라는 프로젝트를 기획한 이유를 정리했다.

이번 글에서는 본격적인 구현에 들어가기 전, 편의점 운영 흐름을 어떻게 도메인 모델로 바꿨는지 정리하려고 한다.

처음에는 단순히 다음과 같은 API를 만들면 된다고 생각했다.

상품 등록 API
점포 등록 API
재고 조회 API
판매 처리 API
입고 처리 API

하지만 이렇게 API 목록부터 나열하면 프로젝트가 단순 CRUD에 가까워질 수 있다. 내가 이 프로젝트에서 보여주고 싶은 것은 API 개수 자체가 아니라, 편의점 운영에서 어떤 데이터가 중심이 되고, 여러 시스템이 그 데이터를 어떻게 공유하는지 이해했다는 점이었다.

그래서 먼저 편의점 운영 흐름을 단순화하고, 그 흐름을 도메인 모델로 옮기는 방식으로 설계를 시작했다.

이번 프로젝트에서 가장 중요하게 본 질문은 다음과 같았다.

POS에서 상품이 팔리면 어떤 데이터가 바뀌어야 할까?
PDA로 입고가 처리되면 어떤 데이터가 증가해야 할까?
고객이 앱에서 보는 재고는 어디에서 조회되어야 할까?
점주나 관리자는 어떤 데이터를 보고 발주를 판단할까?

이 질문들을 따라가다 보니, 결국 프로젝트의 중심에는 Inventory, 즉 점포별 상품 재고가 있어야 한다고 판단했다.

2. 편의점 운영 흐름 단순화하기

실제 편의점 운영은 매우 복잡하다. 상품 발주, 물류센터, 입고, 검수, 진열, 판매, 폐기, 정산, 회계, 프로모션, 멤버십, 모바일 앱, 배달/픽업 등 다양한 업무가 연결되어 있다.

하지만 학습용 미니 프로젝트에서 모든 흐름을 구현할 수는 없다. 따라서 이번 프로젝트에서는 편의점 운영과 가장 직접적으로 연결될 수 있는 흐름만 추렸다.

내가 단순화한 편의점 운영 흐름은 다음과 같다.

상품 등록
→ 점포 등록
→ 점포별 재고 등록
→ PDA 입고 처리
→ POS 판매 처리
→ 고객 재고조회
→ 관리자 재고 확인
→ 결품 위험 판단
→ 발주 추천

이 흐름을 프로젝트 관점에서 다시 표현하면 다음과 같다.

PDA 입고 → Inventory 증가
POS 판매 → Inventory 감소
고객 앱 → Inventory 조회
관리자 WEB → Inventory 조회 + Sale 이력 기반 분석
발주 추천 → Inventory + Sale 이력 기반 계산

이 구조에서 중요한 점은 POS, PDA, 고객 앱, 관리자 WEB이 서로 다른 클라이언트지만, 결국 모두 Inventory라는 같은 데이터를 중심으로 동작한다는 것이다.

3. 핵심 도메인 도출하기

사용자와 운영 흐름을 정리한 뒤, 핵심 도메인을 도출했다.

이번 프로젝트의 주요 도메인은 다음 여섯 가지다.

Store
Product
Inventory
Sale
Receipt
OrderRecommendation

각 도메인의 역할은 다음과 같다.

이 중 가장 중요한 도메인은 Inventory다.

Store와 Product는 기본 정보에 가깝다. Sale과 Receipt는 재고가 변화한 이유를 기록하는 이력 데이터다. OrderRecommendation은 Inventory와 Sale 데이터를 바탕으로 계산되는 결과다.

반면 Inventory는 고객 재고조회, POS 판매, PDA 입고, 관리자 조회, 발주 추천이 모두 의존하는 중심 데이터다.

그래서 이번 프로젝트의 도메인 모델은 Inventory를 중심으로 구성했다.

4. 현재 재고와 이력 데이터를 함께 둔 이유

재고 시스템을 설계하면서 또 하나 고민한 부분은 “현재 재고만 저장할 것인가, 판매/입고 이력도 함께 저장할 것인가”였다.

선택지는 다음과 같았다.

1. Inventory에 현재 재고만 저장한다.
2. Inventory와 Sale 이력만 저장한다.
3. Inventory, Sale, Receipt 이력을 모두 저장한다.
4. 모든 재고 변동을 StockMovement라는 하나의 이력 테이블로 관리한다.

가장 단순한 방식은 1번이다. Inventory에 현재 재고 수량만 저장하면 고객 재고조회와 관리자 재고조회는 구현할 수 있다.

하지만 이 방식은 재고가 왜 변했는지 알기 어렵다.

예를 들어 재고가 30개에서 8개로 줄었다면, 그것이 실제 판매 때문인지, 데이터 오류 때문인지, 폐기 때문인지 추적하기 어렵다.

그래서 이번 프로젝트에서는 3번을 선택했다.

Inventory → 현재 재고 상태
Sale → POS 판매 이력
Receipt → PDA 입고 이력

이렇게 나누면 현재 재고를 빠르게 조회할 수 있고, 동시에 재고가 변한 이유도 추적할 수 있다.

완전한 재고 원장 방식으로 가려면 StockMovement 같은 통합 이력 모델을 두는 것이 더 적절할 수 있다. 예를 들어 판매, 입고, 폐기, 조정 등 모든 변동을 하나의 테이블에 기록하는 방식이다.

하지만 이번 프로젝트의 MVP 범위에서는 POS 판매와 PDA 입고가 핵심이므로, Sale과 Receipt를 분리해 명확하게 표현하는 방식을 선택했다.

이 결정은 개발운영 관점에서도 의미가 있다. 운영 중 재고가 예상과 다르게 변했을 때, 판매 이력과 입고 이력을 통해 원인을 추적할 수 있기 때문이다.

5. 도메인 관계 설계

이번 프로젝트의 기본 관계는 다음과 같다.

Store 1 ─ N Inventory
Product 1 ─ N Inventory

Store 1 ─ N Sale
Product 1 ─ N Sale

Store 1 ─ N Receipt
Product 1 ─ N Receipt

Store 1 ─ N OrderRecommendation
Product 1 ─ N OrderRecommendation

하나의 점포는 여러 상품 재고를 가질 수 있고, 하나의 상품은 여러 점포에 존재할 수 있다.

예를 들어 참치마요 삼각김밥이라는 상품은 한양대점, 왕십리점, 서울숲점에 모두 존재할 수 있다. 하지만 각 점포의 재고 수량은 다르다.

그래서 Store와 Product 사이의 관계를 Inventory라는 도메인으로 풀었다.

여기서 중요한 규칙이 하나 있다.

하나의 점포에는 같은 상품의 재고가 중복으로 존재하면 안 된다.

즉, store_id와 product_id의 조합은 유일해야 한다.

그래서 Inventory 테이블에는 다음과 같은 유니크 제약을 두었다.

unique(store_id, product_id)

이 제약을 두면 한양대점 + 참치마요 삼각김밥 재고가 중복으로 생성되는 문제를 막을 수 있다.

6. 도메인 규칙 정리

도메인을 설계하면서 함께 정리한 핵심 규칙은 다음과 같다.

6.1 Inventory 규칙

재고 수량은 0 이상이어야 한다.
판매 시 재고는 판매 수량만큼 감소한다.
입고 시 재고는 입고 수량만큼 증가한다.
판매 수량이 현재 재고보다 크면 판매할 수 없다.
같은 점포와 같은 상품의 재고는 중복 생성될 수 없다.

이 규칙은 Inventory 도메인 안에서 최대한 관리하려고 했다.

예를 들어 재고 감소는 단순히 Service에서 quantity 값을 직접 빼는 것이 아니라, Inventory.decrease() 같은 메서드로 처리하도록 설계했다.

public void decrease(int quantity) {
    validatePositiveQuantity(quantity);

    if (this.quantity < quantity) {
        throw new BusinessException(ErrorCode.INSUFFICIENT_STOCK);
    }

    this.quantity -= quantity;
}

이렇게 하면 재고 음수 방지라는 규칙이 여러 Service에 흩어지지 않고 Inventory 안에 모일 수 있다.

6.2 Sale 규칙

판매 수량은 1 이상이어야 한다.
판매 처리는 반드시 재고 차감과 함께 이루어져야 한다.
판매 이력은 재고가 줄어든 이유를 추적하기 위해 저장한다.

POS 판매 처리에서는 판매 이력 저장과 재고 차감이 하나의 트랜잭션으로 처리되어야 한다. 둘 중 하나만 성공하면 운영 중 재고 정합성이 깨질 수 있기 때문이다.

6.3 Receipt 규칙

입고 수량은 1 이상이어야 한다.
입고 처리는 반드시 재고 증가와 함께 이루어져야 한다.
입고 이력은 재고가 늘어난 이유를 추적하기 위해 저장한다.

PDA 입고도 POS 판매와 마찬가지로 트랜잭션 처리가 중요하다.

입고 이력만 저장되고 재고가 증가하지 않거나, 재고만 증가하고 입고 이력이 남지 않으면 운영 중 원인을 추적하기 어려워질 수 있다.

6.4 OrderRecommendation 규칙

발주 추천은 최근 판매량과 현재 재고를 기반으로 계산한다.

MVP에서는 다음과 같은 단순 규칙을 사용했다.

최근 7일 평균 판매량 = avgDailySales
목표 재고 = avgDailySales * 3
안전 재고 = avgDailySales * 2
추천 발주량 = max(0, 목표 재고 + 안전 재고 - 현재 재고)

처음부터 AI 기반 수요 예측을 적용하지 않은 이유는, 이번 프로젝트의 목표가 예측 모델의 정확도 자체가 아니기 때문이다.

이 프로젝트에서 보여주고 싶은 것은 POS 판매 이력이 현재 재고와 결합되어 발주 의사결정으로 이어지는 운영 흐름이다. 따라서 설명 가능하고 테스트하기 쉬운 규칙 기반 로직을 우선 적용했다.

7. 대규모 운영 시스템으로 확장한다면

이번 프로젝트는 학습용 미니 프로젝트이기 때문에 범위를 작게 잡았다. 하지만 실제 대규모 운영 시스템이라면 추가로 고민해야 할 지점이 많다.

예를 들어 재고 변동을 Sale과 Receipt로만 나누는 방식은 MVP에서는 명확하지만, 실제 운영에서는 폐기, 조정, 반품, 이동, 행사 재고 등 더 다양한 변동 사유가 생길 수 있다.

이 경우에는 StockMovement 같은 재고 원장 모델을 두고, 모든 재고 변동을 하나의 기준으로 기록하는 방식이 더 적절할 수 있다.

또한 POS 판매가 동시에 많이 발생하는 환경에서는 동시성 제어도 필요하다. 같은 상품의 재고가 1개 남았는데 두 POS에서 동시에 판매 요청이 들어오는 상황을 고려해야 하기 때문이다.

이번 프로젝트에서는 우선순위를 고려해 재고 원장과 동시성 제어까지 완성 구현하지는 않았다. 대신 현재 범위 안에서 재고 정합성, 이력 추적, 도메인 규칙을 명확히 잡는 데 집중했다.

8. 정리

이번 글에서는 StoreOps Platform의 도메인 설계 과정을 정리했다.

핵심은 다음과 같다.

편의점 운영 흐름을 Inventory 중심으로 단순화했다.
현재 재고는 Inventory에 저장하고, 변화 이유는 Sale과 Receipt 이력으로 남겼다.
Store와 Product의 관계는 Inventory로 연결했다.
재고 음수 방지와 재고 증감 규칙은 Inventory 도메인 안에 두었다.
발주 추천은 Inventory와 Sale 이력을 기반으로 계산하도록 설계했다.

다음 글에서는 이 설계를 바탕으로 POS 판매와 PDA 입고를 구현하면서, 재고 데이터 정합성을 어떻게 지키려고 했는지 정리할 예정이다.

시리즈 이어보기
이전 글: 1. 편의점 운영 시스템 프로젝트를 시작한 이유 | 전체 글 목록 | 다음 글: 3. 재고 정합성을 위한 POS 판매·PDA 입고 트랜잭션 구현

StoreOps Platform 시리즈

• 1편: 프로젝트 배경
• 2편: 도메인 설계
• 3편: 재고 트랜잭션
• 4편: 대규모 Inventory 확장
• 전체 글 목록

1. 왜 이 프로젝트를 시작했는가

편의점 운영 시스템을 주제로 백엔드 프로젝트를 정리하면서 가장 먼저 든 생각은 하나였다.

편의점 운영을 뒷받침하는 IT 시스템은 어떤 흐름으로 연결될까?

처음에는 편의점 IT라고 하면 고객이 사용하는 앱이나 POS 정도를 먼저 떠올렸다. 하지만 운영 흐름을 정리해보니, 편의점 IT는 생각보다 넓은 범위의 시스템을 다루고 있었다.

편의점 IT 시스템의 역할은 크게 세 가지로 나눠볼 수 있었다.

첫째, 그룹웨어, 물류/회계 시스템, 통합정보, RPA, DBA 등과 관련된 WEB 사내 시스템 설계 및 운영이다.
둘째, 고객 모바일 시스템 개발 기획 및 운영이다.
셋째, POS, OPC, PDA 등 점포설비 개발 및 운영이다.

이 관점에서 편의점 운영 시스템은 단순히 하나의 웹 서비스를 만드는 일이 아니라, 편의점 운영 전반에 필요한 여러 시스템을 개발하고 안정적으로 운영하는 역할에 가깝다고 이해했다.

그래서 프로젝트를 정리하면서, 단순한 CRUD 프로젝트보다는 편의점 운영 흐름을 작게라도 반영한 프로젝트를 만들어보고 싶었다.

프로젝트 범위를 현실적으로 제한해야 했기 때문에, 모든 기능을 크게 구현하기보다는 핵심 데이터 흐름을 잘 보여주는 방향으로 범위를 잡았다.

2. 프로젝트 목표

이번 프로젝트의 이름은 StoreOps Platform으로 정했다.

목표는 편의점 운영에서 발생하는 핵심 데이터 흐름을 직접 구현해보는 것이다. 이를 위해 Spring Boot 기반의 모놀리스 백엔드 서버를 만들고, 개념적으로 다음 네 가지 클라이언트가 같은 데이터를 바라보도록 구성했다.

고객 앱
POS 판매 화면
PDA 입고 화면
관리자 대시보드

여기서 중요한 것은 클라이언트 화면의 완성도를 높이는 것이 아니었다. 실제로 보여주고 싶었던 것은 다음에 가까웠다.

POS에서 판매가 발생하면 재고가 줄어든다.
PDA에서 입고가 발생하면 재고가 늘어난다.
고객 앱은 변경된 재고를 조회한다.
관리자 화면은 재고 현황과 판매 이력을 바탕으로 결품 위험과 발주 추천을 확인한다.

즉, 여러 화면이 따로 움직이는 것처럼 보이지만 결국 같은 운영 데이터를 중심으로 연결되는 구조를 구현하고 싶었다.

완성도 높은 프론트엔드를 만드는 것보다, 작은 규모 안에서도 실제 운영 시스템의 데이터 흐름을 명확히 보여주는 것이 이번 프로젝트의 목표였다.

3. 왜 재고 데이터를 중심으로 잡았는가

프로젝트 범위를 정하면서 가장 먼저 고민한 것은 “편의점 운영에서 어떤 데이터가 가장 중요할까?”였다.

상품, 점포, 판매, 입고, 발주 등 여러 데이터가 있지만, 이 프로젝트에서는 재고를 중심 데이터로 잡았다.

편의점에서 재고는 단순히 “상품이 몇 개 남았는가”를 나타내는 숫자가 아니다. 재고 데이터는 고객 경험과 점포 운영을 동시에 좌우한다.

고객 입장에서는 앱에서 재고가 있다고 보고 점포에 방문했는데 실제로 상품이 없다면 헛걸음을 하게 된다. 반대로 실제 점포에는 상품이 있는데 앱에는 품절로 표시된다면 구매 기회를 잃게 된다.

점주 입장에서도 재고는 중요하다. 재고가 너무 적으면 결품이 발생하고, 재고가 너무 많으면 폐기나 보관 부담이 커질 수 있다. 특히 편의점은 상품 회전이 빠르고, 도시락이나 삼각김밥처럼 판매 기한이 중요한 상품도 많기 때문에 재고 관리의 정확성이 운영 효율에 직접적인 영향을 준다.

그래서 이번 프로젝트에서는 재고 데이터를 중심으로 다음 흐름을 구현하기로 했다.

POS 판매 → 재고 감소
PDA 입고 → 재고 증가
고객 앱 → 재고 조회
관리자 WEB → 재고 현황 확인
판매 이력 → 결품 위험 판단
재고/판매 데이터 → 발주 추천

이 흐름을 작게 구현하면 WEB, APP, 점포 시스템이 어떻게 하나의 운영 데이터로 연결되는지 보여줄 수 있다고 판단했다.

4. 프로젝트에서 중요하게 본 기술적 관점

이 프로젝트는 규모가 큰 시스템은 아니다. 그래서 무리하게 MSA나 복잡한 인프라 구조를 적용하기보다는, 작은 시스템 안에서도 운영 시스템다운 고민을 담는 것이 더 중요하다고 생각했다.

이번 프로젝트에서 중요하게 본 기술적 관점은 세 가지다.

4.1 재고 데이터 정합성

POS 판매가 발생하면 재고가 줄어야 하고, PDA 입고가 발생하면 재고가 늘어야 한다. 이 과정에서 재고가 음수가 되거나, 판매 이력과 재고 수량이 서로 맞지 않으면 안 된다.

예를 들어 판매 이력은 저장됐는데 재고가 줄지 않거나, 재고는 줄었는데 판매 이력이 저장되지 않으면 운영 중 원인 추적이 어려워진다.

따라서 판매 처리와 입고 처리는 트랜잭션으로 묶어 데이터 정합성을 지키는 방향으로 구현했다.

4.2 도메인 규칙 캡슐화

재고가 음수가 되면 안 된다는 규칙은 특정 API의 부가 로직이 아니라 Inventory 도메인 자체의 규칙이라고 보았다.

그래서 Service에서 단순히 수량을 직접 수정하기보다, Inventory 객체 안에 decrease()와 increase() 같은 메서드를 두고 재고 변경 규칙을 관리하도록 설계했다.

4.3 개발운영 관점

운영 시스템을 다루는 프로젝트인 만큼, 기능 구현에서 끝내지 않고 운영 관점도 함께 고려하려고 했다.

예를 들어 다음 요소를 포함했다.

표준 예외 응답
Swagger API 문서화
Actuator 헬스체크
핵심 이벤트 로그
테스트 코드
정적 클라이언트 화면

이를 통해 “로컬에서만 동작하는 코드”가 아니라, 외부에서 API 흐름을 확인하고 장애 상황도 어느 정도 파악할 수 있는 서비스 형태로 완성하고자 했다.

5. 앞으로 정리할 내용

이번 글에서는 편의점 운영 시스템를 분석하면서 왜 StoreOps Platform을 만들게 되었는지, 그리고 왜 재고 데이터를 중심으로 잡았는지 정리했다.

다음 글에서는 이 운영 흐름을 실제 도메인 모델로 어떻게 바꿨는지 정리하려고 한다.

특히 다음 내용을 다룰 예정이다.

편의점 운영 흐름 단순화
Store, Product, Inventory, Sale, Receipt 도메인 도출
현재 재고와 판매/입고 이력을 함께 저장한 이유
Inventory를 중심으로 한 관계 설계

결국 이번 프로젝트에서 보여주고 싶은 것은 “편의점 시스템을 완벽하게 구현했다”는 것이 아니다. 짧은 기간 안에서도 편의점 운영 흐름을 이해하고, 그 흐름을 데이터와 도메인 모델로 옮겨보려 했다는 점이다.

시리즈 이어보기
전체 글 목록 | 다음 글: 2. POS/PDA/고객 앱/관리자 WEB을 잇는 도메인 설계

문제
풀이

💡Idea

• 용액을 for문 돌면서, 현재 용액의 값을 -1배 시킨 용액값을 lower_bound로 찾으면 된다.
• lowe_bound로 찾은 위치의 좌우 값을 확인해야 한다.

🔑Code

#include <bits/stdc++.h>
using namespace std;

int main(void){
    ios_base::sync_with_stdio(0);
    cin.tie(0);

    int N, arr[100'000];
    cin >> N;
    for(int i = 0; i < N; i++){
        cin >> arr[i];
    }

    // 이미 오름차순으로 입력됨.
    // sort(arr,arr+N);

    int x, y;
    int cur_abs_sum = 0x7f7f7f7f;
    for(int i = 0; i < N-1; i++){
        int target_value = -arr[i];
        auto idx = lower_bound(arr+i+1, arr+N, target_value);
        
        // 오른쪽 값
        if(idx < arr+N){
            int r = *idx;
            int new_abs_sum = abs(arr[i] + r);
            if(new_abs_sum < cur_abs_sum){
                x = arr[i];
                y = r;
                cur_abs_sum = new_abs_sum;
            }
        }

        // 왼쪽 값
        if(idx-1 > arr+i){
            int l = *(idx-1);
            int new_abs_sum = abs(arr[i] + l);
            if(abs(arr[i] + l) < cur_abs_sum){
                x = arr[i];
                y = l;
                cur_abs_sum = new_abs_sum;
            }
        }
    }

    cout << x << ' ' << y;

    return 0;
}

🗨️ Side Notes

문제
풀이

💡Idea

• bfs 사용해서 풀이 동일한 가중치의 간선에서 최단 거리를 구하는 상황이기 때문에 적절
• dp를 사용하면 안되는 이유:
  • dp[i]가 i 이전의 상태로만 정의가 안됨.
  • 예를 들면, i보다 큰 값에서 뱀을 타고 내려오면 dp[i]는 i보다 큰 값에 영향을 받게 됨.

    🔑Code

    ```c++ #include <bits/stdc++.h> using namespace std;

#define INF 0x3f3f3f3f

int main(void){ ios_base::sync_with_stdio(0); cin.tie(0);

int N, M, vis[101], ladder[101], snake[101];
fill(vis, vis+101, INF);
fill(ladder, ladder+101, -1);
fill(snake, snake+101, -1);

cin >> N >> M;
for(int i = 0; i < N; i++){
    int x, y;
    cin >> x >> y;
    ladder[x] = y;
}
for(int i = 0; i < M; i++){
    int u, v;
    cin >> u >> v;
    snake[u] = v;
}

queue<int> Q;
Q.emplace(1);
vis[1] = 0;

while(!Q.empty()){
    int cur = Q.front(); Q.pop();
    // 정직하게 한 칸
    for(int i = 1; i <= 6; i++){
        int nxt = cur + i;
        int nxt_vis = vis[cur] + 1;
        if(nxt <= 100){
            // 사다리
            if(ladder[nxt] != -1){
                if(nxt_vis < vis[ladder[nxt]]){
                    Q.emplace(ladder[nxt]);
                    vis[ladder[nxt]] = nxt_vis;
                }
            }
            // 뱀
            else if(snake[nxt] != -1){
                if(nxt_vis < vis[snake[nxt]]){
                    Q.emplace(snake[nxt]);
                    vis[snake[nxt]] = nxt_vis;
                }
            }
            // 일반 칸
            else if(nxt_vis < vis[nxt]) {
                Q.emplace(nxt);
                vis[nxt] = nxt_vis;
            }
        }
    }
}

cout << vis[100];

return 0; } ``` ## 🗨️ Side Notes

문제
풀이

💡Idea

union find로 여행 가려는 곳이 연결되어 있는지 판단해주면 된다.

🔑Code

#include <bits/stdc++.h>
using namespace std;

int p[201];

int find(int x){
    if(p[x] < 0) return x;
    return p[x] = find(p[x]);
}

void uni(int u, int v){
    u = find(u), v = find(v);

    if(u == v) return;

    if(p[v] < p[u]) swap(u,v);
    else if(p[v] == p[u]) p[u]--;
    p[v] = u;

    return;
}

bool isUni(int u, int v){
    return find(u) == find(v);
}

int main(void){
    ios_base::sync_with_stdio(0);
    cin.tie(0);

    int N, M;
    cin >> N >> M;

    fill(p+1, p+1+N, -1);

    for(int i = 1; i <= N; i++){
        for(int j = 1; j <= N; j++){
            bool isAdj;
            cin >> isAdj;
            if(isAdj) uni(i,j);
        }
    }

    bool canGo = true;
    int cur, nxt;
    cin >> cur;
    while(cin >> nxt){
        if(!isUni(cur,nxt)){
            canGo = false;
            break;
        }
        cur = nxt;
    }

    if(canGo) cout << "YES";
    else cout << "NO";

    return 0;
}

🗨️ Side Notes