docs: add .v8-project.json reference guide

Consolidate project config documentation into a single guide covering all fields (v8path, databases, webPath, ffmpegPath, tts, webUrl), with "who fills" column and resolution algorithm. Replace duplicated format sections in db-guide.md and web-guide.md with links to the new guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-10 16:14:54 +03:00 · 2026-03-03 13:14:08 +03:00
parent 6505fb1986
commit 01315839fb
5 changed files with 199 additions and 66 deletions
@@ -38,6 +38,7 @@
 | Базы данных (DB) | 9 навыков `/db-*` | Создание баз, загрузка/выгрузка конфигураций, обновление БД, загрузка из Git | [Подробнее](docs/db-guide.md) |
 | Веб-публикация (Web) | 4 навыка `/web-*` | Публикация баз через Apache, статус, остановка, удаление публикаций | [Подробнее](docs/web-guide.md) |
 | Тестирование (Web) | `/web-test` | Взаимодействие с веб-клиентом 1С — навигация, формы, таблицы, отчёты, тестирование | [Подробнее](docs/web-test-guide.md) |
+| Запись видео (Web) | `/web-test` | Запись видеоинструкций с субтитрами, подсветкой и TTS-озвучкой | [Подробнее](docs/web-test-recording-guide.md) |
 | Утилиты | `/img-grid` | Наложение сетки на изображение для определения пропорций колонок | — |

 ## Требования
@@ -192,9 +193,11 @@ docs/
 ├── cf-guide.md             # Гайд: корневые файлы конфигурации
 ├── cfe-guide.md            # Гайд: расширения конфигурации (CFE)
 ├── subsystem-guide.md      # Гайд: подсистемы и командный интерфейс
+├── v8-project-guide.md     # Гайд: конфигурация проекта (.v8-project.json)
 ├── db-guide.md             # Гайд: базы данных 1С
 ├── web-guide.md            # Гайд: веб-публикация через Apache
 ├── web-test-guide.md       # Гайд: тестирование через веб-клиент
+├── web-test-recording-guide.md # Гайд: запись видеоинструкций
 ├── 1c-epf-spec.md          # Спецификация XML-формата (EPF)
 ├── 1c-erf-spec.md          # Спецификация XML-формата (ERF)
 ├── 1c-form-spec.md         # Спецификация управляемых форм
@@ -37,53 +37,7 @@

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

-Файл размещается в корне проекта (рядом с `.git/`).
-
-```json
-{
-  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
-  "databases": [
-    {
-      "id": "dev",
-      "name": "Разработка",
-      "type": "file",
-      "path": "C:\\Bases\\MyApp_Dev",
-      "user": "Admin",
-      "password": "",
-      "aliases": ["dev", "разработка"],
-      "branches": ["dev", "develop", "feature/*"],
-      "configSrc": "C:\\WS\\myapp\\cfsrc"
-    },
-    {
-      "id": "test",
-      "name": "Тестовая",
-      "type": "server",
-      "server": "srv01",
-      "ref": "MyApp_Test",
-      "user": "Admin",
-      "password": "123",
-      "aliases": ["test", "тест"]
-    }
-  ],
-  "default": "dev"
-}
-```
-
-### Поля базы данных
-
-| Поле | Тип | Обязательное | Описание |
-|------|-----|:------------:|----------|
-| `id` | string | да | Уникальный идентификатор |
-| `name` | string | да | Имя |
-| `type` | `"file"` / `"server"` | да | Тип подключения |
-| `path` | string | для file | Каталог файловой базы |
-| `server` | string | для server | Адрес сервера |
-| `ref` | string | для server | Имя базы на сервере |
-| `user` | string | нет | Пользователь 1С |
-| `password` | string | нет | Пароль |
-| `aliases` | string[] | нет | Альтернативные имена |
-| `branches` | string[] | нет | Git-ветки или glob-паттерны (`release/*`, `feature/*`) |
-| `configSrc` | string | нет | Каталог XML-выгрузки |
+Полное описание формата — в [справочнике .v8-project.json](v8-project-guide.md).

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

