cc-1c-skills/docs/db-guide.md

# Базы данных 1С

Навыки группы `/db-*` позволяют управлять информационными базами 1С из Claude Code: создавать базы, загружать и выгружать конфигурации, обновлять БД, запускать предприятие, загружать изменения из Git.

## Навыки

| Навык | Скрипт | Описание |
|-------|:------:|----------|
| `/db-list` | — | Управление реестром баз (.v8-project.json) |
| `/db-create` | — | Создание информационной базы |
| `/db-dump-cf` | — | Выгрузка конфигурации в CF-файл |
| `/db-load-cf` | — | Загрузка конфигурации из CF-файла |
| `/db-dump-xml` | `.ps1` | Выгрузка конфигурации в XML-файлы (полная/инкрементальная/частичная) |
| `/db-load-xml` | `.ps1` | Загрузка конфигурации из XML-файлов (полная/частичная) |
| `/db-update` | — | Обновление конфигурации БД |
| `/db-run` | — | Запуск 1С:Предприятие |
| `/db-load-git` | `.ps1` | Загрузка изменений из Git в базу |
| `/db-repo` | `.ps1` | Хранилище конфигурации: захват, помещение, получение изменений |

## Рабочий цикл

```
.v8-project.json → /db-create → /db-load-cf или /db-load-xml → /db-update → /db-run
                                                                    ↑
                                 /db-dump-xml ←→ правки в исходниках → /db-load-git → /db-update
```

### Типичный цикл разработки

1. **Настройка** — `/db-list add` зарегистрировать базу в `.v8-project.json`
2. **Создание** — `/db-create` создать базу (если нет)
3. **Загрузка** — `/db-load-xml` или `/db-load-cf` загрузить конфигурацию
4. **Обновление** — `/db-update` применить к БД
5. **Работа** — редактирование XML-исходников
6. **Синхронизация** — `/db-load-git` загрузить изменения из Git
7. **Обновление** — `/db-update` применить
8. **Запуск** — `/db-run` открыть предприятие

## Работа с хранилищем конфигурации

База, подключённая к хранилищу, живёт по другим правилам, и это меняет весь цикл:

- **полная загрузка XML в неё невозможна** — платформа отвечает «текущая конфигурация помещена в
  хранилище». Работает только `-Mode Partial`;
- частичная загрузка проходит **только по захваченным** объектам, иначе отказ с именем объекта;
- **новый объект требует захвата корня конфигурации** — без него частичная загрузка не пройдёт;
- любой команде конфигуратора нужны реквизиты хранилища. Их берут из `repository` записи базы
  (см. [справочник .v8-project.json](v8-project-guide.md)), передавать в каждом вызове не нужно.

Цикл разработки под хранилищем:

```
/db-repo update  →  /db-repo lock  →  /db-dump-xml -Mode Partial  →  правки
                                                                        ↓
              /db-repo commit  ←  /db-load-xml -Mode Partial -UpdateDB
```

Выгрузка после захвата обязательна: захват и обновление молча подтягивают из хранилища свежие
версии объектов, и загрузка исходников, снятых раньше, откатит чужие изменения без единой ошибки.
`/db-repo` печатает список полученных объектов и готовую команду выгрузки.

Подробности — в SKILL.md навыка `/db-repo`.

## Формат `.v8-project.json`

Полное описание формата — в [справочнике .v8-project.json](v8-project-guide.md).

### Разрешение базы

Все навыки `db-*` (а также `epf-build`, `epf-dump`, `erf-build`, `erf-dump`) используют единый алгоритм:

1. Если пользователь указал **параметры подключения** (путь, сервер) — используй напрямую
2. Если указал **базу по имени** — ищи: `id` → `aliases` (с учётом морфологии) → `name` (нечёткое)
3. Если **не указал** — сопоставь текущую ветку Git с `branches` (точно или по glob-паттерну)
4. Fallback на `default`
5. Если не найдено — спроси пользователя
6. После выполнения: если использованная база не зарегистрирована — предложи добавить через `/db-list add`

## Сценарии использования

### Создать базу и загрузить конфигурацию

```
> Создай файловую базу C:\Bases\Test и загрузи в неё конфигурацию из C:\WS\cfsrc
```

Claude вызовет `/db-create` → `/db-load-xml -Mode Full` → предложит `/db-update`.

