feat: implement full backend + frontend server detail, settings, and create server pages

Backend: - Complete FastAPI backend with 42+ REST endpoints (auth, servers, config, players, bans, missions, mods, games, system) - Game adapter architecture with Arma 3 as first-class adapter - WebSocket real-time events for status, metrics, logs, players - Background thread system (process monitor, metrics, log tail, RCon poller) - Fernet encryption for sensitive config fields at rest - JWT auth with admin/viewer roles, bcrypt password hashing - SQLite with WAL mode, parameterized queries, migration system - APScheduler cleanup jobs for logs, metrics, events Frontend: - Server Detail page with 7 tabs (overview, config, players, bans, missions, mods, logs) - Settings page with password change and admin user management - Create Server wizard (4-step; known bug: silent validation failure) - New hooks: useServerDetail, useAuth, useGames - New components: ServerHeader, ConfigEditor, PlayerTable, BanTable, MissionList, ModList, LogViewer, PasswordChange, UserManager - WebSocket onEvent callback for real-time log accumulation - 120 unit tests passing (Vitest + React Testing Library) Docs: - Added .gitignore, CLAUDE.md, README.md - Updated FRONTEND.md, ARCHITECTURE.md with current implementation state - Added .env.example for backend configuration Known issues: - Create Server form: "Next" buttons don't validate before advancing, causing silent submit failure when fields are invalid - Config sub-tabs need UX redesign for non-technical users
2026-04-17 11:58:34 +07:00
parent 620429c9b8
commit 6511353b55
119 changed files with 13752 additions and 5000 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,139 @@
+# Languard Server Manager
+
+A multi-game server management platform with a Python/FastAPI backend and React/TypeScript frontend. Currently supports Arma 3 with an extensible adapter system for adding more games.
+
+## Tech Stack
+
+### Backend
+- **Python 3.12+** / **FastAPI** — async REST API
+- **SQLite** with WAL mode — zero-config database
+- **SQLAlchemy** — raw SQL via `text()` queries (no ORM)
+- **BattlEye RCon** — UDP protocol v2 for remote admin
+- **APScheduler** — background cleanup jobs
+- **psutil** — process monitoring and resource metrics
+- **JWT** (python-jose) + **bcrypt** — authentication
+- **Fernet** (cryptography) — sensitive config field encryption
+
+### Frontend
+- **React 19** / **TypeScript 6** / **Vite 8**
+- **TanStack Query v5** — server state management
+- **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)
+
+## Quick Start
+
+### Backend
+
+```bash
+cd backend
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env       # Edit with your settings
+uvicorn main:app --reload
+```
+
+First run prints a generated admin password. Change it immediately via `PUT /api/auth/password`.
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Opens at `http://localhost:5173`. The dev server proxies `/api` to the backend on port 8000.
+
+## Running Tests
+
+### Frontend Unit Tests
+
+```bash
+cd frontend
+npm test                  # Watch mode
+npx vitest run            # Single run
+npx vitest run --coverage # With coverage
+```
+
+### Frontend E2E Tests
+
+```bash
+cd frontend
+# Start backend + frontend dev server first
+npx playwright test                    # All tests (mocked + integration)
+npx playwright tests-e2e/integration/   # Full-stack integration tests only
+```
+
+## Project Structure
+
+```
+languard-servers-manager/
+├── backend/
+│   ├── main.py                  # FastAPI app factory, lifespan, middleware
+│   ├── config.py               # Pydantic Settings (env vars)
+│   ├── database.py              # SQLAlchemy engine, migration runner
+│   ├── dependencies.py          # FastAPI deps: auth, admin, server, adapter
+│   ├── adapters/                # Game adapter system
+│   │   ├── protocols.py         # Protocol definitions (7 capabilities)
+│   │   ├── registry.py          # GameAdapterRegistry singleton
+│   │   ├── exceptions.py        # Typed adapter exceptions
+│   │   └── arma3/               # Arma 3 adapter (7/7 capabilities)
+│   ├── core/
+│   │   ├── auth/                # JWT auth, user CRUD
+│   │   ├── servers/             # Server service, routers, process manager
+│   │   ├── games/               # Game type discovery
+│   │   ├── system/              # Health and status endpoints
+│   │   ├── websocket/           # WS manager, broadcast thread
+│   │   ├── threads/             # Background thread registry
+│   │   ├── dal/                 # Data access layer (repositories)
+│   │   ├── jobs/                # APScheduler cleanup jobs
+│   │   ├── utils/               # Crypto, file utils, port checker
+│   │   └── migrations/          # SQL migration scripts
+│   └── requirements.txt
+├── frontend/
+│   ├── src/
+│   │   ├── App.tsx              # Router + auth guard
+│   │   ├── pages/               # LoginPage, DashboardPage
+│   │   ├── components/         # Sidebar, ServerCard, StatusLed
+│   │   ├── hooks/               # useServers, useWebSocket
+│   │   ├── store/               # auth.store, ui.store (Zustand)
+│   │   ├── lib/                 # api.ts (Axios client)
+│   │   └── __tests__/          # Vitest unit tests
+│   ├── tests-e2e/               # Playwright E2E tests
+│   └── playwright.config.ts
+├── API.md                       # REST + WebSocket API reference
+├── ARCHITECTURE.md              # System architecture overview
+├── DATABASE.md                  # Database schema reference
+├── FRONTEND.md                  # Frontend architecture and components
+├── MODULES.md                   # Module-by-module reference
+└── THREADING.md                 # Background threading model
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `LANGUARD_SECRET_KEY` | (required) | JWT signing key |
+| `LANGUARD_ENCRYPTION_KEY` | (required) | Fernet key for sensitive config fields |
+| `LANGUARD_DB_PATH` | `./languard.db` | SQLite database path |
+| `LANGUARD_SERVERS_DIR` | `./servers` | Base directory for server data |
+| `LANGUARD_HOST` | `0.0.0.0` | Listen host |
+| `LANGUARD_PORT` | `8000` | Listen port |
+| `LANGUARD_CORS_ORIGINS` | `["http://localhost:5173"]` | CORS allowed origins |
+| `LANGUARD_LOG_RETENTION_DAYS` | `7` | Log cleanup retention |
+| `LANGUARD_METRICS_RETENTION_DAYS` | `30` | Metrics cleanup retention |
+| `LANGUARD_PLAYER_HISTORY_RETENTION_DAYS` | `90` | Player history retention |
+| `LANGUARD_JWT_EXPIRE_HOURS` | `24` | JWT token expiry |
+| `LANGUARD_ARMA3_DEFAULT_EXE` | (required for Arma 3) | Default Arma 3 executable path |
+
+## Documentation
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — System design, component diagram, security model
+- **[API.md](API.md)** — Complete REST + WebSocket API reference
+- **[DATABASE.md](DATABASE.md)** — Schema, tables, indexes, migration system
+- **[FRONTEND.md](FRONTEND.md)** — React component tree, state management, design system
+- **[MODULES.md](MODULES.md)** — File-by-file module reference
+- **[THREADING.md](THREADING.md)** — Background thread model and concurrency