Skip to content

Latest commit

 

History

History
99 lines (68 loc) · 6.17 KB

case-study-ko.md

File metadata and controls

99 lines (68 loc) · 6.17 KB

OrderOps Cloud 구축 사례

한 줄 설명

주문 조회부터 역할별 상태 변경, 동시 수정 충돌 처리, 감사 이력까지 하나의 업무 흐름으로 연결한 멀티테넌트 주문 운영 시스템입니다.

구축 목표

주문 관리 도구의 핵심은 표와 통계 카드를 보여 주는 데 그치지 않습니다. 주문이 어느 회사에 속하는지, 누가 어떤 상태로 바꿀 수 있는지, 동시에 들어온 수정 요청을 어떻게 처리하는지, 변경 근거를 어떻게 보존하는지가 함께 동작해야 합니다.

OrderOps Cloud는 다음 규칙을 브라우저 화면, API, PostgreSQL 제약, 자동화 테스트로 연결했습니다.

  • 사용자는 현재 세션의 회사 데이터만 조회합니다.
  • 열람 전용 사용자의 변경 요청은 API에서도 거부합니다.
  • 같은 주문을 동시에 수정하면 오래된 요청이 앞선 작업을 덮어쓰지 않습니다.
  • 주문 상태와 담당자·변경 사유를 같은 트랜잭션으로 기록합니다.
  • 감사 이벤트의 일반 수정과 삭제를 DB 트리거에서 차단합니다.

핵심 사용자 흐름

  1. 사용자가 회사와 역할을 선택해 로그인합니다.
  2. API가 세션의 회사 ID로 주문과 운영 지표를 조회합니다.
  3. 사용자가 주문을 선택하면 현재 상태에서 가능한 다음 단계가 표시됩니다.
  4. 변경 요청에 화면이 마지막으로 확인한 주문 버전과 변경 사유를 전송합니다.
  5. 서버가 회사, 역할, 상태 전이, 버전을 검증합니다.
  6. PostgreSQL 트랜잭션 안에서 주문과 감사 이벤트를 함께 기록합니다.
  7. 화면이 갱신된 주문, 지표, 감사 이력을 다시 불러옵니다.

설계 결정

회사 경계를 세션에서 결정

보호된 API는 요청 본문에 담긴 회사 정보를 신뢰하지 않습니다. 서버가 HttpOnly 세션 쿠키로 사용자와 회사 컨텍스트를 복원하고, 그 회사 ID를 모든 업무 쿼리에 적용합니다. 다른 회사 주문을 조회하거나 변경하려 하면 존재 여부를 노출하지 않도록 404를 반환합니다.

화면 제어와 서버 권한 검증을 분리

클라이언트가 버튼을 숨기는 처리는 사용성을 위한 보조 장치입니다. admin, operator, viewer의 전이 규칙은 서버에서 다시 확인합니다. 열람 전용 계정이 변경 API를 직접 호출해도 403 TRANSITION_FORBIDDEN으로 거부됩니다.

상태 변경과 감사 로그를 한 트랜잭션으로 처리

변경 대상 행을 FOR UPDATE로 잠그고, 주문 버전 증가와 감사 이벤트 생성을 함께 커밋합니다. 감사 이벤트에는 당시 담당자 이름과 역할을 스냅샷으로 남깁니다. PostgreSQL 트리거는 일반적인 감사 이력 수정·삭제를 거부합니다.

낙관적 버전으로 덮어쓰기 방지

각 주문은 증가하는 version을 가집니다. 클라이언트의 expectedVersion이 DB의 현재 버전과 다르면 API는 409 VERSION_CONFLICT를 반환합니다. 사용자는 최신 주문을 다시 확인한 뒤 변경을 이어 갑니다.

변경 요청의 출처와 입력 형식을 검사

로그인·로그아웃·상태 변경은 SameSite=Strict 쿠키와 X-OrderOps-Request 헤더, Fetch Metadata를 함께 검사합니다. 로그인과 상태 변경은 JSON 본문만 받고, 잘못된 필터·식별자·본문 크기를 안정적인 오류 코드로 구분합니다.

공유 환경의 쓰기 상태를 관리

SHARED_ACCESS_MODE=true에서는 로그인 시 현재 회사의 주문과 감사 이력을 기준 상태로 되돌립니다. 변경 사유는 공개 환경에서 수행한 상태 변경으로 고정하고, 로그인과 상태 변경에 인스턴스 단위 요청 제한을 적용합니다. 화면은 user.sharedAccessMode를 읽어 자유 입력 필드를 숨깁니다.

구현 범위

  • React + TypeScript 주문 워크스페이스
  • Node.js 24 + Express 5 API
  • PostgreSQL 16 스키마와 기준 주문 데이터
  • scrypt 비밀번호 해시 검증
  • 해시만 DB에 저장하는 8시간 세션 쿠키
  • 같은 출처 변경 요청 표식, Fetch Metadata 검사, 보안 응답 헤더
  • 회사별 주문·지표·감사 이력 조회
  • 역할 기반 주문 상태 전이
  • 트랜잭션 기반 주문·감사 로그 동시 기록
  • 담당자 스냅샷과 DB 트리거 기반 append-only 감사 이력
  • 주문 버전을 이용한 동시 수정 충돌 처리
  • 공유 환경 보호 모드의 회사 상태 초기화, 고정 감사 메모, 요청 제한
  • 단위 테스트, PostgreSQL 통합 테스트, Playwright 사용자 흐름, CI
  • Docker Compose, OpenAPI, 아키텍처·운영 문서

검증 시나리오

npm run verify

전체 검증은 다음 경로를 확인합니다.

  • 운영 담당자의 상태 변경과 감사 로그가 함께 저장되는지
  • liveness와 PostgreSQL readiness가 구분되는지
  • 같은 출처 표식 없는 변경 요청이 인증 전에 거부되는지
  • 열람 전용 계정의 변경 요청이 서버에서 거부되는지
  • 다른 회사 주문과 감사 이력이 404로 숨겨지는지
  • 오래된 주문 버전이 동시 수정 충돌로 처리되는지
  • 감사 이벤트의 일반 수정·삭제가 DB에서 거부되는지
  • 데스크톱과 모바일에서 로그인·조회·변경·감사 흐름이 이어지는지

현재 범위와 확장 계획

현재 버전은 주문 워크플로의 핵심 경로를 완성했습니다. 비밀번호 재설정, MFA, 분산 요청 제한, 커서 페이지네이션, PostgreSQL RLS, 버전형 마이그레이션, 택배사 연동, 웹훅 재시도, 관측성 플랫폼, 백업 복구 훈련은 다음 확장 범위입니다.

우선순위는 다음과 같습니다.

  1. PostgreSQL RLS와 권한 회귀 테스트로 회사 격리를 강화합니다.
  2. 버전형 마이그레이션과 비파괴 기준 데이터 전략을 도입합니다.
  3. 공유 저장소나 엣지 방화벽 기반 요청 제한과 세션 관리 화면을 추가합니다.
  4. 커서 페이지네이션과 데이터 분포에 맞춘 필터 인덱스를 검증합니다.
  5. 요청 ID, 구조화 로그, 오류 추적, 백업 복구 절차를 연결합니다.