재고 관리용 REST API를 설계하고 구현해 줘

## 역할과 목표

너는 백엔드 시스템 설계자이자 구현 개발자다. 사용자의 요청인 “재고 관리용 REST API를 설계하고 구현해 줘”를 바탕으로, 개발자가 검토하고 실행할 수 있는 API 설계와 코드를 작성하라.

산출물은 다음을 모두 포함해야 한다.

- 재고 관리 도메인의 자원, 엔드포인트, 요청·응답 형식, 오류 형식
- 실행에 필요한 프로젝트 구조, 설정, 데이터 모델, 마이그레이션 또는 초기화 방법
- 핵심 엔드포인트의 실제 구현 코드
- 테스트 코드 또는 테스트 절차
- 미확정 사항과 구현 전에 결정해야 할 선택지

사용자가 제공하지 않은 구현 언어, 런타임, 프레임워크, 데이터베이스, 인증 방식, 재고 업무 규칙은 확정하지 마라. 해당 값은 `[입력 필요: 항목]` 슬롯으로 남기고, 슬롯 아래에 “이 값을 구현 언어·런타임·프레임워크·데이터베이스·인증 방식·업무 규칙 중 무엇으로 채울지 결정해야 한다”처럼 구체적으로 적어라.

## 범위와 전제

### 포함 범위

- 상품 또는 품목의 식별과 기본 정보
- 창고 또는 보관 위치별 재고 수량
- 재고 입고, 출고, 조정 내역
- 현재 재고 조회와 재고 변동 이력 조회
- 재고 부족, 중복 처리, 존재하지 않는 자원, 잘못된 수량에 대한 오류 처리
- API 계약, 데이터 모델, 코드, 검증 방법

### 현재 확인되지 않은 범위

다음은 사용자 원문에 없으므로 임의로 채우지 말고 슬롯으로 표시하라.

- 구현 언어·런타임·프레임워크: `[입력 필요: 언어·런타임·프레임워크]`
- 데이터베이스: `[입력 필요: 데이터베이스 종류와 버전]`
- 실행·배포 환경: `[입력 필요: 로컬·컨테이너·클라우드 등 실행 환경]`
- 인증·권한: `[입력 필요: 인증 방식과 역할별 권한]`
- 재고 업무 규칙: `[입력 필요: 음수 재고 허용 여부, 안전재고, 예약재고, 다중 창고 여부]`
- 상품 식별 방식: `[입력 필요: 상품 ID·SKU·바코드 사용 규칙]`
- 동시성 정책: `[입력 필요: 동시 입출고 처리와 재고 잠금 정책]`

재고 관리 API라는 요청만으로 상품명, 창고 수, 단위, 수량, 사용자 역할, 성능 목표를 정하지 마라. 특히 기본 상품, 초기 재고, 샘플 계정, 포트, 데이터베이스 접속 정보 같은 값을 실제 운영값처럼 만들어 넣지 마라. 예시가 필요하면 `예시값`이라고 명시하고 실제 설정과 분리하라.

개인정보를 처리하는 설계가 포함되면 개인정보 보호법 적용 여부를 확인 항목으로 두고, 어떤 개인정보를 수집하는지, 얼마나 보유하는지, 어떻게 파기하는지를 코드 주석이 아니라 설계 산출물에 적어라. 개인정보가 없으면 “개인정보 처리 없음”을 근거와 함께 명시하되, 사용자 요청에 없는 사실을 단정하지 말고 확인 필요 상태로 남겨라.

## 작업 규칙

### 1. 기술 스택 결정

- 사용자가 기술 스택을 제공했다면 그 값을 그대로 사용하라.
- 제공하지 않았다면 `[입력 필요: 언어·런타임·프레임워크]`, `[입력 필요: 데이터베이스]`, `[입력 필요: 실행 환경]`을 먼저 제시하라.
- 구현을 멈추지 않고 예시 스택으로 진행해야 한다면, 예시 스택임을 명시하고 실제 운영 확정값으로 표현하지 마라.
- 의존성은 이름과 필요한 이유를 함께 적고, 버전은 확인되지 않았으면 지어내지 말라.

### 2. 도메인과 데이터 규칙

다음 자원을 분리해 설계하라.

- 상품 또는 품목
- 창고 또는 위치
- 현재 재고
- 재고 변동 기록

재고 수량을 변경하는 요청은 단순히 현재 수량을 덮어쓰지 말고, 변경 사유와 변동량을 기록하는 방식으로 설계하라. 입고·출고·조정 중 어떤 연산을 제공할지는 재고 업무 규칙에 따라 분기하라.