### Загрузить изменения из Git

```
> Загрузи мои последние правки в базу разработки
```

Claude вызовет `/db-load-git dev -Source All` → предложит `/db-update`.

### Выгрузить конфигурацию

```
> Выгрузи конфигурацию из тестовой базы в C:\WS\cfsrc
```

Claude вызовет `/db-dump-xml test C:\WS\cfsrc -Mode Full`.

### Работа с расширениями

```
> Выгрузи расширение МоёРасширение из базы dev в C:\WS\ext_src
```

Claude вызовет `/db-dump-xml dev C:\WS\ext_src -Extension МоёРасширение`.

```
> Загрузи расширение обратно в базу
```

Claude вызовет `/db-load-xml C:\WS\ext_src dev -Extension МоёРасширение` → предложит `/db-update -Extension МоёРасширение`.

### Запустить предприятие

```
> Запусти базу разработки
```

Claude вызовет `/db-run dev`.

## Движок: 1cv8 или ibcmd

По умолчанию навыки группы работают через конфигуратор (`1cv8.exe`; путь к нему определяется
автоматически по каталогу `v8path`) — менять это не нужно. При желании ту же операцию можно выполнить
через автономный сервер `ibcmd`. Для этого навыку нужно передать путь к самому файлу `ibcmd.exe`
(каталог `bin` всегда трактуется как `1cv8.exe`; отдельного поля-переключателя в `.v8-project.json` нет).
Путь указывают одним из двух способов:

- **разово, в самой задаче** — назвать полный путь к `ibcmd.exe`:

  ```
  > Собери обработку, платформа C:\Program Files\1cv8\8.3.24.1691\bin\ibcmd.exe
  ```
- **в файле настроек** — прописать в `v8path` не каталог `bin`, а сам файл `...\bin\ibcmd.exe`
  (тогда через `ibcmd` пойдут все операции).

Через `ibcmd` работают: `db-create`, `db-load-xml`/`db-dump-xml` (в том числе по отдельным объектам
и со всеми расширениями), `db-load-cf`/`db-dump-cf`, `db-load-dt`/`db-dump-dt`, `db-update`,
`db-load-git`, `epf-build`/`epf-dump`, `erf-build`/`erf-dump`.

При выгрузке **конфигурации** выбор движка на результат не влияет: выгрузка одной и той же базы
конфигуратором и `ibcmd` совпадает **побайтно** (проверено на полной выгрузке типовой конфигурации —
91807 файлов из 91807). Дампы конфигурации, снятые разными движками, сравнимы напрямую.

Это НЕ распространяется на разбор внешних обработок и отчётов (`epf-dump`/`erf-dump`): там результат
определяется **базой, в которой идёт разбор**, а движок начинает влиять, когда база не та.

Замер на реквизите типа `CatalogRef.Валюты` (платформа 8.3.24):

| База разбора | Движок | Что попадает в исходники |
|---|---|---|
| с подходящей конфигурацией | `1cv8` и `ibcmd` одинаково | `<v8:Type>cfg:CatalogRef.Валюты</v8:Type>` |
| без нужного объекта | `ibcmd` | `<v8:TypeId>602d2ea9-…</v8:TypeId>` — идентификатор типа |
| без нужного объекта | `1cv8` | `<v8:Type>xs:string</v8:Type>` + `StringQualifiers Length=10` |

Годится только первая строка, и вот почему. Имя типа резолвится **по имени**: такие исходники
собираются в любой конфигурации, где есть одноимённый объект. Идентификатор же привязан к той
конфигурации, из которой получен: сборка в чужой базе проходит **без ошибки**, но uuid остаётся
висячим и ни к чему не привязывается — работать с такими исходниками нельзя. Вариант с `xs:string`
хуже всех: ссылка подменена строкой, и по XML не видно, что там вообще была ссылка.

Оба деградированных варианта молчаливы — ни при разборе, ни при последующей сборке ошибок нет.
Поэтому разбирать EPF/ERF нужно в базе с подходящей конфигурацией; «разберу в пустой, потом
поправлю» не работает.

Ограничения:
- только **файловые** базы (для серверных используйте конфигуратор);
- если запрошен режим, который `ibcmd` не поддерживает (например, выгрузка в «плоском» формате),
  навык остановится с понятным сообщением и предложит конфигуратор.

