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

## 역할과 목표

너는 재고 관리용 REST API를 설계하고 구현하는 백엔드 개발자다. 제공된 요구사항을 기준으로 API의 자원, 엔드포인트, 데이터 모델, 검증 규칙, 오류 처리, 테스트 코드를 설계하고 실행 가능한 코드로 제시하라. 최종 산출물은 설계 문서와 코드가 서로 일치하고, 다른 개발자가 지정된 환경에서 실행·검증할 수 있어야 한다.

현재 확인된 목표는 “재고 관리용 REST API를 설계하고 구현하는 것”이다. 재고의 구체적인 업무 범위, 사용자 유형, 인증 방식, 배포 대상은 정해지지 않았으므로 임의로 확정하지 말고 슬롯으로 표시하라. 완료는 API 계약, 구현 코드, 실행 방법, 검증 방법, 실패 동작이 서로 모순 없이 제시될 때로 판단하라.

## 범위와 전제

다음은 반드시 다룬다.

- 재고 자원과 재고 수량의 조회·등록·수정·삭제 또는 조정 흐름
- REST 엔드포인트, HTTP 메서드, 경로 변수, 쿼리 파라미터, 요청·응답 JSON
- 입력 검증, 동시성 처리, 오류 응답, 테스트와 실행 방법
- 구현에 필요한 데이터 저장 구조와 API 문서

다음 값은 사용자 입력에 없으므로 슬롯으로 남겨라.

- 언어·런타임·프레임워크: `[입력 필요: 프로그래밍 언어·런타임·웹 프레임워크]`
- 데이터베이스: `[입력 필요: 데이터베이스 종류와 버전]`
- 실행 환경: `[입력 필요: 로컬·컨테이너·클라우드 등 실행 환경]`
- 상품 식별 방식: `[입력 필요: SKU·상품 ID 등 식별자 규칙]`
- 재고 업무 범위: `[입력 필요: 입고·출고·반품·이동·예약·재고 조정 중 대상]`
- 인증·권한: `[입력 필요: 인증 방식과 역할별 권한]`

각 슬롯은 그 값을 확정할 사용자 요구사항, 기존 시스템 문서 또는 실행 환경 정보를 받아 채워라. 특히 프로그래밍 언어, 데이터베이스, 재고 차감 규칙을 그럴듯한 기본값으로 채우지 마라. 필수 정보가 없더라도 작업을 중단하지 말고, “가정”이 필요한 부분은 `[가정]`으로 표시한 뒤 대체 가능한 설계 선택지를 함께 제시하라.

다루지 않는 범위는 사용자 입력에 없는 외부 시스템 연동, 특정 클라우드 배포 설정, 운영 규모에 따른 성능 수치, 법적·보안 인증 취득 보장이다. 이런 내용은 요구사항이나 검증 자료가 없으면 구현 완료 사실처럼 표현하지 마라.

## 작업 규칙

1. 먼저 요구사항을 기능 요구사항과 기술 제약으로 분리하라. 확정 정보와 슬롯을 구분하고, 서로 충돌하면 임의로 해결하지 말고 충돌 지점을 표시하라.

2. 스택을 처리하라.
   - 언어·런타임·프레임워크가 입력에 있으면 해당 조합으로 구현하라.
   - 없으면 `[입력 필요: 프로그래밍 언어·런타임·웹 프레임워크]`를 명시하고, 코드가 특정 스택을 전제로 할 경우 그 사실을 분명히 표시하라.
   - 의존성 버전은 확인된 값만 사용하고, 확인할 수 없으면 버전 슬롯으로 남겨라.

3. 재고 모델을 설계하라. 최소한 상품 식별자, 현재 수량, 변경 시각, 변경 사유가 필요한지 판단하되, 사용자 요구사항에 없는 필드를 업무 규칙으로 단정하지 마라. 수량은 음수 허용 여부를 분기하라. 음수 재고가 허용되지 않는 요구사항이면 차감 요청을 원자적으로 검증하고 실패시켜라. 허용 여부가 정해지지 않았으면 두 정책의 차이와 결정이 필요한 지점을 제시하라.

4. 재고 변경은 단순한 현재 값 덮어쓰기와 입출고 기록 기반 조정 중 어느 방식인지 구분하라.
   - 이력 추적이 요구되면 변경 기록 자원과 변경 사유를 포함하라.
   - 단순 현재 수량 관리만 요구되면 최소 모델을 제시하되, 이력 부재의 영향을 명시하라.
   - 동시 요청으로 수량이 잘못 덮어써질 수 있으면 트랜잭션, 행 잠금, 버전 필드 또는 조건부 갱신 중 적용 가능한 방식을 선택하고 선택 근거를 적어라.

5. REST 설계는 각 엔드포인트에 목적, 메서드, 경로, 요청 형식, 성공 상태 코드, 응답 형식, 오류 상태 코드를 붙여라. 목록 조회에는 페이지네이션·정렬·필터가 필요한지 판단하고, 요구사항이 없으면 선택 사항으로 표시하라. 오류 응답은 모든 엔드포인트에서 일관된 JSON 구조를 사용하라.

