PRD: Agent manager groups
| Module | Helpdesk (CORE-13) | PRD ID | PRD-AGT-001 |
| Status | In-progress | Owner | Helpdesk squad |
| Date | 2026-06-03 | Version | v0.1 |
| Packages | @nx/helpdesk · apps/bo · apps/core | URD | AGT |
TL;DR
Gives support managers a back-office surface to curate agent groups and routing rules: manage a user's group memberships straight from the agent screen, edit a group's members through a single unified flow, and configure prioritized assignment rules - all scoped per organizer so group names stay unambiguous. The result: agent grouping and auto-routing become self-serve in the back office instead of piecemeal, schema-only operations.
1. Context & Problem
The Helpdesk agent model already carries agents, agent groups, and prioritized assignment rules in the backend, but the back-office surface for managing them is incomplete. Group membership can only be edited piecemeal, group names are not uniquely scoped, and assignment rules have no management screen. Support managers cannot curate who belongs to which group or how new tickets route without falling back to ad-hoc, schema-level changes.
This increment builds the missing back-office UI on top of the existing agent-group and assignment-rule domain, and tightens the group schema so memberships and routing rules are managed directly and unambiguously.
Build status: the Helpdesk backend does not currently compile (see the module overview and URD). Until the build is repaired, no Helpdesk requirement is treated as verified-shipped; this PRD specifies intended behavior for the management surface.
2. Goals & Non-Goals
Goals
- Manage an agent's group memberships from the agent screen (add/remove via a dedicated "Manage groups" dialog and action).
- Edit a group's members from the group screen through a single unified
editMemberFormSchemaflow (replacing separate add-member / remove-member use cases and routes). - Enforce unique agent-group names scoped by
organizerId. - Carry
organizerIdthrough agent-group inputs and assignment logic (replacingmerchantId-based scoping for these flows). - Provide an assignment-rule management screen and API in the back office.
Non-Goals
- The auto-assignment worker logic and assignment strategies themselves - already present; see URD-AGT-006…007.
- Agent performance tracking and agent schedules (URD-AGT-008…009).
- Repairing the broken Helpdesk backend build.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Self-serve grouping | Group membership is managed entirely from the back office (no schema-level edits) |
| Name uniqueness | Zero duplicate agent-group names within an organizer |
| Routing coverage | Assignment rules per organizer are created and reordered through the management screen |
| Flow simplicity | Member edits go through one editMemberFormSchema call, not separate add/remove paths |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Support Manager | Curate agent groups, manage memberships, and configure prioritized assignment rules |
| Support Agent | Be placed in the right groups so the relevant tickets route to them |
Core scenarios: open an agent → manage their group memberships in a dialog → open a group → edit its members in one flow → create and reorder prioritized assignment rules so new tickets route to the right group.
5. User Stories
- As a support manager, I want to add or remove an agent's group memberships from the agent screen, so I can manage grouping where I already work.
- As a support manager, I want to edit a group's members in a single flow, so I don't juggle separate add and remove actions.
- As a support manager, I want agent-group names to be unique within my organizer, so groups are unambiguous across merchants.
- As a support manager, I want a screen to create and reorder assignment rules, so I can control how new tickets are routed.
- As a support agent, I want my group memberships to reflect my real skills/teams, so the right tickets reach me.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Manage an agent's group memberships from the agent screen (add/remove) via a "Manage groups" dialog and action | URD-AGT-004 |
| FR-2 | Edit a group's members through a single unified editMemberFormSchema flow, replacing separate add/remove member use cases and routes | URD-AGT-004 |
| FR-3 | Agent-group names are unique, scoped by organizerId | URD-AGT-004 |
| FR-4 | Agent-group inputs and assignment logic carry organizerId (replacing merchantId scoping for these flows) | URD-AGT-001 · URD-AGT-005 |
| FR-5 | Configure prioritized assignment rules per organizer through a management screen + API and a sidebar entry | URD-AGT-005 |
Full requirement text and acceptance criteria live in the Helpdesk URD. This PRD references them rather than restating them.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | Unique-name constraint is enforced at the schema level, scoped by organizerId; membership edits are consistent (no orphaned or duplicate memberships) |
| Tenancy & authz | Agent-group and assignment-rule operations are scoped per organizer; gated by helpdesk management permissions |
| Consistency | Member edits apply through one transactional flow; partial failures don't leave a group half-edited |
| i18n | User-facing labels/statuses are bilingual ({ en, vi }) |
| Build gate | No requirement is verified-shipped until the Helpdesk backend build is repaired |
8. UX & Flows
Key screens (in apps/bo): the agent screen's "Manage groups" dialog and action, the group member-editing flow, and the assignment-rule management screen reachable from the sidebar.
9. Data & Domain
| Entity | Role |
|---|---|
Agent | A merchant/organizer user who works tickets; carries group memberships |
AgentGroup | A named group of agents, unique per organizerId; members edited via the unified flow |
| Group membership | The agent ↔ group link managed from the agent and group screens |
| Assignment rule | A prioritized routing rule per organizer, configured in the management screen |
Conceptual only - full schema and invariants in the helpdesk domain model.
10. Dependencies & Assumptions
Depends on
- Agent ↔ user link (URD-AGT-001) - an agent exists within a merchant/organizer before it can be grouped.
- Assignment strategies & worker (URD-AGT-006…007) - the management screen configures rules the existing worker evaluates.
- User Management (
CORE-01) - agents are users linked to a merchant/organizer. apps/coreagent / agent-group schema and interface - for the membership and unique-name changes.
Assumptions
- The organizer has agents to group and at least one group to route to.
- The underlying agent-group and assignment-rule backend predates this increment and is available once the build is repaired.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Helpdesk backend build is broken | No requirement verified-shipped until repaired; UI/schema specified against intended behavior |
merchantId → organizerId scope change for these flows | Apply consistently across agent-group inputs and assignment logic; verify no cross-merchant leakage |
| Unique-name constraint may collide on legacy duplicate group names | De-duplicate existing group names per organizer before enforcing the constraint |
| Unified member-edit flow replaces add/remove routes | Remove the superseded use cases/routes to avoid a parallel patchwork surface |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 - AGT is P1, In-progress (see the Helpdesk feature catalog) |
| Rollout | All organizers; back-office surface, no feature flag |
| Migration | De-duplicate any existing per-organizer group names before enforcing the unique constraint |
| Launch criteria | Manage-groups dialog, unified member edit, unique-name constraint, and assignment-rule screen verified end-to-end - gated on the Helpdesk build being repaired |
| Monitoring | Group membership changes, assignment-rule edits, and duplicate-name rejection rate |
13. FAQ
Where do I manage an agent's groups? From the agent screen - a "Manage groups" dialog and action let you add or remove memberships in place.
Why one editMemberFormSchema flow instead of separate add/remove? A single unified flow is simpler and replaces the old separate add-member / remove-member use cases and routes.
Why are group names scoped by organizerId and not merchantId? Group names must be unambiguous across an organizer's merchants, so uniqueness and assignment scoping move to organizerId for these flows.
Does this change auto-assignment behavior? No - the auto-assignment worker and strategies already exist; this increment only adds the screen to configure prioritized rules.
Is this live? No - the Helpdesk backend build is broken, so nothing here is verified-shipped until that is repaired.
References
- URD: Helpdesk - Agent Management (
AGT) - requirements (URD-AGT-001, URD-AGT-004, URD-AGT-005) - Module: Helpdesk - overview + traceability
- Developer: @nx/helpdesk · domain model