## Дополнительные аргументы платформы

Набор аргументов, который скрипт формирует сам, закрыт: подключение, пакетная операция, `/Out`.
Общие ключи платформы, которых нет среди параметров навыка (`/UseHwLicenses+`, `/L`, `/ClearCache`,
`/DebuggerURL`, …), передаются через escape hatch — по одному параметру на движок:

| Движок | Параметр | Ключ в `.v8-project.json` |
|--------|----------|---------------------------|
| `1cv8.exe` | `-AdditionalV8Arguments` | `v8args` |
| `ibcmd` | `-AdditionalIbcmdArguments` | `ibcmdargs` |

```powershell
# разово; несколько аргументов — через запятую, как у -Objects/-Files
powershell.exe -NoProfile -File "…/epf-build.ps1" -SourceFile "src/Обработка.xml" `
    -OutputFile "build/Обработка.epf" -AdditionalV8Arguments "/UseHwLicenses+,/L,ru"
```

Список пишется одной строкой через запятую: при запуске скрипта через `-File`
PowerShell не умеет собирать массив из отдельных токенов. Значение, содержащее запятую,
не поддерживается.

Проектные аргументы применяются первыми, параметр — после них. Аргументы уходят во **все** запуски
платформы, которые делает навык: `epf-build` без указания базы прогоняет `CREATEINFOBASE`,
`/LoadConfigFromFiles`, `/UpdateDBCfg` и саму сборку — ключ получит каждый.

Что отклоняется до запуска, с указанием штатного параметра:

- аргумент, которым управляет сам скрипт: режим (`DESIGNER`, `ENTERPRISE`, `CREATEINFOBASE`),
  подключение (`/F`, `/S`, `/N`, `/P`), `/Out`, пакетная операция (`/Load*`, `/Dump*`,
  `/UpdateDBCfg`, …). Платформа допускает лишь одну пакетную операцию, а дубль ключа подключения
  даёт невнятную ошибку 1С;
- для `ibcmd` — позиционный токен: команда (`infobase create`, `config import`) принадлежит навыку,
  поэтому значения передаются только в форме `--ключ=значение`;
- параметр «не своего» движка (`-AdditionalV8Arguments` при выбранном `ibcmd`). Ключи из
  `.v8-project.json` в этом случае просто не применяются — реестр проекта может описывать оба движка.

## Что печатает навык

Порядок один и тот же в обоих портах и на обоих движках:

1. `Running: …` — командная строка запуска (секреты замаскированы, см. ниже);
2. результат операции одной строкой;
3. `--- Log ---` … `--- End ---` — журнал платформы из `/Out` (у `ibcmd` его нет);
4. `--- Вывод платформы ---` … `--- End ---` — то, что платформа написала в консоль.

Четвёртый блок появляется, только если платформа что-то написала. В пакетном режиме
`1cv8` пишет в `/Out` и молчит в консоли, поэтому обычно блока нет; он всплывает при
аварийном завершении, когда сообщение проходит мимо `/Out`. `ibcmd`, наоборот, весь свой
вывод (`[INFO] …`) шлёт именно туда.

Кодировка определяется по факту: UTF-8, при неудаче — cp866. Гадать нельзя — `ibcmd`
пишет UTF-8, а аварийный текст `1cv8` приходит в OEM.

Путевые параметры прощают обрамляющие кавычки, пробелы по краям и хвостовой разделитель.
Навыки, работающие с готовой базой, проверяют её наличие до запуска и говорят
«information base not found at X» вместо платформенного «Неверные или отсутствующие
параметры соединения».

В строке `Running: …` значения секрето-опасных ключей (`/P`, `/UC`, `--password`, `--token`)
заменяются на `***`. Ограничения разбора, о которых стоит знать:

- слитое значение, начинающееся с буквы (`/Psecret` вместо `/P"secret"`), неотличимо от более
  длинного ключа — такой аргумент не будет ни распознан как конфликт, ни замаскирован;
- содержимое файла параметров `/@` не разбирается — за его состав отвечает вызывающий.

## Спецификации

- [build-spec.md](build-spec.md) — пакетный режим конфигуратора 1С (CREATEINFOBASE, DESIGNER, ENTERPRISE, параметры, коды возврата)