1c Storage Ops

---
name: 1c-storage-ops
description: "Хранилище конфигурации 1С через пакетный запуск платформы: отчет по версиям, захват и снятие захвата, обновление, помещение, выгрузка в CF, подключение и отключение базы. Триггеры - 'хранилище конфигурации', 'захвати объекты', 'помести в хранилище', 'сними захват', 'обнови из хранилища', 'подключи базу к хранилищу', 'отключи от хранилища', 'отчет по версиям хранилища'. НЕ для git: это другой механизм."
---

# Операции с хранилищем конфигурации 1С

Хранилище конфигурации это механизм платформы, а не git. Совместная работа идет через захват объектов,
история версий хранится на стороне хранилища. Скил закрывает ту часть, которая выполняется пакетным
запуском платформы.

## Usage

```powershell
powershell.exe -NoProfile -File skills/1c-storage-ops/scripts/storage-ops.ps1 -Operation <операция> [параметры]
```

## Операции

| Операция | Что делает | Список объектов |
|----------|------------|-----------------|
| `status` | Отчет по версиям хранилища в файл. Самая дешевая проверка всей связки: платформа, база, хранилище, учетные данные | неприменим |
| `lock` | Захватить объекты для редактирования | обязателен |
| `update` | Обновить локальную конфигурацию из хранилища | обязателен |
| `commit` | Поместить изменения в хранилище | обязателен |
| `unlock` | Отменить захват | обязателен |
| `dump` | Выгрузить конфигурацию хранилища в CF, целиком или конкретную версию | неприменим |
| `bind` | Подключить информационную базу к хранилищу | неприменим |
| `unbind` | Отключить информационную базу от хранилища | неприменим |

## Параметры

| Параметр | Обязательный | Описание |
|----------|:------------:|----------|
| `-Operation <имя>` | да | Одна из операций выше |
| `-V8Path <путь>` | нет | Каталог bin платформы или полный путь к 1cv8.exe |
| `-InfoBasePath <путь>` | * | Файловая база |
| `-InfoBaseServer <сервер>` | * | Сервер 1С |
| `-InfoBaseRef <имя>` | * | Имя базы на сервере |
| `-UserName <имя>` | нет | Пользователь базы |
| `-Password <пароль>` | нет | Пароль пользователя базы |
| `-RepositoryPath <путь>` | да | Каталог хранилища конфигурации |
| `-RepositoryUser <имя>` | нет | Пользователь хранилища |
| `-RepositoryPassword <пароль>` | нет | Пароль пользователя хранилища |
| `-Objects "имя,имя"` | ** | Полные имена объектов через запятую |
| `-IncludeChildObjects` | нет | Захватывать вместе с подчиненными объектами |
| `-Comment <текст>` | *** | Комментарий помещения |
| `-KeepLocked` | нет | Оставить объекты захваченными после помещения |
| `-OutputFile <путь>` | **** | Файл отчета для `status`, CF-файл для `dump` |
| `-Version <номер>` | нет | Номер версии для `dump`; без него берется последняя |
| `-Extension <имя>` | нет | Работать с хранилищем расширения |
| `-Force` | нет | Принудительный режим, за двумя воротами (см. ниже) |
| `-ConfirmForce` | нет | Подтверждение принудительного режима |
| `-ConfirmDiscardChanges` | нет | Подтверждение принудительной отмены захвата с потерей изменений |
| `-ConfirmUnbind` | нет | Подтверждение отключения базы от хранилища |
| `-BindAlreadyBoundUser` | нет | Подключить, даже если этот пользователь уже подключен другой базой |
| `-ReplaceLocalConfiguration` | нет | При подключении заменить локальную конфигурацию конфигурацией из хранилища |
| `-ConfirmReplaceLocalConfiguration` | нет | Подтверждение такой замены |
| `-StrictLog` | нет | Отказ в журнале поднимает код возврата до 1, даже если платформа вернула 0 |

> `*` - нужен либо `-InfoBasePath`, либо пара `-InfoBaseServer` + `-InfoBaseRef`
> `**` - обязателен для `lock`, `update`, `commit`, `unlock`; для `status` и `dump` отклоняется
> `***` - обязателен для `commit`
> `****` - обязателен для `status` и `dump`

## Гарды

Каждый отказ происходит ДО запуска платформы.

| Гард | Почему |
|------|--------|
| Операция над объектами без `-Objects` отклоняется | Платформа без списка применяет операцию ко ВСЕЙ конфигурации |
| Маски (`*`, `?`) в перечне отклоняются | Список только явный: маска раскрывается на стороне, которую не видно из вызова |
| Корень конфигурации отклоняется | Операция над корнем захватывает все |
| Имя без точки отклоняется | Ожидается полное имя вида `Справочник.Валюты` |
| Дубли в перечне отклоняются | Признак ошибки составления списка |
| `commit` без комментария отклоняется | Комментарий это связь изменения с задачей |
| `-Force` требует разрешения в проекте И подтверждения в вызове | Долговременное разрешение - ключ `repositoryAllowForce` в `.v8-project.json`; подтверждение - `-ConfirmForce`, а для отмены захвата отдельный `-ConfirmDiscardChanges`, потому что она теряет несохраненные изменения |

