Admin Terminology Management APIs

// Headers required for all requests
const headers = {
  'Authorization': `Bearer ${superAdminToken}`,
  'Content-Type': 'application/json'
}

/admin/terminology

const response = await fetch('/admin/terminology', {
  method: 'GET',
  headers: headers
});

{
  "success": true,
  "message": "Terminology dashboard data fetched",
  "data": {
    "stats": {
      "total_medicines": 197,
      "coded_medicines": 0,
      "pending_review": 0,
      "fhir_ready": 0,
      "by_country": [
        {
          "country": "IN",
          "total": 0,
          "coded": 0,
          "coverage": 0
        },
        {
          "country": "US",
          "total": 197,
          "coded": 0,
          "coverage": 0.0
        },
        {
          "country": "AE",
          "total": 0,
          "coded": 0,
          "coverage": 0
        }
      ],
      "coding_quality": {
        "avg_confidence": null,
        "high_confidence": 0,
        "low_confidence": 197,
        "manual_verified": 0
      }
    },
    "recent_coding": [
      {
        "id": 123,
        "name": "Medicine Name",
        "coding_status": "complete",
        "coding_confidence": 0.95,
        "last_coded_at": "2025-10-03T10:30:00.000Z"
      }
    ],
    "pending_review": [
      {
        "id": 124,
        "name": "Medicine Name",
        "manufacturer": "Manufacturer Name",
        "coding_status": "pending",
        "coding_confidence": 0.0
      }
    ]
  }
}

const params = new URLSearchParams({
  page: 1,
  per_page: 20,
  country: 'US',
  confidence_range: 'low'
});

const response = await fetch(`/admin/terminology/review?${params}`, {
  method: 'GET',
  headers: headers
});

