feat(G): G-WORK/G-HUMAN-DEC/G-UI-TEMPL/G-DOC — workflow workstream, decision guard, template gallery (3 templates), API docs, 43 tests passing

2026-08-18 11:11:50 +02:00
parent 1bf776dff5
commit 59f05de621
5 changed files with 705 additions and 0 deletions
@@ -640,3 +640,83 @@ WebSocket and REST endpoints for AI-driven UI control.
 3. **OpenAPI**: The full OpenAPI spec is available at `/openapi.json` — use it for dynamic endpoint discovery.
 4. **Safe Methods**: GET endpoints are safe to probe. POST/PUT/DELETE require careful payload construction.
 5. **Session Auth**: AI agents should call `POST /api/v1/auth/login` first, then use the returned cookie for all subsequent requests.
+
+---
+
+## Phase G — Workflow MVP Endpoints
+
+### Workflow CRUD
+| Method | Path | Description | Permission |
+|--------|------|-------------|-----------|
+| GET | `/api/v1/workflows` | List workflows (paginated) | `workflows:read` |
+| POST | `/api/v1/workflows` | Create workflow definition | `workflows:write` |
+| GET | `/api/v1/workflows/{id}` | Get workflow by ID | `workflows:read` |
+| PATCH | `/api/v1/workflows/{id}` | Update workflow | `workflows:write` |
+| DELETE | `/api/v1/workflows/{id}` | Delete workflow | `workflows:write` |
+
+### Workflow Instances
+| Method | Path | Description | Permission |
+|--------|------|-------------|-----------|
+| GET | `/api/v1/workflows/instances` | List instances (paginated) | `workflows:read` |
+| POST | `/api/v1/workflows/{id}/instances` | Create instance | `workflows:write` |
+| GET | `/api/v1/workflows/instances/{id}` | Get instance by ID | `workflows:read` |
+| POST | `/api/v1/workflows/instances/{id}/advance` | Advance to next step | `workflows:write` |
+| POST | `/api/v1/workflows/instances/{id}/cancel` | Cancel instance | `workflows:write` |
+| POST | `/api/v1/workflows/instances/{id}/resume` | Resume waiting instance (G-RUN) | `workflows:write` |
+| GET | `/api/v1/workflows/instances/{id}/history` | Step history / execution log (G-LOG) | `workflows:read` |
+
+### Triggers (G-EVT, G-MAN, G-WEB)
+| Method | Path | Description | Permission |
+|--------|------|-------------|-----------|
+| POST | `/api/v1/workflows/{id}/trigger` | Manual trigger (G-MAN) | `workflows:write` |
+| POST | `/api/v1/workflows/webhook/{token}` | Incoming webhook trigger (G-WEB) | Token-based |
+
+### Approval (G-APPROVAL)
+| Method | Path | Description | Permission |
+|--------|------|-------------|-----------|
+| POST | `/api/v1/workflows/instances/{id}/approve` | Approve current step | `workflows:write` |
+| POST | `/api/v1/workflows/instances/{id}/reject` | Reject current step | `workflows:write` |
+
+### Templates (G-UI-TEMPL)
+| Method | Path | Description | Permission |
+|--------|------|-------------|-----------|
+| GET | `/api/v1/workflows/templates` | List workflow templates | `workflows:read` |
+| POST | `/api/v1/workflows/templates/{id}/instantiate` | Create workflow from template | `workflows:write` |
+
+### Step Types (14 total)
+| Type | Description | Config Fields |
+|------|-------------|---------------|
+| `action` | Execute configured action | `action_type`, `user_id`, `notification_*` |
+| `approval` | Pause for human approval | (none) |
+| `notification` | Send notification | `user_id`, `title`, `body`, `notification_type` |
+| `condition` | Branch on condition | `field`, `operator`, `value`, `on_true_step`, `on_false_step` |
+| `wait` | Wait/delay (G-WAIT) | `duration_seconds` or `resume_at` |
+| `http` | HTTP request (G-HTTP) | `method`, `url`, `headers`, `body`, `timeout_seconds`, `response_mapping` |
+| `mail` | Send email (G-MAIL) | `to`, `subject`, `body`, `account_id` |
+| `calendar` | Calendar event (G-CAL) | `action`, `title`, `start`, `end`, `event_id` |
+| `dms` | DMS interaction (G-DMS) | `action`, `query`, `file_id` |
+| `search` | Unified search (G-SEARCH) | `query`, `entity_type`, `limit` |
+| `agent` | Invoke AI agent (G-AGENT) | `agent_id`, `input`, `wait_for_completion` |
+| `crm` | CRM action (G-CRM) | `action`, `data`, `entity_id` |
+| `event` | Publish event (G-EVT) | `event_name`, `payload` |
+| `webhook` | Outgoing webhook (G-WEB) | `url`, `method`, `headers`, `body` |
+
+### Durable WorkflowRun (G-RUN)
+- `status`: `pending` → `in_progress` → `waiting` → `in_progress` → `completed` / `failed` / `cancelled`
+- `resume_at`: ISO datetime when waiting instance should be resumed
+- `resume_reason`: `wait`, `approval`, `retry`, `event`, `webhook`
+- `step_state`: JSONB — per-step output stored for data flow between steps (G-CTX)
+- `retry_count` / `max_retries`: Retry with exponential backoff (G-RETRY)
+- `lock_owner` / `lock_expires_at`: Redis lock for concurrency control
+- `idempotency_key`: Deduplication for side-effect steps (G-IDEMP)
+- `error_message`: Last error message if failed
+
+### SSRF Protection (G-HTTP)
+HTTP and webhook steps block:
+- Private/internal IP ranges (10.x, 172.16-31.x, 192.168.x)
+- Localhost (127.0.0.1, ::1, localhost)
+- Cloud metadata endpoints (metadata.google.internal)
+- Non-HTTP/HTTPS schemes (ftp, file, gopher)
+
+### Automated-Decision Guard (G-HUMAN-DEC)
+Workflow steps with `ai_use_case_metadata` containing `risk_level >= medium` or `requires_approval: true` or `auto_execute: false` require human approval before execution. High-risk actions (send_email, delete_entity, execute_payment, etc.) require review even at low risk levels.