🧩 Оформлятор

Автономный корпоративный сервис формирования DOCX/XLSX по шаблонам и типизированным данным. Runtime работает без обязательного доступа в Интернет. Доступ к рабочему интерфейсу и предметным API закрывается одним общим паролем приложения «Оформлятор».

Note

Пользовательское название продукта — «Оформлятор». Технические идентификаторы docomator, @docomator/*, DOCOMATOR_*, systemd-службы, пути и имена автономных архивов сохранены для совместимости; см. BRANDING.

Important

Общий пароль — не система пользователей и ролей. После входа все допущенные клиенты имеют одинаковые возможности. Пространства остаются жёсткими границами данных, но не ACL. Firewall, reverse proxy и HTTPS по-прежнему обязательны для рабочего контура.

Текущий кодовый контур поддерживает импорт и экспорт данных, DOCX/XLSX-шаблоны, ручной и календарный выпуск, результаты, SMTP/сетевую доставку, резервирование и восстановление. Стабильный выпуск нельзя объявлять до фактической Debian/Astra/Office/recovery/UX-приёмки; см. FINALIZATION и SUPPORT_MATRIX.

Основной путь

войти по общему паролю;
выбрать пространство;
импортировать сотрудников или произвольные объекты из CSV/XLSX либо добавить вручную;
при необходимости выгрузить текущие данные в CSV/XLSX;
загрузить и проверить DOCX/XLSX;
связать изменяемые места с полями и выполнить пробное заполнение;
активировать проверенную версию шаблона;
выбрать всех, группу или отдельные объекты;
проверить обязательные данные;
сформировать персональные или сводные документы;
скачать DOCX/XLSX/ZIP либо доставить через SMTP/сетевую папку;
при ошибке исправить только проблемные данные и повторить неуспешные единицы.

🔐 Общий пароль входа

ADR-0009 вводит один общий password gate без пользователей, персональных кабинетов, ролей и ACL.

Новая установленная система остаётся закрытой, пока оператор локально не задаст пароль:

sudo bash /opt/docomator/current/app/scripts/offline/set-password.sh

Команда скрыто запрашивает пароль, сохраняет только параметризованный scrypt-хэш, создаёт новый случайный session secret и перезапускает API. При смене пароля session secret ротируется, поэтому ранее выданные браузерные сессии прекращают действовать.

Сессия браузера использует подписанную HttpOnly, SameSite=Strict cookie с ограниченным сроком жизни; при HTTPS добавляется Secure. Повторные неверные попытки входа получают локальный backoff. /healthz и /readyz остаются доступны техническим проверкам без пользовательской сессии.

В source/dev-запуске gate выключен только если DOCOMATOR_ACCESS_PASSWORD_HASH и DOCOMATOR_SESSION_SECRET вообще не объявлены. Установленный профиль объявляет их пустыми и поэтому fail-closed остаётся закрытым до set-password.sh.

🧱 Пространства

Пространство изолирует сущности, группы, пользовательские поля и значения, импорт, шаблоны и связанные операции. Типы объектов являются общей системной схемой, но конкретный объект и пользовательское поле принадлежат одному пространству.

См. ENTITY_MODEL_AND_IMPORT, ADR-0008 и ADR-0009.

📥 Импорт CSV/XLSX

Оба пользовательских импорта используют сопровождаемый сценарий:

файл → колонки → сопоставление → preview → исправление → импорт → результат

Есть drag&drop, корректные координаты пустых XLSX-ячеек, физические номера строк, переносы внутри ячейки, повторный импорт, нормализация ФИО и структурированные ошибки code/row/column/propertyKey/rawValue/suggestedAction. Ошибка подсвечивает проблемное сопоставление и не сбрасывает остальные настройки.

📤 Экспорт CSV/XLSX

В разделах сотрудников и произвольных объектов доступны «Экспорт CSV» и «Экспорт XLSX».

Экспорт строится сервером из явно выбранных пространства и типа объектов:

только объекты и пользовательские поля текущего пространства;
отображаемое название, состояние и последние значения;
человеческие заголовки и единицы без UUID и технических ключей;
устойчивый порядок строк и колонок;
CSV UTF-8 BOM, ;, CRLF;
настоящий детерминированный XLSX с текстовыми ячейками, замороженной первой строкой и фильтром;
строки, похожие на формулы Excel/Calc, нейтрализуются и не становятся исполняемыми формулами;
превышение ограничений XLSX не обрезается молча: сервер предлагает CSV или разделение выгрузки.

🛡️ Документы

До сохранения DOCX/XLSX проверяются ZIP/OOXML, размеры, пути, опасные XML-конструкции, макросы, ActiveX, OLE, подписи и внешние связи. Renderer изменяет только разрешённые привязки и повторно считывает значения после формирования.

Поддерживаются выбранный текст DOCX, ячейки XLSX, несколько полей, безопасные форматтеры, повторяемая строка DOCX, повторяемая строка/диапазон XLSX, персональный и сводный выпуск, частичный успех, повтор только ошибок и необязательный PDF-предпросмотр через локальный LibreOffice.

📥 Результаты, доставка и резервирование

Готовые ручные и автоматические документы остаются в разделе «Результаты» до явного удаления. Скачивание не удаляет файл. Worker продолжает сохраняемую операцию после штатного перезапуска без второго результата.

Доставка поддерживает локальный SMTP с TLS/allowlist и разрешённую CIFS/NFS-папку с проверкой mount/sentinel, временным файлом, fsync и атомарным rename. Ошибка доставки не уничтожает уже готовый документ.

Ежедневный systemd timer создаёт проверяемые резервные копии. Восстановление проверяет manifest и SHA-256 до замены рабочих данных.

🚀 Локальный запуск из исходников

Требуются Node.js не ниже 24.18.0 и npm 11+:

npm ci
npm run build
DOCOMATOR_DATA_DIR="$PWD/.tmp/data" npm run migrate

API:

DOCOMATOR_DATA_DIR="$PWD/.tmp/data" npm run start:api

Worker во втором терминале:

DOCOMATOR_DATA_DIR="$PWD/.tmp/data" npm run start:worker

Проверка и полный инженерный gate:

curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz
npm run check

CI дополнительно запускает Chromium user flows, real-stack smoke и сборку/повторную проверку offline archive.

📦 Автономная поставка

Debian и Astra Linux собираются как разные target-профили на соответствующих эталонных VM. Набор .deb одной ОС нельзя использовать для другой.

🟦 Debian

npm run bundle:offline:debian -- \
  --apt-update \
  --llama-server /srv/build/llama.cpp/llama-server \
  --model /srv/models/model.gguf

🟥 Astra Linux

Astra Linux bundle собирается отдельно на согласованной Astra reference VM и требует явного Chromium-профиля этой ОС:

npm run bundle:offline:astra -- \
  --apt-update \
  --llama-server /srv/build/llama.cpp/llama-server \
  --model /srv/models/model.gguf \
  --ux-chromium-package "$ASTRA_CHROMIUM_PACKAGE" \
  --ux-chromium-bin "$ASTRA_CHROMIUM_BIN"

После установки задайте пароль и проверьте первый запуск:

sudo bash /opt/docomator/current/app/scripts/offline/set-password.sh
bash /opt/docomator/current/app/scripts/offline/first-run.sh --check

Целевая приёмка

Пароль acceptance передаётся только через локальный обычный файл текущего пользователя с режимом 0600; пароль и путь к файлу не включаются в акты.

install -m 0600 /dev/null "$HOME/.docomator-acceptance-password"
printf '%s\n' 'ВАШ_ОБЩИЙ_ПАРОЛЬ' > "$HOME/.docomator-acceptance-password"

"$BUNDLE_ROOT/target-acceptance.sh" \
  --config /etc/docomator/docomator.env \
  --base-url http://127.0.0.1:8080/ \
  --password-file "$HOME/.docomator-acceptance-password" \
  --output "$HOME/docomator-target-acts/debian-01"

Для строгого Astra-контура добавляются --require-network --require-smtp. После прогона временный password file удаляется.

Финальный release evidence

После получения target acts Debian/Astra, UX-акта, Office-корпуса, restore-акта и пустого списка блокеров выполняется единый fail-closed gate:

npm run release:evidence -- \
  /srv/docomator-release-evidence \
  --expected-commit '<ПОЛНЫЙ_GIT_SHA>' \
  --expected-version '<ПРОВЕРЯЕМАЯ_ВЕРСИЯ>'

Только успешный release:evidence разрешает менять статус выпуска на stable. Сам по себе зелёный CI или успешно собранный generic bundle целевую Debian/Astra/Office/recovery-приёмку не заменяет.

Что ещё требует внешних свидетельств

чистая offline-установка и reboot на Debian;
отдельный нативный прогон Astra Linux 1.7;
настоящий LibreOffice без SKIPPED;
реальный корпус не менее 20 DOCX + 20 XLSX с проверкой Microsoft Office;
импорт/выпуск 10/100/1000;
restart/failure scenarios;
backup/restore на отдельной чистой машине;
два новых пользователя без устной инструкции;
финальный release evidence без открытых блокеров.

См. SECURITY, ARCHITECTURE, FINALIZATION, SUPPORT_MATRIX и ROADMAP.

Name		Name	Last commit message	Last commit date
Latest commit History 400 Commits
.codex		.codex
.github		.github
apps		apps
config		config
deploy/systemd		deploy/systemd
docs		docs
examples		examples
migrations		migrations
packages		packages
scripts		scripts
tests/e2e		tests/e2e
.editorconfig		.editorconfig
.gitignore		.gitignore
.node-version		.node-version
.npmrc		.npmrc
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
RELEASE_IDENTITY.json		RELEASE_IDENTITY.json
SECURITY.md		SECURITY.md
VERSION		VERSION
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json

Navigation Menu

Repository files navigation

🧩 Оформлятор

Основной путь

🔐 Общий пароль входа

🧱 Пространства

📥 Импорт CSV/XLSX

📤 Экспорт CSV/XLSX

🛡️ Документы

📥 Результаты, доставка и резервирование

🚀 Локальный запуск из исходников

📦 Автономная поставка

🟦 Debian

🟥 Astra Linux

Целевая приёмка

Финальный release evidence

Что ещё требует внешних свидетельств

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🧩 Оформлятор

Основной путь

🔐 Общий пароль входа

🧱 Пространства

📥 Импорт CSV/XLSX

📤 Экспорт CSV/XLSX

🛡️ Документы

📥 Результаты, доставка и резервирование

🚀 Локальный запуск из исходников

📦 Автономная поставка

🟦 Debian

🟥 Astra Linux

Целевая приёмка

Финальный release evidence

Что ещё требует внешних свидетельств

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages