docs(article): добавлен гайд по встраиванию веб-GUI в CLI

2025-09-10 12:55:29 +06:00
parent fd6cee4535
commit 539d9c492d
1 changed files with 173 additions and 0 deletions
--- a/article/embed-gui-guide.md
+++ b/article/embed-gui-guide.md
@@ -0,0 +1,173 @@
+# Встраиваем веб-GUI в консольную утилиту: практический гайд
+
+```metadata
+id: 10
+readTime: 15-20 минут
+date: 2025-09-10 18:00
+author: Direct-Dev (aka Антон Кузнецов)
+level: Средний
+tags: #go #angular #spa #embed #static #cli #webui #devops
+version: 1.0.0
+```
+
+## Содержание
+
+1. [Введение](#введение)
+2. [Идея и архитектура](#идея-и-архитектура)
+3. [Минимальный GUI](#минимальный-gui)
+4. [Сборка фронтенда](#сборка-фронтенда)
+5. [Встраивание в Go-сервис](#встраивание-в-go-сервис)
+6. [API: контракт и примеры](#api-контракт-и-примеры)
+7. [Запуск и проверка](#запуск-и-проверка)
+8. [FAQ и типичные ошибки](#faq-и-типичные-ошибки)
+
+## Введение
+
+Задача: добавить простой веб-интерфейс к консольной утилите, собрать его один раз и отдавать статические файлы прямо из бинарника или из каталога рядом. В качестве примера используем минимальный UI со следующими полями:
+- Targets (строка вида `tcp:host:port;udp:host:port`)
+- Delay (например `1s`)
+- Флаг Wait connection
+- Кнопка Execute
+
+## Идея и архитектура
+
+- **Фронтенд (Angular SPA)** собирается в статический набор файлов (`index.html`, `main-*.js`, `styles-*.css`, и т.д.).
+- **Бэкенд (Go, Gin/Chi/Stdlib)** отдаёт эти файлы по `/` и реализует API по `/api/...`.
+- Раздача статики может быть:
+  - из файловой системы (проще для разработки);
+  - через `embed.FS` (удобно для единого бинарника).
+
+## Минимальный GUI
+
+Мы упростили компонент до минимума в ветке `for-article`. Основной экран — одна форма и кнопка запуска.
+
+Ключевой шаблон компонента:
+```12:60:/home/su/projects/articles/embed-gui-article/ui/src/app/knock/knock-page.component.html
+<div class="container">
+  <p-card header="Port Knocker (Минимальный UI)">
+    <form [formGroup]="form" (ngSubmit)="execute()" class="p-fluid">
+      <div class="grid">
+        <div class="col-12">
+          <label>Targets</label>
+          <input pInputText type="text" formControlName="targets" placeholder="tcp:host:port;udp:host:port" class="w-full" />
+        </div>
+        <div class="col-12 md:col-6">
+          <label>Delay</label>
+          <input pInputText type="text" formControlName="delay" placeholder="1s" class="w-full" />
+        </div>
+        <div class="col-12 md:col-6 flex align-items-center gap-2">
+          <p-checkbox formControlName="waitConnection" [binary]="true"></p-checkbox>
+          <label class="checkbox-label">Wait connection</label>
+        </div>
+        <div class="col-12">
+          <button pButton type="submit" label="Execute" class="w-full" [loading]="executing" [disabled]="executing || form.invalid"></button>
+        </div>
+      </div>
+    </form>
+  </p-card>
+</div>
+```
+
+Логика отправки запроса:
+```1:40:/home/su/projects/articles/embed-gui-article/ui/src/app/knock/knock-page.component.ts
+this.http.post('/api/v1/knock-actions/execute', {
+  targets: v.targets,
+  delay: v.delay,
+  waitConnection: v.waitConnection
+}).subscribe(...)
+```
+
+## Сборка фронтенда
+
+Собираем Angular-приложение и копируем артефакты в каталог, из которого Go-сервис будет обслуживать статику.
+
+Скрипт сборки:
+```1:20:/home/su/projects/articles/embed-gui-article/ui/build-for-embeding.sh
+#!/bin/bash
+# Использование: ./build-for-embeding.sh /abs/path/to/back/cmd/public
+npx ng build --configuration production
+mkdir -p "$DESTINATION_DIR"
+cp -r /home/su/projects/angular/project-front/dist/project-front/browser/* "$DESTINATION_DIR"
+```
+
+- Артефакты после `ng build` лежат в `ui/dist/project-front/browser/`.
+- Рекомендуемая папка для копирования: `back/cmd/public/` (в проекте уже есть пример статики).
+
+## Встраивание в Go-сервис
+
+Вариант А: раздача файлов из папки (`back/cmd/public`).
+- Положите файлы фронта в `back/cmd/public`.
+- Убедитесь, что роутер отдаёт `/` и `/*` из этой папки.
+
+Вариант Б: `embed.FS` в бинарник.
+
+Пример (концептуально):
+```go
+package main
+
+import (
+  "embed"
+  "net/http"
+)
+
+//go:embed public/**
+var webFS embed.FS
+
+func main() {
+  // http.FileServerFS доступен в Go 1.22+, иначе используйте fs.Sub
+  http.Handle("/", http.FileServer(http.FS(webFS)))
+  http.HandleFunc("/api/v1/knock-actions/execute", executeHandler)
+  http.ListenAndServe(":8080", nil)
+}
+```
+
+В репозитории уже есть бэкенд с маршрутами и готовой статикой в `back/cmd/public/`. Для статьи достаточно положить собранный фронт туда.
+
+## API: контракт и примеры
+
+Endpoint: `POST /api/v1/knock-actions/execute`
+
+Request JSON:
+```json
+{
+  "targets": "tcp:127.0.0.1:22;udp:1.2.3.4:53",
+  "delay": "1s",
+  "waitConnection": false
+}
+```
+
+Response 200:
+```json
+{ "status": "ok" }
+```
+
+Пример curl:
+```bash
+curl -X POST http://localhost:8080/api/v1/knock-actions/execute \
+  -H 'Content-Type: application/json' \
+  -d '{"targets":"tcp:127.0.0.1:22","delay":"1s","waitConnection":false}'
+```
+
+## Запуск и проверка
+
+1) Собрать фронт и скопировать файлы:
+```bash
+cd /home/su/projects/articles/embed-gui-article/ui
+./build-for-embeding.sh /home/su/projects/articles/embed-gui-article/back/cmd/public
+```
+
+2) Запустить бэкенд (варианты):
+- Через make/скрипт, если есть.
+- Локально `go run ./back` (или соответствующая команда в вашем проекте).
+
+3) Открыть в браузере `/` и проверить, что форма грузится, а `Execute` бьёт в API.
+
+## FAQ и типичные ошибки
+
+- Статика не находится: проверьте путь копирования и что сервер обслуживает каталог.
+- SPA роуты дают 404 при F5: настройте отдачу `index.html` по умолчанию.
+- CORS при раздельных портах: либо проксируйте, либо включите CORS в сервере.
+
+---
+
+Этот гайд показывает минимальный путь: собрать веб-UI, скопировать в папку статики бэкенда и обеспечить один API‑эндпоинт. Для production можно добавить `embed.FS`, версионирование артефактов и CI/CD.