refactor(api): unify /api contract across frontend, nginx, and backend

frontend/.env.example

@@ -1,2 +1,2 @@
-# Для локального npm run dev. Полный список переменных — в корневом .env.example репозитория.
-VITE_API_BASE_URL=http://localhost:3001
+# Для локального npm run dev дополнительных VITE-переменных не требуется.
+# Полный список переменных окружения — в корневом .env.example репозитория.

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "calendar-run-frontend",
   "private": true,
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

frontend/src/api/errors.ts

@@ -47,7 +47,7 @@ function isGatewayStatus(status: number): boolean {
   return status === 502 || status === 503 || status === 504;
 }
 
-function hasStructuredApiError(payload: unknown): payload is ApiErrorPayload {
+export function isStructuredApiErrorPayload(payload: unknown): payload is ApiErrorPayload {
   if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
     return false;
   }
@@ -55,7 +55,7 @@ function hasStructuredApiError(payload: unknown): payload is ApiErrorPayload {
 }
 
 export function toApiError(status: number, payload: unknown): ApiError {
-  if (isGatewayStatus(status) && !hasStructuredApiError(payload)) {
+  if (isGatewayStatus(status) && !isStructuredApiErrorPayload(payload)) {
     return new ApiError({
       code: "network_error",
       status,
@@ -63,7 +63,7 @@ export function toApiError(status: number, payload: unknown): ApiError {
     });
   }
 
-  if (!hasStructuredApiError(payload) && (status === 401 || status === 403 || status === 404)) {
+  if (!isStructuredApiErrorPayload(payload) && (status === 401 || status === 403 || status === 404)) {
     return new ApiError({
       code: "network_error",
       status,

frontend/src/api/http.ts

@@ -1,10 +1,10 @@
-import { ApiError, toApiError } from "./errors";
+import { ApiError, isStructuredApiErrorPayload, toApiError } from "./errors";
 
-const API_BASE_URL = (import.meta.env.VITE_API_BASE_URL as string | undefined)?.trim() || "http://localhost:3001";
+const API_ROOT = "/api";
 
 function buildUrl(path: string): string {
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  return `${API_BASE_URL}${normalizedPath}`;
+  return `${API_ROOT}${normalizedPath}`;
 }
 
 async function parseResponseBody(response: Response): Promise<unknown> {
@@ -36,6 +36,14 @@ async function parseResponseBody(response: Response): Promise<unknown> {
 
 const GATEWAY_RETRY_STATUSES = new Set([502, 503, 504]);
 
+/** Повтор при «пустом» 404: часто бывает при нескольких инстансах/прокси до полного деплоя. */
+function shouldRetryIdempotentError(status: number, payload: unknown): boolean {
+  if (GATEWAY_RETRY_STATUSES.has(status)) {
+    return true;
+  }
+  return status === 404 && !isStructuredApiErrorPayload(payload);
+}
+
 function delay(ms: number): Promise<void> {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
@@ -69,7 +77,7 @@ export async function requestJson<T>(path: string, init?: RequestInit): Promise<
       const payload = await parseResponseBody(response);
 
       if (!response.ok) {
-        const retryable = idempotent && GATEWAY_RETRY_STATUSES.has(response.status) && attempt < maxAttempts;
+        const retryable = idempotent && attempt < maxAttempts && shouldRetryIdempotentError(response.status, payload);
         if (retryable) {
           await delay(80 * attempt);
           continue;

frontend/src/app/layouts/AppShellFooter.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react";
 import { getBackendMeta } from "../../api";
 import { FRONTEND_VERSION } from "../../frontendVersion";
+import { readCachedBackendVersion, writeCachedBackendVersion } from "../../lib/backendVersionCache";
 
 function isAbortError(error: unknown): boolean {
   return (
@@ -10,7 +11,7 @@ function isAbortError(error: unknown): boolean {
 }
 
 export function AppShellFooter(): JSX.Element {
-  const [backendVersion, setBackendVersion] = useState<string | null>(null);
+  const [backendVersion, setBackendVersion] = useState<string | null>(() => readCachedBackendVersion());
 
   useEffect(() => {
     const ac = new AbortController();
@@ -20,13 +21,24 @@ export function AppShellFooter(): JSX.Element {
           return;
         }
         const v = meta.version;
-        setBackendVersion(typeof v === "string" && v.length > 0 ? v : "не указана");
+        const label = typeof v === "string" && v.length > 0 ? v : "не указана";
+        writeCachedBackendVersion(label);
+        setBackendVersion(label);
       })
       .catch((err) => {
         if (ac.signal.aborted || isAbortError(err)) {
           return;
         }
-        setBackendVersion("недоступна");
+        setBackendVersion((prev) => {
+          const cached = readCachedBackendVersion();
+          if (cached) {
+            return cached;
+          }
+          if (prev !== null) {
+            return prev;
+          }
+          return "недоступна";
+        });
       });
     return () => ac.abort();
   }, []);

frontend/src/lib/backendVersionCache.ts

@@ -0,0 +1,21 @@
+const STORAGE_KEY = "calendar_run.backendVersion.v1";
+
+export function readCachedBackendVersion(): string | null {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    return raw !== null && raw.trim().length > 0 ? raw.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCachedBackendVersion(version: string): void {
+  try {
+    if (version === "недоступна" || version === "не указана") {
+      return;
+    }
+    sessionStorage.setItem(STORAGE_KEY, version);
+  } catch {
+    // private mode / quota
+  }
+}

frontend/vite.config.ts

@@ -3,4 +3,12 @@ import react from "@vitejs/plugin-react";
 
 export default defineConfig({
   plugins: [react()],
+  server: {
+    proxy: {
+      "/api": {
+        target: "http://localhost:3001",
+        changeOrigin: true,
+      },
+    },
+  },
 });