C9S/mono
3
0
Fork 0
Code Issues 2 Pull Requests 11 Actions Packages Projects 3 Releases Wiki Activity

docs: добавлены AGENTS.md для 6 компонентов (factory, boot, parser, sdk, cooptypes, notifications)

Browse Source 
Co-authored-by: Alex Ant <dacom-dark-sun@users.noreply.github.com>
This commit is contained in:
Cursor Agent
2026-02-25 19:02:40 +00:00
parent 804cfc8b72
commit 5043995d14
6 changed files with 589 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/boot/AGENTS.md
+102
View File
@@ -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
components/cooptypes/AGENTS.md
+98
View File
@@ -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
│ │ └── <id>.<Name>/ — Каждая директория = один шаблон
│ │ ├── 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-зависимостей. Это базовый пакет, от которого зависят все остальные компоненты.
components/factory/AGENTS.md
+83
View File
@@ -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) — типы контрактов, интерфейсы документов
components/notifications/AGENTS.md
+97
View File
@@ -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<T> — билдер для создания 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<IWorkflow>()
.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`) для триггера уведомлений.
components/parser/AGENTS.md
+100
View File
@@ -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) — имена контрактов, таблиц
components/sdk/AGENTS.md
+109
View File
@@ -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<ValueTypes['TypeName']>`
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` — детальное руководство по созданию селекторов, валидации типов и структуре запросов/мутаций.