feat: 도매상 재고 표시 추가 (약국 N / 도매 M) + 문서화

docs/DATABASE_STRUCTURE.md

@@ -212,8 +212,98 @@ PostgreSQL에서 일부 제품은 APC 대신 **바코드**로 등록됨:
 
 ---
 
+## 재고 시스템 (2025-06-30)
+
+### 이중 재고 구조
+
+| 위치 | 테이블 | 용도 | 조회 방식 |
+|------|--------|------|-----------|
+| **MSSQL (PM_DRUG)** | `IM_total` | 약국 재고 | `IM_QT_sale_debit` |
+| **PostgreSQL** | `inventory` | 도매상 재고 | `SUM(quantity)` |
+
+### 약국 재고 (MSSQL)
+
+```sql
+-- IM_total 테이블
+SELECT DrugCode, IM_QT_sale_debit as stock
+FROM IM_total
+WHERE DrugCode = 'LB000003157';
+-- → 8 (현재 약국 보유 수량)
+```
+
+### 도매상 재고 (PostgreSQL)
+
+도매상 재고는 **입출고 이력**으로 관리됩니다.
+
+```sql
+-- inventory 테이블 (입출고 이력)
+-- quantity: +입고(INBOUND), -출고(OUTBOUND)
+
+SELECT A.apc, A.product_name, SUM(I.quantity) as wholesaler_stock
+FROM inventory I
+JOIN apc A ON I.apdb_id = A.idx
+WHERE A.for_pets = true
+GROUP BY A.apc, A.product_name
+HAVING SUM(I.quantity) > 0;
+
+-- 안텔민뽀삐: 38개
+-- 복합개시딘: 6개
+-- 세레니아16mg: 4개
+```
+
+### inventory 테이블 주요 컬럼
+
+| 컬럼 | 타입 | 설명 |
+|------|------|------|
+| apdb_id | integer | apc.idx FK |
+| quantity | integer | 수량 (+입고/-출고) |
+| transaction_type | varchar | INBOUND/OUTBOUND |
+| transaction_date | timestamp | 거래일시 |
+| wholesaler_price | numeric | 도매가 |
+| retail_price | numeric | 소매가 |
+| expiration_date | date | 유효기간 |
+
+### API 응답 예시
+
+```json
+{
+  "name": "안텔민뽀삐(5kg이하)",
+  "price": 5000,
+  "stock": 8,              // 약국 재고
+  "wholesaler_stock": 38   // 도매상 재고
+}
+```
+
+### 프론트엔드 표시
+
+```
+┌────────────────────────────────┐
+│ 💊 안텔민뽀삐(5kg이하)           │
+│    ₩5,000  약국 8 / 도매 38    │
+└────────────────────────────────┘
+```
+
+- **약국 재고 있음**: 초록색 `약국 8`
+- **약국 품절**: 빨간색 `품절`
+- **도매상 재고**: 파란색 `도매 38` (발주 가능)
+
+---
+
+## 향후 계획: 연관 제품 추천
+
+약국에 없지만 도매상에 있는 제품 추천 로직:
+
+1. **카테고리 기반**: 같은 efficacy_effect (심장사상충, 외부기생충 등)
+2. **신제품**: PostgreSQL `created_at` 최신순
+3. **인기 제품**: 도매상 출고량 기준 (`transaction_type = 'OUTBOUND'` 집계)
+
+→ 클릭 시 발주 연결 (미구현)
+
+---
+
 ## 관련 파일
 
 - `backend/app.py`: `_get_animal_drugs()`, `_get_animal_drug_rag()`
 - `backend/scripts/insert_apc_*.py`: APC INSERT 스크립트
+- `backend/scripts/check_pgsql_stock_sum.py`: 도매상 재고 확인
 - `docs/APC_MAPPING_PLAN.md`: APC 매핑 기획