# 말레이시아 창고 재고관리 모듈 (`malaysia`)

말레이시아 현지 창고의 입고/출고/조정과 세트 BOM, 일일 재고조사를 관리한다.
cupang 모듈과 동일한 패턴: **malaysia_stock_db(PostgreSQL) 전용**, JSON 폴백 없음.
상품명은 기존 `itemcode_db`(읽기 전용)을 재사용한다.

- 경로(prefix): `/malaysia`
- 권한키: `malaysia` (admin 은 항상 통과)
- 환경변수: `MALAYSIA_STOCK_DB_URL` (미설정 시 "설정 필요" 안내), `ITEMCODE_DB_URL`(세트 BOM/이름)
- DB: `malaysia_stock_db` / 역할 `malaysia_app`

> **세트 구성(BOM)은 별도 관리하지 않는다.** itemcode_db `set_components`
> (set_code / single_code / quantity)에서 읽는다. 모듈 안에 세트구성 메뉴 없음.
> `malaysia_stock_db.set_bom` 테이블은 더 이상 쓰지 않는다(레거시, 무시).
> 입출고·재고조사는 전체 아이템(+세트) 그리드에 **수량만 키인**해 일괄 등록한다.

---

## 재고 원칙

- **입고/출고/조정은 낱개 아이템(MT-/MX-/MZ-) 기준**으로만 movement 저장.
- **세트(MY-)는 movement 불가.** 세트는 ① 재고조사 입력, ② BOM 구성 계산에만 사용.
- 세트 주문 출고는 `set_bom` 으로 분해해 구성품별 `OUT` movement 를 생성(`/malaysia/movements/set-out`).
- 뚜껑(MD-)은 재고관리 대상에서 **완전 제외**(어디에도 사용 불가).

### 현재고 계산

```
현재고 = SUM(IN) - SUM(OUT) + SUM(ADJUST) + SUM(STOCKTAKE)
```

- `IN`/`OUT` qty 는 양수만. `ADJUST`/`STOCKTAKE` 는 음수(±) 허용.
- 재고조사 확정 시 **시스템 재고와 조사 최종치의 "차이"만** `STOCKTAKE` movement 로 기록 → 이력 보존 + 계산 단순.

### 일일 재고조사 집계

```
낱개 최종 재고(total_qty)
  = direct_qty(낱개 직접 조사)
  + from_set_qty(세트 수량을 set_bom 으로 분해한 합)
```

예) `MT-0320` 낱개 100 + `MY-0002`(MT-0320 1개 포함) 20세트 → `MT-0320` total = **120**.
> 낱개 입력 시 **세트 안에 든 건 빼고** 낱개 보관분만 입력한다. 세트 안 상품은 BOM 으로 자동 계산.

---

## 테이블 (`scripts/sql/malaysia_stock_db_init.sql`)

| 테이블 | 용도 |
| --- | --- |
| `warehouses` | 창고. seed: `MY-WH-01 / Malaysia Warehouse` |
| `malaysia_items` | 관리 대상 코드 스코프(낱개/세트) + 이름 스냅샷. seed: 낱개 12 + 세트 5 |
| `set_bom` | 세트 구성표. `UNIQUE(set_code, component_code)`. prefix CHECK 내장 |
| `stock_movement` | 입고/출고/조정/조사 이력. `item_code` 는 낱개만(CHECK) |
| `daily_stocktake` | 재고조사 헤더. 같은 날짜+창고 finalized 1건(부분 유니크) |
| `daily_stocktake_line` | 조사 라인. `sku_code` 낱개+세트 허용, `UNIQUE(stocktake_id, sku_code)` |

검증 규칙(요구사항 8)은 **DB CHECK + 서비스 레이어(`store.py`)** 양쪽에 걸려 있다.

---

## 주요 화면 / API

화면: `/malaysia/`(재고 현황) · `/malaysia/movements`(입출고) · `/malaysia/stocktakes`(재고조사) · `/malaysia/sets`(세트 구성)

JSON API:

| Method | 경로 | 설명 |
| --- | --- | --- |
| GET | `/malaysia/api/warehouses` | 창고 목록 |
| GET | `/malaysia/api/items?kind=individual\|set` | 아이템 목록 |
| GET/POST | `/malaysia/api/bom` | 세트 구성 조회/등록 |
| GET | `/malaysia/api/stock?wh=` | 현재고 현황 |
| POST | `/malaysia/api/movements` | 낱개 movement 등록 |
| POST | `/malaysia/api/movements/set-out` | 세트 출고(BOM 분해) |
| GET | `/malaysia/api/stocktakes/{id}/result` | 재고조사 최종 계산 |

---

## 초기화 (운영, 1회 — 사용자 승인 후)

```bash
read -s -p "malaysia_app password: " APP_PWD; echo
docker exec -i postgres-db psql -U postgres \
  -v app_password="$APP_PWD" \
  < scripts/sql/malaysia_stock_db_init.sql

# main-app .env 에 추가:
#   MALAYSIA_STOCK_DB_URL=postgresql://malaysia_app:<APP_PWD>@postgres-db:5432/malaysia_stock_db
cd /opt/www/main && docker compose up -d --build
```

> 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. itemcode_db 는 건드리지 않음.

## 테스트

```bash
python -m pytest tests/test_malaysia_stock.py -v   # pytest 있으면
python tests/test_malaysia_stock.py                # 없으면 standalone 폴백
```
순수 로직(코드 검증 / 세트 분해 / 재고조사 집계)만 검증하므로 DB 불필요.