Add instructions management functionality and update related components
CI / Backend (build + test) (push) Successful in 1m17s
CI / Frontend (lint + typecheck + build) (push) Successful in 32s

- Introduced new endpoints for managing instruction intros and tabs, allowing admins to create, update, and delete instructional content.
- Enhanced the FactoryResetCommandHandler to include the seeding of instruction data during a factory reset.
- Updated the database schema to include InstructionIntro and InstructionTab entities, with corresponding migrations.
- Improved frontend routing and components to support the new instructions section, including a dedicated page for displaying instructions and tabs.
- Enhanced API documentation to reflect the new instruction management features and their expected request/response formats.
- Added localization support for the new instructions functionality in both Russian and English.
This commit is contained in:
Leonid Pershin
2026-07-14 22:20:10 +03:00
parent 8c53fcded2
commit bef3880593
52 changed files with 2303 additions and 24 deletions
@@ -0,0 +1,52 @@
import { useState } from 'react'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { useTranslation } from 'react-i18next'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import { toast } from '@/shared/ui/toast-store'
import { Button } from '@/shared/ui/button'
import { Textarea } from '@/shared/ui/textarea'
import { HttpError } from '@/shared/api/client'
import type { InstructionIntroDto } from '@/shared/api/types'
import { updateInstructionIntro } from './api'
export function InstructionIntroEditor({ intro }: { intro: InstructionIntroDto }) {
const { t } = useTranslation()
const queryClient = useQueryClient()
const [body, setBody] = useState(intro.body)
const [previewMode, setPreviewMode] = useState(false)
const mutation = useMutation({
mutationFn: () => updateInstructionIntro(body.trim()),
onSuccess: async () => {
toast.success(t('admin.instructions.introSaved'))
await queryClient.invalidateQueries({ queryKey: ['instruction-intro'] })
},
onError: (error) => toast.error(error instanceof HttpError ? error.detail : t('auth.genericError')),
})
const isDirty = body.trim() !== intro.body.trim()
return (
<div className="flex flex-col gap-3">
<div className="flex items-center justify-between">
<p className="text-sm text-muted-foreground">{t('admin.instructions.introHint')}</p>
<Button type="button" size="sm" variant="ghost" onClick={() => setPreviewMode((v) => !v)}>
{t('admin.news.preview')}
</Button>
</div>
{previewMode ? (
<div className="flex min-h-32 flex-col gap-2 rounded-md border border-border px-3 py-2 text-sm [&_a]:text-primary [&_a]:hover:underline [&_li]:ml-4 [&_ul]:list-disc [&_ol]:list-decimal">
<ReactMarkdown remarkPlugins={[remarkGfm]}>{body || t('admin.instructions.tabBody')}</ReactMarkdown>
</div>
) : (
<Textarea value={body} onChange={(e) => setBody(e.target.value)} rows={8} />
)}
<div>
<Button disabled={!body.trim() || !isDirty || mutation.isPending} onClick={() => mutation.mutate()}>
{t('admin.roles.save')}
</Button>
</div>
</div>
)
}
@@ -0,0 +1,100 @@
import { useState } from 'react'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { useTranslation } from 'react-i18next'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import { toast } from '@/shared/ui/toast-store'
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/shared/ui/dialog'
import { Button } from '@/shared/ui/button'
import { Input } from '@/shared/ui/input'
import { Label } from '@/shared/ui/label'
import { Textarea } from '@/shared/ui/textarea'
import { HttpError } from '@/shared/api/client'
import type { InstructionTabDto } from '@/shared/api/types'
import { createInstructionTab, updateInstructionTab } from './api'
export function InstructionTabFormDialog({
tab,
open,
onOpenChange,
}: {
tab?: InstructionTabDto
open?: boolean
onOpenChange?: (open: boolean) => void
}) {
const { t } = useTranslation()
const queryClient = useQueryClient()
const [internalOpen, setInternalOpen] = useState(false)
const [title, setTitle] = useState(tab?.title ?? '')
const [body, setBody] = useState(tab?.body ?? '')
const [sortOrder, setSortOrder] = useState(String(tab?.sortOrder ?? 0))
const [previewMode, setPreviewMode] = useState(false)
const isControlled = open !== undefined
const dialogOpen = isControlled ? open : internalOpen
const setDialogOpen = isControlled ? onOpenChange! : setInternalOpen
const mutation = useMutation({
mutationFn: () =>
tab
? updateInstructionTab(tab.id, title.trim(), body.trim(), Number(sortOrder))
: createInstructionTab(title.trim(), body.trim(), Number(sortOrder)),
onSuccess: async () => {
toast.success(tab ? t('admin.instructions.tabUpdated') : t('admin.instructions.tabCreated'))
await queryClient.invalidateQueries({ queryKey: ['instruction-tabs'] })
setDialogOpen(false)
},
onError: (error) => toast.error(error instanceof HttpError ? error.detail : t('auth.genericError')),
})
const canSubmit = title.trim() && body.trim()
return (
<Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
{!isControlled && (
<DialogTrigger asChild>
<Button size="sm">{t('admin.instructions.createTab')}</Button>
</DialogTrigger>
)}
<DialogContent>
<DialogHeader>
<DialogTitle>{tab ? tab.title : t('admin.instructions.createTab')}</DialogTitle>
</DialogHeader>
<form
className="flex flex-col gap-4"
onSubmit={(e) => {
e.preventDefault()
if (canSubmit) mutation.mutate()
}}
>
<div className="flex flex-col gap-1.5">
<Label htmlFor="tabTitle">{t('admin.instructions.tabTitle')}</Label>
<Input id="tabTitle" value={title} onChange={(e) => setTitle(e.target.value)} required />
</div>
<div className="flex flex-col gap-1.5">
<div className="flex items-center justify-between">
<Label htmlFor="tabBody">{t('admin.instructions.tabBody')}</Label>
<Button type="button" size="sm" variant="ghost" onClick={() => setPreviewMode((v) => !v)}>
{t('admin.news.preview')}
</Button>
</div>
{previewMode ? (
<div className="flex min-h-32 flex-col gap-2 rounded-md border border-border px-3 py-2 text-sm [&_a]:text-primary [&_a]:hover:underline [&_li]:ml-4 [&_ul]:list-disc [&_ol]:list-decimal">
<ReactMarkdown remarkPlugins={[remarkGfm]}>{body || t('admin.instructions.tabBody')}</ReactMarkdown>
</div>
) : (
<Textarea id="tabBody" value={body} onChange={(e) => setBody(e.target.value)} required />
)}
</div>
<div className="flex flex-col gap-1.5">
<Label htmlFor="tabSortOrder">{t('admin.apps.sortOrder')}</Label>
<Input id="tabSortOrder" type="number" min={0} value={sortOrder} onChange={(e) => setSortOrder(e.target.value)} />
</div>
<Button type="submit" disabled={!canSubmit || mutation.isPending}>
{tab ? t('admin.roles.save') : t('admin.instructions.createTab')}
</Button>
</form>
</DialogContent>
</Dialog>
)
}
@@ -0,0 +1,24 @@
import { apiRequest } from '@/shared/api/client'
import type { InstructionIntroDto, InstructionTabDto } from '@/shared/api/types'
export function updateInstructionIntro(body: string) {
return apiRequest<InstructionIntroDto>('/admin/instructions/intro', { method: 'PUT', body: { body } })
}
export function createInstructionTab(title: string, body: string, sortOrder: number) {
return apiRequest<InstructionTabDto>('/admin/instructions/tabs', {
method: 'POST',
body: { title, body, sortOrder },
})
}
export function updateInstructionTab(id: string, title: string, body: string, sortOrder: number) {
return apiRequest<InstructionTabDto>(`/admin/instructions/tabs/${id}`, {
method: 'PUT',
body: { title, body, sortOrder },
})
}
export function deleteInstructionTab(id: string) {
return apiRequest<void>(`/admin/instructions/tabs/${id}`, { method: 'DELETE' })
}
+10
View File
@@ -0,0 +1,10 @@
import { apiRequest } from '@/shared/api/client'
import type { InstructionIntroDto, InstructionTabDto } from '@/shared/api/types'
export function getInstructionIntro() {
return apiRequest<InstructionIntroDto>('/instructions/intro')
}
export function listInstructionTabs() {
return apiRequest<InstructionTabDto[]>('/instructions/tabs')
}
+21
View File
@@ -25,6 +25,7 @@ import { Route as AdminRolesRouteImport } from './routes/admin/roles'
import { Route as AdminNodesRouteImport } from './routes/admin/nodes'
import { Route as AdminNewsRouteImport } from './routes/admin/news'
import { Route as AdminMaintenanceRouteImport } from './routes/admin/maintenance'
import { Route as AdminInstructionsRouteImport } from './routes/admin/instructions'
import { Route as AdminConfigsRouteImport } from './routes/admin/configs'
import { Route as AdminAuditRouteImport } from './routes/admin/audit'
import { Route as AdminAppsRouteImport } from './routes/admin/apps'
@@ -110,6 +111,11 @@ const AdminMaintenanceRoute = AdminMaintenanceRouteImport.update({
path: '/maintenance',
getParentRoute: () => AdminRoute,
} as any)
const AdminInstructionsRoute = AdminInstructionsRouteImport.update({
id: '/instructions',
path: '/instructions',
getParentRoute: () => AdminRoute,
} as any)
const AdminConfigsRoute = AdminConfigsRouteImport.update({
id: '/configs',
path: '/configs',
@@ -145,6 +151,7 @@ export interface FileRoutesByFullPath {
'/admin/apps': typeof AdminAppsRoute
'/admin/audit': typeof AdminAuditRoute
'/admin/configs': typeof AdminConfigsRoute
'/admin/instructions': typeof AdminInstructionsRoute
'/admin/maintenance': typeof AdminMaintenanceRoute
'/admin/news': typeof AdminNewsRoute
'/admin/nodes': typeof AdminNodesRoute
@@ -166,6 +173,7 @@ export interface FileRoutesByTo {
'/admin/apps': typeof AdminAppsRoute
'/admin/audit': typeof AdminAuditRoute
'/admin/configs': typeof AdminConfigsRoute
'/admin/instructions': typeof AdminInstructionsRoute
'/admin/maintenance': typeof AdminMaintenanceRoute
'/admin/news': typeof AdminNewsRoute
'/admin/nodes': typeof AdminNodesRoute
@@ -189,6 +197,7 @@ export interface FileRoutesById {
'/admin/apps': typeof AdminAppsRoute
'/admin/audit': typeof AdminAuditRoute
'/admin/configs': typeof AdminConfigsRoute
'/admin/instructions': typeof AdminInstructionsRoute
'/admin/maintenance': typeof AdminMaintenanceRoute
'/admin/news': typeof AdminNewsRoute
'/admin/nodes': typeof AdminNodesRoute
@@ -213,6 +222,7 @@ export interface FileRouteTypes {
| '/admin/apps'
| '/admin/audit'
| '/admin/configs'
| '/admin/instructions'
| '/admin/maintenance'
| '/admin/news'
| '/admin/nodes'
@@ -234,6 +244,7 @@ export interface FileRouteTypes {
| '/admin/apps'
| '/admin/audit'
| '/admin/configs'
| '/admin/instructions'
| '/admin/maintenance'
| '/admin/news'
| '/admin/nodes'
@@ -256,6 +267,7 @@ export interface FileRouteTypes {
| '/admin/apps'
| '/admin/audit'
| '/admin/configs'
| '/admin/instructions'
| '/admin/maintenance'
| '/admin/news'
| '/admin/nodes'
@@ -391,6 +403,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof AdminMaintenanceRouteImport
parentRoute: typeof AdminRoute
}
'/admin/instructions': {
id: '/admin/instructions'
path: '/instructions'
fullPath: '/admin/instructions'
preLoaderRoute: typeof AdminInstructionsRouteImport
parentRoute: typeof AdminRoute
}
'/admin/configs': {
id: '/admin/configs'
path: '/configs'
@@ -427,6 +446,7 @@ interface AdminRouteChildren {
AdminAppsRoute: typeof AdminAppsRoute
AdminAuditRoute: typeof AdminAuditRoute
AdminConfigsRoute: typeof AdminConfigsRoute
AdminInstructionsRoute: typeof AdminInstructionsRoute
AdminMaintenanceRoute: typeof AdminMaintenanceRoute
AdminNewsRoute: typeof AdminNewsRoute
AdminNodesRoute: typeof AdminNodesRoute
@@ -441,6 +461,7 @@ const AdminRouteChildren: AdminRouteChildren = {
AdminAppsRoute: AdminAppsRoute,
AdminAuditRoute: AdminAuditRoute,
AdminConfigsRoute: AdminConfigsRoute,
AdminInstructionsRoute: AdminInstructionsRoute,
AdminMaintenanceRoute: AdminMaintenanceRoute,
AdminNewsRoute: AdminNewsRoute,
AdminNodesRoute: AdminNodesRoute,
+1
View File
@@ -13,6 +13,7 @@ const TABS = [
{ to: '/admin/roles', key: 'roles' },
{ to: '/admin/nodes', key: 'nodes' },
{ to: '/admin/apps', key: 'apps' },
{ to: '/admin/instructions', key: 'instructions' },
{ to: '/admin/news', key: 'news' },
{ to: '/admin/support', key: 'support' },
{ to: '/admin/audit', key: 'audit' },
@@ -0,0 +1,98 @@
import { useState } from 'react'
import { createFileRoute } from '@tanstack/react-router'
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
import { useTranslation } from 'react-i18next'
import { toast } from '@/shared/ui/toast-store'
import { Button } from '@/shared/ui/button'
import { Card, CardContent, CardHeader, CardTitle } from '@/shared/ui/card'
import { getInstructionIntro, listInstructionTabs } from '@/features/instructions/api'
import { deleteInstructionTab } from '@/features/admin/instructions/api'
import { InstructionIntroEditor } from '@/features/admin/instructions/InstructionIntroEditor'
import { InstructionTabFormDialog } from '@/features/admin/instructions/InstructionTabFormDialog'
import type { InstructionTabDto } from '@/shared/api/types'
export const Route = createFileRoute('/admin/instructions')({ component: AdminInstructionsPage })
function AdminInstructionsPage() {
const { t } = useTranslation()
const queryClient = useQueryClient()
const [editingTab, setEditingTab] = useState<InstructionTabDto | null>(null)
const introQuery = useQuery({ queryKey: ['instruction-intro'], queryFn: getInstructionIntro })
const tabsQuery = useQuery({ queryKey: ['instruction-tabs'], queryFn: listInstructionTabs })
const deleteMutation = useMutation({
mutationFn: deleteInstructionTab,
onSuccess: async () => {
toast.success(t('admin.instructions.tabDeleted'))
await queryClient.invalidateQueries({ queryKey: ['instruction-tabs'] })
},
onError: () => toast.error(t('auth.genericError')),
})
return (
<div className="flex flex-col gap-6">
<Card>
<CardHeader>
<CardTitle className="text-base">{t('admin.instructions.introTitle')}</CardTitle>
</CardHeader>
<CardContent>
{introQuery.isLoading && <p className="text-sm text-muted-foreground"></p>}
{introQuery.data && <InstructionIntroEditor intro={introQuery.data} />}
</CardContent>
</Card>
<div className="flex flex-col gap-4">
<div className="flex items-center justify-between">
<h2 className="text-lg font-semibold tracking-tight">{t('admin.instructions.tabsTitle')}</h2>
<InstructionTabFormDialog />
</div>
{tabsQuery.isLoading && <p className="text-sm text-muted-foreground"></p>}
{tabsQuery.isError && (
<div className="flex items-center gap-2">
<p className="text-sm text-muted-foreground">{t('auth.genericError')}</p>
<Button variant="outline" size="sm" onClick={() => void tabsQuery.refetch()}>
{t('activation.retry')}
</Button>
</div>
)}
{tabsQuery.data?.length === 0 && <p className="text-sm text-muted-foreground">{t('admin.instructions.tabsEmpty')}</p>}
{tabsQuery.data && tabsQuery.data.length > 0 && (
<div className="flex flex-col gap-2">
{tabsQuery.data.map((tab) => (
<div key={tab.id} className="flex items-center justify-between rounded-md border border-border px-3 py-2 text-sm">
<div className="flex flex-col">
<span>{tab.title}</span>
<span className="text-xs text-muted-foreground">{t('admin.apps.sortOrder')}: {tab.sortOrder}</span>
</div>
<div className="flex gap-2">
<Button size="sm" variant="outline" onClick={() => setEditingTab(tab)}>
{t('admin.roles.edit')}
</Button>
<Button
size="sm"
variant="ghost"
disabled={deleteMutation.isPending}
onClick={() => {
if (confirm(t('admin.instructions.confirmDeleteTab'))) deleteMutation.mutate(tab.id)
}}
>
{t('admin.roles.delete')}
</Button>
</div>
</div>
))}
</div>
)}
</div>
{editingTab && (
<InstructionTabFormDialog tab={editingTab} open={!!editingTab} onOpenChange={(open) => !open && setEditingTab(null)} />
)}
</div>
)
}
+53 -9
View File
@@ -1,32 +1,76 @@
import { useState } from 'react'
import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'
import { useTranslation } from 'react-i18next'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import { useRequireActivated } from '@/features/auth/guards'
import { AppsCatalog } from '@/features/apps/AppsCatalog'
import { getInstructionIntro, listInstructionTabs } from '@/features/instructions/api'
import { cn } from '@/shared/lib/cn'
export const Route = createFileRoute('/instructions')({ component: InstructionsPage })
const APPS_TAB_ID = '__apps__'
const MARKDOWN_CLASSES = '[&_a]:text-primary [&_a]:hover:underline [&_li]:ml-4 [&_ul]:list-disc [&_ol]:list-decimal'
function InstructionsPage() {
const { t } = useTranslation()
const { isReady } = useRequireActivated()
const introQuery = useQuery({ queryKey: ['instruction-intro'], queryFn: getInstructionIntro })
const tabsQuery = useQuery({ queryKey: ['instruction-tabs'], queryFn: listInstructionTabs })
const [activeTab, setActiveTab] = useState(APPS_TAB_ID)
if (!isReady) return null
const tabs = tabsQuery.data ?? []
const activeExtraTab = tabs.find((tab) => tab.id === activeTab)
return (
<div className="mx-auto flex w-full max-w-4xl flex-col gap-8 px-6 py-10">
<div>
<h1 className="text-2xl font-semibold tracking-tight">{t('instructions.title')}</h1>
<p className="mt-1 text-sm text-muted-foreground">{t('instructions.intro')}</p>
{introQuery.data?.body && (
<div className={cn('mt-2 flex flex-col gap-2 text-sm text-muted-foreground', MARKDOWN_CLASSES)}>
<ReactMarkdown remarkPlugins={[remarkGfm]}>{introQuery.data.body}</ReactMarkdown>
</div>
)}
</div>
<ol className="flex flex-col gap-2 text-sm">
<li>1. {t('instructions.step1')}</li>
<li>2. {t('instructions.step2')}</li>
<li>3. {t('instructions.step3')}</li>
</ol>
<div className="flex flex-col gap-4">
<nav className="flex flex-wrap gap-1 border-b border-border">
<button
type="button"
onClick={() => setActiveTab(APPS_TAB_ID)}
className={cn(
'whitespace-nowrap px-3 py-2 text-sm text-muted-foreground hover:text-foreground',
activeTab === APPS_TAB_ID && 'border-b-2 border-primary font-medium text-foreground',
)}
>
{t('instructions.appsTitle')}
</button>
{tabs.map((tab) => (
<button
key={tab.id}
type="button"
onClick={() => setActiveTab(tab.id)}
className={cn(
'whitespace-nowrap px-3 py-2 text-sm text-muted-foreground hover:text-foreground',
activeTab === tab.id && 'border-b-2 border-primary font-medium text-foreground',
)}
>
{tab.title}
</button>
))}
</nav>
<div>
<h2 className="mb-3 text-lg font-semibold tracking-tight">{t('instructions.appsTitle')}</h2>
<AppsCatalog />
{activeTab === APPS_TAB_ID ? (
<AppsCatalog />
) : activeExtraTab ? (
<div className={cn('flex flex-col gap-2 text-sm', MARKDOWN_CLASSES)}>
<ReactMarkdown remarkPlugins={[remarkGfm]}>{activeExtraTab.body}</ReactMarkdown>
</div>
) : null}
</div>
</div>
)
+16
View File
@@ -117,6 +117,22 @@ export type NewsPostDto = {
updatedAt: string | null
}
export type InstructionIntroDto = {
id: string
body: string
updatedAt: string
}
/** Один DTO на пользовательскую страницу и админку — у вкладки нет полей, скрытых от юзера. */
export type InstructionTabDto = {
id: string
title: string
body: string
sortOrder: number
createdAt: string
updatedAt: string | null
}
export type LinkTokenResponse = {
deepLink: string | null
expiresAt: string
+30 -8
View File
@@ -102,10 +102,6 @@ const resources = {
instructions: {
title: 'Инструкции по подключению',
intro: 'Как подключиться за три шага — на любом устройстве.',
step1: 'Установите приложение для вашей ОС из списка ниже.',
step2: 'На странице «Мои конфиги» скопируйте ссылку или откройте QR-код нужного конфига.',
step3: 'Импортируйте ссылку или отсканируйте QR в приложении — готово.',
appsTitle: 'Приложения',
noApps: 'Каталог приложений пока пуст.',
recommended: 'Рекомендуем',
@@ -196,6 +192,7 @@ const resources = {
roles: 'Роли',
nodes: 'Ноды',
apps: 'Приложения',
instructions: 'Инструкции',
news: 'Новости',
support: 'Тикеты',
audit: 'Аудит',
@@ -319,6 +316,20 @@ const resources = {
deleted: 'Приложение удалено.',
confirmDelete: 'Удалить приложение из каталога?',
},
instructions: {
introTitle: 'Основная инструкция',
introHint: 'Показывается над вкладками на странице «Инструкции» (Markdown).',
introSaved: 'Инструкция сохранена.',
tabsTitle: 'Дополнительные вкладки',
tabsEmpty: 'Дополнительных вкладок пока нет.',
createTab: 'Добавить вкладку',
tabTitle: 'Название вкладки',
tabBody: 'Текст (Markdown)',
tabCreated: 'Вкладка добавлена.',
tabUpdated: 'Вкладка обновлена.',
tabDeleted: 'Вкладка удалена.',
confirmDeleteTab: 'Удалить вкладку инструкций?',
},
news: {
create: 'Добавить новость',
title: 'Заголовок',
@@ -509,10 +520,6 @@ const resources = {
instructions: {
title: 'Connection instructions',
intro: 'Get connected in three steps, on any device.',
step1: 'Install the app for your OS from the list below.',
step2: 'On the "My configs" page, copy the link or open the QR code for the config you want.',
step3: 'Import the link or scan the QR code in the app — done.',
appsTitle: 'Apps',
noApps: 'The app catalog is empty right now.',
recommended: 'Recommended',
@@ -603,6 +610,7 @@ const resources = {
roles: 'Roles',
nodes: 'Nodes',
apps: 'Apps',
instructions: 'Instructions',
news: 'News',
support: 'Tickets',
audit: 'Audit',
@@ -726,6 +734,20 @@ const resources = {
deleted: 'App deleted.',
confirmDelete: 'Remove this app from the catalog?',
},
instructions: {
introTitle: 'Main instruction',
introHint: 'Shown above the tabs on the Instructions page (Markdown).',
introSaved: 'Instruction saved.',
tabsTitle: 'Additional tabs',
tabsEmpty: 'No additional tabs yet.',
createTab: 'Add tab',
tabTitle: 'Tab title',
tabBody: 'Body (Markdown)',
tabCreated: 'Tab added.',
tabUpdated: 'Tab updated.',
tabDeleted: 'Tab deleted.',
confirmDeleteTab: 'Delete this instruction tab?',
},
news: {
create: 'Add post',
title: 'Title',