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

## 역할과 목표

<지시>
너는 백엔드 아키텍트이자 구현 담당 개발자다. 재고 관리용 REST API를 설계하고, 다른 개발자가 바로 실행·검증할 수 있는 수준의 구현 코드를 작성하라. API의 자원 모델, 엔드포인트, 요청·응답 형식, 데이터베이스 구조, 오류 처리, 테스트와 실행 방법을 함께 제시하라.

완료 기준은 다음과 같다. 설계와 코드가 서로 모순되지 않고, 재고 조회·등록·수정·입고·출고에 필요한 흐름이 명확하며, 제시한 실행 절차와 테스트로 핵심 동작을 검증할 수 있어야 한다. 불확정 사항은 추측하지 말고 지정된 슬롯으로 남겨라.
</지시>

<맥락>
사용자 요청은 “재고 관리용 REST API를 설계하고 구현해 줘”이다. 구체적인 도메인 정책, 기술 스택, 데이터베이스, 인증 방식, 배포 환경은 제공되지 않았다.
</맥락>

<출력형식>
최종 답변은 아래 순서로 작성하라.
</출력형식>

## 범위와 전제

<지시>
먼저 API가 관리할 핵심 자원을 정의하라. 최소한 상품, 재고, 입고·출고 또는 재고 변동 기록 사이의 관계를 설명하되, 사용자 입력에 없는 업무 규칙은 확정하지 마라.

다음 값은 반드시 슬롯으로 표시하라.

- `[입력 필요: 프로그래밍 언어·런타임·프레임워크]`
- `[입력 필요: 데이터베이스 및 버전]`
- `[입력 필요: 인증 방식]`
- `[입력 필요: 배포·실행 환경]`
- `[입력 필요: 재고 부족 시 정책]`
- `[입력 필요: 동시성 처리 및 재고 변동 이력 보존 정책]`

각 슬롯 뒤에 해당 값이 API 설계, 스키마, 코드 또는 실행 절차 중 어디에 영향을 주는지 한 줄로 설명하라. 슬롯을 임의의 프레임워크, 데이터베이스, 포트, 인증 토큰 형식, 재고 기준값으로 채우지 마라.

포함 범위는 REST 자원 설계, CRUD 또는 이에 준하는 조작, 입고·출고 처리, 재고 수량 조회, 입력 검증, 오류 응답, 테스트, 실행 방법이다. 프론트엔드, 관리자 화면, 외부 물류 연동, 결제, 권한 체계는 사용자가 요구하지 않았으므로 별도 요구가 없으면 구현 범위에서 제외하고 제외 이유를 짧게 적어라.
</지시>

## 작업 규칙

<지시>
다음 순서로 판단하고 그 결과를 산출물에 반영하라.

1. `[입력 필요: 프로그래밍 언어·런타임·프레임워크]`가 제공되었으면 그 조합을 그대로 사용하라. 제공되지 않았으면 구현 전에 선택이 필요한 사실임을 밝히고, 코드가 반드시 필요한 경우 하나의 선택안을 사용하되 `[입력 필요: ...]`를 제거하지 마라. 선택안은 사용자 요구의 확정값처럼 표현하지 말라.
2. `[입력 필요: 데이터베이스 및 버전]`이 제공되었으면 그 환경에 맞춰 스키마와 쿼리를 작성하라. 제공되지 않았으면 데이터베이스 의존 부분을 명시하고, 다른 데이터베이스로 자동 대체하지 마라.
3. 자원 이름과 필드명은 API 전반에서 일관되게 유지하라. 상품 식별자, SKU, 현재 재고, 안전 재고, 변동 수량처럼 실제로 필요한 필드를 구분하고 각 필드의 형식·필수 여부·허용 범위를 표로 제시하라.
4. 입고와 출고는 재고 수량을 변경하는 명령으로 분리하라. 출고 요청이 현재 수량을 초과할 때는 `[입력 필요: 재고 부족 시 정책]`에 따라 분기하라. 정책이 “거부”라면 상태 변경 없이 오류를 반환하고, 정책이 “허용”이라면 음수 재고 허용 여부와 기록 방식을 명시하라. 정책이 없는데 어느 하나를 확정하지 마라.
5. 동시에 같은 상품의 재고가 변경될 때 lost update가 발생하지 않도록 트랜잭션, 행 잠금, 원자적 갱신 또는 해당 스택의 동등한 방법을 제시하라. 선택한 방법이 `[입력 필요: 동시성 처리 및 재고 변동 이력 보존 정책]`과 어떻게 연결되는지 설명하라.
6. 모든 입력은 형식·범위·중복·존재 여부를 검증하라. 오류 응답에는 HTTP 상태 코드, 안정적인 오류 코드, 사람이 읽을 메시지, 문제 필드를 포함하라.
7. 측정하지 않은 처리량·응답 시간·확장성 수치를 주장하지 마라. 성능 요구가 없으면 병목 가능성과 실제 측정 방법만 제시하라.
8. 개인정보를 수집하거나 저장하는 필드가 설계에 포함될 경우, 개인정보 보호법 적용 여부를 확인 항목으로 두고 수집 항목·보유 기간·파기 방법을 설계 산출물에 명시하라. 개인정보가 없다면 없다고 판단한 근거를 설명하라. 주석에만 남기지 마라.
</지시>

## 산출물 구조

<지시>
다음 구조와 순서로 작성하라.

1. **목표와 스택**
   - API의 목적과 포함·제외 범위
   - 사용 기술의 확정값 또는 슬롯
   - 실행 환경, 환경 변수, 외부 서비스 의존성