{
  "success": true,
  "message": "Review data fetched",
  "data": {
    "medicines": [
      {
        "id": 196,
        "name": "Aagnil Syrup",
        "manufacturer": "Haledew Remedies",
        "country": "US",
        "med_type": "Syrup",
        "prescription_type": "otc",
        "snomed_code": null,
        "country_specific_code": null,
        "ndc_code": null,
        "coding_status": "pending",
        "coding_confidence": 0.0,
        "coding_source": null,
        "last_coded_at": null,
        "prescription_count": 0,
        "fhir_ready": false
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_count": 197,
      "total_pages": 10
    },
    "filters": {
      "country": "US",
      "confidence_range": "low",
      "status": null,
      "prescription_usage": null
    }
  }
}

{
  "snomed_code": "387458008",
  "country_specific_code": "RX789012",
  "ndc_code": "54321-987-65",
  "coding_status": "complete",
  "coding_confidence": 0.98
}

const medicineId = 196;
const updateData = {
  snomed_code: "387458008",
  country_specific_code: "RX789012",
  ndc_code: "54321-987-65",
  coding_status: "complete",
  coding_confidence: 0.98
};

const response = await fetch(`/admin/terminology/${medicineId}`, {
  method: 'PATCH',
  headers: headers,
  body: JSON.stringify(updateData)
});

{
  "success": true,
  "message": "Medicine codes updated successfully",
  "data": {
    "medicine": {
      "id": 196,
      "name": "Aagnil Syrup",
      "snomed_code": "387458008",
      "country_specific_code": "RX789012",
      "ndc_code": "54321-987-65",
      "coding_status": "complete",
      "coding_confidence": 0.98,
      "coding_source": "manual",
      "last_coded_at": "2025-10-03T10:30:00.000Z"
    },
    "fhir_ready": true,
    "coding_summary": {
      "snomed_code": "387458008",
      "country_specific_code": "RX789012",
      "ndc_code": "54321-987-65",
      "status": "complete",
      "confidence": 0.98,
      "source": "manual",
      "last_coded_at": "2025-10-03T10:30:00.000Z"
    }
  }
}

{
  "success": false,
  "errors": [
    {
      "source": "request",
      "title": "Request At least one coding field must be provided with a non-empty value (snomed_code, country_specific_code, ndc_code, coding_status, or coding_confidence)"
    }
  ]
}

{
  "success": false,
  "errors": [
    {
      "source": "coding_confidence",
      "title": "Coding Confidence must be between 0.0 and 1.0"
    }
  ]
}

{
  "success": false,
  "errors": [
    {
      "source": "coding_status",
      "title": "Coding Status must be one of: pending, partial, complete, failed"
    }
  ]
}

const params = new URLSearchParams({
  q: 'Aagnil',
  country: 'US',
  limit: 10
});

const response = await fetch(`/admin/terminology/search?${params}`, {
  method: 'GET',
  headers: headers
});

{
  "success": true,
  "message": "Search completed",
  "data": {
    "type": "search",
    "data": {
      "query": "Aagnil",
      "limit": 10,
      "results": [
        {
          "id": 196,
          "name": "Aagnil Syrup",
          "manufacturer": "Haledew Remedies",
          "country": "US",
          "coding_status": "complete",
          "coding_confidence": 0.98,
          "snomed_code": "387458008",
          "country_specific_code": "RX789012",
          "ndc_code": "54321-987-65",
          "coding_summary": {
            "snomed_code": "387458008",
            "country_specific_code": "RX789012",
            "ndc_code": "54321-987-65",
            "status": "complete",
            "confidence": 0.98,
            "source": "manual",
            "last_coded_at": "2025-09-15T20:08:33.349Z"
          },
          "fhir_ready": true,
          "prescription_count": 0
        }
      ],
      "total_found": 1
    }
  }
}

const response = await fetch('/admin/terminology/health', {
  method: 'GET',
  headers: headers
});

{
  "success": true,
  "message": "System health check completed",
  "data": {
    "type": "health",
    "data": {
      "timestamp": "2025-09-15T20:03:06.910Z",
      "overall_status": "unhealthy",
      "components": {
        "database": {
          "status": "healthy",
          "response_time_ms": 9.01,
          "total_medicines": 197,
          "coded_medicines": 0,
          "coding_coverage": 0.0
        },
        "terminology_apis": {
          "overall_status": "degraded",
          "apis": {
            "nrces_snomed": {
              "status": "unhealthy",
              "error": "Failed to open TCP connection to snowstorm.nrces.in:443",
              "response_time_ms": 1.43,
              "last_checked": "2025-09-15T20:03:06.920Z"
            },
            "rxnorm": {
              "status": "healthy",
              "response_time_ms": 1264.89,
              "last_checked": "2025-09-15T20:03:08.185Z"
            },
            "fda_ndc": {
              "status": "healthy",
              "response_time_ms": 1286.37,
              "last_checked": "2025-09-15T20:03:09.472Z"
            }
          },
          "healthy_count": 2,
          "total_count": 3
        },
        "job_queues": {
          "status": "healthy",
          "queue_size": 0,
          "processing": 0,
          "retrying": 0,
          "dead": 0,
          "total_pending": 0
        },
        "coding_quality": {
          "status": "unhealthy",
          "coding_coverage": 0.0,
          "average_confidence": 0,
          "failure_rate": 0.0,
          "metrics": {
            "total_medicines": 197,
            "coded_medicines": 0,
            "high_confidence": 1,
            "low_confidence": 196,
            "failed_coding": 0
          }
        },
        "data_freshness": {
          "status": "healthy",
          "last_terminology_update": "2025-09-15T20:01:28.866Z",
          "days_since_update": 0.0,
          "recent_imports": 197,
          "recent_updates": 197
        }
      },
      "alerts": [
        {
          "severity": "warning",
          "component": "database",
          "message": "Low coding coverage: 0.0% (threshold: 85.0%)"
        },
        {
          "severity": "warning",
          "component": "apis",
          "message": "Some APIs are down: nrces_snomed"
        },
        {
          "severity": "warning",
          "component": "quality",
          "message": "Coding quality issues detected"
        }
      ],
      "metrics": {
        "uptime": 99.9,
        "throughput": 1,
        "error_rate": 0.0,
        "api_performance": {
          "avg_response_time_ms": 150,
          "success_rate": 99.5
        }
      }
    }
  }
}

{
  "success": false,
  "errors": [
    {
      "source": "field_name",
      "title": "Error message description"
    }
  ]
}

{
  "success": false,
  "errors": [
    {
      "source": "medicine",
      "title": "Medicine not found"
    }
  ]
}

{
  "success": false,
  "errors": [
    {
      "source": "query",
      "title": "Query must be at least 2 characters"
    }
  ]
}

// hooks/useTerminologyAPI.js
import { useState, useEffect } from 'react';

export const useTerminologyDashboard = () => {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchDashboard = async () => {
      try {
        const response = await fetch('/admin/terminology', {
          headers: {
            'Authorization': `Bearer ${getAuthToken()}`,
            'Content-Type': 'application/json'
          }
        });
        
        const result = await response.json();
        
        if (result.success) {
          setData(result.data);
        } else {
          setError(result.errors?.[0]?.title || 'Unknown error');
        }
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchDashboard();
  }, []);

  return { data, loading, error };
};

// components/TerminologyDashboard.jsx
import React from 'react';
import { useTerminologyDashboard } from '../hooks/useTerminologyAPI';

const TerminologyDashboard = () => {
  const { data, loading, error } = useTerminologyDashboard();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div className="terminology-dashboard">
      <h1>Terminology Management</h1>
      
      <div className="stats-grid">
        <div className="stat-card">
          <h3>Total Medicines</h3>
          <p>{data.stats.total_medicines.toLocaleString()}</p>
        </div>
        
        <div className="stat-card">
          <h3>Coded Medicines</h3>
          <p>{data.stats.coded_medicines.toLocaleString()}</p>
        </div>
        
        <div className="stat-card">
          <h3>FHIR Ready</h3>
          <p>{data.stats.fhir_ready.toLocaleString()}</p>
        </div>
        
        <div className="stat-card">
          <h3>Pending Review</h3>
          <p>{data.stats.pending_review.toLocaleString()}</p>
        </div>
      </div>

      <div className="country-breakdown">
        <h2>Coverage by Country</h2>
        {data.stats.by_country.map(country => (
          <div key={country.country} className="country-stat">
            <span>{country.country}</span>
            <span>{country.coded}/{country.total}</span>
            <span>{country.coverage}%</span>
          </div>
        ))}
      </div>
    </div>
  );
};

