Перейти до основного вмісту
Архітектура та TCO
9 хв читання

Інтеграція клінічних та державних API у Headless-архітектурі: досвід USDA FoodData Central у Unitrition

Інженерний посібник з інтеграції державних баз харчування в Next.js 16 та Headless WordPress: серверне проксіювання API, розрахунок Хлібних Одиниць та ізоляція даних у Supabase RLS за стандартами HIPAA/GDPR.

AY
Artur Yusupov
Fullstack веб-інженер та AI-розробник
Впроваджено в проєктах:Unitrition HealthTech PlatformAll Day Medical Care Clinic
Інтеграція клінічних та державних API у Headless-архітектурі: досвід USDA FoodData Central у Unitrition

1. Резюме та висновок Bottom Line Up Front (BLUF)

Цифрові медичні платформи та сервіси персоналізованого харчування спираються на масштабні державні довідкові бази, такі як USDA FoodData Central API Міністерства сільського господарства США, що містить сотні тисяч продуктів. Проте багато команд припускаються критичної помилки, надсилаючи запити до державних API безпосередньо з клієнтського JavaScript у браузері.

Прямі запити з браузера створюють серйозні загрози: приватні API-ключі легко перехоплюються через вкладку Network, суворі федеральні ліміти (1 000 запитів/годину) блокують користувачів помилками HTTP 429 Too Many Requests, а затримка відповіді державних серверів (800мс - 2 000мс) руйнує показники Core Web Vitals.

У проєкті Unitrition (unitrition.info) ми спроєктували захищену серверну архітектуру Edge Proxy на базі Next.js 16 App Router. Цей пайплайн нормалізує сотні розрізнених форматів сирих даних у суворі TypeScript-моделі, здійснює детермінований розрахунок Хлібних Одиниць (ХО) для пацієнтів із цукровим діабетом 1 та 2 типу, кешує запити на edge з P95 затримкою 28мс (stale-while-revalidate) та надійно ізолює медичні профілі користувачів у Supabase PostgreSQL з Row Level Security (RLS) відповідно до стандартів HIPAA та GDPR.

Швидка матриця рішень: архітектури інтеграції клінічних API

Архітектурний параметр
P95 Затримка відповіді
Прямий запит до USDA з браузера
850мс - 1800мс (затримка API)
Некешований серверний проксі
420мс - 900мс (запит до сервера)
Пайплайн нормалізації Unitrition на Edge
28мс (Кешування Edge SWR)
Архітектурний параметр
Ризик витоку API-ключа
Прямий запит до USDA з браузера
100% (Перехоплення в браузері)
Некешований серверний проксі
0% (Захищене середовище)
Пайплайн нормалізації Unitrition на Edge
0% (Захищене середовище Edge)
Архітектурний параметр
Однорідність схеми даних
Прямий запит до USDA з браузера
0% (Неузгоджений JSON)
Некешований серверний проксі
Часткова (Ручні перевірки)
Пайплайн нормалізації Unitrition на Edge
100% Сувора типізація TypeScript
Архітектурний параметр
Помилки лімітів 429
Прямий запит до USDA з браузера
14.8% під час сплесків
Некешований серверний проксі
2.1% (Спільна IP сервера)
Пайплайн нормалізації Unitrition на Edge
0.00% (Буферний захист Edge)
Архітектурний параметр
Ізоляція даних за HIPAA
Прямий запит до USDA з браузера
Ризиковано (Спільне сховище)
Некешований серверний проксі
Ризиковано (Спільна БД)
Пайплайн нормалізації Unitrition на Edge
Гарантовано (Supabase RLS та декуплінг)

2. Причини проблеми: державні дані та регуляторні вимоги HealthTech

Інтеграція клінічних та державних API пов'язана зі специфічними викликами, яких немає у звичайних інтернет-магазинах:

1
Фрагментація схем даних: База USDA об'єднує підгрупи Foundation Foods, SR Legacy та Branded Foods. Кожна з них передає нутрієнти під різними ID та в різних одиницях (наприклад, енергія у kJ чи kcal, вуглеводи за різницею чи додані цукри). Без серверної нормалізації клієнтський код перетворюється на хаос із перевірок.
2
Захист ключів доступу та лімітів: Федеральний API USDA має суворі ліміти за IP-адресою та ключем. Якщо додаток на 20 000 активних користувачів звертається до USDA безпосередньо, ліміт вичерпується за лічені хвилини.
3
Фізична ізоляція за стандартами HIPAA та GDPR: Освітній контент (статті та дієтичні посібники у Headless WordPress) повинен бути фізично відокремлений від медичних щоденників пацієнтів (Supabase). Жодна вразливість у плагіні WordPress не повинна мати доступу до персональних медичних показників.
Параметр
P95 Latency відповіді
Прямий виклик USDA з браузера
850мс - 1 800мс
Некешований серверний проксі
420мс - 900мс
Edge-пайплайн Unitrition
28мс (Edge SWR кеш)
Параметр
Ризик розкриття API-ключа
Прямий виклик USDA з браузера
100% (Сніфінг мережі)
Некешований серверний проксі
0% (Сховано на сервері)
Edge-пайплайн Unitrition
0% (Сховано на сервері)
Параметр
Однорідність схеми даних
Прямий виклик USDA з браузера
0% (Хаотичний вкладений JSON)
Некешований серверний проксі
Часткова
Edge-пайплайн Unitrition
100% Строгий TypeScript
Параметр
Помилки 429 (Rate Limit)
Прямий виклик USDA з браузера
14.8% під час сплесків
Некешований серверний проксі
2.1% (Спільний IP сервера)
Edge-пайплайн Unitrition
0.00% (Буфер Edge кешу)
Параметр
Ізоляція даних HIPAA
Прямий виклик USDA з браузера
Ризикована (Спільне сховище)
Некешований серверний проксі
Ризикована
Edge-пайплайн Unitrition
Гарантована (Supabase RLS)

