From 950b49ddaabaf31bed038f80484a75ed0a9e31be Mon Sep 17 00:00:00 2001 From: Artur Ayukhanov Date: Fri, 21 Nov 2025 22:17:49 +0300 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=BE=20=D1=82=D0=B5=D1=85=D0=BD=D0=B8=D1=87?= =?UTF-8?q?=D0=B5=D1=81=D0=BA=D0=BE=D0=B5=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/TECHNICAL_DESCRIPTION.md | 159 ++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 docs/TECHNICAL_DESCRIPTION.md diff --git a/docs/TECHNICAL_DESCRIPTION.md b/docs/TECHNICAL_DESCRIPTION.md new file mode 100644 index 0000000..5bd3d76 --- /dev/null +++ b/docs/TECHNICAL_DESCRIPTION.md @@ -0,0 +1,159 @@ +# Техническое описание проекта 1commands + +## Общая информация + +**Название проекта:** 1commands +**Тип:** Библиотека для OneScript (oscript) +**Лицензия:** MIT +**Репозиторий:** https://github.com/artbear/1commands +**Язык разработки:** OneScript/1С + +## Назначение + +Библиотека 1commands предназначена для упрощения работы с запуском различных приложений и командных файлов из среды OneScript. Библиотека позволяет выполнять рутинные операции по запуску приложений и командных файлов операционной системы. + +## Поддерживаемые типы команд + +- Командные файлы Windows (cmd, bat) +- Bash-скрипты (bash) +- PowerShell-скрипты +- Приложения 1С через vanessa-runner +- Другие системные приложения и утилиты + +## Архитектура + +### Основные классы + +**Класс "Команда"** + +Предоставляет функциональность для выполнения одиночных команд с параметрами. + +**Класс "КомандныйФайл"** + +Обеспечивает создание и выполнение командных файлов различных типов (bat, cmd, ps1 и др.). + +### Структура проекта + +``` +1commands/ +├── src/ # Исходный код библиотеки +├── features/ # BDD-спецификации и описание функциональности +├── step_definitions/ # Примеры использования +├── tests/ # Модульные тесты +└── packagedef # Описание пакета +``` + +## Функциональные возможности + +### Запуск команд + +- Установка команды и параметров +- Установка строки запуска целиком +- Получение кода возврата +- Получение вывода команды +- Немедленный вывод лога команды +- Контроль процесса выполнения + +### Работа с командными файлами + +- Создание временных командных файлов +- Добавление команд в файл +- Указание приложения для запуска файла +- Поддержка различных расширений (.bat, .cmd, .ps1, .sh) +- Получение текста файла +- Выполнение файла + +## Примеры использования + +### Пример 1: Простая команда + +```bsl +Команда = Новый Команда; +Команда.УстановитьКоманду("oscript"); +Команда.ДобавитьПараметр("-version"); +КодВозврата = Команда.Исполнить(); +Сообщить(КодВозврата); +Сообщить(Команда.ПолучитьВывод()); +``` + +### Пример 2: Командный файл Windows + +```bsl +КомандныйФайл = Новый КомандныйФайл; +КомандныйФайл.Создать(); +КомандныйФайл.ДобавитьКоманду("@echo off"); +КомандныйФайл.ДобавитьКоманду("oscript -version"); +КодВозврата = КомандныйФайл.Исполнить(); +Сообщить(КомандныйФайл.ПолучитьВывод()); +``` + +### Пример 3: PowerShell скрипт + +```bsl +КомандныйФайл = Новый КомандныйФайл; +КомандныйФайл.УстановитьПриложение("C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe"); +КомандныйФайл.Создать("", ".ps1"); +КомандныйФайл.ДобавитьКоманду("Get-Help"); +КодВозврата = КомандныйФайл.Исполнить(); +Сообщить(КомандныйФайл.ПолучитьВывод()); +``` + +## Технические особенности + +### Режимы вывода + +**Немедленный вывод** + +Лог команды выводится во время выполнения команды в реальном времени. + +**Отложенный вывод** + +Вывод команды получается после завершения работы команды. Используется метод `ПоказыватьВыводНемедленно(Ложь)` для решения проблем с зависанием некоторых команд. + +### Обработка ошибок + +- Получение кода возврата команды +- Перехват вывода stderr +- Обработка исключений при выполнении + +## Требования к системе + +- OneScript (oscript) +- Операционная система: Windows, Linux, macOS +- Права на выполнение команд и создание временных файлов + +## Установка + +```bash +opm install 1commands +``` + +## Интеграция + +Библиотека интегрируется с экосистемой OneScript и может использоваться совместно с: +- vanessa-runner +- vanessa-automation +- Другими библиотеками oscript + +## Известные проблемы и решения + +**Проблема:** Зависание при выполнении некоторых команд (например, gitsync). + +**Решение:** Отключить режим немедленного вывода с помощью метода `ПоказыватьВыводНемедленно(Ложь)`. + +## Поддержка и документация + +- Чат поддержки: Vanessa open-source +- Чат разработчиков: oscript_library +- Дополнительная документация: папка features в репозитории +- Примеры: папка step_definitions + +## Разработка и тестирование + +### BDD-тестирование + +Функциональность описана с помощью BDD-спецификаций в папке features. + +### Примеры использования + +Дополнительные примеры доступны в step_definitions. From 666af55d0da883c8c7a234d048a3bb4f3d686cdb Mon Sep 17 00:00:00 2001 From: Artur Ayukhanov Date: Fri, 21 Nov 2025 22:54:23 +0300 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=BE=20=D0=B1=D0=B8=D0=B7=D0=BD=D0=B5=D1=81?= =?UTF-8?q?-=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=D0=B8=D0=B5=20=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/BUSINESS_DESCRIPTION.md | 193 +++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/BUSINESS_DESCRIPTION.md diff --git a/docs/BUSINESS_DESCRIPTION.md b/docs/BUSINESS_DESCRIPTION.md new file mode 100644 index 0000000..189e884 --- /dev/null +++ b/docs/BUSINESS_DESCRIPTION.md @@ -0,0 +1,193 @@ +# Бизнес-описание проекта 1commands + +## Краткое описание + +1commands — это библиотека для автоматизации запуска системных команд и приложений в среде OneScript, предназначенная для упрощения DevOps-процессов и автоматизации рутинных операций в экосистеме 1С:Предприятие. + +## Целевая аудитория + +### Основные пользователи + +- Разработчики на платформе 1С:Предприятие +- DevOps-инженеры, работающие с 1С +- Администраторы информационных баз 1С +- Специалисты по автоматизации бизнес-процессов + +### Сценарии использования + +- Автоматизация развертывания конфигураций 1С +- Интеграция с системами контроля версий +- Автоматизация тестирования +- Выполнение регламентных операций +- Построение CI/CD пайплайнов + +## Бизнес-ценность + +### Преимущества для бизнеса + +**Сокращение времени разработки** + +Упрощение работы с системными командами позволяет разработчикам сосредоточиться на бизнес-логике, а не на технических деталях запуска приложений. + +**Снижение операционных рисков** + +Стандартизированный подход к запуску команд уменьшает количество ошибок при развертывании и обслуживании систем. + +**Повышение производительности** + +Автоматизация рутинных операций освобождает время специалистов для решения более важных задач. + +**Кроссплатформенность** + +Единый интерфейс для работы с командами в Windows, Linux и macOS снижает затраты на поддержку гетерогенной инфраструктуры. + +## Рыночное позиционирование + +### Конкурентные преимущества + +- Специализация на экосистеме 1С и OneScript +- Open Source модель разработки +- Активное сообщество пользователей +- Интеграция с популярными инструментами (vanessa-runner, vanessa-automation) +- Простота использования и низкий порог входа + +### Альтернативные решения + +Ручное написание скриптов на PowerShell, Bash или использование сторонних инструментов автоматизации, не специализированных для 1С. + +## Модель распространения + +**Тип лицензии:** Open Source (MIT) +**Стоимость:** Бесплатно +**Модель поддержки:** Сообщество разработчиков и пользователей + +## Экономический эффект + +### Для малого бизнеса + +- Снижение затрат на IT-инфраструктуру +- Отсутствие лицензионных платежей +- Быстрое внедрение автоматизации + +### Для среднего и крупного бизнеса + +- Масштабируемость решений +- Стандартизация процессов разработки +- Снижение времени на развертывание обновлений +- Повышение надежности систем + +### Оценка экономии + +При автоматизации типовых операций экономия времени разработчиков может составлять 20-30% на задачах развертывания и тестирования. + +## Сценарии применения + +### DevOps и CI/CD + +- Автоматическое развертывание конфигураций 1С +- Запуск синтаксического контроля +- Выполнение автоматических тестов +- Интеграция с Jenkins, GitLab CI, GitHub Actions + +### Администрирование + +- Регламентные операции с базами данных +- Резервное копирование +- Обновление платформы и конфигураций +- Мониторинг состояния систем + +### Разработка + +- Локальная отладка скриптов +- Быстрое прототипирование решений +- Тестирование интеграций с внешними системами + +## Экосистема и интеграции + +### Совместимость + +- OneScript (oscript) +- Vanessa-runner +- Vanessa-automation +- Git и системы контроля версий +- Системы CI/CD + +### Расширяемость + +Открытая архитектура позволяет расширять функциональность под специфические потребности бизнеса. + +## Риски и ограничения + +### Технические ограничения + +- Требуется установленный OneScript +- Зависимость от операционной системы для специфичных команд +- Возможны проблемы с зависанием при использовании немедленного вывода + +### Бизнес-риски + +- Зависимость от активности open-source сообщества +- Отсутствие коммерческой поддержки по SLA +- Необходимость самостоятельного обучения персонала + +## Внедрение + +### Этапы внедрения + +**Пилотный проект (1-2 недели)** + +Установка библиотеки, обучение команды, автоматизация первых процессов. + +**Масштабирование (1-2 месяца)** + +Распространение на все проекты, создание внутренних стандартов, интеграция с CI/CD. + +**Оптимизация (постоянно)** + +Совершенствование автоматизации, обмен опытом с сообществом. + +### Требования к персоналу + +- Базовые знания OneScript +- Понимание командной строки +- Опыт работы с 1С:Предприятие + +## Метрики эффективности + +### KPI внедрения + +- Время развертывания конфигурации (сокращение на 40-60%) +- Количество ошибок при развертывании (снижение на 30-50%) +- Время на выполнение рутинных операций (экономия 10-15 часов в месяц на специалиста) +- Покрытие автоматизацией процессов (целевой показатель 70-80%) + +## Дорожная карта развития + +### Текущие возможности + +Запуск команд, создание командных файлов, поддержка различных ОС и типов скриптов. + +### Потенциальные улучшения + +- Расширенное логирование +- Поддержка асинхронного выполнения +- Интеграция с облачными платформами +- Графический интерфейс мониторинга + +## Поддержка и обучение + +### Каналы поддержки + +- Чаты сообщества (Vanessa open-source, oscript_library) +- GitHub Issues +- Документация в репозитории + +### Обучающие материалы + +- Примеры в репозитории +- BDD-спецификации +- Опыт сообщества + +## Выводы + +Проект 1commands представляет собой эффективное решение для автоматизации операций в экосистеме 1С, обеспечивая бизнесу снижение затрат, повышение надежности и ускорение процессов разработки и развертывания. Open Source модель делает решение доступным для организаций любого размера, а активное сообщество обеспечивает непрерывное развитие проекта.