시골약사 116712aa24 docs: 데이터베이스 스키마 및 API 문서 추가

- database_schema.md: 전체 테이블 구조 상세 설명
  - 27개 테이블의 컬럼 정의 및 설명
  - 테이블 간 관계 설명
  - 주요 비즈니스 규칙 문서화

- database_erd.md: ER 다이어그램 및 데이터 플로우
  - Mermaid 다이어그램으로 시각화
  - 재고 흐름도, 처방-조제 흐름 설명
  - 인덱스 전략 및 데이터 무결성 규칙

- api_documentation.md: REST API 상세 명세
  - 약재, 처방, 조제, 재고, 환자 관리 API
  - 요청/응답 형식 예시
  - 에러 처리 방식

- README 업데이트: 문서 링크 추가

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2026-02-15 19:07:34 +00:00

9.5 KiB

Raw Permalink Blame History

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

약재 관리 API

GET /api/herbs

약재 제품 목록 조회

Response:

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

GET /api/herbs/masters

마스터 약재 목록 조회 (454개 표준 약재)

Response:

{
  "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:

{
  "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:

{
  "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:

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

POST /api/formulas

처방 등록

Request Body:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

POST /api/purchases/receipts

구매 영수증 등록

Request Body:

{
  "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:

{
  "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:

{
  "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:

{
  "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는 다음과 같은 에러 응답 형식을 따릅니다:

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

HTTP 상태 코드

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

9.5 KiB Raw Permalink Blame History

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

목차

약재 관리 API

GET /api/herbs

GET /api/herbs/masters

GET /api/herbs/by-ingredient/{ingredient_code}

GET /api/herbs/{herb_item_id}/available-lots

처방 관리 API

GET /api/formulas

POST /api/formulas

GET /api/formulas/{formula_id}/ingredients

조제 관리 API

POST /api/compounds

GET /api/compounds/recent

재고 관리 API

GET /api/inventory/summary

GET /api/inventory/low-stock

GET /api/stock-ledger

환자 관리 API

GET /api/patients

POST /api/patients

GET /api/patients/{patient_id}/prescriptions

구매/입고 API

POST /api/purchases/upload

POST /api/purchases/receipts

재고 조정 API

POST /api/stock-adjustments

GET /api/stock-adjustments

통계 API

GET /api/stats/herb-usage

에러 응답

HTTP 상태 코드

9.5 KiB

Raw Permalink Blame History