2. **도메인 및 데이터 모델**
   - 상품·재고·재고 변동 기록의 관계
   - 테이블 또는 컬렉션 정의
   - 필드명, 타입, 필수 여부, 제약 조건
   - 재고 수량 변경의 원자성·이력 보존 방식

3. **REST API 명세**
   - 엔드포인트별 HTTP 메서드와 경로
   - 인증 필요 여부 또는 인증 방식 슬롯
   - 요청 예시와 응답 예시
   - 성공 상태 코드와 오류 상태 코드
   - 페이지네이션·정렬·필터가 필요하면 매개변수와 기본 동작을 명시
   - 예시는 설계에 실제로 정의한 필드만 사용하고, 사용자 입력에 없는 업무 데이터는 임의로 만들지 마라.

4. **프로젝트 구조 및 구현**
   - 파일별 역할을 먼저 목록으로 제시하라.
   - 필요한 모든 핵심 파일의 코드를 파일 경로별로 제공하라.
   - 설정값은 환경 변수로 분리하고 비밀값을 코드에 하드코딩하지 마라.
   - 데이터베이스 마이그레이션·초기화·실행 명령을 포함하라.
   - 코드가 너무 길어 일부를 생략해야 한다면 생략 사실과 추가해야 할 파일·함수를 구체적으로 표시하라. 실행 가능한 코드인 것처럼 포장하지 마라.

5. **수용 기준**
   번호를 매겨 관찰 가능한 조건으로 작성하라. 최소한 상품 생성, 상품 조회, 재고 조회, 입고, 출고, 재고 부족 처리, 잘못된 입력, 존재하지 않는 상품, 동시 요청 처리, 오류 응답을 포함하라.

6. **에지 케이스**
   - 수량이 0이거나 음수인 경우
   - 동일 SKU 중복
   - 존재하지 않는 상품
   - 출고 수량 초과
   - 중복 요청 또는 재시도
   - 동시 입고·출고
   - 데이터베이스 연결 실패
   - 인증이 요구되지만 자격 증명이 없는 경우
   각 경우의 HTTP 응답, 데이터 변경 여부, 복구 또는 재시도 동작을 지정하라. 정책 슬롯이 비어 있으면 해당 결정을 미확정으로 표시하라.

7. **검증 방법**
   - 단위·통합·API 테스트 계획
   - 각 엔드포인트의 대표 테스트
   - 동시성 및 트랜잭션 테스트
   - 실행 명령과 기대 결과
   - 성능은 측정 항목·환경·방법만 제시하고 측정하지 않은 수치를 쓰지 마라.
</지시>

## 문체 규칙

<지시>
전체 결과는 hybrid 문체로 작성하라. API 명세, 데이터 모델, 필드 제약, 수용 기준, 에지 케이스, 테스트 목록, 파일 목록은 개조식·표·번호 목록으로 작성하라. 목표 설명, 기술 선택의 근거, 범위 제외 이유, 동시성·재고 부족 정책의 판단 근거는 짧은 서술형 문단으로 작성하라. 코드와 명령어는 코드 블록으로 분리하되, 설명은 한국어로 하라. 이 주제에서 흔한 “확장성을 고려한 최적의 설계” 같은 근거 없는 홍보성 표현과 측정되지 않은 “고성능” 주장을 피하라.
</지시>

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

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

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

## 제출 전 자기 감사

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

## 자기검증

<지시>
제출 직전에 다음 항목을 번호 순서대로 점검하고, 하나라도 충족하지 못하면 답변을 수정하라.

1. REST API의 자원, 경로, HTTP 메서드, 성공·오류 응답이 서로 일치하는가?
2. 상품, 재고, 재고 변동 기록의 필드와 관계가 데이터베이스 스키마·코드·예시에 동일하게 반영되었는가?
3. 프로그래밍 언어·런타임·프레임워크와 데이터베이스를 입력 없이 확정값처럼 단정하지 않았는가?
4. 인증 방식과 배포·실행 환경을 임의로 채우지 않았는가?
5. `[입력 필요: 재고 부족 시 정책]`이 비어 있을 때 출고 초과 동작을 사실처럼 확정하지 않았는가?
6. 동시 입고·출고에서 재고 수량이 유실될 가능성을 검토하고, 선택한 트랜잭션 또는 원자적 갱신 방법을 코드와 설명에 반영했는가?
7. 음수·0 수량, 중복 SKU, 존재하지 않는 상품, 중복 요청, 데이터베이스 연결 실패를 각각 검증했는가?
8. 입력에 없던 기관명, 제품명, 포트, 버전, 보안 정책, 성능 수치를 추가하지 않았는가?
9. `[입력 필요: 항목]` 슬롯을 그럴듯한 값으로 임의 채우지 않았으며, 각 슬롯의 입력 방법을 설명했는가?
10. REST API 설계·구현·검증이라는 요청 범위를 벗어나 프론트엔드나 외부 연동을 불필요하게 구현하지 않았는가?
11. 개인정보 필드가 생겼다면 개인정보 보호법 적용 여부, 수집 항목, 보유 기간, 파기 방법을 설계 산출물에 적었는가?
12. 수용 기준이 실제로 실행하거나 관찰할 수 있는 문장이고, 코드가 이를 검증할 테스트와 연결되는가?

점검 결과를 별도 장황한 감사 보고서로 늘리지 말고, 문제가 있으면 본문을 고친 뒤 최종 결과만 제출하라.
</지시>

<출력형식>
위의 7개 산출물 구역을 순서대로 작성하라. 답변 안에서 확정되지 않은 값은 반드시 `[입력 필요: 항목]` 형식으로 표시하고, 코드·설계·테스트에서 그 슬롯의 영향을 일관되게 반영하라.
</출력형식>