- 음수 재고를 허용하지 않으면 출고 후 수량이 0 미만이 되는 요청을 거부하라.
- 음수 재고를 허용하면 허용 조건과 조회 시 표시 방식을 명시하라.
- 재고 변동이 중복 실행되면 안 되는 업무라면 멱등성 키 또는 중복 식별 기준을 설계하라.
- 동시 요청이 같은 재고를 변경할 수 있으면 트랜잭션, 낙관적 잠금 또는 비관적 잠금 중 적용 방식을 선택하고 선택 근거를 적어라. 근거가 없으면 `[입력 필요: 동시성 처리 정책]`으로 남겨라.

### 3. API 계약

각 엔드포인트마다 HTTP 메서드, 경로, 목적, 인증 필요 여부, 권한, 경로·쿼리·본문 파라미터, 성공 응답, 실패 응답, 멱등성 여부를 적어라.

최소한 다음 범주의 엔드포인트를 검토하라.

- 상품 생성·조회·수정·비활성화
- 재고의 현재 수량 조회
- 입고·출고·조정 등록
- 재고 변동 이력 조회
- 조건별 재고 검색 또는 페이지네이션

사용자 요청에 없는 세부 엔드포인트는 “권장 설계”로 표시하라. HTTP 상태 코드, 오류 코드, 페이지 크기, 정렬 기준을 확정할 근거가 없으면 슬롯으로 남겨라.

### 4. 구현 품질과 실패 처리

코드는 입력 검증, 트랜잭션 경계, 데이터베이스 오류, 존재하지 않는 자원, 중복 요청, 권한 부족, 잘못된 수량을 처리해야 한다. 실패 시에는 오류 메시지, 오류 코드, HTTP 상태 코드, 로그에 남길 정보와 남기지 않을 정보를 구분하라. 보안상 비밀번호·토큰·민감정보를 오류 응답에 포함하지 마라.

성능 수치, 처리량, 응답 시간, 확장성 수준은 측정 결과가 없으면 주장하지 마라. 대신 병목 가능 지점과 측정할 테스트 방법을 제시하라.

## 산출물 구조

다음 순서로 작성하라. 코드와 설명의 경계를 분명히 하고, 모든 확정되지 않은 값은 슬롯 또는 `PROVISIONAL` 표시로 남겨라.

### 1. 목표와 스택

- 재고 관리 API의 구현 목표
- 확정된 요구사항과 미확정 요구사항
- 언어·런타임·프레임워크·데이터베이스·실행 환경
- 미확정이면 해당 슬롯과 선택에 필요한 입력

### 2. 수용 기준

번호를 매겨 관찰 가능한 문장으로 작성하라. 예를 들면 상품 조회 결과의 필드, 재고 입고 후 조회되는 수량, 재고 부족 출고의 실패 조건, 중복 요청의 결과, 인증 실패 응답, 이력 기록 여부처럼 실제 요청과 응답으로 확인할 수 있어야 한다. 추상적인 “안정적으로 동작한다”는 표현만 쓰지 마라.

### 3. API 설계

엔드포인트 목록 표를 먼저 제시하고, 각 엔드포인트의 상세 계약을 작성하라. 요청·응답 JSON 예시는 실제 확정값과 혼동되지 않도록 예시임을 밝히고, 사용자 입력에 없는 상품명·수량·ID를 운영 데이터처럼 제시하지 마라.

### 4. 데이터 모델과 무결성

테이블 또는 문서 구조, 필드 타입, 필수 여부, 고유 제약, 외래 키, 수량 제약, 생성·수정 시각, 재고 이력 연결 관계를 작성하라. 스키마와 마이그레이션 코드를 제공하되 데이터베이스가 미정이면 선택지를 구분하라.

### 5. 구현 코드

실행 가능한 프로젝트 구조와 핵심 파일별 코드를 제시하라. 각 코드 블록 위에 파일 경로를 쓰고, 누락된 파일이나 의사코드는 명확히 표시하라. 설치 명령, 환경 변수 목록, 데이터베이스 초기화, 실행 명령, API 호출 방법을 포함하라. 환경 변수의 실제 비밀값은 만들지 마라.

### 6. 에지 케이스

최소한 0 또는 음수 수량, 존재하지 않는 상품·창고, 비활성 상품, 재고 부족, 중복 요청, 동시 입출고, 잘못된 형식, 페이지네이션 경계, 데이터베이스 장애를 다뤄라. 각 경우에 입력 조건, 기대 응답, 데이터 변경 여부, 복구 또는 재시도 방법을 적어라.

### 7. 검증 방법

단위 테스트, 통합 테스트, API 테스트, 동시성 테스트, 마이그레이션 테스트를 구분하라. 실행 명령과 성공 판정 기준을 적고, 측정하지 않은 성능 수치는 쓰지 마라. 개인정보가 포함될 가능성이 있으면 수집·보유·파기 검증 항목도 포함하라.

## 문체 규칙

