docs(v8-project): пример .v8-project.example.json + рекомендуемая структура src/ + ibcmd

- .v8-project.example.json в корне как шаблон (без секретов, коммитится; точное имя .v8-project.json остаётся в .gitignore). Версия платформы и configSrc=src\cf под рекомендуемую структуру. - v8-project-guide: раздел «Рекомендуемая структура проекта» (src/cf, src/cfe/<Имя>, src/epf/<Имя>, src/erf/<Имя>), упоминание шаблона, configSrc-примеры → src\cf, нейтральный раздел про выбор движка 1cv8/ibcmd. - db-guide: нейтральный раздел «Движок: 1cv8 или ibcmd» (по умолчанию конфигуратор; ibcmd — на усмотрение пользователя через -V8Path в задаче или файл ibcmd.exe в v8path). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 06:54:38 +03:00 · 2026-06-22 19:46:21 +03:00
parent 684bbb5036
commit c172cf142a
3 changed files with 109 additions and 14 deletions
@@ -0,0 +1,35 @@
+{
+  "v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
+  "databases": [
+    {
+      "id": "dev",
+      "name": "Разработка",
+      "type": "file",
+      "path": "C:\\Bases\\MyApp_Dev",
+      "user": "Администратор",
+      "password": "",
+      "aliases": ["dev", "разработка"],
+      "branches": ["dev", "develop", "feature/*"],
+      "configSrc": "src\\cf",
+      "webUrl": "http://localhost:8081/dev"
+    },
+    {
+      "id": "test",
+      "name": "Тестовая",
+      "type": "server",
+      "server": "srv01",
+      "ref": "MyApp_Test",
+      "user": "Администратор",
+      "password": "",
+      "aliases": ["test", "тест", "тестовая"],
+      "branches": ["main", "release/*"]
+    }
+  ],
+  "default": "dev",
+  "webPath": "C:\\tools\\apache24",
+  "ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe",
+  "tts": {
+    "provider": "edge",
+    "voice": "ru-RU-DmitryNeural"
+  }
+}
@@ -98,6 +98,31 @@ Claude вызовет `/db-load-xml C:\WS\ext_src dev -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` не поддерживает (например, выгрузка в «плоском» формате),
+  навык остановится с понятным сообщением и предложит конфигуратор.
+
 ## Спецификации

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

 Размещается в корне проекта (рядом с `.git/`). Создаётся навыком `/db-list add` или вручную.

-> **Безопасность**: файл содержит секреты (пароли баз данных, API-ключи TTS) и добавлен в `.gitignore` — он не попадает в репозиторий. Каждый разработчик заводит свой `.v8-project.json` локально.
+> **Шаблон**: в корне репозитория лежит `.v8-project.example.json` — скопируйте его в `.v8-project.json` и поправьте пути под свою машину.
+
+> **Безопасность**: файл содержит секреты (пароли баз данных, API-ключи TTS) и добавлен в `.gitignore` — он не попадает в репозиторий. Каждый разработчик заводит свой `.v8-project.json` локально. Пример (`.v8-project.example.json`) секретов не содержит и хранится в репозитории.

 ## Полная схема

 ```jsonc
 {
  // === Платформа ===
-  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
+  "v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",

  // === Базы данных ===
  "databases": [
@@ -24,7 +26,7 @@
      "password": "",                       // пароль
      "aliases": ["dev", "разработка"],     // альтернативные имена
      "branches": ["dev", "feature/*"],     // привязка к Git-веткам
-      "configSrc": "C:\\WS\\myapp\\cfsrc",  // каталог XML-выгрузки конфигурации
+      "configSrc": "src\\cf",                // каталог XML-выгрузки конфигурации (см. структуру ниже)
      "webUrl": "http://localhost:8081/dev"  // URL веб-клиента (для /web-test)
    },
    {
@@ -54,7 +56,7 @@

 | Поле | Тип | Обяз. | По умолчанию | Описание | Кто заполняет |
 |------|-----|:-----:|-------------|----------|---------------|
-| `v8path` | string | да | — | Путь к каталогу `bin` платформы 1С | `/db-list add` или руками |
+| `v8path` | string | да | — | Путь к каталогу `bin` платформы 1С (или к файлу `1cv8.exe`/`ibcmd.exe`, см. ниже) | `/db-list add` или руками |
 | `databases` | array | да | — | Список баз данных | `/db-list add` |
 | `default` | string | нет | — | `id` базы по умолчанию | `/db-list` |
 | `editingAllowedCheck` | `"deny"`/`"warn"`/`"off"` | нет | `deny` | Глобальная реакция support-guard на правку объектов на замке (см. ниже) | Руками |
@@ -77,7 +79,7 @@
 | `password` | string | нет | Пароль | `/db-list add` или руками |
 | `aliases` | string[] | нет | Альтернативные имена для обращения к базе | `/db-list add` или руками |
 | `branches` | string[] | нет | Git-ветки или glob-паттерны (`release/*`, `feature/*`) | Руками |
-| `configSrc` | string | нет | Каталог XML-выгрузки конфигурации | Руками |
+| `configSrc` | string | нет | Каталог XML-выгрузки конфигурации (рекомендуется `src/cf`, см. структуру ниже). Путь относительный — от корня проекта | Руками |
 | `editingAllowedCheck` | `"deny"`/`"warn"`/`"off"` | нет | Override реакции support-guard для этой базы (см. ниже) | Руками |
 | `skillSuggester` | `"on"`/`"off"` | нет | Override подсказок навыков для этой базы (см. ниже) | Руками |
 | `webUrl` | string | нет | URL веб-клиента для `/web-test` | Руками |
@@ -152,11 +154,44 @@ URL для открытия базы в браузере через `/web-test`.

 Полезно, если веб-клиент доступен по нестандартному адресу (другой порт, внешний сервер, reverse proxy).

+## Рекомендуемая структура проекта
+
+Исходники 1С удобно держать под единым каталогом `src/`:
+
+```
+src/
+  cf/                        # XML-выгрузка конфигурации (configSrc базы → "src\\cf")
+  cfe/<ИмяРасширения>/       # исходники расширения (CFE)
+  epf/<ИмяОбработки>/        # исходники внешней обработки (EPF)
+  erf/<ИмяОтчёта>/           # исходники внешнего отчёта (ERF)
+```
+
+В `.v8-project.json` напрямую участвует только `cf` — через поле `configSrc` базы (`"src\\cf"`).
+Каталоги `cfe`/`epf`/`erf` в конфиг не прописываются: их пути передаются соответствующим навыкам
+аргументами при сборке/разборке (`epf-build -SourceFile src\\epf\\<Имя>\\<Имя>.xml`,
+`cfe-borrow -SrcDir src\\cfe\\<Имя>` и т.п.). Структура — соглашение, а не требование; навыки работают
+с любыми путями.
+
+## Движок: 1cv8 или ibcmd
+
+По умолчанию навыки `/db-*`, `/epf-*`, `/erf-*` работают через конфигуратор (`1cv8.exe`; путь к нему
+определяется автоматически по каталогу `v8path`) — менять это не нужно.
+
+При желании ту же операцию можно выполнить через автономный сервер `ibcmd`. Для этого навык должен
+получить путь к самому файлу `ibcmd.exe` (каталог `bin` всегда трактуется как `1cv8.exe`). Путь
+указывают одним из двух способов:
+- **разово, в самой задаче** — назвать полный путь к `ibcmd.exe`, например
+  `C:\\Program Files\\1cv8\\8.3.24.1691\\bin\\ibcmd.exe`;
+- **в файле настроек** — прописать в `v8path` не каталог `bin`, а сам файл `...\\bin\\ibcmd.exe` (тогда через
+  `ibcmd` пойдут все операции).
+
+Через `ibcmd` поддерживаются только файловые базы. Какие именно навыки это умеют — в [руководстве по базам](db-guide.md#движок-1cv8-или-ibcmd).
+
 ## Минимальный пример

 ```json
 {
-  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
+  "v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
  "databases": [
    {
      "id": "dev",
@@ -172,7 +207,7 @@ URL для открытия базы в браузере через `/web-test`.

 ```json
 {
-  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
+  "v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
  "databases": [
    {
      "id": "dev",
@@ -183,18 +218,18 @@ URL для открытия базы в браузере через `/web-test`.
      "password": "",
      "aliases": ["dev", "разработка"],
      "branches": ["dev", "develop", "feature/*"],
-      "configSrc": "C:\\WS\\myapp\\cfsrc",
+      "configSrc": "src\\cf",
      "webUrl": "http://localhost:8081/dev"
    },
    {
-      "id": "prod",
-      "name": "Рабочая",
+      "id": "test",
+      "name": "Тестовая",
      "type": "server",
      "server": "srv01",
-      "ref": "MyApp_Prod",
-      "user": "Admin",
-      "password": "secret",
-      "aliases": ["prod", "рабочая", "боевая"],
+      "ref": "MyApp_Test",
+      "user": "Администратор",
+      "password": "",
+      "aliases": ["test", "тест", "тестовая"],
      "branches": ["main", "release/*"]
    }
  ],