social-media/docs/TASKS/approval-workflow/005-multi-level-approval-step-configuration-backend.md

Task: Multi-level approval step configuration backend

Feature

docs/FEATURES/approval-workflow.md

Goal

Persist workspace-level multi-level approval step configuration and expose it through workspace settings APIs.

Context

The workspace can currently select Multi-level, but there is no backend model or API surface for defining the ordered steps that make multi-level approval usable.

Scope

• Add a workspace-owned approval step configuration data model.
• Each configured step must include:
  • display name
  • sort order
  • target type: Role, Membership, or Member
  • target value
  • required approver count
• Add EF Core configuration and migration.
• Return configured approval steps from workspace APIs.
• Allow workspace managers/admins to replace the configured step list for a workspace.
• Validate:
  • Multi-level workspaces must have at least one step.
  • step names are required and bounded.
  • target type is one of Role, Membership, or Member.
  • role targets use known workspace roles.
  • membership targets use known membership categories.
  • member targets reference a user with workspace access.
  • required approver count is at least 1.
  • sort order is stable and unique per workspace.

Constraints

• Do not implement active approval workflow instance recalculation in this task.
• Do not implement approval step execution or per-step approval decisions in this task.
• Do not implement reminders, comments, reopening, or magic links in this task.
• Keep backend feature code under backend/src/Socialize.Api/Modules/Approvals or Modules/Workspaces according to existing ownership patterns.
• If backend contracts change, update OpenAPI when the backend is running.

Likely Files

• backend/src/Socialize.Api/Modules/Approvals/Data/*
• backend/src/Socialize.Api/Modules/Approvals/Handlers/*
• backend/src/Socialize.Api/Modules/Workspaces/Handlers/*
• backend/src/Socialize.Api/Data/AppDbContext.cs
• backend/src/Socialize.Api/Migrations/*
• backend/tests/Socialize.Tests/Approvals/*
• shared/openapi/openapi.json
• frontend/src/api/schema.d.ts

Done When

• Multi-level step configuration is persisted per workspace.
• Workspace responses include configured approval steps.
• Managers/admins can save an ordered list of approval steps.
• Invalid target types, target values, counts, and empty multi-level configurations are rejected.
• Backend tests cover validation and persistence rules.
• OpenAPI and generated frontend schema are updated.

Validation Commands

dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
./scripts/update-openapi.sh