From e71dd9a60047d57829223067b9a824bb4da61f22 Mon Sep 17 00:00:00 2001 From: "Tran G. (Revernomad) Khoa" Date: Fri, 17 Apr 2026 15:50:33 +0700 Subject: [PATCH] docs: update root .md files to reflect current frontend state and planned UX enhancements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ARCHITECTURE.md: fix diagram (Server Detail was "planned", now complete), expand frontend directory listing with all 5 pages, all server components, all hooks - FRONTEND.md: note planned terrain/display_name/workshop_id fields on Mission/Mod types; add planned hooks table for Phases 1-5 of UX enhancement plan - MODULES.md: annotate PlayerRepository with get_by_slot() and ThreadRegistry with get_rcon_client() as planned additions in Phase 4 - API.md: add "Upcoming Endpoints" section documenting all planned routes for Phases 1-5 of the UX enhancement plan - README.md: update unit test count (69 → ~120), update frontend structure comment to list all current pages/components/hooks --- API.md | 35 ++++++++++++++++++++++++++++++++++- ARCHITECTURE.md | 21 +++++++++++++++++++-- FRONTEND.md | 15 +++++++++++++-- MODULES.md | 4 ++-- README.md | 10 +++++----- 5 files changed, 73 insertions(+), 12 deletions(-) diff --git a/API.md b/API.md index f120884..826b07d 100644 --- a/API.md +++ b/API.md @@ -1485,4 +1485,37 @@ Implemented via `slowapi` middleware. | `FILE_TOO_LARGE` | 413 | Upload exceeds 500 MB | | `NO_FILENAME` | 400 | No filename in upload request | | `VALIDATION_ERROR` | 400 | General validation failure | -| `INTERNAL_ERROR` | 500 | Unexpected server error | \ No newline at end of file +| `INTERNAL_ERROR` | 500 | Unexpected server error | + +--- + +## Upcoming Endpoints (UX Enhancement Plan) + +These endpoints are planned and will be added during the Arma 3 UX Enhancement implementation. They do not exist yet. + +### Phase 1 — Config UI Schema + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/servers/{server_id}/config/ui-schema` | Bearer | Returns widget hints per field (`widget`, `label`, `placeholder`) for the frontend config editor | + +### Phase 2 — Mission Rotation + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/servers/{server_id}/missions/rotation` | Bearer | Get current mission rotation list | +| PUT | `/servers/{server_id}/missions/rotation` | Admin | Replace mission rotation (requires `config_version` for optimistic locking) | + +### Phase 4 — Player Kick / Ban + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| POST | `/servers/{server_id}/players/{slot_id}/kick` | Admin | Kick player by slot ID via RCon; requires `reason` in body | +| POST | `/servers/{server_id}/players/{slot_id}/ban` | Admin | Ban player by slot ID via RCon + DB; requires `reason` and optional `duration_minutes` (`null` = permanent) | + +### Phase 5 — Log File Browser + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/servers/{server_id}/logfiles` | Bearer | List historical `.rpt` log files with `filename`, `size_bytes`, `modified_at` | +| GET | `/servers/{server_id}/logfiles/{filename}` | Bearer | Stream or return contents of a historical log file | \ No newline at end of file diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4e7351a..d5d85ac 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -30,7 +30,8 @@ Arma 3 is the first-class, built-in adapter. Adding a new game server type requi ``` +--------------------------------------------------------------+ | React Frontend (SPA) | -| Dashboard | Login | Server List | Server Detail (planned) | +| Login | Dashboard | Server Detail (7 tabs) | Create Server | +| Settings | (all routes complete) | +------------------------------+-------------------------------+ | HTTP REST + WebSocket (/ws) v @@ -712,22 +713,38 @@ frontend/ pages/ LoginPage.tsx # Login form (react-hook-form + zod validation) DashboardPage.tsx # Server dashboard with ServerCard grid + ServerDetailPage.tsx # 7-tab detail page (overview, config, players, bans, missions, mods, logs) + CreateServerPage.tsx # 4-step wizard (admin only) + SettingsPage.tsx # Password change + admin user management components/ layout/ Sidebar.tsx # Sidebar navigation servers/ ServerCard.tsx # Server status card with lifecycle buttons + ServerHeader.tsx # Server name, status, stats, lifecycle buttons + ConfigEditor.tsx # Tabbed config editor with optimistic locking + PlayerTable.tsx # Current players + history with search + BanTable.tsx # Ban list + create/revoke form + MissionList.tsx # Mission list + .pbo upload/delete + ModList.tsx # Mod list with enable/disable checkboxes + LogViewer.tsx # Log display with level filter (props-driven) + settings/ + PasswordChange.tsx # Password change form + UserManager.tsx # User CRUD table (admin only) ui/ StatusLed.tsx # Status LED indicator component hooks/ useServers.ts # TanStack Query hooks for server CRUD + lifecycle + useServerDetail.ts # Config, players, bans, missions, mods, RCon hooks + useAuth.ts # Auth management hooks (users, password, logout) + useGames.ts # Game type hooks (list, detail, schema, defaults) useWebSocket.ts # WebSocket hook with exponential backoff reconnect store/ auth.store.ts # Zustand auth store (persisted to localStorage) ui.store.ts # Zustand UI store (sidebar, notifications) lib/ api.ts # Axios client with auth interceptors - __tests__/ # 12 unit test files (Vitest) + __tests__/ # 14 unit test files (~120 tests, Vitest) tests-e2e/ auth/ login.spec.ts # Login E2E test diff --git a/FRONTEND.md b/FRONTEND.md index 058c7b3..6d75bd1 100644 --- a/FRONTEND.md +++ b/FRONTEND.md @@ -205,11 +205,22 @@ All server data flows through TanStack Query hooks: **Key type notes**: - `Server` type in `useServers.ts` uses `game_port`, `current_players`, `max_players` (matches enriched API response) -- `Mission` type: `{ name, filename, size_bytes }` (not DB schema fields) -- `Mod` type: `{ name, path, size_bytes, enabled }` (not DB schema fields) +- `Mission` type: `{ name, filename, size_bytes }` — `terrain` field planned (Phase 2 UX enhancement) +- `Mod` type: `{ name, path, size_bytes, enabled }` — `display_name`, `workshop_id` fields planned (Phase 3 UX enhancement) - `Ban` type: `{ id, server_id, guid, name, reason, banned_by, banned_at, expires_at, is_active, game_data }` (matches API) - There is no REST endpoint for logs — logs are only pushed via WebSocket events +**Planned hooks (UX Enhancement Plan):** + +| Hook | Phase | Endpoint | +|---|---|---| +| `useConfigUISchema(serverId)` | Phase 1 | `GET /api/servers/:id/config/ui-schema` | +| `useMissionRotation(id)` | Phase 2 | `GET /api/servers/:id/missions/rotation` | +| `useUpdateMissionRotation(id)` | Phase 2 | `PUT /api/servers/:id/missions/rotation` | +| `useKickPlayer(id)` | Phase 4 | `POST /api/servers/:id/players/:slot_id/kick` | +| `useBanPlayer(id)` | Phase 4 | `POST /api/servers/:id/players/:slot_id/ban` | +| `useLogFiles(id)` | Phase 5 | `GET /api/servers/:id/logfiles` | + QueryClient defaults: `staleTime: 10s`, `retry: 2`, `refetchOnWindowFocus: false`. ### Client State (Zustand) diff --git a/MODULES.md b/MODULES.md index a5afdf1..379b2fb 100644 --- a/MODULES.md +++ b/MODULES.md @@ -105,7 +105,7 @@ All 7 capabilities implemented: | Module | Purpose | |---|---| | `base_thread.py` | `BaseServerThread` — abstract base with stop event, thread-local DB, exception backoff | -| `thread_registry.py` | `ThreadRegistry` — manages per-server thread bundles, start/stop/reattach | +| `thread_registry.py` | `ThreadRegistry` — manages per-server thread bundles, start/stop/reattach; `get_rcon_client(server_id)` class method to be added in Phase 4 | | `log_tail.py` | `LogTailThread` — tails log files, parses lines, persists to DB, broadcasts | | `process_monitor.py` | `ProcessMonitorThread` — detects crashes, triggers auto-restart | | `metrics_collector.py` | `MetricsCollectorThread` — psutil CPU/RAM collection every 10s | @@ -125,7 +125,7 @@ All 7 capabilities implemented: | `base_repository.py` | `BaseRepository` — thin wrapper around SQLAlchemy `text()` queries | | `server_repository.py` | `ServerRepository` — CRUD, status updates, running servers, restart count | | `config_repository.py` | `ConfigRepository` — Per-section upsert with Fernet encryption and optimistic locking | -| `player_repository.py` | `PlayerRepository` — Upsert/clear players, player_history queries | +| `player_repository.py` | `PlayerRepository` — Upsert/clear players, player_history queries; `get_by_slot(server_id, slot_id)` to be added in Phase 4 | | `ban_repository.py` | `BanRepository` — Ban CRUD with active/inactive flag | | `event_repository.py` | `EventRepository` — Insert server events, query, cleanup | | `log_repository.py` | `LogRepository` — Insert parsed log entries, query with filters, cleanup | diff --git a/README.md b/README.md index 9fe04ae..0c08223 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ A multi-game server management platform with a Python/FastAPI backend and React/ - **Zustand 5** — client state (auth, UI) - **Tailwind CSS** — dark neumorphic design system - **Playwright** — E2E testing (23 tests) -- **Vitest** + **React Testing Library** — unit tests (69 tests) +- **Vitest** + **React Testing Library** — unit tests (~120 tests) ## Quick Start @@ -96,12 +96,12 @@ languard-servers-manager/ ├── frontend/ │ ├── src/ │ │ ├── App.tsx # Router + auth guard -│ │ ├── pages/ # LoginPage, DashboardPage -│ │ ├── components/ # Sidebar, ServerCard, StatusLed -│ │ ├── hooks/ # useServers, useWebSocket +│ │ ├── pages/ # LoginPage, DashboardPage, ServerDetailPage, CreateServerPage, SettingsPage +│ │ ├── components/ # Sidebar, ServerCard, ConfigEditor, PlayerTable, BanTable, MissionList, ModList, LogViewer, StatusLed +│ │ ├── hooks/ # useServers, useServerDetail, useAuth, useGames, useWebSocket │ │ ├── store/ # auth.store, ui.store (Zustand) │ │ ├── lib/ # api.ts (Axios client) -│ │ └── __tests__/ # Vitest unit tests +│ │ └── __tests__/ # Vitest unit tests (~120 tests) │ ├── tests-e2e/ # Playwright E2E tests │ └── playwright.config.ts ├── API.md # REST + WebSocket API reference