MH-4 PHP Services + DB-Cache-Tables — Plan-Review

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

1 — Live-State Verification

2 — Artefakt-Konsum (MH-0.5 → MH-3b)

Pattern-Referenz: gui/app/Services/Apply/Baseline/ApplyBaselineService.php (existing, RECON-2.3). Behält:

• DB::transaction Atomicity
• INSERT commands + INSERT audit_events Sequence
• Hard-restrict environment = 'testnet'
• Idempotency-Key-Pattern
• Boundary contract docstring (never touches state files, never spawns worker)
• AuditMetadataScrubber für Token/Secret-Filter

3 — MH-4 Scope aus Roadmap (verifiziert)

Canonical MH-Phase-Tabelle (aus 00_overview.md §4)

Was MH-4 GENAU liefert

1. DB-Migration: 2 neue Tabellen (managed_proposals, managed_assets_history)
2. Eloquent Models: ManagedProposal, ManagedAssetHistory
3. ProposalService mit 3 Builder-Methoden:
   • createRequestCommand(asset, userId, intent) → request_managed_proposal
   • createApproveCommand(proposalId, userId, variant, overrides, hardConfirm) → approve_managed_proposal
   • createRejectCommand(proposalId, userId, reason) → reject_managed_proposal
4. ManagedStateService mit 3 Builder-Methoden:
   • createPauseCommand(asset, userId) → pause_managed_asset
   • createResumeCommand(asset, userId) → resume_managed_asset
   • createReleaseCommand(asset, userId, strategy) → release_managed_asset
5. ~30 PHPUnit Tests (Builder + Idempotency + Validator + Migration up/down)

Was MH-4 NICHT liefert (BACKLOG für andere MH-Phasen)

Service-Verantwortlichkeiten (per 05_commandbus_worker §1 Pipeline)

Operator-Klick (GUI / MH-5)
   ↓
Filament Action (admin-only, MH-5)
   ↓
Service.createXxxCommand()                           ← MH-4
   ↓
DB::transaction:
   1. INSERT commands (status='pending', idempotency_key='mh:...')
   2. INSERT audit_events (managed.asset_proposal_requested, etc.)
   3. INSERT managed_proposals (für proposal-create: state='proposal_pending')
   ↓
Worker --once / Daemon                               ← MH-6
   ↓
claim_next() → _handle_<type>() →
   - load Readers (Baseline / Managed / Proposal)
   - call Engine.generate / Writer.apply / ProposalReader.read
   - UPDATE managed_proposals (state='risk_proposed', proposal_json=...)
   - INSERT managed_assets_history
   - emit audit_event managed.* (succeeded)
   - write audit_snapshot file

4 — Konfliktcheck Sonder-Anforderungen

5 — Identifizierte Risiken

6 — Test-Plan

7 — Betroffene Dateien (Final-Inventory)

Neue Files

Unverändert

