MH-4c ManagedStateService — Plan-Review

Projekt: Steve-TradingBot · Phase: RECON-MH-4c · Author: claude-opus-4-7[1m]
Generated: 2026-05-12 21:17 UTC · master HEAD: 93f4026 (MH-4b-3 closed)
Status: NO CODE Plan-Review only — Operator-GO erforderlich vor MH-4c Code-Phase

1 — Live-State Verification

2 — Konsumierte Artefakte

Wichtig: ProposalService bleibt unverändert. MH-4c liefert eine eigene neue Klasse ManagedStateService (separate File).

3 — MH-4c Scope-Rekonstruktion

Roadmap-Definition (canonical aus 05_commandbus_worker §8)

class ManagedStateService
{
    public function createPauseCommand(string $asset, int $userId): Command { ... }
    public function createResumeCommand(string $asset, int $userId): Command { ... }
    public function createReleaseCommand(string $asset, int $userId, string $strategy): Command { ... }
}

3 Service-Methoden im Detail

a) createPauseCommand(string $asset, int $userId)

• Semantik: Operator pausiert managed-asset → Worker setzt später state managed_active → managed_paused
• Validation: asset regex, userId positiv
• Idempotency-Key: mh:pause:{asset}:{YmdHis} (per-click distinct, NICHT shared)
• Hard-Confirm: ❌ NEIN (low-risk, reversibel via resume)
• CommandType: pause_managed_asset (Registry timeout 120s)
• Audit: managed.asset_pause_requested

b) createResumeCommand(string $asset, int $userId)

• Semantik: Operator resumed → Worker setzt later state managed_paused → managed_active
• Validation: asset regex, userId positiv
• Idempotency-Key: mh:resume:{asset}:{YmdHis}
• Hard-Confirm: ❌ NEIN
• CommandType: resume_managed_asset
• Audit: managed.asset_resume_requested

c) createReleaseCommand(string $asset, int $userId, string $strategy, string $hardConfirm)

• Semantik: Operator released → Asset verlässt managed-Lebenszyklus. High-Risk, semantisch irreversibel
• Validation: asset regex, userId positiv, strategy whitelisted, hardConfirm exact-match
• Idempotency-Key: mh:release:{asset}:{YmdHis}
• Hard-Confirm: ✅ JA — <asset>:release:<strategy> (case-sensitive)
• CommandType: release_managed_asset
• Audit: managed.asset_release_requested

Strategy-Whitelist für Release

Vorschlag — 2 Werte:

• to_frozen: Asset returns to baseline frozen policy. Worker setzt state managed_* → managed_released → später frozen (Two-File-Atomic, MH-6 Worker-Job).
• mark_released_only: State-flip auf managed_released ohne Policy-Wechsel. Asset bleibt in managed_released für Audit-Trail. Operator entscheidet später separat über frozen-Revert.

Welche DB-Reads/Writes sind erlaubt?

READ (Phase 1, empfohlen):

• ❌ NICHT managed_proposals (wrong domain — proposals vs. managed-assets)
• ❌ NICHT managed_assets_history (Service schreibt da nichts; muss da auch nichts lesen in Phase 1)
• ❌ NICHT managed_state.json (Hybrid C — GUI liest keine Bot-Files)

→ MH-4c-Phase-1 macht KEINE State-Cache-Lookup. Service ist pure command-builder. Worker MH-6 ist final state-validator.

WRITE:

• ✅ INSERT commands (status=pending)
• ✅ INSERT audit_events (managed.asset_*_requested)
• ❌ NIE managed_proposals
• ❌ NIE managed_assets_history (Worker MH-6)
• ❌ NIE State-Files

State-Transitions: nur vorbereitet, nicht ausgeführt

4 — Konfliktcheck Sonder-Anforderungen

5 — Empfohlene Lieferung

Service-API

namespace App\Services\Managed;

class ManagedStateService
{
    public function __construct(private readonly CommandTypeRegistry $commandRegistry) {}

    public function createPauseCommand(string $asset, int $userId): Command;
    public function createResumeCommand(string $asset, int $userId): Command;
    public function createReleaseCommand(
        string $asset, int $userId, string $strategy, string $hardConfirm
    ): Command;

    // Public static helper (reusable in MH-5 Wizard)
    public static function buildReleaseHardConfirmString(
        string $asset, string $strategy
    ): string;  // returns "<asset>:release:<strategy>"

    // Constants
    public const REQUEST_ENVIRONMENT     = 'testnet';
    public const AUDIT_SUBJECT_TYPE      = 'ManagedAsset';
    public const PAUSE_TIMEOUT_SECONDS   = 120;
    public const RESUME_TIMEOUT_SECONDS  = 120;
    public const RELEASE_TIMEOUT_SECONDS = 120;
    public const ALLOWED_RELEASE_STRATEGIES = ['to_frozen', 'mark_released_only'];
}

