Description

Implement a secure admin endpoint that allows our internal team to create a Research Group, find the existing user (professor) by identifier, and assign:
1. The user to the research group, and
2. The Professor role to the user within that research group.
The endpoint should be accessible via Bruno.

Tasks

Endpoint (suggested):

• POST /api/admin/research-groups/provision

AuthZ / Security:

• Restricted to server-side admin/service accounts (e.g., ADMIN).
• Enforce via @PreAuthorize / route guard.
• Audit log each call (who, when, what).

Example Request Payload
{ "researchGroup": { "name": "Applied Engineering & Technology", "headName": "Prof. Jane Doe" }, "universityId": "ab123cde", }

Behavior:

1. Validate payload (non-empty name, headName, valid email, role ∈ {PROFESSOR} for now).
2. Create research_groups row if a group with the same name (case-insensitive) or other props does not yet exist.
3. Find users by university id (exact match). If not found → 404 with actionable message.
4. Change entry in user_research_group_roles for (user_id, research_group_id) to role PROFESSOR or create one.
5. All steps must run in a single DB transaction; rollback on any failure.
6. Return the created/linked entities.

Status codes:

• 201 Created if group newly created; 200 OK if group already existed or idempotent replay.
• 400 Bad Request invalid payload (e.g., empty name, invalid email).
• 401/403 unauthorized/forbidden.
• 404 Not Found user not found.
• 409 Conflict name clashes beyond defined uniqueness rules (e.g., duplicate non-canonicalized names if constraint fails).
• 500 on unexpected server errors.

Validation Rules

• researchGroup.name: 3–150 chars, trim, collapse whitespace; unique case-insensitive.
• researchGroup.headName: 3–150 chars; may include titles like “Prof.” (do not try to parse/normalize the title).
• userSelector.email: RFC-5322 compliant (basic).
• role: must be PROFESSOR.

Acceptance Criteria

• POST /api/admin/research-groups/provision exists and is restricted to admin/service users.
• Endpoint creates the research group if not present; reuses it if present.
• Endpoint finds user by (email) tumId; fails with 404 if not found.
• Endpoint assigns role PROFESSOR in user_research_group_roles (upsert).
• Whole operation is transactional.
• Proper HTTP status codes and structured error responses.
• Audit logging present.
• New APIs are visible in Bruno
• Added documentation for the endpoint