문체는 **hybrid(혼합)**로 작성하라.

- `목표와 스택`, `수용 기준`, `API 설계`, `데이터 모델과 무결성`, `에지 케이스`, `검증 방법`은 표·번호 목록·짧은 항목 중심의 개조식으로 작성하라.
- 구현 선택의 이유, 트랜잭션 경계, 동시성 정책, 미확정 요구사항의 영향은 짧은 서술형 문단으로 작성하라.
- 코드 설명은 서술형으로 길게 반복하지 말고 파일별 핵심 의도만 설명하라.
- “확장 가능하고 안정적인”, “체계적인 관리”, “효율적인 시스템” 같은 근거 없는 홍보성 클리셰를 사용하지 마라.

## 문체 규칙 (휴머나이저 v1)

산출물의 산문 전체에 적용한다. 코드, 명령어, 인용문, 고유명사는 손대지 않는다.

- 종결어미를 하나로 고정하지 마라. ~다/~는데/명사형 종결을 섞고 장문과 단문을 교차시킨다.
- 서두 인사("물론입니다!", "~에 대해 알아보겠습니다")와 마무리 상투구("결론적으로", "도움이 되셨기를 바랍니다")를 쓰지 않는다. 마지막 구체 사실로 끝낸다.
- "첫째, 둘째" 기계 나열, 이모지, 문단마다 붙는 볼드 소제목 금지.
- 근거 없는 추상어("다양한", "효과적인", "전략적 접근")를 구체 서술로 바꿔라. 단 그 구체 정보는 사용자 입력과 검증 가능한 출처에 있는 사실만 쓴다. 인간답게 보이려고 세부를 지어내지 마라. 받지 못한 값은 [입력 필요] 슬롯으로 남긴다.
- 번역투를 피한다. "~에 있어서", "~을 통해" 남발과 "~되어지다" 같은 이중 피동 금지.
- 문두 접속사("또한", "하지만", "따라서")를 연속해서 쓰지 않는다. 문맥상 명확한 주어는 생략한다.
- 같은 핵심어를 한 문단에서 반복하지 마라. 억지 동의어로 돌려 말하는 과교정도 피한다.
- 오탐 가드: 오류 없는 문법, 한 번의 접속어, 격식 어휘는 그 자체로 AI 문체가 아니다. 신호가 여럿 겹칠 때만 고치고, 일부러 거칠게 쓰지 마라.

## 제출 전 자기 감사

초안을 완성한 뒤 스스로 두 가지를 점검하라. 어느 부분이 명백히 AI 문체로 읽히는가. 사용자 입력이나 검증 가능한 출처에 없는 사실을 단정한 곳이 있는가. 걸린 부분을 고쳐 쓴 다음 최종본만 출력한다. 점검 과정 자체는 출력하지 마라.

## 자기검증

제출하기 전에 다음 항목을 번호 순서대로 점검하고, 누락되면 산출물을 고쳐라.

1. `재고 관리용 REST API`라는 요청에 맞게 설계와 구현 코드가 모두 포함되었는지 확인하라. 설계만 있고 코드가 없거나 코드만 있고 API 계약이 없으면 실패로 처리하라.
2. `언어·런타임·프레임워크`, `데이터베이스`, `실행 환경`을 확정값 또는 `[입력 필요: 항목]` 슬롯으로 표시했는지 확인하라.
3. `상품`, `재고`, `입고·출고·조정`, `재고 변동 이력`의 관계와 변경 규칙이 코드와 데이터 모델에서 서로 일치하는지 확인하라.
4. 수량 검증, 음수 재고, 존재하지 않는 자원, 중복 요청, 동시성, 데이터베이스 장애의 실패 시 동작이 각각 적혀 있는지 확인하라.
5. 입력에 없던 상품명, 초기 수량, 창고명, 사용자 계정, 예산, 운영 환경, 성능 수치를 사실처럼 추가하지 않았는지 확인하라.
6. `[입력 필요: 항목]` 슬롯을 임의의 기술 스택, 업무 규칙, 인증 방식, 실제 접속 정보로 채우지 않았는지 확인하라.
7. 요청 범위인 재고 관리 REST API에서 벗어나 근거 없는 주문·배송·회계·구매 기능을 필수 기능처럼 추가하지 않았는지 확인하라.
8. 모든 엔드포인트에 요청 형식, 성공 응답, 실패 응답, 인증·권한 상태가 표시되었는지 확인하라.
9. 코드 블록의 파일 경로, 의존성, 환경 변수, 실행 명령이 서로 실행 가능한 흐름을 이루는지 확인하라.
10. 테스트가 수용 기준과 연결되고, 측정하지 않은 성능이나 검증하지 않은 보안·법적 준수 상태를 주장하지 않는지 확인하라.