From 5043995d14c7b48eb4fccc8845bd9af7608a98a8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 25 Feb 2026 19:02:40 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20AGENTS.md=20=D0=B4=D0=BB=D1=8F=206=20?= =?UTF-8?q?=D0=BA=D0=BE=D0=BC=D0=BF=D0=BE=D0=BD=D0=B5=D0=BD=D1=82=D0=BE?= =?UTF-8?q?=D0=B2=20(factory,=20boot,=20parser,=20sdk,=20cooptypes,=20noti?= =?UTF-8?q?fications)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alex Ant --- components/boot/AGENTS.md | 102 +++++++++++++++++++++++++++ components/cooptypes/AGENTS.md | 98 ++++++++++++++++++++++++++ components/factory/AGENTS.md | 83 ++++++++++++++++++++++ components/notifications/AGENTS.md | 97 +++++++++++++++++++++++++ components/parser/AGENTS.md | 100 ++++++++++++++++++++++++++ components/sdk/AGENTS.md | 109 +++++++++++++++++++++++++++++ 6 files changed, 589 insertions(+) create mode 100644 components/boot/AGENTS.md create mode 100644 components/cooptypes/AGENTS.md create mode 100644 components/factory/AGENTS.md create mode 100644 components/notifications/AGENTS.md create mode 100644 components/parser/AGENTS.md create mode 100644 components/sdk/AGENTS.md diff --git a/components/boot/AGENTS.md b/components/boot/AGENTS.md new file mode 100644 index 00000000000..33d8bec8992 --- /dev/null +++ b/components/boot/AGENTS.md @@ -0,0 +1,102 @@ +# @coopenomics/boot + +## Назначение + +CLI-утилита для инициализации блокчейна EOSIO и развёртывания кооператива. Выполняет полный цикл: запуск ноды → создание аккаунтов → активация фич → деплой контрактов → выпуск токенов → загрузка шаблонов → создание кооператива и совета. + +## Структура + +``` +src/ +├── index.ts — CLI точка входа (commander): boot, boot:clean, boot:extra, +│ start, stop, clear, cleos, deploy, create-coop, unlock +├── init/ +│ ├── booter.ts — Главные сценарии: boot(), bootClean(), bootExtra() +│ ├── infra.ts — startInfra() — базовая инфраструктура блокчейна +│ │ installInitialData() — начальные данные (пользователи, совет) +│ │ installExtraData() — расширенные данные +│ └── cooperative.ts — CooperativeClass — создание программ ЦПП, регистрация +│ └── participant.ts — Логика регистрации пайщика +├── blockchain/ +│ └── index.ts — Класс Blockchain — обёртка над eosjs для работы с EOSIO +│ (создание аккаунтов, деплой контрактов, транзакции, токены) +├── configs/ +│ ├── index.ts — Главная конфигурация (аккаунты, ключи, токен, эмиссия) +│ ├── networks.ts — Настройки сети (протокол, хост, порт) +│ ├── contracts.ts — Список контрактов и путей к их WASM/ABI файлам +│ └── protocol_features/ — JSON-файлы фич для активации на блокчейне +├── docker/ — Управление Docker-контейнером ноды блокчейна +│ ├── container.ts, run.ts, stop.ts, find.ts, exec.ts, deploy.ts +│ ├── health.ts — Проверка готовности ноды +│ └── purge.ts — Очистка данных блокчейна и БД +├── *-init.ts — Инициализация реляционной БД (пользователи, vault, статус, extensions) +├── tests/ — Интеграционные тесты +│ ├── capital.test.ts — Основной тест (полный цикл ЦПП) +│ ├── wallet.test.ts — Тесты кошелька +│ ├── registrator.test.ts — Тесты регистрации +│ └── capital/ — Вспомогательные функции для тестов капитала +└── utils/ — Утилиты (sleep, randomHash, randomUsername, и т.д.) +``` + +## Порядок загрузки (boot flow) + +1. **startInfra()** — основа: + - Инициализация `Blockchain` с ключами + - Создание системных аккаунтов (eosio.token, registrator, soviet, и т.д.) + - Активация фич протокола (PREACTIVATE_FEATURE → остальные) + - Деплой смарт-контрактов (eosio.boot → eosio.system → все остальные) + - Создание и выпуск токенов + - Загрузка шаблонов документов из `@coopenomics/factory` Registry + - Настройка ресурсов (powerup) + +2. **installInitialData()** — данные кооператива: + - Сохранение организации, платёжных методов, физлиц в MongoDB + - Сохранение переменных кооператива (vars) + - Регистрация пользователей в блокчейне + - Инициализация реляционной БД (пользователи, vault) + - Создание совета (board) + - Создание программ ЦПП (Благорост, маркетплейс) + +3. **bootClean()** — минимальная загрузка (только инфра + программы, без данных) + +4. **bootExtra()** — расширенная загрузка (5 членов совета, дополнительные пайщики) + +## Режимы контрактов + +- **test** — контракты собранные с флагом `test` (позволяют boot с 1 членом совета) +- **production** — стандартные контракты (требуют кворум) + +Пути к WASM/ABI файлам указаны в `configs/contracts.ts`, относительно `../contracts/build/contracts/`. + +## Тесты + +- Фреймворк: **Vitest** +- Основной тест: `src/tests/capital.test.ts` — полный цикл ЦПП (создание программ, проектов, инвестирование, голосование, конвертация) +- Требует: полностью загруженный блокчейн (`pnpm run reboot`), MongoDB, реляционную БД + +### Запуск + +``` +pnpm --filter @coopenomics/boot test +``` + +### Важно: Duplicate transaction + +EOSIO отклоняет транзакции с одинаковым хешем (TAPOS block + action data). При повторных вызовах одинаковых действий нужен `await sleep(500)` между ними. + +## Скрипты package.json + +| Скрипт | Описание | +|--------|----------| +| `boot` | Полная загрузка: инфра + данные + кооператив | +| `boot:clean` | Чистая загрузка: только инфра + программы | +| `boot:extra` | Расширенная загрузка: инфра + 5 членов совета | +| `create-coop` | Создание кооператива после boot:clean | +| `test` | Vitest (capital.test.ts, timeout 240s) | +| `test:all` | Все тесты | +| `clear` | Очистка блокчейна и перезапуск ноды | + +## Зависимости от других компонентов + +- `cooptypes` (workspace) — типы контрактов +- `@coopenomics/factory` (workspace) — реестр шаблонов, сохранение данных в MongoDB diff --git a/components/cooptypes/AGENTS.md b/components/cooptypes/AGENTS.md new file mode 100644 index 00000000000..35764baaf42 --- /dev/null +++ b/components/cooptypes/AGENTS.md @@ -0,0 +1,98 @@ +# cooptypes + +## Назначение + +Общая библиотека TypeScript-типов экосистемы кооперативов. Содержит интерфейсы для всех смарт-контрактов блокчейна, модели данных кооперативов, интерфейсы документов и реестр шаблонов документов с Markdown-шаблонами. + +## Структура + +``` +src/ +├── index.ts — Главный экспорт: _Common, contracts, Cooperative, Interfaces +├── contracts/ — Типы для каждого смарт-контракта +│ ├── index.ts — Экспорт всех контрактов +│ ├── draft/ — DraftContract: шаблоны документов +│ ├── registrator/ — RegistratorContract: аккаунты и кооперативы +│ ├── soviet/ — SovietContract: советы и решения +│ ├── gateway/ — GatewayContract: платёжный шлюз +│ ├── token/ — TokenContract: токены +│ ├── wallet/ — WalletContract: кошельки и взносы +│ ├── capital/ — CapitalContract: интеллектуальная капитализация +│ ├── fund/ — FundContract: фонды +│ ├── branch/ — BranchContract: кооперативные участки +│ ├── marketplace/ — MarketContract: маркетплейс +│ ├── ledger/ — LedgerContract: бухгалтерская книга +│ ├── meet/ — MeetContract: общие собрания +│ ├── loan/ — LoanContract: займы +│ ├── system/ — SystemContract: системные операции +│ ├── msig/ — MsigContract: мульти-подписи +│ └── wrap/ — WrapContract: привилегированные действия +├── cooperative/ +│ ├── users/ — IIndividualData, IOrganizationData, IEntrepreneurData +│ ├── registry/ — Реестр шаблонов документов с Markdown-шаблонами +│ │ ├── index.ts — Экспорт всех шаблонов по registry_id +│ │ └── ./ — Каждая директория = один шаблон +│ │ ├── index.ts — Метаданные (title, description, context, model, translations) +│ │ └── template.md — Markdown-шаблон (не у всех) +│ ├── payments/ — Типы платёжных методов +│ └── Model.ts — IVars, основная модель кооператива +├── interfaces/ — Общие интерфейсы системы +│ ├── index.ts — Экспорт всех интерфейсов +│ ├── branch.ts, capital.ts, draft.ts, fund.ts +│ ├── gateway.ts, ledger.ts, loan.ts, marketplace.ts +│ ├── meet.ts, msig.ts, registrator.ts, soviet.ts +│ ├── system.ts, token.ts, wallet.ts, wrap.ts +│ └── ... +└── common/ — Общие утилитарные типы +``` + +## Ключевые концепции + +### Именование контрактов + +Каждый контракт экспортирует `contractName` с вариантами для разных сетей: +```typescript +SovietContract.contractName.production // → 'soviet' +``` + +### Структура контракта + +Каждый контракт содержит: +- **Tables** — интерфейсы таблиц блокчейна (имя таблицы + тип строки) +- **Actions** — интерфейсы действий (параметры + авторизация) + +Пример: +```typescript +RegistratorContract.Tables.Cooperatives.tableName // → 'coops' +RegistratorContract.Tables.Cooperatives.ICooperative // интерфейс строки + +SovietContract.Actions.Decisions.VoteFor.IVoteForDecision // интерфейс параметров действия +``` + +### Реестр шаблонов (cooperative/registry/) + +Каждый шаблон (по `registry_id`) содержит: +- `title` — название документа +- `description` — описание +- `context` — контекст (statement, decision, act, и т.д.) +- `model` — JSON-модель данных для генерации +- `translations` — переводы (обычно `{ ru: {...} }`) +- Опционально: `template.md` — Markdown-шаблон с Handlebars-плейсхолдерами + +### IDocument + +Базовый интерфейс документа блокчейна: `version`, `hash`, `doc_hash`, `meta_hash`, `meta`, `signatures`. + +## Скрипты package.json + +| Скрипт | Описание | +|--------|----------| +| `build` | Сборка через unbuild | +| `dev` | Пересборка при изменениях (nodemon + unbuild) | +| `test` | Vitest | +| `lint` | ESLint | +| `typecheck` | TypeScript проверка | + +## Зависимости + +Нет workspace-зависимостей. Это базовый пакет, от которого зависят все остальные компоненты. diff --git a/components/factory/AGENTS.md b/components/factory/AGENTS.md new file mode 100644 index 00000000000..508283eda9b --- /dev/null +++ b/components/factory/AGENTS.md @@ -0,0 +1,83 @@ +# @coopenomics/factory + +## Назначение + +Движок генерации юридических документов кооператива. Принимает данные, валидирует их по JSON-схемам, заполняет Handlebars/Nunjucks-шаблоны, конвертирует HTML → PDF через WeasyPrint и сохраняет результат в MongoDB. + +## Структура + +``` +src/ +├── Actions/ — Фабрики документов. Каждый файл = один тип документа по registry_id +│ (например, 100.ParticipantApplication.ts — заявление на вступление) +├── Templates/ — Шаблоны документов: модель данных, переводы, контекст, описание +│ └── registry.ts — Реестр: маппинг registry_id → модуль шаблона +├── Models/ — Модели данных (Individual, Organization, Entrepreneur, Udata, +│ Vars, PaymentMethod, Cooperative, Project, Document) +├── Services/ +│ ├── Generator/ — PDFService: HTML → PDF через WeasyPrint (exec в shell) +│ ├── Validator/ — Валидация данных по JSON Schema через AJV (с русской локалью) +│ ├── Databazor/ — MongoDB-коннектор, поиск (SearchService), CRUD-операции +│ └── Templator/ — Шаблонизатор Nunjucks: рендер HTML из шаблона + переменных +├── Schema/ — JSON-схемы для валидации входных данных (Individual, Organization, и т.д.) +├── Interfaces/ — TypeScript интерфейсы (IGeneratedDocument, IGenerate, и т.д.) +├── Fonts/ — Шрифт Arial в base64 для PDF +└── index.ts — Класс Generator — главная точка входа +``` + +## Ключевые концепции + +### Система реестра (registry_id) + +Каждый документ идентифицируется числовым `registry_id`. Реестр определён в `Templates/registry.ts` и дублируется в `Actions/index.ts`. Номера сгруппированы по смыслу: +- 1–4: базовые соглашения (кошелёк, ЭЦП, приватность, пользовательское) +- 50–51: соглашение Coopenomics, конвертация +- 100–101: заявление на вступление, выбор участка +- 300–304: общее собрание (повестка, решение совета, уведомление, бюллетень, решение) +- 501, 599, 600: решения по заявлению, свободные решения +- 700–702, 800–802, 900–901: имущественные взносы, возвраты +- 994–999, 1000–1090: программы ЦПП (Генератор, Благорост), договоры, акты + +### Источник шаблонов (SOURCE) + +- `SOURCE=local` — шаблоны берутся из локальных файлов в `Templates/` +- Иначе — загружаются из MongoDB (дельты парсера, таблица `drafts` / `translations`) + +### Генерация PDF + +`PDFService` в `Services/Generator/` записывает HTML во временный файл, вызывает `weasyprint` через `child_process.exec`, читает результат. Требует установленного WeasyPrint в системе. + +### Mock-система + +- `src/Utils/testMocks.ts` — экспортирует `testMocks` (массив моков из `mocks/tables/` и `mocks/actions/`) +- `src/Utils/mocks/matchMock.ts` — сопоставление моков по фильтрам +- Используется в тестах для подмены данных из MongoDB + +## Тесты + +- Фреймворк: **Vitest** +- Путь: `test/` +- Подготовка данных: `test/utils/index.ts` — функция `preLoading()` очищает коллекции MongoDB и заполняет тестовыми данными (реестр шаблонов, переменные, пользователи, организации, платёжные методы, данные собраний) +- Требует работающий MongoDB + +### Запуск + +``` +NODE_ENV=test SOURCE=local SKIP_BLOCK_FETCH=TRUE pnpm --filter @coopenomics/factory test +``` + +Переменная `MONGO_URI` указывает на строку подключения к MongoDB. По умолчанию берётся из `.env` или строится из `MONGO_HOST`. + +## Скрипты package.json + +| Скрипт | Описание | +|--------|----------| +| `build` | Сборка через unbuild | +| `dev` | Пересборка при изменениях (nodemon + unbuild) | +| `test` | Vitest (timeout 240s, exclude `documents/`) | +| `lint` | ESLint | +| `typecheck` | TypeScript проверка (`tsc --noEmit`) | + +## Зависимости от других компонентов + +- `cooptypes` (workspace) — типы контрактов, интерфейсы документов diff --git a/components/notifications/AGENTS.md b/components/notifications/AGENTS.md new file mode 100644 index 00000000000..d1289413dbc --- /dev/null +++ b/components/notifications/AGENTS.md @@ -0,0 +1,97 @@ +# @coopenomics/notifications + +## Назначение + +Библиотека типобезопасных workflow-уведомлений для Novu. Определяет 21 workflow уведомлений (email, in-app, push), валидирует payload через Zod-схемы и синхронизирует определения с Novu API. + +## Структура + +``` +src/ +├── index.ts — Главный экспорт: Types, WorkflowBuilder, Workflows, defaults +├── base/ +│ ├── workflow-builder.ts — WorkflowBuilder — билдер для создания workflow +│ └── defaults.ts — Фабрики шагов: createEmailStep, createInAppStep, createPushStep +│ Настройки preferences по умолчанию +├── types/ +│ └── index.ts — Типы: WorkflowDefinition, WorkflowStep, PayloadSchema, +│ BaseWorkflowPayload, NovuWorkflowData, PreferencesConfig +├── workflows/ — 21 workflow, каждый в своей директории +│ ├── index.ts — Реестр: allWorkflows[], workflowsById{}, экспорт всех +│ ├── welcome/ — Приветственное уведомление +│ ├── email-verification/ — Подтверждение email +│ ├── reset-key/ — Сброс ключа +│ ├── invite/ — Приглашение +│ ├── approval-request/ — Запрос на одобрение +│ ├── approval-response/ — Ответ на запрос одобрения +│ ├── decision-approved/ — Решение одобрено +│ ├── decision-expired/ — Решение истекло +│ ├── incoming-transfer/ — Входящий перевод +│ ├── payment-paid/ — Платёж оплачен +│ ├── payment-cancelled/ — Платёж отменён +│ ├── new-initial-payment-request/ — Запрос начального платежа +│ ├── new-deposit-payment-request/ — Запрос депозита +│ ├── new-agenda-item/ — Новый пункт повестки +│ ├── meet-initial/ — Собрание создано +│ ├── meet-reminder-start/ — Напоминание о начале собрания +│ ├── meet-started/ — Собрание началось +│ ├── meet-reminder-end/ — Напоминание о завершении собрания +│ ├── meet-restart/ — Собрание перезапущено +│ ├── meet-ended/ — Собрание завершено +│ └── server-provisioned/ — Сервер создан +├── sync/ +│ ├── sync-runner.ts — CLI для синхронизации workflow с Novu API +│ │ --dev: режим watch (chokidar), production: одноразовая синхронизация +│ └── novu-sync.service.ts — NovuSyncService: upsert workflow в Novu через REST API +└── utils/ + └── slugify/ — Транслитерация русских названий → латинские slug ID +``` + +## Ключевые концепции + +### Паттерн WorkflowBuilder + +Каждый workflow создаётся через fluent-builder: +```typescript +const workflow = WorkflowBuilder + .create() + .name('Добро пожаловать') + .workflowId(slugify('Добро пожаловать')) + .description('Приветственные уведомления') + .payloadSchema(zodSchema) + .tags(['user']) + .addSteps([ + createEmailStep('step-id', 'Тема', 'Тело письма'), + createInAppStep('step-id', 'Заголовок', 'Контент'), + createPushStep('step-id', 'Заголовок', 'Тело'), + ]) + .build() +``` + +### Zod-схемы + +Каждый workflow определяет Zod-схему для payload. Схема автоматически конвертируется в JSON Schema для Novu API через `zod-to-json-schema`. + +### Синхронизация с Novu + +- `pnpm run sync` — однократная синхронизация всех workflow +- `pnpm run sync:dev` — режим разработки с watch +- Требует переменных `NOVU_API_KEY` и `NOVU_API_URL` + +### Slugify + +Названия workflow на русском языке транслитерируются в латинские slug ID через `utils/slugify/`. Это обеспечивает стабильные `workflowId` для Novu API. + +## Скрипты package.json + +| Скрипт | Описание | +|--------|----------| +| `build` | Сборка через unbuild | +| `dev` | Сборка с watch | +| `test` | Vitest | +| `sync` | Синхронизация workflow с Novu (production) | +| `sync:dev` | Синхронизация с watch (development) | + +## Зависимости + +Нет workspace-зависимостей. Используется контроллером (`controller`) для триггера уведомлений. diff --git a/components/parser/AGENTS.md b/components/parser/AGENTS.md new file mode 100644 index 00000000000..152eb56e9ae --- /dev/null +++ b/components/parser/AGENTS.md @@ -0,0 +1,100 @@ +# @coopenomics/parser + +## Назначение + +Индексатор блокчейна EOSIO через State History Plugin (SHiP). Подключается к WebSocket ноды, получает блоки, действия и дельты таблиц, сохраняет в MongoDB и публикует события в Redis Streams. Предоставляет REST API для чтения данных. + +## Структура + +``` +src/ +├── index.ts — Express-сервер (REST API) + запуск парсера +│ PORT из переменной окружения, ACTIVATE_PARSER=1 включает парсинг +├── config.ts — Конфигурация: переменные окружения (API, SHIP, MONGO, REDIS, и т.д.) +│ subscribedContracts — список контрактов для индексации +├── Reader/ +│ └── Reader.ts — loadReader() — подключение к SHiP WebSocket +│ Логика START_BLOCK: 1 → старт с HEAD + инициализация, +│ другое значение → старт с указанного блока +├── Parser/ +│ └── index.ts — Главный Parser класс, оркестрирует все парсеры +├── ActionParser/ — Парсинг действий (транзакций) блокчейна +│ ├── Parser/ — ActionParser — обработка потока действий +│ ├── Factory/ — ActionFactory — маршрутизация действий по обработчикам +│ └── Actions/ — Обработчики действий (any.any.ts — универсальный) +├── DeltaParser/ — Парсинг дельт (изменений таблиц) блокчейна +│ ├── Parser/ — DeltaParser — обработка потока дельт +│ ├── Factory/ — DeltaFactory — маршрутизация дельт по обработчикам +│ └── Deltas/ — Обработчики дельт (any.any.any.ts — универсальный) +├── BlockParser/ — Парсинг блоков (обновление текущего блока в sync) +├── ForkParser/ — Обработка форков цепочки +│ ├── Parser/, Factory/, Forks/ +├── Database/ +│ └── index.ts — MongoDB: коллекции actions, deltas, sync +│ CRUD, пагинация, агрегация по primary_key, очистка +├── Initializer/ +│ └── index.ts — initializeFromBlockchain() — при первом запуске (HEAD) +│ загружает данные кооператива и шаблоны из блокчейна в MongoDB +├── RedisNotifier/ +│ └── index.ts — Публикация событий в Redis Streams +└── Utils/ + └── Blockchain.ts — Утилиты для работы с RPC (fetchAbi, getInfo, extractTables) +``` + +## Ключевые концепции + +### Протокол SHiP (State History Plugin) + +Парсер подключается к WebSocket-эндпоинту ноды EOSIO. Библиотека `@blockmatic/eosio-ship-reader` управляет подключением и десериализацией. + +### Логика START_BLOCK + +- `START_BLOCK=1` — при первом запуске стартует с HEAD-блока и выполняет `initializeFromBlockchain()` (загрузка кооператива и шаблонов из RPC). При повторных запусках продолжает с сохранённого блока. +- `START_BLOCK=N` (N>1) — начинает парсинг с блока N (для полного replay). + +### subscribedContracts + +Список контрактов для индексации определён в `config.ts`: +`draft`, `meet`, `soviet`, `registrator`, `eosio.token`, `capital`, `wallet`, `ledger` + +Действия и таблицы этих контрактов автоматически подписываются через ABI. + +### Redis Streams + +Парсер публикует события в Redis Streams для потребления другими сервисами (controller). Конфигурация через переменные `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_STREAM_LIMIT`. + +### REST API + +- `GET /get-tables` — чтение дельт таблиц (с пагинацией и фильтрацией) +- `GET /get-actions` — чтение действий (с пагинацией и фильтрацией) +- `GET /get-current-block` — текущий обработанный блок + +## Переменные окружения + +| Переменная | Описание | +|-----------|----------| +| `API` | URL RPC-ноды блокчейна | +| `SHIP` | WebSocket URL ноды (SHiP) | +| `MONGO_EXPLORER_URI` | Строка подключения к MongoDB | +| `START_BLOCK` | Начальный блок (1 = с HEAD) | +| `FINISH_BLOCK` | Конечный блок (макс. значение = бесконечно) | +| `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` | Подключение к Redis | +| `REDIS_STREAM_LIMIT` | Лимит длины Redis-стрима | +| `ACTIVATE_PARSER` | 1 = включить парсинг при старте | +| `COOPNAME` | Имя кооператива (для инициализации) | +| `NODE_ENV` | test — добавляет суффикс `-test` к имени БД | +| `PORT` | Порт Express-сервера (по умолчанию 4000) | + +## Скрипты package.json + +| Скрипт | Описание | +|--------|----------| +| `dev` | Запуск с nodemon (hot-reload) | +| `build` | Сборка через unbuild | +| `lint` | ESLint | +| `test` | Vitest | +| `typecheck` | TypeScript проверка | + +## Зависимости от других компонентов + +- `cooptypes` (workspace) — имена контрактов, таблиц diff --git a/components/sdk/AGENTS.md b/components/sdk/AGENTS.md new file mode 100644 index 00000000000..003d3dd262e --- /dev/null +++ b/components/sdk/AGENTS.md @@ -0,0 +1,109 @@ +# @coopenomics/sdk + +## Назначение + +TypeScript SDK для работы с GraphQL API кооператива. Предоставляет типобезопасный клиент с поддержкой запросов, мутаций, подписок, а также вспомогательные классы для работы с блокчейном, документами и криптографией. + +## Структура + +``` +src/ +├── index.ts — Класс Client — главная точка входа. +│ Client.create() / Client.New(), login(), Query, Mutation, Subscription +├── classes/ — Вспомогательные классы +│ ├── account.ts — Account — работа с аккаунтами +│ ├── blockchain.ts — Blockchain — взаимодействие с EOSIO через @wharfkit/session +│ ├── document.ts — Document — подписание документов (WIF) +│ ├── crypto.ts — Crypto — криптографические утилиты +│ ├── vote.ts — Vote — подписание голосований +│ └── canvas.ts — Canvas — генерация на canvas +├── mutations/ — GraphQL мутации, сгруппированные по доменам +│ ├── accounts/ — Управление аккаунтами +│ ├── auth/ — Аутентификация (login, refresh, logout) +│ ├── branches/ — Кооперативные участки +│ ├── capital/ — Программы ЦПП (инвестирование, проекты) +│ ├── documents/ — Работа с документами +│ ├── extensions/ — Расширения +│ ├── gateway/ — Платёжный шлюз +│ ├── meet/ — Общие собрания +│ ├── notification/ — Уведомления +│ ├── participants/ — Пайщики +│ ├── paymentMethods/ — Платёжные методы +│ ├── registration/ — Регистрация +│ ├── system/ — Системные операции +│ ├── wallet/ — Кошелёк +│ └── ... +├── queries/ — GraphQL запросы, сгруппированные по доменам +│ ├── accounts/, agenda/, agreements/, blockchain-explorer/ +│ ├── branches/, capital/, desktop/, documents/ +│ ├── extensions/, gateway/, ledger/, meet/ +│ ├── notification/, onecoop/, paymentMethods/ +│ ├── registration/, system/, wallet/ +│ └── ... +├── selectors/ — GraphQL Zeus селекторы — типобезопасные объекты выборки полей +│ ├── capital/, common/, desktop/, documents/ +│ ├── extensions/, gateway/, ledger/, meet/ +│ ├── notification/, participants/, registration/ +│ ├── system/, wallet/, branches/, agreements/ +│ └── ... +├── zeus/ — Авто-сгенерированные GraphQL типы (Zeus codegen) +│ ├── index.ts — Thunder, Subscription, ZeusScalars, типы +│ └── const.ts — Константы +├── types/ — TypeScript типы (client, controller, document, blockchain) +└── utils/ — Утилиты (paginationSelector, validateSelector, MakeAllFieldsRequired) +``` + +## Ключевые концепции + +### Zeus Type System + +SDK использует **GraphQL Zeus** — генератор типов, дающий полную типобезопасность без рукописных типов. Типы в `zeus/` генерируются из GraphQL-схемы контроллера. + +### Паттерн Selector + +Селекторы (`selectors/`) определяют, какие поля запрашивать из GraphQL. Каждый селектор: +1. Определяет `raw*Selector` — объект с `true` для каждого поля +2. Валидирует через `MakeAllFieldsRequired` +3. Экспортирует финальный селектор через `Selector('TypeName')(rawSelector)` +4. Экспортирует тип модели: `ModelTypes['TypeName']` + +### Client + +```typescript +const client = Client.create({ api_url: '...', wif: '...', username: '...' }) +await client.login(email, wif) + +// Запросы и мутации через Zeus с полной типизацией +const result = await client.Query({ ... }) +await client.Mutation({ ... }) +``` + +Доступ к подсистемам: `client.Blockchain`, `client.Document`, `client.Crypto`, `client.Vote`, `client.Account`. + +### Мутации и запросы + +Каждая мутация/запрос экспортирует: +- `name` — имя операции +- `mutation` / `query` — Zeus selector +- `IInput` — интерфейс входных данных +- `IOutput` — интерфейс результата (опционально) + +## Скрипты package.json + +| Скрипт | Описание | +|--------|----------| +| `build` | Сборка через unbuild (с предварительной проверкой типов) | +| `dev` | Stub-режим unbuild | +| `test` | Vitest (timeout 60s) | +| `lint` | ESLint | +| `typecheck` | TypeScript проверка | +| `docs` | Генерация документации (typedoc) | + +## Зависимости от других компонентов + +- `cooptypes` (workspace) — общие типы +- Зависит от GraphQL-схемы `controller` (для генерации Zeus типов) + +## Правила работы с Zeus (подробности) + +См. файл `.cursor/rules/sdk.mdc` — детальное руководство по созданию селекторов, валидации типов и структуре запросов/мутаций.