EcoComfort — документация проекта

В MVP водитель находит открытую AC-площадку, выбирает физический порт, при необходимости бронирует время, пополняет EcoCoin, приезжает, подключает автомобиль, запускает зарядку по QR или вручную, наблюдает подтверждённую станцией сессию, останавливает её, получает фактический расчёт и чек, обращается в поддержку.

Продуктовая система включает мобильные приложения iOS/Android, backend, веб-админку, интеграцию с оборудованием через CSMS/OCPP, СБП и карты, кассу и фискализацию, SMS, карты и геокодирование, push и внутренние уведомления, поддержку, журналирование, аудит, мониторинг и обработку ошибок.

Портал — это проектирование и демонстрация, а не система управления зарядками. Внешние действия показаны на примерах и помечены.

• Аудитория: заказчик, команда разработки, технические специалисты, будущая операторская команда и демонстрационные посетители.
• Язык интерфейса — русский; технические имена сущностей и статусов сохраняются рядом с человекочитаемым описанием.
• Режим портала — интерактивная демонстрация на вымышленных данных.

Подтверждённое требование присутствует в исходном ТЗ. Допущение для оценки предложено для предварительной оценки и требует подтверждения. Открытое решение должен выбрать заказчик. Предлагаемая технология — рекомендуемый вариант для проектирования. Демонстрационные данные вымышлены. Всё, что не входит в MVP, описано как отдельная опция.

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

• Открытые решения D01–D11 не закрываются за заказчика.
• Срок 14–16 недель — предварительный ориентир, а не гарантия.
• Демонстрационные станции и адреса не являются реальными точками зарядки.
• Статус «показано в приложении» не означает «пройдено на оборудовании».

Серверные компоненты используются для статической документации, клиентские — только там, где нужны состояние, таймеры, обработчики или браузерные API. Тяжёлые React Flow и Mermaid подключаются на профильных страницах, чтобы не утяжелять первичную загрузку.

Состояние витрины хранится в браузере: React Context + useReducer, сохранение в localStorage. Его можно вернуть к исходному.

Стек будущего продукта (предложение): React Native + Expo, Node.js/NestJS, PostgreSQL, Prisma, REST/OpenAPI. Подробный список — на странице «Система».

• Next.js App Router, React, TypeScript, Tailwind CSS.
• Lucide React для иконок, @xyflow/react и Mermaid для диаграмм.
• Zod, Vitest, Playwright для валидации и проверок.
• Локальные ресурсы и системные шрифты вместо внешних CDN.

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

Все основные маршруты открываются напрямую и корректно обновляются. Активный раздел подсвечен. Для неизвестного маршрута есть содержательная 404-страница. Глобальный поиск работает по требованиям, решениям, испытаниям, экранам, сущностям, API и глоссарию.

• Обзор: главная, дорожная карта, границы MVP.
• Требования: реестр FR, экраны, приёмка.
• Демо: приложение, кабинет, админка, сценарии.
• Архитектура: система, данные, API, интеграции, безопасность, эксплуатация.
• Управление: решения, риски, изменения. Справка: глоссарий и источники.

Каждый шаг имеет собственные состояния: загрузка, успех, пустой результат, ошибка, отсутствие связи, устаревшие данные, блокировка действия, обработка запроса и путь восстановления.

Демонстрационный сценарий проходит через реальные компоненты сайта и единый store. Созданная бронь появляется в кабинете, связанная сессия, платёж, проводки и чек доступны по ID, а те же объекты видны в админке.

• Без GPS доступен ручной выбор района и адреса.
• Бронь требует входа; карта и карточки доступны гостю.
• Старт не считается успешным до подтверждения станции.
• Итог не подставляется при расхождении показаний — создаётся сверка.

Каждое требование имеет приоритет, категорию, формулировку, ценность, акторов, предусловия, основной и альтернативные потоки, ошибки, экраны, API, сущности, журналирование, связанные решения, приёмочные тесты и статус реализации.

Требования не сокращаются до одной строки: карточка показывает исходный смысл и связи с экранами, данными и тестами. Если технический экран ещё не визуализирован, портал прямо указывает это вместо выдуманной реализации.

• FR-001–FR-023 — обязательный объём MVP.
• FR-024 гостевая оплата, FR-025 платный простой, FR-026 закрытые территории — опции.
• Каждое обязательное требование связано хотя бы с одним AT-сценарием.

