Промпт для технического писателя и создания документации

Для демонстрации работы я выбрал следующий сценарий: разработчик просит описать эндпоинт API для системы управления складом.

Входные данные от пользователя: «Напиши доку на метод POST /inventory/adjust. Он нужен, чтобы менять количество товара на складе. Передаем ID товара, количество и причину (списание или приход). Нужно описание JSON и пример».

1. Контекст и цель

Документирование эндпоинта для корректировки остатков на складе. Цель — предоставить бэкенд- и фронтенд-разработчикам спецификацию для интеграции функционала инвентаризации.

2. Ответ модели: Спецификация API

POST /inventory/adjust Метод изменяет текущее количество единиц товара.

Request Body (JSON):

• product_id (string, required): UUID товара.

• adjustment_value (integer, required): Число единиц (положительное для прихода, отрицательное для списания).

• reason (enum, required): Причина («restock», «damage», «sale_return», «write_off»).

Пример запроса:

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "adjustment_value": -5,
  "reason": "damage"
}

Ответы:

• 200 OK: Успешное обновление. Возвращает new_balance.

• 400 Bad Request: Недостаточно остатка для списания или неверный формат данных.

3. Допущения и ограничения

• Авторизация через Bearer Token (в заголовках).

• Система не позволяет уходить в отрицательный остаток.

• Изменение происходит атомарно.

4. Критерии приемки и чеклист

• [ ] Описаны все обязательные поля и типы данных.

• [ ] Указаны возможные значения для reason.

• [ ] Приведены коды ответов (200, 400). Критерий: Разработчик может реализовать запрос без уточняющих вопросов.

5. Следующий шаг

Передача спецификации Frontend-разработчику для реализации формы списания.

...