From 4418e09211196d69a83df4b9e64c5506e77e5aca Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 25 Feb 2026 18:30:06 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=BE=D0=B7=D0=B4=D0=B0=D0=BD?= =?UTF-8?q?=D0=B8=D0=B5=20=D0=BF=D1=80=D0=BE=D1=84=D0=B5=D1=81=D1=81=D0=B8?= =?UTF-8?q?=D0=BE=D0=BD=D0=B0=D0=BB=D1=8C=D0=BD=D1=8B=D1=85=20README.md=20?= =?UTF-8?q?=D0=B4=D0=BB=D1=8F=206=20=D0=BA=D0=BE=D0=BC=D0=BF=D0=BE=D0=BD?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=BE=D0=B2=20=D0=BC=D0=BE=D0=BD=D0=BE=D1=80?= =?UTF-8?q?=D0=B5=D0=BF=D0=BE=D0=B7=D0=B8=D1=82=D0=BE=D1=80=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - cooptypes: типы и интерфейсы экосистемы с подробной архитектурой - sdk: TypeScript SDK с быстрым стартом и описанием классов - notifications: библиотека уведомлений с таблицей 21 workflow - contracts: смарт-контракты EOSIO с описанием чистой архитектуры - migrator: утилита миграций с жизненным циклом - docs: документация MkDocs Material с инструкцией по синхронизации Co-authored-by: Alex Ant --- components/contracts/README.md | 209 +++++++++------------ components/cooptypes/README.md | 180 ++++++++---------- components/docs/README.md | 123 +++++++++--- components/migrator/README.md | 242 +++++++----------------- components/notifications/README.md | 289 ++++++++++------------------- components/sdk/README.md | 193 +++++++++---------- 6 files changed, 501 insertions(+), 735 deletions(-) diff --git a/components/contracts/README.md b/components/contracts/README.md index 7ecf21a0fc9..d46d5ed511d 100644 --- a/components/contracts/README.md +++ b/components/contracts/README.md @@ -1,156 +1,121 @@ -# Введение +# ⛓️ @coopenomics/contracts -Репозиторий содержит в себе смарт-контракты операционной системы coopOS, образующих протокол COOPENOMICS. +> Смарт-контракты EOSIO для кооперативного управления на блокчейне -## Окружение -В качестве окружения используется контейнер операционной системы coopOS. Для запуска выполните команду из корня репозитория: +## Описание -``` -pnpm run enter +Набор смарт-контрактов на C++, образующих протокол COOPENOMICS — операционную систему кооператива на блокчейне EOSIO. Контракты реализуют полный цикл управления: регистрация участников, голосование совета, паевые взносы, документооборот, финансовый учёт, маркетплейс и проведение собраний. + +Архитектура контрактов следует принципам **чистой архитектуры**: `app/` (оркестрация действий), `domain/entity/` (сущности и таблицы), `domain/core/` (межсущностная бизнес-логика). + +## Контракты + +| Контракт | Назначение | +|----------|------------| +| `soviet` | Совет кооператива — голосование, решения, повестки | +| `registrator` | Регистрация и управление аккаунтами пользователей и организаций | +| `capital` | Управление интеллектуальной капитализацией и паевыми взносами | +| `wallet` | Финансовые операции — взносы и возвраты | +| `draft` | Шаблоны документов и их переводы в блокчейне | +| `gateway` | Платёжный шлюз — депозиты и выводы | +| `fund` | Управление фондами кооператива | +| `ledger` | Бухгалтерская книга кооператива | +| `meet` | Общие собрания пайщиков | +| `marketplace` | Маркетплейс товаров и услуг | +| `branch` | Создание и управление кооперативными участками | +| `contributor` | Управление вкладчиками | +| `loan` | Управление займами | + +## Установка + +```bash +pnpm install --filter @coopenomics/contracts ``` -После выполнения команды и входа в контейнер, выполняйте команды компиляции внутри него. +## Скрипты + +| Скрипт | Описание | +|--------|----------| +| `pnpm run build:all` | Компиляция всех контрактов | +| `pnpm run build:all:test` | Компиляция всех контрактов в тестовом режиме | +| `pnpm run build:one -- <имя>` | Компиляция одного контракта по имени | +| `pnpm run enter` | Вход в Docker-контейнер для ручной сборки | + +> Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter @coopenomics/contracts run <скрипт>` ## Компиляция -Для компиляции выполните команду: -``` -mkdir build -cd build +Компиляция выполняется внутри Docker-контейнера с необходимым EOSIO CDT: + +```bash +pnpm run enter # Вход в контейнер сборки +mkdir build && cd build cmake -DBUILD_TARGET= .. make - ``` -Компиляция всех контрактов произойдёт в папку build/contracts. Для указания конкретного контракта, который необходимо скомпилировать, используйте названия папок из директории cpp в качестве параметра -DBUILD_TARGET. Например, для контракта fund: +Для компиляции с тестами: + +```bash +cmake -DBUILD_TARGET= -DBUILD_TESTS=ON .. +make ``` + +Для компиляции одного контракта: + +```bash cmake -DBUILD_TARGET=fund .. make ``` -Для компиляции всех контрактов передавайте пустой параметр -DBUILD_TARGET= . Без явной передачи параметра используйте кэшированный, ранее переданный параметр, что может привести к путанице. Поэтому, всегда явно передавайте параметр цели компиляции. - - -## Загрузка -Перед автоматической загрузкой контрактов в локальную версию блокчейна - скомпилируйте их как показано выше. После чего, выйдите из контейнера и выполните команду установки загрузчика в вашем окружении: +## Архитектура ``` -pnpm install +cpp/ +├── soviet/ # Совет кооператива +│ ├── app/ # Оркестрация действий +│ └── domain/ # Бизнес-логика +│ ├── entity/ # Сущности, таблицы, индексы +│ └── core/ # Межсущностная логика +├── capital/ # Паевые взносы +├── registrator/ # Регистрация аккаунтов +├── wallet/ # Финансовые операции +├── draft/ # Шаблоны документов +├── gateway/ # Платёжный шлюз +├── fund/ # Фонды кооператива +├── ledger/ # Бухгалтерский учёт +├── meet/ # Собрания пайщиков +├── marketplace/ # Маркетплейс +├── branch/ # Кооперативные участки +├── contributor/ # Вкладчики +└── loan/ # Займы +build/ +└── contracts/ # Скомпилированные .wasm и .abi файлы ``` -Скопируйте файл .env-example в .env: +### Принципы чистой архитектуры -``` -cp .env-example .env -``` +- **`app/`** — уровень приложения; действия, вызываемые контрактом, которые оркестрируют бизнес-логику +- **`domain/entity/`** — сущности с таблицами, индексами и простыми бизнес-функциями; запрещено вызывать другие сущности напрямую +- **`domain/core/`** — корневая бизнес-логика, объединяющая несколько сущностей -И запустите загрузку: +## Тестирование -``` -pnpm run cli boot -``` - -Команда загрузки запустит блокчейн и произведет установку всех контрактов для начала работы. Параметры конфигурации блокчейна можно найти в файле scripts/restart.sh - -Блокчейн будет запущен в контейнере и остановит свою работу при завершении работы программы. Данные сохраняются в ./blockchain-data корневой директории репозитория. Данные кошелька пишутся в ./wallet-data. - -После остановки контейнера вы можете перезапустить его командной: - -``` -pnpm run cli start - -``` - -Для перезагрузки блокчейна вновь вызовите: - -``` -pnpm run boot -``` - -Последняя команда очистит всю историю цепочки блоков и перезагрузит локальный блокчейн до начального состояния. - -## Кошелёк -Для доступа командному кошельку cleos используйте команду - -``` -pnpm run cli cleos - -``` - -Для отображения полного списка команд воспользуйтесь: -``` -pnpm run cli cleos --help -``` - -Командный кошелёк позволяет совершать любые транзакции и просматривать любые таблицы в блокчейне. Для более удобной постоянной работы занесите алиас в файл ~/.bashrc для быстрого вызова: - -``` -alias=cd && pnpm run cli cleos -``` - -Подтяните изменения профиля: -``` -source ~/.bashrc -``` - -Теперь утилита cleos доступна простой командной: - -``` -cleos get info -``` - - -## Тесты - -### Полные тесты -Тесты по-умолчанию НЕ компилируются вместе с контрактами. Для компиляции необходимо передать флаг конфигурации сборки -DBUILD_TESTS=ON: -``` -cmake -DBUILD_TARGET= -DBUILD_TESTS=ON +```bash +cd build +cmake -DBUILD_TARGET= -DBUILD_TESTS=ON .. make -``` -Все контракты пересоберутся вместе со всеми тестами. - -Для запуска тестов (из директории build): -``` ctest --test-dir contracts/tests --output-on-failure ``` -### Выборочные тесты -Для выборочного указания тестового файла используйте из директории build: +Выборочный тест одного контракта: -``` -cmake -DBUILD_TARGET=fund -DBUILD_TESTS=ON -DTEST_TARGET=fund.tester.cpp .. +```bash +cmake -DBUILD_TARGET=fund -DTEST_TARGET=fund.tester.cpp .. make -``` - -Команды пересоберет указанный контракт и его тест. Выборочная сборка и тесты значительно ускоряют отладку. - - -### Информативные тесты -Для большей детализации тестового процесса добавьте флаг -DVERBOSE=ON при конфигурации сборки: -``` -cmake -DBUILD_TARGET=fund -DTEST_TARGET=fund.tester.cpp -DVERBOSE=ON .. -make -``` - -Дополнительная вербозность показывает отладочную информацию из тестов, включая консоль контрактов, в которую информация выводится через методы print. - - -## Документация -Для генерации документации используйте команду Doxygen версии от 1.9.3: -``` -git submodule update --init --recursive -doxygen -``` - -Документация будет собрана в папке docs/html, откройте файл index.html в браузере: -``` -open docs/html/index.html +ctest --test-dir contracts/tests --output-on-failure ``` ## Лицензия -Продукт Потребительского Кооператива "ВОСХОД" распространяется по лицензии BY-NC-SA 4.0. -Разрешено делиться, копировать и распространять материал на любом носителе и форме, адаптировать, делать ремиксы, видоизменять и создавать новое, опираясь на этот материал. При использовании, Вы должны обеспечить указание авторства, предоставить ссылку, и обозначить изменения, если таковые были сделаны. Если вы перерабатываете, преобразовываете материал или берёте его за основу для производного произведения, вы должны распространять переделанные вами части материала на условиях той же лицензии , в соответствии с которой распространяется оригинал. Запрещено коммерческое использование материала. Использование в коммерческих целях – это использование, в первую очередь направленное на получение коммерческого преимущества или денежного вознаграждения. - -Юридический текст лицензии: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/cooptypes/README.md b/components/cooptypes/README.md index 14327f859bc..97f2d9c4ee5 100644 --- a/components/cooptypes/README.md +++ b/components/cooptypes/README.md @@ -1,129 +1,95 @@ -# COOPTYPES +# 🧩 cooptypes -[![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] +> Общие TypeScript типы и интерфейсы для всей экосистемы «Цифровой Кооператив» -Модуль cooptypes содержит информацию для работы со смарт-контрактами кооперативной -экономики. В этом модуле представлены реестры действий и таблиц каждого -смарт-контракта, а также имена аккаунтов для разных блокчейн-сетей. +## Описание -Каждое действие содержит интерфейс транзакции, информацию о требуемой авторизации и имя действия, которое нужно вызвать на уровне смарт-контракта. +Модуль `cooptypes` — центральная библиотека типов, обеспечивающая единый типизированный контракт между всеми компонентами экосистемы COOPENOMICS. Содержит описания действий, таблиц и интерфейсов каждого смарт-контракта блокчейна, модели данных кооператива, реестр шаблонов документов и пользовательские интерфейсы. -Каждая таблица содержит интерфейс для работы с данными и информацию о пространстве хранения информации в блокчейне. +Используется как зависимость в компонентах `controller`, `parser`, `desktop`, `sdk`, `factory` и `boot`. -## Как пользоваться -Перейти на страницу документации и ознакомиться с набором пространств имен контрактов, в каджом из которых есть действия и таблицы, а также, интерфейсы данных, имена контрактов, пространств хранения и требуемая авторизация. Всё это доступно из интерфейса IDE после импорта контракта. +## Возможности -### Получение таблиц +- **Типы контрактов** — полное описание действий (`Actions`) и таблиц (`Tables`) для каждого смарт-контракта: `SovietContract`, `RegistratorContract`, `DraftContract`, `TokenContract`, `CapitalContract`, `WalletContract`, `GatewayContract`, `FundContract`, `LedgerContract`, `MarketContract`, `MeetContract`, `BranchContract` и др. +- **Модели кооператива** — структуры данных для пользователей (`Cooperative.Users`) и реестра документов (`Cooperative.Registry`) +- **Интерфейсы** — типизированные интерфейсы для всех доменов: `Soviet`, `Capital`, `Registrator`, `Wallet`, `Gateway`, `Fund`, `Draft`, `Meet`, `Marketplace`, `Branch`, `Ledger`, `Loan`, `Token`, `System` +- **Реестр шаблонов** — шаблоны юридических документов с markdown-разметкой -``` -import EosApi from 'eosjs-api'; -import {SovietContract} from 'cooptypes' +## Установка -const options = { - httpEndpoint: 'http://127.0.0.1:8888', - }; - -const api = new EosApi(options); -const coopname = 'testcoop' - тестовое имя аккаунта кооператива - -const _scope = SovietContract.Tables.Boards.scope +```bash +pnpm install --filter cooptypes ``` -Получив _scope, необходимо проверить его и подставить переменную: +## Скрипты + +| Скрипт | Описание | +|--------|----------| +| `pnpm run build` | Сборка библиотеки (`unbuild`) | +| `pnpm run dev` | Режим разработки с автоматической пересборкой (`nodemon`) | +| `pnpm run test` | Запуск тестов (`vitest`) | +| `pnpm run lint` | Проверка кода (`ESLint`) | +| `pnpm run typecheck` | Проверка типов TypeScript (`tsc --noEmit`) | +| `pnpm run docs` | Генерация документации (`TypeDoc`) | + +> Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter cooptypes run <скрипт>` + +## Архитектура ``` -let scope - -if (_scope === '_coopname' ) - scope = coopname -if (_scope === '_username) - scope = username -... и так далее - -``` -scope - это области памяти хранения информации в смарт-контракте, которые представлены в виде универсальных параметров _username, _coopname или прочих, в соответствии с которыми необходимо подставить переменную. - -Например, для получения таблицы с членами совета кооператива, необходимо подставить область памяти _coopname, или, 'testcoop', как было определено выше для тестового кооператива. Также, вместо _coopname могут быть указаны имена других контрактов или пользователей. Область памяти определяется тем, как именно смарт-контракт хранит информацию. - -После подстановок, мы можем получить информацию из таблицы смарт-контракта блокчейна: -``` -api.getTableRows( - { - json: true, - code: SovietContract.contractName.production, //извлекаем имя контракта - scope, //подставляем ранее полученную область памяти - table: SovietContract.Tables.Boards.tableName, //извлекаем имя таблицы в контракте - limit: 10, // устанавливаем лимит - - // не обязательные параметры запроса - /* upper_bound, // - верхняя граница - lower_bound, // - нижняя граница - key_type, // - тип ключа - index_position, // нижняя граница - */ - }) +src/ +├── contracts/ # Типы смарт-контрактов блокчейна +│ ├── soviet/ # Совет кооператива +│ ├── registrator/ # Регистрация аккаунтов +│ ├── capital/ # Паевые взносы +│ ├── wallet/ # Финансовые операции +│ ├── gateway/ # Платёжный шлюз +│ ├── draft/ # Шаблоны документов +│ ├── fund/ # Фонды кооператива +│ ├── ledger/ # Бухгалтерский учёт +│ ├── marketplace/ # Маркетплейс +│ ├── meet/ # Собрания пайщиков +│ ├── branch/ # Кооперативные участки +│ ├── token/ # Системные токены +│ ├── system/ # Системный контракт +│ ├── msig/ # Мультиподписи +│ ├── wrap/ # Привилегированные действия +│ └── index.ts # Реэкспорт всех контрактов +├── cooperative/ # Модели данных кооператива +│ ├── users/ # Типы пользователей +│ ├── registry/ # Реестр шаблонов документов +│ └── index.ts +├── interfaces/ # Типизированные интерфейсы по доменам +│ ├── soviet.ts +│ ├── capital.ts +│ ├── registrator.ts +│ ├── wallet.ts +│ ├── gateway.ts +│ ├── fund.ts +│ ├── draft.ts +│ ├── meet.ts +│ ├── marketplace.ts +│ ├── branch.ts +│ ├── ledger.ts +│ ├── loan.ts +│ ├── token.ts +│ ├── system.ts +│ └── index.ts +└── index.ts # Главная точка входа ``` -Те же параметры scope, table, code могут быть использованы для получения информации из модуля [COOPARSER](https://github.com/coopenomics/cooparser). Последнее используется, когда необходимо получить исторические данные и нет необходимости проверять их актуальность по наличию таблиц в блокчейне. Однако, таблицы в блокчейне необходимо всегда проверять перед отправкой любой транзакции действия. Нельзя полагаться на данные из парсера при подготовке транзакции действия. +Каждый контракт экспортирует: `contractName` (имя аккаунта контракта), `Actions` (действия с интерфейсами и авторизацией), `Tables` (таблицы с интерфейсами и scope). -### Транзакция действий -Состояние любого смарт-контракта может изменяться только с помощью действий. Для того, чтобы совершить действия, необходимо сформировать и отправить транзакцию с помощью библиотеки eosjs или альтернатив. +## Конфигурация -``` -import { Api, JsonRpc } from 'eosjs'; -import { JsSignatureProvider } from 'eosjs/dist/eosjs-jssig'; -import { TextEncoder, TextDecoder } from 'util'; -import fetch from 'isomorphic-fetch'; +Дополнительная конфигурация не требуется. Модуль является чистой библиотекой типов без внешних зависимостей на рантайм-сервисы. -const signatureProvider = new JsSignatureProvider([wif]); -const api = new Api({ rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() }); -``` +## Тестирование -транзакция может содержать в себе массив действий, которые будут применяться последовательно друг за другом. Ниже мы сформируем транзакцию регистрации нового аккаунта, которая может быть вызвана только администратором или председателем кооператива. - -``` - const result = await eos.transact( - { - actions: [ - { - //здесь мы извлекаем имя контракта - account: RegistratorContract.contractName.production, - //здесь мы извлекаем имя действия - name: RegistratorContract.Actions.CreateAccount.actionName, - authorization: [ - { - // требуемые авторизации хранятся в RegistratorContract.Actions.CreateAccount.authorizations, откуда могут быть извлечены программно или вручную. - actor: chairman, - permission: 'active', - }, - ], - data: { - // подставляем данные действия - } as RegistratorContract.Actions.CreateAccount.ICreateAccount, - // здесь извлекаем интерфейс для действия - }, - ] - } - ); +```bash +pnpm --filter cooptypes run test ``` ## Лицензия -[MIT](./LICENSE) License © 2024-PRESENT [CBS VOSKHOD](https://github.com/coopenomics) - - - -[npm-version-src]: https://img.shields.io/npm/v/cooptypes?style=flat&colorA=080f12&colorB=1fa669 -[npm-version-href]: https://npmjs.com/package/cooptypes -[npm-downloads-src]: https://img.shields.io/npm/dm/cooptypes?style=flat&colorA=080f12&colorB=1fa669 -[npm-downloads-href]: https://npmjs.com/package/cooptypes -[bundle-src]: https://img.shields.io/bundlephobia/minzip/cooptypes?style=flat&colorA=080f12&colorB=1fa669&label=minzip -[bundle-href]: https://bundlephobia.com/result?p=cooptypes -[license-src]: https://img.shields.io/github/license/coopenomics/cooptypes.svg?style=flat&colorA=080f12&colorB=1fa669 -[license-href]: https://github.com/coopenomics/cooptypes/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/cooptypes +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/docs/README.md b/components/docs/README.md index 20eb05b2e71..bb562ebe79e 100644 --- a/components/docs/README.md +++ b/components/docs/README.md @@ -1,40 +1,103 @@ -# Документация «Цифровой Кооператив» +# 📚 @coopenomics/docs + +> Документация проекта «Цифровой Кооператив» + +## Описание + +`@coopenomics/docs` — компонент документации всей платформы. Использует [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) для генерации статического сайта из markdown-файлов. Включает руководства для пайщиков, администраторов и разработчиков, протоколы, API-документацию и глоссарий. + +Публикация на GitHub Pages выполняется через `gh-pages`. + +## Возможности + +- **MkDocs Material** — современная тема с тёмным/светлым режимом, навигацией, поиском и подсветкой кода +- **Макросы** — поддержка `mkdocs-macros-plugin` через `main.py` для динамического контента +- **Многоразделовая структура** — руководства для участников, администраторов, членов совета и разработчиков +- **Автосинхронизация** — скрипт `sync-docs.sh` подтягивает документацию из компонентов `sdk` и `controller` +- **GitHub Pages** — автоматическая публикация собранной документации + +## Предварительные требования + +- **Python 3.8+** +- **MkDocs и плагины** (см. раздел «Установка») +- **Node.js** (только для публикации на GitHub Pages) ## Установка -1. **Установите Python (3.8+)** - Убедитесь, что Python установлен в системе: - ```sh - python --version - ``` +### Python-зависимости -2. **Установите mkdocs и необходимые плагины:** - Рекомендуется использовать виртуальное окружение: - ```sh - python -m venv venv - source venv/bin/activate - pip install mkdocs-material mkdocs-macros-plugin mkdocs-section-index mkdocs-blog pymdown-extensions - ``` - > **Примечание:** - > Если используются дополнительные плагины, проверьте их наличие в `mkdocs.yml` и установите их через pip. +```bash +python -m venv venv +source venv/bin/activate +pip install mkdocs-material mkdocs-macros-plugin mkdocs-section-index mkdocs-blog pymdown-extensions +``` -3. **Установите Node.js-зависимости (только для публикации):** - ```sh - pnpm install - ``` +> Если используются дополнительные плагины, проверьте их наличие в `mkdocs.yml` и установите через `pip`. -## Сборка и запуск +### Node.js-зависимости (для публикации) -- **Локальный запуск документации:** - ```sh - mkdocs serve - ``` - Откройте [http://localhost:8000](http://localhost:8000) в браузере. +```bash +pnpm install --filter @coopenomics/docs +``` +## Скрипты -## Структура +| Скрипт | Описание | +|--------|----------| +| `mkdocs serve` | Локальный запуск сервера документации | +| `mkdocs build` | Сборка статического сайта в директорию `site/` | +| `./sync-docs.sh` | Синхронизация SDK и Controller документации | +| `pnpm run publish` | Публикация на GitHub Pages через `gh-pages` | -- `mkdocs.yml` — конфигурация сайта -- `docs/` — исходные markdown-файлы и ресурсы -- `main.py` — макросы для mkdocs-macros-plugin -- `site/` — собранная статика (автоматически создаётся) +## Синхронизация документации + +Скрипт `sync-docs.sh` автоматически подтягивает и копирует документацию из связанных компонентов: + +1. Копирует сгенерированную документацию SDK в `docs/sdk/` +2. Генерирует документацию контроллера и копирует в `docs/graphql/` + +```bash +./sync-docs.sh +``` + +## Архитектура + +``` +├── mkdocs.yml # Конфигурация MkDocs +├── main.py # Макросы для mkdocs-macros-plugin +├── sync-docs.sh # Скрипт синхронизации документации +├── docs/ # Исходные markdown-файлы +│ ├── participants/ # Руководство для пайщиков +│ │ ├── getting-started/ # Начало работы +│ │ ├── financial-operations/ # Финансовые операции +│ │ └── documents-and-applications/ # Документы +│ ├── manual/ # Руководство администратора +│ │ ├── about-mono/ # О платформе +│ │ ├── participants/ # Управление участниками +│ │ ├── documents/ # Документооборот +│ │ ├── soviet/ # Управление советом +│ │ └── admins/ # Администраторы +│ ├── new/ # Новые разделы документации +│ ├── sdk/ # Сгенерированная документация SDK +│ ├── graphql/ # Сгенерированная документация API +│ └── vocabulary.md # Глоссарий терминов +├── overrides/ # Пользовательские шаблоны +├── site/ # Собранная статика (автогенерация) +└── package.json +``` + +## Локальная разработка + +```bash +# Активируйте виртуальное окружение Python +source venv/bin/activate + +# Запустите dev-сервер +mkdocs serve +``` + +Документация будет доступна в браузере (адрес указывается в выводе команды `mkdocs serve`). + +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/migrator/README.md b/components/migrator/README.md index 44e47e20e13..36986bef5f5 100644 --- a/components/migrator/README.md +++ b/components/migrator/README.md @@ -1,200 +1,82 @@ -# Система миграций для смарт-контрактов COOPOS -Эта система автоматических миграций для смарт-контрактов COOPOS разработана на Node.js и TypeScript. Она предназначена для выполнения миграционных файлов с использованием паттерна фабрики. Система отслеживает состояние миграций и гарантирует, что будут выполнены только те миграции, которые еще не были применены. Конфигурация, специфичная для окружения, может загружаться динамически из различных файлов .env (например, local.env, prod.env). +# 🔄 migrator + +> Утилита миграции данных между версиями платформы «Цифровой Кооператив» + +## Описание + +`migrator` — система автоматических миграций для данных и смарт-контрактов платформы. Использует паттерн фабрики для динамической загрузки и последовательного выполнения миграционных скриптов. Отслеживает состояние миграций через JSON-файл и гарантирует применение только новых, ещё не выполненных миграций. + +Поддерживает несколько окружений (`local`, `test`, `prod`) с раздельной конфигурацией через `.env` файлы. ## Возможности -- Автоматическое выполнение миграций: Выполняет миграционные скрипты в указанном порядке. -- Отслеживание состояния миграций: Сохраняет информацию о последней выполненной миграции в файле migration_state.json. -- Динамическая загрузка конфигурации для окружений: Использует файлы .env для настроек, специфичных для разных окружений. -- Паттерн фабрики: Динамически загружает и выполняет миграционные файлы. -- Поддержка нескольких окружений: Легкое переключение между различными окружениями (например, local или prod) с использованием переменных окружения. - -## Требования -- Node.js (v14.x или выше) -- TypeScript (последняя версия) -- COOPOS (EOSJS библиотека для взаимодействия с блокчейном COOPOS) -- Библиотека fs-extra для операций с файловой системой +- **Автоматическое отслеживание** — JSON-файл состояния хранит последнюю выполненную миграцию для каждого окружения +- **Инкрементальное применение** — выполняются только новые миграции, пропуская уже применённые +- **Паттерн Factory** — динамическая загрузка миграционных скриптов через `MigrationFactory` +- **Множество окружений** — раздельные `.env` файлы для `local`, `test` и `prod` +- **Утилиты** — вспомогательные функции для работы с черновиками документов, переводами и блокчейн-операциями ## Установка -Склонируйте репозиторий: -``` bash -git clone -cd +```bash +pnpm install --filter migrator ``` -Установите необходимые зависимости: +## Скрипты + +| Скрипт | Описание | +|--------|----------| +| `pnpm run local` | Запуск миграций для локального окружения | +| `pnpm run test` | Запуск миграций для тестового окружения | +| `pnpm run prod` | Запуск миграций для production-окружения | + +> Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter migrator run <скрипт>` + +## Конфигурация + +Создайте `.env` файлы для каждого окружения в корне компонента: + +- `local.env` — локальная разработка +- `test.env` — тестовое окружение +- `prod.env` — production + +Основные переменные: endpoint блокчейна, приватные ключи для подписи транзакций. Подробности — в примерах `.env` файлов. + +## Архитектура -``` bash -npm install -Настройте .env файлы для разных окружений: ``` - -local.env -prod.env - -Пример файла .env: - -``` env -COOPOS_ENDPOINT=https://api.testnet.COOPOS.io -COOPOS_PRIVATE_KEY=your_private_key -``` - -``` bash -project-root/ -├── migrations/ # Директория миграций -│ ├── 001_initial_migration.ts -│ ├── 002_upgrade_contract.ts -│ +├── migrations/ # Миграционные скрипты +│ ├── 043_edit_selected_draft.ts +│ ├── 044_create_drafts.ts +│ └── ... # Нумерованные по порядку ├── src/ -│ ├── factory.ts # Фабрика для загрузки миграций -│ ├── migrator.ts # Основная логика миграций -│ ├── migration_interface.ts # Интерфейс для миграционных классов -│ ├── utils/dirname.ts # Утилита для эмуляции __dirname в ES модулях -│ ├── index.ts # Основная точка входа -│ -├── migration_state.json # Файл для отслеживания последней выполненной миграции -├── local.env # Конфигурация для локального окружения -├── prod.env # Конфигурация для продакшн окружения -├── package.json -└── tsconfig.json +│ ├── index.ts # Точка входа — загрузка .env и запуск +│ ├── migrator.ts # Основная логика: загрузка состояния, выполнение миграций +│ ├── factory.ts # Фабрика загрузки миграционных скриптов +│ ├── migration_interface.ts # Интерфейс миграции +│ ├── eos.ts # Утилиты для работы с блокчейном EOSIO +│ └── utils/ # Вспомогательные утилиты +│ ├── createDraft.ts # Создание черновиков документов +│ ├── editDraft.ts # Редактирование черновиков +│ ├── editTranslation.ts # Работа с переводами +│ └── dirname.ts # ESM-совместимый __dirname +└── migration_state.json # Состояние выполненных миграций (per-env) ``` -## Использование -Создание миграционных файлов: +### Жизненный цикл миграции -Миграционные файлы должны размещаться в папке migrations. Каждый файл миграции должен экспортировать класс, который реализует интерфейс Migration. Например: +1. Загружается файл состояния `migration_state.json` +2. Определяется последняя выполненная миграция для текущего окружения +3. Из директории `migrations/` выбираются все скрипты после последней выполненной +4. Каждая миграция загружается через `MigrationFactory` и выполняется последовательно +5. После успешного выполнения состояние обновляется -``` typescript -import { Migration } from './migration_interface'; - -export class InitialMigration implements Migration { - async run(): Promise { - console.log('Запуск первой миграции...'); - // Логика миграции (например, взаимодействие с контрактами COOPOS) - } -} +## Тестирование +```bash +pnpm --filter migrator run test ``` -Запуск миграций: - -Для запуска миграций используйте следующую команду: - -``` bash -NODE_ENV=local npx ts-node src/index.ts -``` - -Эта команда выполнит все ожидающие миграции, начиная с последней зафиксированной в файле migration_state.json. - -Работа с разными окружениями: - -Система поддерживает несколько окружений с использованием файлов .env. Чтобы указать конкретное окружение, используйте переменную NODE_ENV: - -Для локального окружения: - -``` bash -NODE_ENV=local npx ts-node src/index.ts - -Для продакшн окружения: - -``` bash -NODE_ENV=prod npx ts-node src/index.ts -``` - -## Детали системы миграций - -### 1. Интерфейс миграций -Каждый миграционный файл должен реализовать следующий интерфейс Migration: - -``` typescript -export interface Migration { - run(): Promise; -} -``` - -Это гарантирует, что каждый миграционный файл содержит метод run, который будет выполнен системой миграций. - -### 2. Паттерн фабрики -Класс MigrationFactory динамически загружает миграционные файлы по их именам и возвращает экземпляр соответствующего класса: - -``` typescript -import { Migration } from '../migrations/migration_interface'; -import * as path from 'path'; -import { getDirname } from '../utils/dirname'; - -export class MigrationFactory { - static async createMigration(migrationFile: string): Promise { - try { - const __dirname = getDirname(import.meta.url); - const migrationModule = await import(path.join(__dirname, '../migrations', migrationFile + '.ts')); - const MigrationClass = migrationModule.default || migrationModule[Object.keys(migrationModule)[0]]; - return new MigrationClass(); - } catch (error) { - console.error(`Не удалось загрузить файл миграции ${migrationFile}:`, error); - return null; - } - } -} -``` - -### 3. Отслеживание состояния миграций -Система миграций сохраняет информацию о последней выполненной миграции в файл migration_state.json. После успешного выполнения каждой миграции, система обновляет этот файл с указанием последней миграции. - -``` json -{ - "lastMigration": "002_upgrade_contract.ts" -} -``` - -Если файл migration_state.json не существует, система предполагает, что миграции ещё не выполнялись, и начинает выполнение с первого файла. - -### 4. Мигратор -Класс Migrator отвечает за выполнение ожидающих миграций: - -``` typescript -import fs from 'fs-extra'; -import * as path from 'path'; -import { getDirname } from './utils/dirname'; -import { MigrationFactory } from './factory'; - -export class Migrator { - private stateFilePath: string; - private state: { lastMigration: string | null }; - - constructor() { - const __dirname = getDirname(import.meta.url); - this.stateFilePath = path.join(__dirname, '../migration_state.json'); - this.state = { lastMigration: null }; - } - - // Загрузка состояния миграций и фильтрация ожидающих миграций - async runMigrations(): Promise { - await this.loadState(); - const pendingMigrations = await this.getPendingMigrations(); - - for (const file of pendingMigrations) { - const migration = await MigrationFactory.createMigration(file); - if (migration) { - await migration.run(); - this.state.lastMigration = file; - await this.saveState(); - } - } - - console.log('Миграции завершены.'); - } -} -``` - -## Решение проблем - -Проблема: Миграция не загружается -Убедитесь, что файл миграции существует в директории migrations. Проверьте имя файла в migration_state.json и убедитесь, что оно совпадает с существующими файлами миграций. - -Проблема: Миграция не найдена (например, "MigrationClass is not a constructor") -Убедитесь, что ваши файлы миграций экспортируют класс, который реализует интерфейс Migration. - ## Лицензия -Этот проект лицензирован под лицензией MIT. +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/notifications/README.md b/components/notifications/README.md index 71c02753327..e4ca74f01e3 100644 --- a/components/notifications/README.md +++ b/components/notifications/README.md @@ -1,218 +1,119 @@ -# Notifications Library - Типизированные Workflow для Novu +# 🔔 @coopenomics/notifications -Библиотека для создания типизированных workflow уведомлений с использованием Zod схем и паттерна Builder. +> Типобезопасная библиотека workflow-уведомлений для платформы Novu -## Особенности +## Описание -- 🔒 **Типобезопасность** - Полная типизация payload с Zod -- 🏗️ **Builder Pattern** - Удобное создание workflow -- 📝 **Декларативный API** - Простое описание шагов уведомлений -- 🔧 **Расширяемость** - Легкое добавление новых типов workflow -- ⚡ **Валидация** - Автоматическая валидация данных -- 🏷️ **Теги и роли** - Группировка уведомлений по ролям пользователей +`@coopenomics/notifications` — библиотека для создания и управления workflow уведомлений кооператива. Построена на Zod-схемах и паттерне Builder, обеспечивая полную типобезопасность payload каждого уведомления. Поддерживает множество каналов доставки и ролевую маршрутизацию через систему тегов. + +Интегрируется с платформой [Novu](https://novu.co) для оркестрации и доставки уведомлений. + +## Возможности + +- **21 workflow** — покрытие всех ключевых бизнес-процессов кооператива +- **Типобезопасность** — Zod-схемы для валидации payload каждого workflow +- **Многоканальность** — Email (HTML), In-App, Push, SMS, Chat +- **Ролевая маршрутизация** — теги для направления уведомлений по ролям (председатель, член совета, пайщик) +- **Паттерн Builder** — удобное декларативное создание новых workflow через `WorkflowBuilder` +- **Синхронизация** — автоматическая синхронизация workflow с платформой Novu + +## Workflow + +| Workflow | Описание | +|----------|----------| +| `welcome` | Приветствие нового участника | +| `approval-request` | Запрос на утверждение (совету) | +| `approval-response` | Ответ на запрос утверждения | +| `decision-approved` | Решение утверждено | +| `decision-expired` | Решение просрочено | +| `payment-paid` | Платёж выполнен | +| `payment-cancelled` | Платёж отменён | +| `new-initial-payment-request` | Запрос начального взноса | +| `new-deposit-payment-request` | Запрос депозитного взноса | +| `incoming-transfer` | Входящий перевод | +| `new-agenda-item` | Новый пункт повестки | +| `meet-initial` | Инициация собрания | +| `meet-reminder-start` | Напоминание о начале собрания | +| `meet-started` | Собрание началось | +| `meet-reminder-end` | Напоминание об окончании собрания | +| `meet-restart` | Перезапуск собрания | +| `meet-ended` | Собрание завершено | +| `invite` | Приглашение в кооператив | +| `reset-key` | Сброс ключа доступа | +| `email-verification` | Подтверждение электронной почты | +| `server-provisioned` | Сервер подготовлен | ## Установка ```bash -cd components/notifications -pnpm install +pnpm install --filter @coopenomics/notifications ``` -## Быстрый старт +## Скрипты -### 1. Создание нового workflow +| Скрипт | Описание | +|--------|----------| +| `pnpm run build` | Сборка библиотеки (`unbuild`) | +| `pnpm run dev` | Режим разработки с отслеживанием изменений (`unbuild --watch`) | +| `pnpm run test` | Запуск тестов (`vitest`) | +| `pnpm run sync` | Синхронизация workflow с платформой Novu | +| `pnpm run sync:dev` | Синхронизация в dev-режиме | -```typescript -import { z } from 'zod'; -import { WorkflowBuilder, createEmailStep, createInAppStep } from '@coopenomics/notifications'; +> Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter @coopenomics/notifications run <скрипт>` -// Определяем схему данных -const myPayloadSchema = z.object({ - userName: z.string(), - userEmail: z.string().email(), - orderTotal: z.number(), -}); +## Конфигурация -type MyPayload = z.infer; +Для синхронизации с Novu необходим API-ключ. Подробности о настройке — в [документации Novu](https://docs.novu.co). -// Создаем workflow -export const orderConfirmationWorkflow = WorkflowBuilder - .create() - .name('Order Confirmation') - .workflowId('order-confirmation') - .description('Подтверждение заказа') - .payloadSchema(myPayloadSchema) - .addSteps([ - createEmailStep( - 'order-email', - 'Заказ подтвержден - {{payload.userName}}', - 'Здравствуйте, {{payload.userName}}! Ваш заказ на сумму {{payload.orderTotal}} подтвержден.' - ), - createInAppStep( - 'order-notification', - 'Заказ обработан', - 'Заказ успешно обработан и скоро будет отправлен.' - ), - ]) - .build(); -``` - -### 2. Регистрация workflow - -Добавьте ваш workflow в `src/workflows/index.ts`: - -```typescript -import { orderConfirmationWorkflow } from './order-confirmation'; - -export const allWorkflows: WorkflowDefinition[] = [ - welcomeWorkflow, - orderConfirmationWorkflow, // ← добавляем новый workflow -]; -``` - -### 3. Использование в коде - -```typescript -import { orderConfirmationWorkflow } from '@coopenomics/notifications'; - -// Валидация данных -const payload = orderConfirmationWorkflow.payloadZodSchema.parse({ - userName: 'Иван Иванов', - userEmail: 'ivan@example.com', - orderTotal: 1500, -}); - -// Данные для отправки в Novu -const novuData = orderConfirmationWorkflow.payloadSchema; -``` - -## Структура проекта +## Архитектура ``` src/ -├── types/ # Базовые типы и интерфейсы -├── base/ # Базовые утилиты и настройки -│ ├── defaults.ts # Настройки по умолчанию -│ └── workflow-builder.ts # Builder для создания workflow -└── workflows/ # Папки с workflow - ├── welcome/ # Приветственные уведомления - ├── order/ # Уведомления о заказах - └── index.ts # Экспорт всех workflow +├── types/ # Базовые типы и интерфейсы +│ └── index.ts # ChannelConfig, WorkflowStep, WorkflowDefinition +├── base/ # Ядро библиотеки +│ ├── defaults.ts # Настройки по умолчанию для каналов +│ └── workflow-builder.ts # Паттерн Builder для создания workflow +├── utils/ # Вспомогательные утилиты +│ └── index.ts +├── workflows/ # Определения workflow (21 директория) +│ ├── welcome/ # Приветствие +│ ├── approval-request/ # Запрос утверждения +│ ├── approval-response/ # Ответ на утверждение +│ ├── decision-approved/ # Решение утверждено +│ ├── decision-expired/ # Решение просрочено +│ ├── payment-paid/ # Платёж выполнен +│ ├── payment-cancelled/ # Платёж отменён +│ ├── meet-initial/ # Инициация собрания +│ ├── meet-started/ # Собрание началось +│ ├── meet-ended/ # Собрание завершено +│ ├── meet-reminder-start/ # Напоминание о начале +│ ├── meet-reminder-end/ # Напоминание об окончании +│ ├── meet-restart/ # Перезапуск собрания +│ ├── invite/ # Приглашение +│ ├── reset-key/ # Сброс ключа +│ ├── email-verification/ # Подтверждение email +│ ├── incoming-transfer/ # Входящий перевод +│ ├── new-agenda-item/ # Пункт повестки +│ ├── new-initial-payment-request/ # Запрос начального взноса +│ ├── new-deposit-payment-request/ # Запрос депозитного взноса +│ └── server-provisioned/ # Сервер подготовлен +├── sync/ # Синхронизация с Novu +│ ├── novu-sync.service.ts # Сервис синхронизации +│ └── sync-runner.ts # Точка входа для sync-скриптов +└── index.ts # Главная точка входа ``` -## API Reference +Каждый workflow экспортирует определение типа `WorkflowDefinition` с Zod-схемой payload, настройками каналов и шаблонами сообщений. Все workflow автоматически регистрируются через массив `allWorkflows` и доступны по идентификатору через `workflowsById`. -### WorkflowBuilder - -Основной класс для создания workflow: - -```typescript -const workflow = WorkflowBuilder - .create() - .name('Workflow Name') // Название workflow - .workflowId('unique-workflow-id') // Уникальный ID - .description('Описание workflow') // Описание (опционально) - .payloadSchema(zodSchema) // Zod схема для валидации - .addStep(step) // Добавить шаг - .addSteps([step1, step2]) // Добавить несколько шагов - .origin('external') // Источник (опционально) - .build(); // Собрать workflow -``` - -### Вспомогательные функции - -```typescript -// Email уведомление -createEmailStep(name, subject, body) - -// In-app уведомление -createInAppStep(name, subject, body, avatar?) - -// Push уведомление -createPushStep(name, title, body) - -// SMS уведомление -createSmsStep(name, body) -``` - -## Типы workflow - -### Email -- `subject` - Тема письма -- `body` - HTML содержимое -- `editorType` - 'html' | 'text' - -### In-App -- `subject` - Заголовок уведомления -- `body` - Текст уведомления -- `avatar` - URL аватара (опционально) - -### Push -- `subject` - Заголовок push-уведомления -- `body` - Текст push-уведомления - -### SMS -- `body` - Текст SMS - -## Шаблонизация - -Используйте Handlebars синтаксис для динамических данных: - -```typescript -// Простая подстановка -"Привет, {{payload.userName}}!" - -// Условные блоки -"{{#payload.age}}Ваш возраст: {{payload.age}}{{/payload.age}}" - -// Вложенные объекты -"{{payload.order.total}} руб." -``` - -## Теги и роли - -Библиотека поддерживает группировку уведомлений по ролям пользователей с помощью тегов. Теги позволяют фильтровать уведомления в UI компонентах. - -### Добавление тегов к workflow - -```typescript -export const newAgendaItemWorkflow = WorkflowBuilder - .create() - .name('Новый вопрос на повестке') - .workflowId('new-agenda-item') - .description('Уведомление о новом вопросе на повестке') - .payloadSchema(newAgendaItemPayloadSchema) - .tags(['chairman', 'member']) // Теги для ролей пользователей - .addSteps([ - // ... шаги - ]) - .build(); -``` - -### Использование в компонентах - -```typescript -// Создание табов для фильтрации по ролям -const tabs = [ - { - label: 'Все уведомления', - filter: { - tags: [userRole.value], // Фильтр по роли пользователя - }, - }, -]; -``` - -### Доступные роли - -- `chairman` - Председатель совета -- `member` - Член совета -- `user` - Обычный пользователь - -## Сборка +## Тестирование ```bash -pnpm build +pnpm --filter @coopenomics/notifications run test ``` -Результат сборки будет в папке `dist/`. +Проект содержит 7 smoke-тестов на `vitest`, проверяющих корректность определений workflow и Zod-схем. + +## Лицензия + +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru) diff --git a/components/sdk/README.md b/components/sdk/README.md index 4c692b28266..fd02d287b00 100644 --- a/components/sdk/README.md +++ b/components/sdk/README.md @@ -1,127 +1,116 @@ -# @coopenomics/sdk +# 🔌 @coopenomics/sdk -[@coopenomics/sdk](https://coopenomics.world) — это SDK-клиент, обеспечивающий удобный программный доступ к запросам, мутациям и подпискам [GraphQL-API](/graphql) с полной типизацией входных и выходных данных на TypeScript. Он предназначен для интеграции с `MONO` и [Кооперативной Экономикой](https://coopenomics.world), упрощая взаимодействие с системой. +> TypeScript SDK для типобезопасной работы с GraphQL API кооператива -## Документация -https://цифровой-кооператив.рф/documentation +## Описание -## Возможности SDK +`@coopenomics/sdk` — клиентская библиотека для программного взаимодействия с API платформы «Цифровой Кооператив». Обеспечивает полную типизацию запросов, мутаций и подписок через [GraphQL Zeus](https://github.com/graphql-editor/graphql-zeus). Включает классы для работы с блокчейном EOSIO, цифровыми подписями, генерацией документов и JWT-аутентификацией. -- **Запросы** к `MONO` с автоматической типизацией. -- **Мутации** данных с валидацией входных параметров. -- **Подписки** на события в системе. -- **Классы** для работы с блокчейном, цифровыми подписями и документами. -- **Интеграция с блокчейном**, включая отправку транзакций. -- **Поддержка JWT-токенов** для аутентификации. +📖 Документация: [цифровой-кооператив.рф/sdk](https://цифровой-кооператив.рф/sdk) + +## Возможности + +- **Типобезопасные запросы** — все GraphQL-запросы и мутации полностью типизированы через Zeus-селекторы +- **Блокчейн-операции** — подпись транзакций, работа с аккаунтами и ключами EOSIO (`@wharfkit`) +- **Документооборот** — генерация, подпись и верификация юридических документов +- **Голосование** — участие в голосованиях совета кооператива +- **Подписки в реальном времени** — WebSocket-подписки на события через `graphql-ws` +- **JWT-аутентификация** — управление токенами доступа +- **Canvas** — утилиты для генерации визуальных представлений ## Установка -```sh -npm install @coopenomics/sdk -# или +```bash +pnpm install --filter @coopenomics/sdk + +# Для внешних проектов: pnpm add @coopenomics/sdk ``` -Подключение +## Быстрый старт -```ts -import { createClient } from '@coopenomics/sdk' +```typescript +import { Client } from '@coopenomics/sdk' -// создаём клиент -const client = createClient({ - api_url: 'http://127.0.0.1:2998/v1/graphql', // адрес MONO GraphQL-API - chain_url: 'https://api.coopenomics.world', // адрес конечной точки блокчейна - chain_id: 'cae86058a6d8698833afb474ab8a5ad8599c6cf54f9ebcf275dbac7055c16fe1', // идентификатор цепочки блоков +const client = new Client({ + api_url: '/v1/graphql', + chain_url: '', + chain_id: '', }) + +// Установка JWT-токена +client.setToken('') + +// Выполнение типизированного запроса +const result = await client.Query(Queries.GetSystemInfo, {}) ``` -Аутентификация выполняется с помощью JWT: +## Скрипты -```ts -client.setToken('') +| Скрипт | Описание | +|--------|----------| +| `pnpm run build` | Сборка библиотеки (`unbuild`, с предварительной проверкой типов) | +| `pnpm run dev` | Режим разработки (`unbuild --stub`) | +| `pnpm run test` | Запуск тестов (`vitest`, таймаут 60 сек) | +| `pnpm run lint` | Проверка кода (`ESLint`) | +| `pnpm run typecheck` | Проверка типов TypeScript (`tsc --noEmit`) | +| `pnpm run docs` | Генерация документации (`TypeDoc` + автокомментарии) | + +> Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter @coopenomics/sdk run <скрипт>` + +## Конфигурация + +SDK не требует `.env` файлов — параметры передаются при создании клиента: + +| Параметр | Описание | +|----------|----------| +| `api_url` | URL GraphQL API контроллера | +| `chain_url` | URL блокчейн-ноды | +| `chain_id` | Идентификатор цепочки блоков | + +## Архитектура + +``` +src/ +├── classes/ # Высокоуровневые классы +│ ├── account.ts # Работа с аккаунтами +│ ├── blockchain.ts # Блокчейн-операции +│ ├── canvas.ts # Визуальные утилиты +│ ├── crypto.ts # Криптографические операции +│ ├── document.ts # Документооборот +│ └── vote.ts # Голосование +├── mutations/ # Типизированные мутации (Zeus selectors) +├── queries/ # Типизированные запросы (Zeus selectors) +├── selectors/ # Переиспользуемые селекторы по доменам +│ ├── system/ # Системные запросы +│ ├── registration/ # Регистрация +│ ├── wallet/ # Кошелёк +│ ├── gateway/ # Платежи +│ ├── documents/ # Документы +│ ├── decisions/ # Решения совета +│ ├── meet/ # Собрания +│ ├── ledger/ # Бухгалтерия +│ ├── extensions/ # Расширения +│ └── ... # Другие домены +├── types/ # Типы и интерфейсы клиента +│ ├── client/ # Опции подключения +│ ├── blockchain/ # Блокчейн-типы +│ ├── controller/ # Типы контроллера +│ └── document/ # Типы документов +├── zeus/ # Сгенерированный клиент GraphQL Zeus +└── index.ts # Точка входа (экспорт Client) ``` -## Запросы -Для выполнения запросов используйте пространство Queries. Например, получение данных об аккаунте: +Селекторы генерируются из GraphQL-схемы контроллера с помощью `graphql-zeus`. Каждый селектор валидируется через `MakeAllFieldsRequired` для гарантии полноты полей. -```ts -import { Queries } from '@coopenomics/sdk' +## Тестирование -const variables: Queries.Accounts.GetAccount.IInput = { - data: { username: '' } -} - -const { [Queries.Accounts.GetAccount.name]: result } = await client.Query( - Queries.Accounts.GetAccount.query, - { variables } -) +```bash +pnpm --filter @coopenomics/sdk run test ``` -Результат будет типизирован в соответствии с Queries.Accounts.GetAccount.IOutput. - -## Мутации -Для изменения данных используется пространство Mutations. Например, создание паевого взноса: - -```ts -import { Mutations } from '@coopenomics/sdk' - -const variables: Mutations.Payments.CreateDepositPayment.IInput = { - data: { username: '', quantity: '100.00' } -} - -const { [Mutations.Payments.CreateDepositPayment.name]: result } = await client.Mutation( - Mutations.Payments.CreateDepositPayment.mutation, - { variables } -) -``` - -Результат будет типизирован в соответствии с Mutations.Payments.CreateDepositPayment.IOutput. - -### Работа с блокчейном -SDK включает классы для взаимодействия с блокчейном, например: - -```ts - -import { Blockchain } from '@coopenomics/sdk' - -const blockchain = new Blockchain(client) -blockchain.setWif(, ) - -const tableData = await blockchain.getAllRows('some_contract', 'some_scope', 'some_table') -``` - -### Использование списков Zeus -Некоторые мутации требуют списки значений, например, установка статуса платежа: - -```ts -import { Mutations, Zeus } from '@coopenomics/sdk' - -const variables: Mutations.Payments.SetPaymentStatus.IInput = { - data: { id: '', status: Zeus.PaymentStatus.PAID } -} - -const { [Mutations.Payments.SetPaymentStatus.name]: result } = await client.Mutation( - Mutations.Payments.SetPaymentStatus.mutation, - { variables } -) -``` - -Полный список доступных значений находится в документации SDK. - -### Дополнительная информация -Общая документация: https://цифровой-кооператив.рф/documentation - -Руководство по SDK: https://цифровой-кооператив.рф/sdk - -Документация GraphQL API: https://цифровой-кооператив.рф/graphql - -Кооперативная Экономика: https://coopenomics.world +Проект содержит 4 интеграционных теста на `vitest` с таймаутом 60 секунд, проверяющих корректность работы клиента с API. ## Лицензия -Продукт Потребительского Кооператива "ВОСХОД" распространяется по лицензии BY-NC-SA 4.0. -Разрешено делиться, копировать и распространять материал на любом носителе и форме, адаптировать, делать ремиксы, видоизменять и создавать новое, опираясь на этот материал. При использовании, Вы должны обеспечить указание авторства, предоставить ссылку, и обозначить изменения, если таковые были сделаны. Если вы перерабатываете, преобразовываете материал или берёте его за основу для производного произведения, вы должны распространять переделанные вами части материала на условиях той же лицензии, в соответствии с которой распространяется оригинал. Запрещено коммерческое использование материала. Использование в коммерческих целях – это использование, в первую очередь направленное на получение коммерческого преимущества или денежного вознаграждения. - -Юридический текст лицензии: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru - -© 2025 Потребительский Кооператив "ВОСХОД". Все права защищены. +[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru)