npm - @coopenomics/docs-factory - Versions diffs - 1.0.0 → 1.1.0 - Mend

@coopenomics/docs-factory 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,117 +1,90 @@
-# 📄 @coopenomics/factory
-Фабрика документов кооператива — библиотека для генерации юридически значимых документов (PDF). Объединяет шаблоны из блокчейна, приватные данные из хранилища и рендерит HTML через Handlebars/Nunjucks с последующей генерацией PDF через WeasyPrint.
-## Основные возможности
-- Более 60 шаблонов юридических документов (заявления, протоколы, решения, договоры, акты)
-- Рендеринг HTML из шаблонов Handlebars и Nunjucks
-- Генерация PDF через WeasyPrint
-- Валидация данных по JSON Schema
-- Электронная подпись документов через EOSIO-ключи
-- Хранение документов и метаданных в MongoDB
-- Сборка как ES-модуль и CommonJS (unbuild)
+# @coopenomics/docs-factory
+Фабрика документов цифрового кооператива. Собирает юридически значимые документы
+по шаблонам из цепи и данным пайщиков: модель документа → HTML (Nunjucks) → PDF
+(WeasyPrint 67). Хэш документа — SHA-256 PDF; повторная сборка по метаданным даёт
+тот же документ байт в байт.
+Пакет вынесен из монорепозитория `C9S/mono` 29.10.2026 (шаг 6а фабрики v2).
+Прежнее имя `@coopenomics/factory` устарело.
+## Что внутри
+- **Сборщики всех видов документов** цифрового кооператива — 92 вида (`src/Actions`).
+  Сборщик — объявление: какие данные прочитать на блок документа и как собрать
+  из них модель (`defineBuilder`, `src/Builder`).
+- **Версии сборщиков** `major.minor`. Версия пишется в `meta.builder` нового
+  документа; пересборка идёт ровно той версией, что записана в мете. Все версии
+  вида документа — в одном файле: `Factory` (1.0) и дописанные в конец
+  `Factory_1_1`, `Factory_2_0`. Выпущенная версия заморожена: исправление —
+  новый `minor` в конце файла.
+- **Шаблоны и реестр шаблонов** (`src/Templates`) с номерами редакций; ключ
+  `x-builder` в схеме редакции объявляет, под какой `major` сборщика она написана.
+- **Порт хранилища** `IFactoryStorage` и реализации: PostgreSQL
+  (`PostgresFactoryStorage`, Kysely) и память (`MemoryFactoryStorage`).
+- **Порт данных цепи** `IChainDataSource`: шаблоны, таблицы и действия на блок.
 ## Установка
-Компонент является частью монорепозитория. Установка зависимостей из корня проекта:
 ```bash
-pnpm install
+pnpm add @coopenomics/docs-factory cooptypes
 ```
