From 151676df2b612568124d50d7ebb9d9e31ebb807a Mon Sep 17 00:00:00 2001
From: Andrey Kutin <adwet@yandex.ru>
Date: Fri, 23 Oct 2026 20:39:45 +0300
Subject: [PATCH] docs: update API and schema documentation

---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 46 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index aeb39eb..b5f293b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # cards
 
-Веб-сервер на C++20 с использованием Boost.Beast и PostgreSQL. Отдаёт случайные записи из базы данных по REST API.
+Веб-сервер на C++20 с использованием Boost.Beast и PostgreSQL. Отдаёт случайные записи из таблицы `random_data` по HTTP API.
 
 ## Требования
 
@@ -22,6 +22,8 @@ sudo apt-get install libboost-all-dev libpq-dev libpqxx-dev nlohmann-json3-dev c
 ./configure.sh
 ```
 
+Скрипт устанавливает зависимости для Debian/Ubuntu, собирает проект и создаёт deb-пакет.
+
 Или вручную:
 
 ```bash
@@ -44,19 +46,19 @@ cd ..
 ### Поля `config.json`
 
 **server**
-| Поле | Тип | Значение по умолчанию |
+| Поле | Тип | Обязательно |
 |---|---|---|
-| address | string | `"0.0.0.0"` |
-| port | int | `8080` |
-| threads | int | `4` |
+| address | string | да |
+| port | int | да |
+| threads | int | да |
 
 **database**
 | Поле | Тип | Значение по умолчанию |
 |---|---|---|
 | host | string | `"localhost"` |
 | port | int | `5432` |
-| dbname | string | `"testdb"` |
-| user | string | `"postgres"` |
+| dbname | string | пустая строка |
+| user | string | пустая строка |
 | password | string | (пусто) |
 
 ### Переменные окружения
@@ -80,21 +82,52 @@ DB_PASSWORD=secret ./build/bin/cards
 | Метод | Путь | Описание |
 |---|---|---|
 | GET | `/` | Случайная запись из таблицы `random_data` |
+| GET | `/cards?count=N` | До `N` случайных записей из таблицы `random_data` |
 | GET | `/health` | Проверка состояния сервера |
 
+Параметр `count` обязателен для `/cards`, должен быть целым числом и ограничивается диапазоном от 1 до 1000. Если записей в базе меньше запрошенного числа, сервер вернёт все доступные записи. Для выборок до 10 записей применяется обычная стратегия, для бо́льших — рекурсивный SQL-запрос.
+
 ### Пример ответа `GET /`
 
 ```json
 {
     "id": 3,
     "name": "Gamma",
-    "value": 300,
+    "text": "Third test record",
     "description": "Third test record",
     "created_at": "2025-01-01 12:00:00",
     "timestamp": 1735732800000000000
 }
 ```
 
+### Пример ответа `GET /cards?count=2`
+
+```json
+{
+    "data": [
+        {
+            "id": 3,
+            "name": "Gamma",
+            "text": "Third test record",
+            "description": "Third test record",
+            "created_at": "2025-01-01 12:00:00"
+        },
+        {
+            "id": 5,
+            "name": "Delta",
+            "text": "Fourth test record",
+            "description": "Fourth test record",
+            "created_at": "2025-01-01 12:00:00"
+        }
+    ],
+    "count": 2,
+    "requested_count": 2,
+    "total_available": 5,
+    "strategy": "slow",
+    "timestamp": 1735732800000000000
+}
+```
+
 ### Пример ответа `GET /health`
 
 ```json
@@ -106,7 +139,7 @@ DB_PASSWORD=secret ./build/bin/cards
 
 ## База данных
 
-При первом запуске автоматически создаётся таблица `random_data` и заполняется десятью тестовыми записями.
+При первом запуске автоматически создаётся таблица `random_data`. Начальные данные сервер не добавляет: их необходимо загрузить самостоятельно.
 
 Схема таблицы:
 
@@ -114,12 +147,14 @@ DB_PASSWORD=secret ./build/bin/cards
 CREATE TABLE random_data (
     id          SERIAL PRIMARY KEY,
     name        VARCHAR(100) NOT NULL,
-    value       INTEGER NOT NULL,
+    text        TEXT NOT NULL,
     description TEXT,
     created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 ```
 
+> При обновлении существующей базы данных схему нужно мигрировать отдельно: `CREATE TABLE IF NOT EXISTS` не изменяет уже созданные таблицы. Например, для предыдущей схемы с полем `value` выполните `ALTER TABLE random_data RENAME COLUMN value TO text;`.
+
 ## systemd
 
 Юнит-файл: `deploy/systemd/cards.service`
@@ -158,7 +193,7 @@ cmake ..
 cpack
 ```
 
-Результат: `cards-1.0.0-Linux.deb`
+Результат: `cards-1.0.1-Linux.deb`
 
 ### Содержимое deb-пакета