# 한의원 약재 관리 시스템 API 문서

## 목차
1. [약재 관리 API](#약재-관리-api)
2. [처방 관리 API](#처방-관리-api)
3. [조제 관리 API](#조제-관리-api)
4. [재고 관리 API](#재고-관리-api)
5. [환자 관리 API](#환자-관리-api)
6. [구매/입고 API](#구매입고-api)
7. [재고 조정 API](#재고-조정-api)

## 약재 관리 API

### GET /api/herbs
약재 제품 목록 조회

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "herb_item_id": 1,
      "insurance_code": "A001300",
      "herb_name": "인삼",
      "stock_quantity": 1500.0,
      "efficacy_tags": ["보기", "생진"]
    }
  ]
}
```

### GET /api/herbs/masters
마스터 약재 목록 조회 (454개 표준 약재)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "ingredient_code": "3400H1AHM",
      "herb_name": "인삼",
      "herb_name_hanja": "人蔘",
      "herb_name_latin": "Ginseng Radix",
      "stock_quantity": 7000.0,
      "has_stock": 1,
      "lot_count": 3,
      "product_count": 2,
      "company_count": 2,
      "efficacy_tags": ["보기", "생진"]
    }
  ]
}
```

### GET /api/herbs/by-ingredient/{ingredient_code}
특정 성분코드의 제품 목록 조회

**Parameters:**
- `ingredient_code`: 성분코드 (예: 3400H1AHM)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "herb_item_id": 38,
      "insurance_code": "060600420",
      "herb_name": "인삼",
      "product_name": "신흥인삼",
      "company_name": "신흥",
      "specification": "(주)신흥제약",
      "stock_quantity": 7000.0,
      "lot_count": 2,
      "avg_price": 17.5
    }
  ]
}
```

### GET /api/herbs/{herb_item_id}/available-lots
조제용 가용 로트 목록 (원산지별 그룹화)

**Parameters:**
- `herb_item_id`: 제품 ID

**Response:**
```json
{
  "success": true,
  "data": {
    "herb_name": "인삼",
    "insurance_code": "060600420",
    "origins": [
      {
        "origin_country": "한국",
        "total_quantity": 3000.0,
        "min_price": 20.0,
        "max_price": 25.0,
        "lot_count": 2,
        "lots": [
          {
            "lot_id": 1,
            "quantity_onhand": 1500.0,
            "unit_price_per_g": 20.0,
            "received_date": "2024-01-15"
          }
        ]
      }
    ],
    "total_quantity": 7000.0
  }
}
```

## 처방 관리 API

### GET /api/formulas
처방 목록 조회

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "formula_id": 1,
      "formula_code": "F001",
      "formula_name": "쌍화탕",
      "formula_type": "탕제",
      "base_cheop": 20,
      "base_pouches": 60
    }
  ]
}
```

### POST /api/formulas
처방 등록

**Request Body:**
```json
{
  "formula_code": "F002",
  "formula_name": "십전대보탕",
  "formula_type": "탕제",
  "base_cheop": 20,
  "base_pouches": 60,
  "description": "기혈 보충",
  "ingredients": [
    {
      "ingredient_code": "3400H1AHM",
      "grams_per_cheop": 6.0,
      "notes": ""
    }
  ]
}
```

### GET /api/formulas/{formula_id}/ingredients
처방 구성 약재 조회 (ingredient_code 기반)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "ingredient_code": "3400H1AHM",
      "herb_name": "인삼",
      "grams_per_cheop": 6.0,
      "total_available_stock": 7000.0,
      "available_products": [
        {
          "herb_item_id": 38,
          "herb_name": "신흥인삼",
          "specification": "(주)신흥제약",
          "stock": 7000.0
        }
      ]
    }
  ]
}
```

## 조제 관리 API

### POST /api/compounds
조제 실행

**Request Body:**
```json
{
  "patient_id": 1,
  "formula_id": 1,
  "je_count": 1,
  "cheop_total": 20,
  "pouch_total": 60,
  "ingredients": [
    {
      "herb_item_id": 38,
      "grams_per_cheop": 6.0,
      "origin": "auto"
    }
  ]
}
```

**Response:**
```json
{
  "success": true,
  "compound_id": 123,
  "message": "조제가 완료되었습니다",
  "summary": {
    "total_cost": 15000,
    "consumptions": [
      {
        "herb_name": "인삼",
        "total_used": 120.0,
        "lots_used": [
          {
            "lot_id": 1,
            "origin": "한국",
            "quantity": 120.0,
            "unit_price": 20.0
          }
        ]
      }
    ]
  }
}
```

### GET /api/compounds/recent
최근 조제 내역

**Query Parameters:**
- `limit`: 조회 건수 (기본값: 10)
- `patient_id`: 환자 ID (선택)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "compound_id": 123,
      "compound_date": "2024-01-20",
      "patient_name": "홍길동",
      "formula_name": "쌍화탕",
      "cheop_total": 20,
      "pouch_total": 60,
      "cost_total": 15000,
      "status": "completed"
    }
  ]
}
```

## 재고 관리 API

### GET /api/inventory/summary
재고 현황 요약

