First commit

2026-10-16 21:11:50 +03:00
commit 34f52d6b1d
11 changed files with 915 additions and 0 deletions
@@ -0,0 +1,104 @@
+# ric930-usrinfo
+
+Локальный конвертер `*.USR`: **USR → XML** и **XML → USR**.
+
+Полная спецификация бинарного формата: **[docs/USR_FORMAT.md](docs/USR_FORMAT.md)**.
+
+## Запуск без параметров
+
+```bash
+# Linux
+./ric930-usrinfo-linux-amd64
+```
+
+```powershell
+# Windows PowerShell
+.\ric930-usrinfo-windows-amd64.exe
+```
+
+Программа найдёт все `.USR` в **текущем рабочем каталоге** (не рекурсивно, расширение без учёта регистра) и создаст рядом с каждым файлом **только одноимённый `.XML`**.
+
+## Команды и маски
+
+```bash
+# USR -> XML
+ric930-usrinfo decode 'CONS#12*.USR'
+ric930-usrinfo decode A.USR B.USR
+ric930-usrinfo --decode '*.USR'
+
+# XML -> USR
+ric930-usrinfo encode 'CONS#12*.XML'
+ric930-usrinfo encode A.XML B.XML
+ric930-usrinfo --encode '*.XML'
+
+# Другой каталог
+ric930-usrinfo decode -dir /data/consultant 'CONS#12*.USR'
+ric930-usrinfo encode -dir /data/consultant '*.XML'
+
+# Запретить перезапись
+ric930-usrinfo decode -no-overwrite '*.USR'
+```
+
+Команды `decode` / `encode` (как и флаги `--decode` / `--encode`) **обязательно** принимают один или несколько файлов либо масок. Маски `*`, `?`, `[a-z]` обрабатываются программой, включая Windows. В Linux кавычки нужны, чтобы оболочка не раскрыла маски раньше программы. Пути могут быть относительными или абсолютными; рекурсивный обход подкаталогов не предусмотрен. Параметры должны стоять до списка файлов.
+
+### Параметры
+
+```text
+-dir DIR          Базовый каталог (по умолчанию текущий)
+-no-overwrite    Не заменять уже существующие результаты
+-max-xml-mb N    Лимит исходного/распакованного XML: 1..30 МБ (по умолчанию 30)
+-version         Вывести версию
+-h / --help      Справка
+```
+
+## Алгоритм
+
+Формат содержит zlib-поток, к байтам которого применено смещение `33 + 50*i` по модулю 256 (индексы с нуля):
+
+```text
+USR[i] = (zlib[i] + 33 + 50*i) mod 256
+zlib[i] = (USR[i] - 33 - 50*i) mod 256
+XML = zlib.decompress(zlib)
+```
+
+**USR → XML** сохраняет исходные байты документа, включая объявленную кодировку, пробелы и комментарии. При **XML → USR → XML** исходные XML-байты воспроизводятся в точности. При этом созданный USR может отличаться по байтам от "оригинального" USR из-за особенностей сжатия DEFLATE.
+
+Перед сохранением приложение проверяет корректность распакованного XML с учётом кодировки; неподдерживаемые и повреждённые файлы приводят к ошибке для конкретного входа. Лимит USR — 15 МБ, лимит XML — 30 МБ (настраивается вниз). Каждый файл обрабатывается независимо; ошибка одного не останавливает остальные.
+
+Результат сначала записывается во временный файл рядом с назначением, затем переименовывается. По умолчанию выходной файл обновляется; `-no-overwrite` позволяет пропустить существующий.
+
+Коды завершения: `0` — без ошибок; `1` — ошибка обработки хотя бы одного файла; `2` — неверные аргументы CLI. Исполняемые файлы не принимают XML другого формата в качестве исходного файла для `decode` и не принимают `.USR` для `encode`.
+
+## Сборка
+
+```bash
+make build           # Linux amd64 и Windows amd64
+make build-linux
+make build-windows
+make vet             # анализ кода
+make clean
+```
+
+Результаты в `dist/`:
+
+```text
+ric930-usrinfo-linux-amd64
+ric930-usrinfo-windows-amd64.exe
+```
+
+## Структура проекта
+
+```text
+cmd/ric930-usrinfo/  CLI, параметры и справка
+internal/app/        Поиск, маски, операции с файлами
+internal/usr/        Кодирование/декодирование USR
+internal/xmlcheck/   Проверка XML, в том числе Windows-1251
+docs/USR_FORMAT.md   Спецификация бинарного формата
+Makefile             Сборка для Linux и Windows
+```
+
+**Ограничения:** данный проект является результатом долгосрочной работы по альтернативному методу получения данных для собственных учетных систем из оригинальных файлов статистики программного проекта "КонсультантПлюс".
+
+Все действия были выполнены исключительно в познавательных целях без достижения возможности фальсификации производственных или иных данных.
+
+В исследовальских целях было использовано свободное ПО: Ghidra, IDA Free, ProccessExplorer, objdump и dumpbin.