## Подключение и отключение: что надо знать до запуска

**Привязка регистрируется на стороне хранилища, а не внутри файла базы.** Замерено: отключение, выполненное с
файловой КОПИИ базы, сняло привязку и у исходной базы - хранилище регистрирует связь по пользователю.
Отсюда два следствия:

- проверять отключение на копии бесполезно и опасно: копия и оригинал делят одну привязку;
- прежде чем отключать, надо понимать, кто еще работает с хранилищем через эту связку.

**Обратное подключение требует пустой локальной конфигурации.** На непустой платформа отвечает
`Конфигурация не пустая!` и отказывает. Рабочий путь - `-ReplaceLocalConfiguration`, но он заменяет
локальную конфигурацию конфигурацией из хранилища: несохраненные локальные правки при этом теряются.
Поэтому ключ закрыт отдельным подтверждением.

Последовательность восстановления после отключения, проверенная целиком: подключение с заменой
конфигурации, затем отчет по версиям, затем захват и снятие - все с нулевым кодом.

## Формат файла со списком объектов

Скрипт собирает его сам, но формат стоит знать - он замерен на платформе, а не взят из описания.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Objects xmlns="http://v8.1c.ru/8.3/config/objects" version="1.0">
  <Object fullName="Справочник.Валюты" includeChildObjects="false"/>
</Objects>
```

Замеры на 8.3.27.1859:

- простой текст со списком имен платформа отвергает разбором XML: `Document is empty`;
- атрибут называется `includeChildObjects`. На `includeChildren` платформа отвечает прямо:
  `читаемый тег не соответствует ожидаемым. Текущий includeChildren, ожидаемые includeChildObjects`;
- имя пользователя хранилища с кириллицей платформой принимается.

## Примеры

```powershell
# Проверить связку и получить отчет по версиям
powershell.exe -NoProfile -File skills/1c-storage-ops/scripts/storage-ops.ps1 `
  -Operation status -InfoBasePath "C:\Bases\MyDB" `
  -RepositoryPath "C:\Repo" -RepositoryUser "Администратор" -OutputFile "report.mxl"

# Захватить объекты
powershell.exe -NoProfile -File skills/1c-storage-ops/scripts/storage-ops.ps1 `
  -Operation lock -InfoBasePath "C:\Bases\MyDB" -RepositoryPath "C:\Repo" `
  -Objects "Справочник.Валюты,Справочник.Склады"

# Поместить с комментарием и оставить захват
powershell.exe -NoProfile -File skills/1c-storage-ops/scripts/storage-ops.ps1 `
  -Operation commit -InfoBasePath "C:\Bases\MyDB" -RepositoryPath "C:\Repo" `
  -Objects "Справочник.Валюты" -Comment "ЗАДАЧА-123: добавлен реквизит" -KeepLocked

# Отключить базу от хранилища
powershell.exe -NoProfile -File skills/1c-storage-ops/scripts/storage-ops.ps1 `
  -Operation unbind -InfoBasePath "C:\Bases\MyDB" -RepositoryPath "C:\Repo" -ConfirmUnbind

# Подключить обратно, заменив локальную конфигурацию конфигурацией из хранилища
powershell.exe -NoProfile -File skills/1c-storage-ops/scripts/storage-ops.ps1 `
  -Operation bind -InfoBasePath "C:\Bases\MyDB" -RepositoryPath "C:\Repo" `
  -ReplaceLocalConfiguration -ConfirmReplaceLocalConfiguration
```

## Диагностика

| Сообщение платформы | Что значит |
|---------------------|------------|
| `Хранилище конфигурации по адресу ... не обнаружено` | Неверный `-RepositoryPath` либо каталог недоступен |
| `Неклассифицированная ошибка работы с хранилищем конфигурации` | База не подключена к хранилищу либо отказ на его стороне |
| `Объекты, отсутствующие в обеих конфигурациях` | Имя в перечне не разрешилось: опечатка либо объекта нет |
| `Объект уже захвачен пользователем ...` | Захват держит другой разработчик. Это отчет пользователю и остановка, а не повод снимать чужой захват |
| `Информационная база не связана с хранилищем конфигурации` | Привязки нет: подключить операцией `bind` |
| `Конфигурация не пустая!` при подключении | Подключение требует пустой локальной конфигурации либо `-ReplaceLocalConfiguration` |

Отчет операции `status` платформа отдает в формате MXL (табличный документ), а не текстом.

Вердикт операции строится по четырем сигналам, а не по коду возврата - `designer-batch-verdict.md`.
Пароли базы и хранилища маскируются в печатаемой командной строке.

## Связанное

- `docs/build-spec.md`, раздел про хранилище конфигурации - ключи командной строки.
- `designer-batch-verdict.md` - как читается результат пакетного запуска.
- `1c-db-dump-cf` - выгрузка конфигурации базы, а не хранилища.