@haiiro/docuflow 0.0.4 → 0.0.5

package/bin/install.mjs

@@ -13,9 +13,9 @@ import { fileURLToPath } from 'node:url';
 
 const REGISTRY_URL = 'https://registry.npmjs.org';
 
-const packageJson = JSON.parse(
-  await readFile(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
-);
+const packageDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(await readFile(join(packageDir, 'package.json'), 'utf8'));
+const manifest = JSON.parse(await readFile(join(packageDir, 'manifest.json'), 'utf8'));
 
 const fail = (message) => {
   console.error(`\n✗ ${message}\n`);
@@ -78,14 +78,60 @@ const callMetadataApi = async ({ url, apiKey }, query, variables) => {
   }
 
   if (firstError !== undefined || body?.data === undefined) {
-    const details = firstError?.extensions?.userFriendlyMessage ?? firstError?.message ?? `HTTP ${response.status}`;
-
-    throw new Error(typeof details === 'string' ? details : JSON.stringify(details));
+    throw new CrmApiError(firstError, response.status);
   }
 
   return body.data;
 };
 
+class CrmApiError extends Error {
+  constructor(graphqlError, status) {
+    const details =
+      graphqlError?.extensions?.userFriendlyMessage ?? graphqlError?.message ?? `HTTP ${status}`;
+
+    super(typeof details === 'string' ? details : JSON.stringify(details));
+    this.extensions = graphqlError?.extensions ?? {};
+    this.rawMessage = graphqlError?.message ?? '';
+  }
+
+  // The app was installed from the marketplace on this CRM: the server keeps
+  // it tied to npm and refuses an archive for it.
+  get isSourceChannelMismatch() {
+    return (
+      [this.extensions.code, this.extensions.subCode].includes('SOURCE_CHANNEL_MISMATCH') ||
+      /source channel|Cannot upload tarball/i.test(`${this.message} ${this.rawMessage}`)
+    );
+  }
+
+  // Manifest validation lists what is wrong per entity; the platform CLI
+  // prints it the same way.
+  describe() {
+    const lines = [this.message];
+    const { errors } = this.extensions;
+
+    if (this.rawMessage !== '' && this.rawMessage !== this.message) {
+      lines.push(this.rawMessage);
+    }
+
+    if (errors !== null && typeof errors === 'object') {
+      for (const [metadataName, entries] of Object.entries(errors)) {
+        for (const entry of entries ?? []) {
+          const entity = entry.flatEntityMinimalInformation ?? {};
+          const name = entity.name ?? entity.label ?? entity.universalIdentifier ?? '';
+
+          for (const entryError of entry.errors ?? []) {
+            const value = entryError.value !== undefined ? ` (значение: ${JSON.stringify(entryError.value)})` : '';
+
+            lines.push(`  ${metadataName} ${name}: ${entryError.code} — ${entryError.message}${value}`);
+          }
+        }
+      }
+    }
+
+    return lines.join('\n');
+  }
+}
+
 const downloadPackageTarball = async (version) => {
   const metadataResponse = await fetch(`${REGISTRY_URL}/${packageJson.name}/${version}`);
 
@@ -111,6 +157,32 @@ const install = async (options) => {
   const tarball = await downloadPackageTarball(options.version);
 
   console.log(`→ Загружаю в CRM ${connection.url} (${(tarball.length / 1e6).toFixed(1)} МБ)`);
+
+  try {
+    await uploadArchive(connection, label, tarball);
+  } catch (error) {
+    if (!(error instanceof CrmApiError) || !error.isSourceChannelMismatch) {
+      throw error;
+    }
+
+    // Installed from the marketplace before: the server fetches the same
+    // version from npm itself.
+    console.log('→ Приложение подключено из каталога npm, ставлю эту версию через каталог');
+  }
+
+  console.log(`→ Устанавливаю «${manifest.application.displayName ?? packageJson.name}» ${options.version}`);
+  await callMetadataApi(
+    connection,
+    `mutation InstallApplication($universalIdentifier: String!, $version: String) {
+      installApplication(universalIdentifier: $universalIdentifier, version: $version) { id }
+    }`,
+    { universalIdentifier: manifest.application.universalIdentifier, version: options.version },
+  );
+
+  console.log(`\n✓ ${label} установлен. Обновите страницу CRM.\n`);
+};
+
+const uploadArchive = async (connection, label, tarball) => {
   const { createFileUpload } = await callMetadataApi(
     connection,
     `mutation CreateFileUpload($filename: String!, $size: Float!, $fileFolder: FileFolder!) {
@@ -129,24 +201,13 @@ const install = async (options) => {
     fail(`Хранилище файлов CRM не приняло архив (HTTP ${uploadResponse.status})`);
   }
 
-  const { completeAppTarballUpload } = await callMetadataApi(
+  await callMetadataApi(
     connection,
     `mutation CompleteAppTarballUpload($fileId: UUID!) {
-      completeAppTarballUpload(fileId: $fileId) { id universalIdentifier name }
+      completeAppTarballUpload(fileId: $fileId) { id }
     }`,
     { fileId: createFileUpload.fileId },
   );
-
-  console.log(`→ Устанавливаю «${completeAppTarballUpload.name}»`);
-  await callMetadataApi(
-    connection,
-    `mutation InstallApplication($universalIdentifier: String!) {
-      installApplication(universalIdentifier: $universalIdentifier) { id }
-    }`,
-    { universalIdentifier: completeAppTarballUpload.universalIdentifier },
-  );
-
-  console.log(`\n✓ ${label} установлен. Обновите страницу CRM.\n`);
 };
 
 const options = readOptions(process.argv.slice(2));
@@ -156,4 +217,10 @@ if (options.help || options.url === undefined || options.apiKey === undefined) {
   process.exit(options.help ? 0 : 1);
 }
 
-await install(options).catch((error) => fail(`Установка не прошла: ${error.message}`));
+if (options.apiKey.startsWith('npm_')) {
+  fail('Это токен npm, а нужен ключ API самой CRM: «Настройки → API и вебхуки → Создать ключ»');
+}
+
+await install(options).catch((error) =>
+  fail(`Установка не прошла: ${error instanceof CrmApiError ? error.describe() : error.message}`),
+);

package/manifest.json

@@ -49,7 +49,7 @@
     "defaultRoleUniversalIdentifier": "26b1dde8-4ed9-4f39-8516-e0dcb734ea5a",
     "aboutDescription": "# Документооборот (`@crm-nordiv/docuflow`)\n\nЗадания, процессы и документы компании в одном разделе. Ставится в CRM как приложение, без правок\nсервера.\n\n- universalIdentifier: `0b7d5d2e-8c4f-4a59-9a43-2f6f1c3e9d21`\n\n## Что получается после установки\n\n| Где | Что |\n|---|---|\n| Сайдбар | пункт «Документооборот» с вкладками «Задания», «Процессы», «Документы» |\n| «Задания» | задачи раздела «Документооборот»; фильтры «Открытые / Мои / Просроченные / Выполненные», поиск, создание задания с инструкцией и полями для заполнения |\n| Карточка задачи | вкладка «Задание»: инструкция, поля задания (собрать конструктором, заполнить), «Выполнить» |\n| Карточка процесса | вкладка «Запуск и задания»: параметры запуска (конструктор полей) и, для шагов «Человеческий ввод» черновика, кто выполняет, срок в днях, обязательные поля; у каждого поля видна переменная, которой его читают следующие шаги |\n| Редактор процесса | шаг «Запуск с параметрами» (из приложения): отдаёт следующим шагам параметры, заполненные перед запуском |\n| «Процессы» | процессы с ручным запуском раздела «Документооборот»; форма параметров до запуска, «Запустить», «Создать», «Изменить процесс» |\n| «Документы» | папки, фильтры, поиск по названию и номеру, документ с реквизитами (тип, номер, дата, срок действия, контрагент, описание), файл в поле «Файл» карточки, карточка с источником |\n| Автоматически | шаг «Человеческий ввод» процесса становится задачей; её выполнение продолжает процесс; файл, приложенный к любой записи, копируется в документы с отметкой, кто, когда и куда его добавил |\n| Битрикс24 | страница приложения в портале со списком открытых заданий сотрудника и ссылками в CRM; уведомление исполнителю нового задания |\n\n## Данные\n\n| Объект | Поля |\n|---|---|\n| `smbDocument` (новый) | название, файл, тип, номер, дата, действует до, контрагент (компания), описание, статус, автор, ответственный, папка; источник: `origin`, `sourceObjectName`, `sourceRecordId`, `sourceRecordName`, `sourceFileId`, `workflowRunId` |\n| `smbDocumentFolder` (новый) | название, цвет, родительская папка |\n| `workflow` | `smbSection` «Раздел»: CRM / Документооборот; `smbLaunchFields` «Параметры запуска» — поля, которые заполняют перед запуском |\n| `task` | `smbSection`, `smbInstruction` «Инструкция»; `smbFormSchema`, `smbFormValues` — поля задания; `smbWorkflowRunId`, `smbWorkflowStepId`, `smbWorkflowThreadId` — связь с шагом процесса |\n| `company` | `smbDocuments` — документы контрагента |\n| роли | «Документооборот: функции приложения» (права функций), «Документооборот: участник процессов» (для людей, см. ниже) |\n\n## Установка\n\nОдна команда, на любой CRM; повторный запуск с новой версией пакета обновляет приложение:\n\n```bash\nnpx @haiiro/docuflow install --url https://crm.example.ru --api-key '<ключ API>'\n```\n\nНужно: Node.js 20+ на машине, откуда запускается команда, и ключ API администратора\n(«Настройки → API и вебхуки»). Команда скачивает эту версию пакета из npm, загружает её в CRM\nархивом приложения и устанавливает. Каталог приложений CRM для этого не нужен, поэтому\nрезультат одинаков на любом сервере, в том числе там, где «Документооборот» раньше ставили из исходников.\nКонкретная версия: `--version 0.0.4`. Ключ можно передать переменной `CRM_API_KEY`, адрес — `CRM_URL`.\n\nИз исходников (для разработки): `yarn install && yarn app remote:add --url … --api-key … --as prod && yarn app apply --remote prod`.\n\nЗатем в «Настройки → Приложения → Документооборот» заполнить переменные:\n\n| Переменная | Что указать |\n|---|---|\n| `DOCFLOW_ENGINE` | `APP` |\n| `CRM_PUBLIC_URL` | адрес CRM компании, например `https://acme.example.ru`; по нему строятся ссылки из Битрикс24 |\n| `BITRIX_CLIENT_ID`, `BITRIX_CLIENT_SECRET` | из карточки локального приложения портала; без них Битрикс24 не подключается, остальное работает |\n\n**Права людей.** Отвечать на шаг запущенного процесса может только тот, у кого есть право\n«Рабочие процессы». Кто выполняет задания процессов или запускает процессы с параметрами,\nполучает роль «Документооборот: участник процессов» или это право в своей роли. Право также\nпозволяет менять процессы: давайте его тем, кому это допустимо. Обычные задания и документы\nправа «Рабочие процессы» не требуют.\n\n## Как пользоваться\n\n- **Процесс.** «Процессы → Создать» открывает карточку процесса с уже выставленным разделом.\n  Существующий процесс переносится в документооборот полем «Раздел» в его карточке.\n- **Запуск с параметрами.** Вкладка процесса «Запуск и задания» → «Добавить поле»: название, тип\n  (текст, число, дата, сотрудник, компания, контакт, сделка), обязательность. «Сохранить параметры»\n  ставит процессу ручной запуск, если запуска ещё нет, и первым шагом черновика — шаг «Запуск с\n  параметрами». В следующих шагах параметры выбираются в списке переменных как поля этого шага:\n  `{{<шаг>.<поле>}}`, точное имя показано рядом с полем. Опубликуйте процесс. Параметры\n  заполняются в «Процессах» до запуска; обязательные проверяются и на странице, и на сервере, а\n  значения хранятся в запуске (`trigger.smbDocflowParameters`).\n- **Задание шага.** Шаг «Человеческий ввод» становится задачей раздела процесса: у исполнителя\n  из вкладки «Запуск и задания», без него — у запустившего. Поля задания — поля шага из редактора.\n  «Выполнить» проверяет обязательные поля и продолжает процесс; значения дальше читаются\n  переменными шага `{{<шаг>.<поле>}}`.\n- **Своё задание.** «Задания → Создать»: название, исполнитель, срок, инструкция и поля для\n  заполнения тем же конструктором. Поля меняются в панели задания («Изменить поля»).\n- **Документы.** «Документы → Добавить документ»: реквизиты, затем «Создать и прикрепить файл» —\n  справа откроется карточка документа, файл кладётся в её поле «Файл». Так сделано потому, что\n  страница приложения в песочнице видит только имя и размер выбранного файла, не его содержимое.\n  Файл, приложенный к любой записи (компания, сделка, задача, свой объект), появляется в\n  документах сам: «Где загружен», автор, дата, для задачи процесса — ссылка на запуск. Документ\n  хранит копию файла.\n\n## Ограничения\n\n- Рамку вокруг страницы раздела рисует платформа (страница из виджетов), приложение её не меняет.\n- Параметры запуска относятся к процессу, а не к версии: после правки полей опубликованная версия\n  до публикации нового черновика получает новые поля, а переменные убранных полей в ней пусты.\n- Если после ручного запуска идут сразу несколько шагов, «Запуск с параметрами» встаёт перед\n  первым из них; остальным ветвям переменные шага недоступны.\n- Документ без файла создаётся раньше файла: если закрыть карточку, не прикрепив файл, документ\n  останется с пустым полем «Файл».\n\n## Битрикс24\n\nПодключается локальным приложением портала (одна компания — один портал).\n\n1. В портале: «Разработчикам → Другое → Локальное приложение», тип «Серверное».\n2. Адреса — HTTP-маршруты приложения на адресе компании (точный адрес виден в «Настройки →\n   Приложения → Документооборот → функции»):\n   - путь обработчика: `https://<адрес компании>/s/bitrix/app`\n   - путь первоначальной установки: `https://<адрес компании>/s/bitrix/install`\n3. Права приложения: `user`, `im`.\n4. Сохранить, скопировать «Код приложения» и «Ключ приложения» в `BITRIX_CLIENT_ID` и\n   `BITRIX_CLIENT_SECRET`, затем открыть приложение в портале — установка завершится сама.\n\nКаждый запрос портала проверяется обменом refresh-токена на `oauth.bitrix.info` с ключом\nприложения; адрес портала берётся из ответа Битрикс24. Привязывается первый подтверждённый портал,\nдругой портал к той же компании не подключится. Токены портала хранятся в хранилище приложения, не\nв записях. Сотрудник находится по почте профиля Битрикс24.\n\n## Разработка\n\n```bash\nyarn app dev        # следит за src/ и синхронизирует с сервером\nyarn app dev:function:logs\nyarn test && yarn typecheck && yarn lint\n```\n\nУстройство `src/`: `shared/` — общий код (формы, процессы, фильтры REST, Битрикс24); `server/` —\nобращения к записям и движку процессов из функций; `logic-functions/`; `front/` и\n`front-components/` — интерфейс; `objects/`, `fields/`, `views/`, `roles/`, `page-layouts/`,\n`navigation-menu-items/` — данные и раскладка. Записи читаются и пишутся только через REST API\n(`server/records.ts`, `front/api.ts`), движок процессов — через две мутации GraphQL\n(`server/workflow-engine.ts`, `server/launch-step.ts`): при смене версии платформы сверять эти\nфайлы. Стили интерфейса только inline: теги `<style>` в странице приложения платформа отбрасывает.\n",
     "yarnLockChecksum": "0632f6795528cecac52b40852fa9da90",
-    "packageJsonChecksum": "b3f192bf9ca0ca7d816208d3db9eb9db",
+    "packageJsonChecksum": "db63b70d70082dd84376b3616f0fd3c9",
     "requiredServerVersionRange": null,
     "healthCheckLogicFunction": {
       "universalIdentifier": "84360081-db5a-4f1c-9644-d975ccad9b2c"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiiro/docuflow",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "NorDiv Документооборот: задания с полями, процессы с запуском по параметрам, документы со всех записей, приложение Битрикс24",
   "license": "AGPL-3.0-only",
   "publishConfig": {