Init Commit

2026-09-04 11:48:19 +07:00
commit cb8a79260e
300 changed files with 42404 additions and 0 deletions
@@ -0,0 +1,9 @@
+# CDN Manager
+
+Каркас self-hosted CDN Manager.
+
+- App id (auth-portal): `cdn`
+- Стек: pnpm monorepo, Vite/React/TanStack/ReUI, Fastify/Drizzle/SQLite
+- Образы: `cdnmanager` / `cdn-manager`
+
+См. [README](../README.md) и [AGENTS.md](../AGENTS.md).
@@ -0,0 +1,16 @@
+# Branch protection (configure in Gitea UI)
+
+Apply these rules to **main** and **develop**:
+
+- [ ] Require pull request before merging
+- [ ] Required approvals: 1
+- [ ] Require status checks: `test`
+- [ ] Require branches to be up to date before merging
+- [ ] Include administrators
+- [ ] Prevent force push
+- [ ] Prevent deletion
+
+Repository secrets required for CI:
+
+- `PACKAGE_TOKEN` — registry push
+- `GITEA_TOKEN` — releases and wiki sync
@@ -0,0 +1,87 @@
+# Релизы и версионирование CDN Manager
+
+CDNManager использует [Conventional Commits](https://www.conventionalcommits.org/) и [semantic-release](https://semantic-release.gitbook.io/) для полностью автоматических релизов на Gitea (`git.shx.one`). Ручное повышение версии в коде не требуется.
+
+Заголовок после `тип(scope):` — **на русском** (см. `.cursor/rules/commit-messages-ru.mdc`). Analyzer смотрит только префикс `feat` / `fix` / …
+
+## Как определяется версия
+
+| Тип коммита | Bump |
+|-------------|------|
+| `feat` | minor (1.0.0 → 1.1.0) |
+| `fix`, `perf`, `ci`, `refactor` | patch (1.5.1 → 1.5.2) |
+| `feat!`, `fix!` или `BREAKING CHANGE:` в теле | major (1.0.0 → 2.0.0) |
+| `docs`, `chore`, `test` | без релиза |
+
+**Scope:** один идентификатор **без запятых** (`web`, `api`, `ci`). Заголовок `refactor(a, b): …` **не парсится** semantic-release → релиз не создаётся (commitlint на PR это тоже отклонит).
+
+`refactor` — patch без новых функций: перестройка кода/UI при том же поведении для пользователя.
+
+Первый релиз при отсутствии git-тегов — **1.0.0**, если есть releasable-коммиты.
+
+## CI-пайплайн (push в main)
+
+```text
+push/merge в main
+  → workflow CD: quality (web, api)
+  → job publish:
+       → semantic-release: git tag vX.Y.Z на текущий commit (без доп. commit)
+       → Gitea Release + CHANGELOG.md как attachment
+       → зеркало base-образов в cdnmanager-buildcache:base-*
+       → docker buildx bake с VERSION=X.Y.Z (pull=false, named builder cfdm)
+       → образы: latest, vX.Y.Z, X.Y.Z, sha-*, короткий SHA
+  → job update-wiki (параллельно publish): docs/Home.md → wiki
+```
+
+Pull request: workflow **CI** — quality gates + commitlint; релиз и образы **не** публикуются.
+
+Workflows: [.gitea/workflows/ci.yaml](../.gitea/workflows/ci.yaml), [.gitea/workflows/cd.yaml](../.gitea/workflows/cd.yaml), reusable [.gitea/workflows/quality.yaml](../.gitea/workflows/quality.yaml).
+
+Конфиг semantic-release: [.releaserc.json](../.releaserc.json) — без `@semantic-release/git` (CHANGELOG не коммитится в репозиторий).
+
+## Секреты Gitea
+
+Один PAT — **`ACTIONS_PAT`** (Settings → Actions → Secrets).
+
+| Право PAT | Зачем |
+|-----------|--------|
+| push tags | git tag `vX.Y.Z` на commit merge |
+| releases | Gitea Release + notes |
+| packages (Container Registry) | push образов |
+
+Fallback для **git tag**: `gitea.token`, если PAT недоступен. Push образов в Container Registry — **только `ACTIONS_PAT`** (у job token Gitea нет права packages).
+
+Wiki: секрет **`ACTIONS_PAT`** (fallback `GITEA_TOKEN`) для clone/push `*.wiki.git` на `https://git.shx.one` (не внутренний `GITEA_INSTANCE_URL` раннера). Токен передаётся в URL (`oauth2:<PAT>`): Gitea на неаутентифицированный wiki push отвечает 404, а не 401.
+
+## Источник правды для версии
+
+Semver из git-тега пробрасывается в образ как `APP_VERSION` / `GIT_SHA` / `BUILD_TIME` при bake (`deploy/docker/cfdm/Dockerfile`).
+
+## Scope и semantic-release
+
+Парсер conventional-commits **не понимает запятые в scope**. Правило: **один scope** (`web`, `api`, `ci`, `docker`).
+
+На push в `main` job **publish** запускает `scripts/commit/verify-release-commits.mjs` — в логе будут предупреждения о непарсящихся коммитах.
+
+Если релиз «не создался», а CI зелёный: смотрите лог release — часто `No releasable commits`. Исправление: новый коммит с корректным заголовком (например `fix(web): …`).
+
+## Перезапуск упавшего job publish
+
+semantic-release пишет `.release-version` только в `successCmd` при **новом** релизе. Если тег `vX.Y.Z` уже создан, а `docker buildx bake` упал, повторный run того же SHA делает semantic-release no-op (файла нет). Job **publish** тогда берёт версию из git-тега на `HEAD` и публикует образы.
+
+Перезапускать нужно **весь job publish**, не отдельный шаг bake: checkout + semantic-release + detect + bake идут подряд.
+
+## CHANGELOG
+
+Release notes — в Gitea Release; файл `CHANGELOG.md` генерируется в CI и прикрепляется как asset, **не** попадает в git history.
+
+## Проверка после релиза
+
+1. Один run workflow **CD** на push в main: job **publish** зелёный.
+2. Gitea: тег `vX.Y.Z` на том же commit, что и merge; Release с notes.
+3. Container Registry: `cfdm:vX.Y.Z`, `cfdm:X.Y.Z`, `cfdm:latest` и алиас `cdn-manager` с теми же тегами.
+4. `curl http://localhost:8080/health` → `"status":"ok"`.
+
+## Первый релиз (bootstrap)
+
+Merge в `main` с `feat(release): …` → **v1.0.0** в том же CI run.
@@ -0,0 +1,119 @@
+# UI Design Contract (ops apps)
+
+Единый контракт для **CDNManager · vps-tracker · EvoBGP · EvoFirewall · auth-portal**.  
+Surface: **ReUI Frame**. Kit: `apps/web/src/components/reui-kit/`.  
+Иерархия: **ReUI PRO > shadcn primitives**.
+
+Карта: [docs](https://reui.io/docs) · [llms.txt](https://reui.io/llms.txt) · [Get Started](https://reui.io/docs/get-started) · [Styling](https://reui.io/docs/styling) · [Registry](https://reui.io/docs/registry) · [License](https://reui.io/docs/license-setup) · [Blocks](https://reui.io/blocks) · [MCP](https://reui.io/docs/mcp) · [Agent Skills](https://reui.io/docs/agent-skills)
+
+## Surface
+
+Project lock: **`surface: frame`**. Ops / list / dashboard / detail / settings — только **Frame**, не shadcn Card как shell. Не смешивать Card и Frame на одном ops-экране.
+
+```ts
+// apps/web/src/lib/ui-surface.ts (где есть)
+export const UI_SURFACE = 'frame' as const
+```
+
+Settings: секции через Frame + `gap` (без hairline `Separator` под PageHeader); `SettingRow` без `FieldSeparator` по умолчанию (`separated` opt-in). Preview: [settings-3](https://reui.io/preview/base/settings-3) · [settings-16](https://reui.io/preview/base/settings-16).
+
+## Canonical PRO references
+
+| Зона | Block | Preview |
+|------|-------|---------|
+| Shell | `app-shell-12` (+ cmdk/monitor где нужно) | https://reui.io/preview/base/app-shell-12 · https://reui.io/preview/base/app-shell-7 |
+| KPI | horizontal compact hybrid (EvoBGP SoT: icon left + label/Badge + value ± variant) | https://reui.io/preview/base/stats-12 |
+| Quick Actions | Frame tiles (sibling KPI) + Badge «Перейти» | https://reui.io/preview/base/stats-12 · https://reui.io/preview/base/card-12 |
+| Dashboard | `dashboard-1` | https://reui.io/preview/base/dashboard-1 |
+| Lists | `data-grid-filtering-2` | https://reui.io/preview/base/data-grid-filtering-2 |
+| Settings | `settings-16` + SettingRow | https://reui.io/preview/base/settings-16 |
+| Auth | `auth-13` | https://reui.io/preview/base/auth-13 |
+| Empty | `empty-state-14` (prefer) / `empty-state-12` | https://reui.io/preview/base/empty-state-14 · https://reui.io/preview/base/empty-state-12 |
+| Forms | `form-7` → Sheet/Drawer | https://reui.io/preview/base/form-7 |
+
+## Kit API (`reui-kit/`)
+
+| Component | Role |
+|-----------|------|
+| `ResourcePage` | Frame + line tabs + Filters + DataGrid |
+| `KpiStatGrid` | EvoBGP hybrid KPI tiles (`items`/`cards`, `variant`, Badge) |
+| `QuickActionGrid` | KPI-like quick action tiles (gated by `showQuickActions`) |
+| `OpsDashboard` | KPI + optional `afterKpi` + charts + attention queue |
+| `SettingsShell` | settings nav + Outlet |
+| `DetailPanel` | detail Frame sections |
+| `filter-utils` | apply/clear ReUI Filters |
+
+`KpiStatGrid` / `QuickActionGrid` markup — SoT **EvoBGP**; в остальных apps diff только `@scope/ui` imports.
+
+## Dashboard layout
+
+| App | Section order |
+|-----|---------------|
+| EvoBGP / CDNManager / EvoFirewall | KPI → **QuickActionGrid** → charts / rest |
+| vps-tracker | banner → KPI → charts → attention → **QuickActionGrid** → CSV |
+| auth-portal | portal-specific; Quick Actions при наличии dashboard |
+
+Gating: DB `show_quick_actions` / `showQuickActions` / `ui_show_quick_actions` (default `true`).
+
+## Shared App Shell chrome
+
+Эталон разметки: production apps + ReUI [app-shell-12](https://reui.io/preview/base/app-shell-12).  
+При переключении между apps меняются **только** sidebar nav labels/hrefs и `main` content.
+
+| Токен / зона | Значение |
+|--------------|----------|
+| `SIDEBAR_WIDTH` / `--sidebar-width` | `240px` |
+| Sidebar / hover colors | theme `--sidebar` / `--sidebar-accent` — **без** AppShell `color-mix` override |
+| Header | `h-12`, `sticky`, `border-b`, `px-4 md:px-6` |
+| Header left | `SidebarTrigger` + `Separator` + Breadcrumb |
+| Header right | **AppsMenu** → **SystemMonitorPopover** (тема — в NavUser) |
+| Sidebar | AppSwitcher → groups → icons `size-4` → **NavUser** в `SidebarFooter` |
+| `main` | `gap-4 md:gap-6`, `px-4 py-4 md:px-6 md:py-5` |
+| Search | hotkey ⌘K / Ctrl+K only (не кнопка в header) |
+
+Запрещено в chrome: `SidebarRail`, sync-row footer, Search pill в header, issues Badge в header, `ModeToggle` в header (тема только в NavUser), Provider `color-mix` для `--sidebar*`.
+
+NavUser (footer): avatar + name/email; dropdown — Настройки / Тема (segmented) / Выйти. Preview: [app-shell-1](https://reui.io/preview/base/app-shell-1).
+
+App Switcher: auth-portal `GET /api/v1/app-switcher`. Ids: `cfdm` · `vps` · `bgp` · `fw` · `dns` · `cdn`. Admin: portal `/admin/apps`.
+
+QuickActionGrid / KPI icons: только semantic **text** (`text-info` / `text-primary` / …) на `IconTile` `elevated` — без solid fills.
+
+## System monitor
+
+`SystemMonitorPopover` in header after AppsMenu. Preview: https://reui.io/preview/base/app-shell-12 · https://reui.io/preview/base/app-shell-7
+
+## MCP workflow
+
+1. MCP `user-reui` — `search` / `get_block` / `compose_page` / `get_component` with `surface: "frame"`
+2. Cite `previewUrl` + `docsUrl`
+3. CLI from `apps/web`: `pnpm dlx shadcn@latest add @reui/...`
+4. Adapt into kit — do not hand-roll KPI / Quick Actions / grid / settings rows
+5. `validate_usage` / `get_audit_checklist`
+
+Primitives: MCP `plugin-shadcn-shadcn` + project `@scope/ui` (`@cdnmanager/ui` / `@evobgp/ui` / `@evofw/ui` / `@authportal/ui`).
+
+## License
+
+```env
+# apps/web/.env.local (gitignored)
+REUI_LICENSE_KEY=
+```
+
+`apps/web/components.json` → `@reui` с `Authorization: Bearer ${REUI_LICENSE_KEY}`.
+
+## Spacing
+
+- AppShell main / PageShell: `gap-4 md:gap-6`, `px-4 py-4 md:px-6 md:py-5`
+- No `space-y-*` / `space-x-*` — use `flex` + `gap-*`
+- Max 1 primary CTA per screen
+- Semantic tokens only — no raw `bg-emerald-*`
+
+## Forbidden
+
+- Card as ops list/dashboard shell
+- Hand-rolled data tables when ReUI DataGrid / `ResourcePage` exists
+- Hand-rolled KPI when `KpiStatGrid` exists
+- Hand-rolled Quick Actions when `QuickActionGrid` exists
+- SectionCards / DataGridCard as design эталон
+- Mixing Card and Frame surfaces on one ops screen