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
@@ -8,6 +8,10 @@ The system accepts a short article description, asks boundary-setting questions,

 v1 is an internal or single-tenant editorial tool. It is not a customer-facing multi-tenant SaaS product.

+### Main principle
+
+The workflow is a first-class Admin-managed product object, not a hard-coded backend status chain. The pipeline is gate-driven: each workflow stage defines its purpose, ordered parts, owner role, runner profile, required inputs, outputs, and acceptance criteria. Runtime execution cannot move to the next stage until the current stage is complete and every required human approval or validation gate has passed.
+
 Chosen architecture:

 ```text
@@ -50,6 +54,7 @@ Claude Code can be supported as an optional internal runner, but not as the main
 14. Multi-site configuration
 15. Job history and audit trail
 16. Codex CLI-based agent execution
+17. Admin-managed workflow templates and editable workflow stages
 ```

 ## Out of scope for v1
@@ -76,13 +81,13 @@ The publishing step in v1 should create a **direct commit to the configured prod

 ## Admin

-Can configure target websites, pipeline parameters, agent runner profiles, prompt versions, publishing YAML, and site-specific transformation/upload scripts.
+Can configure target websites, workflow templates, workflow stages, pipeline parameters, agent runner profiles, prompt versions, publishing YAML, and site-specific transformation/upload scripts.

 ## Editor

 Can create briefs, answer boundary questions, run the pipeline, edit intermediate results, approve plans, edit drafts, approve final content, and create publish commits.

-Only Admins can edit upload scripts and pipeline configuration. Admins are fully trusted code operators because admin-defined transformation scripts run directly on the runner host inside checked-out site repositories.
+Only Admins can edit workflow configuration, upload scripts, and pipeline configuration. Admins are fully trusted code operators because admin-defined transformation scripts run directly on the runner host inside checked-out site repositories.

 ---

