PM-6451 TM/PM role update

[vas3a]

This pull request refines timesheet and engagement manager authorization, introducing a distinct Talent Manager (TM) platform role with read-only timesheet access and the ability to assign or remove engagement managers. It ensures Project Managers no longer have elevated timesheet privileges, clarifies role-based behaviors, and updates error messages and tests to reflect these changes.

Authorization and Role Handling

• Introduced a dedicated Talent Manager (TM) platform role with read-only timesheet access (TimesheetViewerRole.Tm), and updated logic so TMs can assign and remove engagement managers, while Project Managers can no longer do so (canManageEngagementManagers, isTimesheetTm, and related logic in timesheet-access.service.ts). [1] [2] [3]
• Updated the role resolution order: Administrators and machine tokens with manage scope are ADMINISTRATOR, engagement managers are MANAGER, TMs are TM (read-only), and Project Managers are treated as unrelated (404). [1] [2] [3]

API and Error Message Updates

• Modified API documentation and error messages to reflect that both Administrators and TMs can manage engagement managers, and clarified forbidden response descriptions. [1] [2] [3] [4]

Testing Enhancements

• Expanded and updated unit and e2e tests to verify new TM behaviors: TMs can assign/remove engagement managers, have read-only timesheet access, and Project Managers are denied elevated privileges. [1] [2] [3] [4] [5] [6] [7] [8] [9]

DTO and API Response Adjustments

• Updated DTOs so viewerRole can be TM or undefined, and changed example values to reflect the new TM role. [1] [2]

Bugfixes and Minor Improvements

• Fixed query parameter formatting in MemberService for fetching user details.

[Copilot]

Copilot review overview

🟡 Changes recommended

The engagement list response role regresses for managers and TM date-range filtering can drop the submitted-only constraint, risking incorrect authorization behavior.

Review effort: Lite
Findings: 3 · 1

Open (4)

• viewerRole should be required in the API response · New
• Manager callers lose viewerRole in engagement results · New
• TM date filter overwrites submitted-status constraint · New
• TM error message uses unclear acronym · New

What changed in this PR

This PR refines role-based authorization in the timesheets and engagement-manager flows by introducing a distinct Talent Manager (TM) role with read-only timesheet access and the ability to assign/remove engagement managers, while ensuring Project Managers no longer receive elevated timesheet privileges.

Changes:

• Add TM as a dedicated timesheet viewer role and enforce TM read-only behavior across timesheet actions.
• Adjust role resolution/authorization so PMs are treated as unrelated (404) and TMs can manage engagement managers.
• Update unit/e2e tests, DTOs, and API docs/error messages to reflect the new role behavior.

File	Description
src/​timesheets/​timesheets.service.ts	Enforces TM read-only behavior; adjusts engagement list access and filtering logic.
src/​timesheets/​timesheets.service.spec.ts	Updates unit tests for TM read-only behavior and PM denial.
src/​timesheets/​timesheet-roles.ts	Adds the TM viewer role constant.
src/​timesheets/​timesheet-engagements.controller.ts	Updates endpoint documentation to include TM engagement list semantics.
src/​timesheets/​timesheet-authorization.e2e.spec.ts	Expands e2e coverage for TM access and PM being unrelated.
src/​timesheets/​timesheet-access.service.ts	Adds TM detection, separates “timesheet admin” vs TM, and adds canManageEngagementManagers.
src/​timesheets/​timesheet-access.service.spec.ts	Updates role-resolution unit tests for TM/PM behavior.
src/​timesheets/​dto/​timesheet-engagement-list.dto.ts	Adjusts DTO typing/examples for viewer role changes.
src/​integrations/​member.service.ts	Fixes query parameter formatting for member lookups by user IDs.
src/​engagements/​managers/​engagement-managers.service.ts	Switches authorization from “admin only” to “admin or TM”.
src/​engagements/​managers/​engagement-managers.service.spec.ts	Adds test coverage for TM allowed and PM refused manager changes.
src/​engagements/​managers/​engagement-managers.controller.ts	Updates docs/guards usage to align with TM ability to manage managers.
src/​common/​constants.ts	Adds TM read-only error message.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.