Erlaubte Methoden

• 3 public command-builder
• 1 public static helper (Hard-Confirm-Builder für release)
• private validateAsset (mirror aus ProposalService)
• private validateUserId (mirror)
• private validateStrategy (NEU — whitelist-check)
• private validateHardConfirm (NEU für release)
• private writeAudit (mirror)
• private buildXxxIdempotencyKey (3 builders)

Verbotene Methoden

• Command::update()
• ManagedProposal::* (different domain)
• ManagedAssetHistory::* (Worker MH-6)
• File-IO / Subprocess
• environment != 'testnet'

Exceptions

0 neue Exception-Klassen. Reuse aus MH-4b:

• InvalidCommandPayloadException für asset/userId/strategy/hardConfirm-Validierung
• Keine state-spezifischen Exceptions in MH-4c-Phase-1 (kein state-cache-lookup)

Payload-Schemas

pause / resume:

{
  "environment":  "testnet",
  "asset":        "<asset>",
  "requested_by": <userId>,
  "expires_at":   "<iso8601-z>"
}

release:

{
  "environment":  "testnet",
  "asset":        "<asset>",
  "strategy":     "to_frozen|mark_released_only",
  "hard_confirm": "<asset>:release:<strategy>",
  "requested_by": <userId>,
  "expires_at":   "<iso8601-z>"
}

Idempotency-Keys

NICHT shared wie decide. Operator kann legitim mehrfach pause/resume/release klicken — jeder Click = neuer Command + neuer Audit-Trail.

6 — Test-Plan

7 — Betroffene Dateien

Neue Files

Unverändert

• gui/app/Services/Managed/ProposalService.php (MH-4b komplett intact)
• gui/app/Services/CommandTypeRegistry.php (3 Validators existieren ab MH-1)
• alle MH-4a/4b Modelle + Migrations
• Bot-Side trading/*.py — 0 Touches

Erwartete LOC: ~450 Service + ~750 Tests = ~1200 LOC

8 — Stop-Regeln MH-4c

9 — Backup / Migration / Restart-Bedarf

→ MH-4c = Reine Code+Test+Commit Phase.

10 — Risiken-Übersicht

11 — Kleinste sichere Code-Phase + GO/NO-GO

Subschnitt-Optionen

Empfehlung: MH-4c-monolithic

Begründung:

1. Pattern voll etabliert durch MH-4b — keine Discovery
2. 3 Methoden gehören semantisch zusammen als asset-lifecycle commands; sub-cuts würden Wizard-Build (MH-5) unvollständig deployen
3. Service hat NICHTS Komplexes — pure command-builder ohne state-cache lookup
4. Release ist die einzige nicht-triviale Methode (Hard-Confirm + Strategy); pause/resume sind trivial
5. Rollback-Cost minimal: git revert + 0 DB-Rows

Pre-Implementation-Q an Operator

1. MH-4c-monolithic oder Sub-Cut? ← Empfehlung monolithisch
2. ManagedStateService als separate Klasse ODER Methoden in ProposalService einbauen? ← Empfehlung separate Klasse (saubere domain-separation)
3. Release Strategy-Whitelist: ['to_frozen', 'mark_released_only'] — beide? andere Werte? ← Empfehlung beide, Operator kann später erweitern
4. Release Hard-Confirm Format: <asset>:release:<strategy> (3-Teil mit strategy-binding) ODER <asset>:release (2-Teil simpel)? ← Empfehlung 3-Teil (bindet an strategy-Wahl)
5. pause/resume Hard-Confirm: NEIN (low-risk, reversibel)? ← Empfehlung JA, NEIN bestätigen
6. State-Cache-Lookup-Strategie: Phase 1 NO lookup (Worker = authoritative) ← Empfehlung Phase 1 NO lookup
7. Code-Reuse aus ProposalService: Duplizieren ODER Trait extrahieren? ← Empfehlung Duplizieren (kein Premature-Abstraction)
8. 0 neue Exception-Klassen bestätigen? ← Empfehlung JA (InvalidCommandPayloadException reicht)
9. audit_event_types: managed.asset_pause_requested / managed.asset_resume_requested / managed.asset_release_requested bestätigen?

Scope-Größe + Risiko-Bewertung MH-4c-monolithic

STOP vor Implementierung. Erwarte Operator-GO mit Subschnitt-Wahl (monolithic empfohlen) + Q1-Q9-Approval, insbesondere Strategy-Whitelist + Hard-Confirm-Format + State-Cache-Lookup-Strategie.

© Steve-TradingBot · RECON-MH-4c · Plan-Review (no-code phase)