Skip to content

srs.ru.md

Latest commit

 

History

History
1314 lines (980 loc) · 64.8 KB

srs.ru.md

File metadata and controls

1314 lines (980 loc) · 64.8 KB
Raw

Техническое задание (SRS)

Проект: MYCELIUM CORE

Версия: 1.0
Статус: полная версия ТЗ
Тип системы: desktop sandbox‑приложение для моделирования и аудита электронного голосования на локальной Ethereum‑сети
Архитектурная модель: один смарт‑контракт, локальный узел, один GUI‑клиент

Примечание к реализации: Данный SRS является исходным базовым требованием. Фактическая реализация отличается в следующем для улучшения архитектуры и UX:

  • Выбрана PyQt6 вместо PySide6 (см. ADR-001).
  • Смарт-контракт называется VotingCore.sol (вместо VotingCoreSecure.sol).
  • session_manager.py не выделен в отдельный модуль — его логика интегрирована в фасад AppController.
  • Файловая структура сгруппирована в data/: data/chain-data/, data/logs/, data/exports/ (вместо корневых папок).

1. Общие сведения

1.1 Наименование

MYCELIUM CORE — простое автономное настольное приложение для развёртывания локальной blockchain‑среды, подготовки сессии голосования, подачи голосов, просмотра результатов и проведения базового аудита безопасности.

1.2 Назначение

Система предназначена для:

  • моделирования защищённого on‑chain голосования;
  • демонстрации ограничений и преимуществ электронного голосования на смарт‑контракте;
  • тестирования логики стадий;
  • демонстрации защиты от повторного голосования;
  • проведения аудит‑ориентированных сценариев в контролируемой среде.

1.3 Цель разработки

Разработать компактное, понятное, безопасное и архитектурно чистое приложение, которое:

  • использует один смарт‑контракт как единый источник истины;
  • исключает токеновую модель голосования;
  • не допускает прямой blockchain‑логики в UI;
  • поддерживает несколько сессий голосования в рамках одного запуска приложения;
  • хранит все необходимые проектные файлы в одной корневой папке;
  • поддерживает локализацию и темы;
  • остаётся удобным для последующего сопровождения.

1.4 Характер системы

Система является:

  • учебной;
  • исследовательской;
  • демонстрационной;
  • стендовой;
  • аудит‑ориентированной.

Система не предназначена для использования в реальных публичных или государственных выборах.

1.5 Диаграммы архитектуры

Для однозначного понимания взаимодействия компонентов система должна быть описана следующими диаграммами (документ с диаграммами поставляется отдельно):

  • Диаграмма компонентов – показывает модули (GUI, Controller, Service Layer, Web3 Provider, Geth Manager, Nonce Manager) и связи между ними.
  • Диаграмма последовательности (sequence diagram) для сценария «Создание новой сессии в чистом режиме» – с шагами: подтверждение пользователя, архивация логов, остановка Geth, очистка chain-data, перезапуск, деплой нового контракта.
  • Диаграмма состояний (state diagram) для жизненного цикла сессии голосования: SETUP → ACTIVE → FINISHED → (архивирована).
  • Диаграмма классов для core-моделей (Election, Candidate, Voter, Session).

2. Основные принципы системы

  1. Один контракт — одна истина.
  2. Голосование выполняется только методом castVote.
  3. Критические ограничения обеспечиваются прежде всего on-chain.
  4. UI не взаимодействует напрямую с Web3.
  5. Все write‑операции выполняются только через сервисный слой.
  6. Приложение должно поддерживать повторное создание новых сессий голосования.
  7. Система должна быть полностью самодостаточной в пределах одной папки проекта.
  8. По умолчанию приватный ключ администратора не сохраняется.
  9. Светлая/тёмная тема и ru/en локализация обязательны.
  10. Цветовая семантика статусов должна быть единообразной.

3. Границы системы

3.1 Что входит в систему

Система должна обеспечивать:

  • запуск локального Geth;
  • проверку RPC‑доступности;
  • компиляцию и деплой одного смарт‑контракта;
  • регистрацию кандидатов;
  • регистрацию избирателей в whitelist;
  • управление стадиями выборов;
  • голосование избирателей;
  • генерацию QR‑квитанции;
  • просмотр результатов;
  • аудит инвариантов безопасности;
  • экспорт результатов;
  • создание новой сессии голосования;
  • архивирование предыдущей сессии;
  • логирование действий;
  • локализацию ru/en;
  • светлую и тёмную тему.

3.2 Что не входит в систему

Система не обязана:

  • обеспечивать анонимное криптографическое голосование;
  • использовать публичный Ethereum mainnet/testnet;
  • поддерживать многопользовательский серверный backend;
  • обеспечивать production‑уровень безопасности для реальных выборов;
  • реализовывать токены, mint, transfer, approve, allowance;
  • использовать внешние базы данных.

4. Целевые пользователи

4.1 Администратор

Выполняет:

  • развёртывание контракта;
  • добавление кандидатов;
  • добавление избирателей;
  • управление стадиями;
  • запуск новой сессии;
  • экспорт результатов.

4.2 Избиратель

Выполняет:

  • ввод приватного ключа;
  • выбор кандидата;
  • отправку голоса;
  • получение квитанции.

4.3 Аудитор / тестировщик

Выполняет:

  • просмотр результатов;
  • проверку инвариантов;
  • проверку статусов безопасности;
  • анализ журналов и экспортированных данных.

5. Архитектурная модель

5.1 Высокоуровневая схема

GUI (PySide6)
   ↓
Application Controller
   ↓
Service Layer
   ↓
Web3 / Compiler / Geth / Nonce Manager
   ↓
Voting smart contract

5.2 Архитектурные ограничения

Слой интерфейса пользователя не должен:

  • напрямую создавать контракты Web3;
  • напрямую строить транзакции;
  • напрямую подписывать транзакции;
  • напрямую вызывать методы отправки raw transaction;
  • содержать бизнес‑логику голосования.

5.3 Обязательные уровни системы

Система должна быть разделена минимум на:

  • UI;
  • controller;
  • services;
  • infrastructure;
  • utils;
  • contract artifacts.

6. Модель сессий голосования

6.1 Базовое требование

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

6.2 Новая сессия голосования

Должна существовать функция «Новое голосование», запускаемая из UI.

6.3 Поведение при запуске новой сессии

Перед созданием новой сессии система должна:

  • предложить сохранить и архивировать результаты текущей сессии;
  • архивировать текущий лог;
  • сбросить рабочий контекст интерфейса;
  • очистить текущие адреса контракта;
  • очистить текущие локальные данные кандидатов и избирателей из оперативного контекста.

6.4 Режимы новой сессии

Система должна поддерживать два режима:

Быстрый режим

  • сохраняется текущая blockchain‑среда;
  • выполняется новый деплой нового контракта;
  • предыдущая сессия остаётся в истории сети.

Чистый режим

  • архивируется предыдущая сессия;
  • очищается активная blockchain‑среда;
  • локальный узел перезапускается;
  • новая сессия начинается на чистой цепочке.

Чистый режим (подробный алгоритм)
При выборе чистого режима система должна выполнить следующие шаги строго по порядку:

  1. Запросить подтверждение пользователя с предупреждением «Все данные текущей сессии будут архивированы, цепочка блоков будет полностью удалена».
  2. Архивировать текущий лог и результаты (если есть) в logs/archive/<session_id>/ и exports/results/.
  3. Остановить процесс Geth (если запущен).
  4. Удалить папку chain-data/active целиком (или переименовать в chain-data/archive/old_<timestamp> для отладки).
  5. Заново создать пустую папку chain-data/active.
  6. Запустить Geth с параметрами инициализации новой пустой цепи.
  7. Дождаться готовности RPC.
  8. Сбросить контекст UI (очистить адреса контракта, списки кандидатов/избирателей и др).
  9. Перевести интерфейс в исходное состояние (стадия SETUP, ни одного контракта).

Примечание: после чистого режима ранее развёрнутые контракты и голоса полностью теряются. Это соответствует поведению «абсолютно новых выборов».

7. Файловая структура проекта

7.1 Общее требование

Все необходимые файлы проекта должны располагаться в одной корневой папке.

7.2 Целевая структура

mycelium-core/
│
├── main.py
├── requirements.txt
├── app.cfg
├── .env
├── .env.example
│
├── bin/
│   ├── geth.exe
│   └── solc.exe
│
├── contracts/
│   ├── VotingCoreSecure.sol
│   └── abi/
│       └── VotingCoreSecure.json
│
├── src/
│   ├── core/
│   │   ├── app_controller.py
│   │   ├── session_manager.py
│   │   ├── geth_manager.py
│   │   ├── compiler_service.py
│   │   ├── web3_provider.py
│   │   ├── nonce_manager.py
│   │   ├── voting_service.py
│   │   ├── audit_service.py
│   │   └── models.py
│   │
│   ├── ui/
│   │   ├── main_window.py
│   │   ├── tabs/
│   │   │   ├── admin_tab.py
│   │   │   ├── vote_tab.py
│   │   │   └── audit_tab.py
│   │   │
│   │   ├── widgets/
│   │   │   ├── toast.py
│   │   │   ├── status_badge.py
│   │   │   ├── section_card.py
│   │   │   └── confirm_dialog.py
│   │   │
│   │   ├── themes/
│   │   │   ├── dark.qss
│   │   │   └── light.qss
│   │   │
│   │   └── i18n/
│   │       ├── ru.json
│   │       └── en.json
│   │
│   └── utils/
│       ├── config.py
│       ├── paths.py
│       ├── logger.py
│       ├── validators.py
│       ├── crypto.py
│       └── qr.py
│
├── chain-data/
│   ├── active/
│   └── archives/
│
├── logs/
│   ├── active/
│   │   └── session.log
│   └── archive/
│       └── <session_id>/
│
├── exports/
│   ├── voters/
│   ├── receipts/
│   └── results/
│
└── runtime/
    └── cache/

Нота: фактическую структуру см. в файлах src/development/setup.md / src/development/setup.ru.md.

