michaelschiemer/docs/tasks.md

# Improvement Tasks Checklist

This document lists actionable, logically ordered improvements for the project. Each task is prefixed with a checkbox for tracking. Tasks span architecture, quality, security, performance, testing, developer experience, and documentation.

Note: Some items reference existing files and modules to guide implementation. Execute tasks incrementally from top to bottom for best results.

## Wichtigste Aufgaben (Top-Prioritäten – sofort angehen)

Die folgenden Punkte liefern den größten Nutzen und sollten priorisiert bearbeitet werden. Sie referenzieren die entsprechenden Abschnitte weiter unten.

- [ ] CI/CD Pipeline aufsetzen und härten (Lint, PHPStan, Tests, Composer Audit) – siehe „CI/CD Pipeline Hardening“ (Punkt 2). Blocking für Qualität und Sicherheit.
- [ ] Statische Analyse hochdrehen (strict_types prüfen, PHPStan-Level erhöhen, Baseline pflegen) – siehe „Static Analysis and Type Safety“ (Punkt 3). Schneller Qualitätsgewinn.
- [ ] Kritische Tests ergänzen: Sicherheitskomponenten/WAF und Integrationspfade (Auth, Persistence) – siehe „Testing Improvements“ (Punkt 14/15) und „Security Improvements“ (Punkt 7).
- [ ] CacheKey-Typo in CacheFeatureFlagRepository beheben und Negative-Caching-Strategie absichern – siehe „Feature Flags System“ (Punkt 11) und „Concrete Fixes“ (Punkt 20).
- [ ] HTTP-Layer Tests für HttpRequest/Query, Fehlerpfade und Middleware-Kette – siehe „HTTP Layer and Routing“ (Punkt 10).
- [ ] WAF/Rate Limiting verbessern, Regeln schärfen, Tests hinzufügen – siehe „Security Improvements > Enhance WAF functionality“ (Punkt 7/IntelligentRateLimitLayer).
- [ ] Konfiguration & Secrets zentralisieren (.env.example vervollständigen, Validierung beim Boot) – siehe „Configuration and Secrets Management“ (Punkt 5).
- [ ] Observability Basis schaffen: strukturierte Logs, Metriken (Hit/Miss/Errors), Tracing-Hooks – siehe „Error Handling and Observability“ (Punkt 6) und „Performance and Caching“ (Punkt 8).
- [ ] Datenbank-Quick-Wins: N+1 erkennen, Indexe ergänzen, Integrations-Tests für Repositories – siehe „Data Layer and Persistence“ (Punkt 9).
- [ ] Deployment/Operations stabilisieren: Healthchecks in Docker Compose, idempotente Deploy-Schritte – siehe „Deployment and Ops“ (Punkt 19).
- [ ] Developer-Docs aktualisieren (Getting Started, Troubleshooting) und ADRs für Schlüsselentscheidungen – siehe „Documentation“ (Punkt 17) und „Developer Experience“ (Punkt 16).

