80 lines
5.0 KiB
Markdown
80 lines
5.0 KiB
Markdown
# 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
|
|
|
|
- [x] 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`.
|
|
- [x] Workflow templates are persisted with status, version, audit metadata, and ordered stages.
|
|
- [x] Stage parts are persisted as structured JSON and returned unchanged through the public API.
|
|
- [x] Admin can update stage owner role, runner profile, inputs, outputs, acceptance criteria, human approval flag, retry policy, and stage parts.
|
|
- [x] Admin can reorder stages and the returned workflow reflects the new order.
|
|
- [x] Activation creates an immutable version increment and archives no data.
|
|
- [x] Archive hides workflow from Editor list but keeps Admin history visible.
|
|
- [x] Editor mutation attempts return the same authorization error shape used by existing Admin APIs.
|
|
- [x] 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.
|