docs: finalise Arma 3 UX enhancement plan and update project docs

- .claude/plan/arma3-ux-enhancement.md: full plan review pass - Add Progress Tracker table for session handoff - Fix Phase 1 field names to match ServerConfig model (password_admin, battleye, disable_von) - Fix Phase 2 rotation endpoints to use ServerService(db) inline pattern - Fix Phase 4 router/service: add get_by_slot() to PlayerRepository, add get_rcon_client() to ThreadRegistry, fix BanRepository.create() signature (expires_at not duration_minutes), correct router pattern - Fix Phase 6: already implemented, mark as SKIP - Fix CSS class names: btn-secondary→btn-ghost, input-base→neu-input - Add 19 implementation decisions from Q&A session to Coding Conventions - CLAUDE.md: update status table, type mapping table, add plan summary and new endpoint list, add key implementation gotchas section - frontend/README.md: replace Vite boilerplate with project README - frontend/tests-e2e: E2E test improvements from previous session (mock-based login error test, full dashboard mock coverage)
2026-04-17 15:45:34 +07:00
parent 34cc1fd008
commit a688bdfdf9
5 changed files with 477 additions and 265 deletions
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,73 +1,72 @@
-# React + TypeScript + Vite
+# Languard Server Manager — Frontend

-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+React 19 + TypeScript + Vite frontend for the Languard game server management panel.

-Currently, two official plugins are available:
+## Stack

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+- **React 19** with hooks
+- **TypeScript** strict mode
+- **Vite** dev server + build
+- **TanStack Query** for server state (all API calls)
+- **Zustand** for client state (auth, UI notifications)
+- **react-hook-form + Zod** for form validation
+- **Tailwind CSS** with custom neumorphic design tokens
+- **Vitest** for unit tests

-## React Compiler
+## Dev Server