@@ -0,0 +1,191 @@
+# Конфигурация проекта (.v8-project.json)
+
+Файл `.v8-project.json` — единый конфиг проекта для всех навыков Claude Code. Хранит пути к платформе 1С, список баз данных и настройки инструментов (Apache, ffmpeg, TTS).
+
+Размещается в корне проекта (рядом с `.git/`). Создаётся навыком `/db-list add` или вручную.
+
+## Полная схема
+
+```jsonc
+{
+  // === Платформа ===
+  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
+
+  // === Базы данных ===
+  "databases": [
+    {
+      "id": "dev",                          // уникальный идентификатор
+      "name": "Разработка",                 // отображаемое имя
+      "type": "file",                       // "file" или "server"
+      "path": "C:\\Bases\\MyApp_Dev",       // каталог (для file)
+      "user": "Admin",                      // пользователь 1С
+      "password": "",                       // пароль
+      "aliases": ["dev", "разработка"],     // альтернативные имена
+      "branches": ["dev", "feature/*"],     // привязка к Git-веткам
+      "configSrc": "C:\\WS\\myapp\\cfsrc",  // каталог XML-выгрузки конфигурации
+      "webUrl": "http://localhost:8081/dev"  // URL веб-клиента (для /web-test)
+    },
+    {
+      "id": "test",
+      "name": "Тестовая",
+      "type": "server",                     // серверная база
+      "server": "srv01",                    // адрес сервера 1С
+      "ref": "MyApp_Test",                  // имя базы на сервере
+      "user": "Admin",
+      "password": "123",
+      "aliases": ["test", "тест"]
+    }
+  ],
+  "default": "dev",
+
+  // === Инструменты ===
+  "webPath": "C:\\tools\\apache24",                  // каталог Apache
+  "ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe", // путь к ffmpeg
+  "tts": {                                            // настройки озвучки
+    "provider": "edge",
+    "voice": "ru-RU-DmitryNeural"
+  }
+}
+```
+
+## Корневые поля
+
+| Поле | Тип | Обяз. | По умолчанию | Описание | Кто заполняет |
+|------|-----|:-----:|-------------|----------|---------------|
+| `v8path` | string | да | — | Путь к каталогу `bin` платформы 1С | `/db-list add` или руками |
+| `databases` | array | да | — | Список баз данных | `/db-list add` |
+| `default` | string | нет | — | `id` базы по умолчанию | `/db-list` |
+| `webPath` | string | нет | `tools/apache24` | Каталог Apache HTTP Server | Руками |
+| `ffmpegPath` | string | нет | `tools/ffmpeg/bin/ffmpeg.exe` | Путь к ffmpeg | Руками |
+| `tts` | object | нет | Edge TTS, DmitryNeural | Настройки озвучки видео | Руками |
+
+## Базы данных (`databases[]`)
+
+| Поле | Тип | Обяз. | Описание | Кто заполняет |
+|------|-----|:-----:|----------|---------------|
+| `id` | string | да | Уникальный идентификатор | `/db-list add` |
+| `name` | string | да | Отображаемое имя | `/db-list add` |
+| `type` | `"file"` / `"server"` | да | Тип подключения | `/db-list add` |
+| `path` | string | для file | Каталог файловой базы | `/db-list add` |
+| `server` | string | для server | Адрес сервера 1С | `/db-list add` |
+| `ref` | string | для server | Имя базы на сервере | `/db-list add` |
+| `user` | string | нет | Пользователь 1С | `/db-list add` или руками |
+| `password` | string | нет | Пароль | `/db-list add` или руками |
+| `aliases` | string[] | нет | Альтернативные имена для обращения к базе | `/db-list add` или руками |
+| `branches` | string[] | нет | Git-ветки или glob-паттерны (`release/*`, `feature/*`) | Руками |
+| `configSrc` | string | нет | Каталог XML-выгрузки конфигурации | Руками |
+| `webUrl` | string | нет | URL веб-клиента для `/web-test` | Руками |
+
+### Разрешение базы
+
+Все навыки `/db-*`, `/epf-build`, `/epf-dump`, `/erf-build`, `/erf-dump`, `/web-publish` используют единый алгоритм:
+
+1. Если пользователь указал **параметры подключения** (путь, сервер) — используются напрямую
+2. Если указал **базу по имени** — поиск: `id` → `aliases` (с учётом морфологии) → `name` (нечёткое)
+3. Если **не указал** — сопоставление текущей ветки Git с `branches` (точно или по glob-паттерну)
+4. Fallback на `default`
+5. Если не найдено — Claude спросит пользователя
+6. Если база не зарегистрирована — Claude предложит `/db-list add`
+
+## Настройки инструментов
+
+### `webPath` — Apache HTTP Server
+
+Путь к каталогу Apache. Используется навыками `/web-publish`, `/web-info`, `/web-stop`, `/web-unpublish`.
+
+Если не задан — ищется в `tools/apache24` от корня проекта. При первом вызове `/web-publish` Apache скачивается автоматически.
+
+Подробнее — в [гайде по веб-публикации](web-guide.md).
+
+### `ffmpegPath` — ffmpeg
+
+Путь к исполняемому файлу ffmpeg. Используется навыком `/web-test` для записи видео.
+
+Если не задан — ищется по порядку:
+1. `tools/ffmpeg/bin/ffmpeg.exe` (от корня проекта)
+2. `ffmpeg` в системном PATH
+
+Подробнее — в [гайде по записи видео](web-test-recording-guide.md).
+
+### `tts` — озвучка видеоинструкций
+
+| Поле | Тип | По умолчанию | Описание |
+|------|-----|-------------|----------|
+| `provider` | string | `"edge"` | Провайдер: `"edge"`, `"elevenlabs"`, `"openai"` |
+| `voice` | string | `"ru-RU-DmitryNeural"` | Голос (имя или ID в зависимости от провайдера) |
+| `apiKey` | string | — | API-ключ (для elevenlabs, openai) |
+| `apiUrl` | string | — | URL сервиса (для openai-совместимых) |
+| `model` | string | — | Модель (для openai) |
+
+Подробнее о выборе провайдера и голосов — в [гайде по записи видео](web-test-recording-guide.md#доступные-голоса-и-провайдеры).
+
+### `webUrl` — URL веб-клиента (per-database)
+
+URL для открытия базы в браузере через `/web-test`. Задаётся в записи конкретной базы.
+
+Если не задан — `/web-test` берёт URL из активной веб-публикации (`/web-publish`).
+
+Полезно, если веб-клиент доступен по нестандартному адресу (другой порт, внешний сервер, reverse proxy).
+
+## Минимальный пример
+
+```json
+{
+  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
+  "databases": [
+    {
+      "id": "dev",
+      "name": "Разработка",
+      "type": "file",
+      "path": "C:\\Bases\\MyApp"
+    }
+  ]
+}
+```
+
+## Полный пример
+
+```json
+{
+  "v8path": "C:\\Program Files\\1cv8\\8.3.25.1257\\bin",
+  "databases": [
+    {
+      "id": "dev",
+      "name": "Разработка",
+      "type": "file",
+      "path": "C:\\Bases\\MyApp_Dev",
+      "user": "Admin",
+      "password": "",
+      "aliases": ["dev", "разработка"],
+      "branches": ["dev", "develop", "feature/*"],
+      "configSrc": "C:\\WS\\myapp\\cfsrc",
+      "webUrl": "http://localhost:8081/dev"
+    },
+    {
+      "id": "prod",
+      "name": "Рабочая",
+      "type": "server",
+      "server": "srv01",
+      "ref": "MyApp_Prod",
+      "user": "Admin",
+      "password": "secret",
+      "aliases": ["prod", "рабочая", "боевая"],
+      "branches": ["main", "release/*"]
+    }
+  ],
+  "default": "dev",
+  "webPath": "C:\\tools\\apache24",
+  "ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe",
+  "tts": {
+    "provider": "edge",
+    "voice": "ru-RU-DmitryNeural"
+  }
+}
+```
+
+## Связанные навыки
+
+- [Базы данных](db-guide.md) — `/db-list`, `/db-create`, `/db-load-xml`, `/db-dump-xml` и другие
+- [Веб-публикация](web-guide.md) — `/web-publish`, `/web-info`, `/web-stop`
+- [Тестирование в браузере](web-test-guide.md) — `/web-test`
+- [Запись видеоинструкций](web-test-recording-guide.md) — запись видео, субтитры, озвучка
@@ -33,28 +33,11 @@
 8. **Проверка** — обновить страницу в браузере
 9. **Завершение** — `/web-stop` остановить Apache

-## Конфигурация `webPath` в `.v8-project.json`
+## Конфигурация в `.v8-project.json`

 Поле `webPath` указывает путь к каталогу Apache. Если не задано, используется `tools/apache24` от корня проекта.

-```json
-{
-  "v8path": "C:\\Program Files\\1cv8\\8.3.24.1691\\bin",
-  "webPath": "C:\\tools\\apache24",
-  "databases": [
-    {
-      "id": "dev",
-      "name": "Разработка",
-      "type": "file",
-      "path": "C:\\Bases\\MyApp_Dev",
-      "user": "Admin"
-    }
-  ],
-  "default": "dev"
-}
-```
-
-> `webPath` — опционально. Если не задан, все навыки `/web-*` ищут Apache в `tools/apache24`.
+Полное описание формата — в [справочнике .v8-project.json](v8-project-guide.md).

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

@@ -8,6 +8,8 @@

 ## Предусловия

+Все пути и настройки хранятся в `.v8-project.json` — см. [справочник формата](v8-project-guide.md).
+
 ### ffmpeg (обязательно)

 Выберите один из вариантов: