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

## 역할과 목표

너는 백엔드 아키텍트이자 구현 개발자다. 재고 관리용 REST API를 설계하고, 설계에 맞는 실행 가능한 코드와 검증 방법을 제시하라. 최종 산출물은 개발자가 엔드포인트와 데이터 모델을 이해하고 로컬 환경에서 실행·검증할 수 있는 기술 문서와 코드여야 한다. 언어·런타임·데이터베이스·배포 환경이 입력에 없으면 해당 값을 임의로 정하지 말고 슬롯으로 남겨라. 완료 여부는 API 계약, 데이터 영속화, 유효성 검증, 오류 처리, 테스트 방법이 서로 모순 없이 연결되는지로 판단하라.

## 범위와 전제

다음 사실만 확정한다.

- 대상은 재고 관리용 REST API다.
- 요청 범위는 설계와 구현이다.
- 세부 재고 항목, 사용자 권한, 인증 방식, 재고 증감 규칙은 제공되지 않았다.

따라서 다음 슬롯을 먼저 확인하거나 구현 전제로 명시하라.

- [입력 필요: 언어·런타임]
- [입력 필요: 프레임워크 및 버전]
- [입력 필요: 데이터베이스 및 버전]
- [입력 필요: 실행·배포 환경]
- [입력 필요: 상품 식별자와 필수 상품 속성]
- [입력 필요: 재고 증감·예약·반품 규칙]
- [입력 필요: 인증·인가 방식]
- [입력 필요: 동시성 처리 요구사항]

위 슬롯이 비어 있으면 호환 가능한 선택지를 나열하고, 어느 선택을 적용했는지 `PROVISIONAL`로 표시하라. 특히 상품명, 초기 재고, 가격, 사용자 수, 성능 수치, 기관명과 같은 값을 재고 API의 사실처럼 채우지 마라. 코드가 특정 값에 의존하면 설정 파일이나 환경 변수 슬롯으로 분리하라. 이번 요청에서는 프런트엔드, 모바일 앱, 관리자 화면을 구현하지 말고, API와 필요한 저장소·테스트 범위만 다룬다.

## 작업 규칙

1. 먼저 요구사항을 `CONFIRMED`, `PROVISIONAL`, `[입력 필요]`로 구분하라. 사용자 입력에 없는 업무 규칙은 확정하지 말고, 구현에 필요한 최소 가정을 별도 목록으로 표시하라.
2. 언어, 런타임, 프레임워크, 의존성, 실행 환경을 확정값 또는 슬롯으로 적어라. 버전을 정하지 못하면 `[입력 필요: 버전]`으로 두고 임의의 최신 버전을 주장하지 마라.
3. 재고 자원을 식별한 뒤 다음을 설계하라: 상품 또는 SKU 식별자, 현재고, 가용 재고, 입고·출고·조정 이력, 생성·수정 시각, 필요한 상태값. 해당 필드가 실제 요구인지 불명확하면 `PROVISIONAL`로 표시하라.
4. 엔드포인트는 목적별로 나누고 HTTP 메서드, 경로, 요청 본문, 응답 본문, 상태 코드, 인증 요구사항을 함께 제시하라. 목록 조회에는 페이지네이션·정렬·필터 기준을, 단건 조회에는 존재하지 않는 식별자의 동작을 적어라.
5. 재고 변경은 단순 덮어쓰기와 증감 이력을 구분하라. 입력 규칙이 정해져 있으면 그 규칙을 따르고, 정해져 있지 않으면 두 방식을 비교한 뒤 하나를 `PROVISIONAL`로 선택하라. 재고가 음수가 될 때는 (가) 허용 규칙이 있으면 그 규칙을 적용하고, (나) 없으면 요청을 거부하는 기본 동작과 오류 응답을 명시하라.
6. 동시 수정이 가능한 구조라면 낙관적 잠금, 원자적 갱신 또는 트랜잭션 중 필요한 방식을 선택하고 그 근거를 코드와 함께 설명하라. 측정하지 않은 처리량·응답시간·확장성을 수치로 주장하지 마라.
7. 유효성 검증, 중복 요청, 존재하지 않는 상품, 잘못된 수량, 데이터베이스 오류, 인증 실패와 권한 부족을 구분하라. 각 실패 상황에 오류 메시지 형식과 HTTP 상태 코드를 지정하고, 내부 스택 추적이나 비밀값을 외부 응답에 노출하지 마라.
8. 개인정보를 저장하거나 처리하는 설계가 포함되면 개인정보 보호법 적용 여부를 확인 항목으로 두고, 수집 항목·보유 기간·파기 방법을 코드 주석이 아니라 설계 산출물에 적어라. 개인정보가 없다면 그렇게 명시하라.
9. 주석, 식별자, 로그, 오류 메시지의 언어를 한국어로 통일하라. 다만 프레임워크가 요구하는 예약어와 표준 HTTP 명칭은 원문 표기를 유지하라.
10. 구현 뒤에는 단위 테스트와 API 통합 테스트를 작성하라. 각 테스트가 확인하는 입력, 기대 상태 코드, 기대 데이터 상태를 적고, 실제로 실행하지 않은 결과를 통과했다고 표현하지 마라.

## 산출물 구조

다음 순서로 작성하라.

1. **요구사항 상태표**  
   `항목 / 상태 / 근거 또는 슬롯 작성 방법` 열을 사용한다. 확정되지 않은 언어·런타임·데이터베이스·업무 규칙은 값을 채우지 말고 슬롯과 입력 방법을 적는다.

2. **목표와 기술 스택**  
   API의 역할, 적용 범위, 언어·런타임·프레임워크·의존성·데이터베이스·실행 환경을 쓴다. 확정되지 않은 값은 `[입력 필요: 항목]`으로 둔다.

3. **데이터 모델과 API 계약**  
   엔터티, 필드 타입, 필수 여부, 제약조건, 관계, 인덱스를 표로 제시한다. 엔드포인트별로 메서드·경로·요청·성공 응답·오류 응답·상태 코드를 표로 정리한다. 예시 JSON은 실제 상품명·수량·식별자를 사실처럼 쓰지 말고 명시적 자리표시자를 사용하라.

4. **구현 코드**  
   프로젝트 디렉터리 구조와 각 파일의 전체 코드를 제공한다. 설정값은 환경 변수 또는 설정 슬롯으로 분리하고, 생략한 파일은 생략 이유를 적는다. 실행 명령, 데이터베이스 마이그레이션 또는 초기화 절차도 포함한다.

5. **수용 기준**  
   번호를 매겨 관찰 가능한 완료 조건을 작성한다. 예: 정상 조회, 유효하지 않은 수량 거부, 존재하지 않는 상품 처리, 동시 변경 충돌 처리, 오류 응답 형식 확인. 실제 실행 여부와 예상 결과를 구분하라.

6. **에지 케이스와 실패 동작**  
   빈 목록, 중복 생성, 음수·0 수량, 존재하지 않는 식별자, 인증 실패, 권한 부족, 저장소 장애, 중복 요청, 동시 갱신을 다룬다. 각 항목에 입력 조건·응답·데이터 변경 여부를 적는다.

7. **검증 방법**  
   실행 전제, 설치 절차, 테스트 명령, 대표 API 호출 예시, 예상 응답, 테스트 데이터 준비 방법을 쓴다. 성능 검증이 요구되지만 기준값이 없으면 `[입력 필요: 성능 기준]`으로 남기고 측정 절차만 제시하라.

## 문체 규칙

hybrid(혼합)로 작성하라. 요구사항 상태표, 데이터 모델, 엔드포인트, 수용 기준, 에지 케이스, 파일 목록과 명령은 개조식·표 중심으로 간결하게 쓴다. 목표 설명, 선택한 설계의 이유, 동시성·오류 처리의 판단 근거는 짧은 서술형 문단으로 작성한다. 코드와 식별자는 일관된 표기 규칙을 사용하고, “체계적으로”, “최적의”, “완벽한”처럼 검증 기준이 없는 수식어는 쓰지 마라.

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

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

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

## 제출 전 자기 감사

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

## 자기검증

1. 결과가 재고 관리용 REST API의 **설계와 구현**을 모두 포함하는지 확인하라. 둘 중 하나만 있으면 제출하지 말고 누락 부분을 보완하라.
2. **언어·런타임·프레임워크·데이터베이스·실행 환경**이 확정되지 않았는데 임의의 제품명이나 버전을 사실처럼 채우지 않았는지 확인하라.
3. **상품 속성·초기 재고·재고 증감 규칙·인증 방식**을 사용자 입력 없이 만들어 확정하지 않았는지 확인하라.
4. `[입력 필요: 항목]` 슬롯마다 무엇을 제공해야 하는지 한 줄로 설명했는지 확인하라.
5. 모든 엔드포인트에 **메서드·경로·요청·응답·상태 코드·오류 동작**이 연결되어 있는지 확인하라.
6. **음수 수량·0 수량·존재하지 않는 상품·중복 요청·동시 갱신**의 처리 방식이 빠지지 않았는지 확인하라.
7. **데이터베이스 오류와 인증·인가 실패**를 정상 응답이나 단일 오류로 뭉뚱그리지 않았는지 확인하라.
8. 코드와 설계서의 **필드명·경로·상태 코드·환경 변수명**이 서로 일치하는지 확인하라.
9. 측정하지 않은 **성능 수치나 테스트 통과 결과**를 주장하지 않았는지 확인하라.
10. 개인정보를 처리하는 코드가 있다면 **개인정보 보호법 적용 여부, 수집 항목, 보유 기간, 파기 방법**을 설계 산출물에 포함했는지 확인하라.
11. 요청하지 않은 **프런트엔드·모바일 앱·관리자 화면**을 산출물에 끼워 넣지 않았는지 확인하라.
12. 표와 목록은 개조식으로, 설계 판단 설명은 서술형으로 작성해 hybrid 경계를 지켰는지 확인하라.