217 lines
12 KiB
Markdown
217 lines
12 KiB
Markdown
# BanGUI — Task List
|
|
|
|
This document breaks the entire BanGUI project into development stages, ordered so that each stage builds on the previous one. Every task is described in prose with enough detail for a developer to begin work. References point to the relevant documentation.
|
|
|
|
---
|
|
|
|
## Open Issues
|
|
|
|
> **Architectural Review — 2026-03-16**
|
|
> The findings below were identified by auditing every backend and frontend module against the rules in [Refactoring.md](Refactoring.md) and [Architekture.md](Architekture.md).
|
|
> Tasks are grouped by layer and ordered so that lower-level fixes (repositories, services) are done before the layers that depend on them.
|
|
|
|
---
|
|
|
|
## Feature: Worldmap Country Tooltip
|
|
|
|
> **2026-03-17**
|
|
> The world map on the Map page colours each country by ban count but provides no immediate information on hover — the user must click a country to see its name in the filter bar below, and must read the small SVG count label to learn the number of bans.
|
|
>
|
|
> Goal: show a lightweight floating tooltip whenever the pointer enters a country, displaying the country's display name and its current ban count, so the information is accessible without a click.
|
|
|
|
---
|
|
|
|
### Task WM-1 — Show country name and ban count tooltip on map hover
|
|
|
|
**Scope:** `frontend/src/components/WorldMap.tsx`, `frontend/src/pages/MapPage.tsx`
|
|
|
|
`countryNames` (ISO alpha-2 → display name) is already available in `MapPage` from `useMapData` but is not forwarded to `WorldMap`. The map component itself tracks no hover state. This task adds pointer-event handlers to each country `<g>` element, tracks the hovered country in local state together with the last known mouse coordinates, and renders a positionned HTML tooltip `<div>` on top of the SVG.
|
|
|
|
**Implementation steps:**
|
|
|
|
1. **Extend `WorldMapProps` and `GeoLayerProps`** in `WorldMap.tsx`:
|
|
- Add `countryNames?: Record<string, string>` to `WorldMapProps` (optional — falls back to the ISO alpha-2 code when absent).
|
|
- Thread it through `GeoLayer` the same way the threshold props are already threaded.
|
|
|
|
2. **Add hover state to `GeoLayer`** — declare:
|
|
```ts
|
|
const [tooltip, setTooltip] = useState<{
|
|
cc: string;
|
|
count: number;
|
|
name: string;
|
|
x: number;
|
|
y: number;
|
|
} | null>(null);
|
|
```
|
|
On each country `<g>` element add:
|
|
- `onMouseEnter` — set `tooltip` with the country code, count, display name (from `countryNames`, falling back to the alpha-2 code), and mouse page coordinates (`e.clientX`, `e.clientY`).
|
|
- `onMouseMove` — update only the `x`/`y` in the existing tooltip (keep name/count stable).
|
|
- `onMouseLeave` — set `tooltip` to `null`.
|
|
|
|
Skip setting the tooltip for countries where `cc === null` (no ISO mapping available) but keep `onMouseLeave` so re-entering after leaving from an unmapped border still clears the state.
|
|
|
|
3. **Render the tooltip inside `GeoLayer`** — because `GeoLayer` is rendered inside `ComposableMap` which is inside `mapWrapper`, the tooltip div cannot be positioned relative to the map wrapper from here (the SVG clip/transform would offset it). Instead, use a React **portal** (`ReactDOM.createPortal`) to mount the tooltip directly on `document.body` so it sits in the root stacking context and can be positioned with `position: fixed` using the raw `clientX`/`clientY` coordinates.
|
|
|
|
Tooltip structure (styled with a new `makeStyles` class `tooltip` in `WorldMap.tsx`):
|
|
```tsx
|
|
{tooltip &&
|
|
createPortal(
|
|
<div
|
|
className={styles.tooltip}
|
|
style={{ left: tooltip.x + 12, top: tooltip.y + 12 }}
|
|
role="tooltip"
|
|
aria-live="polite"
|
|
>
|
|
<span className={styles.tooltipCountry}>{tooltip.name}</span>
|
|
<span className={styles.tooltipCount}>
|
|
{tooltip.count.toLocaleString()} ban{tooltip.count !== 1 ? "s" : ""}
|
|
</span>
|
|
</div>,
|
|
document.body,
|
|
)}
|
|
```
|
|
|
|
4. **Tooltip styles** — add three new classes to the `makeStyles` call in `WorldMap.tsx`:
|
|
```ts
|
|
tooltip: {
|
|
position: "fixed",
|
|
zIndex: 9999,
|
|
pointerEvents: "none",
|
|
backgroundColor: tokens.colorNeutralBackground1,
|
|
border: `1px solid ${tokens.colorNeutralStroke2}`,
|
|
borderRadius: tokens.borderRadiusSmall,
|
|
padding: `${tokens.spacingVerticalXS} ${tokens.spacingHorizontalS}`,
|
|
display: "flex",
|
|
flexDirection: "column",
|
|
gap: tokens.spacingVerticalXXS,
|
|
boxShadow: tokens.shadow4,
|
|
},
|
|
tooltipCountry: {
|
|
fontSize: tokens.fontSizeBase200,
|
|
fontWeight: tokens.fontWeightSemibold,
|
|
color: tokens.colorNeutralForeground1,
|
|
},
|
|
tooltipCount: {
|
|
fontSize: tokens.fontSizeBase200,
|
|
color: tokens.colorNeutralForeground2,
|
|
},
|
|
```
|
|
|
|
5. **Pass `countryNames` from `MapPage`** — in `MapPage.tsx`, add the `countryNames` prop to the existing `<WorldMap …>` JSX:
|
|
```tsx
|
|
<WorldMap
|
|
countries={countries}
|
|
countryNames={countryNames}
|
|
selectedCountry={selectedCountry}
|
|
onSelectCountry={setSelectedCountry}
|
|
…
|
|
/>
|
|
```
|
|
|
|
6. **Countries with zero bans** — the tooltip should still appear when the user hovers over a country with `0` bans (showing the name and "0 bans"), so users know the country is tracked but has no bans. Do not suppress the tooltip for zero-count countries.
|
|
|
|
**Acceptance criteria:**
|
|
- Moving the pointer over any mapped country on the Map page shows a floating tooltip within 0 ms (synchronous state update) containing the country's full display name (e.g. `Germany`) on the first line and the ban count (e.g. `42 bans` or `0 bans`) on the second line.
|
|
- Moving the pointer off a country hides the tooltip immediately.
|
|
- The tooltip follows the pointer as it moves within a country's borders.
|
|
- Clicking a country still selects/deselects it exactly as before; the tooltip does not interfere with the click handler.
|
|
- The tooltip is not interactive (`pointerEvents: none`) and does not steal focus from the map.
|
|
- `tsc --noEmit` produces no new errors.
|
|
|
|
**Status:** ✅ Completed (2026-03-19)
|
|
|
|
---
|
|
|
|
## Feature: Global Unique BanGUI Version
|
|
|
|
> **2026-03-17**
|
|
> The BanGUI application version is currently scattered across three independent files that are not kept in sync:
|
|
> - `Docker/VERSION` — `v0.9.8` (release artifact, written by the release script)
|
|
> - `frontend/package.json` — `0.9.8`
|
|
> - `backend/pyproject.toml` — `0.9.4` ← **out of sync**
|
|
>
|
|
> Additionally the BanGUI version is only shown in the sidebar footer (`MainLayout.tsx`). Neither the Dashboard nor the Configuration → Server view exposes the BanGUI application version, only the fail2ban daemon version.
|
|
>
|
|
> Goal: one authoritative version string, propagated automatically to all layers, and displayed consistently on both the Dashboard and the Configuration → Server page.
|
|
|
|
---
|
|
|
|
### Task GV-1 — Establish a single source of truth for the BanGUI version
|
|
|
|
**Scope:** `Docker/VERSION`, `backend/pyproject.toml`, `frontend/package.json`, `backend/app/__init__.py`
|
|
|
|
`Docker/VERSION` is already the file written by the release script (`Docker/release.sh`) and is therefore the natural single source of truth.
|
|
|
|
1. Sync the two package manifests to the current release version:
|
|
- Set `version` in `backend/pyproject.toml` to `0.9.8` (strip the leading `v` that `Docker/VERSION` contains).
|
|
- `frontend/package.json` is already `0.9.8` — no change needed.
|
|
2. Make the backend read its version **directly from `Docker/VERSION`** at import time instead of from `pyproject.toml`, so a future release-script bump of `Docker/VERSION` is sufficient. Update `_read_pyproject_version()` in `backend/app/__init__.py`:
|
|
- Add a new helper `_read_docker_version() -> str` that resolves `Docker/VERSION` relative to the repository root (two `parents` above `backend/app/`), strips the leading `v` and whitespace, and returns the bare semver string.
|
|
- Change `_read_version()` to try `_read_docker_version()` first, then fall back to `_read_pyproject_version()`, then `importlib.metadata`.
|
|
3. Make the frontend read its version from `Docker/VERSION` at build time. In `frontend/vite.config.ts`, replace the `pkg.version` import with a `fs.readFileSync('../Docker/VERSION', 'utf-8').trim().replace(/^v/, '')` call so both the dev server and production build always reflect the file.
|
|
- Update `declare const __APP_VERSION__: string;` in `frontend/src/vite-env.d.ts` if the type declaration needs adjustment (it should not).
|
|
|
|
**Acceptance criteria:**
|
|
- `backend/app/__version__` equals the content of `Docker/VERSION` (without `v` prefix) at runtime.
|
|
- `frontend` build constant `__APP_VERSION__` equals the same value.
|
|
- Bumping only `Docker/VERSION` (e.g. `v0.9.9`) causes both layers to pick up the new version without touching any other file.
|
|
- All existing tests pass (`pytest backend/`).
|
|
|
|
---
|
|
|
|
### Task GV-2 — Expose the BanGUI version through the API
|
|
|
|
**Scope:** `backend/app/models/server.py`, `backend/app/models/config.py`, `backend/app/routers/dashboard.py`, `backend/app/routers/config.py`
|
|
|
|
Add a `bangui_version` field to every API response that already carries the fail2ban daemon `version`, so the frontend can display the BanGUI application version next to it.
|
|
|
|
1. **`backend/app/models/server.py`** — Add to `ServerStatusResponse`:
|
|
```python
|
|
bangui_version: str = Field(..., description="BanGUI application version.")
|
|
```
|
|
2. **`backend/app/models/config.py`** — Add to `ServiceStatusResponse`:
|
|
```python
|
|
bangui_version: str = Field(..., description="BanGUI application version.")
|
|
```
|
|
3. **`backend/app/routers/dashboard.py`** — In `get_server_status`, import `__version__` from `app` and populate the new field:
|
|
```python
|
|
return ServerStatusResponse(status=cached, bangui_version=__version__)
|
|
```
|
|
4. **`backend/app/routers/config.py`** — Do the same for the `GET /api/config/service-status` endpoint.
|
|
|
|
**Do not** change the existing `version` field (fail2ban daemon version) — keep it exactly as-is so nothing downstream breaks.
|
|
|
|
**Acceptance criteria:**
|
|
- `GET /api/dashboard/status` response JSON contains `"bangui_version": "0.9.8"`.
|
|
- `GET /api/config/service-status` response JSON contains `"bangui_version": "0.9.8"`.
|
|
- All existing backend tests pass.
|
|
- Add one test per endpoint asserting that `bangui_version` matches `app.__version__`.
|
|
|
|
---
|
|
|
|
### Task GV-3 — Display the BanGUI version on Dashboard and Configuration → Server
|
|
|
|
**Scope:** `frontend/src/components/ServerStatusBar.tsx`, `frontend/src/components/config/ServerHealthSection.tsx`, `frontend/src/types/server.ts`, `frontend/src/types/config.ts`
|
|
|
|
After GV-2 the API delivers `bangui_version`; this task makes the frontend show it.
|
|
|
|
1. **Type definitions**
|
|
- `frontend/src/types/server.ts` — Add `bangui_version: string` to the `ServerStatusResponse` interface.
|
|
- `frontend/src/types/config.ts` — Add `bangui_version: string` to the `ServiceStatusResponse` interface.
|
|
|
|
2. **Dashboard — `ServerStatusBar.tsx`**
|
|
The status bar already renders `v{status.version}` (fail2ban version with a tooltip). Add a second badge directly adjacent to it that reads `BanGUI v{status.bangui_version}` with the tooltip `"BanGUI version"`. Match the existing badge style.
|
|
|
|
3. **Configuration → Server — `ServerHealthSection.tsx`**
|
|
The health section already renders a `Version` row with the fail2ban version. Add a new row below it labelled `BanGUI` (or `BanGUI Version`) that renders `{status.bangui_version}`. Apply the same `statLabel` / `statValue` CSS classes used by the adjacent rows.
|
|
|
|
4. **Remove the duplicate from the sidebar** — Once the version is visible on the relevant pages, the sidebar footer in `frontend/src/layouts/MainLayout.tsx` can drop `v{__APP_VERSION__}` to avoid showing the version in three places. Replace it with the plain product name `BanGUI` — **only do this if the design document (`Docs/Web-Design.md`) does not mandate showing the version there**; otherwise leave it and note the decision in a comment.
|
|
|
|
**Acceptance criteria:**
|
|
- Dashboard status bar shows `BanGUI v0.9.8` with an appropriate tooltip.
|
|
- Configuration → Server health section shows a `BanGUI` version row reading `0.9.8`.
|
|
- No TypeScript compile errors (`tsc --noEmit`).
|
|
- Both values originate from the same API field (`bangui_version`) and therefore always match the backend version.
|
|
|
|
---
|