droboticflow-new/PROJECT.md

7.6 KiB

Project: droboticflow Dual-Track Workflow Execution Isolation (Debug Run vs Production Run)

Architecture

The system establishes strict dual-track isolation between Production Runs (正式运行) and Debug Runs (调试运行) across the entire lifecycle:

  1. Frontend Experience:
    • Dual action buttons in the Workflow Editor: Orange 【调试运行】 (Debug Run) and Green/Blue 【正式运行】 (Production Run).
    • Production Data Input Panel: Exclusively exposes root workflow input ports (syncRootWorkflowInputs), rendering all intermediate nodes and hyperparameters as collapsed, read-only sections with "🔒 已锁定不可篡改".
    • Developer Debug Console: Enables instant node hyperparameter overrides, dev/poc environment switching, and step/single-node execution on draft workflows.
    • Monitoring & Project Views: Dedicated mode filter (all | production | debug) with distinct visual badges and temporary artifact indicators.
  2. Backend Security & API Layer:
    • POST /api/workflow-releases/:id/runs: Dedicated production execution endpoint bound strictly to immutable WorkflowReleaseRecord. Returns HTTP 422 production_input_forbidden if any non-root inputs, node overrides, or topology modifications are present.
    • POST /api/workflows/:id/run: Supports debug execution with transient nodeOverrides, debugTarget (single-node or subtree), and draft state execution.
    • Immutable metadata binding for production runs (mode: "production", releaseId, workflowVersion, gitCommitSha, imageDigest).
  3. Execution Engine & Worker:
    • Worker runtime applies NodeOverrides during execution without mutating the database workflow record.
    • Support for single-node execution targets and transient execution states.
  4. Metrics, Delivery & Audit Isolation:
    • Workforce calculations (dashboard_workforce.go) and platform metrics (memory.go:BuildDashboardSummaryAt) strictly filter out debug runs/events.
    • DeliveryPackage creation and listing isolate production deliverables; debug artifacts are tagged as temporary.

Feature Inventory

# Feature Description Milestone Source
F1 RunMode Domain & Storage Models Add RunMode (production / debug) and provenance fields (ReleaseID, WorkflowVersion, GitCommitSha, ImageDigest, NodeOverrides, DebugTarget) to RunRecord, RunSummary, RunSummaryQuery, and update Memory/Mongo stores M1 Survey (Backend/Metrics)
F2 Metrics & Worklog Event Domain Models Add Mode and temporary tagging to AnnotationWorklogEventRecord, DeliveryPackageRecord, and ExecutionArtifact M1 Survey (Metrics)
F3 Production Run Release API & Security Gate Implement POST /api/workflow-releases/:id/runs with 422 production_input_forbidden rejection for non-root inputs or parameter tampering M2 Survey (Backend) & R1/R2
F4 Debug Run API & Node Overrides Enhance /api/workflows/:id/run for draft execution, transient node overrides, and single-node debug targeting M2 Survey (Backend) & R1/R2
F5 Worker Runtime Transient Overrides & Single-Node Enable worker scheduler to execute single nodes and apply per-run node parameter overrides M2 Survey (Backend) & R1
F6 Workforce Metrics Isolation Filter out debug events from QualityPassRate, AcceptancePassRate, ReworkRate, and DurationSeconds in dashboard_workforce.go M3 Survey (Metrics) & R4
F7 DeliveryPackage & Artifact Isolation Isolate formal DeliveryPackages to production runs and tag debug artifacts as temporary M3 Survey (Metrics) & R4
F8 Frontend Action Bar Dual Triggers Dual action buttons (Debug Run vs Production Run) in WorkflowEditor.tsx & WorkflowEditorControls.tsx M4 Survey (Frontend) & R3
F9 Production Data Input Panel with Locked Nodes Modal showing root inputs with intermediate nodes locked ("🔒 已锁定不可篡改") M4 Survey (Frontend) & R3
F10 Developer Debug Console UI Modal supporting node parameter overrides, dev/poc env selector, and step/single-node execution M4 Survey (Frontend) & R3
F11 Monitoring Center & History Mode Filters Add mode filter (all / production / debug) and badges to Monitoring.tsx, monitoring.ts, and ProjectDetail.tsx M5 Survey (Frontend) & R4
F12 Comprehensive E2E Testing Suite Requirements-driven 4-tier test suite covering R1-R4 acceptance criteria E2E Track Survey (Metrics) & AC
F13 Final Integration & Adversarial Hardening Pass 100% E2E tests + Tier 5 white-box adversarial verification M6 Survey & Dual Track

Milestones

# Name Scope Dependencies Status
M1 Domain Models & Storage Persistence internal/domain, internal/store (RunMode, RunRecord, RunSummary, Store queries) none DONE
M2 Backend APIs, Security Gate & Worker Engine internal/api (/api/workflow-releases/:id/runs, 422 gate, debug run), internal/worker (overrides, single-node) M1 DONE
M3 Metrics, Delivery & Audit Isolation internal/api/dashboard_workforce.go, internal/api/delivery_packages.go, internal/worker/human_release.go M1, M2 DONE
M4 Frontend Workflow Editor Dual-Track Controls & Modals src/pages/WorkflowEditor.tsx, src/components/WorkflowEditorControls.tsx, src/lib/workflow-editor.js M2 DONE
M5 Frontend Monitoring & History Mode Filters src/pages/Monitoring.tsx, src/services/api/monitoring.ts, src/pages/ProjectDetail.tsx M1, M2 DONE
M6 Final Verification & Adversarial Hardening 100% E2E test suite pass + Tier 5 adversarial testing loop M1, M2, M3, M4, M5, E2E Track DONE

Interface Contracts

Client ↔ Backend API

  1. Production Run: POST /api/workflow-releases/:id/runs
    • Request Body: { "trigger": "manual", "inputs": { [portKey: string]: ArtifactPayload } }
    • Response: 202 Accepted with RunRecord (where mode: "production", releaseId, workflowVersion, gitCommitSha, imageDigest).
    • Error on tampering: 422 Unprocessable Entity with { "error": "...", "code": "production_input_forbidden", "issues": [...] }.
  2. Debug Run: POST /api/workflows/:id/run
    • Request Body: { "trigger": "manual", "mode": "debug", "inputs": { ... }, "nodeOverrides": { [nodeId: string]: NodeOverride }, "debugTarget": { "targetNodeId": string, "singleNode": boolean } }
    • Response: 202 Accepted with RunRecord (where mode: "debug").
  3. Run Query: GET /api/runs?mode=production|debug|all&status=...&projectId=...
    • Response: Paginated list of RunSummary records matching the mode filter.

Code Layout

  • internal/domain/: Domain models (types.go, workflow_release.go, workflow_inputs.go, delivery_package.go, annotation_operations.go).
  • internal/store/: Store interfaces & implementations (store.go, memory.go, mongo.go).
  • internal/api/: REST handlers (server.go, workflow_releases.go, dashboard_workforce.go, delivery_packages.go, tenant.go).
  • internal/worker/: Workflow execution runtime (runtime.go, executor.go, human_release.go).
  • src/lib/: Frontend utilities (workflow-editor.js, workflow-inputs.js).
  • src/components/: Frontend components (WorkflowEditorControls.tsx, WorkflowEditorModals.tsx, etc.).
  • src/pages/: Frontend pages (WorkflowEditor.tsx, Monitoring.tsx, ProjectDetail.tsx, Dashboard.tsx).
  • src/services/api/: Frontend API clients (workflows.ts, monitoring.ts, workflow-releases.ts).
  • tests/: Automated tests (tests/frontend/, backend Go tests in internal/*).