// components/MedicineReview.jsx
import React, { useState, useEffect } from 'react';

const MedicineReview = () => {
  const [medicines, setMedicines] = useState([]);
  const [filters, setFilters] = useState({
    country: '',
    confidence_range: '',
    page: 1
  });
  const [pagination, setPagination] = useState({});

  const fetchMedicines = async () => {
    const params = new URLSearchParams(
      Object.fromEntries(
        Object.entries(filters).filter(([key, value]) => value !== '')
      )
    );
    
    const response = await fetch(`/admin/terminology/review?${params}`, {
      headers: {
        'Authorization': `Bearer ${getAuthToken()}`,
        'Content-Type': 'application/json'
      }
    });
    
    const result = await response.json();
    if (result.success) {
      setMedicines(result.data.medicines);
      setPagination(result.data.pagination);
    }
  };

  useEffect(() => {
    fetchMedicines();
  }, [filters]);

  const updateMedicine = async (medicineId, updateData) => {
    const response = await fetch(`/admin/terminology/${medicineId}`, {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${getAuthToken()}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updateData)
    });
    
    const result = await response.json();
    if (result.success) {
      // Refresh the list
      fetchMedicines();
    } else {
      console.error('Update failed:', result.errors);
    }
  };

  return (
    <div className="medicine-review">
      <div className="filters">
        <select 
          value={filters.country} 
          onChange={(e) => setFilters({...filters, country: e.target.value, page: 1})}
        >
          <option value="">All Countries</option>
          <option value="IN">India</option>
          <option value="US">United States</option>
          <option value="AE">UAE</option>
        </select>
        
        <select 
          value={filters.confidence_range} 
          onChange={(e) => setFilters({...filters, confidence_range: e.target.value, page: 1})}
        >
          <option value="">All Confidence</option>
          <option value="low">Low (&lt; 0.3)</option>
          <option value="medium">Medium (0.3-0.7)</option>
          <option value="high">High (&gt; 0.7)</option>
        </select>
      </div>

      <div className="medicines-list">
        {medicines.map(medicine => (
          <MedicineCard 
            key={medicine.id} 
            medicine={medicine} 
            onUpdate={updateMedicine}
          />
        ))}
      </div>

      <div className="pagination">
        <button 
          disabled={pagination.page === 1}
          onClick={() => setFilters({...filters, page: pagination.page - 1})}
        >
          Previous
        </button>
        
        <span>Page {pagination.page} of {pagination.total_pages}</span>
        
        <button 
          disabled={pagination.page === pagination.total_pages}
          onClick={() => setFilters({...filters, page: pagination.page + 1})}
        >
          Next
        </button>
      </div>
    </div>
  );
};