-Или только для этого компонента:
-```bash
-pnpm install --filter @coopenomics/factory
-```
+`cooptypes` — зависимость приложения (`peerDependencies`): фабрика берёт тот
+выпуск, что стоит у приложения.
-### Системные зависимости
+Для PDF нужен WeasyPrint 67 в `/venv/bin/python3` и системный шрифт Arial —
+как в образе контроллера (`components/controller/Dockerfile` в `C9S/mono`).
-Для генерации PDF необходим [WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation).
+## Использование
-## Скрипты
+```ts
+import { Generator, PostgresFactoryStorage } from '@coopenomics/docs-factory'
-| Скрипт | Команда | Описание |
-|--------|---------|----------|
-| `build` | `pnpm run build` | Сборка библиотеки (unbuild) |
-| `dev` | `pnpm run dev` | Режим разработки с автопересборкой (nodemon) |
-| `test` | `pnpm run test` | Запуск тестов (Vitest) |
-| `lint` | `pnpm run lint` | Проверка кода (ESLint) |
-| `typecheck` | `pnpm run typecheck` | Проверка типов TypeScript |
-| `setup-indexes` | `pnpm run setup-indexes` | Настройка индексов MongoDB |
+const generator = new Generator(chainDataSource) // реализация IChainDataSource
+await generator.connect(new PostgresFactoryStorage({ host, port, user, password, database }))
-Из корня монорепозитория:
+// Новая сборка: версия сборщика — по объявлению действующей редакции шаблона
+const document = await generator.generate({ registry_id: 1, coopname: 'voskhod', username: 'ant', lang: 'ru' })
-```bash
-pnpm run build:lib       # Сборка factory + cooptypes
-pnpm run dev:lib         # Режим разработки factory + cooptypes
-pnpm run test:component  # Компонентные тесты factory
+// Пересборка по метаданным подписанного документа — тем же сборщиком
+const same = await generator.generate({ ...document.meta }, { skip_save: true })
 ```
-## Конфигурация
+Таблицы хранилища на узле создаёт миграция контроллера; отдельному приложению —
+`await storage.ensureSchema()`.
-Хранилище фабрики — порт `IFactoryStorage`; реализации — PostgreSQL (`PostgresFactoryStorage`) и память. Для набора тестов нужен PostgreSQL. Переменные окружения:
+## Разработка
-- `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USERNAME`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE` — база набора тестов
-- `SOURCE` — источник данных (`local` для тестов)
+Тесты и эталоны запускаются только в CI (workflow `Factory`, `.github/workflows/factory.yml`)
+на каждый пуш. Локально — сборка и проверки сборщиков:
-Подробное описание переменных — в файле `.env-example`.
+| Команда | Что делает |
+|---|---|
+| `pnpm build` | сборка (unbuild) с проверкой типов |
+| `pnpm lint` | ESLint |
+| `pnpm check` | полнота экспорта сборщиков, чтения на блок, заморозка версий |
+| `node scripts/x-builder-check.mjs` | `x-builder` не меняется внутри редакции (после `pnpm build`) |
+| `node scripts/golden-coverage.mjs` | у каждого вида документа есть эталон |
-## Тестирование
+Эталоны — `test/golden/<номер>/<случай>.{html,meta.json,pdf.sha256}`. Пересоздать —
+пуш в ветку `ci/update`, забрать артефакт `factory-golden`, закоммитить; только
+при осознанной смене вывода. Правила для сборщиков — `CLAUDE.md`.
-```bash
-SOURCE=local NODE_ENV=test pnpm --filter @coopenomics/factory run test
-```
-Тестовый набор покрывает генерацию документов различных типов. Тесты требуют запущенный MongoDB и используют таймаут 240 секунд.
-Файлы тестов:
+Совместная правка с монорепозиторием: в `C9S/mono` — `pnpm factory:link`
+(подключает этот чекаут, ожидается в `~/docs-factory`) и `pnpm factory:unlink`.
-| Файл | Описание |
-|------|----------|
-| `test/index.test.ts` | Основные тесты генерации документов |
-| `test/wallet.test.ts` | Тесты документов кошелька |
-| `test/meet.test.ts` | Тесты документов собраний |
-| `test/blagorost.test.ts` | Тесты документов программы «Благорост» |
-| `test/market.test.ts` | Тесты документов маркетплейса |
-| `test/search.test.ts` | Тесты поиска документов |
-| `test/udata.test.ts` | Тесты пользовательских данных |
-| `test/documents-1000-plus.test.ts` | Тесты документов с registry_id > 1000 |
+## Выпуск
-## Архитектура
+1. Поднять `version` в `package.json` (семантическая версия), коммит в `main`.
+2. Тег `vX.Y.Z` (предварительный — `vX.Y.Z-dev.N`) в `C9S/docs-factory`.
+3. Workflow `Release`: проверки Factory → сверка тега с версией → публикация в npm
+   (предварительная — с меткой `next`) → робот открывает PR в `C9S/mono` → `dev`
+   с новой точной версией во всех `package.json` и `pnpm-lock.yaml`.
-```
-src/
-├── index.ts               # Точка входа библиотеки
-├── config.ts              # Конфигурация подключений
-├── Actions/               # Генераторы документов (по registry_id)
-│   ├── 1.WalletAgreement.ts
-│   ├── 100.ParticipantApplication.ts
-│   ├── 300.AnnualGeneralMeetingAgenda.ts
-│   ├── 600.FreeDecision.ts
-│   ├── 1001.GenerationContract.ts
-│   └── ...                # Более 60 шаблонов
-├── Factory/               # Ядро фабрики документов
-├── Models/                # Модели данных MongoDB
-│   ├── Cooperative.ts
-│   ├── Individual.ts
-│   ├── Organization.ts
-│   ├── Document.ts
-│   └── ...
-└── templates/             # HTML-шаблоны (Nunjucks/Handlebars)
-test/                      # Тесты (Vitest)
-```
-### Процесс генерации документа
-1. Загрузка шаблона и JSON Schema из блокчейна
-2. Получение приватных данных из хранилища (MongoDB)
-3. Валидация данных по JSON Schema (Ajv)
-4. Конструирование контекста для шаблона
-5. Рендеринг HTML из Nunjucks/Handlebars-шаблона
-6. Подпись хеша документа EOSIO-ключом
-7. Генерация PDF через WeasyPrint
+Монорепозиторий поднимает версию только этим PR: гейт `pnpm check` держит
+точную и одну версию, контроллер при старте сверяет установленную фабрику с
+объявленной.
 ## Приватные данные документа: `doc_data`
@@ -121,7 +94,7 @@ test/                      # Тесты (Vitest)
 1. Контроллер собирает приватный payload и вызывает `generator.saveDocData(payload, registry_id)` — возвращается `{ hash }` (sha256, идемпотентный).
 2. `hash` передаётся on-chain в Action под зарезервированным именем `doc_data_hash`.
-3. При генерации/регенерации фабрика подгружает payload из `doc_private_data` через `generator.getDocData(hash)` и подставляет в `combinedData.doc_data`.
+3. При сборке и пересборке фабрика подгружает payload из хранилища (`getDocData(hash)`) и подставляет в модель документа как `doc_data`.
 4. Шаблон документа использует приватные поля как `{{ doc_data.<field> }}`.
 ### Пример
@@ -146,14 +119,17 @@ await generator.generate({
 })
 ```
-Фабрика (`src/Actions/1103.MarketplaceTransportNote.ts`):
+Сборщик (`src/Actions/1103.MarketplaceTransportNote.ts`) объявляет чтение, каркас его выполняет:
 ```ts
-const doc_data = await this.loadDocData<TransportNoteDocData>(data)
-const combinedData = { ...base, doc_data }
+reads: ({ data, f }) => ({
+  docData: () => f.loadDocData<TransportNoteDocData>(data),
+  // …
+}),
+assemble: ({ meta, reads: { docData } }) => ({ meta, doc_data: docData, /* … */ }),
 ```
-Шаблон (`Templates/1103.MarketplaceTransportNote/index.ts`):
+Шаблон (`src/Templates/1103.MarketplaceTransportNote.ts`):
 ```html
 <tr><th>Экспедитор</th><td>{{ doc_data.expeditor_full_name }}</td></tr>
@@ -174,22 +150,13 @@ const combinedData = { ...base, doc_data }
 ### Graceful degradation
-Если запись в `doc_private_data` удалена (например, по запросу пайщика), документ остаётся **верифицируемым по хэшу подписи** (хэш зафиксирован on-chain), но не регенерируется. Это явное архитектурное решение: ценность блокчейн-подписи сохраняется; восстановление PDF — обратимо deprecated.
+Если приватные данные удалены (например, по запросу пайщика), документ остаётся **верифицируемым по хэшу подписи** (хэш зафиксирован on-chain), но не регенерируется. Это явное архитектурное решение: ценность блокчейн-подписи сохраняется; восстановление PDF — обратимо deprecated.
 ### Когда применять
 - **Новые документы** с персональными данными — сразу через `doc_data`.
 - **Существующие документы** (700-1099, 300-304 и т.д.) — остаются без изменений. Паттерн прогрессивный, переводить старые документы при отсутствии необходимости не нужно.
-## Ключевые зависимости
-- **nunjucks / handlebars** — шаблонизаторы
-- **ajv** — валидация JSON Schema
-- **mongodb** — хранилище данных
-- **eosjs-ecc** — криптографические операции EOSIO
-- **pdf-lib** — работа с PDF
-- **unbuild** — сборка библиотеки
 ## Лицензия
 [BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru)

package/dist/index.cjs CHANGED Viewed