• gui/app/Services/CommandTypeRegistry.php (8 managed.* Types bereits aus MH-1)
• gui/app/Services/Apply/Baseline/ApplyBaselineService.php (Pattern-Source)
• gui/app/Services/Apply/ApplyProfileService.php (Hard-Confirm Pattern-Source)
• gui/app/Services/ConfigProfile/AuditMetadataScrubber.php (gewieder-verwendet)
• gui/app/Models/Command.php / gui/app/Models/AuditEvent.php
• 0 Bot-Side Touches (trading/*.py)
• 0 docker cp
• 0 Bot/Worker Restart

Erwartete LOC: ~600 PHP services + ~150 migrations/models + ~50 enum + ~900 tests = ~1700 LOC total.

8 — DB-Migrations-Plan

Migration 1: managed_proposals

CREATE TABLE managed_proposals (
    proposal_id           UUID PRIMARY KEY,
    asset                 VARCHAR(32) NOT NULL,
    state                 VARCHAR(32) NOT NULL,
    proposal_json         JSON,
    generated_at          TIMESTAMP,
    expires_at            TIMESTAMP,
    decided_at            TIMESTAMP NULL,
    requested_by_user_id  BIGINT NULL REFERENCES users(id) ON DELETE SET NULL,
    decided_by_user_id    BIGINT NULL REFERENCES users(id) ON DELETE SET NULL,
    decision              VARCHAR(16) NULL,
    created_at            TIMESTAMP DEFAULT now(),
    updated_at            TIMESTAMP DEFAULT now()
);
CREATE INDEX idx_managed_proposals_state    ON managed_proposals(state);
CREATE INDEX idx_managed_proposals_asset    ON managed_proposals(asset);
CREATE INDEX idx_managed_proposals_expires  ON managed_proposals(expires_at);

Migration 2: managed_assets_history

CREATE TABLE managed_assets_history (
    id            BIGSERIAL PRIMARY KEY,
    asset         VARCHAR(32) NOT NULL,
    state_from    VARCHAR(32),
    state_to      VARCHAR(32) NOT NULL,
    actor         VARCHAR(64) NOT NULL,
    event_type    VARCHAR(64) NOT NULL,
    metadata_json JSON,
    ts            TIMESTAMP NOT NULL
);
CREATE INDEX idx_managed_history_asset_ts ON managed_assets_history(asset, ts);
CREATE INDEX idx_managed_history_event    ON managed_assets_history(event_type);

Rollback Plan

• php artisan migrate:rollback --step=2 → Schema::dropIfExists('managed_proposals'); Schema::dropIfExists('managed_assets_history')
• Pre-Migration pg_dump-Backup → Restore-Point falls Rollback nicht reicht

Migration-Workflow

1. Pre-Migration Backup: pg_dump -Fc -d tradingbot_gui > /srv/shares/backups/mh-4-pre-migration-<UTC>.pgdump
2. php artisan migrate --pretend → SQL preview
3. php artisan migrate --path=database/migrations/2026_05_xx_xxxxxx_create_managed_proposals_table.php
4. php artisan migrate --path=database/migrations/2026_05_xx_xxxxxx_create_managed_assets_history_table.php
5. Verifizieren: \d managed_proposals + \d managed_assets_history + INDEX-Check
6. Rollback-Test in Staging-DB (falls vorhanden) oder unittest-suite-Sandbox

9 — Stop-Regeln MH-4

10 — Backup / Restart-Bedarf

→ MH-4 = Code+Migration+Test+Commit auf master + pg_dump-Backup. Bot bleibt komplett unbehelligt.

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

Subschnitt-Optionen

Empfehlung: MH-4a — Migration + Models + Enum atomar zuerst

Begründung:

1. Maximaler Scope-Lock: Schema-additiv-only, kein Business-Logic-Code. Klar auditierbar.
2. Migration ist riskiest sub-step: separates Commit → vor Service-Logic isoliert verifizieren
3. Eloquent Models + Enum = passive data-shape Layer; keine INSERT INTO commands etc.
4. State-Enum-Parity-Test pinnt PHP↔Bot Konvention sofort beim ersten Commit
5. Rollback-Cost minimal: migrate:rollback + git revert
6. MH-4b/c folgen sequenziell: Services bauen auf existing Schema auf, einfacher zu reviewen

Pre-Implementation-Q an Operator

1. MH-4a Subschnitt oder MH-4-monolithic? ← Empfehlung MH-4a (max scope-lock, Migration isoliert verifizierbar)
2. ManagedProposalState als PHP-Enum (Laravel 9+ feature) oder als Plain-String-Constants Class? ← Empfehlung PHP Enum (typsicher, IDE-Autocomplete, Eloquent cast)
3. Foreign Keys auf users(id): ON DELETE SET NULL oder RESTRICT? Roadmap-Schema sagt SET NULL für requested_by_user_id + decided_by_user_id. ← Empfehlung SET NULL (Audit-Trail durabel, User-Löschung erlaubt)
4. Migration-Run via php artisan migrate in GUI-Container oder via --pretend + manuell? ← Empfehlung: zuerst --pretend, dann live nach Operator-Approval auf pg_dump-Backup
5. managed_proposals.proposal_json Type: JSON (Postgres native) oder JSONB? Schema-Doc sagt JSON. ← Empfehlung JSON wie spec sagt; JSONB wäre nice-to-have für Indexing aber MH-4 hat keine JSON-path Queries

Scope-Größe + Risiko-Bewertung MH-4a

STOP vor Implementierung. Erwarte Operator-GO mit Subschnitt-Wahl (MH-4a empfohlen) + Q1-Q5-Approval.

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