Это образец. Целевую структуру можно изменять.

7.3 Требования к папке bin/

Папка bin/ должна содержать:

  • локальный geth;
  • локальный solc как опциональный fallback.

Приложение должно искать эти бинарные файлы только внутри проекта.

7.4 Требования к папке contracts/

Контракт и ABI‑артефакты должны располагаться только в bin/contracts/.

7.5 Требования к chain-data/

Blockchain‑данные должны размещаться внутри проекта, а не в системных каталогах ОС.

7.6 Требования к logs/

Логи текущей и прошлых сессий должны находиться внутри проекта.

8. Конфигурация проекта

8.1 Пользовательский конфиг app.cfg

Файл app.cfg обязателен.

Он должен хранить:

  • выбранный язык;
  • выбранную тему;
  • размер и положение окна;
  • последние пути импорта/экспорта;
  • предпочтительный режим новой сессии;
  • флаг dev mode;
  • другие безопасные пользовательские настройки.

Он не должен хранить:

  • приватные ключи избирателей;
  • приватный ключ администратора по умолчанию;
  • чувствительные секреты.

8.2 Файл .env

Файл .env допускается и уместен как технический конфиг.

Он может содержать:

  • RPC host;
  • RPC port;
  • log level;
  • dev mode flag;
  • compiler options;
  • gas defaults;
  • optional dev admin key;
  • прочие технические параметры среды, которые можно сохранить для повторного использования.

Он не должен использоваться как основной безопасный storage секретов.

8.3 Хранение admin private key

По умолчанию:

  • приватный ключ администратора не должен сохраняться.

Опционально:

  • система может поддерживать developer convenience mode, при котором admin key читается из .env;
  • при этом UI должен явно показывать, что активен небезопасный dev‑режим.

9. Выбор GUI‑библиотеки

9.1 Основная рекомендация

Для проекта должна использоваться PySide6.

9.2 Обоснование

PySide6 подходит, потому что:

  • хорошо поддерживает desktop‑архитектуру;
  • имеет зрелую систему виджетов;
  • поддерживает QSS;
  • хорошо работает с вкладками, таблицами, формами и потоками;
  • подходит для кроссплатформенной desktop‑разработки;
  • удобен для долгосрочного сопровождения.

9.3 Допустимая альтернатива

Допускается использование PyQt6, если это требуется по внутренним причинам проекта, однако предпочтительным вариантом остаётся PySide6.

10. Функциональные требования

10.1 Управление средой исполнения

FR-ENV-01 Автозапуск локального узла

При запуске приложения система должна автоматически запускать локальный blockchain‑узел из папки bin/.

FR-ENV-02 Проверка готовности RPC

Система должна проверять доступность RPC и переходить в рабочее состояние только после подтверждения готовности узла.

FR-ENV-03 Отображение статуса RPC

Система должна отображать в интерфейсе статус соединения с RPC.

FR-ENV-04 Отображение номера блока

Система должна отображать текущий номер блока.

FR-ENV-05 Обработка ошибок среды

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

FR-ENV-06 Корректная остановка узла

При закрытии приложения локальный узел должен завершаться корректно/целиком.

FR-ENV-07 Обнаружение внезапного завершения Geth

Система должна периодически (раз в 5 секунд) проверять, жив ли процесс Geth. Если процесс не отвечает или завершился с ошибкой, UI должен показать красный статус «🔴 RPC: GETH CRASHED» и заблокировать все операции, требующие записи в блокчейн.

FR-ENV-08 Автоматический перезапуск Geth

При краше Geth система должна предложить пользователю перезапустить узел (кнопка «Restart Node»). Автоматический перезапуск без подтверждения не допускается, чтобы не терять данные.

FR-ENV-09 Обработка ошибки «адрес уже используется»

Если порт RPC (по умолчанию 8545) занят, система должна при старте показать ошибку с предложением сменить порт в .env и завершить работу.

FR-ENV-10 Таймаут подключения к RPC

После запуска Geth система должна ждать RPC не более 30 секунд. Если за это время RPC не ответил, выдать сообщение «Geth запущен, но RPC недоступен. Проверьте логи Geth».

10.2 Компиляция и деплой

FR-DEP-01 Компиляция одного контракта

Система должна компилировать один смарт‑контракт голосования.

FR-DEP-02 Деплой из интерфейса

Администратор должен иметь возможность развернуть контракт из UI одной операцией.

FR-DEP-03 Отображение адреса контракта

После успешного деплоя система должна отобразить адрес контракта.

FR-DEP-04 Сохранение ABI

ABI контракта должно сохраняться локально внутри проекта bin/contracts/abi.

FR-DEP-05 Сессионный контекст

После деплоя адрес контракта и связанные данные должны быть сохранены в контексте текущей сессии.

FR-DEP-06 Защита от случайного повторного деплоя

Система должна предотвращать случайный повторный деплой без подтверждённого перехода к новой сессии.

10.3 Конфигурация выборов

FR-CONF-01 Создание новой конфигурации выборов

Администратор должен иметь возможность задать:

  • название выборов;
  • идентификатор сессии;
  • допустимый лимит числа кандидатов.

FR-CONF-02 Валидация параметров выборов

Система должна валидировать конфигурацию выборов до деплоя.

10.4 Управление кандидатами

FR-ADM-01 Добавление кандидатов

Администратор должен иметь возможность добавлять кандидатов до начала голосования.

FR-ADM-02 Поля кандидата

Для кандидата должны задаваться:

  • имя / ФИО;
  • партия / политическая принадлежность;
  • адрес.

FR-ADM-03 Генерация тестового адреса кандидата

Система должна уметь генерировать тестовый адрес кандидата.

FR-ADM-04 Проверка формата адреса кандидата

Система должна проверять корректность формата адреса кандидата.

FR-ADM-05 Запрет дублирования

Система должна запрещать добавление кандидата с уже существующим адресом.

FR-ADM-06 Регистрация кандидатов on-chain

Система должна позволять зарегистрировать подготовленный список кандидатов в контракте.

FR-ADM-07 Ограничение по стадиям

Регистрация кандидатов должна быть доступна только до старта голосования.

10.5 Управление избирателями

FR-ADM-08 Добавление избирателей в whitelist

Администратор должен иметь возможность добавить избирателей в whitelist до начала голосования.

FR-ADM-09 Источники избирателей

Система должна поддерживать:

  • ручной ввод адресов;
  • импорт из JSON;
  • генерацию тестовых ключей.

FR-ADM-10 Генерация тестовых избирателей

Система должна уметь сгенерировать заданное количество тестовых пар:

  • адрес;
  • приватный ключ.

FR-ADM-11 Экспорт JSON с избирателями

Система должна позволять экспортировать тестовые ключи избирателей в JSON.

FR-ADM-12 Предупреждение о риске экспорта

Перед экспортом приватных ключей система должна показывать предупреждение повышенной важности.

FR-ADM-13 Регистрация whitelist on-chain

Система должна выполнять пакетную регистрацию избирателей в whitelist.

FR-ADM-14 Ограничение по стадиям

Изменение whitelist должно быть доступно только до старта голосования.

10.6 Управление стадиями

FR-STAGE-01 Старт голосования

Администратор должен иметь возможность перевести выборы в стадию активного голосования.

FR-STAGE-02 Завершение голосования

Администратор должен иметь возможность завершить голосование.

FR-STAGE-03 Ограничение операций по стадиям

После старта голосования система должна запрещать изменения setup‑части.

FR-STAGE-04 Отображение стадии

Текущая стадия должна отображаться в UI постоянно.

10.7 Голосование

FR-VOTE-01 Ввод приватного ключа

Избиратель должен иметь возможность вручную ввести приватный ключ.

FR-VOTE-02 Загрузка из JSON

Избиратель должен иметь возможность загрузить ключ из JSON‑файла.

FR-VOTE-03 Вычисление адреса

Система должна автоматически вычислять адрес по введённому ключу.

FR-VOTE-04 Проверка статуса избирателя

Система должна отображать:

  • входит ли адрес в whitelist;
  • голосовал ли адрес;
  • активна ли стадия голосования.

FR-VOTE-05 Отображение списка кандидатов

Система должна показывать список зарегистрированных кандидатов.

FR-VOTE-06 Выбор одного кандидата

Избиратель должен иметь возможность выбрать только одного кандидата.

FR-VOTE-07 Отправка голоса

После выбора кандидата избиратель должен иметь возможность отправить голос.

FR-VOTE-08 Блокировка повторного нажатия

Во время обработки голосования кнопка отправки должна быть заблокирована.

FR-VOTE-09 Подтверждение транзакции

После успешной отправки голоса система должна показать:

  • TX Hash;
  • номер блока;
  • адрес выбранного кандидата.

FR-VOTE-10 Очистка чувствительных данных

После завершения операции поле приватного ключа должно очищаться.

10.8 Квитанция и подтверждение

FR-REC-01 Формирование квитанции

После успешного голосования система должна формировать квитанцию.

FR-REC-02 Генерация QR

Квитанция должна быть доступна в виде QR‑кода.

FR-REC-03 Сохранение QR

Пользователь должен иметь возможность сохранить QR‑квитанцию.

FR-REC-04 Копирование TX Hash

Пользователь должен иметь возможность скопировать TX Hash.

10.9 Результаты

FR-RES-01 Просмотр результатов

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

FR-RES-02 Сортировка результатов

Результаты должны сортироваться по убыванию числа голосов.

FR-RES-03 Победитель или ничья

Система должна определять победителя или фиксировать ничью.

FR-RES-04 Явка

Система должна рассчитывать процент явки.

FR-RES-05 Экспорт результатов

Система должна уметь экспортировать результаты в JSON.

10.10 Аудит

FR-AUD-01 Запуск полного аудита

Система должна запускать полный аудит завершённой сессии голосования.

FR-AUD-02 Проверка повторного голосования

Система должна проверять, что каждый избиратель голосовал не более одного раза.

FR-AUD-03 Проверка whitelist

Система должна проверять, что голосовали только разрешённые адреса.

FR-AUD-04 Проверка стадии

Система должна проверять, что голоса подавались только в разрешённой стадии.

FR-AUD-05 Проверка валидности кандидатов

Система должна проверять, что голоса отдавались только зарегистрированным кандидатам.

FR-AUD-06 Проверка ограничений администрирования

Система должна проверять, что административные действия выполнялись только владельцем и только в разрешённых стадиях.

FR-AUD-07 Визуальное представление аудита

Результаты аудита должны отображаться в виде понятной таблицы статусов.

FR-AUD-08 Экспорт отчёта аудита

Система должна позволять экспортировать сводный аудит‑отчёт.

10.11 Новая сессия голосования

FR-SESSION-01 Создание новой сессии

Система должна позволять создать новую сессию голосования без закрытия приложения.

FR-SESSION-02 Предупреждение перед сбросом

Перед созданием новой сессии система должна запросить подтверждение.

FR-SESSION-03 Архивация текущей сессии

Перед запуском новой сессии система должна предложить сохранить результаты и архивировать лог.

FR-SESSION-04 Быстрый режим

Система должна поддерживать создание новой сессии через новый деплой в существующей blockchain‑среде.

FR-SESSION-05 Чистый режим

Система должна поддерживать создание новой сессии с очисткой blockchain‑среды и перезапуском узла.

FR-SESSION-06 Сброс активного UI‑контекста

После новой сессии система должна очистить активные данные прошлой сессии из интерфейса.

10.12 Локализация

FR-I18N-01 Поддержка двух языков

Система должна поддерживать минимум:

  • русский;
  • английский.

FR-I18N-02 JSON‑локализация

Все пользовательские тексты должны храниться в JSON‑файлах:

  • ru.json
  • en.json

FR-I18N-03 Полное покрытие

Локализация должна охватывать:

  • вкладки;
  • кнопки;
  • статусы;
  • подсказки;
  • диалоги;
  • ошибки;
  • названия стадий;
  • аудит‑статусы;
  • уведомления.

FR-I18N-04 Переключение языка

Пользователь должен иметь возможность менять язык в UI.

10.13 Темизация

FR-THEME-01 Светлая и тёмная тема

Система должна поддерживать две темы:

  • light;
  • dark.

FR-THEME-02 Сохранение выбранной темы

Выбранная тема должна сохраняться в app.cfg.

FR-THEME-03 Применение без потери состояния

Переключение темы не должно сбрасывать текущую сессию.

11. Нефункциональные требования

11.1 Архитектура

NFR-ARC-01 Один смарт‑контракт

Проект должен использовать только один смарт‑контракт голосования.

NFR-ARC-02 Отсутствие Web3‑логики в UI

UI не должен напрямую работать с Web3.

NFR-ARC-03 Сервисный слой обязателен

Все blockchain‑операции должны проходить через сервисы.

NFR-ARC-04 Единый контроллер

В системе должен существовать единый координирующий слой управления приложением.

NFR-ARC-05 Модульность

Код должен быть разбит на независимые модули.

11.2 Безопасность

NFR-SEC-01 Не сохранять admin key по умолчанию

Приватный ключ администратора не должен сохраняться автоматически.

NFR-SEC-02 Не логировать секреты

Секретные данные не должны попадать в логи.

NFR-SEC-03 Минимизация времени жизни ключей в памяти

Ключи должны храниться в памяти как можно меньше времени.

NFR-SEC-04 Централизованный nonce manager

Все write‑операции должны использовать единый менеджер nonce.

NFR-SEC-05 Безопасное поведение по умолчанию

Недостаточно подтверждённые состояния должны трактоваться как запрещающие выполнение действия.

NFR-SEC-06 Приоритет on-chain ограничений

Главные(!) ограничения должны обеспечиваться контрактом.

NFR-SEC-07 Dev mode должен быть явно помечен

Если используется admin key из .env, UI должен показывать режим разработчика и предупреждение о небезопасности.

11.3 Производительность

NFR-PERF-01 Неблокирующий интерфейс

Длительные операции не должны блокировать UI.

NFR-PERF-02 Фоновые worker‑задачи

Компиляция, деплой, batch‑операции и аудит должны выполняться в фоновых задачах.

NFR-PERF-03 Прогресс операций

Для длительных операций должны отображаться индикаторы прогресса или занятости.

11.4 Надёжность

NFR-REL-01 Устойчивость к ошибкам RPC

Система должна корректно обрабатывать временную недоступность RPC.

NFR-REL-02 Устойчивость к ошибкам ввода

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

NFR-REL-03 Контролируемое завершение

При закрытии приложения фоновые процессы должны завершаться корректно.

NFR-REL-04 Безопасная работа с новой сессией

Переход к новой сессии не должен приводить к частично сброшенному состоянию.

11.5 Поддерживаемость

NFR-MNT-01 Понятная структура проекта

Структура каталогов должна быть логичной и простой.

NFR-MNT-02 Минимизация дублирования

Не допускается дублирование логики между слоями.

NFR-MNT-03 Редактируемость интерфейса

Изменение UI не должно требовать изменения backend‑логики.

NFR-MNT-04 Вынесение текстов в JSON

Все тексты должны храниться в локализационных файлах.

NFR-MNT-05 Вынесение тем в отдельные файлы

Темизация должна быть реализована через отдельные QSS‑файлы.

11.6 Наблюдаемость

NFR-OBS-01 Логирование ключевых действий

Все важные действия должны писаться в лог сессии.

NFR-OBS-02 Архивация логов сессии

Логи завершённых сессий должны архивироваться.

NFR-OBS-03 Логирование ошибок и исключений

Ошибки и исключения должны логироваться.

11.7 Портабельность

NFR-PORT-01 Все проектные ресурсы внутри одной папки

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

NFR-PORT-02 Минимум ручной настройки

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

12. Требования к цветовой семантике интерфейса

12.1 Общая цветовая логика

🟢 Зелёный

Используется для:

  • успешного состояния;
  • подтверждённого подключения;
  • валидного ввода;
  • успешной транзакции;
  • Passed в аудите;
  • разрешённого статуса;
  • активной готовности.

🟡 Жёлтый

Используется для:

  • предупреждений;
  • стадии Setup;
  • неполной конфигурации;
  • информационных предупреждений;
  • пользовательского внимания;
  • ничьи;
  • dev mode warning.

🔴 Красный

Используется для:

  • ошибок;
  • запрещённых действий;
  • невалидного ввода;
  • отключённого RPC;
  • Failed в аудите;
  • стадии Finished как финального закрытого состояния;
  • критических предупреждений безопасности.

12.2 Требование доступности

Цвет не должен быть единственным индикатором смысла.
Рядом с цветом всегда должны присутствовать:

  • текст;
  • и/или иконка;
  • и/или подпись статуса.

13. ASCII‑визуализация UI (пример)

13.1 Главное окно

+--------------------------------------------------------------------------------------------------+
| MYCELIUM CORE                            RPC: [🟢 CONNECTED] | Block: 1054 | Theme: Dark         |
+--------------------------------------------------------------------------------------------------+
| [ Admin ] [ Vote ] [ Audit ]                                                    [ New Session ]  |
+--------------------------------------------------------------------------------------------------+
|                                                                                                  |
|                                         ACTIVE TAB CONTENT                                       |
|                                                                                                  |
+--------------------------------------------------------------------------------------------------+
| Stage: [🟡 SETUP] | Contract: 0x............................................. | Lang: RU         |
+--------------------------------------------------------------------------------------------------+

13.2 Вкладка Admin

+--------------------------------------------------------------------------------------------------+
| ADMIN                                                                                            |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Election --------------------------------------------------------+
| Title:        [ Local Secure Election 2026                                ]                      |
| Election ID:  [ auto-generated                                            ]                      |
| Max Cands:    [ 10 ]                                                                             |
| Admin Key:    [ ******************************************************* ] [Show]                 |
|                                                                                                  |
| [ Deploy Election ]                                                                              |
| Contract: 0x............................................................ (green/yellow/red color)|
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Candidates ------------------------------------------------------+
| Name:   [ Alice Johnson                           ]                                              |
| Party:  [ Reform Alliance                         ]                                              |
| Addr:   [ 0x......................................................... ] [Gen] [Add]              |
|                                                                                                  |
| +----------------------------------------------------------------------------------------------+ |
| | Name                  | Party                | Address                                       | |
| +----------------------------------------------------------------------------------------------+ |
| | Alice Johnson         | Reform Alliance      | 0x...                                         | |
| | Bob Smith             | Civic Front          | 0x...                                         | |
| +----------------------------------------------------------------------------------------------+ |
|                                                                                                  |
| [ Register Candidates ]                                                                          |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Voters ----------------------------------------------------------+
| [ Generate Test Voters ] Count: [ 100 ]                                                          |
| [ Import JSON ] [ Export JSON ]                                                                  |
| Loaded voters: 100                                                                               |
|                                                                                                  |
| [ Add Voters To Whitelist ]                                                                      |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Stage -----------------------------------------------------------+
| Current Stage: [🟡 SETUP]                                                                        |
| [ Start Voting ]                                                           [ Finish Voting ]     |
+--------------------------------------------------------------------------------------------------+

13.3 Вкладка Vote

+--------------------------------------------------------------------------------------------------+
| VOTE                                                                                             |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Authentication --------------------------------------------------+
| Private Key: [ ******************************************************* ] [Show] [Load JSON]      |
| Address:      0x........................................................................         |
| Whitelisted:  [🟢 YES]                                                                           |
| Has Voted:    [🟡 NO]                                                                            |
| Stage:        [🟢 ACTIVE]                                                                        |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Candidates ------------------------------------------------------+
| ( ) Alice Johnson      | Reform Alliance                                                         |
| ( ) Bob Smith          | Civic Front                                                             |
| ( ) Carol Lee          | Green Horizon                                                           |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Voting ----------------------------------------------------------+
|                           [ CAST SECURE VOTE ]                                                   |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Receipt ---------------------------------------------------------+
|                                                                                                  |
|                                                                                                  |
|                              +----------------------------+                                      |
|                              |                            |                                      |
|                              |         QR RECEIPT         |                                      |
|                              |                            |                                      |
|                              +----------------------------+                                      |
|                                                                                                  |
| TX Hash: 0x......................................................................................|
|                                                                                                  |
|  [ Save QR ] [ Copy TX ]                                                                         |
+--------------------------------------------------------------------------------------------------+

13.4 Вкладка Audit

+--------------------------------------------------------------------------------------------------+
| AUDIT                                                                                            |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Results ---------------------------------------------------------+
| Stage:        [🔴 FINISHED]                                                                      |
| Total Voters: 100                                                                                |
| Total Votes:  87                                                                                 |
| Turnout:      87%                                                                                |
|                                                                                                  |
| +----------------------------------------------------------------------------------------------+ |
| | Candidate              | Party                | Address                   | Votes            | |
| +----------------------------------------------------------------------------------------------+ |
| | Alice Johnson          | Reform Alliance      | 0x...                     | 41               | |
| | Bob Smith              | Civic Front          | 0x...                     | 29               | |
| | Carol Lee              | Green Horizon        | 0x...                     | 17               | |
| +----------------------------------------------------------------------------------------------+ |
|                                                                                                  |
| Winner: Alice Johnson                                                                            |
| [ Export Results ]                                                                               |
+--------------------------------------------------------------------------------------------------+

+-------------------------------- Security Audit --------------------------------------------------+
| [ Run Full Audit ]                                                                               |
|                                                                                                  |
| +----------------------------------------------------------------------------------------------+ |
| | Check                                 | Status        | Details                              | |
| +----------------------------------------------------------------------------------------------+ |
| | Double Vote Protection                | [🟢 PASSED]   | No duplicate voters                  | |
| | Whitelist Enforcement                 | [🟢 PASSED]   | All voters whitelisted               | |
| | Stage Enforcement                     | [🟢 PASSED]   | Votes cast only in Active            | |
| | Candidate Integrity                   | [🟢 PASSED]   | All votes target valid candidates    | |
| | Owner-only Administration             | [🟢 PASSED]   | Restricted operations protected      | |
| | Post-start Freeze                     | [🟢 PASSED]   | Setup locked after start             | |
| +----------------------------------------------------------------------------------------------+ |
+--------------------------------------------------------------------------------------------------+

13.5 Пример ошибок и предупреждений

RPC Status:        [🔴 DISCONNECTED]
Private Key:       [ bad_input ]                  [🔴 INVALID]
Export Secret Keys:[ voters.json ]                [🟡 WARNING]
Deploy Result:     [ contract deployed ]          [🟢 SUCCESS]

14. Требования к локализации

14.1 Файлы локализации

Обязательны файлы:

  • src/ui/i18n/ru.json
  • src/ui/i18n/en.json

14.2 Что подлежит локализации

Все пользовательские тексты:

  • меню;
  • вкладки;
  • поля;
  • кнопки;
  • диалоги;
  • статусы;
  • уведомления;
  • ошибки;
  • подсказки;
  • этапы аудита;
  • названия стадий;
  • цветовые статусы.

14.3 Поведение

При старте приложения язык должен загружаться из app.cfg.

15. Требования к темам оформления

15.1 Файлы тем

Обязательны:

  • src/ui/themes/dark.qss
  • src/ui/themes/light.qss

15.2 Поведение

Выбранная тема должна:

  • загружаться из app.cfg;
  • применяться ко всему приложению;
  • изменяться без сброса активной сессии.

16. Форматы данных для экспорта и импорта

16.1 Экспорт избирателей (voters.json)

При экспорте по FR-ADM-11 генерируется JSON следующей структуры, пример:

 {
   "election_id": "SESSION_20260423_001",
   "export_timestamp": "2026-04-23T14:35:00Z",
   "voters": [
     {
       "address": "0xAbC...123",
       "private_key": "0x...",
       "has_voted": false
     }
   ]
 }

Перед экспортом обязательно показывается предупреждение (FR-ADM-12).

16.2 Экспорт результатов (results.json)

При экспорте по FR-RES-05 генерируется JSON, пример:

{
  "election": {
    "title": "Local Secure Election 2026",
    "session_id": "SESSION_20260423_001",
    "stage": "FINISHED",
    "start_block": 1024,
    "end_block": 2048
  },
  "statistics": {
    "total_voters": 100,
    "total_votes": 87,
    "turnout_percent": 87.0
  },
  "results": [
    {
      "candidate_name": "Alice Johnson",
      "party": "Reform Alliance",
      "address": "0x...",
      "votes": 41
    }
  ],
  "winner": "Alice Johnson",
  "is_tie": false
}

16.3 Экспорт аудит-отчёта (audit_report.json)

Дополнительно (FR-AUD-08) должен экспортироваться отчёт, пример:

{
  "session_id": "...",
  "audit_timestamp": "...",
  "checks": [
    {
      "check_name": "Double Vote Protection",
      "status": "PASSED",
      "details": "No duplicate voters"
    }
  ]
}

17. Требования к логированию

17.1 Лог текущей сессии

Система должна вести активный лог:

logs/active/session.log

17.2 Архивация

При завершении или архивировании сессии лог должен перемещаться в архив.

17.3 Что должно логироваться

  • запуск/остановка Geth;
  • компиляция;
  • деплой;
  • регистрация кандидатов;
  • регистрация избирателей;
  • изменение стадий;
  • отправка голоса;
  • создание новой сессии;
  • запуск аудита;
  • экспорт результатов;
  • ошибки;
  • необработанные исключения.

17.4 Запрет на логирование секретов

Приватные ключи, seed‑фразы и аналогичные секреты не должны попадать в лог.

18. Приёмочные критерии

Система считается принятой, если выполняются условия:

  1. Все ресурсы проекта размещаются в одной корневой папке.
  2. Локальный Geth запускается автоматически из bin/.
  3. Контракт компилируется и деплоится из UI.
  4. Используется один смарт‑контракт.
  5. Администратор может зарегистрировать кандидатов.
  6. Администратор может зарегистрировать whitelist избирателей.
  7. Голосование можно запустить только после подготовки выборов.
  8. Избиратель может проголосовать только один раз.
  9. Голосование невозможно вне активной стадии.
  10. Голосование невозможно не из whitelist.
  11. После голосования отображается TX Hash и QR‑квитанция.
  12. После завершения выборов отображаются корректные результаты.
  13. Аудит показывает статусы инвариантов безопасности.
  14. Поддерживаются ru/en через JSON.
  15. Поддерживаются dark/light темы.
  16. Выбранные язык и тема сохраняются в app.cfg.
  17. По умолчанию admin key не сохраняется.
  18. Dev mode с ключом из .env явно помечается как небезопасный.
  19. Система поддерживает “Новое голосование”.
  20. Доступны быстрый и чистый режимы новой сессии.
  21. Логи и результаты прошлых сессий архивируются.
  22. UI не содержит прямых Web3‑операций.
  23. Длительные операции не блокируют интерфейс.

19. Этапы разработки

Этап 1. Базовая инфраструктура и каркас проекта

Включает:

  • создание структуры каталогов;
  • выбор PySide6;
  • подключение конфигурации app.cfg;
  • подключение .env;
  • настройку логирования;
  • реализацию запуска и остановки локального Geth;
  • создание базового окна приложения;
  • подключение тем и локализации.

Этап 2. Смарт‑контракт и сервисный слой

Включает:

  • реализацию одного смарт‑контракта голосования;
  • компиляцию и деплой;
  • реализацию Web3 provider;
  • реализацию nonce manager;
  • реализацию service layer;
  • реализацию app controller.

Этап 3. Экран администратора и подготовка выборов

Включает:

  • конфигурацию выборов;
  • добавление кандидатов;
  • генерацию и импорт избирателей;
  • экспорт JSON с предупреждением;
  • регистрацию whitelist;
  • управление стадиями;
  • отображение статусов.

Этап 4. Экран голосования и квитанции

Включает:

  • ввод и загрузку приватного ключа;
  • проверку статуса избирателя;
  • отображение кандидатов;
  • отправку голоса;
  • очистку чувствительных данных;
  • генерацию TX Hash и QR‑квитанции.

Этап 5. Аудит, новые сессии и финальная стабилизация

Включает:

  • экран результатов;
  • расчёт явки и победителя;
  • security audit;
  • экспорт результатов;
  • реализацию “Нового голосования”;
  • быстрый и чистый режим новой сессии;
  • архивирование логов и результатов;
  • финальную отладку и приёмочное тестирование.

20. Итоговое требование к продукту

В результате разработки должен быть получен компактный, самодостаточный, безопасный и поддерживаемый desktop‑проект, который:

  • работает из одной корневой папки;
  • использует один смарт‑контракт;
  • не содержит избыточной token‑логики;
  • даёт возможность проводить несколько сессий голосования;
  • поддерживает темы и локализацию;
  • подходит для демонстрации, обучения и аудита защищённого on-chain голосования.

20. Управление версиями и миграция данных

20.1 Версионирование приложения

Каждый релиз должен иметь семантическую версию вида MAJOR.MINOR.PATCH (например, 1.0.0). Версия отображается в окне «О программе» и записывается в app.cfg и лог при старте.

20.2 Совместимость конфигурации

При запуске новой версии система должна проверять версию в app.cfg. Если файл отсутствует или версия старая, система должна создать резервную копию старого конфига и сгенерировать новый с настройками по умолчанию. Потеря пользовательских настроек темы/языка недопустима.

20.3 Миграция ABI смарт-контракта

Поскольку контракт обновляется только через деплой в новой сессии, миграция данных не требуется. Однако в коде приложения должна быть возможность указать в .env ожидаемую версию ABI (хеш). Если ABI развернутого контракта не совпадает с ожидаемым, приложение должно показать предупреждение.

20.4 Архивация старых сессий

При создании новой сессии (любой режим) система не должна автоматически удалять архивы старше 30 дней. Удаление только по явному действию администратора через UI или вручную.