feat: version banner UI + GET /api/v1/version backend endpoint

ordinis-admin-ui/src/api/queries.ts

@@ -507,3 +507,30 @@ export const useRecordRaw = (
     ...recordRawQuery(dictionaryName, businessKey ?? ''),
     enabled: Boolean(businessKey),
   })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// App version + update detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ServerVersion = {
+  version: string
+  commit: string
+  branch: string
+  tag: string
+  builtAt: string
+}
+
+export const serverVersionQuery = queryOptions({
+  queryKey: ['version'] as const,
+  queryFn: async (): Promise<ServerVersion> => {
+    const { data } = await apiClient.get<ServerVersion>('/version')
+    return data
+  },
+  // Poll каждые 5 минут — обновление detection без excessive load.
+  // Stale-while-revalidate: даже если нет focus, перезапрашиваем по таймеру.
+  refetchInterval: 5 * 60 * 1000,
+  refetchIntervalInBackground: true,
+  staleTime: 60 * 1000,
+})
+
+export const useServerVersion = () => useQuery(serverVersionQuery)

ordinis-admin-ui/src/components/version/UpdateBanner.tsx

@@ -0,0 +1,74 @@
+import { useTranslation } from 'react-i18next'
+import { Button } from '@nstart/ui'
+import { ArrowClockwise, BookOpen, X } from '@phosphor-icons/react'
+import { useState } from 'react'
+import { useAppVersion } from './useAppVersion'
+
+const DOCS_URL = '/docs/'  // ordinis-docs deployment, mirrors prod /docs path
+
+/**
+ * Banner — показывается top-of-page когда client bundle отстаёт от server.
+ *
+ * <p>Pattern такой же как Altum VS / Geoportal: persistent strip, contextual
+ * CTAs, dismissable (но re-appears после next refetch если still mismatched).
+ *
+ * <p>Two CTAs:
+ * <ul>
+ *   <li><b>Обновить</b> — {@code window.location.reload()}. Browser fetches new
+ *       bundle (cache-busting через Vite hashed filenames).</li>
+ *   <li><b>Что нового →</b> — opens user руководство (changelog / release notes).</li>
+ * </ul>
+ *
+ * <p>Dismiss button (×) — temporarily скрывает banner до следующего
+ * {@code useServerVersion} refetch (5 min). Не persists в localStorage —
+ * критичный update должен progressively становиться более insistent.
+ */
+export function UpdateBanner() {
+  const { t } = useTranslation()
+  const { updateAvailable, serverVersion, serverCommit, serverTag } = useAppVersion()
+  const [dismissed, setDismissed] = useState(false)
+
+  if (!updateAvailable || dismissed) return null
+
+  const versionLabel = serverTag || serverVersion || serverCommit?.substring(0, 7) || ''
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="bg-ultramarain text-white"
+    >
+      <div className="max-w-6xl mx-auto px-4 sm:px-6 py-2 flex items-center gap-3 flex-wrap text-sm">
+        <ArrowClockwise size={18} weight="bold" className="shrink-0" aria-hidden />
+        <span className="flex-1 min-w-0">
+          {t('updateBanner.message', { version: versionLabel })}
+        </span>
+        <div className="flex items-center gap-2 ml-auto">
+          <Button
+            size="sm"
+            variant="secondary"
+            onClick={() => window.open(DOCS_URL, '_blank', 'noopener,noreferrer')}
+          >
+            <BookOpen size={16} weight="regular" className="mr-1" aria-hidden />
+            {t('updateBanner.docs')}
+          </Button>
+          <Button
+            size="sm"
+            variant="primary"
+            onClick={() => window.location.reload()}
+          >
+            {t('updateBanner.reload')}
+          </Button>
+          <button
+            type="button"
+            aria-label={t('updateBanner.dismiss') as string}
+            onClick={() => setDismissed(true)}
+            className="ml-1 p-1 rounded hover:bg-white/10"
+          >
+            <X size={16} weight="bold" aria-hidden />
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

ordinis-admin-ui/src/components/version/VersionBadge.tsx

@@ -0,0 +1,46 @@
+import { useAppVersion } from './useAppVersion'
+
+/**
+ * Subtle version indicator в header. Показывает client version + short commit.
+ *
+ * <p>Hover/title attribute exposes полную идентификацию (server tag, build time).
+ * Используется как secondary affordance для эксплуатационной диагностики
+ * (юзер скриншотит badge в bug report → ops знает точную сборку).
+ *
+ * <p>Если update available — badge подсвечивается dot indicator. Banner делает
+ * primary CTA, badge — passive signal.
+ */
+export function VersionBadge() {
+  const {
+    clientVersion,
+    clientCommit,
+    clientBuiltAt,
+    serverVersion,
+    serverCommit,
+    serverTag,
+    updateAvailable,
+  } = useAppVersion()
+
+  const tooltip = [
+    `client: ${clientVersion} (${clientCommit})`,
+    `server: ${serverTag || serverVersion} (${serverCommit ?? '...'})`,
+    `built: ${clientBuiltAt}`,
+  ].join('\n')
+
+  return (
+    <span
+      className="inline-flex items-center gap-1.5 text-xs text-carbon/60 font-mono select-none"
+      title={tooltip}
+    >
+      {updateAvailable && (
+        <span
+          aria-label="Доступна новая версия"
+          className="inline-block w-1.5 h-1.5 rounded-full bg-ultramarain animate-pulse"
+        />
+      )}
+      <span>v{clientVersion}</span>
+      <span className="text-carbon/40">·</span>
+      <span>{clientCommit.substring(0, 7)}</span>
+    </span>
+  )
+}

ordinis-admin-ui/src/components/version/useAppVersion.ts

@@ -0,0 +1,40 @@
+import { useServerVersion } from '@/api/queries'
+
+/**
+ * App version + update detection hook.
+ *
+ * <p>Returns:
+ * <ul>
+ *   <li>{@code clientVersion}, {@code clientCommit}, {@code clientBuiltAt} —
+ *       built-time injected via Vite {@code define} (см. vite.config.ts).</li>
+ *   <li>{@code serverVersion} — polled из {@code /api/v1/version} каждые 5 мин.</li>
+ *   <li>{@code updateAvailable} — true когда client.commit ≠ server.commit AND
+ *       обе stamps known (не "unknown" и не undefined).</li>
+ * </ul>
+ *
+ * <p>Update detection conservative — игнорирует "unknown" commit (dev mode без
+ * git OR before-build-info), чтобы не показывать banner ложно.
+ */
+export function useAppVersion() {
+  const { data: server, isLoading } = useServerVersion()
+
+  const clientCommit = __APP_COMMIT__
+  const clientVersion = __APP_VERSION__
+  const clientBuiltAt = __APP_BUILT_AT__
+
+  const knownClient = clientCommit !== 'unknown' && clientCommit !== ''
+  const knownServer = Boolean(server?.commit) && server!.commit !== 'unknown'
+  const updateAvailable =
+    knownClient && knownServer && clientCommit !== server!.commit
+
+  return {
+    clientVersion,
+    clientCommit,
+    clientBuiltAt,
+    serverVersion: server?.version,
+    serverCommit: server?.commit,
+    serverTag: server?.tag,
+    updateAvailable,
+    isLoading,
+  }
+}

ordinis-admin-ui/src/routes/__root.tsx

@@ -3,6 +3,8 @@ import type { QueryClient } from '@tanstack/react-query'
 import { useTranslation } from 'react-i18next'
 import { LanguageSwitch } from '@nstart/ui'
 import { AuthBadge } from '@/auth/AuthBadge'
+import { UpdateBanner } from '@/components/version/UpdateBanner'
+import { VersionBadge } from '@/components/version/VersionBadge'
 
 export const Route = createRootRouteWithContext<{ queryClient: QueryClient }>()({
   component: RootLayout,
@@ -17,6 +19,7 @@ function RootLayout() {
   const { t, i18n } = useTranslation()
   return (
     <div className="min-h-full flex flex-col bg-white">
+      <UpdateBanner />
       <header className="border-b border-regolith bg-white">
         <div className="max-w-6xl mx-auto px-4 sm:px-6 py-3 sm:py-4 flex items-center flex-wrap gap-3 sm:gap-6">
           <Link to="/" className="font-primary text-base sm:text-lg text-ultramarain">
@@ -74,6 +77,7 @@ function RootLayout() {
             </Link>
           </nav>
           <div className="ml-auto flex items-center gap-3">
+            <VersionBadge />
             <LanguageSwitch
               value={i18n.language}
               options={LANG_OPTIONS}

ordinis-admin-ui/src/vite-env.d.ts

@@ -8,3 +8,12 @@ interface ImportMetaEnv {
 interface ImportMeta {
   readonly env: ImportMetaEnv
 }
+
+/**
+ * Build identity injected via Vite {@code define} (см. vite.config.ts).
+ * Используются {@code useAppVersion} hook + {@code UpdateBanner} component
+ * для server-vs-client comparison.
+ */
+declare const __APP_VERSION__: string
+declare const __APP_COMMIT__: string
+declare const __APP_BUILT_AT__: string

ordinis-admin-ui/vite.config.ts

@@ -4,8 +4,37 @@ import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import { TanStackRouterVite } from '@tanstack/router-vite-plugin'
 import path from 'path'
+import { execSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+
+// Build identity injected at compile time. Used by /update banner — client
+// сравнивает свой commit с server's /api/v1/version и показывает "Доступна
+// новая версия" если различаются.
+//
+// Fallbacks для CI / sandboxed builds где git unavailable: env var override,
+// затем "unknown".
+const APP_VERSION: string = JSON.parse(
+  readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8'),
+).version
+const APP_COMMIT: string =
+  process.env.CI_COMMIT_SHORT_SHA ??
+  (() => {
+    try {
+      return execSync('git rev-parse --short HEAD', { stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim()
+    } catch {
+      return 'unknown'
+    }
+  })()
+const APP_BUILT_AT: string = new Date().toISOString()
 
 export default defineConfig({
+  define: {
+    __APP_VERSION__: JSON.stringify(APP_VERSION),
+    __APP_COMMIT__: JSON.stringify(APP_COMMIT),
+    __APP_BUILT_AT__: JSON.stringify(APP_BUILT_AT),
+  },
   test: {
     environment: 'jsdom',
     setupFiles: ['./src/test/setup.ts'],

ordinis-app/pom.xml

@@ -109,9 +109,54 @@
 
   <build>
     <plugins>
+      <!-- Resolves git.commit.id.abbrev / git.branch / git.tags из локального .git
+           directory. Properties доступны для других plugin'ов в той же phase'е.
+           CI без .git folder → плагин fallback'ит к "Unknown", это OK. -->
+      <plugin>
+        <groupId>io.github.git-commit-id</groupId>
+        <artifactId>git-commit-id-maven-plugin</artifactId>
+        <version>9.0.1</version>
+        <executions>
+          <execution>
+            <id>git-info</id>
+            <goals><goal>revision</goal></goals>
+            <phase>validate</phase>
+          </execution>
+        </executions>
+        <configuration>
+          <failOnNoGitDirectory>false</failOnNoGitDirectory>
+          <failOnUnableToExtractRepoInfo>false</failOnUnableToExtractRepoInfo>
+          <skipPoms>false</skipPoms>
+          <generateGitPropertiesFile>false</generateGitPropertiesFile>
+          <includeOnlyProperties>
+            <includeOnlyProperty>^git.commit.id.abbrev$</includeOnlyProperty>
+            <includeOnlyProperty>^git.branch$</includeOnlyProperty>
+            <includeOnlyProperty>^git.tags$</includeOnlyProperty>
+            <includeOnlyProperty>^git.commit.time$</includeOnlyProperty>
+          </includeOnlyProperties>
+        </configuration>
+      </plugin>
       <plugin>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-maven-plugin</artifactId>
+        <executions>
+          <!-- Генерирует META-INF/build-info.properties → Spring Boot создаёт
+               BuildProperties bean → VersionController экспонирует /api/v1/version
+               для UI update banner. См. ordinis-rest-api/.../web/VersionController.
+               git.* properties resolved выше через git-commit-id-maven-plugin. -->
+          <execution>
+            <id>build-info</id>
+            <goals><goal>build-info</goal></goals>
+            <configuration>
+              <additionalProperties>
+                <commit>${git.commit.id.abbrev}</commit>
+                <branch>${git.branch}</branch>
+                <tag>${git.tags}</tag>
+                <gitTime>${git.commit.time}</gitTime>
+              </additionalProperties>
+            </configuration>
+          </execution>
+        </executions>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>

ordinis-rest-api/src/main/java/cloud/nstart/terravault/ordinis/restapi/web/VersionController.java

@@ -0,0 +1,81 @@
+package cloud.nstart.terravault.ordinis.restapi.web;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.info.BuildProperties;
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.Instant;
+import java.util.Optional;
+
+/**
+ * {@code GET /api/v1/version} — экспонирует server build identity для UI
+ * update-detection banner.
+ *
+ * <p>Frontend (admin-ui) bundle'ит свой commit SHA в build-time через Vite
+ * {@code define.__APP_COMMIT__}. Periodic poll этого endpoint'а сравнивает
+ * server commit vs client commit. Mismatch → "Доступна новая версия" banner с
+ * CTA {@code Обновить} (window.location.reload).
+ *
+ * <p>Source данных:
+ * <ul>
+ *   <li>{@code BuildProperties} bean создаётся Spring Boot когда есть
+ *       {@code META-INF/build-info.properties} (генерируется
+ *       spring-boot-maven-plugin {@code build-info} goal в ordinis-app pom).</li>
+ *   <li>Дополнительные {@code commit}, {@code branch}, {@code tag}
+ *       resolved из CI env vars (см. additionalProperties в plugin config).</li>
+ * </ul>
+ *
+ * <p>Если build-info.properties отсутствует (e.g., запуск в IDE без mvn package)
+ * — возвращает sensible defaults чтобы UI не падал.
+ *
+ * <p>Public endpoint — auth НЕ required (нужен на login screen чтобы клиент
+ * сразу знал stale ли его bundle).
+ */
+@RestController
+@RequestMapping("/api/v1/version")
+public class VersionController {
+
+  private final Optional<BuildProperties> buildProps;
+
+  // BuildProperties может отсутствовать в dev — оптимально через Optional.
+  public VersionController(@Autowired(required = false) BuildProperties buildProps) {
+    this.buildProps = Optional.ofNullable(buildProps);
+  }
+
+  @GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
+  public VersionInfo current() {
+    return buildProps.map(b -> new VersionInfo(
+        b.getVersion(),
+        Optional.ofNullable(b.get("commit")).orElse("unknown"),
+        Optional.ofNullable(b.get("branch")).orElse(""),
+        Optional.ofNullable(b.get("tag")).orElse(""),
+        b.getTime() != null ? b.getTime().toString() : ""
+    )).orElseGet(() -> new VersionInfo(
+        "0.0.0-dev",
+        "unknown",
+        "",
+        "",
+        Instant.now().toString()
+    ));
+  }
+
+  /**
+   * Stable JSON shape для UI client.
+   *
+   * @param version Maven {@code project.version} (e.g. "0.1.0-SNAPSHOT" или "1.1.0")
+   * @param commit short git SHA (e.g. "07c5ca0") — primary update detection key
+   * @param branch git branch (e.g. "main"), empty в tag builds
+   * @param tag git tag if applicable (e.g. "v1.1.0"), empty в branch builds
+   * @param builtAt ISO-8601 instant
+   */
+  public record VersionInfo(
+      String version,
+      String commit,
+      String branch,
+      String tag,
+      String builtAt
+  ) {}
+}