sam-docs/frontend/api-specs/stock-receiving-changes-20260317.md

입고관리 / 재고현황 변경사항 (2026-03-17)

날짜: 2026-03-17 작업자: R&D실 (백엔드) 대상: React 프론트엔드 API 상태: 구현 완료, 개발서버 배포 완료

---

변경 항목

#	항목	대상 화면	작업 유형
1	원자재로트번호 자동채번	입고등록	UI 변경
2	재고 조정 위치 이동	입고관리 → 재고 상세	UI 이동 + API 연동

---

1. 원자재로트번호 자동채번

대상

URL: /material/receiving-management/new/mode-new
     /material/receiving-management/[id]?mode=edit
컴포넌트: ReceivingDetail.tsx

변경 내용

항목	변경 전	변경 후
lot_no 입력	사용자 직접 입력	readOnly (API 자동 생성)
신규 등록 시	프론트에서 generateLotNo() 호출	lot_no 미전송 → API가 자동 채번
수정 모드	편집 가능	readOnly (기존 값 표시)

프론트 작업

✅ lot_no input에 readOnly 속성 적용
✅ 배경색 회색(비활성) 처리
✅ 신규 등록 시 placeholder: "저장 시 자동 생성"
✅ 저장 후 API 응답의 lot_no 값으로 화면 갱신
❌ generateLotNo() 함수 호출 제거

API 동작

POST /api/v1/receivings (신규 등록)
  → lot_no 미전송 시 API가 채번규칙 기반 자동 생성
  → 채번 형식: YYMMDD-NN (예: 260317-01, 260317-02)
  → 응답: { "data": { "lot_no": "260317-01", ... } }

채번 형식은 MNG 채번규칙 관리에서 테넌트별 변경 가능. 프론트는 형식에 의존하지 않고 API 응답값을 그대로 표시.

---

2. 재고 조정 위치 이동

AS-IS → TO-BE

AS-IS:
  입고관리 목록 (ReceivingList.tsx)
    → 헤더에 [재고 조정] 버튼 → InventoryAdjustmentDialog 팝업
  입고관리 상세 (ReceivingDetail.tsx)
    → 하단에 재고 조정 이력 섹션

TO-BE:
  입고관리 목록 → [재고 조정] 버튼 제거
  입고관리 상세 → 재고 조정 섹션 제거
  재고현황 > 재고 상세 > 기본 정보 아래 > 재고 조정 섹션 (이력 + 추가)

대상 컴포넌트

작업	파일	내용
제거	ReceivingManagement/ReceivingList.tsx	헤더의 "재고 조정" 버튼 + isAdjustmentOpen 상태 + InventoryAdjustmentDialog 제거
제거	ReceivingManagement/ReceivingDetail.tsx	재고 조정 이력 섹션 렌더링 제거
추가	StockStatus/StockStatusDetail.tsx	기본 정보 카드 아래에 재고 조정 섹션 추가
이동	ReceivingManagement/InventoryAdjustmentDialog.tsx	공통 위치로 추출 권장

재고 조정 섹션 UI

┌──────────────────────────────────────────────────────────────────┐
│  재고 조정                                          [+ 추가]     │
├──────┬─────────────────────┬────────────┬─────────┬────────────┤
│  No  │  조정일시           │  증감 수량  │  사유    │  검수자     │
├──────┼─────────────────────┼────────────┼─────────┼────────────┤
│  1   │  2026-03-17 14:30   │  +100      │  실사조정│  김보곤     │
│  2   │  2026-03-16 10:15   │  -50       │  파손폐기│  홍길동     │
├──────────────────────────────────────────────────────────────────┤
│               재고 조정 이력이 없습니다.                           │
└──────────────────────────────────────────────────────────────────┘

+ 추가 버튼 동작

1. 클릭 시 입력 폼/모달 오픈
2. 증감 수량 (필수, 0 제외) 및 사유 (선택) 입력
3. 저장 시 POST /api/v1/stocks/{stockId}/adjustments 호출
4. 성공 시 이력 테이블 새로고침 + 기본 정보의 재고량 갱신

---

API 스펙

2-1. 재고 조정 이력 조회

GET /api/v1/stocks/{stockId}/adjustments

응답:

{
  "success": true,
  "message": "데이터를 조회했습니다.",
  "data": [
    {
      "id": 1,
      "adjusted_at": "2026-03-17 14:30",
      "quantity": 100,
      "balance_qty": 196,
      "remark": "실사 조정",
      "inspector": "김보곤"
    },
    {
      "id": 2,
      "adjusted_at": "2026-03-16 10:15",
      "quantity": -50,
      "balance_qty": 96,
      "remark": "파손 폐기",
      "inspector": "홍길동"
    }
  ]
}

2-2. 재고 조정 등록

POST /api/v1/stocks/{stockId}/adjustments
Content-Type: application/json

요청:

{
  "quantity": 100,
  "remark": "실사 조정"
}

필드	타입	필수	설명
quantity	number	O	증감 수량 (양수: 증가, 음수: 감소, 0 불가)
remark	string	X	조정 사유 (최대 500자)

응답:

{
  "success": true,
  "message": "데이터를 생성했습니다.",
  "data": {
    "id": 3,
    "adjusted_at": "2026-03-17 15:00",
    "quantity": 100,
    "balance_qty": 296,
    "remark": "실사 조정",
    "inspector": "김보곤"
  }
}

stockId 확인 방법

재고 상세 조회 응답에서 stock 관계의 id를 사용:

GET /api/v1/stocks/{itemId}
→ response.data.stock.id     ← 이것이 stockId

---

TypeScript 타입

// 재고 조정 이력
interface StockAdjustmentRecord {
  id: number;
  adjusted_at: string;     // "2026-03-17 14:30"
  quantity: number;         // 양수: 증가, 음수: 감소
  balance_qty: number;      // 조정 후 잔량
  remark: string | null;
  inspector: string;
}

// 재고 조정 입력 폼
interface StockAdjustmentForm {
  quantity: number;         // 필수, 0 불가
  remark?: string;          // 선택, 최대 500자
}

---

Server Action 예시

// StockStatus/actions.ts에 추가

export async function getStockAdjustments(stockId: number) {
  return fetchApi(`/stocks/${stockId}/adjustments`);
}

export async function createStockAdjustment(
  stockId: number,
  data: StockAdjustmentForm
) {
  return fetchApi(`/stocks/${stockId}/adjustments`, {
    method: 'POST',
    body: JSON.stringify(data),
  });
}

---

작업 체크리스트

입고 목록 (ReceivingList.tsx)

• 헤더의 "재고 조정" 버튼 제거
• isAdjustmentOpen 상태 변수 제거
• InventoryAdjustmentDialog import 및 렌더링 제거

입고 상세 (ReceivingDetail.tsx)

• lot_no input → readOnly 변경
• placeholder: "저장 시 자동 생성"
• generateLotNo() 호출 제거
• 재고 조정 이력 섹션 렌더링 제거

재고 상세 (StockStatusDetail.tsx)

• 기본 정보 카드 아래에 재고 조정 섹션 추가
• GET /stocks/{stockId}/adjustments 연동 → 이력 테이블 렌더링
• + 추가 버튼 → 입력 폼/모달 → POST /stocks/{stockId}/adjustments 연동
• 조정 성공 시 재고량 갱신 (기본 정보 리로드)