forked from longtao.wu/droboticflow
70 lines
7.6 KiB
Markdown
70 lines
7.6 KiB
Markdown
# 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/*`).
|