Update Tasks documentation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-04-25 18:26:40 +02:00
parent 24f9fdd358
commit c3410bd554

View File

@@ -1,52 +1,3 @@
### T-04 · Encapsulate `geo_service` module-level mutable state in a class
**Where found:** `backend/app/services/geo_service.py` — module globals `_cache`, `_neg_cache`, `_dirty`, `_geoip_reader`, `_geoip_initialized`, `_cache_lock`
**Why this is needed:** Module-level mutable state is invisible to callers, cannot be injected, and requires test-escape-hatch functions (`clear_cache()`) that exist only because the state can't be reset otherwise. It also violates SRP — the module owns both the geo lookup logic *and* the cache lifecycle.
**Goal:** `GeoCache` class with instance state, instantiated once at startup and stored on `app.state` (consistent with `InMemorySessionCache`).
**What to do:**
1. Create `class GeoCache` in `geo_service.py` or a new `app/services/geo_cache.py` with the cache dict, neg-cache, dirty set, and lock as instance attributes.
2. Expose `lookup`, `lookup_batch`, `flush_dirty`, `load_from_db`, `clear`, etc. as methods.
3. Instantiate in `startup.py` or `main.py` lifespan and store as `app.state.geo_cache`.
4. Update `dependencies.py` to inject `GeoCache` rather than returning `geo_service.lookup_batch` directly.
5. Remove `clear_cache()` and `clear_neg_cache()` module-level functions (move to instance methods).
**Possible traps and issues:**
- Background tasks (`geo_cache_flush.py`, `geo_re_resolve.py`) reference module-level functions. They need to receive the `GeoCache` instance.
- `geo_service.is_cached()` is called from `ban_service` — update call sites.
- Many tests likely patch `geo_service._cache` or call `geo_service.clear_cache()` — all tests need updating.
**Docs changes needed:** `Docs/Architekture.md` — document `GeoCache` as a managed stateful service alongside session cache.
**Doc references:** `Docs/Architekture.md`, `Docs/Backend-Development.md`
---
### T-05 · Remove `app.state` mutation from `_build_app_context` in `dependencies.py`
**Where found:** `backend/app/dependencies.py``_build_app_context()` mutates `state.session_cache` on every request
**Why this is needed:** A function named `_build_app_context` (a "build" / read operation) has a side effect of mutating `app.state`. Startup configuration decisions belong in the lifespan handler, not in the per-request dependency graph.
**Goal:** `_build_app_context` is pure (read-only). Session cache type is decided once at startup in `main.py`.
**What to do:**
1. Move the session cache swap logic (`_session_cache_enabled` check → replace `NoOpSessionCache` with `InMemorySessionCache`) to the lifespan handler in `main.py`.
2. Remove the three `if/elif/elif` branches mutating `state.session_cache` from `_build_app_context`.
3. Ensure settings-change flow (runtime settings update) also triggers a cache swap if needed.
**Possible traps and issues:**
- If `runtime_settings` can change mid-process (setup wizard updates settings), the cache swap must still happen. Identify where `runtime_settings` is set and add a swap there.
- Tests that call `_build_app_context` directly may rely on the mutation side effect.
**Docs changes needed:** None.
**Doc references:** `backend/app/dependencies.py`, `backend/app/main.py`
---
### T-06 · Eliminate `AppState` Protocol / `ApplicationContext` dataclass redundancy
**Where found:** `backend/app/dependencies.py``AppState` Protocol (lines ~4060) and `ApplicationContext` dataclass (lines ~6275) describe identical fields.