**Response:**
```json
{
  "success": true,
  "data": {
    "total_items": 87,
    "items_with_stock": 75,
    "total_value": 2500000,
    "by_origin": {
      "한국": {
        "item_count": 30,
        "total_quantity": 15000,
        "total_value": 1200000
      },
      "중국": {
        "item_count": 45,
        "total_quantity": 25000,
        "total_value": 1300000
      }
    }
  }
}
```

### GET /api/inventory/low-stock
재고 부족 약재 조회

**Query Parameters:**
- `threshold`: 재고 기준량 (기본값: 100g)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "herb_item_id": 5,
      "herb_name": "당귀",
      "current_stock": 50.0,
      "threshold": 100.0,
      "last_purchase_date": "2024-01-01"
    }
  ]
}
```

### GET /api/stock-ledger
재고 원장 조회

**Query Parameters:**
- `herb_item_id`: 제품 ID (선택)
- `start_date`: 시작일 (선택)
- `end_date`: 종료일 (선택)
- `event_type`: IN/OUT/ADJUST (선택)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "ledger_id": 1,
      "event_time": "2024-01-20 14:30:00",
      "event_type": "OUT",
      "herb_name": "인삼",
      "lot_id": 1,
      "quantity_delta": -120.0,
      "reference_table": "compound_consumptions",
      "reference_id": 456
    }
  ]
}
```

## 환자 관리 API

### GET /api/patients
환자 목록 조회

**Query Parameters:**
- `search`: 검색어 (이름, 전화번호)
- `is_active`: 활성 여부

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "patient_id": 1,
      "name": "홍길동",
      "phone": "010-1234-5678",
      "gender": "M",
      "birth_date": "1980-01-01",
      "last_visit": "2024-01-20"
    }
  ]
}
```

### POST /api/patients
환자 등록

**Request Body:**
```json
{
  "name": "홍길동",
  "phone": "010-1234-5678",
  "jumin_no": "800101-1******",
  "gender": "M",
  "birth_date": "1980-01-01",
  "address": "서울시 강남구",
  "notes": ""
}
```

### GET /api/patients/{patient_id}/prescriptions
환자 처방 이력

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "compound_id": 123,
      "compound_date": "2024-01-20",
      "formula_name": "쌍화탕",
      "cheop_total": 20,
      "pouch_total": 60,
      "cost_total": 15000,
      "ingredients": [
        {
          "herb_name": "인삼",
          "product_name": "신흥인삼",
          "grams_per_cheop": 6.0,
          "total_grams": 120.0,
          "origin_country": "한국"
        }
      ]
    }
  ]
}
```

## 구매/입고 API

### POST /api/purchases/upload
거래명세표 업로드

**Form Data:**
- `file`: 엑셀 파일
- `supplier_id`: 공급처 ID

**Response:**
```json
{
  "success": true,
  "receipt_id": 789,
  "summary": {
    "total_items": 25,
    "total_amount": 500000,
    "items_processed": 25,
    "items_failed": 0
  }
}
```

### POST /api/purchases/receipts
구매 영수증 등록

**Request Body:**
```json
{
  "supplier_id": 1,
  "receipt_date": "2024-01-20",
  "receipt_no": "R2024012001",
  "vat_included": true,
  "vat_rate": 10.0,
  "total_amount": 550000,
  "lines": [
    {
      "herb_item_id": 38,
      "origin_country": "한국",
      "quantity_g": 1000,
      "unit_price_per_g": 20.0,
      "line_total": 20000
    }
  ]
}
```

## 재고 조정 API

### POST /api/stock-adjustments
재고 보정

**Request Body:**
```json
{
  "adjustment_date": "2024-01-20",
  "adjustment_type": "correction",
  "notes": "실사 보정",
  "details": [
    {
      "herb_item_id": 38,
      "lot_id": 1,
      "quantity_after": 1480.0,
      "reason": "실사 차이"
    }
  ]
}
```

### GET /api/stock-adjustments
재고 보정 내역 조회

**Query Parameters:**
- `start_date`: 시작일
- `end_date`: 종료일
- `herb_item_id`: 제품 ID (선택)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "adjustment_id": 1,
      "adjustment_date": "2024-01-20",
      "adjustment_no": "ADJ20240120001",
      "adjustment_type": "correction",
      "total_items": 5,
      "created_by": "admin"
    }
  ]
}
```

## 통계 API

### GET /api/stats/herb-usage
약재 사용 통계

**Query Parameters:**
- `period`: daily/weekly/monthly
- `start_date`: 시작일
- `end_date`: 종료일

**Response:**
```json
{
  "success": true,
  "data": {
    "period": "2024-01",
    "top_used": [
      {
        "herb_name": "인삼",
        "total_quantity": 5000.0,
        "usage_count": 25,
        "total_cost": 100000
      }
    ],
    "total_compounds": 150,
    "total_cost": 3000000
  }
}
```

## 에러 응답

모든 API는 다음과 같은 에러 응답 형식을 따릅니다:

```json
{
  "success": false,
  "error": "에러 메시지",
  "code": "ERROR_CODE"
}
```

### HTTP 상태 코드
- `200 OK`: 성공
- `400 Bad Request`: 잘못된 요청
- `404 Not Found`: 리소스를 찾을 수 없음
- `500 Internal Server Error`: 서버 오류