-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+# From this directory
+npx vite --host
+# → http://localhost:5173
 ```

-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+## Tests

-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+npx vitest run          # run once
+npx vitest              # watch mode
+npx tsc --noEmit        # type check only
 ```
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── layout/         # Sidebar
+│   ├── servers/        # ServerCard, ConfigEditor, PlayerTable, MissionList, ModList, LogViewer, BanTable
+│   ├── settings/       # PasswordChange, UserManager
+│   └── ui/             # StatusLed, (planned) TagListEditor, ConfirmModal
+├── hooks/
+│   ├── useServers.ts       # Dashboard server list + start/stop/restart mutations
+│   ├── useServerDetail.ts  # All per-server queries and mutations
+│   ├── useAuth.ts
+│   └── useWebSocket.ts     # Real-time events (logs, status changes)
+├── pages/
+│   ├── LoginPage.tsx
+│   ├── DashboardPage.tsx
+│   ├── ServerDetailPage.tsx
+│   ├── CreateServerPage.tsx
+│   └── SettingsPage.tsx
+├── store/
+│   ├── auth.store.ts   # JWT + user role
+│   └── ui.store.ts     # Notification queue
+└── lib/
+    ├── api.ts          # Axios instance with JWT interceptor + 401 redirect
+    └── logger.ts
+```
+
+## CSS Conventions
+
+Custom utility classes defined in `src/index.css` (do not add new CSS files):
+
+| Class | Use |
+|-------|-----|
+| `neu-card` | Card surface with neumorphic raised shadow |
+| `neu-input` | Input with recessed shadow |
+| `btn-primary` | Amber accent button |
+| `btn-ghost` | Text-only button with hover background |
+| `btn-danger` | Red destructive button |
+
+Tailwind design tokens in `tailwind.config.js`: `surface-{base,raised,recessed,overlay}`, `text-{primary,secondary,muted}`, `status-{running,stopped,crashed,starting,restarting}`, `accent`.
--- a/frontend/tests-e2e/auth/login.spec.ts
+++ b/frontend/tests-e2e/auth/login.spec.ts
@@ -29,11 +29,18 @@ test.describe("Login Flow", () => {
  });

  test("should show error on invalid credentials", async ({ page }) => {
+    // Mock the backend to return 401 for invalid login
+    await page.route("**/api/auth/login", (route) =>
+      route.fulfill({
+        status: 401,
+        contentType: "application/json",
+        body: JSON.stringify({
+          detail: "Invalid credentials",
+        }),
+      }),
+    );
+
    await loginPage.login("invalid", "credentials");
-    await page.waitForResponse(
-      (resp) => resp.url().includes("/api/auth/login"),
-      { timeout: 10_000 },
-    ).catch(() => {});
    await expect(loginPage.errorMessage).toBeVisible({ timeout: 10_000 });
  });

@@ -52,7 +59,16 @@ test.describe("Login Flow", () => {
      }),
    );

-    await page.route("**/api/servers*", (route) =>
+    // Mock auth/me and servers so the dashboard loads
+    await page.route("**/api/auth/me", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true, data: { id: 1, username: "admin", role: "admin" }, error: null }),
+      }),
+    );
+
+    await page.route("**/api/servers**", (route) =>
      route.fulfill({
        status: 200,
        contentType: "application/json",
@@ -66,8 +82,14 @@ test.describe("Login Flow", () => {
  });

  test("should show loading state while submitting", async ({ page }) => {
-    await page.route("**/api/auth/login", (route) =>
-      route.fulfill({
+    let resolveLogin: (value: unknown) => void;
+    const loginPromise = new Promise((resolve) => {
+      resolveLogin = resolve;
+    });
+
+    await page.route("**/api/auth/login", async (route) => {
+      await loginPromise;
+      await route.fulfill({
        status: 200,
        contentType: "application/json",
        body: JSON.stringify({
@@ -77,19 +99,19 @@ test.describe("Login Flow", () => {
            user: { id: 1, username: "admin", role: "admin" },
          },
        }),
-        delay: 500,
-      }),
-    );
+      });
+    });

-    await page.route("**/api/servers*", (route) =>
-      route.fulfill({
-        status: 200,
-        contentType: "application/json",
-        body: JSON.stringify({ success: true, data: [] }),
-      }),
-    );
+    await loginPage.usernameInput.fill("admin");
+    await loginPage.passwordInput.fill("password");

-    await loginPage.login("admin", "password");
-    await expect(loginPage.submitButton).toContainText("Signing in...");
+    // Click submit and immediately check for loading state
+    await loginPage.submitButton.click();
+
+    // The button should show "Signing in..." while the request is pending
+    await expect(loginPage.submitButton).toContainText("Signing in...", { timeout: 5_000 });
+
+    // Resolve the login to let the test finish
+    resolveLogin!("done");
  });
 });
--- a/frontend/tests-e2e/dashboard/dashboard.spec.ts
+++ b/frontend/tests-e2e/dashboard/dashboard.spec.ts
@@ -1,138 +1,224 @@
 import { test, expect } from "@playwright/test";
 import { DashboardPage } from "../pages/DashboardPage";

+const MOCK_TOKEN = "mock-jwt-token";
+
+const MOCK_USER = { id: 1, username: "admin", role: "admin" };
+
+const MOCK_SERVERS = [
+  {
+    id: 1,
+    name: "A3Master",
+    game_type: "arma3",
+    status: "running",
+    port: 2302,
+    max_players: 64,
+    current_players: 32,
+    restart_count: 2,
+    auto_restart: true,
+    created_at: "2026-01-01T00:00:00Z",
+  },
+  {
+    id: 2,
+    name: "Arma3 Test Server",
+    game_type: "arma3",
+    status: "stopped",
+    port: 2303,
+    max_players: 32,
+    current_players: 0,
+    restart_count: 0,
+    auto_restart: false,
+    created_at: "2026-01-02T00:00:00Z",
+  },
+];
+
+/**
+ * Set up auth + mock all API calls the dashboard needs.
+ * IMPORTANT: Playwright checks routes in reverse registration order (last registered = first checked).
+ * So we register the catch-all FIRST, then specific routes AFTER so they take priority.
+ */
+async function setupDashboardMocks(page: import("@playwright/test").Page, servers = MOCK_SERVERS) {
+  // Set mock auth state in localStorage for both:
+  // 1) The Zustand persist store (key: languard-auth) so ProtectedLayout sees isAuthenticated: true
+  // 2) The raw token (key: languard_token) so the Axios interceptor adds the Bearer header
+  await page.addInitScript(({ token, user }) => {
+    localStorage.setItem("languard_token", token);
+    localStorage.setItem(
+      "languard-auth",
+      JSON.stringify({ state: { token, user }, version: 0 }),
+    );
+  }, { token: MOCK_TOKEN, user: MOCK_USER });
+
+  // Catch-all for unhandled API calls — register FIRST so it has lowest priority
+  await page.route("**/api/**", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({ success: true, data: null, error: null }),
+    }),
+  );
+
+  // Specific routes — register AFTER catch-all so they take priority
+  await page.route("**/api/auth/me", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({ success: true, data: MOCK_USER, error: null }),
+    }),
+  );
+
+  await page.route("**/api/servers**", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({ success: true, data: servers, error: null }),
+    }),
+  );
+}
+
 test.describe("Dashboard", () => {
  let dashboardPage: DashboardPage;

  test.beforeEach(async ({ page }) => {
-    // Set up auth token so we're logged in
-    await page.addInitScript(() => {
-      localStorage.setItem("languard_token", "mock-jwt-token");
-    });
-
-    // Mock the servers API
-    await page.route("**/api/servers*", (route) =>
-      route.fulfill({
-        status: 200,
-        contentType: "application/json",
-        body: JSON.stringify({
-          success: true,
-          data: [
-            {
-              id: 1,
-              name: "Arma3 Main Server",
-              game_type: "arma3",
-              status: "running",
-              port: 2302,
-              max_players: 64,
-              current_players: 32,
-              restart_count: 2,
-              auto_restart: true,
-              created_at: "2026-01-01T00:00:00Z",
-            },
-            {
-              id: 2,
-              name: "Arma3 Test Server",
-              game_type: "arma3",
-              status: "stopped",
-              port: 2303,
-              max_players: 32,
-              current_players: 0,
-              restart_count: 0,
-              auto_restart: false,
-              created_at: "2026-01-02T00:00:00Z",
-            },
-          ],
-        }),
-      }),
-    );
-
+    await setupDashboardMocks(page);
    dashboardPage = new DashboardPage(page);
    await dashboardPage.goto();
  });

  test("should display dashboard header", async () => {
-    await expect(dashboardPage.content).toBeVisible();
+    await expect(dashboardPage.content).toBeVisible({ timeout: 10_000 });
    await expect(dashboardPage.content.locator("h1")).toContainText("Dashboard");
  });

  test("should show server count", async () => {
+    await expect(dashboardPage.content).toBeVisible({ timeout: 10_000 });
    await expect(dashboardPage.content.locator("text=2 servers configured")).toBeVisible();
  });

  test("should render server cards", async () => {
+    await expect(dashboardPage.serverCards.first()).toBeVisible({ timeout: 10_000 });
    const count = await dashboardPage.getServerCount();
    expect(count).toBe(2);
  });

  test("should display server names in cards", async () => {
+    await expect(dashboardPage.serverCards.first()).toBeVisible({ timeout: 10_000 });
    const name = await dashboardPage.getServerCardName(0);
-    expect(name).toContain("Arma3 Main Server");
+    expect(name).toContain("A3Master");
  });

  test("should show Add Server button", async () => {
+    await expect(dashboardPage.content).toBeVisible({ timeout: 10_000 });
    await expect(dashboardPage.addServerButton).toBeVisible();
    await expect(dashboardPage.addServerButton).toContainText("Add Server");
  });

  test("should show sidebar with server list", async () => {
-    await expect(dashboardPage.sidebar).toBeVisible();
+    await expect(dashboardPage.sidebar).toBeVisible({ timeout: 10_000 });
    await expect(dashboardPage.sidebar.locator("text=Servers")).toBeVisible();
-    await expect(dashboardPage.sidebar.locator("text=Arma3 Main Server")).toBeVisible();
+    await expect(dashboardPage.sidebar.locator("text=A3Master")).toBeVisible();
  });

  test("should show Stop button for running server", async () => {
+    await expect(dashboardPage.serverCards.first()).toBeVisible({ timeout: 10_000 });
    const firstCard = dashboardPage.serverCards.nth(0);
    await expect(firstCard.locator('button[aria-label^="Stop"]')).toBeVisible();
  });

  test("should show Start button for stopped server", async () => {
+    await expect(dashboardPage.serverCards.nth(1)).toBeVisible({ timeout: 10_000 });
    const secondCard = dashboardPage.serverCards.nth(1);
    await expect(secondCard.locator('button[aria-label^="Start"]')).toBeVisible();
  });

  test("should display player count in server card", async () => {
+    await expect(dashboardPage.serverCards.first()).toBeVisible({ timeout: 10_000 });
    const firstCard = dashboardPage.serverCards.nth(0);
    await expect(firstCard.locator("text=32/64")).toBeVisible();
  });

  test("should navigate to server detail on card click", async ({ page }) => {
-    const firstCard = dashboardPage.serverCards.nth(0);
-    const link = firstCard.locator("xpath=ancestor::a");
-    await link.click();
-    await expect(page).toHaveURL(/\/servers\/1/);
+    await expect(dashboardPage.serverCards.first()).toBeVisible({ timeout: 10_000 });
+    // Click the server card link (not the sidebar link) — use .first() to avoid strict mode
+    const serverLink = page.locator('[data-testid="dashboard-content"] a[href="/servers/1"]');
+    await serverLink.click();
+    await expect(page).toHaveURL(/\/servers\/1/, { timeout: 5_000 });
  });
 });

 test.describe("Dashboard - Empty State", () => {
  test("should show empty state when no servers", async ({ page }) => {
-    await page.addInitScript(() => {
-      localStorage.setItem("languard_token", "mock-jwt-token");
-    });
+    await page.addInitScript(({ token, user }) => {
+      localStorage.setItem("languard_token", token);
+      localStorage.setItem(
+        "languard-auth",
+        JSON.stringify({ state: { token, user }, version: 0 }),
+      );
+    }, { token: MOCK_TOKEN, user: MOCK_USER });

-    await page.route("**/api/servers*", (route) =>
+    // Catch-all first (lowest priority)
+    await page.route("**/api/**", (route) =>
      route.fulfill({
        status: 200,
        contentType: "application/json",
-        body: JSON.stringify({ success: true, data: [] }),
+        body: JSON.stringify({ success: true, data: null, error: null }),
+      }),
+    );
+
+    // Specific routes after (higher priority)
+    await page.route("**/api/auth/me", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true, data: MOCK_USER, error: null }),
+      }),
+    );
+
+    await page.route("**/api/servers**", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true, data: [], error: null }),
      }),
    );

    const dashboardPage = new DashboardPage(page);
    await dashboardPage.goto();

-    await expect(dashboardPage.emptyState).toBeVisible();
+    await expect(dashboardPage.emptyState).toBeVisible({ timeout: 10_000 });
    await expect(dashboardPage.emptyState.locator("text=No servers configured yet")).toBeVisible();
  });
 });

 test.describe("Dashboard - Error State", () => {
  test("should show error state when API fails", async ({ page }) => {
-    await page.addInitScript(() => {
-      localStorage.setItem("languard_token", "mock-jwt-token");
-    });
+    await page.addInitScript(({ token, user }) => {
+      localStorage.setItem("languard_token", token);
+      localStorage.setItem(
+        "languard-auth",
+        JSON.stringify({ state: { token, user }, version: 0 }),
+      );
+    }, { token: MOCK_TOKEN, user: MOCK_USER });

-    await page.route("**/api/servers*", (route) =>
+    // Catch-all first (lowest priority)
+    await page.route("**/api/**", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true, data: null, error: null }),
+      }),
+    );
+
+    // Specific routes after (higher priority)
+    await page.route("**/api/auth/me", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ success: true, data: MOCK_USER, error: null }),
+      }),
+    );
+
+    await page.route("**/api/servers**", (route) =>
      route.fulfill({
        status: 500,
        contentType: "application/json",