Один расчёт.
Одна согласованная модель.

• Архитектура
• Данные
• Алгоритм расчёта
• Контракты API
• Безопасность
• Эксплуатация

1. Архитектура v1

Браузер
  │ HTTP :3000 · Next.js / React / TypeScript
  │ GET страницы, SVG, HTML-документация
  │ fetch('/api/...') — тот же origin
  ▼
Next.js rewrite /api/*
  │ HTTP loopback :5080, API_URL на стороне сервера
  ▼
ASP.NET Core 10 · C# Minimal API
  ├─ Каталог и зоны (серверные константы)
  ├─ Валидация и расчёт decimal
  ├─ Ограничение запросов
  └─ PortalStore · SemaphoreSlim
       └─ App_Data/portal.json (атомарная замена файла)

Стек выбран в соответствии с запросом: C# на бэкенде и Next.js/React на фронтенде. Не используется подмена C# логики обработчиками Next.js. Весь расчёт цены и создание заявки выполняются в API.

ADR-02: серверный proxy позволяет браузеру использовать один origin. CORS для прямого доступа к API не включён. Оба процесса по умолчанию слушают только 127.0.0.1. ADR-03: нет оплаты и состояния «Подтверждено», пока не реализованы поставщики, остатки и диспетчеризация.

2. Модель данных

Product 1 ─── N Quote 1 ─── 0..1 Order
Zone    1 ─── N Quote

Order содержит полный снимок Quote.
Product и Zone живут в Catalog (код).
Quote и Order сохраняются в одном StoreState (JSON).
Receipt — ограниченная проекция Order для клиента.

Ссылочная целостность проверяется приложением при создании расчёта. Заявка сохраняет снимок, поэтому последующие изменения каталога не изменяют уже зафиксированную сумму. Устаревшие свободные расчёты очищаются при следующем создании расчёта; снимки в заявках остаются. Автоматической очистки заявок нет.

Точность

Деньги — C# decimal, округление до копеек AwayFromZero. Объём при переводе тонн округляется вверх до 0,001 м³, чтобы не занизить загрузку машины. Отображаемая масса округляется до 0,001 т. Число рейсов вычисляется по неокруглённой массе из нормализованного объёма. Даты API — UTC ISO 8601, дата поставки — календарная YYYY-MM-DD по Москве.

3. Алгоритм расчёта

Вход: productId, quantity, unit ∈ {m3, t}, zoneId
1. Проверить материал и зону.
2. quantity > 0 и ≤ 1000.
3. rawVolume = unit == t ? quantity / density : quantity.
4. volume = ceil(rawVolume × 1000) / 1000.
5. Проверить 3 ≤ volume ≤ 500.
6. weightExact = volume × density.
7. trips = pickup ? 0 : ceil(max(volume / 12, weightExact / 20)).
8. materialCost = round(volume × price, 2, AwayFromZero).
9. deliveryCost = trips × zone.pricePerTrip.
10. total = materialCost + deliveryCost.
11. Зафиксировать расчёт; expiresAt = UTC now + 24h.

Объёмный помощник на фронтенде: V = площадь(м²) × слой(см) / 100. Он не включает коэффициент уплотнения, потери или технологический запас. Пользователь переносит результат в серверный калькулятор.

4. HTTP API

Base URL для прямых локальных запросов: http://127.0.0.1:5080; браузер обращается к http://127.0.0.1:3000/api. JSON: camelCase, UTF-8, числа в машинном формате с точкой. Лимит тела — 16 КБ. Некорректный JSON и несовместимые типы дают HTTP 400; инфраструктурные ошибки — Problem Details 500 без внутренних подробностей.

Для всех операций, кроме health: максимум 60 запросов в минуту на IP, без очереди; превышение — 429. Тело 429 может быть пустым. Прокси пересылает запросы с loopback, поэтому в текущем локальном режиме лимит фактически общий для браузеров этого сервера.

Создание расчёта

POST /api/quotes
Content-Type: application/json

{"productId":"sand-quarry","quantity":10,"unit":"m3","zoneId":"near"}

200 OK
{
  "id": "<32 hex>",
  "productId": "sand-quarry", "productName": "Песок карьерный",
  "quantity": 10, "unit": "m3", "volume": 10, "weight": 15,
  "zoneId": "near", "zoneName": "До 30 км от МКАД", "trips": 1,
  "materialCost": 6500, "deliveryCost": 6500, "total": 13000,
  "currency": "RUB", "expiresAt": "<UTC ISO 8601>",
  "tariffVersion": "demo-v1", "isEstimate": true
}

Создание заявки

POST /api/orders
{
  "quoteId": "<id расчёта>",
  "name": "Тестовый клиент", "phone": "+7 900 000-00-00",
  "address": "Тестовый объект, улица 1",
  "deliveryDate": "<сегодня..+90 дней, YYYY-MM-DD>",
  "customerType": "private", "company": null,
  "comment": "Нужен подъезд для самосвала", "consent": true
}

201 Created → Receipt
{
  "id":"KR-<12 hex>", "token":"<64 hex>",
  "status":"Новая заявка", "total":13000,
  "productName":"Песок карьерный", "volume":10,
  "deliveryDate":"<YYYY-MM-DD>", "createdAt":"<UTC ISO 8601>"
}

Цена в OrderRequest отсутствует. Лишние JSON-поля игнорируются стандартным десериализатором и не меняют итог. При повторе одного quoteId с теми же именем и телефоном возвращается прежний Receipt, даже если повторное тело содержит другой комментарий или дату: заявка не обновляется. Для изменений нужен новый расчёт.

Валидация заявки

Проверка заявки

GET /api/orders/KR-…
X-Order-Token: <64 hex>

200 → Receipt
404 → {"message":"Заявка не найдена или код доступа неверен"}

Общий формат доменной ошибки: {"message":"Текст для пользователя"}. Фронтенд обрабатывает также пустые/не-JSON ответы и недоступность API; не показывает успешную отправку до ответа сервера. Во время запроса кнопка блокируется. Устаревший ответ расчёта после изменения параметров отбрасывается по локальной ревизии.

5. Безопасность и ограничения

В v1 нет сторонних аналитических трекеров и удалённых шрифтов; изображения — собственные локальные SVG. Метаданные запрещают индексацию демо. Эти меры не делают прототип готовым для публичного приёма реальных данных.

6. Хранение, эксплуатация и развёртывание

Один процесс API. SemaphoreSlim сериализует операции чтения/изменения/записи. Новый JSON сначала пишется во временный файл, затем заменяет основной в той же директории. Это защищает от частичной записи при обычном завершении операции, но не заменяет транзакционную БД, fsync и резервное копирование. Несколько процессов с одним файлом запрещены.

Путь: DataDirectory из конфигурации, по умолчанию backend/Karerchik.Api/App_Data. Каталог создаётся автоматически. Ошибка чтения JSON не приводит к тихой потере данных — запрос завершается ошибкой. На диске данные не зашифрованы. Автоматической очистки заказов и интерфейса удаления нет.

Запуск Windows

# Из папки v1:
powershell -ExecutionPolicy Bypass -File .scriptsstart.ps1
# Портал: http://127.0.0.1:3000
# API:    http://127.0.0.1:5080/api/health

# Остановка только процессов проекта:
powershell -ExecutionPolicy Bypass -File .scriptsstop.ps1

# Проверки:
dotnet build .ackendKarerchik.Api -c Release
cd frontend
npm ci
npm run build
npm run typecheck
cd ..
node --test tests/api.test.mjs

Требуются .NET SDK 10 и Node.js 24 (проверено в среде проекта). Пакеты фронтенда фиксируются package-lock.json; запускать npm ci. API не использует внешние NuGet-пакеты. Скрипт start использует production-сборку Next.js, при её отсутствии выполняет сборку.

Восстановление и резервная копия

1. Остановить оба процесса штатным скриптом.
2. Скопировать App_Data/portal.json в защищённое резервное хранилище.
3. Для восстановления заменить файл из копии при остановленном API.
4. Запустить, проверить health и известную тестовую заявку по номеру и секрету.

Не включать рабочие заявки, токены, логи и зависимости в Git. Каталог App_Data исключён .gitignore. Тесты используют отдельное временное хранилище и не затрагивают рабочие заявки.

Нефункциональные требования

7. Источники по стеку

Next.js — официальная установка; Microsoft Learn — ASP.NET Core APIs. Версии npm проверены 16.10.2026: Next.js 16.4.2, React 19.3.1; фактические зависимости зафиксированы lockfile.