docs: define admin-managed workflow tasks

2026-05-22 03:22:38 +03:00
parent 5ea0d5978a
commit d1ae5c4437
5 changed files with 202 additions and 2 deletions
@@ -0,0 +1,79 @@
+# Task 021: Admin Workflow Template API
+
+Development description: Build the backend domain, persistence, and public API for Admin-managed workflow templates with editable ordered stages and stage parts.
+
+## Implementation Details
+
+- Backend contract:
+  - `POST /api/admin/workflows`
+  - `GET /api/admin/workflows`
+  - `GET /api/admin/workflows/{workflow_id}`
+  - `PATCH /api/admin/workflows/{workflow_id}`
+  - `POST /api/admin/workflows/{workflow_id}/stages`
+  - `PATCH /api/admin/workflows/{workflow_id}/stages/{stage_id}`
+  - `DELETE /api/admin/workflows/{workflow_id}/stages/{stage_id}`
+  - `POST /api/admin/workflows/{workflow_id}/stages/reorder`
+  - `POST /api/admin/workflows/{workflow_id}/activate`
+  - `POST /api/admin/workflows/{workflow_id}/archive`
+- Workflow template fields:
+  - Name.
+  - Slug.
+  - Description.
+  - Status: `DRAFT`, `ACTIVE`, `ARCHIVED`.
+  - Version number.
+  - Created/updated metadata.
+- Workflow stage fields:
+  - Stable key.
+  - Display name.
+  - Description.
+  - Position.
+  - Owner role.
+  - Runner profile key.
+  - Required inputs.
+  - Expected outputs.
+  - Acceptance criteria.
+  - Human approval requirement.
+  - Retry policy.
+- Workflow stage parts:
+  - Store as structured JSON under each stage for v1.
+  - Each part has key, type, title, prompt/config payload, and acceptance criteria.
+- Repository/schema:
+  - Add relational tables for workflow templates and stages.
+  - Preserve structured stage-part JSON without ad hoc string parsing.
+  - Add audit events for create/update/reorder/activate/archive.
+- Authorization:
+  - Admin can create and mutate workflow templates.
+  - Editor can read active workflow templates but cannot mutate them.
+
+## Public Interface
+
+- Admin can create a workflow template, add/edit/reorder stages, activate it, and archive it.
+- Editor can list/read active workflow templates for article creation context only.
+- Mutating endpoints consistently reject Editor requests.
+
+## Acceptance Criteria
+
+- [ ] TDD pre-requirement: before implementation, write one failing Admin API test for creating a workflow template with two editable stages and one failing Editor mutation denial test; proceed one behavior at a time and record evidence in `Result`.
+- [ ] Workflow templates are persisted with status, version, audit metadata, and ordered stages.
+- [ ] Stage parts are persisted as structured JSON and returned unchanged through the public API.
+- [ ] Admin can update stage owner role, runner profile, inputs, outputs, acceptance criteria, human approval flag, retry policy, and stage parts.
+- [ ] Admin can reorder stages and the returned workflow reflects the new order.
+- [ ] Activation creates an immutable version increment and archives no data.
+- [ ] Archive hides workflow from Editor list but keeps Admin history visible.
+- [ ] Editor mutation attempts return the same authorization error shape used by existing Admin APIs.
+- [ ] OpenAPI/shared contracts include workflow template request/response schemas.
+
+## Verification
+
+- Run backend workflow-template API integration tests.
+- Run backend authorization integration tests covering Admin/Editor access.
+- Run schema initialization against the test database.
+
+## Result
+
+- Status: Not started.
+- TDD plan:
+- Red evidence:
+- Green evidence:
+- Refactor notes:
+- Verification output: