From ca79457c195e449cfe3a8ca25f3b9d03c5d977fb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 25 Feb 2026 18:25:53 +0000 Subject: [PATCH] docs: add professional Russian-language README files for 7 components - boot: CLI blockchain initialization utility - cleos: EOSIO cleos wrapper with wallet container - controller: NestJS GraphQL API backend - desktop: Vue 3 + Quasar cooperative workspace - factory: legal document generator library - parser: blockchain indexer via SHiP - setup: interactive setup wizard Co-authored-by: Alex Ant --- components/boot/README.md | 101 ++++++++++++++- components/cleos/README.md | 77 ++++++++++++ components/controller/README.md | 128 ++++++++++++++++++- components/desktop/README.md | 112 +++++++++++++---- components/factory/README.md | 178 ++++++++++++++++---------- components/parser/README.md | 214 +++++++++++++++----------------- components/setup/README.md | 71 +++++++++++ 7 files changed, 676 insertions(+), 205 deletions(-) create mode 100644 components/cleos/README.md create mode 100644 components/setup/README.md diff --git a/components/boot/README.md b/components/boot/README.md index c17710748d9..fc98e55209e 100644 --- a/components/boot/README.md +++ b/components/boot/README.md @@ -1 +1,100 @@ -# Загрузчик. +# 🚀 @coopenomics/boot + +CLI-утилита для инициализации блокчейн-инфраструктуры кооператива. Создаёт системные аккаунты, устанавливает смарт-контракты, настраивает токены и разворачивает кооперативную среду. Включает интеграционные тесты для основных подсистем платформы. + +## Основные возможности + +- Полный цикл развёртывания блокчейна EOSIO — от запуска ноды до создания кооператива +- Установка системных и прикладных смарт-контрактов +- Инициализация токенов и создание тестовых данных +- Управление Docker-контейнерами блокчейн-ноды +- Интеграционные тесты: паевые взносы (capital), кошелёк (wallet), регистрация участников (registrator) +- Поддержка нескольких режимов загрузки: стандартный, чистый и расширенный + +## Установка + +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: + +```bash +pnpm install +``` + +Или только для этого компонента: + +```bash +pnpm install --filter @coopenomics/boot +``` + +## Скрипты + +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `boot` | `pnpm run boot` | Запуск блокчейна и установка контрактов | +| `boot:clean` | `pnpm run boot:clean` | Чистый запуск с полной переустановкой | +| `boot:extra` | `pnpm run boot:extra` | Расширенная инициализация с дополнительными данными | +| `deploy` | `pnpm run deploy` | Развёртывание контрактов на запущенной ноде | +| `cli` | `pnpm run cli` | Интерактивный командный интерфейс (Commander.js) | +| `clear` | `pnpm run clear` | Очистка данных блокчейна | +| `start` | `pnpm run start` | Перезапуск ноды | +| `stop` | `pnpm run stop` | Остановка ноды | +| `test` | `pnpm run test` | Интеграционные тесты (capital) | +| `test:all` | `pnpm run test:all` | Все интеграционные тесты | + +## Конфигурация + +Скопируйте `.env-example` в `.env` и настройте переменные окружения: + +- Endpoint блокчейн-ноды (API) +- Строка подключения к MongoDB +- Строка подключения к реляционной БД +- Приватные ключи для развёртывания контрактов + +Подробное описание переменных — в файле `.env-example`. + +## Тестирование + +Перед запуском тестов необходима работающая инфраструктура (см. `docker-compose.yaml` в корне проекта): + +```bash +pnpm --filter @coopenomics/boot run test +pnpm --filter @coopenomics/boot run test:all +``` + +Тесты используют **Vitest** с таймаутом 240 секунд — это связано с ожиданием подтверждения блокчейн-транзакций. + +## Архитектура + +``` +src/ +├── index.ts # Точка входа CLI (Commander.js) +├── init/ # Логика инициализации +│ ├── booter.ts # Загрузчик блокчейна +│ ├── cooperative.ts # Настройка кооператива +│ ├── infra.ts # Инфраструктурная инициализация +│ └── participant.ts # Создание участников +├── blockchain/ # Взаимодействие с EOSIO (eosjs) +├── docker/ # Управление Docker-контейнерами +├── configs/ # Конфигурация ноды и протокол-фичи +├── tests/ # Интеграционные тесты +│ ├── capital.test.ts # Тесты паевых взносов +│ ├── wallet.test.ts # Тесты кошелька +│ └── registrator.test.ts # Тесты регистрации +└── utils/ # Вспомогательные утилиты +scripts/ +├── reboot.sh # Полный перезапуск +├── clean_reboot.sh # Чистый перезапуск +└── extra_reboot.sh # Расширенный перезапуск +``` + +## Ключевые зависимости + +- **eosjs** — взаимодействие с блокчейном EOSIO +- **commander** — CLI-фреймворк +- **dockerode** — управление Docker-контейнерами из Node.js +- **mongoose** — работа с MongoDB +- **pg** — работа с реляционной БД +- **vitest** — тестирование + +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/cleos/README.md b/components/cleos/README.md new file mode 100644 index 00000000000..ba2086008d2 --- /dev/null +++ b/components/cleos/README.md @@ -0,0 +1,77 @@ +# 🔑 @coopenomics/cleos + +Обёртка над утилитой `cleos` из набора инструментов EOSIO. Запускает Docker-контейнер с предустановленным кошельком для прямого взаимодействия с блокчейном — отправки транзакций, просмотра таблиц контрактов, управления ключами и аккаунтами. + +## Основные возможности + +- Готовая среда с кошельком и ключами для локальной разработки +- Отправка транзакций в блокчейн +- Просмотр таблиц смарт-контрактов +- Управление аккаунтами и ключами блокчейна +- Разблокировка и сброс кошелька через вспомогательные скрипты + +## Установка + +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: + +```bash +pnpm install +``` + +## Скрипты + +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `run` | `pnpm run run` | Запуск Docker-контейнера с кошельком | + +Из корня монорепозитория можно использовать: + +```bash +pnpm run enter +``` + +## Использование + +Для работы необходима запущенная инфраструктура (см. `docker-compose.yaml` в корне проекта). + +### Запуск + +```bash +pnpm run enter +``` + +### Внутри контейнера + +```bash +./unlock.sh # Разблокировка кошелька +./cleos.sh get info # Информация о блокчейне +./cleos.sh get table # Просмотр таблиц +``` + +### Вспомогательные скрипты + +| Скрипт | Назначение | +|--------|-----------| +| `unlock.sh` | Разблокировка кошелька (пароль применяется автоматически) | +| `cleos.sh` | Прокси-вызов `cleos` с настроенным подключением к ноде | +| `reset.sh` | Сброс состояния кошелька | + +## Конфигурация + +Кошелёк использует дефолтный ключ для локальной среды разработки. Пароль хранится в файле `password` внутри директории `eosio-wallet` и применяется автоматически при разблокировке. + +## Архитектура + +``` +├── run.sh # Скрипт запуска Docker-контейнера +├── eosio-wallet/ # Хранилище кошелька +│ └── password # Пароль для разблокировки +└── scripts/ # Вспомогательные скрипты + ├── unlock.sh # Разблокировка кошелька + ├── cleos.sh # Прокси-вызов cleos + └── reset.sh # Сброс кошелька +``` + +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/controller/README.md b/components/controller/README.md index 7fc50886135..5f89b5f8964 100644 --- a/components/controller/README.md +++ b/components/controller/README.md @@ -1 +1,127 @@ -# CONTROLLER +# 🎛️ @coopenomics/controller + +Основной бэкенд-сервис платформы «Цифровой Кооператив». GraphQL API на NestJS с чистой архитектурой — обрабатывает все запросы от рабочего стола, управляет кооперативными процессами, генерирует документы и взаимодействует с блокчейном EOSIO. + +## Основные возможности + +- GraphQL API для всех операций платформы +- Чистая архитектура: domain → infrastructure → modules +- Управление пайщиками, кошельками и финансовыми операциями +- Электронный документооборот с ЭП через блокчейн +- Система расширений (extensions) для модульного подключения функциональности +- Платёжный шлюз с поддержкой нескольких провайдеров +- JWT-аутентификация и авторизация +- Миграции данных через TypeORM +- Интеграция с Novu для уведомлений и LiveKit для видеоконференций + +## Установка + +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: + +```bash +pnpm install +``` + +Или только для этого компонента: + +```bash +pnpm install --filter @coopenomics/controller +``` + +## Скрипты + +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `dev` | `pnpm run dev` | Запуск в режиме разработки (nodemon + ts-node) | +| `start` | `pnpm run start` | Запуск в production-режиме | +| `lint` | `pnpm run lint` | Проверка кода (ESLint) | +| `lint:fix` | `pnpm run lint:fix` | Автоисправление lint-ошибок | +| `typecheck` | `pnpm run typecheck` | Проверка типов TypeScript | +| `migration:generate` | `pnpm run migration:generate` | Генерация новой миграции | +| `migration:run` | `pnpm run migration:run` | Применение всех миграций | +| `migration:status` | `pnpm run migration:status` | Текущий статус миграций | +| `migration:rollback` | `pnpm run migration:rollback` | Откат миграций | +| `migration:list` | `pnpm run migration:list` | Список всех миграций | +| `docs` | `pnpm run docs` | Генерация документации API (SpectaQL) | + +## Конфигурация + +Скопируйте `.env-example` в `.env` и настройте переменные окружения: + +- Строки подключения к MongoDB, реляционной БД, Redis +- Endpoint блокчейн-ноды и `CHAIN_ID` +- `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` — ключи для push-уведомлений +- Настройки JWT-аутентификации +- Конфигурация платёжных провайдеров +- Настройки Sentry для мониторинга ошибок + +Подробное описание переменных — в файле `.env-example`. + +## Тестирование + +Интеграционные тесты выполняются через компонент `@coopenomics/boot`, который разворачивает полную инфраструктуру: + +```bash +pnpm --filter @coopenomics/boot run test +``` + +## Архитектура + +Проект следует принципам **чистой архитектуры** с направлением зависимостей внутрь (к домену): + +``` +src/ +├── domain/ # Доменный слой (бизнес-логика) +│ ├── account/ # Аккаунты пользователей +│ ├── agreement/ # Соглашения +│ ├── auth/ # Аутентификация +│ ├── blockchain/ # Интерфейсы блокчейна +│ ├── branch/ # Кооперативные участки +│ ├── capital/ # Паевые взносы +│ ├── cooplace/ # Маркетплейс +│ ├── document/ # Документооборот +│ ├── extension/ # Расширения +│ ├── gateway/ # Платёжный шлюз +│ ├── ledger/ # Бухгалтерский учёт +│ ├── meet/ # Собрания +│ ├── participant/ # Участники кооператива +│ ├── registration/ # Регистрация +│ ├── wallet/ # Кошельки +│ └── common/ # Общие порты и репозитории +├── infrastructure/ # Инфраструктурный слой (адаптеры) +│ ├── blockchain/ # Адаптер блокчейна EOSIO +│ ├── database/ # Адаптеры БД (Mongoose, TypeORM) +│ └── external/ # Внешние сервисы +├── modules/ # Прикладной слой (NestJS-модули) +│ ├── auth/ # Модуль аутентификации +│ ├── cooperative/ # Модуль кооператива +│ └── ... # Остальные модули +└── extensions/ # Система подключаемых расширений + ├── extensions.registry.ts + └── base.extension.module.ts +migrations/ # Миграции данных (TypeORM) +``` + +### Поток данных + +1. **Резолвер** принимает входные данные и передаёт в сервис +2. **Сервис** вызывает интерактор домена, передавая DTO (реализующие доменный интерфейс) +3. **Интерактор** выполняет бизнес-логику и взаимодействует с портами +4. **Адаптеры** (инфраструктура) преобразуют доменные объекты в формат внешних систем +5. Результаты возвращаются обратно по цепочке + +## Ключевые зависимости + +- **@nestjs/\*** — фреймворк бэкенда +- **graphql / @nestjs/graphql** — GraphQL API +- **mongoose** — MongoDB ODM +- **typeorm** — реляционный ORM с миграциями +- **eosjs** — взаимодействие с блокчейном EOSIO +- **ioredis** — Redis-клиент +- **@novu/api** — сервис уведомлений +- **livekit-server-sdk** — видеоконференции +- **winston** — логирование + +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/desktop/README.md b/components/desktop/README.md index 25bf0097b63..eb342770b22 100644 --- a/components/desktop/README.md +++ b/components/desktop/README.md @@ -1,38 +1,106 @@ -# Terminal App +# 🖥️ @coopenomics/desktop + +Веб-приложение рабочего стола кооператива на Vue 3 и Quasar Framework с поддержкой SSR и SPA. Реализует интерфейс для всех участников кооператива: председателя, членов совета и пайщиков — включая регистрацию, голосование, документооборот, финансовые операции и управление кооперативом. + +## Основные возможности + +- Архитектура Feature Sliced Design (FSD) +- SSR и SPA режимы (Quasar Framework) +- Pug-шаблоны с Composition API +- Система расширений (extensions) для модульного подключения функциональности +- Интернационализация (Vue I18n) +- Pinia для управления состоянием с персистентностью +- Интеграция с блокчейном EOSIO через Wharfkit +- Push-уведомления через Novu +- Мониторинг через Sentry и OpenReplay + +## Установка + +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: -## Install the dependencies ```bash -yarn -# or -npm install +pnpm install ``` -### Start the app in development mode (hot-code reloading, error reporting, etc.) +Или только для этого компонента: + ```bash -quasar dev +pnpm install --filter @coopenomics/desktop ``` -### Lint the files +## Скрипты + +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `dev` | `pnpm run dev` | Запуск в режиме SSR-разработки | +| `devnet` | `pnpm run devnet` | Запуск в режиме SPA-разработки | +| `build` | `pnpm run build` | Сборка SSR для production | +| `build:spa` | `pnpm run build:spa` | Сборка SPA | +| `build:lib` | `pnpm run build:lib` | Сборка как библиотеки (Vite) | +| `lint` | `pnpm run lint` | Проверка кода (ESLint) | +| `typecheck` | `pnpm run typecheck` | Проверка типов TypeScript | +| `format` | `pnpm run format` | Форматирование кода (Prettier) | +| `start` | `pnpm run start` | Запуск собранного SSR-приложения | + +Из корня монорепозитория: + ```bash -yarn lint -# or -npm run lint +pnpm run dev:desktop ``` +## Конфигурация -### Format the files -```bash -yarn format -# or -npm run format +Скопируйте `.env-example` в `.env`. Основные переменные: + +- URL GraphQL API контроллера +- Endpoint блокчейн-ноды и `CHAIN_ID` +- Настройки Sentry и аналитики +- Настройки OpenReplay и Chatwoot + +Для подключения к тестовой сети используйте `.env-testnet`. + +Подробное описание переменных — в файле `.env-example`. + +## Архитектура + +Проект организован по методологии **Feature Sliced Design (FSD)**: + +``` +src/ +├── app/ # Инициализация приложения, провайдеры +├── pages/ # Маршрутизируемые страницы +├── widgets/ # Составные виджеты +├── features/ # Фичи (бизнес-логика UI) +├── entities/ # Доменные сущности +├── shared/ # Общие утилиты, UI-kit, конфигурация +├── processes/ # Бизнес-процессы +├── stores/ # Хранилища Pinia +├── desktops/ # Рабочие столы по ролям +├── i18n/ # Переводы +└── boot/ # Quasar boot-файлы +extensions/ # Подключаемые расширения +├── capital/ # Паевые взносы +├── chairman/ # Кабинет председателя +├── chatcoop/ # Чат кооператива +├── market/ # Маркетплейс +├── market-admin/ # Администрирование маркетплейса +├── participant/ # Кабинет пайщика +├── powerup/ # Управление ресурсами +└── soviet/ # Совет кооператива ``` +### Стек технологий +- **Vue 3** — Composition API +- **Quasar Framework** — UI-компоненты и SSR/SPA инфраструктура +- **Pug** — шаблоны компонентов +- **Pinia** — управление состоянием +- **Vue Router** — маршрутизация +- **Vue I18n** — интернационализация +- **Wharfkit** — интеграция с блокчейном EOSIO -### Build the app for production -```bash -quasar build -``` +> **Примечание:** в режиме разработки рекомендуется SPA (`quasar dev`), так как SSR-режим не поддерживает рендеринг расширений из-за ограничений сериализации Pinia. -### Customize the configuration -See [Configuring quasar.config.js](https://v2.quasar.dev/quasar-cli-vite/quasar-config-js). +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/factory/README.md b/components/factory/README.md index bfbcb9dad0e..a0bebd38fa5 100644 --- a/components/factory/README.md +++ b/components/factory/README.md @@ -1,77 +1,127 @@ -# Кооперативный генератор документов +# 📄 @coopenomics/factory -[![npm version][npm-version-src]][npm-version-href] -[![npm downloads][npm-downloads-src]][npm-downloads-href] -[![bundle][bundle-src]][bundle-href] -[![JSDocs][jsdocs-src]][jsdocs-href] -[![License][license-src]][license-href] +Фабрика документов кооператива — библиотека для генерации юридически значимых документов (PDF). Объединяет шаблоны из блокчейна, приватные данные из хранилища и рендерит HTML через Handlebars/Nunjucks с последующей генерацией PDF через WeasyPrint. -## Обзор -Данная библиотека предназначена для кооперативов, которые используют блокчейн EOSIO для хранения шаблонов документов и реализуют систему цифровой подписи на основе EOSIO. Шаблоны документов и соответствующие переводы хранятся в блокчейне, в то время как приватные данные для заполнения шаблонов находятся в закрытом хранилище кооператива. Библиотека позволяет генерировать документы, автоматически заполняя их данными из хранилища и подписывая при помощи приватного ключа. +## Основные возможности -## Функциональность -Библиотека предоставляет следующие основные возможности: +- Более 60 шаблонов юридических документов (заявления, протоколы, решения, договоры, акты) +- Рендеринг HTML из шаблонов Handlebars и Nunjucks +- Генерация PDF через WeasyPrint +- Валидация данных по JSON Schema +- Электронная подпись документов через EOSIO-ключи +- Хранение документов и метаданных в MongoDB +- Сборка как ES-модуль и CommonJS (unbuild) -- Генерация метаданных для документов на основе предопределенных шаблонов. -- Конструирование данных для документов, используя JSON Schema, загружаемую из блокчейна. -- Получение шаблонов документов и переводов из блокчейна. -- Рендеринг документов для создания цифровой версии в формате doc и gdoc. -- Подпись сгенерированных документов с использованием приватных ключей EOSIO. +## Установка -## Процесс генерации документов -Получение шаблона и схемы из блокчейна: Шаблоны и схемы загружаются из блокчейна. Шаблоны включают в себя как структуру самого документа, так и переводы элементов документа на разные языки. +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: -Конструирование данных: Фабрика шаблонов использует JSON Schema для определения структуры данных, необходимых для каждого шаблона. Приватные данные загружаются из хранилища кооператива и используются для заполнения шаблонов. - -Рендеринг шаблона: Используя загруженные данные и шаблон, библиотека рендерит окончательный документ. Этот этап включает подстановку реальных данных пользователя и кооператива в шаблон. - -Подпись документа: Сгенерированный документ подписывается с использованием приватного ключа EOSIO. - -Верификация документа: При необходимости, сгенерированные и подписанные документы могут быть верифицированы для подтверждения их подлинности. - -## Подготовка к использованию -Для начала работы с библиотекой необходимо ознакомиться с требованиями окружения: -- Ваше приложение должно взаимодействовать с блокчейном EOSIO для получения шаблонов и схем. -- У кооператива должно быть настроено приватное хранилище для доступа к личным данным. -- Необходим модуль для работы с JSON Schema, например, json-schema для Node.js. -- Вам потребуется EOSJS для подписи документов. - -## Пример использования -Пример реализации фабрики для генерации документа типа joincoop из файла documents/joincoop.ts: - -``` javascript -const joinCoopFactory = new JoinCoopTemplateFactory() -joinCoopFactory.getComplexTemplate() - .then((template) => { - const options = { - username: 'user1', - lang: 'en', - action: 'joincoop' - } - - const generator = new GeneratorJSImpl() - return generator.generate(options) - }) - .then((document) => { - // Работа с сгенерированным и подписанным документом - }) - .catch((error) => { - console.log(error) - // Обработка ошибок - }) +```bash +pnpm install ``` -## Расширение и модификация -Библиотека построена с учетом возможности расширения и модификации. Для добавления новых типов документов реализуйте свои фабрики, соответствующие интерфейсу IDocumentTemplateFactory, и регистрируйте их в главном классе библиотеки. +Или только для этого компонента: -## Поддержка и вклад -Если у вас есть вопросы, предложения или вы хотите внести вклад в проект, пожалуйста, свяжитесь с технической поддержкой или откройте issue в системе управления проектами. +```bash +pnpm install --filter @coopenomics/factory +``` -## Таблица документов -Здесь соберём таблицу имен и шаблонов типизированных документов. +### Системные зависимости + +Для генерации PDF необходим [WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation). + +## Скрипты + +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `build` | `pnpm run build` | Сборка библиотеки (unbuild) | +| `dev` | `pnpm run dev` | Режим разработки с автопересборкой (nodemon) | +| `test` | `pnpm run test` | Запуск тестов (Vitest) | +| `lint` | `pnpm run lint` | Проверка кода (ESLint) | +| `typecheck` | `pnpm run typecheck` | Проверка типов TypeScript | +| `setup-indexes` | `pnpm run setup-indexes` | Настройка индексов MongoDB | + +Из корня монорепозитория: + +```bash +pnpm run build:lib # Сборка factory + cooptypes +pnpm run dev:lib # Режим разработки factory + cooptypes +pnpm run test:component # Компонентные тесты factory +``` + +## Конфигурация + +Для тестирования и локальной работы необходимо подключение к MongoDB. Переменные окружения: + +- `MONGO_URI` — строка подключения к MongoDB +- `SOURCE` — источник данных (`local` для тестов) + +Подробное описание переменных — в файле `.env-example`. + +## Тестирование + +```bash +SOURCE=local NODE_ENV=test pnpm --filter @coopenomics/factory run test +``` + +Тестовый набор покрывает генерацию документов различных типов. Тесты требуют запущенный MongoDB и используют таймаут 240 секунд. + +Файлы тестов: + +| Файл | Описание | +|------|----------| +| `test/index.test.ts` | Основные тесты генерации документов | +| `test/wallet.test.ts` | Тесты документов кошелька | +| `test/meet.test.ts` | Тесты документов собраний | +| `test/blagorost.test.ts` | Тесты документов программы «Благорост» | +| `test/market.test.ts` | Тесты документов маркетплейса | +| `test/search.test.ts` | Тесты поиска документов | +| `test/udata.test.ts` | Тесты пользовательских данных | +| `test/documents-1000-plus.test.ts` | Тесты документов с registry_id > 1000 | + +## Архитектура + +``` +src/ +├── index.ts # Точка входа библиотеки +├── config.ts # Конфигурация подключений +├── Actions/ # Генераторы документов (по registry_id) +│ ├── 1.WalletAgreement.ts +│ ├── 100.ParticipantApplication.ts +│ ├── 300.AnnualGeneralMeetingAgenda.ts +│ ├── 600.FreeDecision.ts +│ ├── 1001.GenerationContract.ts +│ └── ... # Более 60 шаблонов +├── Factory/ # Ядро фабрики документов +├── Models/ # Модели данных MongoDB +│ ├── Cooperative.ts +│ ├── Individual.ts +│ ├── Organization.ts +│ ├── Document.ts +│ └── ... +└── templates/ # HTML-шаблоны (Nunjucks/Handlebars) +test/ # Тесты (Vitest) +``` + +### Процесс генерации документа + +1. Загрузка шаблона и JSON Schema из блокчейна +2. Получение приватных данных из хранилища (MongoDB) +3. Валидация данных по JSON Schema (Ajv) +4. Конструирование контекста для шаблона +5. Рендеринг HTML из Nunjucks/Handlebars-шаблона +6. Подпись хеша документа EOSIO-ключом +7. Генерация PDF через WeasyPrint + +## Ключевые зависимости + +- **nunjucks / handlebars** — шаблонизаторы +- **ajv** — валидация JSON Schema +- **mongodb** — хранилище данных +- **eosjs-ecc** — криптографические операции EOSIO +- **pdf-lib** — работа с PDF +- **unbuild** — сборка библиотеки ## Лицензия -[MIT](./LICENSE) License © 2024-PRESENT [Alex Ant](https://github.com/dacom-dark-sun) - -Версия документации: 1.0.0 +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/parser/README.md b/components/parser/README.md index 84a6fd6af22..9638d3b5d11 100644 --- a/components/parser/README.md +++ b/components/parser/README.md @@ -1,146 +1,126 @@ -# COOPARSER. +# 🔍 @coopenomics/parser -[![npm version][npm-version-src]][npm-version-href] -[![npm downloads][npm-downloads-src]][npm-downloads-href] -[![bundle][bundle-src]][bundle-href] -[![JSDocs][jsdocs-src]][jsdocs-href] -[![License][license-src]][license-href] +Индексатор блокчейна EOSIO. Подключается к State History Plugin (SHiP) через WebSocket, в реальном времени парсит действия и дельты таблиц из блоков, сохраняет данные в MongoDB и публикует события в Redis Streams для дальнейшей обработки другими сервисами. -Пакет производит распаковку блоков, сохраняя действия и дельты таблиц и выдавая их по API. Состоит из двух модулей: парсера и API. Парсер считывает данные из блокчейна и помещает их в базу. API получает данные по запросу и возвращает их с пагинацией. +## Основные возможности + +- Подключение к EOSIO State History Plugin по WebSocket +- Парсинг действий (actions) и дельт таблиц (table deltas) из блоков +- Сохранение индексированных данных в MongoDB +- Публикация событий в Redis Streams +- REST API для запросов с пагинацией и фильтрацией +- Обработка форков блокчейна +- Расширение кастомными обработчиками действий и дельт +- Конфигурируемые подписки на конкретные таблицы и контракты ## Установка -``` + +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: + +```bash pnpm install ``` -### Конфигурационный файл .env -``` -NODE_ENV=development -- Определяет среду выполнения приложения. +Или только для этого компонента: -API=http://127.0.0.1:8888 -- Определяет URL-адрес API, к которому будет осуществляться доступ. - -SHIP=ws://127.0.0.1:8080 -- Определяет URL-адрес WebSocket-соединения, используемого для связи с другими узлами. - -MONGO_EXPLORER_URI=mongodb://127.0.0.1:27017/cooperative -- Определяет URI-адрес MongoDB, используемый для подключения к базе данных. - -START_BLOCK=1 -- Определяет номер блока, с которого начинается парсинг блокчейна. - -FINISH_BLOCK=0xFFFFFFFF -- Определяет номер блока, на котором заканчивается парсинг блокчейна. В данном случае, установлено значение "0xFFFFFFFF", что означает, что парсинг будет продолжаться до последнего доступного блока. - -PORT=4000 -- Определяет порт, на котором будет запущен сервер приложения. - -ACTIVATE_PARSER=0 -- Определяет флаг активации парсера. Если значение равно "1", парсер будет активирован. +```bash +pnpm install --filter @coopenomics/parser ``` -### Конфигурация парсера -В конфиге src/config.ts находится массив таблиц и действий, на которые парсер осуществит подписку. +## Скрипты -``` -export const subsribedTables = [ - { code: 'registrator', table: 'users', 'scope': 'registrator' }, - { code: 'soviet', table: 'participants' }, -] -``` -- подписка будет осуществлена на изменения таблиц указанных контрактов. Параметр scope - не обязательный. Без его указания любые scope будут попадать в базу данных. +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `dev` | `pnpm run dev` | Запуск в режиме разработки (nodemon) | +| `dev:test` | `pnpm run dev:test` | Режим разработки с NODE_ENV=test | +| `start` | `pnpm run start` | Запуск production (esno) | +| `build` | `pnpm run build` | Сборка библиотеки (unbuild) | +| `test` | `pnpm run test` | Запуск тестов (Vitest) | +| `lint` | `pnpm run lint` | Проверка кода (ESLint) | +| `typecheck` | `pnpm run typecheck` | Проверка типов TypeScript | +| `doc` | `pnpm run doc` | Генерация документации (TypeDoc) | -``` -export const subsribedActions = [ - { code: 'soviet', action: 'votefor' }, - { code: 'soviet', action: 'voteagainst' }, -] -``` -- подписка будет осуществлена на действия указанных контрактов. +Из корня монорепозитория: -Парсер может быть расширен любыми кастомными действиями, которые будут выполняться перед добавлением записи в базу данных. Для этого, для таблиц и действий соответственно, в папках src/ActionParser/Actions и src/DeltaParser/Deltas необходимо создать файлы с методами обработки и добавить их к src/ActionParser/Actions или src/DeltaParser/DeltaFactory. - -### Запуск -``` -pnpm start +```bash +pnpm run dev:backend # Запуск parser + controller в режиме разработки ``` -## API +## Конфигурация -### Получение таблиц -Конечная точка предоставляет информацию о изменении (дельтах) таблиц между блоками. +Скопируйте `.env-example` в `.env` и настройте переменные окружения: +- `API` — URL блокчейн-ноды +- `SHIP` — WebSocket URL State History Plugin +- `MONGO_EXPLORER_URI` — строка подключения к MongoDB +- `REDIS_HOST` / `REDIS_PORT` — подключение к Redis +- `START_BLOCK` — номер блока для начала индексации +- `PORT` — порт REST API +- `ACTIVATE_PARSER` — флаг активации парсера (`0` / `1`) + +Подробное описание переменных — в файле `.env-example`. + +## Тестирование + +```bash +pnpm --filter @coopenomics/parser run test ``` -let params = { - page: 1, - limit: 10, - filter: { } - любые параметры фильтрации таблицы, включая данные в полях -}; +## REST API -axios.get('http://localhost:4000/get-tables', { params }) - .then(response => { - console.log(response.data); - // { - // results: array, - // page: number, - // limit: number - // }; - }) -``` +| Endpoint | Описание | +|----------|----------| +| `GET /get-tables` | Дельты таблиц (с пагинацией и фильтрацией) | +| `GET /get-actions` | Действия блокчейна (с пагинацией и фильтрацией) | +| `GET /get-current-block` | Текущий номер обработанного блока | -### Получение действий -Конечная точка предоставляет информацию о действиях, произошедших между блоками. +## Архитектура ``` -let params = { - page: 1, - limit: 10, - filter: { } // любые параметры фильтрации действий, включая данные в полях -}; - -axios.get('http://localhost:4000/get-actions', { params }) - .then(response => { - console.log(response.data); - // { - // results: array, - // page: number, - // limit: number - // }; - }) - .catch(error => { - console.error(error); - }); +src/ +├── index.ts # Точка входа +├── config.ts # Подписки на таблицы и действия +├── ActionParser/ # Парсер действий блокчейна +│ ├── Parser/ # Ядро парсера действий +│ ├── Actions/ # Кастомные обработчики действий +│ └── Factory/ # Фабрика создания обработчиков +├── DeltaParser/ # Парсер дельт таблиц +│ ├── Parser/ # Ядро парсера дельт +│ ├── Deltas/ # Кастомные обработчики дельт +│ └── Factory/ # Фабрика создания обработчиков +├── BlockParser/ # Парсер блоков +│ └── Parser/ # Обработка блоков целиком +├── ForkParser/ # Обработка форков блокчейна +│ ├── Parser/ # Ядро обработки форков +│ ├── Forks/ # Кастомные обработчики форков +│ └── Factory/ # Фабрика создания обработчиков +├── Database/ # Подключение к MongoDB +├── Initializer/ # Инициализация и настройка +├── Reader/ # Чтение данных из SHiP (WebSocket) +├── RedisNotifier/ # Публикация в Redis Streams +├── Types/ # Типы и интерфейсы +└── Utils/ # Вспомогательные утилиты ``` -### Получение текущего блока -Конечная точка предоставляет информацию о текущем блоке. Эта информация используется при формировании кооперативных документов. +### Конвейер обработки -``` -axios.get('http://localhost:4000/get-current-block') - .then(response => { - console.log(response.data); - // number - }) - .catch(error => { - console.error(error); - }); -``` +1. **Reader** подключается к SHiP по WebSocket и получает блоки +2. **BlockParser** извлекает actions и deltas из каждого блока +3. **ActionParser** обрабатывает действия через зарегистрированные обработчики +4. **DeltaParser** обрабатывает дельты таблиц через соответствующие обработчики +5. **ForkParser** следит за форками и корректирует данные +6. Результаты сохраняются в **MongoDB** и публикуются в **Redis Streams** + +## Ключевые зависимости + +- **@blockmatic/eosio-ship-reader** — библиотека чтения SHiP +- **eosjs** — взаимодействие с блокчейном EOSIO +- **mongodb** — хранилище индексированных данных +- **ioredis** — публикация событий в Redis Streams +- **express** — REST API +- **ws** — WebSocket-клиент +- **unbuild** — сборка библиотеки ## Лицензия -[MIT](./LICENSE) License © 2024-PRESENT [CBS VOSKHOD](https://github.com/copenomics) - - - -[npm-version-src]: https://img.shields.io/npm/v/cooparser?style=flat&colorA=080f12&colorB=1fa669 -[npm-version-href]: https://npmjs.com/package/cooparser -[npm-downloads-src]: https://img.shields.io/npm/dm/cooparser?style=flat&colorA=080f12&colorB=1fa669 -[npm-downloads-href]: https://npmjs.com/package/cooparser -[bundle-src]: https://img.shields.io/bundlephobia/minzip/cooparser?style=flat&colorA=080f12&colorB=1fa669&label=minzip -[bundle-href]: https://bundlephobia.com/result?p=cooparser -[license-src]: https://img.shields.io/github/license/copenomics/cooparser.svg?style=flat&colorA=080f12&colorB=1fa669 -[license-href]: https://github.com/copenomics/cooparser/blob/main/LICENSE -[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669 -[jsdocs-href]: https://www.jsdocs.io/package/cooparser +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/setup/README.md b/components/setup/README.md new file mode 100644 index 00000000000..59eccdfa922 --- /dev/null +++ b/components/setup/README.md @@ -0,0 +1,71 @@ +# ⚙️ @coopenomics/setup + +Интерактивный мастер первоначальной настройки платформы «Цифровой Кооператив». Создаёт файлы конфигурации `.env` для всех компонентов монорепозитория через удобный CLI-интерфейс с возможностью выбора режима разработки. + +## Основные возможности + +- Интерактивный CLI с пошаговым мастером настройки +- Два режима установки: «Для разработки» и «Для использования» +- Два режима разработки: только фронтенд на тестнете или полная локальная среда +- Автоматическое копирование `.env` файлов для всех компонентов +- Автоматическая сборка зависимых библиотек (cooptypes, factory, SDK) +- Запуск инфраструктуры через Docker Compose (для локального режима) + +## Установка + +Компонент является частью монорепозитория. Установка зависимостей из корня проекта: + +```bash +pnpm install +``` + +## Скрипты + +| Скрипт | Команда | Описание | +|--------|---------|----------| +| `setup` | `pnpm run setup` | Запуск интерактивного мастера настройки | + +Из корня монорепозитория: + +```bash +pnpm run setup +``` + +## Режимы работы + +### Только фронтенд на тестнете + +Минимальная настройка для разработки фронтенда с подключением к удалённой тестовой сети: + +1. Копирует `.env-testnet` → `.env` для desktop +2. Собирает библиотеки: cooptypes → factory → SDK +3. Готово к запуску: `pnpm run dev:desktop` + +### Локальный фронтенд и бэкенд + +Полная локальная среда разработки со всей инфраструктурой: + +1. Копирует `.env-example` → `.env` для всех компонентов (desktop, controller, boot, factory, parser) +2. Запускает Docker Compose для инфраструктуры (см. `docker-compose.yaml`) +3. Собирает библиотеки: cooptypes → factory → SDK → смарт-контракты +4. Готово к запуску: + - `pnpm boot` — инициализация блокчейна + - `pnpm run dev:backend` — бэкенд + - `pnpm run dev:desktop` — фронтенд + +## Архитектура + +``` +├── setup.ts # Точка входа — интерактивное CLI-меню +└── package.json # Зависимости (inquirer, ora, esno) +``` + +## Ключевые зависимости + +- **inquirer** — интерактивные CLI-меню и вопросы +- **ora** — спиннеры для отображения прогресса +- **esno** — запуск TypeScript без предварительной компиляции + +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru)