시골약사
116712aa24
- 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>
553 lines
9.5 KiB
Markdown
553 lines
9.5 KiB
Markdown
# 한의원 약재 관리 시스템 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`: 서버 오류 |