Полное руководство по функциональности, архитектуре и использованию

1. Назначение, функции и сценарии применения

Battery Passport на базе Battery Wizard Online решает задачи комплексного управления жизненным циклом аккумуляторных батарей: от первичного ввода паспортных данных до многолетнего накопления результатов испытаний и формирования цифрового следа батареи.

1.1. Основные функции платформы

• Хранение паспортных данных батарей (напряжение, емкость, тип, производитель, габариты, срок службы и др.) в таблице Battery с привязкой к брендам, типам и стандартам.
• Импорт протоколов испытаний с приборов CONBAT (разрядные, зарядные, BSL‑мониторинг, RTA и др.) и автоматическое разнесение измерений по таблицам TestData, BSLData, StringData, CellVoltageData и связанным сущностям.
• Рассчет ключевых диагностических показателей (фактическая емкость, отклонения напряжений по элементам, неравномерность, деградация) и формирование итоговых оценок по методикам обслуживания АБ.
• Представление результатов в виде отчетов, актов и паспортов в HTML/PDF, привязанных к конкретным объектам, системам и компаниям (таблицы Report, AdvancedReport и др.).
• Интеграция через HTTP API v2 с мобильными приложениями и внешними ИС для обмена данными о батареях, тестах и отчетах.
• Управление пользователями, тарифами, правами доступа и аудитом активности (Users, Tarif, Tokens, LogAPI, UserSuspiciousActivity и др.).

1.2. Типовые сценарии применения

2. Архитектура, модули и логическая модель

Архитектура решения основана на классической трехслойной схеме: веб‑клиент, серверное приложение на PHP с использованием APIConfig и реляционная база данных wizard_online, дополненная API v2 для внешних клиентов.

2.1. Логические модули серверной части

• Модуль аутентификации и авторизации (login, токены, роль‑базированное управление доступом, тарифы, блокировки и аудит).
• Модуль импорта и парсинга файлов (определение типа прибора, валидация, запись в File/Files, разбор и сохранение измерений).
• Модуль управления справочниками (бренды, типы батарей, стандарты, приборы, тест‑типы, тарифы).
• Модуль построения отчетов и паспортов (генерация документов по шаблонам, формирование PDF/HTML, учет языков и форматов).
• Модуль API v2 (endpoint‑ы для входа, получения списков батарей, тестов, отчетов, работы с пользователями и т.п.).

2.2. Структура базы данных wizard_online (надуровень)

Структура БД подробно документирована в JSON‑файле wizardonline-mysql-database-docs-info-schema-map.json, который описывает все таблицы, колонки, индексы и связи; при анализе и разработке необходимо опираться именно на него, не выдумывая схему.

Общие правила для внешних ключей: любые поля вида CompanyID, UserID, BrandID, SiteID и т.п. трактуются как связи на таблицы Companies, Users, Brands, Sites и другие по явным или описанным в документации правилам.

3. Подробная логика работы платформы

Ниже приводится детальное описание ключевых бизнес‑процессов: от регистрации и импорта файлов до анализа результатов и формирования цифрового паспорта батареи.

3.1. Регистрация, аутентификация и безопасность

1. Пользователь заполняет регистрационную форму Battery Wizard Online, указывая модель прибора, владельца и контактные данные.
2. Заявка попадает в таблицу UserRegistration (через отдельный backend‑процесс), где хранится, пока не будет подтверждена оператором.
3. После одобрения создается запись в Users с привязкой к компании, тарифу и, при необходимости, к конкретным приборам.
4. При входе пользователь вводит логин/пароль; система валидирует данные, учитывая возможные блокировки (UserBanHistory, UserSuspiciousActivity).
5. При успешном входе создается токен в таблице Tokens (или обновляется RefreshTokens), который используется API клиентами для дальнейших запросов.

Для защиты от brute‑force и взломов используется учет неуспешных попыток входа, IP‑адресов, UserAgent и подозрительной активности с хранением в специализированных таблицах безопасности.

3.2. Импорт файлов испытаний

1. Пользователь выбирает файл (или несколько файлов) протоколов на странице импорта.
2. Файл сохраняется на сервере, создается запись в File (путь, размер, CRC, пользователь).
3. Параллельно создается расширенная запись в Files с бизнес‑метаданными (компания, объект, система, батарея, тип теста, температура, комментарии).
4. PHP‑парсер определяет тип прибора и формат; при ошибке формата создается запись в лог и пользователю возвращается сообщение.
5. Если формат корректен, данные измерений последовательно записываются в таблицы: BSLData (BSL‑мониторинг), StringData (по строкам), CellVoltageData (напряжения по элементам), InternalResistanceData (измерения сопротивления) и др.
6. Еще на этапе импорта возможен предварительный расчет агрегированных показателей и сохранение их в TestSummary или аналогичных таблицах для ускорения последующего анализа.

3.3. Анализ результатов и принятие решений

Интерпретация результатов испытаний опирается на формализованные методики обслуживания стартерных и стационарных АБ, где заданы последовательности шагов, пороговые значения и критерии оценки.

• Для каждого теста рассчитывается фактическая емкость, сравниваемая с номинальной емкостью из Battery, с учетом температурных поправок по TemperatureCoefficients и выбранному стандарту из Standards.
• Оценивается разброс напряжений между элементами; данные берутся из CellVoltageData, рассчитываются показатели «ChangeFromMiddle» и схожие поля, отражающие отклонение от среднего.
• Фиксируются причины остановки теста (StopReason, TestDuration и связанные показатели), важные для анализа режима работы и корректности завершения испытания.
• На основании набора правил принимается решение: батарея исправна, требуется обслуживание, предполагаемый отказ или нарушение правил эксплуатации/гарантии.

3.4. Формирование цифрового паспорта батареи

Цифровой паспорт батареи — это совокупность паспортных и эксплуатационных данных, формируемых на основе таблиц Battery, BatteryTypes, Brands, Files, TestData, StringData и других, доступная через веб‑интерфейс и API.

• Статическая часть паспорта: паспортные параметры модели, производитель, год выпуска, серийный номер, стандарт испытаний, срок службы, габариты, масса, подключение и т.п. (Battery, Brands, BatteryTypes, Standards).
• Динамическая часть: история всех тестов с датами, местами проведения, типами испытаний, режимами, результатами и заключениями (Files, TestData, StringData, Reports и др.).
• Дополнительно паспорт может включать информацию по эксплуатации, ремонту и утилизации, если эти данные заведены в отдельных таблицах и корректно связаны с Battery.

4. Подробная инструкция пользователя

4.1. Вход в систему и первоначальная настройка

1. Перейдите на сайт Battery Wizard Online в браузере, используйте адрес, предоставленный поставщиком решения.
2. Выберите пункт меню «Вход» или «Login» и введите логин и пароль, полученные при регистрации.
3. При первом входе рекомендуется сменить пароль и настроить данные профиля (контакты, язык интерфейса, предпочтения).
4. Администратор компании должен создать структуру компании (филиалы, площадки, системы) и базовый каталог батарей, если это ещё не сделано.

4.2. Работа с протоколами испытаний

1. Откройте раздел «Импорт файлов» или аналогичный раздел, соответствующий вашей конфигурации интерфейса.
2. Нажмите «Выбрать файл», укажите файл (или файлы) с прибора CONBAT, затем подтвердите загрузку.
3. После загрузки система отобразит предварительный статус импорта (успешно/ошибка формата/ошибка доступа и т.п.).
4. При успехе перейдите к списку файлов или к разделу «Испытания» и откройте карточку нужного теста, где будут доступны: графики, таблицы, агрегированные показатели и заключение.

4.3. Просмотр цифрового паспорта батареи

• Перейдите в раздел «Батареи» и выполните поиск по модели, серийному номеру, объекту или другим атрибутам.
• Откройте найденную батарею: в карточке будут представлены паспортные характеристики, история тестов и ссылки на отчеты/акты, связанные с этой батареей.
• Для формирования «паспорта» в формате PDF/HTML воспользуйтесь функцией «Сформировать отчет» или «Печать», выбрав подходящий шаблон.

4.4. Отчеты, фильтры и экспорт

• В разделе «Отчеты» доступны фильтры по дате, объектам, компаниям, приборам, типам тестов и состояниям (успешный, прерванный, отклонение параметров и т.п.).
• Результаты можно выгружать в различные форматы (например, PDF и при наличии CSV), печатать и пересылать заинтересованным сторонам.
• При наличии прав доступа пользователь может просматривать и отчеты других подразделений или компаний, если такие права выданы через механизмы ShareForCompany и ShareForUser.

5. API v2 для интеграции и мобильных приложений

API v2 реализован как набор PHP‑скриптов (например, auth.php, battery.php, files.php), использующих APIConfig для доступа к БД wizard_online и параметрам окружения, и предоставляет статeless‑интерфейс для внешних клиентов по HTTP.

5.1. Аутентификация и токены

{
  "method": "POST /v2/auth.php",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "login": "user@example.com",
    "password": "********",
    "uuid": "device-uuid-123",
    "os": "Android",
    "version": "1.2.3"
  }
}

В ответ возвращается JSON с полями успешности, токеном, информацией о пользователе, компании, тарифе, а также служебными данными для клиента.

5.2. Поиск батарей и доступ к паспорту

{
  "method": "GET /v2/battery.php?q=12V%20100Ah&limit=20",
  "headers": {
    "Authorization": "Bearer <token>"
  }
}

В ответ возвращается список батарей, удовлетворяющих поисковым параметрам и правилам видимости (учет компании, прав доступа и тарифов).

5.3. Рекомендации по разработке новых endpoint‑ов

• Всегда подключайте config.php и используйте APIConfig::getDBConnection() вместо прямого подключения к MySQL.
• Получайте входные параметры через APIConfig::getParam(), учитывая допустимые методы (GET/POST/JSON).
• Соблюдайте общую структуру ответа: поле ok/ success, данные, сообщение об ошибке, при необходимости — служебную информацию.
• Ограничивайте объем возвращаемых данных (limit, offset) и не отдавайте полные сырые измерения без пагинации.

<?php
/**
 * Автор: Михаил Дейнекин (deynekin.com, mid1977@gmail.com)
 * Назначение: endpoint /v2/battery_passport.php
 * Описание: возврат краткого паспорта батареи по ID
 */

require_once __DIR__ . '/../config.php';

header('Content-Type: application/json; charset=utf-8');

try {
    $pdo = APIConfig::getDBConnection();

    // В простейшем варианте предполагается, что авторизация уже выполнена
    $batteryId = APIConfig::getParam('battery_id', 'GET');
    if (!$batteryId) {
        throw new InvalidArgumentException('Не указан параметр battery_id');
    }

    // Важно: названия таблиц и полей необходимо взять из JSON-схемы wizard_online
    $sql = '
        SELECT
            b.ID,
            b.Name,
            b.Model,
            b.Serial,
            b.Capacity,
            b.Voltage,
            b.Year,
            b.LifeTime,
            bt.Name AS BatteryTypeName,
            br.BrandName,
            c.Name AS CompanyName
        FROM Battery AS b
        LEFT JOIN BatteryTypes AS bt ON bt.ID = b.BatteryTypeID
        LEFT JOIN Brands AS br ON br.ID = b.BrandID
        LEFT JOIN Companies AS c ON c.ID = b.CompanyID
        WHERE b.ID = :id
    ';

    $stmt = $pdo->prepare($sql);
    $stmt->execute([':id' => $batteryId]);
    $battery = $stmt->fetch(PDO::FETCH_ASSOC);

    if (!$battery) {
        http_response_code(404);
        echo json_encode([
            'ok' => false,
            'message' => 'Батарея не найдена'
        ], JSON_UNESCAPED_UNICODE);
        exit;
    }

    echo json_encode([
        'ok' => true,
        'battery' => $battery
    ], JSON_UNESCAPED_UNICODE);
} catch (Throwable $e) {
    http_response_code(500);
    echo json_encode([
        'ok' => false,
        'message' => $e->getMessage()
    ], JSON_UNESCAPED_UNICODE);
}

Напоминаем, что реальные имена полей (например, Serial, BrandName и др.) необходимо уточнять по JSON‑схеме wizard_online, чтобы избежать расхождений с реальной БД.

6. Структура ключевых таблиц wizard_online (фрагменты)

Далее приведены выдержки из JSON‑документации схемы wizard_online для таблиц Battery и Files как примеры, как именно зафиксированы паспортные данные батареи и метаданные файлов.

6.1. Таблица Battery (паспортные данные АБ)

6.2. Таблицы File и Files (метаданные протоколов)

Для описания файлов протоколов используются две взаимосвязанные таблицы: File с базовыми атрибутами и Files с бизнес‑метаданными (объект, батарея, тестер и т.п.).

Для получения полной информации о файле в запросах к БД рекомендуется начинать с File, присоединять Files, затем Users, Companies, Battery и другие таблицы в соответствии с картой связей.

7. Battery Passport и требования EU Battery Regulation

Европейские инициативы по цифровому паспорту батареи описывают набор данных, который должен сопровождать батарею на протяжении всего жизненного цикла: производитель, материалы, углеродный след, эксплуатация, ремонт и утилизация.

• Battery Wizard Online уже покрывает часть требований: паспортные данные модели, технические характеристики, тесты и оценку состояния, а также историю эксплуатации, если данные регулярно загружаются.
• Для полного соответствия концепции Digital Battery Passport необходимо дополнительно обеспечить хранение сведений о происхождении материалов, углеродном следе и цепочках поставок в расширенных таблицах и/или отдельных модулях.
• API‑слой должен предоставлять стандартизированные структуры данных для взаимодействия с внешними реестрами и регуляторными системами.

При проектировании таких расширений следует использовать уже существующую схему wizard_online и подход к связям (CompanyID, BatteryID и др.), не нарушая общую архитектуру и принципы целостности данных.