Skip to content

DEADover/SMUX

BranchesTags

Repository files navigation

SMUX — EDIFACT ↔ XML Transformation Service

Веб-сервис для двунаправленного преобразования данных между форматами EDIFACT и XML, построенный на базе Smooks с поддержкой DFDL. Предоставляет браузерный UI и REST API для интеграции с ESB/iPaaS платформами.

Важно: несмотря на широкие возможности Smooks, текущая версия SMUX реализует только два направления трансформации: плоский EDIFACT → XML и XML → EDIFACT. Поддерживаются форматы D.93A–D.21B (1993–2021) и XML на базе EDIFACT DFDL Schemas. Произвольный XML стороннего происхождения и другие форматы не поддерживаются.

Возможности

Трансформация

  • EDIFACT → XML (parser) и XML → EDIFACT (unparser)
  • Поддержка всех версий EDIFACT от D.93A до D.21B (30+ версий)
  • Ввод данных текстом или файлом через UI, raw-текст через REST API
  • Просмотр результата с подсветкой синтаксиса (Monaco Editor)
  • Удаление пустых XML-элементов из результата
  • Переопределение кодировки (UTF-8, ISO-8859-1, Windows-1252 и др.)

Управление конфигурациями

  • Полный CRUD для конфигураций Smooks
  • Разделение на пользовательские и базовые конфигурации
  • Редактирование smooks-config.xml прямо в браузере (Monaco Editor)
  • Сброс кэша Smooks через UI или API

Генератор конфигураций

  • Визуальный визард: версия EDIFACT, режим (parser/unparser), типы сообщений
  • Встроенный каталог EDIFACT с 13 категориями и поиском по 150+ типам сообщений
  • Тонкие настройки: режим валидации, кодировка, разделители
  • Генерация конфигурации в один клик

Редактор DFDL-схем

  • Извлечение DFDL-схем из встроенного JAR на диск
  • Редактирование прямо в браузере (Monaco Editor, поддержка многомегабайтных XSD)
  • Локальные переопределения применяются автоматически при следующей трансформации
  • Сброс к оригинальным схемам из JAR в любой момент

Протокол работы (Audit Log)

  • Постоянный журнал всех операций в формате JSONL
  • Фильтрация по уровню (INFO, WARN, ERROR) и категории (TRANSFORM, CONFIG, SCHEMA, API, SYSTEM, GENERATOR)
  • Поиск по тексту, фильтр по диапазону дат, пагинация
  • Авто-обновление, экспорт в JSON, настройка срока хранения

REST API

  • POST /api/transform/{name} — трансформация через именованную конфигурацию
  • Полный API для управления конфигурациями, каталогом, схемами и журналом
  • Интерактивная документация: Swagger UI (/swagger-ui.html) — полностью на русском языке
  • Подходит для интеграции с MuleSoft, Apache Camel, Spring Integration и др.

Tech Stack

Слой Технология
Runtime Java 17
Фреймворк Spring Boot 3.2.5
Движок трансформации Smooks 2.2.1 + smooks-edifact-cartridge 2.1.0
Шаблонизатор Thymeleaf
UI редактор Monaco Editor 0.44.0
Иконки Bootstrap Icons 1.11.3
Контейнер Docker / Docker Compose
API-документация SpringDoc OpenAPI / Swagger UI

Быстрый старт

Docker (рекомендуется)

docker-compose up -d

Открыть http://127.0.0.1:8300

Нативный запуск (Java 17 + Maven)

mvn clean package -DskipTests
java -jar target/smux-1.0.0.jar

Windows-скрипты

# Сборка
scripts\build.bat

# Запуск
scripts\run.bat
# или
powershell -ExecutionPolicy Bypass -File scripts\run.ps1

REST API

Трансформация текста

# EDIFACT → XML
curl -X POST http://127.0.0.1:8300/api/transform/my-parser \
  -H "Content-Type: text/plain" \
  --data-binary @order.edi

# XML → EDIFACT
curl -X POST http://127.0.0.1:8300/api/transform/my-unparser \
  -H "Content-Type: text/plain" \
  --data-binary @order.xml

Генерация конфигурации

curl -X POST http://127.0.0.1:8300/api/catalog/generate-config \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "orders-d03b",
    "version": "d03b",
    "mode": "parser",
    "messageTypes": ["ORDERS", "ORDRSP"],
    "options": { "validationMode": "Off", "encoding": "UTF-8" }
  }'

