From 4e210093a2b62a5fbdcbceb8a3d17edf478e7181 Mon Sep 17 00:00:00 2001 From: Igor Date: Mon, 25 May 2026 08:46:04 +0300 Subject: [PATCH] docs: polish English wording in roadmap and migration docs --- docs/EVENT_HASH_CANONICAL_MIGRATION.md | 64 ++-- docs/ROADMAP.md | 433 ++++++++++++------------- 2 files changed, 248 insertions(+), 249 deletions(-) diff --git a/docs/EVENT_HASH_CANONICAL_MIGRATION.md b/docs/EVENT_HASH_CANONICAL_MIGRATION.md index 6e4fb5c..204fc42 100644 --- a/docs/EVENT_HASH_CANONICAL_MIGRATION.md +++ b/docs/EVENT_HASH_CANONICAL_MIGRATION.md @@ -1,47 +1,47 @@ # Event Hash Canonical Migration -Этот runbook нужен для окружений, где в `audit.events` уже есть исторические строки, -созданные до перехода на canonical JSON-сериализацию. +This runbook is intended for environments where `audit.events` already contains +historical rows that were created before the switch to canonical JSON serialization. -## Почему это важно +## Why this matters -`event_hash` вычисляется как `SHA-256(payload_json)`. При смене правил сериализации -(порядок полей, формат `Instant`) один и тот же логический event может дать другой hash. -Без миграции historical rows проверка `DB event_hash == on-chain hash` будет расходиться. +`event_hash` is calculated as `SHA-256(payload_json)`. If the serialization rules +(field order, `Instant` format) change, the same logical event may produce a different hash. +Without this migration, the `DB event_hash == on-chain hash` check will fail for historical rows. -## Кого это касается +## Who this applies to -- **Новые окружения без данных**: миграция не требуется. -- **Окружения с существующими данными**: выполните шаги ниже до включения строгой сверки. +- **New environments with no data**: no migration is required. +- **Environments with existing data**: complete the steps below before turning on strict verification. -## План миграции +## Migration plan -1. **Остановить writers** (`event-store-service`, `audit-writer-service`), чтобы заморозить записи. -2. **Сделать backup** таблицы `audit.events`. -3. **Пересчитать canonical hash** для каждой строки по фактическому `payload` и обновить `event_hash`. -4. **Синхронизировать с blockchain (`AuditLedger`)**: - - для строк, которые еще не были заякорены on-chain, выполнить backfill через `appendAuditRecord(canonicalHash, timestamp, eventType, sourceAddress)`: - * `canonicalHash` — SHA-256 из пересчитанного payload, переданный как `bytes32` (`0x` + 64 hex chars, либо те же 32 raw bytes при вызове через Web3j); - * `timestamp` — Unix epoch seconds из `audit.events.created_at`; - * `eventType` — имя типа события (e.g., `USER_LOGGED_IN`) из `audit.events.event_type`; - * `sourceAddress` — адрес writer'а (owner контракта AuditLedger); - - для строк, уже заякоренных legacy hash, зафиксировать стратегию: либо отдельная историческая зона без строгого `DB == chain`, либо пересоздание окружения/ledger с canonical hash; - - убедиться, что для целевого набора данных нет "только DB" записей без on-chain отражения. -5. **Проверить консистентность**: - - нет `NULL` в `event_hash`; - - hash в lowercase hex, длина 64; - - выборочно проверить несколько событий end-to-end (DB -> blockchain). -6. **Запустить сервисы обратно** и включать строгую сверку только после успешной проверки. +1. **Stop the writers** (`event-store-service`, `audit-writer-service`) to prevent new writes. +2. **Back up** the `audit.events` table. +3. **Recalculate the canonical hash** for each row based on the actual `payload` and update `event_hash`. +4. **Synchronize with the blockchain (`AuditLedger`)**: + - for rows that have not yet been anchored on-chain, backfill them via `appendAuditRecord(canonicalHash, timestamp, eventType, sourceAddress)`: + * `canonicalHash` — the SHA-256 of the recalculated payload, passed as `bytes32` (`0x` + 64 hex chars, or the same 32 raw bytes when calling through Web3j); + * `timestamp` — Unix epoch seconds from `audit.events.created_at`; + * `eventType` — the event type name (e.g. `USER_LOGGED_IN`) from `audit.events.event_type`; + * `sourceAddress` — the writer address (the owner of the `AuditLedger` contract); + - for rows already anchored with a legacy hash, define the strategy up front: either keep a separate historical zone without strict `DB == chain`, or recreate the environment/ledger with canonical hashes; + - make sure there are no "DB-only" records for the target dataset without an on-chain counterpart. +5. **Verify consistency**: + - no `NULL` values in `event_hash`; + - hashes are stored as lowercase hex and are 64 characters long; + - spot-check several events end-to-end (DB -> blockchain). +6. **Restart the services** and enable strict verification only after all checks pass. -## Минимальные SQL-проверки +## Minimal SQL checks ```sql --- 1) Пустые hash (должно быть 0) +-- 1) Empty hashes (should be 0) SELECT count(*) AS null_hashes FROM audit.events WHERE event_hash IS NULL; --- 2) Невалидный формат (должно быть 0) +-- 2) Invalid format (should be 0) SELECT count(*) AS invalid_format FROM audit.events WHERE event_hash IS NULL @@ -49,8 +49,8 @@ WHERE event_hash IS NULL OR event_hash !~ '^[0-9a-f]{64}$'; ``` -## Примечание по backfill +## Backfill note -Backfill должен использовать тот же canonical mapper, что и сервисы (`CanonicalObjectMapperFactory`). -Это гарантирует одинаковый digest в `event-store-service` и `audit-writer-service`. +The backfill must use the same canonical mapper as the services (`CanonicalObjectMapperFactory`). +This guarantees that `event-store-service` and `audit-writer-service` produce identical digests. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 8f5a7ae..16eab3b 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,70 +1,70 @@ -# GitHub Issues Plan для Distributed Audit Ledger +# GitHub Issue Plan for Distributed Audit Ledger -## Структура Issues +## Issue Structure -Все issues будут связаны через: +All issues will be connected through: - Labels: `backend`, `blockchain`, `frontend`, `infra`, `docs` -- Project Board: для отслеживания статуса (TODO, In Progress, Done) -- Каждый issue будет связан с PR через `Closes #XX` или `Relates to #XX` +- Project Board: to track status (`TODO`, `In Progress`, `Done`) +- PR links: each issue should be linked from a PR via `Closes #XX` or `Relates to #XX` --- ## MVP Phase (Phase 1) — ✅ COMPLETE (Issues #1–#13) -### 1. [SETUP] Инициализация репозитория +### 1. [SETUP] Repository Initialization **ID:** #1 **Labels:** `infra`, `docs` **Description:** -- Создать базовую структуру каталогов согласно архитектуре -- Инициализировать основные конфигурационные файлы -- Добавить LICENSE (MIT) -- Написать базовый README.md -- Добавить .gitignore для Java, Node.js, Solidity +- Create the base directory structure defined by the architecture +- Initialize the main configuration files +- Add `LICENSE` (MIT) +- Write an initial `README.md` +- Add `.gitignore` entries for Java, Node.js, and Solidity **Subtasks:** -- [x] #1.1 - Создать folder structure -- [x] #1.2 - Инициализировать Git репозиторий -- [x] #1.3 - Создать изначальный README и LICENSE +- [x] #1.1 - Create folder structure +- [x] #1.2 - Initialize the Git repository +- [x] #1.3 - Create the initial `README` and `LICENSE` **Expected PR:** PR-1 (Initial repository setup) --- -### 2. [INFRA] Docker Compose для инфраструктуры +### 2. [INFRA] Docker Compose for Infrastructure **ID:** #2 **Labels:** `infra` **Depends on:** #1 **Description:** -Поднять docker-compose с основными сервисами: +Set up `docker-compose` with the core services: - PostgreSQL (port 5432) - Kafka + Zookeeper -- Ganache (локальный блокчейн, port 8545) -- pgAdmin (для управления БД) +- Ganache (local blockchain, port 8545) +- pgAdmin (for database management) **Acceptance Criteria:** -- `docker-compose up` запускает все сервисы -- БД готова к подключению -- Kafka доступен на port 9092 -- Ganache готов к деплою контрактов +- `docker-compose up` starts all services +- The database accepts connections +- Kafka is available on port 9092 +- Ganache is ready for contract deployment **Subtasks:** -- [x] #2.1 - docker-compose.yml с всеми сервисами -- [x] #2.2 - .env файлы с конфигурацией -- [x] #2.3 - Скрипты инициализации БД (схема) -- [x] #2.4 - README для запуска инфраструктуры +- [x] #2.1 - `docker-compose.yml` with all services +- [x] #2.2 - `.env` files with configuration +- [x] #2.3 - Database initialization scripts (schema) +- [x] #2.4 - `README` for starting the infrastructure stack **Expected PR:** PR-2 (Docker Compose setup) --- -### 3. [BLOCKCHAIN] Смарт-контракт AuditLedger +### 3. [BLOCKCHAIN] AuditLedger Smart Contract **ID:** #3 **Labels:** `blockchain` **Depends on:** #2 **Description:** -Разработать Solidity смарт-контракт для хранения хэшей событий. +Implement a Solidity smart contract for storing event hashes. -**Требования:** +**Requirements:** ```solidity contract AuditLedger { struct AuditRecord { @@ -82,23 +82,23 @@ contract AuditLedger { ``` **Subtasks:** -- [x] #3.1 - Написать AuditLedger.sol контракт -- [x] #3.2 - Написать тесты (Hardhat) -- [x] #3.3 - Создать deployment скрипт -- [x] #3.4 - Документация по контракту +- [x] #3.1 - Write the `AuditLedger.sol` contract +- [x] #3.2 - Write tests (Hardhat) +- [x] #3.3 - Create the deployment script +- [x] #3.4 - Document the contract **Expected PR:** PR-3 (Smart contract implementation) --- -### 4. [BACKEND] Инициализация Maven проекта +### 4. [BACKEND] Maven Project Initialization **ID:** #4 **Labels:** `backend`, `infra` **Depends on:** #1, #2 **Description:** -Создать Multi-Module Maven проект для backend сервисов. +Create a multi-module Maven project for the backend services. -**Структура:** +**Structure:** ``` backend/ ├── pom.xml (parent) @@ -112,54 +112,54 @@ backend/ ``` **Subtasks:** -- [x] #4.1 - Создать parent pom.xml с зависимостями -- [x] #4.2 - Создать common модули -- [x] #4.3 - Создать скелеты сервисов +- [x] #4.1 - Create the parent `pom.xml` with shared dependencies +- [x] #4.2 - Create the common modules +- [x] #4.3 - Create service skeletons **Expected PR:** PR-4 (Maven project structure) --- -### 5. [BACKEND] Command Service - скелет +### 5. [BACKEND] Command Service - Skeleton **ID:** #5 **Labels:** `backend` **Depends on:** #4, #2 **Description:** -Создать основу Command Service: Spring Boot приложение с REST API для приема команд. +Build the initial Command Service: a Spring Boot application with a REST API for accepting commands. -**Требования:** +**Requirements:** - Spring Boot 4.x + WebFlux setup - REST controller: `POST /commands/user/login` -- Kafka producer для публикации событий -- Simple in-memory event storage (позже заменим на БД) +- Kafka producer for publishing events +- Simple in-memory event storage (to be replaced with the database later) **Acceptance Criteria:** -- Сервис запускается на port 8081 -- Можно отправить POST команду `curl -X POST http://localhost:8081/commands/user/login -H "Content-Type: application/json" -d '{"userId": "user1"}'` -- Событие публикуется в Kafka topic `user.login.events` +- The service starts on port 8081 +- A POST request can be sent with `curl -X POST http://localhost:8081/commands/user/login -H "Content-Type: application/json" -d '{"userId": "user1"}'` +- The event is published to the Kafka topic `user.login.events` **Subtasks:** -- [x] #5.1 - Spring Boot приложение с Kafka producer -- [x] #5.2 - REST endpoint для `UserLoggedIn` события -- [x] #5.3 - Event DTO класс -- [x] #5.4 - application.yml и конфигурация +- [x] #5.1 - Spring Boot application with Kafka producer +- [x] #5.2 - REST endpoint for the `UserLoggedIn` event +- [x] #5.3 - Event DTO class +- [x] #5.4 - `application.yml` and configuration **Expected PR:** PR-5 (Command Service skeleton) --- -### 6. [BACKEND] Event Store - сервис записи в БД +### 6. [BACKEND] Event Store - Database Write Service **ID:** #6 **Labels:** `backend` **Depends on:** #4, #2 **Description:** -Создать сервис для чтения события из Kafka и сохранения в PostgreSQL. +Create a service that reads events from Kafka and persists them to PostgreSQL. -**Требования:** -- Spring Boot приложение -- Kafka consumer подписан на `user.login.events` -- Spring Data R2DBC для сохранения в БД -- Таблица `audit.events` (id, event_id, aggregate_id, event_type, user_id, payload, created_at, event_hash) +**Requirements:** +- Spring Boot application +- Kafka consumer subscribed to `user.login.events` +- Spring Data R2DBC for database persistence +- `audit.events` table (`id`, `event_id`, `aggregate_id`, `event_type`, `user_id`, `payload`, `created_at`, `event_hash`) **Schema:** ```sql @@ -177,10 +177,10 @@ CREATE TABLE audit.events ( **Subtasks:** - [x] #6.1 - Spring Boot + Spring Data R2DBC setup -- [x] #6.2 - Entity класс и repository +- [x] #6.2 - Entity class and repository - [x] #6.3 - Kafka consumer -- [x] #6.4 - Liquibase / Flyway миграции -- [x] #6.5 - Тесты +- [x] #6.4 - Liquibase / Flyway migrations +- [x] #6.5 - Tests **Expected PR:** PR-6 (Event Store service) @@ -191,22 +191,22 @@ CREATE TABLE audit.events ( **Labels:** `backend`, `blockchain` **Depends on:** #3, #6, #2 **Description:** -Создать сервис для записи хэшей событий в блокчейне. +Create a service that writes event hashes to the blockchain. -**Требования:** -- Kafka consumer на том же топике `user.login.events` -- Вычисление SHA-256 хэша события -- Web3j клиент для взаимодействия с Ganache -- Вызов `appendAuditRecord` на смарт-контракте -- Обработка транзакций и ошибок +**Requirements:** +- Kafka consumer on the same topic: `user.login.events` +- SHA-256 event hash calculation +- Web3j client for interacting with Ganache +- Call `appendAuditRecord` on the smart contract +- Robust transaction and error handling **Subtasks:** -- [x] #7.1 - Web3j setup и конфигурация для Ganache +- [x] #7.1 - Web3j setup and configuration for Ganache - [x] #7.2 - Contract wrapper (ABI-aligned bindings) -- [x] #7.3 - Kafka consumer с обработкой событий -- [x] #7.4 - Hash calculation и blockchain write logic -- [x] #7.5 - Retry механизм при сбое -- [x] #7.6 - Тесты с test containers +- [x] #7.3 - Kafka consumer with event processing +- [x] #7.4 - Hash calculation and blockchain write logic +- [x] #7.5 - Retry mechanism on failure +- [x] #7.6 - Tests with Testcontainers **Expected PR:** PR-7 (Audit Writer Service) @@ -217,33 +217,33 @@ CREATE TABLE audit.events ( **Labels:** `backend` **Depends on:** #6, #2 **Description:** -Создать Query Service с REST API для получения истории событий. +Create a Query Service with a REST API for retrieving event history. **Endpoints:** -- `GET /api/audit-logs` - список событий с фильтром -- `GET /api/audit-logs/{id}` - деталь события -- Query параметры: `?userId=...&eventType=...&from=...&to=...` +- `GET /api/audit-logs` - list events with filters +- `GET /api/audit-logs/{id}` - event details +- Query parameters: `?userId=...&eventType=...&from=...&to=...` **Subtasks:** - [x] #8.1 - Spring Boot WebFlux setup + reactive filtering/query layer - [x] #8.2 - REST controllers -- [x] #8.3 - DTOs и MapStruct mappers -- [x] #8.4 - Reactive filtering/query logic (R2DBC repository/DatabaseClient) -- [x] #8.5 - Тесты +- [x] #8.3 - DTOs and MapStruct mappers +- [x] #8.4 - Reactive filtering/query logic (`R2DBC repository` / `DatabaseClient`) +- [x] #8.5 - Tests **Expected PR:** PR-8 (Query Service MVP) --- -### 9. [BACKEND] Проверка целостности событий +### 9. [BACKEND] Event Integrity Check **ID:** #9 **Labels:** `backend`, `blockchain` **Depends on:** #7, #8 **Description:** -Добавить endpoint для проверки, что хэш события есть в блокчейне. +Add an endpoint that verifies whether an event hash exists on the blockchain. **Endpoint:** -- `GET /api/audit-logs/{id}/integrity-check` → проверить хэш в контракте +- `GET /api/audit-logs/{id}/integrity-check` → verify the hash against the contract **Response:** ```json @@ -261,88 +261,88 @@ CREATE TABLE audit.events ( } ``` -> Возможные значения `status`: `ON_CHAIN` (хэш найден в блокчейне), `MISMATCH` (хэш есть в БД, но не в блокчейне), `PENDING` (хэш ещё не был записан в блокчейн — поле `event_hash` отсутствует в БД). +> Possible `status` values: `ON_CHAIN` (the hash was found on the blockchain), `MISMATCH` (the hash exists in the database but not on-chain), and `PENDING` (the hash has not yet been written to the blockchain — the `event_hash` field is missing in the database). **Subtasks:** -- [x] #9.1 - Web3j клиент для чтения из контракта -- [x] #9.2 - Service для проверки хэша +- [x] #9.1 - Web3j client for reading from the contract +- [x] #9.2 - Service for hash verification - [x] #9.3 - REST endpoint -- [x] #9.4 - Интеграционные тесты (SpringBootTest + Testcontainers PostgreSQL: 11 сценариев — ON_CHAIN, MISMATCH, PENDING, 404, 503, 500, query filters) +- [x] #9.4 - Integration tests (`SpringBootTest` + `Testcontainers` PostgreSQL: 11 scenarios — `ON_CHAIN`, `MISMATCH`, `PENDING`, `404`, `503`, `500`, query filters) **Expected PR:** PR-9 (Integrity check endpoint) --- -### 10. [FRONTEND] Базовый UI на Angular +### 10. [FRONTEND] Basic Angular UI **ID:** #10 **Labels:** `frontend` **Depends on:** #8 **Description:** -Создать Angular приложение с базовый таблицей аудита. +Create an Angular application with a basic audit log table. -**Требования:** +**Requirements:** - Angular 17+ - Material Design components -- Таблица событий с колонками: ID, Тип события, Пользователь, Время, Статус целостности -- Фильтры по типу события и пользователю -- Детальный просмотр события (drawer / modal) +- Event table with columns: ID, Event Type, User, Time, Integrity Status +- Filters by event type and user +- Detailed event view (drawer / modal) **Subtasks:** -- [x] #10.1 - Angular проект setup (ng new) +- [x] #10.1 - Angular project setup (`ng new`) - [x] #10.2 - Material modules setup -- [x] #10.3 - Components для таблицы и фильтров -- [x] #10.4 - HTTP client для Query Service -- [x] #10.5 - Роутинг и layout -- [x] #10.6 - Стили и responsive дизайн +- [x] #10.3 - Components for the table and filters +- [x] #10.4 - HTTP client for Query Service +- [x] #10.5 - Routing and layout +- [x] #10.6 - Styling and responsive design **Expected PR:** PR-10 (Angular UI skeleton) --- -### 11. [FRONTEND] Интеграция с Backend API +### 11. [FRONTEND] Integration with Backend API **ID:** #11 **Labels:** `frontend` **Depends on:** #10, #8, #9 **Description:** -Подключить Frontend к Query Service и Integrity Check APIs. +Integrate the frontend with the Query Service and Integrity Check APIs. **Requirements:** -- Angular HttpClient для запросов -- RxJS observables для обработки async данных -- Таблица событий с реальными данными из БД -- Индикатор целостности в таблице (OK / MISMATCH) -- Детальный просмотр с проверкой blockchain записи +- Angular `HttpClient` for requests +- RxJS observables for handling asynchronous data +- Event table with real data from the database +- Integrity indicator in the table (`OK` / `MISMATCH`) +- Detailed view with blockchain record verification **Subtasks:** -- [x] #11.1 - Services для HTTP запросов -- [x] #11.2 - Models / Interfaces для типизации -- [x] #11.3 - Таблица с real data -- [x] #11.4 - Pagination и lazy loading -- [x] #11.5 - Error handling и loading states -- [x] #11.6 - Unit тесты +- [x] #11.1 - Services for HTTP requests +- [x] #11.2 - Models / interfaces for typing +- [x] #11.3 - Table with live data +- [x] #11.4 - Pagination and lazy loading +- [x] #11.5 - Error handling and loading states +- [x] #11.6 - Unit tests **Expected PR:** PR-11 (Frontend API integration) --- -### 12. [DOCS] Документация архитектуры +### 12. [DOCS] Architecture Documentation **ID:** #12 **Labels:** `docs` **Depends on:** #1 **Description:** -Написать подробную документацию архитектуры с диаграммами. +Write detailed architecture documentation with diagrams. -**Файлы:** -- `docs/ARCHITECTURE.md` - описание всех компонентов -- `docs/CQRS_FLOW.md` - flow диаграмма -- `docs/DEPLOYMENT.md` - инструкции по развертыванию -- `docs/TESTING_SCENARIOS.md` - live demo сценарии +**Files:** +- `docs/ARCHITECTURE.md` - overview of all components +- `docs/CQRS_FLOW.md` - flow diagram +- `docs/DEPLOYMENT.md` - deployment instructions +- `docs/TESTING_SCENARIOS.md` - live demo scenarios **Subtasks:** -- [x] #12.1 - ARCHITECTURE.md с диаграммами (ASCII art) -- [x] #12.2 - CQRS_FLOW.md - пошаговый flow с примерами -- [x] #12.3 - DEPLOYMENT.md - quickstart guide -- [x] #12.4 - TESTING_SCENARIOS.md - curl команды и скриншоты ✅ screenshot pack added +- [x] #12.1 - `ARCHITECTURE.md` with diagrams (ASCII art) +- [x] #12.2 - `CQRS_FLOW.md` - step-by-step flow with examples +- [x] #12.3 - `DEPLOYMENT.md` - quickstart guide +- [x] #12.4 - `TESTING_SCENARIOS.md` - curl commands and screenshots ✅ screenshot pack added **Expected PR:** PR-12 (Architecture documentation) ✅ Implemented via PR #124 @@ -353,56 +353,56 @@ CREATE TABLE audit.events ( **Labels:** `infra` **Depends on:** #4, #5, #6, #7, #8, #10 **Description:** -Настроить GitHub Actions для автоматизированного тестирования и сборки. +Set up GitHub Actions for automated testing and builds. **Pipeline (expanded):** -- Backend: `mvn clean verify` из `backend/` (включая `common/*` и сервисы) -- Frontend: `npm test` + `npm run build` из `frontend/audit-ui/` -- Blockchain: `hardhat test` из `blockchain/` -- SonarQube: анализ всех исходников (backend + frontend + blockchain) -- Telegram: уведомление в канал о результате всех фаз pipeline +- Backend: `mvn clean verify` from `backend/` (including `common/*` and all services) +- Frontend: `npm test` + `npm run build` from `frontend/audit-ui/` +- Blockchain: `hardhat test` from `blockchain/` +- SonarQube: analysis of all source code (backend + frontend + blockchain) +- Telegram: channel notification with the outcome of every pipeline phase **Acceptance Criteria:** -- На `push` в `main` и на `pull_request` запускаются backend/frontend/blockchain проверки -- SonarQube job запускается при наличии настроенных `SONAR_TOKEN` и variables проекта -- Telegram notification отправляется в конце pipeline и содержит статусы ключевых jobs -- При отсутствии Telegram secrets и/или Sonar token pipeline не падает (шаги помечаются как skipped) -- Требования и subtasks синхронизированы между `docs/ROADMAP.md`, GitHub Issue #13 и GitHub Project +- On `push` to `main` and on `pull_request`, backend/frontend/blockchain checks run +- The SonarQube job runs when `SONAR_TOKEN` and project variables are configured +- A Telegram notification is sent at the end of the pipeline and includes the status of the key jobs +- If Telegram secrets and/or the Sonar token are missing, the pipeline does not fail (those steps are marked as skipped) +- Requirements and subtasks are synchronized between `docs/ROADMAP.md`, GitHub Issue #13, and GitHub Project **Subtasks:** -- [x] #13.1 - Backend tests workflow (maven) -- [x] #13.2 - Frontend tests/build workflow (npm) -- [x] #13.3 - Blockchain tests workflow (hardhat) +- [x] #13.1 - Backend test workflow (Maven) +- [x] #13.2 - Frontend test/build workflow (npm) +- [x] #13.3 - Blockchain test workflow (Hardhat) - [x] #13.4 - SonarQube phase for backend sources - [x] #13.5 - SonarQube phase for frontend sources - [x] #13.6 - SonarQube phase for blockchain sources - [x] #13.7 - Telegram notification job for full pipeline status -- [x] #13.8 - Synchronize subtasks in GitHub Issue #13 and GitHub Project board +- [x] #13.8 - Synchronize subtasks in GitHub Issue #13 and the GitHub Project board **Expected PR:** PR-13 (CI/CD setup) --- -## Phase 2 - Расширения +## Phase 2 - Extensions -### 14. [BACKEND] Поддержка дополнительных типов событий +### 14. [BACKEND] Support for Additional Event Types **ID:** #14 **Labels:** `backend` **Depends on:** #5, #6 **Description:** -Добавить поддержку событий: +Add support for the following event types: - `UserProfileChanged` - `EntityCreated` - `EntityUpdated` - `DataDeleted` **Subtasks:** -- [x] #14.1 - Event DTO классы для новых типов +- [x] #14.1 - Event DTO classes for the new types - [x] #14.2 - Command endpoints - [x] #14.3 - Database schema updates - [x] #14.4 - Tests -**Expected PR:** PR-14 (Event types expansion) +**Expected PR:** PR-14 (Event type expansion) --- @@ -411,77 +411,77 @@ CREATE TABLE audit.events ( **Labels:** `backend`, `frontend` **Depends on:** #5, #8, #10 **Description:** -Добавить JWT аутентификацию и роли. +Add JWT-based authentication and role-based authorization. **Requirements:** - Spring Security + JWT tokens -- Роли: `AUDITOR`, `ADMIN`, `USER` +- Roles: `AUDITOR`, `ADMIN`, `USER` - Login endpoint: `POST /auth/login` - Token-based requests **Subtasks:** - [x] #15.1 - Spring Security setup -- [x] #15.2 - JWT token generation и validation +- [x] #15.2 - JWT token generation and validation - [x] #15.3 - Login endpoint - [x] #15.4 - Role-based access control - [x] #15.5 - Frontend authentication service -- [x] #15.6 - Protected routes в Angular +- [x] #15.6 - Protected routes in Angular **Expected PR:** PR-15 (Authentication & Authorization) --- -### 16. [FRONTEND] Advanced filtering и search +### 16. [FRONTEND] Advanced Filtering and Search **ID:** #16 **Labels:** `frontend` **Depends on:** #11 **Status:** ✅ Done **Description:** -Улучшить UI с расширенным поиском и фильтрацией. +Enhance the UI with advanced search and filtering. **Features:** -- Полнотекстовый поиск по содержимому события -- Дата-рейнж пикер -- Множественные фильтры одновременно -- Сохранение фильтров в URL -- Export в CSV +- Full-text search across event content +- Date-range picker +- Multiple filters applied at the same time +- Persist filters in the URL +- Export to CSV **Subtasks:** -- [x] #16.1 - Query параметры в URL +- [x] #16.1 - Query parameters in the URL - [x] #16.2 - Advanced filter components -- [x] #16.3 - Date range picker -- [x] #16.4 - Export функционал -- [x] #16.5 - State management (localStorage) +- [x] #16.3 - Date-range picker +- [x] #16.4 - Export functionality +- [x] #16.5 - State management (`localStorage`) **Expected PR:** PR-16 (Advanced filtering) --- -### 17. [FRONTEND] Event timeline visualization +### 17. [FRONTEND] Event Timeline Visualization **ID:** #17 **Labels:** `frontend` **Depends on:** #16 **Status:** ✅ Done **Description:** -Добавить timeline view событий. +Add a timeline view for events. **Features:** -- Временная шкала событий -- Группировка по дням/часам -- Интерактивные точки на timeline -- Быстрый переход между событиями +- Event timeline +- Grouping by day and hour +- Interactive timeline points +- Quick navigation between events **Acceptance Criteria:** -- Timeline view отображает события текущего набора результатов, сгруппированные по дням и часам -- Клик по событию открывает drawer с деталями и проверкой целостности -- Layout остаётся удобным на мобильных устройствах -- Покрытие тестами для нового/изменённого frontend-кода составляет не менее 80% +- The timeline view displays events from the current result set, grouped by day and hour +- Clicking an event opens a drawer with details and integrity verification +- The layout remains usable on mobile devices +- Test coverage for new or changed frontend code is at least 80% **Subtasks:** - [x] #17.1 - Timeline component - [x] #17.2 - Event grouping logic -- [x] #17.3 - Styling и animations -- [x] #17.4 - Responsive на мобильных +- [x] #17.3 - Styling and animations +- [x] #17.4 - Responsive behavior on mobile - [x] #17.5 - Unit tests and coverage >= 80% **Expected PR:** PR-17 (Timeline visualization) @@ -494,43 +494,43 @@ CREATE TABLE audit.events ( **Depends on:** #9, #14 **Status:** ✅ Done **Description:** -Создать сервис для проверки целостности всех записей и поиска "подорванных" данных. +Create a service that verifies the integrity of all records and identifies compromised data. **Features:** -- Batch проверка всех событий -- Отчет о несоответствиях -- Автоматический запуск по расписанию (Quartz) -- Endpoint для ручной проверки +- Batch verification of all events +- Mismatch report +- Scheduled automatic execution (Quartz) +- Endpoint for manual verification **Subtasks:** - [x] #18.1 - Batch integrity checker logic - [x] #18.2 - Scheduled task setup (Quartz) - [x] #18.3 - Reconciliation report service -- [x] #18.4 - REST endpoint для запуска проверки -- [x] #18.5 - Тесты +- [x] #18.4 - REST endpoint to trigger verification +- [x] #18.5 - Tests **Expected PR:** PR-18 (Reconciliation Service) --- -### 19. [INFRA] Kubernetes манифесты +### 19. [INFRA] Kubernetes Manifests **ID:** #19 **Labels:** `infra` **Depends on:** #13 **Status:** ✅ Done **Description:** -Создать K8s Deployments для production развертывания. +Create Kubernetes deployment manifests for production. **Resources:** -- Deployment для каждого сервиса +- Deployment for each service - Services, ConfigMaps, Secrets - Helm chart -- Ingress конфигурация +- Ingress configuration **Subtasks:** -- [x] #19.1 - K8s deployments для backend сервисов -- [x] #19.2 - K8s deployments для frontend -- [x] #19.3 - ConfigMaps и StatefulSets для Kafka/PostgreSQL +- [x] #19.1 - Kubernetes deployments for backend services +- [x] #19.2 - Kubernetes deployments for the frontend +- [x] #19.3 - ConfigMaps and StatefulSets for Kafka/PostgreSQL - [x] #19.4 - Helm chart - [x] #19.5 - Ingress setup @@ -538,26 +538,26 @@ CREATE TABLE audit.events ( --- -### 20. [DOCS] Live Demo сценарий +### 20. [DOCS] Live Demo Scenario **ID:** #20 **Labels:** `docs` **Depends on:** #12, #18 **Status:** ✅ Done **Description:** -Подготовить готовый сценарий для демонстрации на собеседовании. +Prepare a polished demo scenario for interviews. **Content:** -- Step-by-step инструкции -- Shell/curl команды для тестирования -- Скриншоты UI -- Объяснение архитектурных решений -- Потенциальные вопросы и ответы +- Step-by-step instructions +- Shell/curl commands for testing +- UI screenshots +- Rationale behind key architecture decisions +- Potential questions and answers **Subtasks:** -- [x] #20.1 - Написать guide -- [x] #20.2 - Prepare curl команды -- [x] #20.3 - Prepare скриншоты UI -- [x] #20.4 - Q&A документ +- [x] #20.1 - Write the guide +- [x] #20.2 - Prepare curl commands +- [x] #20.3 - Prepare UI screenshots +- [x] #20.4 - Q&A document **Expected PR:** PR-20 (Demo scenario documentation) @@ -569,16 +569,16 @@ CREATE TABLE audit.events ( ## Labels Reference -| Label | Описание | -|-------|----------| -| `backend` | Java/Spring Backend работы | -| `blockchain` | Solidity/Web3 работы | -| `frontend` | Angular/TypeScript работы | -| `infra` | Docker, K8s, CI/CD | -| `docs` | Документация | -| `bug` | Баг или issue | -| `enhancement` | Улучшение существующей функции | -| `question` | Вопрос или обсуждение | +| Label | Description | +|-------|-------------| +| `backend` | Java/Spring backend work | +| `blockchain` | Solidity/Web3 work | +| `frontend` | Angular/TypeScript work | +| `infra` | Docker, Kubernetes, CI/CD | +| `docs` | Documentation | +| `bug` | Bug or issue | +| `enhancement` | Improvement to an existing feature | +| `question` | Question or discussion | --- @@ -607,19 +607,19 @@ CREATE TABLE audit.events ( --- -## Migration Path (PR linking) +## Migration Path (PR Linking) -Каждый PR должен быть связан с Issue через: +Each PR must be linked to an issue via: ``` Closes #XX Relates to #YY ``` -**Пример PR description:** +**Example PR description:** -```markdown +````markdown ## Description -Implements basic Command Service with Kafka producer +This PR implements a basic Command Service with a Kafka producer. ## Closes - Closes #5 @@ -632,7 +632,7 @@ Implements basic Command Service with Kafka producer - [ ] Code follows style guidelines - [ ] Self-review completed - [ ] Comments added for complex logic -- [ ] Tests added/updated +- [ ] Tests added or updated - [ ] Documentation updated ## Testing @@ -644,15 +644,14 @@ curl -X POST http://localhost:8081/commands/user/login ... ## Screenshots (if applicable) -``` +```` --- ## Notes -1. **Последовательность фаз:** MVP phase должна быть завершена перед Phase 2 -2. **Branching strategy:** Каждый issue → branch по шаблону `/#XX-description`, где `type` = `feature|fix|docs|test` -3. **PR reviews:** Minimum 1 approval перед merge -4. **Commit messages:** `[#XX] Brief description` (с номером issue) -5. **Project board:** Используем GitHub Project для визуализации статуса - +1. **Phase order:** The MVP phase must be complete before Phase 2 begins +2. **Branching strategy:** Each issue should use a branch named `/#XX-description`, where `type` = `feature|fix|docs|test` +3. **PR reviews:** At least 1 approval is required before merge +4. **Commit messages:** `[#XX] Brief description` (including the issue number) +5. **Project board:** Use GitHub Projects to visualize status