Auto-build: copilot (python) from cc0b7d3

.github/skills/db-repo/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: db-repo
+description: Работа с хранилищем конфигурации 1С. Используй когда нужно захватить объекты, поместить изменения в хранилище конфигурации, получить изменения из него, подключить базу к хранилищу
+argument-hint: <lock|unlock|commit|update> [database] -Objects "<объекты>"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - AskUserQuestion
+---
+
+# /db-repo — Хранилище конфигурации 1С
+
+Захват и помещение объектов, получение изменений, подключение базы, история версий,
+администрирование хранилища.
+
+> Хранилище конфигурации 1С, а не Git-репозиторий.
+
+## Usage
+
+```
+/db-repo lock   [database] -Objects "Справочник.Номенклатура"
+/db-repo commit [database] -Objects "Справочник.Номенклатура" -Comment "Добавлен Артикул"
+/db-repo unlock [database] -Objects "Справочник.Номенклатура"
+/db-repo update [database]
+```
+
+## Порядок работы
+
+В базу, подключённую к хранилищу, исходники грузятся **только частично** и **только по захваченным**
+объектам. Выполняй строго по шагам:
+
+```
+0. /db-repo update <база>                      — начать с актуального состояния
+1. /db-repo lock <база> -Objects "Справочник.Номенклатура"
+2. если шаг 0 или 1 напечатал «локальная конфигурация изменена, получено объектов из хранилища: N» —
+   выгрузи названные объекты: /db-dump-xml <база> <каталог> -Mode Partial -ObjectsFile "<файл из вывода>"
+3. правки в исходниках: /meta-edit, /form-edit, /skd-edit, /meta-compile и т. д.
+4. /db-load-xml <каталог> <база> -Mode Partial -Files "Catalogs/Номенклатура.xml,…" -UpdateDB
+5. /db-repo commit <база> -Objects "Справочник.Номенклатура" -Comment "…"
+```
+
+Шаг 0 стоит делать всегда, когда работа не продолжается сразу после предыдущего цикла: правки
+должны опираться на актуальное состояние — в том числе тех объектов, которые ты не меняешь, но
+используешь.
+
+Шаг 2 пропускать нельзя: захват и обновление подтягивают из хранилища свежие версии, и загрузка
+исходников, снятых раньше, откатит чужие изменения — молча, без ошибки.
+
+**Что вообще захватывается.** Отдельные объекты хранилища — сам объект, а также его **формы,
+макеты и команды**. Реквизиты, табличные части, измерения и ресурсы отдельными объектами **не
+являются**: они правятся в составе владельца.
+
+| Что правишь | Что захватывать |
+|-------------|-----------------|
+| Реквизит, табличную часть, измерение, ресурс, модуль объекта | сам объект: `Справочник.Контрагенты` |
+| Существующую форму, макет, команду | её саму: `Справочник.Контрагенты.Форма.ФормаЭлемента` |
+| Добавляешь новую форму, макет, команду | объект-владельца; при помещении назови и новый объект |
+| Добавляешь новый объект конфигурации | только корень: `Конфигурация`. Самого объекта ещё нет — захватить его нельзя; при помещении назови и его |
+
+Захватывай минимум того, что правишь: чем шире захват, тем больше конфликтов с коллегами.
+Захват объекта его формы и макеты не захватывает — для этого есть `-WithChildren`.
+
+## Параметры подключения
+
+Прочитай `.v8-project.json` из корня проекта. Возьми `v8path` и разреши базу:
+1. Если пользователь указал параметры подключения — используй напрямую
+2. Если указал базу по имени — ищи по id / alias / name
+3. Если не указал — сопоставь текущую ветку Git с `databases[].branches`
+4. Если ветка не совпала — используй `default`
+
+Реквизиты хранилища передавать не нужно: запись базы находится по переданным параметрам
+соединения (`-InfoBasePath` либо `-InfoBaseServer` + `-InfoBaseRef`), реквизиты берутся из её
+`repository`. Задать их явно можно параметрами `-Repository*`.
+
+## Команда
+
+```powershell
+python ".github/skills/db-repo/scripts/db-repo.py" -Command <подкоманда> <параметры>
+```
+
+### Рабочий цикл
+
+| Подкоманда | Что делает |
+|------------|------------|
+| `lock` | Захватить объекты |
+| `unlock` | Отменить захват |
+| `commit` | Поместить изменения в хранилище |
+| `update` | Получить изменения из хранилища |
+
+### Параметры
+
+| Параметр | Обязательный | Описание |
+|----------|:------------:|----------|
+| `-InfoBasePath <путь>` | * | Файловая база |
+| `-InfoBaseServer <сервер>` | * | Сервер 1С |
+| `-InfoBaseRef <имя>` | * | Имя базы на сервере |
+| `-UserName <имя>` | нет | Пользователь базы |
+| `-Password <пароль>` | нет | Пароль пользователя базы |
+| `-Objects <список>` | усл. | Объекты через запятую. Для `lock`, `unlock`, `commit` обязателен, если не задан `-All` |
+| `-ObjectsFile <путь>` | нет | Файл со списком объектов, одно имя на строку |
+| `-All` | нет | Операция над всей конфигурацией — вместо `-Objects`, а не вместе с ним |
+| `-WithChildren` | нет | Вместе с подчинёнными объектами на полную глубину |
+| `-Comment <текст>` | нет | Комментарий к помещению (`commit`). Многострочный — как есть, с переводами строк |
+| `-KeepLocked` | нет | Оставить объекты захваченными после помещения |
+| `-Revised` | нет | Получать захваченные объекты, если потребуется |
+| `-Force` | нет | Разное по подкомандам — см. ниже |
+| `-Extension <имя>` | нет | Работать с хранилищем расширения |
+| `-RepositoryPath <путь>` | нет | Хранилище явно, вместо реестра |
+| `-RepositoryUser <имя>` | нет | Пользователь хранилища явно |
+| `-RepositoryPassword <пароль>` | нет | Пароль пользователя хранилища явно |
+| `-AdditionalV8Arguments <список>` | нет | Доп. аргументы `1cv8.exe` через запятую |
+
+> `*` — нужен либо `-InfoBasePath`, либо пара `-InfoBaseServer` + `-InfoBaseRef`
+
+### `-Force`
+
+| Подкоманда | Что делает |
+|------------|------------|
+| `unlock` | **Теряет локальные правки**: объекты перезаписываются версией из хранилища |
+| `commit` | Пытается очистить ссылки на удалённые объекты вместо ошибки |
+| `update` | Подтверждает добавление и удаление объектов конфигурации |
+
+### Имена объектов
+
+Объект — `Справочник.Номенклатура`. Форма, макет, команда — полным путём:
+`Документ.ЗаказПокупателя.Форма.ФормаДокумента`, `Справочник.Номенклатура.Макет.Печать`.
+Корень конфигурации — `Конфигурация`.
+
+Если объект «не найден», это не всегда опечатка: он мог появиться в хранилище позже, чем
+обновлялась база (`/db-repo update`), либо это вовсе не объект хранилища — реквизит или
+табличная часть.
+
+## Результат
+
+Нулевой код не означает, что что-то изменилось. Под нулём приходят «уже захвачено», «обновлять
+нечего», «помещать нечего» и частичный захват — когда часть объектов занята другими, а остальное
+захвачено и его можно править.
+
+**Читай текст вывода, а не только код.** Там же приходит список полученных из хранилища объектов,
+который требует перевыгрузки перед правкой.
+
+## Требуют подтверждения пользователя
+
+Перед этими операциями **спроси подтверждение**:
+
+| Операция | Почему |
+|----------|--------|
+| `lock -All` | Захватывает **всю конфигурацию**: на большой базе идёт долго и блокирует работу всей команде |
+| `unlock -Force` | Теряются локальные правки захваченных объектов |
+| `disconnect` | Теряется подключение базы к хранилищу, в том числе на стороне хранилища |
+| `connect -ForceReplaceCfg` | Конфигурация базы заменяется конфигурацией из хранилища |
+
+`update` не выполнится, если у базы в реестре не объявлено `repository`, а реквизиты не заданы
+явно: на неподключённой к хранилищу базе эта команда заменяет всю конфигурацию его содержимым и
+рапортует успех.
+
+## Расширения
+
+У расширения своё хранилище со своим путём. Укажи `-Extension "<Имя>"` — реквизиты возьмутся из
+`extensions[].repository` записи базы. Подкоманды работают одинаково для основной конфигурации и
+для расширения.
+
+## Остальные задачи
+
+| Файл | Про что |
+|------|---------|
+| [connect.md](references/connect.md) | Подключение и отключение базы от хранилища |
+| [history.md](references/history.md) | История версий, отчёт, выгрузка версии в CF |
+| [admin.md](references/admin.md) | Создание хранилища, пользователи и права |
+| [service.md](references/service.md) | Метки версий, оптимизация, очистка кеша |
+
+## Примеры
+
+```powershell
+# Захватить справочник вместе с подчинёнными объектами
+python ".github/skills/db-repo/scripts/db-repo.py" -Command lock -InfoBasePath "C:\Bases\MyDB" -Objects "Справочник.Номенклатура" -WithChildren
+
+# Захватить корень — он нужен, чтобы добавить или удалить объект конфигурации
+python ".github/skills/db-repo/scripts/db-repo.py" -Command lock -InfoBasePath "C:\Bases\MyDB" -Objects "Конфигурация"
+
+# Поместить новый объект: он уже существует, поэтому называется вместе с корнем
+python ".github/skills/db-repo/scripts/db-repo.py" -Command commit -InfoBasePath "C:\Bases\MyDB" -Objects "Конфигурация,Справочник.Склады" -Comment "Добавлен справочник Склады"
+
+# Поместить с комментарием, оставив захват
+python ".github/skills/db-repo/scripts/db-repo.py" -Command commit -InfoBasePath "C:\Bases\MyDB" -Objects "Справочник.Номенклатура" -Comment "Добавлен реквизит Артикул" -KeepLocked
+
+# Получить изменения из хранилища
+python ".github/skills/db-repo/scripts/db-repo.py" -Command update -InfoBasePath "C:\Bases\MyDB"
+
+# Серверная база, расширение
+python ".github/skills/db-repo/scripts/db-repo.py" -Command lock -InfoBaseServer "srv01" -InfoBaseRef "MyApp_Dev" -UserName "Admin" -Extension "МоёРасширение" -Objects "Справочник.Номенклатура"
+```
+
+## После выполнения
+
+- `lock` или `update` сообщил о полученных объектах — выполни `/db-dump-xml -Mode Partial` с
+  указанным в выводе файлом, и только потом правь исходники
+- после `lock` правки идут через `/db-load-xml -Mode Partial` и `/db-update`
+- изменения готовы — предложи `/db-repo commit` с комментарием