# 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.