1. [ ] Establish a Baseline and Governance
   - [ ] Define and document the minimum supported PHP version and runtime requirements (extensions) in README and composer.json (platform). 
   - [ ] Align coding standards across the codebase (PHP CS Fixer rules and .editorconfig) and enforce via CI. 
   - [ ] Introduce a clear versioning strategy (SemVer), CHANGELOG, and release process.
   - [ ] Audit .gitignore to ensure build artifacts, caches (var/, storage/cache/, vendor/* docs), and generated files are excluded from VCS.

2. [ ] CI/CD Pipeline Hardening
   - [ ] Add CI jobs: lint (php-cs-fixer dry-run), static analysis (phpstan), unit/integration tests (Pest), security scan (composer audit). 
   - [ ] Add optional coverage reporting with Xdebug (XDEBUG_MODE=coverage) and a minimum threshold. 
   - [ ] Add Docker image build/test job and push to a registry for deployment. 
   - [ ] Introduce pre-commit hooks (lint, phpstan, pest) via Husky or CaptainHook for local dev.

3. [ ] Static Analysis and Type Safety
   - [ ] Enable strict_types everywhere (verify headers and add missing declarations). 
   - [ ] Raise PHPStan level progressively to target a high level (e.g., 8/9) and generate/update baseline responsibly. 
   - [ ] Add Psalm or PHPStan-specific rules for DDD boundaries and unsafe patterns (mixed usage, array shape validation). 
   - [ ] Replace magic arrays with value objects or DTOs where appropriate; document contracts.

4. [ ] Dependency Injection and Module Boundaries
   - [ ] Document and formalize module boundaries (src/Application, src/Domain, src/Framework, src/Infrastructure) with allowed dependency directions. 
   - [ ] Add architectural tests (Pest plugin or custom) to enforce dependency rules. 
   - [ ] Review service wiring/discovery (DiscoveryServiceBootstrapper) and replace reflection-heavy or dynamic patterns with explicit configuration where it improves clarity/perf. 
   - [ ] Ensure constructors favor interfaces; introduce missing interfaces for concrete dependencies.

5. [ ] Configuration and Secrets Management
   - [ ] Centralize configuration (env/config/*.php) and document defaults and overrides. 
   - [ ] Validate config at boot (fail-fast with actionable errors). 
   - [ ] Ensure secrets are sourced from environment/secret stores, not committed; add examples to .env.example. 
   - [ ] Add configuration schema tests (ensuring required keys and types).

6. [ ] Error Handling and Observability
   - [ ] Standardize exception hierarchy and error codes across modules; avoid silent failures. 
   - [ ] Add structured logging with context IDs (correlation, request, user) and log levels policy. 
   - [ ] Introduce metrics for key operations (HTTP, cache, DB, queue) and expose Prometheus endpoint securely. 
   - [ ] Add tracing hooks (OpenTelemetry) for critical paths; document propagation.

7. [ ] Security Posture
   - [ ] Perform a security audit against OWASP Top 10; document findings and remediation plan. 
   - [ ] Harden WAF (src/Framework/Waf): review rules, rate limiting strategies, false positive handling, and add tests. 
   - [ ] Ensure input validation and output encoding in View processors; review IfProcessor and templating for SSR XSS vectors. 
   - [ ] Enforce HTTPS, secure cookies, CSRF tokens, and security headers (CSP, HSTS) in HTTP module and Nginx config. 
   - [ ] Add dependency vulnerability scanning in CI (e.g., symfony/security-checker replacement via Composer audit).

8. [ ] Performance and Caching
   - [ ] Review and document cache strategy (Cache, MultiLevelCache, Async caches) and TTL policies per domain entity. 
   - [ ] Add cache metrics (hit/miss/evictions) and logs to analyze effectiveness. 
   - [ ] Implement cache warming for critical data at boot or via worker. 
   - [ ] Resolve known cache correctness issues (e.g., negative caching keys, serialization safety). 
   - [ ] Validate cache key naming with a central builder; enforce namespacing to avoid collisions.

9. [ ] Data Layer and Persistence
   - [ ] Review repositories for N+1 queries and missing indexes; add DB migrations and schema docs. 
   - [ ] Create integration tests for critical repositories. 
   - [ ] Introduce transaction boundaries and retry strategy where needed. 
   - [ ] Add database health checks and readiness probes for Docker composition.

10. [ ] HTTP Layer and Routing
    - [ ] Increase test coverage for HttpRequest, Query, route resolution, middleware chain, and error responses. 
    - [ ] Validate query parsing edge cases (duplicate keys, encodings) and add regression tests. 
    - [ ] Normalize header casing and ensure PSR-7 compatibility where applicable. 
    - [ ] Add request/response size limits and timeouts; document defaults.

11. [ ] Feature Flags System
    - [ ] Define a canonical FeatureFlag repository interface contract and behaviors (null vs. NOT_FOUND semantics). 
    - [ ] Add integration tests for CacheFeatureFlagRepository and FileFeatureFlagRepository, including negative cache behavior. 
    - [ ] Fix typing/typos in cache key creation (CacheKey vs Cachekey) and ensure cache stores only serializable, immutable objects. 
    - [ ] Add an admin endpoint/UI hardening with authorization checks in FeatureFlagController.

12. [ ] Search Module
    - [ ] Validate SearchRequest input constraints and canonicalize parameters. 
    - [ ] Add tests for SearchController behavior (pagination, empty results, errors). 
    - [ ] Document search adapter contracts and index lifecycle.

13. [ ] View and Templating
    - [ ] Review Processors (e.g., IfProcessor) for safety and predictable evaluation semantics. 
    - [ ] Add template linting step and cached view invalidation strategy. 
    - [ ] Ensure compiled view cache is not committed and is purged on deploy; update .gitignore if necessary.

14. [ ] Queue and Async Processing
    - [ ] Define interfaces and contracts for queue-worker; add retry and backoff strategies. 
    - [ ] Add idempotency guards for jobs and visibility timeouts. 
    - [ ] Provide metrics and DLQ handling documentation.

15. [ ] Testing Strategy (Pest)
    - [ ] Standardize test namespaces and file layout; ensure Tests mirror src structure. 
    - [ ] Add factories/fixtures for common entities and a Faker-based generator. 
    - [ ] Add integration tests for critical flows (auth, payments, persistence). 
    - [ ] Add browser/E2E tests (Cypress/Selenium) for top user journeys (optional but recommended). 
    - [ ] Establish coverage thresholds per package and enforce in CI.

16. [ ] Developer Experience
    - [ ] Update Getting Started docs and ensure Docker build.sh and docker-compose flows are reliable across platforms. 
    - [ ] Provide make targets or composer scripts for common tasks (cs, cs-fix, phpstan, pest, reload). 
    - [ ] Create troubleshooting docs for Docker/DNS/cache issues; link from README. 
    - [ ] Add local development data seeding scripts and reset commands.

17. [ ] Documentation
    - [ ] Consolidate scattered docs and backups (backups/docs-backup-*/), migrate relevant content into docs/. 
    - [ ] Add architecture decision records (ADRs) for key choices (DI, caching, WAF, templating). 
    - [ ] Auto-generate API docs where feasible and publish via the existing /api/docs endpoints. 
    - [ ] Keep README concise and link to deeper docs; add contribution guidelines cross-links.

18. [ ] Code Hygiene and Consistency
    - [ ] Eliminate dead code, unused classes, and outdated experimental files; add CI check for unused symbols if possible. 
    - [ ] Normalize naming (English vs. German in code identifiers; German is fine for test names per guidelines). 
    - [ ] Ensure immutability/read-only where appropriate (readonly, final) and avoid incidental mutation. 
    - [ ] Replace ad-hoc string constants with enums/ValueObjects where it improves safety. 
    - [ ] Ensure all public APIs have PHPDoc where types can’t fully express intent.

19. [ ] Deployment and Ops
    - [ ] Review deploy.sh steps for idempotency and error handling; add rollback steps. 
    - [ ] Add health checks to Docker Compose (web, php, db, redis) and readiness/liveness probes. 
    - [ ] Parameterize environment-specific config (staging/production) and secrets injection. 
    - [ ] Ensure asset build and cache warmups are part of deployment pipeline.

20. [ ] Concrete Fixes Identified During Review
    - [ ] Fix Cache key class typo in CacheFeatureFlagRepository::getCacheKey (use CacheKey, not Cachekey) and add a unit test to catch it. 
    - [ ] Verify negative caching marker ('NOT_FOUND') doesn’t collide with real values; prefer a dedicated NullObject or sentinel ValueObject. 
    - [ ] Audit src/Framework/View/cache/* and similar generated artifacts into .gitignore and remove from repo if committed.

21. [ ] Monitoring and Alerting
    - [ ] Add basic alerting for error rates, latency, and resource saturation. 
    - [ ] Create runbooks for on-call responses and link them from docs/operations.

22. [ ] Accessibility and Internationalization (Optional but Valuable)
    - [ ] Add A11y checks for rendered views and components. 
    - [ ] Formalize i18n/l10n strategy for user-facing content.

23. [ ] Risk Register and Backlog Grooming
    - [ ] Maintain a living risk register (security, data loss, availability) and mitigation tasks. 
    - [ ] Review this checklist quarterly and update priorities.