Skill (ru)

# Навык: Проверить баланс по track (iiko)

## Что делает
Загружает кошельковые балансы гостя из iiko по `cardTrack`.

Если гость не найден (iiko возвращает 404), функция возвращает результат `not_found` вместо генерации исключения.

## Входные данные
- `settings: IikoSettings` (конфигурация клиента из переменных окружения)
- `organization_id: str` (необязательный явный iiko loyalty organization id)
- `all_organizations: bool` (если `True`, команда обрабатывает все найденные организации по очереди; иначе по умолчанию использует первую найденную организацию)
- `card_track: str` (track-номер гостя)
- `transport: IikoTransport` (HTTP транспорт; можно подменить в тестах)
- `token_provider: Callable[[IikoSettings], Awaitable[str]]` (по умолчанию `shared.auth.get_access_token`)

В CLI: `--use-local-env` / `--no-use-local-env`; в MCP: `use_local_env` (см. `IIKO_DEFAULT_USE_LOCAL_ENV`).

## Выходные данные
`dict[str, Any]` со структурой:
- Гость найден:
  - `status: "found"`
  - `guest_id: <id customer>`
  - `card_track: <входной track>`
  - `wallet_balances: <список>` (по возможности; пустой список если поле отсутствует/невалидно)
- Гость не найден:
  - `status: "not_found"`
  - `guest_id: ""`
  - `card_track: <входной track>`
  - `wallet_balances: []`

## Как работает (реализация)
1. Получает iiko access token через `shared.auth.get_access_token` (или через внедрённый `token_provider`).
2. Разрешает организации:
   - использует `organization_id`, если он передан явно
   - иначе по умолчанию использует первую найденную организацию
   - если `all_organizations=True`, выполняет команду для всех найденных организаций по очереди
3. Делает поиск гостя по `cardTrack` через `shared.customers.get_customer_by_card_track`:
   - POST `/loyalty/iiko/customer/info`
4. Обрабатывает “не найдено”:
   - если `IikoApiError.status_code == 404`, возвращаем `not_found`
   - при любом другом статусе исключение пробрасывается
5. Парсит `walletBalances`:
   - если это список — возвращаем как есть
   - иначе — возвращаем пустой список

## Используемые общие модули
- `src/iiko_api_mcp_server/config.py` (`IikoSettings`)
- `src/iiko_api_mcp_server/shared/auth.py` (`get_access_token`)
- `src/iiko_api_mcp_server/shared/http.py` (`IikoTransport`, маппинг ошибок)
- `src/iiko_api_mcp_server/shared/customers.py` (хелпер поиска гостя)
- `src/iiko_api_mcp_server/commands/check_balance.py` (координационная логика)

## Тестирование
Юнит-тесты находятся в:
- `tests/commands/test_check_balance.py`

Тесты проверяют:
- путь “найден” (возвращается `status="found"` и сохраняются `walletBalances`)
- путь “не найден” (404 маппится в `status="not_found"` и balances пустой)
- по умолчанию при нескольких организациях используется первая найденная организация
- CLI корректно передаёт opt-in флаг `--all-organizations`

В тестах используется `RecordingTransport` и фейковый token provider, чтобы не обращаться к live iiko.

## Чеклист отладки
1. Запустить точечные тесты:
   - `python -m pytest tests/commands/test_check_balance.py -v`
2. Если парсинг выглядит неверно, проверьте формат `walletBalances` в `RecordingTransport.responses`.
3. Убедитесь, что маппинг “404 => not_found” работает.