@@ -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:
@@ -0,0 +1,64 @@
+# Task 022: Admin Workflow Builder UI
+
+Development description: Build the Admin dashboard workflow builder so Admins can create workflows and edit their ordered stages and stage parts from the frontend using the existing FSD structure.
+
+## Implementation Details
+
+- Frontend FSD boundaries:
+  - `pages/admin-workflows` owns the route-level page.
+  - `features/admin-workflows` owns workflow list/create/edit interactions.
+  - `entities/workflow-template` owns workflow template types, selectors, and formatters if shared across pages.
+  - `shared/pipeline-api` owns HTTP client methods only.
+- Admin navigation:
+  - Add Workflows item to Admin navigation.
+  - Keep Editor navigation unchanged.
+- Workflow list:
+  - Show name, status, version, updated timestamp, stage count, and active/archive actions.
+  - Allow creating a new draft workflow.
+- Workflow editor:
+  - Edit workflow metadata.
+  - Add/edit/delete stages.
+  - Reorder stages.
+  - Edit stage parts as structured rows/cards with type, title, config payload, and acceptance criteria.
+  - Edit human approval flag, owner role, runner profile key, retry policy, required inputs, and expected outputs.
+- UX constraints:
+  - Use dense Admin dashboard layout consistent with existing Admin screens.
+  - Avoid marketing/landing-page treatment.
+  - Show API errors inline near the relevant form/action.
+  - Disable destructive actions while requests are pending.
+- Tests:
+  - Add frontend model tests for workflow builder state transitions.
+  - Add API client tests/mocks if the current test pattern supports them.
+
+## Public Interface
+
+- Admin can open `/admin/workflows`, create a draft workflow, edit stages/parts, reorder stages, activate, and archive.
+- Editor does not see the Workflows nav item.
+
+## Acceptance Criteria
+
+- [ ] TDD pre-requirement: before implementation, write one failing frontend model test for creating a workflow draft and adding/reordering stages; proceed one behavior at a time and record evidence in `Result`.
+- [ ] Admin navigation exposes Workflows and routes to the builder page.
+- [ ] Editor navigation does not expose Workflows.
+- [ ] Workflow list loads from the backend API and shows empty/error/loading states.
+- [ ] Workflow editor can create workflow drafts and persist metadata.
+- [ ] Workflow editor can add, edit, delete, and reorder stages.
+- [ ] Workflow editor can edit structured stage parts without converting them to opaque strings.
+- [ ] Activation/archive actions update UI state after successful API responses.
+- [ ] Frontend code follows the existing FSD folder boundaries.
+
+## Verification
+
+- Run frontend workflow builder model tests.
+- Run frontend Admin navigation tests.
+- Run frontend typecheck.
+- Manually verify Admin workflow create/edit/reorder/activate/archive in Docker Compose.
+
+## Result
+
+- Status: Not started.
+- TDD plan:
+- Red evidence:
+- Green evidence:
+- Refactor notes:
+- Verification output:
@@ -0,0 +1,51 @@
+# Task 023: Workflow Template Binding And Demo Readiness
+
+Development description: Bind Admin-managed workflow templates into the demo product flow so article/site configuration references an active workflow template and the final demo checklist proves workflow management is not an isolated Admin CRUD surface.
+
+## Implementation Details
+
+- Backend binding:
+  - Add active workflow template reference to target site configuration or article creation input, following the existing product model.
+  - Validate that article creation cannot reference archived or missing workflow templates.
+  - Preserve existing article workflow status behavior while exposing the configured workflow template snapshot in article detail.
+  - Store the workflow template version/snapshot used by each article so later template edits do not rewrite historical article context.
+- Frontend binding:
+  - Article creation/site configuration shows the selected active workflow template.
+  - Article detail shows the configured workflow template and stage summary in the workflow/history area.
+- Demo readiness:
+  - Update demo seed data with at least one active workflow template.
+  - Update demo checklist/protocol to include Admin workflow creation/editing and article creation using the active workflow.
+  - Keep the existing end-to-end publishing path working.
+
+## Public Interface
+
+- Admin can configure which active workflow template is used by a site or article.
+- Editor can see which workflow template governs an article.
+- Demo reviewers can prove the Admin workflow builder affects the article flow.
+
+## Acceptance Criteria
+
+- [ ] TDD pre-requirement: before implementation, write one failing public API test showing article creation stores the active workflow template snapshot; proceed one behavior at a time and record evidence in `Result`.
+- [ ] Seed data includes an active workflow template with stages matching the demo pipeline.
+- [ ] Article creation records the workflow template id, version, and stage summary snapshot.
+- [ ] Article creation rejects archived/missing workflow template references.
+- [ ] Article detail exposes workflow template summary to the frontend.
+- [ ] Site configuration or article creation UI allows selecting an active workflow template.
+- [ ] Existing end-to-end demo publishing smoke still passes.
+- [ ] Final demo readiness protocol includes manual steps for Admin workflow create/edit/reorder/activate and Editor article flow using that workflow.
+
+## Verification
+
+- Run backend article creation workflow-template binding tests.
+- Run existing end-to-end demo stack smoke test.
+- Run frontend model tests for the selected workflow template display.
+- Run final manual demo checklist and record the protocol.
+
+## Result
+
+- Status: Not started.
+- TDD plan:
+- Red evidence:
+- Green evidence:
+- Refactor notes:
+- Verification output:
@@ -23,6 +23,7 @@ This task pool turns `IDEA.md` into vertical, testable implementation slices tha
 - Backend is FastAPI.
 - Frontend is Next.js.
 - Workflow orchestration uses LangGraph, while article/domain tables remain authoritative for product state.
+- Workflow templates, stages, and stage parts are Admin-managed product configuration, not hard-coded UI-only metadata.
 - Queue is Redis-backed Celery, Dramatiq, or RQ.
 - Postgres stores domain state and manifests, not large source snapshots.
 - Object storage stores research source-section artifacts, assets, and job artifacts.