@@ -5045,7 +5045,7 @@ function latestMinorOf(versions, major) {
 const name = "@coopenomics/docs-factory";
 const type = "module";
-const version = "1.0.0";
+const version = "1.1.0";
 const description = "Фабрика документов цифрового кооператива: сборка документов по шаблонам, сборщики всех видов документов, версии сборщиков";
 const author = "Alex Ant <chairman.voskhod@gmail.com>";
 const license = "MIT";
@@ -9984,12 +9984,16 @@ const Actions = {
   WalletAgreement: _1_WalletAgreement
 };
+const BUILDER_EXPORT = /^Factory(_\d+_\d+)?$/;
 function isBuilderModule(value) {
   if (!value || typeof value !== "object")
     return false;
   const m = value;
   return typeof m.Factory === "function" && typeof m.Template?.registry_id === "number";
 }
+function builderExports(module) {
+  return Object.entries(module).filter(([key, value]) => BUILDER_EXPORT.test(key) && typeof value === "function");
+}
 function buildFactories(modules, storage) {
   const builders = {};
   const problems = [];
@@ -9999,21 +10003,27 @@ function buildFactories(modules, storage) {
       continue;
     }
     const id = module.Template.registry_id;
-    const factory = new module.Factory(storage);
-    const spec = factory.spec;
-    if (spec?.registry_id !== void 0 && spec.registry_id !== id)
-      problems.push(`${name}: \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0438\u0435 \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${spec.registry_id} \u043D\u0435 \u0441\u043E\u0432\u043F\u0430\u0434\u0430\u0435\u0442 \u0441 \u043D\u043E\u043C\u0435\u0440\u043E\u043C \u0448\u0430\u0431\u043B\u043E\u043D\u0430 ${id}`);
-    const version = spec?.version ?? FIRST_BUILDER_VERSION;
-    if (!isBuilderVersion(version)) {
-      problems.push(`${name}: \u0432\u0435\u0440\u0441\u0438\u044F \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${JSON.stringify(version)} \u043D\u0435 \u0432 \u0432\u0438\u0434\u0435 major.minor`);
-      continue;
-    }
-    const set = builders[id] ?? (builders[id] = /* @__PURE__ */ new Map());
-    if (set.has(version)) {
-      problems.push(`${name}: \u0432\u0435\u0440\u0441\u0438\u044F ${version} \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${id} \u0443\u0436\u0435 \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0430 \u0434\u0440\u0443\u0433\u0438\u043C \u043C\u043E\u0434\u0443\u043B\u0435\u043C`);
-      continue;
+    for (const [exportName, Builder] of builderExports(module)) {
+      const where = `${name}.${exportName}`;
+      const factory = new Builder(storage);
+      const spec = factory.spec;
+      if (spec?.registry_id !== void 0 && spec.registry_id !== id)
+        problems.push(`${where}: \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0438\u0435 \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${spec.registry_id} \u043D\u0435 \u0441\u043E\u0432\u043F\u0430\u0434\u0430\u0435\u0442 \u0441 \u043D\u043E\u043C\u0435\u0440\u043E\u043C \u0448\u0430\u0431\u043B\u043E\u043D\u0430 ${id}`);
+      const version = spec?.version ?? FIRST_BUILDER_VERSION;
+      if (!isBuilderVersion(version)) {
+        problems.push(`${where}: \u0432\u0435\u0440\u0441\u0438\u044F \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${JSON.stringify(version)} \u043D\u0435 \u0432 \u0432\u0438\u0434\u0435 major.minor`);
+        continue;
+      }
+      const expected = exportName === "Factory" ? FIRST_BUILDER_VERSION : exportName.slice("Factory_".length).replace("_", ".");
+      if (version !== expected)
+        problems.push(`${where}: \u044D\u043A\u0441\u043F\u043E\u0440\u0442 ${exportName} \u043E\u0431\u044A\u044F\u0432\u043B\u044F\u0435\u0442 \u0432\u0435\u0440\u0441\u0438\u044E ${version}, \u043F\u043E \u0438\u043C\u0435\u043D\u0438 \u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F ${expected}`);
+      const set = builders[id] ?? (builders[id] = /* @__PURE__ */ new Map());
+      if (set.has(version)) {
+        problems.push(`${where}: \u0432\u0435\u0440\u0441\u0438\u044F ${version} \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${id} \u0443\u0436\u0435 \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0430`);
+        continue;
+      }
+      set.set(version, factory);
     }
-    set.set(version, factory);
   }
   const templateIds = Object.keys(Registry).map(Number);
   for (const id of templateIds) {

package/dist/index.mjs CHANGED Viewed

@@ -5030,7 +5030,7 @@ function latestMinorOf(versions, major) {
 const name = "@coopenomics/docs-factory";
 const type = "module";
-const version = "1.0.0";
+const version = "1.1.0";
 const description = "Фабрика документов цифрового кооператива: сборка документов по шаблонам, сборщики всех видов документов, версии сборщиков";
 const author = "Alex Ant <chairman.voskhod@gmail.com>";
 const license = "MIT";
@@ -9969,12 +9969,16 @@ const Actions = {
   WalletAgreement: _1_WalletAgreement
 };
+const BUILDER_EXPORT = /^Factory(_\d+_\d+)?$/;
 function isBuilderModule(value) {
   if (!value || typeof value !== "object")
     return false;
   const m = value;
   return typeof m.Factory === "function" && typeof m.Template?.registry_id === "number";
 }
+function builderExports(module) {
+  return Object.entries(module).filter(([key, value]) => BUILDER_EXPORT.test(key) && typeof value === "function");
+}
 function buildFactories(modules, storage) {
   const builders = {};
   const problems = [];
@@ -9984,21 +9988,27 @@ function buildFactories(modules, storage) {
       continue;
     }
     const id = module.Template.registry_id;
-    const factory = new module.Factory(storage);
-    const spec = factory.spec;
-    if (spec?.registry_id !== void 0 && spec.registry_id !== id)
-      problems.push(`${name}: \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0438\u0435 \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${spec.registry_id} \u043D\u0435 \u0441\u043E\u0432\u043F\u0430\u0434\u0430\u0435\u0442 \u0441 \u043D\u043E\u043C\u0435\u0440\u043E\u043C \u0448\u0430\u0431\u043B\u043E\u043D\u0430 ${id}`);
-    const version = spec?.version ?? FIRST_BUILDER_VERSION;
-    if (!isBuilderVersion(version)) {
-      problems.push(`${name}: \u0432\u0435\u0440\u0441\u0438\u044F \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${JSON.stringify(version)} \u043D\u0435 \u0432 \u0432\u0438\u0434\u0435 major.minor`);
-      continue;
-    }
-    const set = builders[id] ?? (builders[id] = /* @__PURE__ */ new Map());
-    if (set.has(version)) {
-      problems.push(`${name}: \u0432\u0435\u0440\u0441\u0438\u044F ${version} \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${id} \u0443\u0436\u0435 \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0430 \u0434\u0440\u0443\u0433\u0438\u043C \u043C\u043E\u0434\u0443\u043B\u0435\u043C`);
-      continue;
+    for (const [exportName, Builder] of builderExports(module)) {
+      const where = `${name}.${exportName}`;
+      const factory = new Builder(storage);
+      const spec = factory.spec;
+      if (spec?.registry_id !== void 0 && spec.registry_id !== id)
+        problems.push(`${where}: \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0438\u0435 \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${spec.registry_id} \u043D\u0435 \u0441\u043E\u0432\u043F\u0430\u0434\u0430\u0435\u0442 \u0441 \u043D\u043E\u043C\u0435\u0440\u043E\u043C \u0448\u0430\u0431\u043B\u043E\u043D\u0430 ${id}`);
+      const version = spec?.version ?? FIRST_BUILDER_VERSION;
+      if (!isBuilderVersion(version)) {
+        problems.push(`${where}: \u0432\u0435\u0440\u0441\u0438\u044F \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${JSON.stringify(version)} \u043D\u0435 \u0432 \u0432\u0438\u0434\u0435 major.minor`);
+        continue;
+      }
+      const expected = exportName === "Factory" ? FIRST_BUILDER_VERSION : exportName.slice("Factory_".length).replace("_", ".");
+      if (version !== expected)
+        problems.push(`${where}: \u044D\u043A\u0441\u043F\u043E\u0440\u0442 ${exportName} \u043E\u0431\u044A\u044F\u0432\u043B\u044F\u0435\u0442 \u0432\u0435\u0440\u0441\u0438\u044E ${version}, \u043F\u043E \u0438\u043C\u0435\u043D\u0438 \u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F ${expected}`);
+      const set = builders[id] ?? (builders[id] = /* @__PURE__ */ new Map());
+      if (set.has(version)) {
+        problems.push(`${where}: \u0432\u0435\u0440\u0441\u0438\u044F ${version} \u0441\u0431\u043E\u0440\u0449\u0438\u043A\u0430 ${id} \u0443\u0436\u0435 \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D\u0430`);
+        continue;
+      }
+      set.set(version, factory);
     }
-    set.set(version, factory);
   }
   const templateIds = Object.keys(Registry).map(Number);
   for (const id of templateIds) {

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@coopenomics/docs-factory",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Фабрика документов цифрового кооператива: сборка документов по шаблонам, сборщики всех видов документов, версии сборщиков",
   "author": "Alex Ant <chairman.voskhod@gmail.com>",
   "license": "MIT",