# API OrbitDesk — локальная лаборатория

Редакция QA Orbit · API-CORE-1 · 2026-10-28.1

Это исполняемая **учебная модель**, а не настоящее приложение и не API портала QA Orbit. Все пользователи, токены и задачи синтетические. Не добавляйте реальные данные. Процесс не обращается наружу и слушает только `127.0.0.1`. Данные находятся в памяти; остановка/перезапуск их удаляет. Лабораторные методы snapshot/reset позволяют видеть все учебные объекты и не являются образцом production-безопасности.

## Подготовка

1. Создайте отдельную папку, например `qa-orbit-api-practice`.
2. Скачайте в неё `api-lab.mjs`, `check-lab.mjs`, `contract.md` и при желании `orbitdesk.postman_collection.json` из курса. Прочитайте исходники перед выполнением.
3. Нужен поддерживаемый Node.js 22.13+ (подойдут текущие 24/26). Проверьте `node --version`. Зависимостей нет, `npm install` не нужен.

В первом терминале из этой папки:

```bash
node api-lab.mjs
```

Ожидается сообщение: `listening at http://127.0.0.1:4177`. Если порт занят, выберите свободный:

```bash
QA_ORBIT_API_PORT=4178 node api-lab.mjs
```

Переменная задаётся в этом запуске; не используйте публичный интерфейс. В Windows PowerShell перед запуском задайте `$env:QA_ORBIT_API_PORT='4178'`, затем `node api-lab.mjs`.

## Первый запрос

Во втором терминале:

```bash
curl -i http://127.0.0.1:4177/tasks \
  -H 'Authorization: Bearer demo-anna' \
  -H 'Content-Type: application/json' \
  --data '{"title":"План"}'
```

Ожидаются 201, Location, JSON с новым ID, authorId=u-a, team=north, state=draft, description="", priority=normal. ID берите из ответа; он не обязан быть конкретным t5, если запросы уже выполнялись. Curl в Windows PowerShell используйте как `curl.exe` либо импортируйте коллекцию Postman.

## Автоматическая самопроверка

Второй терминал, пока сервер работает:

```bash
node check-lab.mjs
```

Для порта 4178:

```bash
QA_ORBIT_API_URL=http://127.0.0.1:4178 node check-lab.mjs
```

PowerShell: `$env:QA_ORBIT_API_URL='http://127.0.0.1:4178'; node check-lab.mjs`.

Скрипт проверяет реальные локальные HTTP-ответы и снимки. Он сбрасывает **только синтетическую лабораторию** до и после; параллельно не выполняйте свои запросы к тому же процессу. Число `checks passed` является результатом модели в этих условиях, не оценкой production-сервиса. При ошибке читайте первое assertion и сравнивайте контракт. `Connection refused` означает, что стенд/порт недоступен; это не HTTP 500.

## Postman

Импортируйте `orbitdesk.postman_collection.json`. Проверьте переменную коллекции baseUrl (`http://127.0.0.1:4177`, либо выбранный порт), studentToken=`demo-anna`. Не подключайте реальный production-адрес и реальные токены. Локальный запрос должен отправляться из клиента/агента, имеющего доступ к вашему 127.0.0.1. Запускайте всю последовательность по порядку: Reset→Create→Read→Publish→Repeat. Не запускайте параллельно с check-lab.mjs: оба используют reset. Перед Create taskId очищается; Read/Publish работают с ID нового ответа. Каждый request содержит assertions.

## Управление состоянием

```bash
curl -s http://127.0.0.1:4177/__lab/snapshot -H 'X-Lab-Key: local-only'
curl -s -X POST http://127.0.0.1:4177/__lab/reset -H 'X-Lab-Key: local-only'
```

Reset восстанавливает четыре начальные задачи из contract.md и счётчик. Не выполняйте reset между первым и повторным publish, если проверяете переход.

## Остановка

В первом терминале нажмите **Ctrl+C**. Сервер завершится и данные исчезнут. Не оставляйте учебный процесс работающим после занятия. В последующем запуске модель начинается с начальных данных.

## Ограничения

Нет настоящей регистрации, секретного хранилища, БД, распределённых сервисов, персистентности, SLA и проверки нагрузки. Публичные demo-токены — учебный переключатель роли. Снимки/сброс намеренно доступны только локальной модели по известному ключу. Ошибочные трассы в workbook — отдельные задания для анализа; корректный lab не обязан воспроизводить эти нарушения. Офлайн-режим возможен без запуска: проектируйте запросы и отмечайте их Not run.

Технические источники: [HTTP RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html), [Postman scripts](https://learning.postman.com/docs/tests-and-scripts/write-scripts/test-scripts/). Код и учебный контракт написаны для QA Orbit.