content-factory/tasks/021-admin-workflow-template-api.md

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: Implemented.
• TDD plan: Use the existing pre-requirement API tests in apps/backend/tests/integration/test_admin_workflow_templates_public_api.py, then cover the remaining acceptance criteria with a focused API flow for reorder, activate/archive, editor visibility, admin history, and audit persistence.
• Red evidence: Pre-implementation PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps.backend.tests.integration.test_admin_workflow_templates_public_api failed with two public API assertions: expected 201/403, actual 404 {"detail":"Not Found"} for missing /api/admin/workflows.
• Green evidence: PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps.backend.tests.integration.test_admin_workflow_templates_public_api -> Ran 3 tests ... OK.
• Refactor notes: Added workflow template status/contracts, admin/editor router, application service, SQLite/Postgres tables, repositories, ordered stage persistence, structured stage-part JSON, activation/archive, and audit events. Active workflow templates are readable by editors; draft/archived templates remain admin history only. Draft-only mutation preserves activated version immutability.
• Verification output: PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps.backend.tests.contracts.test_public_openapi_contract -> Ran 1 test ... OK; PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps.backend.tests.integration.test_schema_storage_contracts -> Ran 3 tests ... OK; PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m py_compile ... for changed backend modules -> OK. Existing broader auth suite was also attempted and still fails in test_editor_can_create_articles_and_approve_plan_review with 404 {"detail":"Not Found"} while approving nonexistent plan id 00000000-0000-0000-0000-000000000123; left unchanged.