Решения охватывают тарифы, отмену, прогноз, EcoCoin, платный простой, оборудование/CSMS, внешних поставщиков, юридические требования, поддержку, бренд и гостевой сценарий.

Портал показывает статус, владельца, влияние на экраны, этапы, требования и тесты. Рабочие значения в демо — допущения, а не утверждённые правила. Локальное изменение статуса в демо не является юридически значимым решением.

• Блокирующие: D01, D02, D04, D06, D07, D08.
• Отложенные опции: D05, D11.
• D03 и D10 требуют подтверждения параметров и материалов.

Клиенты: iOS, Android, веб-админка и демонстрационный портал. API-слой отвечает за вход, токены, права, ограничение частоты, валидацию схем и аудит. Бизнес-модули покрывают пользователей, каталог, календарь, кошелёк, платежи, сессии, уведомления, чеки, поддержку и инциденты.

Хранилище future-продукта — PostgreSQL с миграциями и резервным копированием. Внешние системы — CSMS/OCPP, платёжный провайдер, онлайн-касса, SMS, карты/геокодер и push. Портал не изображает эти интеграции как проверенные.

• Предлагаемые компоненты помечаются как вариант, а не утверждённая инфраструктура.
• Адаптеры внешних систем изолированы от доменной логики.
• Очередь — только при подтверждённой необходимости; кэш не является источником истины для денег и календаря.

Денежные значения хранятся целыми минимальными единицами. Для сессии сохраняется снимок тарифа, чтобы изменение тарифа не меняло историческую сумму. Для платежа и команды хранятся внешний ID, внутренний ID, correlation ID и ключ идемпотентности.

Для телеметрии фиксируются значение, единица, источник, время измерения и получения. Проводки неизменяемы; ручная корректировка создаётся отдельной компенсирующей записью с причиной. Существующие записи не переписываются.

• Уникальность внешнего события в пределах провайдера.
• Одна успешная бронь на конфликтующий интервал.
• Доступный баланс не ниже нуля; двойное удержание запрещено.
• Допустимые переходы статусов и связь итоговой проводки с сессией.

Входные схемы валидируются сервером, права проверяются на каждом защищённом действии с учётом объекта. Ошибки имеют стабильный код, безопасное сообщение, данные для корреляции и понятное действие клиента.

Повтор безопасной операции возвращает результат того же логического действия. Финансовые и командные действия не повторяются автоматически под новым ключом при неизвестном исходе. URL и JSON на портале — иллюстративные проектные предложения, а не утверждённый контракт.

• Коды ошибок: AUTH_REQUIRED, SLOT_CONFLICT, HOLD_EXPIRED, PAYMENT_PENDING, STATUS_STALE, RECONCILIATION_REQUIRED и другие.
• Для списков предусмотрены курсоры и предсказуемая сортировка.
• Кэшированный статус не выдаётся за подтверждение свободного слота.

Для оборудования проверяются Start, Stop, измерения, тайм-ауты, повтор команд, потеря связи и восстановление. Для платежей — тестовый контур, подписи webhook, сверка статусов и повторные события. Для кассы — фискализация, очередь и повтор ошибок.

Портал не заявляет проверенную интеграцию без доступа к оборудованию, ключам и тестовым кабинетам. На этапе проектирования фиксируются только требования и предлагаемые контуры.

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

Пользователь видит баланс, доступную сумму, зарезервированную сумму и историю проводок с источником: покупка, бонус, компенсация, возврат, административная корректировка.

Демонстрационное пополнение не запускает реальный платёж. Курс 1 EcoCoin = 1 ₽ используется только в интерфейсе демо. Реальная модель покупки, списания, фискализации и возврата должна быть утверждена до включения денег.

• Неиспользованный резерв освобождается при финализации.
• Расхождение показаний не превращается в удобную сумму.
• Ручная корректировка — отдельная обратная/компенсирующая запись с причиной.

Обязательные случаи включают потерю сети во время зарядки, недоступность backend, отсутствие ответа CSMS, устаревший статус, неверный QR, несовместимый разъём, две одновременные заявки, истёкший hold, повторный webhook, повторный Start/Stop, задержку финальных измерений, ошибку кассы и действия вне роли.

Ключевые принципы: не лгать о состоянии зарядки, не терять денежный след, не повторять внешнюю команду без проверки предыдущего результата, не менять исторический расчёт, не показывать сомнительный порт свободным и не превращать неопределённость в успех.

• Неизвестный результат Start/Stop — отдельный статус, не успех.
• Ошибка чека не удаляет сессию и платёж.
• Поздний webhook при занятом слоте уходит в возврат/сверку.
• Роль поддержки не может менять финансовую проводку.

Права проверяются на сервере с учётом объекта/площадки. SMS, вход и чувствительные API ограничиваются по частоте. Одноразовые коды защищены от перебора. Секреты, OTP, пароли и карточные данные не попадают в логи.

Юридические требования, сроки хранения, удаление/анонимизация и регион данных помечаются «Требует подтверждения» и не выдаются за гарантированные без проверки применимого законодательства и юриста заказчика.

• RBAC и MFA для админки — рассматриваемый вариант.
• Отдельные секреты для dev/test/pilot/prod.
• Минимизация и маскирование персональных данных.
• Модель угроз по важным активам и границам доверия.

Категории метрик: доступность backend, возраст телеметрии, успешные Start/Stop, тайм-ауты CSMS, платежи в промежуточном статусе, повторные webhooks, зависшие holds, сессии без финальных показаний, очередь чеков, расхождения журнала, конфликты календаря и обращения без ответа.

Пороги и дежурства — открытая эксплуатационная договорённость. Для каждой метрики указываются источник, единица, предполагаемый порог и ответственный. Значения не выдаются за измеренные факты.

• Структурированные логи с уровнем, временем, сервисом, средой, correlation ID, entity ID и безопасным кодом.
• Резервное восстановление проверяется на отдельной среде.
• RPO/RTO требуют решения заказчика.

Каждый сценарий содержит предусловия, шаги, ожидаемый результат, доказательство, связанные требования, данные и статус. Портал различает «показано в приложении», «показано частично» и «не показано». Статус «пройдено на реальном оборудовании» не присваивается без испытания.

Проверки самого сайта включают unit-тесты логики, компонентные тесты, Playwright-сценарии, lint, типы и production build. Один ручной клик не считается полной проверкой.

• Не заявлять о прохождении тестов, которые не запускались.
• Не считать демонстрационную симуляцию реальной интеграцией.
• Проверять прямые маршруты, 360 px, печать и ошибки консоли.

В сумму MVP не входят гостевая веб-оплата без приложения, DC-зарядки, шлагбаумы и ANPR, корпоративные кабинеты, подписки, криптовалюты, P2P, расширенная лояльность, полноценная CRM, другие языки, полноценный чат без договора, новые марки оборудования, дополнительные CSMS и комиссии провайдеров.

Платный простой и автоматические компенсации не включаются в финансовую логику до D05 и надёжного подтверждения занятости места.

• Опции оцениваются отдельно и не размывают согласованный MVP.
• Границы фиксируются письменно; новые требования меняют объём и сроки.

План предполагает частичный параллелизм и внешние зависимости. Задержка доступа к станции, платёжному тестовому контуру или договору на кассу помечает соответствующий блок как внешнюю зависимость; такие блокировки нельзя устранить одним кодом.

Срок — предварительный ориентир для согласованного MVP, а не план всей будущей платформы. Расходы внешних сервисов в разработку не входят, если договором не установлено иное.

Глобальный поиск работает локально и ищет по ID и тексту требований, решений, экранов, сущностей, API и глоссария. Оглавление текущей страницы строится по заголовкам и подсвечивает активный раздел.

Печать использует стандартный механизм браузера: скрывает навигацию и демо-контролы, сохраняет содержание, подписи схем, легенды и ID. Таблицы и страницы получают адекватные разрывы.

• Ctrl/Cmd + K открывает поиск, Escape закрывает.
• Связи между FR, AT, D, экранами и сущностями кликабельны.
• Копирование кода и технических фрагментов доступно без внешних сервисов.

Портал не выдумывает авторство, подписи, даты согласования, фамилии, юридическую проверку, акты или результаты испытаний. Версия сайта отличается от версии исходного ТЗ.

Технические версии фиксируются lock-файлом. Ссылки на официальную документацию используются для проверки установки и совместимости, а не как подтверждение проверенных интеграций.

• Исходное ТЗ: версия 2.0, 29.09.2026.
• Сайт: портал v0.1, демонстрационные данные.
• Внешние интеграции не проверены без ключей и оборудования.