// Medicine card component for updating individual medicines
const MedicineCard = ({ medicine, onUpdate }) => {
  const [editing, setEditing] = useState(false);
  const [formData, setFormData] = useState({
    snomed_code: medicine.snomed_code || '',
    country_specific_code: medicine.country_specific_code || '',
    ndc_code: medicine.ndc_code || '',
    coding_status: medicine.coding_status || 'pending',
    coding_confidence: medicine.coding_confidence || ''
  });

  const handleSubmit = async (e) => {
    e.preventDefault();
    
    // Filter out empty values
    const updateData = Object.fromEntries(
      Object.entries(formData).filter(([key, value]) => value !== '')
    );
    
    await onUpdate(medicine.id, updateData);
    setEditing(false);
  };

  return (
    <div className="medicine-card">
      <div className="medicine-info">
        <h3>{medicine.name}</h3>
        <p>Manufacturer: {medicine.manufacturer}</p>
        <p>Country: {medicine.country}</p>
        <p>Status: {medicine.coding_status}</p>
        <p>Confidence: {(medicine.coding_confidence * 100).toFixed(1)}%</p>
        <p>FHIR Ready: {medicine.fhir_ready ? 'Yes' : 'No'}</p>
      </div>
      
      {editing ? (
        <form onSubmit={handleSubmit} className="edit-form">
          <input
            type="text"
            placeholder="SNOMED Code"
            value={formData.snomed_code}
            onChange={(e) => setFormData({...formData, snomed_code: e.target.value})}
          />
          <input
            type="text"
            placeholder="Country Code (RxNorm/CDCI)"
            value={formData.country_specific_code}
            onChange={(e) => setFormData({...formData, country_specific_code: e.target.value})}
          />
          <input
            type="text"
            placeholder="NDC Code"
            value={formData.ndc_code}
            onChange={(e) => setFormData({...formData, ndc_code: e.target.value})}
          />
          <select
            value={formData.coding_status}
            onChange={(e) => setFormData({...formData, coding_status: e.target.value})}
          >
            <option value="pending">Pending</option>
            <option value="partial">Partial</option>
            <option value="complete">Complete</option>
            <option value="failed">Failed</option>
          </select>
          <input
            type="number"
            step="0.01"
            min="0"
            max="1"
            placeholder="Confidence (0.0-1.0)"
            value={formData.coding_confidence}
            onChange={(e) => setFormData({...formData, coding_confidence: e.target.value})}
          />
          <div className="form-actions">
            <button type="submit">Save</button>
            <button type="button" onClick={() => setEditing(false)}>Cancel</button>
          </div>
        </form>
      ) : (
        <button onClick={() => setEditing(true)}>Edit Codes</button>
      )}
    </div>
  );
};

// Test 1: Update single field
const response1 = await fetch('/admin/terminology/196', {
  method: 'PATCH',
  headers: headers,
  body: JSON.stringify({ "coding_status": "complete" })
});

// Test 2: Update multiple fields
const response2 = await fetch('/admin/terminology/196', {
  method: 'PATCH',
  headers: headers,
  body: JSON.stringify({
    "snomed_code": "387458008",
    "country_specific_code": "RX789012",
    "ndc_code": "54321-987-65",
    "coding_status": "complete",
    "coding_confidence": 0.98
  })
});

// Test 3: Invalid request (should fail)
const response3 = await fetch('/admin/terminology/196', {
  method: 'PATCH',
  headers: headers,
  body: JSON.stringify({}) // Empty body - will be rejected
});

// Test 4: Invalid confidence (should fail)
const response4 = await fetch('/admin/terminology/196', {
  method: 'PATCH',
  headers: headers,
  body: JSON.stringify({ "coding_confidence": 1.5 }) // > 1.0 - will be rejected
});

config.active_job.queue_adapter = :sidekiq

# Process all uncoded medicines (batch size: 100)
rake terminology:process_uncoded

# Process high-priority medicines (prescribed medicines first)
rake terminology:process_priority

# Process medicines by country
rake terminology:process_country COUNTRY=US

# Get statistics and available tasks
rake terminology:stats

# Generate detailed quality report
rake terminology:quality_report

# Export medicines for manual review (saves CSV to tmp/)
rake terminology:export_for_review

# Import manual coding corrections
rake terminology:import_corrections CORRECTIONS_FILE=path/to/corrections.csv

# Validate existing medicine codes
rake terminology:validate_codes

# Fix common coding issues
rake terminology:fix_coding_issues