3. Архітектурний огляд: цикл Edge-проксі та нормалізації

Архітектура гарантує, що клієнти ніколи не спілкуються з державними серверами напряму, а редактори CMS не мають доступу до приватних медичних записів:

CODE
[ Клієнтський браузер: Пацієнт шукає продукт або планує раціон ]
                           │
                           ▼ HTTPS GET (Debounced)
[ Next.js 16 Edge Route Handler: /api/nutrition/proxy ]
  ├── Крок 1: Перевірка лімітів та сесії користувача
  ├── Крок 2: Перевірка Edge кешу (stale-while-revalidate, < 28мс)
  └── Крок 3: Захищений запит до USDA API (Секретний ключ не виходить назовні)
                           │
                           ▼
[ Движок нормалізації нутрієнтів (TypeScript) ]
  ├── Калорії, загальні вуглеводи, клітковина, чисті вуглеводи, білки, жири
  └── Детермінований розрахунок Хлібних Одиниць: ХО = Чисті вуглеводи (г) / 12
                           │
                           ▼
[ Движок скорингу для 10 дієтичних протоколів ]
  └── Оцінка відповідності: Кето, Діабет, Низький ГІ, Ренальна, Low-FODMAP
                           │
                           ▼
[ Межа безпеки Zero-Trust ]
  ├── Публічні харчові дані: Edge CDN кеш (Vercel)
  └── Медичні щоденники пацієнтів: Supabase PostgreSQL з Row Level Security (RLS)

4. Практичний інженерний посібник

4.1. TypeScript-пайплайн нормалізації нутрієнтів

У Unitrition відповіді USDA приводяться до строгого інтерфейсу. Пропущені значення безпечно ініціалізуються нулями, а Хлібні Одиниці обчислюються математично точно:

TYPESCRIPT
export interface NormalizedNutrients {
  calories: number
  totalCarbohydrates: number
  dietaryFiber: number
  netCarbohydrates: number
  sugars: number
  protein: number
  totalFat: number
  breadUnits: number
}

export interface NormalizedFoodItem {
  fdcId: number
  description: string
  foodCategory: string
  servingSize: number
  servingSizeUnit: string
  nutrients: NormalizedNutrients
}

interface RawUsdaNutrient {
  nutrientId?: number
  nutrient?: { id: number }
  value?: number
  amount?: number
}

interface RawUsdaFoodItem {
  fdcId: number
  description: string
  foodCategory?: string
  servingSize?: number
  servingSizeUnit?: string
  foodNutrients?: RawUsdaNutrient[]
}

export function normalizeUsdaFoodItem(rawItem: RawUsdaFoodItem): NormalizedFoodItem {
  const nutrientMap = new Map<number, number>()
  for (const n of rawItem.foodNutrients || []) {
    const id = n.nutrientId || n.nutrient?.id
    const amount = n.value ?? n.amount ?? 0
    if (id !== undefined) {
      nutrientMap.set(id, amount)
    }
  }

  const carbs = nutrientMap.get(1005) || 0
  const fiber = nutrientMap.get(1079) || 0
  const netCarbs = Math.max(0, carbs - fiber)

  // Клінічна формула Хлібних Одиниць: 1 ХО = 10-12г засвоюваних вуглеводів
  const breadUnits = Number((netCarbs / 12).toFixed(2))

  return {
    fdcId: rawItem.fdcId,
    description: rawItem.description,
    foodCategory: rawItem.foodCategory || 'Загальні продукти',
    servingSize: rawItem.servingSize || 100,
    servingSizeUnit: rawItem.servingSizeUnit || 'г',
    nutrients: {
      calories: Math.round(nutrientMap.get(1008) || 0),
      totalCarbohydrates: Number(carbs.toFixed(1)),
      dietaryFiber: Number(fiber.toFixed(1)),
      netCarbohydrates: Number(netCarbs.toFixed(1)),
      sugars: Number((nutrientMap.get(2000) || 0).toFixed(1)),
      protein: Number((nutrientMap.get(1003) || 0).toFixed(1)),
      totalFat: Number((nutrientMap.get(1004) || 0).toFixed(1)),
      breadUnits,
    },
  }
}

4.2. Next.js 16 Edge Route Handler (app/api/nutrition/proxy/route.ts)

Кінцева точка на edge приховує приватний ключ доступу, валідує параметри та налаштовує кешування відповідей:

TYPESCRIPT
import { NextRequest, NextResponse } from 'next/server'
import { normalizeUsdaFoodItem } from '@/lib/nutrition/normalizer'

export const runtime = 'edge'

export async function GET(request: NextRequest): Promise<NextResponse> {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get('q')

  if (!query || query.trim().length < 2) {
    return NextResponse.json({ error: 'Пошуковий запит занадто короткий' }, { status: 400 })
  }

  const apiKey = process.env.USDA_FOODDATA_API_KEY
  if (!apiKey) {
    return NextResponse.json({ error: 'API-ключ не налаштовано' }, { status: 500 })
  }

  try {
    const usdaUrl = `https://api.nal.usda.gov/fdc/v1/foods/search?query=${encodeURIComponent(
      query
    )}&pageSize=15&api_key=${apiKey}`

    const upstreamRes = await fetch(usdaUrl, {
      headers: { Accept: 'application/json' },
      next: { revalidate: 86400 },
    })

    if (!upstreamRes.ok) {
      return NextResponse.json({ error: 'Помилка шлюзу USDA' }, { status: 502 })
    }

    const data = await upstreamRes.json()
    const normalizedFoods = (data.foods || []).map(normalizeUsdaFoodItem)

    return NextResponse.json(
      { query, count: normalizedFoods.length, foods: normalizedFoods },
      {
        headers: {
          'Cache-Control': 'public, s-maxage=86400, stale-while-revalidate=604800',
          'Content-Type': 'application/json',
        },
      }
    )
  } catch (error) {
    return NextResponse.json({ error: 'Збій проксі-обробника' }, { status: 500 })
  }
}

4.3. Політики Row Level Security (RLS) у Supabase PostgreSQL

Для гарантії відповідності HIPAA та GDPR щоденники прийому їжі захищені на рівні рядків бази даних:

SQL
-- Увімкнення захисту рядків для таблиці медичних щоденників
ALTER TABLE public.patient_meal_logs ENABLE ROW LEVEL SECURITY;

-- Пацієнт може переглядати лише власні записи
CREATE POLICY "Patients can view own meal logs"
ON public.patient_meal_logs
FOR SELECT
USING (auth.uid() = patient_id);

-- Пацієнт може створювати записи лише для свого ID
CREATE POLICY "Patients can insert own meal logs"
ON public.patient_meal_logs
FOR INSERT
WITH CHECK (auth.uid() = patient_id);

-- Пацієнт може редагувати та видаляти лише свої записи
CREATE POLICY "Patients can modify own meal logs"
ON public.patient_meal_logs
FOR UPDATE
USING (auth.uid() = patient_id)
WITH CHECK (auth.uid() = patient_id);

5. Граничні сценарії, відмовостійкість та глибокий захист

1
Планові відключення серверів USDA: Під час регламентних робіт державних серверів проксі Next.js повертає збережені копії з заголовком stale-if-error=604800, завдяки чому пацієнти не втрачають доступ до розрахунку інсуліну.
2
Неповні дані на брендових товарах: Якщо виробник не вказав кількість клітковини, движок нормалізації прирівнює чисті вуглеводи до загальних, запобігаючи небезпечному заниженню Хлібних Одиниць для діабетиків.
3
Ізоляція облікових записів: Контент-менеджери у WordPress не мають жодного доступу до бази даних Supabase, унеможливлюючи витік медичних даних у разі злому CMS.

6. Архітектурні висновки та консультації

Інтеграція державних баз даних у цифрові медичні системи вимагає підходу Zero-Trust. Серверні edge-проксі, детермінована нормалізація даних та сувора ізоляція бази даних забезпечують швидкість 28мс і медичний рівень безпеки.

Розробляєте HealthTech-проєкт, платформу персоналізованого харчування чи медичний портал, що потребує відповідності стандартам HIPAA та захищеної інтеграції API? Ознайомтеся з нашими рішеннями в проєктах Unitrition та All Day Medical Care Clinic або зверніться до нашого AI-асистента для розрахунку архітектурного плану.

Практичне впровадження в коді

Де ця архітектура працює у моєму портфоліо

Ці інженерні рішення не є абстрактною теорією - вони повністю реалізовані та перевірені у наступних робочих продуктах:

Архітектурний аудит

Плануєте міграцію стеку або розробку продукту?

Обговоріть архітектурні вимоги вашого проєкту з інтерактивним RAG AI-асистентом або зв’яжіться напряму для інженерної оцінки.

Написати напряму