API 설계

Commit Only 구조를 선택한 이유

DB 구조가 어느 정도 정리되자,
자연스럽게 다음 질문에 도착했다.

“이 데이터를 서버에는 언제 보내야 하지?”

입고, 출고, 폐기, 실사…
모두 사용자가 여러 단계를 거쳐서 완성하는 작업이다.
중간 단계마다 서버에 저장할 수도 있었고,
모든 걸 한 번에 보낼 수도 있었다.

이 선택이 API 설계의 방향을 결정했다.

---

Draft API를 처음엔 당연하게 생각했다

초기에는 이런 구조도 떠올렸다.

• 스캔할 때마다 서버에 임시 저장
• 수정할 때마다 Draft 업데이트
• 마지막에 확정 플래그만 변경

UI 기준으로 보면 꽤 자연스럽다.
하지만 조금만 더 생각해보니 문제가 보이기 시작했다.

---

Draft를 서버가 들고 있을 때의 문제

Draft를 서버에 저장하는 순간, 서버는 이런 상태를 감당해야 한다.

• 아직 확정되지 않은 데이터
• 언제 취소될지 모르는 상태
• 브라우저 종료, 네트워크 끊김 같은 예외

즉, 서버가 **“사실이 아닐 수도 있는 데이터”**를
계속 관리해야 한다는 뜻이다.

“이 데이터는 기록인가, 아니면 임시 메모인가?”
백엔드 서버를 임시 메모리 처럼 사용한다는게 어색했고, 레디스 같은 캐싱 서버를 사용한다해도 어차피 브라우저, 백엔드, 캐싱서버가 같은 보드에서 돌아간다면 큰 의미가 없다고 생각했다.

---

서버는 ‘사실’만 기억하게 하자

이 질문을 기준으로 역할을 나눴다.

• 브라우저: 임시 상태(Draft)
• 서버(DB): 확정된 결과(Commit)

그래서 API 구조는 단순해졌다.

• 입고/출고/폐기 Draft API 없음
• 오직 Commit API만 존재
• Commit 시점에만 트랜잭션 발생

이게 우리가 선택한 Commit Only 구조다.

---

Commit Only 구조의 장점

이 구조의 가장 큰 장점은 명확함이다.

• DB에 있는 데이터는 전부 “이미 일어난 일”
• 중간 상태는 서버가 책임지지 않음
• 로그, 재고, 이력이 항상 정합성을 가짐

특히 재고(inventory)와 이력(inbound_history, outbound_history)을
같이 갱신해야 하는 구조에서는
Commit 단위 트랜잭션이 거의 필수에 가까웠다.

---

대신 감수해야 했던 것들

물론 단점도 있었다.

• 브라우저 상태 관리가 복잡해짐
• 새로고침/이탈 시 Draft 유실 가능
• UX 설계에 더 신경 써야 함

하지만 이 부담은 의도적으로 클라이언트 쪽으로 넘겼다.

서버는 복잡해지면 되돌리기 어렵고,
브라우저는 다시 그릴 수 있기 때문이다.

“서버는 사실만 기억한다”는 원칙으로 설계해서 테스트 단계에서 개발작업이나, 시스템 다운후 동작에서 큰 꼬임이 없었던 장점이 있다.

---

세션 설계와 Commit Only의 연결

이 구조는 세션 설계와도 자연스럽게 이어졌다.

• 세션 시작 → 작업 맥락 생성
• Draft는 브라우저에서만 유지
• Commit 시점에
  • 세션 ID
  • 사용자 ID
  • 결과 데이터
    를 함께 서버로 전송

그래서 서버 입장에서는
“이 세션에서 이런 결과가 확정됐다”만 남는다.

---

아쉬웠던 점

다만, 이 구조가 완벽하다고 보긴 어렵다.

• 브라우저 비정상 종료 시 세션 정리 문제
• Commit 전에 세션이 유실될 가능성
• 세션 생명주기를 명확히 정의하지 못함

다음에 다시 설계한다면
Commit Only 구조는 유지하되,
세션을 상태 객체로 더 명확히 다뤘을 것 같다.

---

이 단계에서 남기는 요약 회고

이 API 설계에서 배운 점

• 서버는 사실만 저장하는 게 가장 안전하다
• 임시 상태는 최대한 클라이언트에 둔다
• 임시저장을 하고싶으면 임시메모리를 어디에서 쓸건지 고민하자(별도의 레디스서버, 백서버 메모리, 브라우저 등등)
• Commit 단위가 명확하면 DB 설계도 단순해진다