diff --git a/README.md b/README.md index 46dcedba..577d87e1 100644 --- a/README.md +++ b/README.md @@ -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 # Спецификация управляемых форм diff --git a/docs/db-guide.md b/docs/db-guide.md index 459cdf44..c238a545 100644 --- a/docs/db-guide.md +++ b/docs/db-guide.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). ### Разрешение базы diff --git a/docs/v8-project-guide.md b/docs/v8-project-guide.md new file mode 100644 index 00000000..80dd7984 --- /dev/null +++ b/docs/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) — запись видео, субтитры, озвучка diff --git a/docs/web-guide.md b/docs/web-guide.md index 49d2e83d..e28ab3d1 100644 --- a/docs/web-guide.md +++ b/docs/web-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). ## Сценарии использования diff --git a/docs/web-test-recording-guide.md b/docs/web-test-recording-guide.md index cf94afc1..80a18eaf 100644 --- a/docs/web-test-recording-guide.md +++ b/docs/web-test-recording-guide.md @@ -8,6 +8,8 @@ ## Предусловия +Все пути и настройки хранятся в `.v8-project.json` — см. [справочник формата](v8-project-guide.md). + ### ffmpeg (обязательно) Выберите один из вариантов: