PRD: Nhóm quản lý agent

Module	Hỗ trợ khách hàng (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

Cung cấp cho quản lý hỗ trợ một bề mặt back office để quản lý agent group và rule định tuyến: quản lý membership group của một user ngay từ màn hình agent, chỉnh sửa thành viên của một group qua một luồng hợp nhất, và cấu hình các assignment rule theo thứ tự ưu tiên - tất cả đều được scope theo organizer để tên group luôn rõ ràng. Kết quả: việc gom nhóm agent và tự động định tuyến trở nên tự phục vụ trong back office thay vì làm rời rạc, chỉ ở mức schema.

1. Context & Problem

Mô hình agent của Helpdesk đã có sẵn agent, agent group và các assignment rule theo thứ tự ưu tiên ở backend, nhưng bề mặt back office để quản lý chúng còn chưa hoàn chỉnh. Membership group chỉ có thể chỉnh sửa rời rạc, tên group chưa được scope duy nhất, và assignment rule chưa có màn hình quản lý. Quản lý hỗ trợ không thể quản lý ai thuộc group nào hay cách ticket mới được định tuyến mà không phải quay về các thay đổi ad-hoc ở mức schema.

Gói này xây dựng phần UI back office còn thiếu dựa trên domain agent-group và assignment-rule sẵn có, và siết lại schema của group để membership và rule định tuyến được quản lý trực tiếp và rõ ràng.

Trạng thái build: backend của Helpdesk hiện không build được (xem tổng quan module và URD). Cho tới khi build được sửa, không yêu cầu Helpdesk nào được coi là đã verified-shipped; PRD này đặc tả hành vi dự kiến cho bề mặt quản lý.

2. Goals & Non-Goals

Goals

• Quản lý membership group của một agent từ màn hình agent (thêm/xóa qua dialog và action "Manage groups" riêng).
• Chỉnh sửa thành viên của một group từ màn hình group qua một luồng editMemberFormSchema hợp nhất (thay cho các use case và route thêm/xóa thành viên riêng lẻ).
• Bắt buộc tên agent-group là duy nhất, scope theo organizerId.
• Mang organizerId xuyên suốt input agent-group và logic assignment (thay cho scoping dựa trên merchantId ở các luồng này).
• Cung cấp một màn hình quản lý assignment rule và API trong back office.

Non-Goals

• Bản thân logic worker tự động phân công và các strategy assignment - đã có sẵn; xem URD-AGT-006…007.
• Theo dõi hiệu suất agent và lịch làm việc của agent (URD-AGT-008…009).
• Sửa lỗi build backend Helpdesk.

3. Success Metrics

Metric	Target / signal
Tự phục vụ gom nhóm	Membership group được quản lý hoàn toàn từ back office (không chỉnh sửa ở mức schema)
Tên duy nhất	Không có tên agent-group trùng lặp trong cùng một organizer
Phủ định tuyến	Assignment rule theo organizer được tạo và sắp xếp lại qua màn hình quản lý
Đơn giản hóa luồng	Chỉnh sửa thành viên đi qua một lệnh editMemberFormSchema, không qua các đường thêm/xóa riêng

4. Personas & Use Cases

Persona	Mục tiêu trong tính năng này
Quản lý hỗ trợ	Quản lý agent group, membership và cấu hình các assignment rule theo thứ tự ưu tiên
Agent hỗ trợ	Được đặt vào đúng group để các ticket liên quan định tuyến tới mình

Core scenarios: mở một agent → quản lý membership group trong dialog → mở một group → chỉnh sửa thành viên trong một luồng → tạo và sắp xếp lại các assignment rule theo thứ tự ưu tiên để ticket mới định tuyến tới đúng group.

5. User Stories

• Là quản lý hỗ trợ, tôi muốn thêm hoặc xóa membership group của một agent từ màn hình agent, để tôi quản lý việc gom nhóm ngay nơi mình đang làm việc.
• Là quản lý hỗ trợ, tôi muốn chỉnh sửa thành viên của một group trong một luồng duy nhất, để không phải xoay xở giữa các action thêm và xóa riêng biệt.
• Là quản lý hỗ trợ, tôi muốn tên agent-group là duy nhất trong organizer của mình, để các group không bị nhập nhằng giữa các merchant.
• Là quản lý hỗ trợ, tôi muốn một màn hình để tạo và sắp xếp lại các assignment rule, để tôi kiểm soát cách ticket mới được định tuyến.
• Là agent hỗ trợ, tôi muốn membership group của mình phản ánh đúng kỹ năng/đội nhóm thực tế, để đúng ticket đến tay tôi.

6. Functional Requirements

#	Requirement	URD ref
FR-1	Quản lý membership group của một agent từ màn hình agent (thêm/xóa) qua dialog và action "Manage groups"	URD-AGT-004
FR-2	Chỉnh sửa thành viên của một group qua một luồng editMemberFormSchema hợp nhất, thay cho các use case và route thêm/xóa thành viên riêng lẻ	URD-AGT-004
FR-3	Tên agent-group là duy nhất, scope theo organizerId	URD-AGT-004
FR-4	Input agent-group và logic assignment mang organizerId (thay cho scoping merchantId ở các luồng này)	URD-AGT-001 · URD-AGT-005
FR-5	Cấu hình các assignment rule theo thứ tự ưu tiên cho mỗi organizer qua màn hình quản lý + API và một mục sidebar	URD-AGT-005

Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Helpdesk. PRD này tham chiếu chúng thay vì lặp lại.

7. Non-Functional Requirements

Area	Requirement
Data integrity	Ràng buộc tên duy nhất được áp ở mức schema, scope theo organizerId; chỉnh sửa membership nhất quán (không membership mồ côi hay trùng lặp)
Tenancy & authz	Thao tác agent-group và assignment-rule được scope theo organizer; được kiểm soát bởi permission quản lý helpdesk
Consistency	Chỉnh sửa thành viên áp dụng qua một luồng transactional; lỗi cục bộ không để lại group bị sửa dở dang
i18n	Nhãn/trạng thái hiển thị cho người dùng là song ngữ ({ en, vi })
Build gate	Không yêu cầu nào được verified-shipped cho tới khi build backend Helpdesk được sửa

8. UX & Flows

Các màn hình chính (trong apps/bo): dialog và action "Manage groups" trên màn hình agent, luồng chỉnh sửa thành viên group, và màn hình quản lý assignment rule truy cập từ sidebar.

9. Data & Domain

Entity	Vai trò
Agent	Một user merchant/organizer xử lý ticket; mang các membership group
AgentGroup	Một group agent có tên, duy nhất theo organizerId; thành viên được chỉnh sửa qua luồng hợp nhất
Membership group	Liên kết agent ↔ group được quản lý từ màn hình agent và group
Assignment rule	Một rule định tuyến theo thứ tự ưu tiên cho mỗi organizer, cấu hình trong màn hình quản lý

Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong domain model helpdesk.

10. Dependencies & Assumptions

Depends on

• Liên kết agent ↔ user (URD-AGT-001) - một agent tồn tại trong merchant/organizer trước khi có thể gom nhóm.
• Assignment strategy & worker (URD-AGT-006…007) - màn hình quản lý cấu hình các rule mà worker sẵn có sẽ đánh giá.
• Quản lý người dùng (CORE-01) - agent là user được liên kết với một merchant/organizer.
• Schema và interface agent / agent-group trong apps/core - cho các thay đổi về membership và tên duy nhất.

Assumptions

• Organizer có sẵn agent để gom nhóm và ít nhất một group để định tuyến tới.
• Backend agent-group và assignment-rule có trước gói này và sẵn dùng khi build được sửa.

11. Risks & Open Questions

Risk / question	Mitigation / status
Build backend Helpdesk đang lỗi	Không yêu cầu nào verified-shipped cho tới khi sửa; UI/schema được đặc tả theo hành vi dự kiến
Đổi scope merchantId → organizerId cho các luồng này	Áp dụng nhất quán trên input agent-group và logic assignment; kiểm tra không rò rỉ chéo merchant
Ràng buộc tên duy nhất có thể đụng độ với tên group trùng lặp cũ	Khử trùng lặp tên group hiện có theo organizer trước khi áp ràng buộc
Luồng chỉnh sửa thành viên hợp nhất thay cho route thêm/xóa	Gỡ các use case/route bị thay thế để tránh bề mặt chắp vá song song

12. Release Plan & Launch Criteria

Aspect	Plan
Phase	P1 - AGT là P1, In-progress (xem danh mục tính năng Helpdesk)
Rollout	Tất cả organizer; bề mặt back office, không feature flag
Migration	Khử trùng lặp mọi tên group hiện có theo organizer trước khi áp ràng buộc tên duy nhất
Launch criteria	Dialog manage-groups, chỉnh sửa thành viên hợp nhất, ràng buộc tên duy nhất, và màn hình assignment-rule được kiểm chứng toàn trình - phụ thuộc vào việc build Helpdesk được sửa
Monitoring	Thay đổi membership group, chỉnh sửa assignment rule, và tỷ lệ từ chối tên trùng lặp

13. FAQ

Tôi quản lý group của một agent ở đâu? Từ màn hình agent - một dialog và action "Manage groups" cho phép thêm hoặc xóa membership tại chỗ.

Vì sao một luồng editMemberFormSchema thay vì thêm/xóa riêng? Một luồng hợp nhất duy nhất đơn giản hơn và thay cho các use case và route thêm/xóa thành viên cũ.

Vì sao tên group scope theo organizerId chứ không phải merchantId? Tên group phải rõ ràng giữa các merchant của một organizer, nên tính duy nhất và scoping assignment chuyển sang organizerId cho các luồng này.

Điều này có đổi hành vi tự động phân công không? Không - worker tự động phân công và các strategy đã có sẵn; gói này chỉ thêm màn hình để cấu hình các rule theo thứ tự ưu tiên.

Đã chạy thật chưa? Chưa - build backend Helpdesk đang lỗi, nên chưa có gì ở đây được verified-shipped cho tới khi sửa xong.

References

• URD: Helpdesk - Agent Management (AGT) - yêu cầu (URD-AGT-001, URD-AGT-004, URD-AGT-005)
• Module: Hỗ trợ khách hàng - tổng quan + traceability
• Developer: @nx/helpdesk · domain model