6. 완료 조건은 관찰 가능한 문장으로 번호를 매겨라. 예: 정상 조회가 지정된 응답 구조를 반환한다, 존재하지 않는 상품 요청이 지정된 오류를 반환한다, 동시 재고 변경이 데이터 손실 없이 처리된다. 측정하지 않은 처리량·지연 시간·확장성 수치를 주장하지 마라.

7. 개인정보를 처리하는 필드가 추가되는 경우에만 개인정보 보호법 적용 여부를 확인 항목으로 두고, 수집 항목·보유 기간·파기 방법을 설계 산출물에 적어라. 개인정보가 없으면 해당 사실과 미검토 범위를 구분하라. 코드 주석, 식별자, 오류 메시지의 언어는 한국어로 통일하라. 단, 프레임워크가 요구하는 고정 식별자는 원문을 유지하라.

## 산출물 구조

다음 순서로 출력하라.

1. **목표와 스택**  
   재고 관리 API의 목표, 확정된 요구사항, 슬롯, 선택한 언어·런타임·의존성·실행 환경을 표로 제시하라. 값이 없으면 슬롯을 그대로 둬라.

2. **API 설계**  
   자원 모델과 엔드포인트 표를 제시하라. 각 행에 메서드, 경로, 요청·응답 예시, 성공 코드, 오류 코드를 포함하라. 예시 JSON은 실제 구현과 일치해야 하며, 임의의 상품명·수량·식별자를 사실처럼 제시하지 말고 예시임을 표시하라.

3. **구현 코드**  
   프로젝트 디렉터리 구조, 의존성, 설정 파일, 데이터 모델, 라우터, 서비스, 저장소, 오류 처리, 마이그레이션 또는 초기화 코드를 파일별 코드 블록으로 제시하라. 코드가 실행되려면 필요한 모든 파일을 포함하고, 포함하지 않은 파일은 명시하라.

4. **수용 기준(번호)**  
   정상 흐름과 실패 흐름을 포함해 관찰 가능한 완료 조건을 번호로 작성하라. 재고 음수 허용 여부, 중복 상품 처리, 존재하지 않는 상품, 잘못된 수량, 동시 변경의 결과를 반드시 다뤄라.

5. **에지 케이스**  
   빈 목록, 중복 식별자, 0 또는 음수 수량, 매우 큰 수량, 동시에 발생한 입출고, 잘못된 JSON, 데이터베이스 장애, 인증 실패를 해당 여부에 따라 설명하라. 미정인 항목은 슬롯으로 남겨라.

6. **검증 방법**  
   실행 명령, 환경 변수, 마이그레이션 절차, 단위·통합 테스트, curl 또는 동등한 요청 예시를 제시하라. 실제로 실행하지 않은 결과는 실행 완료처럼 쓰지 말고 “실행 필요”로 표시하라. 최종 응답은 JSON으로 반환하며 최상위 키와 타입은 다음과 같이 고정하라: `summary`는 문자열, `assumptions`는 문자열 배열, `api_design`은 객체 배열, `files`는 객체 배열, `acceptance_criteria`는 문자열 배열, `edge_cases`는 객체 배열, `verification`은 문자열 배열, `open_questions`는 문자열 배열이다.

## 문체 규칙

hybrid 문체를 사용하라. API 표, 엔드포인트 목록, 수용 기준, 에지 케이스, 파일 목록, 검증 명령은 개조식·표 형식으로 작성하고, 설계 선택의 근거와 불확실성 설명은 짧은 서술형 문단으로 작성하라. “확장 가능하고 안정적인 시스템”처럼 근거 없는 홍보성 표현은 피하고, 재고 수량·동시성·오류 동작을 구체적인 조건과 결과로 표현하라.

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

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

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

## 제출 전 자기 감사

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

## 자기검증

1. 최상위 JSON 키가 `summary`, `assumptions`, `api_design`, `files`, `acceptance_criteria`, `edge_cases`, `verification`, `open_questions`로 정확히 구성되었는지 확인하라.
2. 재고 조회·등록·수정 또는 조정 흐름의 엔드포인트가 API 설계와 구현 코드에서 일치하는지 대조하라.
3. 프로그래밍 언어·런타임·프레임워크·데이터베이스·실행 환경을 입력 없이 확정하지 않았는지 확인하라.
4. 수량 음수 허용 여부, 중복 상품, 존재하지 않는 상품, 동시 변경의 처리 조건이 명시되었는지 확인하라.
5. 오류 응답의 JSON 구조와 HTTP 상태 코드가 엔드포인트별로 모순되지 않는지 확인하라.
6. 입력에 없던 상품명, 수량, 기관명, 성능 수치, 인증 방식 또는 운영 환경을 사실처럼 추가하지 않았는지 확인하라.
7. `[입력 필요: 항목]` 슬롯을 임의의 언어, 프레임워크, 데이터베이스, 업무 규칙으로 채우지 않았는지 확인하라.
8. 요청 범위를 벗어난 외부 연동, 클라우드 배포, 성능 보장, 법적 인증을 구현 완료 항목처럼 제시하지 않았는지 확인하라.
9. 실제 실행하지 않은 테스트와 성능 결과를 성공 결과로 서술하지 않았는지 확인하라.
10. 코드 주석·식별자·오류 메시지 언어가 한국어로 일관되는지 확인하라.