500 lines
23 KiB
Markdown
500 lines
23 KiB
Markdown
# Round: Mentoring (Finalist Collaboration Layer)
|
||
|
||
## 1. Purpose & Position in Flow
|
||
|
||
The MENTORING round is **not a judging stage** — it is a collaboration layer that activates between Jury 2 finalist selection and the Live Finals. It provides finalist teams who requested mentoring with a private workspace to refine their submissions with guidance from an assigned mentor.
|
||
|
||
| Aspect | Detail |
|
||
|--------|--------|
|
||
| Position | Round 6 (after Jury 2, before Live Finals) |
|
||
| Participants | Finalist teams + assigned mentors |
|
||
| Duration | Configurable (typically 2-4 weeks) |
|
||
| Output | Better-prepared finalist submissions; some mentoring files promoted to official submissions |
|
||
|
||
### Who Gets Mentoring
|
||
|
||
- Only projects that have `Project.wantsMentorship = true` AND have advanced to finalist status (ProjectRoundState PASSED in the Jury 2 round)
|
||
- Admin can override: assign mentoring to projects that didn't request it, or skip projects that did
|
||
|
||
---
|
||
|
||
## 2. Data Model
|
||
|
||
### Round Record
|
||
|
||
```
|
||
Round {
|
||
id: "round-mentoring"
|
||
competitionId: "comp-2026"
|
||
name: "Finalist Mentoring"
|
||
roundType: MENTORING
|
||
status: ROUND_DRAFT → ROUND_ACTIVE → ROUND_CLOSED
|
||
sortOrder: 5
|
||
windowOpenAt: "2026-06-01" // Mentoring period start
|
||
windowCloseAt: "2026-06-30" // Mentoring period end
|
||
juryGroupId: null // No jury for mentoring
|
||
submissionWindowId: null // Mentoring doesn't collect formal submissions
|
||
configJson: { ...MentoringConfig }
|
||
}
|
||
```
|
||
|
||
### MentoringConfig
|
||
|
||
```typescript
|
||
type MentoringConfig = {
|
||
// Who gets mentoring
|
||
eligibility: "all_advancing" | "requested_only"
|
||
// all_advancing: Every finalist gets a mentor
|
||
// requested_only: Only projects with wantsMentorship=true
|
||
|
||
// Workspace features
|
||
chatEnabled: boolean // Bidirectional messaging (default: true)
|
||
fileUploadEnabled: boolean // Mentor + team can upload files (default: true)
|
||
fileCommentsEnabled: boolean // Threaded comments on files (default: true)
|
||
filePromotionEnabled: boolean // Promote workspace file to official submission (default: true)
|
||
|
||
// Promotion target
|
||
promotionTargetWindowId: string | null
|
||
// Which SubmissionWindow promoted files go to
|
||
// Usually the most recent window (Round 2 docs)
|
||
// If null, promotion creates files without a window (admin must assign)
|
||
|
||
// Auto-assignment
|
||
autoAssignMentors: boolean // Use AI/algorithm to assign (default: false)
|
||
maxProjectsPerMentor: number // Mentor workload cap (default: 3)
|
||
|
||
// Notifications
|
||
notifyTeamsOnOpen: boolean // Email teams when mentoring opens (default: true)
|
||
notifyMentorsOnAssign: boolean // Email mentors when assigned (default: true)
|
||
reminderBeforeClose: number[] // Days before close to remind (default: [7, 3, 1])
|
||
}
|
||
```
|
||
|
||
### Related Models
|
||
|
||
| Model | Purpose |
|
||
|-------|---------|
|
||
| `MentorAssignment` | Links mentor to project (existing, enhanced) |
|
||
| `MentorMessage` | Chat messages between mentor and team (existing) |
|
||
| `MentorNote` | Mentor's private notes (existing) |
|
||
| `MentorFile` | **NEW** — Files uploaded in workspace |
|
||
| `MentorFileComment` | **NEW** — Threaded comments on files |
|
||
| `ProjectFile` | Target for file promotion |
|
||
| `SubmissionFileRequirement` | Requirement slot that promoted file fills |
|
||
|
||
---
|
||
|
||
## 3. Mentor Assignment
|
||
|
||
### 3.1 Assignment Methods
|
||
|
||
| Method | Description |
|
||
|--------|-------------|
|
||
| `MANUAL` | Admin picks mentor for each project |
|
||
| `AI_SUGGESTED` | AI recommends matches, admin approves |
|
||
| `AI_AUTO` | AI auto-assigns, admin can override |
|
||
| `ALGORITHM` | Round-robin or expertise-matching algorithm |
|
||
|
||
### 3.2 Assignment Criteria
|
||
|
||
The existing `mentor-matching.ts` service evaluates:
|
||
- **Expertise overlap** — mentor's tags vs project's tags/category
|
||
- **Country/region diversity** — avoid same-country bias
|
||
- **Workload balance** — distribute evenly across mentors
|
||
- **Language** — match if language preferences exist
|
||
|
||
### 3.3 Assignment Flow
|
||
|
||
```
|
||
1. MENTORING round opens (status → ROUND_ACTIVE)
|
||
2. System identifies eligible projects:
|
||
- All finalists (if eligibility = "all_advancing")
|
||
- Only finalists with wantsMentorship (if "requested_only")
|
||
3. For each eligible project without a mentor:
|
||
a. If autoAssignMentors: Run AI/algorithm assignment
|
||
b. Else: Flag as "needs mentor" in admin dashboard
|
||
4. Admin reviews assignments, can:
|
||
- Accept suggestions
|
||
- Reassign mentors
|
||
- Skip projects (no mentoring needed)
|
||
5. Assigned mentors receive email notification
|
||
6. Workspace becomes active for mentor+team
|
||
```
|
||
|
||
### 3.4 Workspace Activation
|
||
|
||
When a mentor is assigned and the MENTORING round is ROUND_ACTIVE:
|
||
|
||
```typescript
|
||
// MentorAssignment is updated:
|
||
{
|
||
workspaceEnabled: true,
|
||
workspaceOpenAt: round.windowOpenAt,
|
||
workspaceCloseAt: round.windowCloseAt,
|
||
}
|
||
```
|
||
|
||
The workspace is accessible from:
|
||
- **Mentor dashboard** → "My Projects" → select project → Workspace tab
|
||
- **Applicant dashboard** → "Mentor" section → Workspace tab
|
||
- **Admin** → can view any workspace at any time
|
||
|
||
---
|
||
|
||
## 4. Workspace Features
|
||
|
||
### 4.1 Messaging (Chat)
|
||
|
||
Bidirectional chat between mentor and team members:
|
||
|
||
```
|
||
┌────────────────────────────────────────────────┐
|
||
│ Mentor Workspace — OceanClean AI │
|
||
│ ──────────────────────────────────────────── │
|
||
│ [💬 Chat] [📁 Files] [📋 Milestones] │
|
||
│ │
|
||
│ ┌────────────────────────────────────────┐ │
|
||
│ │ Dr. Martin (Mentor) Apr 5, 10:30│ │
|
||
│ │ Welcome! I've reviewed your business │ │
|
||
│ │ plan. Let's work on the financial │ │
|
||
│ │ projections section. │ │
|
||
│ │ │ │
|
||
│ │ Sarah (Team Lead) Apr 5, 14:15│ │
|
||
│ │ Thank you! We've uploaded a revised │ │
|
||
│ │ version. See the Files tab. │ │
|
||
│ │ │ │
|
||
│ │ Dr. Martin (Mentor) Apr 6, 09:00│ │
|
||
│ │ Great improvement! I've left comments │ │
|
||
│ │ on the file. One more round should do. │ │
|
||
│ └────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [Type a message... ] [Send] │
|
||
└────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Implementation:**
|
||
- Uses existing `MentorMessage` model
|
||
- Messages auto-marked as read when the chat is viewed
|
||
- Real-time updates via polling (every 10s) or WebSocket if available
|
||
- Both mentor and any team member can send messages
|
||
|
||
### 4.2 File Upload & Comments
|
||
|
||
The core new feature: a private file space with threaded discussion.
|
||
|
||
```
|
||
┌────────────────────────────────────────────────┐
|
||
│ [💬 Chat] [📁 Files] [📋 Milestones] │
|
||
│ │
|
||
│ ┌── Workspace Files ───────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ 📄 Business Plan v2.pdf │ │
|
||
│ │ Uploaded by Sarah (Team) · Apr 5 │ │
|
||
│ │ 💬 3 comments │ │
|
||
│ │ [Download] [Comment] [Promote →] │ │
|
||
│ │ │ │
|
||
│ │ 📄 Financial Model.xlsx │ │
|
||
│ │ Uploaded by Dr. Martin (Mentor) · Apr 6│ │
|
||
│ │ 💬 1 comment │ │
|
||
│ │ [Download] [Comment] │ │
|
||
│ │ │ │
|
||
│ │ 📄 Pitch Deck Draft.pptx │ │
|
||
│ │ Uploaded by Sarah (Team) · Apr 8 │ │
|
||
│ │ ✅ Promoted → "Presentation" slot │ │
|
||
│ │ [Download] [View Comments] │ │
|
||
│ │ │ │
|
||
│ └──────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [📤 Upload File] │
|
||
└────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**File Upload Flow:**
|
||
1. User (mentor or team member) clicks "Upload File"
|
||
2. Client calls `mentor.getWorkspaceUploadUrl(mentorAssignmentId, fileName, mimeType)`
|
||
3. Server generates MinIO pre-signed PUT URL
|
||
4. Client uploads directly to MinIO
|
||
5. Client calls `mentor.saveWorkspaceFile(mentorAssignmentId, fileName, mimeType, size, bucket, objectKey, description)`
|
||
6. Server creates `MentorFile` record
|
||
|
||
**File Comments:**
|
||
|
||
```
|
||
┌── Comments on: Business Plan v2.pdf ──────────┐
|
||
│ │
|
||
│ Dr. Martin (Mentor) · Apr 5, 16:00 │
|
||
│ Section 3.2 needs stronger market analysis. │
|
||
│ Consider adding competitor comparisons. │
|
||
│ └─ Sarah (Team) · Apr 5, 18:30 │
|
||
│ Good point — we'll add a competitive │
|
||
│ landscape section. See updated version. │
|
||
│ │
|
||
│ Dr. Martin (Mentor) · Apr 6, 10:00 │
|
||
│ Revenue projections look much better now. │
|
||
│ Ready for promotion to official submission? │
|
||
│ └─ Sarah (Team) · Apr 6, 11:00 │
|
||
│ Yes, let's promote it! │
|
||
│ │
|
||
│ [Add comment... ] [Post] │
|
||
└────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Implementation:**
|
||
- `MentorFileComment` with `parentCommentId` for threading
|
||
- Both mentor and team members can comment
|
||
- Admin can view all comments
|
||
- Comments are timestamped and attributed
|
||
|
||
### 4.3 File Promotion to Official Submission
|
||
|
||
The key feature: converting a private mentoring file into an official submission document.
|
||
|
||
**Promotion Flow:**
|
||
|
||
```
|
||
1. Team member (or admin) clicks "Promote →" on a workspace file
|
||
2. Dialog appears:
|
||
┌────────────────────────────────────────┐
|
||
│ Promote File to Official Submission │
|
||
│ │
|
||
│ File: Business Plan v2.pdf │
|
||
│ │
|
||
│ Target submission window: │
|
||
│ [Round 2 Docs ▾] │
|
||
│ │
|
||
│ Replaces requirement: │
|
||
│ [Business Plan ▾] │
|
||
│ │
|
||
│ ⚠ This will replace the current │
|
||
│ "Business Plan" file for this project. │
|
||
│ │
|
||
│ [Cancel] [Promote & Replace] │
|
||
└────────────────────────────────────────┘
|
||
|
||
3. On confirmation:
|
||
a. System creates a new ProjectFile record:
|
||
- projectId: project's ID
|
||
- submissionWindowId: selected window
|
||
- requirementId: selected requirement slot
|
||
- fileName, mimeType, size: copied from MentorFile
|
||
- bucket, objectKey: SAME as MentorFile (no file duplication)
|
||
- version: incremented from previous file in slot
|
||
b. Previous file in that slot gets `replacedById` set to new file
|
||
c. MentorFile updated:
|
||
- isPromoted: true
|
||
- promotedToFileId: new ProjectFile ID
|
||
- promotedAt: now
|
||
- promotedByUserId: actor ID
|
||
d. Audit log entry created:
|
||
- action: "MENTOR_FILE_PROMOTED"
|
||
- details: { mentorFileId, projectFileId, submissionWindowId, requirementId, replacedFileId }
|
||
```
|
||
|
||
**Key Rules:**
|
||
- Only files in **active** mentoring workspaces can be promoted
|
||
- Promotion **replaces** the existing file for that requirement slot (per user's decision)
|
||
- The MinIO object is **not duplicated** — both MentorFile and ProjectFile point to the same objectKey
|
||
- Once promoted, the MentorFile shows a "Promoted" badge and the promote button is disabled
|
||
- Admin can un-promote (revert) if needed, which deletes the ProjectFile and resets MentorFile flags
|
||
- Promotion is audited with full provenance chain
|
||
|
||
**Who Can Promote:**
|
||
- Team lead (Project.submittedByUserId or TeamMember.role = LEAD)
|
||
- Admin (always)
|
||
- Mentor (only if `MentoringConfig.mentorCanPromote` is true — default false for safety)
|
||
|
||
### 4.4 Privacy Model
|
||
|
||
```
|
||
Visibility Matrix:
|
||
┌──────────────────┬────────┬──────────┬───────┬──────┐
|
||
│ Content │ Mentor │ Team │ Admin │ Jury │
|
||
├──────────────────┼────────┼──────────┼───────┼──────┤
|
||
│ Chat messages │ ✅ │ ✅ │ ✅ │ ❌ │
|
||
│ Workspace files │ ✅ │ ✅ │ ✅ │ ❌ │
|
||
│ File comments │ ✅ │ ✅ │ ✅ │ ❌ │
|
||
│ Mentor notes │ ✅ │ ❌ │ ✅* │ ❌ │
|
||
│ Promoted files │ ✅ │ ✅ │ ✅ │ ✅** │
|
||
└──────────────────┴────────┴──────────┴───────┴──────┘
|
||
|
||
* Only if MentorNote.isVisibleToAdmin = true
|
||
** Promoted files become official submissions visible to jury
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Mentor Dashboard
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Mentor Dashboard │
|
||
│ ─────────────────────────────────────────────────────── │
|
||
│ │
|
||
│ Mentoring Period: June 1 – June 30 │
|
||
│ ⏱ 18 days remaining │
|
||
│ │
|
||
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ │
|
||
│ │ 3 │ │ 12 │ │ 5 │ │
|
||
│ │ Teams │ │ Messages│ │ Files │ │
|
||
│ └─────────┘ └─────────┘ └──────────┘ │
|
||
│ │
|
||
│ My Assigned Teams │
|
||
│ ┌────────────────────────────────────────────────────┐ │
|
||
│ │ OceanClean AI (Startup) │ │
|
||
│ │ 💬 2 unread messages · 📁 3 files · Last: Apr 6 │ │
|
||
│ │ [Open Workspace] │ │
|
||
│ ├────────────────────────────────────────────────────┤ │
|
||
│ │ Blue Carbon Hub (Concept) │ │
|
||
│ │ 💬 0 unread · 📁 1 file · Last: Apr 4 │ │
|
||
│ │ [Open Workspace] │ │
|
||
│ ├────────────────────────────────────────────────────┤ │
|
||
│ │ SeaWatch Monitor (Startup) │ │
|
||
│ │ ⚠ No activity yet │ │
|
||
│ │ [Open Workspace] │ │
|
||
│ └────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Milestones │
|
||
│ ┌────────────────────────────────────────────────────┐ │
|
||
│ │ ☑ Initial review (3/3 teams) │ │
|
||
│ │ ☐ Business plan feedback (1/3 teams) │ │
|
||
│ │ ☐ Pitch deck review (0/3 teams) │ │
|
||
│ └────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Applicant Experience
|
||
|
||
On the applicant dashboard, a "Mentoring" section appears when mentoring is active:
|
||
|
||
```
|
||
┌────────────────────────────────────────────────┐
|
||
│ Your Mentor: Dr. Martin Duval │
|
||
│ Expertise: Marine Biology, Sustainability │
|
||
│ │
|
||
│ Mentoring Period: June 1 – June 30 │
|
||
│ ⏱ 18 days remaining │
|
||
│ │
|
||
│ [💬 Messages (2 unread)] │
|
||
│ [📁 Workspace Files (3)] │
|
||
│ [📋 Milestones] │
|
||
└────────────────────────────────────────────────┘
|
||
```
|
||
|
||
Clicking "Workspace Files" opens the same workspace view as the mentor (with appropriate permissions).
|
||
|
||
---
|
||
|
||
## 7. Admin Experience
|
||
|
||
Admin can:
|
||
- **Assign/reassign mentors** via bulk or individual assignment
|
||
- **View any workspace** (read-only or with full edit access)
|
||
- **Promote files** on behalf of teams
|
||
- **Track activity** — dashboard showing mentor engagement:
|
||
- Messages sent per mentor
|
||
- Files uploaded
|
||
- Milestones completed
|
||
- Last activity timestamp
|
||
- **Extend/close mentoring window** per team or globally
|
||
- **Export workspace data** for audit purposes
|
||
|
||
---
|
||
|
||
## 8. API — New and Modified Procedures
|
||
|
||
### New Procedures (mentor-workspace router)
|
||
|
||
| Procedure | Auth | Purpose |
|
||
|-----------|------|---------|
|
||
| `mentorWorkspace.getUploadUrl` | Mentor or Team | Get MinIO pre-signed URL for workspace upload |
|
||
| `mentorWorkspace.saveFile` | Mentor or Team | Create MentorFile record after upload |
|
||
| `mentorWorkspace.listFiles` | Mentor, Team, Admin | List workspace files with comment counts |
|
||
| `mentorWorkspace.deleteFile` | Uploader or Admin | Delete workspace file |
|
||
| `mentorWorkspace.getFileDownloadUrl` | Mentor, Team, Admin | Get MinIO pre-signed URL for download |
|
||
| `mentorWorkspace.addComment` | Mentor, Team, Admin | Add comment to file (with optional parentCommentId) |
|
||
| `mentorWorkspace.listComments` | Mentor, Team, Admin | Get threaded comments for a file |
|
||
| `mentorWorkspace.deleteComment` | Author or Admin | Delete a comment |
|
||
| `mentorWorkspace.promoteFile` | Team Lead or Admin | Promote workspace file to official submission |
|
||
| `mentorWorkspace.unpromoteFile` | Admin only | Revert a promotion |
|
||
| `mentorWorkspace.getWorkspaceStatus` | Any participant | Get workspace summary (file count, message count, etc.) |
|
||
|
||
### Modified Existing Procedures
|
||
|
||
| Procedure | Change |
|
||
|-----------|--------|
|
||
| `mentor.getMyProjects` | Include workspace status (file count, unread messages) |
|
||
| `mentor.getProjectDetail` | Include MentorFile[] with comment counts |
|
||
| `applicant.getMyDashboard` | Include mentor workspace summary if mentoring active |
|
||
| `file.listByProjectForRound` | Promoted files visible to jury (via ProjectFile record) |
|
||
|
||
---
|
||
|
||
## 9. Service: `mentor-workspace.ts`
|
||
|
||
### Key Functions
|
||
|
||
```typescript
|
||
// Upload handling
|
||
async function getWorkspaceUploadUrl(
|
||
mentorAssignmentId: string,
|
||
fileName: string,
|
||
mimeType: string,
|
||
actorId: string,
|
||
prisma: PrismaClient
|
||
): Promise<{ uploadUrl: string; objectKey: string }>
|
||
|
||
// Save file metadata after upload
|
||
async function saveWorkspaceFile(
|
||
mentorAssignmentId: string,
|
||
uploadedByUserId: string,
|
||
file: { fileName, mimeType, size, bucket, objectKey },
|
||
description: string | null,
|
||
prisma: PrismaClient
|
||
): Promise<MentorFile>
|
||
|
||
// Promote file to official submission
|
||
async function promoteFileToSubmission(
|
||
mentorFileId: string,
|
||
submissionWindowId: string,
|
||
requirementId: string | null,
|
||
actorId: string,
|
||
prisma: PrismaClient
|
||
): Promise<{ mentorFile: MentorFile; projectFile: ProjectFile }>
|
||
// Steps:
|
||
// 1. Validate mentorFile exists, is not already promoted, workspace is active
|
||
// 2. If requirementId: find existing ProjectFile for that requirement, set replacedById
|
||
// 3. Create new ProjectFile (reusing same bucket/objectKey — no MinIO duplication)
|
||
// 4. Update MentorFile: isPromoted=true, promotedToFileId, promotedAt, promotedByUserId
|
||
// 5. Audit log with full provenance
|
||
|
||
// Revert promotion
|
||
async function unpromoteFile(
|
||
mentorFileId: string,
|
||
actorId: string,
|
||
prisma: PrismaClient
|
||
): Promise<void>
|
||
// Steps:
|
||
// 1. Find the ProjectFile created by promotion
|
||
// 2. If it replaced a previous file, restore that file's replacedById=null
|
||
// 3. Delete the promoted ProjectFile
|
||
// 4. Reset MentorFile flags
|
||
// 5. Audit log
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Edge Cases
|
||
|
||
| Scenario | Handling |
|
||
|----------|----------|
|
||
| Team doesn't want mentoring but admin assigns anyway | Assignment created; team sees mentor in dashboard |
|
||
| Mentor goes inactive during period | Admin can reassign; previous workspace preserved |
|
||
| File promoted then mentor period closes | Promoted file remains as official submission |
|
||
| Team tries to promote file for a requirement that doesn't exist | Error — must select valid requirement or leave requirementId null |
|
||
| Two files promoted to the same requirement slot | Second promotion replaces first (versioning) |
|
||
| Mentoring file is larger than requirement maxSizeMB | Warning shown but promotion allowed (admin override implicit) |
|
||
| Workspace closed but team needs one more upload | Admin can extend via round window or grant grace |
|
||
| Promoted file deleted from workspace | ProjectFile remains (separate record); audit shows provenance |
|