Справочник эндпоинтов

Метод Путь Описание
POST /api/transform/{name} Трансформация файла (multipart)
POST /api/transform/{name}/text Трансформация plain-text
POST /api/transform/{name}/refresh Сброс кэша Smooks
GET /api/configs Список всех конфигураций
GET/POST/DELETE /api/configs/{name} Чтение / создание / удаление конфига
POST /api/configs/{name}/update Обновить smooks-config.xml
GET /api/configs/status Статус сервиса
GET /api/configs/edifact-versions Доступные версии EDIFACT
GET /api/catalog/categories Категории типов сообщений
GET /api/catalog/category?name= Типы сообщений в категории
GET /api/catalog/search?q= Поиск по типам сообщений
POST /api/catalog/generate-config Генерация конфига из параметров
POST /api/schemas/extract?version= Извлечь DFDL-схемы из JAR
GET /api/schemas/files?version= Список локальных файлов схем
GET/PUT/DELETE /api/schemas/file?path= Чтение / сохранение / удаление файла схемы
GET /api/logs Записи журнала (с фильтрацией)
DELETE /api/logs Очистить журнал
GET/PUT /api/logs/settings Настройки хранения журнала
GET /api/logs/export Экспорт журнала в JSON

Полная интерактивная документация: /swagger-ui.html

📂 Структура проекта

Полное описание см. в docs/PROJECT_STRUCTURE.md

SMUX/
├── src/main/
│   ├── java/com/smux/
│   │   ├── controller/             REST API (6 контроллеров)
│   │   ├── service/                Бизнес-логика (7 сервисов)
│   │   ├── model/                  Модели запросов и ответов
│   │   └── config/                 Конфигурация Spring
│   └── resources/
│       ├── application.yml         Настройки приложения
│       ├── templates/index.html    Весь фронтенд (~6100 строк)
│       ├── static/                 Логотипы и иконки
│       └── samples/                Шаблоны конфигураций Smooks
│
├── docs/                           Документация
│   ├── QUICK_START.md              Быстрый старт
│   ├── INSTALL.md                  Установка
│   ├── ARCHITECTURE.md             Архитектура
│   ├── DEVELOPMENT.md              Разработка
│   └── setup/                      Docker и конфигурация
│
├── scripts/                        Скрипты сборки и запуска
├── Dockerfile                      Docker образ
├── docker-compose.yml              Docker Compose конфигурация
└── pom.xml                         Maven конфигурация

Конфигурация

Основные настройки в src/main/resources/application.yml:

server:
  port: 8300

app:
  storage:
    base-dir: ./smooks-data

По умолчанию контейнер биндится на 127.0.0.1:8300 (только локальный доступ). Для проброса наружу поправьте ports в docker-compose.yml.

Runtime-данные хранятся в ./smooks-data/ (gitignored):

smooks-data/
├── configs/{name}/
│   ├── smooks-config.xml     конфигурация Smooks
│   └── metadata.json         метаданные конфигурации
├── schemas/{version}/        локальные DFDL-схемы (извлечённые из JAR)
├── logs/
│   └── audit.jsonl           журнал операций
└── settings/
    └── audit-settings.json   настройки хранения журнала

Примеры интеграции

Apache Camel

from("direct:edifact-in")
  .to("http://smux-host:8300/api/transform/orders-d03b");

MuleSoft

<http:request method="POST" url="http://smux-host:8300/api/transform/orders-d03b"/>

📚 Документация

Документ Описание
docs/QUICK_START.md Быстрый старт для Windows/Linux/Docker
docs/INSTALL.md Полная установка и развёртывание
docs/ARCHITECTURE.md Техническое устройство и архитектура
docs/DEVELOPMENT.md Разработка: команды, i18n, Git workflow
docs/setup/QUICKSTART_DOCKER.md Docker за 3 команды
docs/setup/DOCKER_SETUP.md Docker конфигурация, переменные, troubleshooting

Лицензия

Использует компоненты с открытым исходным кодом:

  • Smooks 2.2.1 — Apache 2.0 / LGPL v3
  • Spring Boot 3.2.5 — Apache 2.0
  • Monaco Editor — MIT
  • Bootstrap Icons — MIT

About

Web based EDIFACT-XML transformation service based on open-sourced Smooks, extensible Java framework

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages