WMS REST API

REST API для склада: авторизация по JWT, управление пользователями и группами, справочники (категории, ячейки, товары), операции приёмки/выдачи, складские остатки, дашборд и отчёты.

JWT MySQL Express Multer (upload)

Быстрый старт

Выполните логин через POST /users/login (демо: admin/admin), получите access и refresh токены.
Передавайте заголовок Authorization: Bearer <accessToken> для всех защищённых эндпойнтов.
При истечении accessToken обновите его через POST /users/refresh-token.

curl -X POST {{BASE_URL}}/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

Состояние API

База URL: —
Авторизация: JWT (Bearer)
Версия Bootstrap: 5.3.x
Ответы: application/json
Защита статики /assets: требует JWT

Аутентификация

Все защищённые эндпойнты требуют заголовок Authorization: Bearer <accessToken>. Токены выдаются после логина, обновление — по refresh-токену.

POST /users/login

PUBLIC

Вход по логину/паролю. В демо значения подставлены: admin/admin.

Body application/json: {"username": "admin", "password": "admin"}
Успех 200: {"accessToken": "...", "refreshToken": "...", "user": {...}}

curl -X POST {{BASE_URL}}/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

const res = await fetch(`${BASE_URL}/users/login`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({username:'admin', password:'admin'})
});
const data = await res.json();
localStorage.setItem('accessToken', data.accessToken);
localStorage.setItem('refreshToken', data.refreshToken);

Пример ответа

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "UserID": 1,
    "Username": "admin",
    "UserFullName": "Администратор",
    "UserLevel": 1,
    "UserStatus": 1,
    "LastLoginDate": "2025-08-06 10:30:00"
  }
}

POST /users/refresh-token

PUBLIC

Обновите access-токен с помощью refresh-токена.

Body application/json: {"refreshToken": "..."}
Успех 200: {"accessToken": "..."}

curl -X POST {{BASE_URL}}/users/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"REFRESH_TOKEN"}'

Пользователи

CRUD над пользователями, управление аватаром, вход, обновление токена. Пароли в демо могут храниться в MD5; для боевой среды используйте bcrypt/argon2.

Метод	Путь	Описание	Тело	Примечания
GET	/users	Список пользователей	–	Требует JWT
GET	/users/:id	Пользователь по ID	–	JWT
POST	/users	Создать пользователя	JSON + optional avatar	JWT
PUT	/users/:id	Обновить пользователя	JSON	JWT
DELETE	/users/:id	Удалить пользователя	–	JWT
POST	/users/:id/avatar	Загрузить/заменить аватар	multipart/form-data `avatar`	JWT
GET	/users/:id/avatar	Получить аватар	–	JWT
DELETE	/users/:id/avatar	Удалить аватар	–	JWT
POST	/users/login	Логин	JSON	Публичный
POST	/users/refresh-token	Обновление access	JSON	Публичный

curl -X GET {{BASE_URL}}/users \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Пример ответа

[
  {"UserID":1,"Username":"admin","UserFullName":"Администратор","UserLevel":1,"UserStatus":1},
  {"UserID":2,"Username":"manager","UserFullName":"Менеджер","UserLevel":2,"UserStatus":1}
]

Группы

Группы доступа (уровни/статусы). Нельзя удалить группу, если к ней привязаны пользователи.

Метод	Путь	Описание	Тело	Примечания
GET	/groups	Список групп	–	JWT
GET	/groups/:id	Группа по ID	–	JWT
POST	/groups	Создать группу	JSON	JWT
PUT	/groups/:id	Обновить группу	JSON	JWT
DELETE	/groups/:id	Удалить группу	–	JWT

Категории

Простой CRUD. При удалении категория не должна быть связана с товарами.

Метод	Путь	Описание	Тело	Примечания
GET	/categories	Список категорий	–	JWT
GET	/categories/:id	Категория по ID	–	JWT
POST	/categories	Создать	JSON	JWT
PUT	/categories/:id	Обновить	JSON	JWT
DELETE	/categories/:id	Удалить	–	JWT

Товары

CRUD и загрузка изображения. Перед удалением проверяется использование товара (склад/приёмки/выдачи).

Метод	Путь	Описание	Тело	Примечания
GET	/products	Список	–	JWT (есть режим с категориями)
GET	/products/:id	По ID	–	JWT
POST	/products	Создать	JSON	JWT
PUT	/products/:id	Обновить	JSON	JWT
DELETE	/products/:id	Удалить	–	JWT
POST	/products/upload	Загрузка файла	multipart/form-data `image`	JWT

curl -X POST {{BASE_URL}}/products \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"ProductName":"Demo Product","CategoryID":1,"ProductBarcode":"ABC123","ProductImage":"assets/product/no_image.png"}'

Ячейки склада

CRUD с проверкой зависимостей (склад/приёмки/выдачи) перед удалением.

Метод	Путь	Описание	Тело	Примечания
GET	/cells	Список	–	JWT
GET	/cells/:id	По ID	–	JWT
POST	/cells	Создать	JSON	JWT
PUT	/cells/:id	Обновить	JSON	JWT
DELETE	/cells/:id	Удалить	–	JWT

Склад

Только чтение — остатки управляются исключительно через приёмки/выдачи.

Метод	Путь	Описание	Тело	Примечания
GET	/warehouse	Список остатков	–	JWT
GET	/warehouse/:id	Остаток по ID записи	–	JWT
POST	/warehouse	—	—	Запрещено
PUT	/warehouse/:id	—	—	Запрещено
DELETE	/warehouse/:id	—	—	Запрещено

Приёмки

CRUD. При создании/изменении корректируются остатки склада (добавление/перемещение/дельта).

Метод	Путь	Описание	Тело	Примечания
GET	/receives	Список	–	JWT, есть `?withDetails=true`
GET	/receives/:id	По ID	–	JWT
POST	/receives	Создать	JSON	JWT
PUT	/receives/:id	Обновить	JSON	JWT
DELETE	/receives/:id	Удалить	–	JWT (осторожно с остатками)

Выдачи

CRUD. При изменениях корректируются остатки (уменьшение/перекладка/возврат количества).

Метод	Путь	Описание	Тело	Примечания
GET	/issues	Список	–	JWT, есть `?withDetails=true`
GET	/issues/:id	По ID	–	JWT
POST	/issues	Создать	JSON	JWT
PUT	/issues/:id	Обновить	JSON	JWT
DELETE	/issues/:id	Удалить	–	JWT

Дашборд

Агрегированные метрики и последние события.

GET /dashboard/statistics

JWT

Возвращает счётчики (пользователи, группы, товары и т.д.).

curl -X GET {{BASE_URL}}/dashboard/statistics \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

GET /dashboard/monitoring

JWT

Последние приёмки/выдачи, топ-товары и пр.

curl -X GET {{BASE_URL}}/dashboard/monitoring \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Отчёты

Форматы: receives и issues. Режимы: daily, weekly, monthly, interval.

Метод	Путь	Параметры	Пример	Примечания
GET	/report/:type/daily	`?date=YYYY-MM-DD`	/report/receives/daily?date=2025-08-06	JWT
GET	/report/:type/weekly	`?date=YYYY-MM-DD`	/report/issues/weekly?date=2025-08-06	JWT (берёт нед. интервал)
GET	/report/:type/monthly	`?year=YYYY&month=MM`	/report/receives/monthly?year=2025&month=08	JWT
GET	/report/:type/interval	`?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD`	/report/issues/interval?startDate=2025-08-01&endDate=2025-08-06	JWT

curl -X GET "{{BASE_URL}}/report/receives/daily?date=2025-08-06" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Коды ошибок

Код	Когда	Пример
`400`	Валидация/некорректные параметры	`{"error":"Invalid payload"}`
`401`	Нет/просрочен токен	`{"error":"Unauthorized"}`
`403`	Неверный токен/нет прав	`{"error":"Forbidden"}`
`404`	Не найдено	`{"error":"Not found"}`
`409`	Нарушение ограничений (напр., удаление сущности с зависимостями)	`{"error":"Conflict"}`
`500`	Внутренняя ошибка	`{"error":"Internal server error"}`

Безопасность и замечания

Все эндпойнты (кроме /users/login, /users/refresh-token) требуют JWT.
Путь /assets защищён — раздаётся только при наличии валидного токена.
В демо пароли могут храниться как MD5 — для продакшена используйте bcrypt/argon2.
Склад изменяется только через приёмки/выдачи — прямые правки запрещены.
Важные операции рекомендуется оборачивать в транзакции (особенно приёмки/выдачи).

Примечания

Схема БД ожидает поля вида ProductID, CategoryID, CellID, UserID и т.д.
Изображения грузятся через multer в папки assets/user, assets/product.
Дашборд и отчёты — read-only над агрегированными запросами.