Skip to main content

V4.0 Migration Guide - User Cases Update

Version: 4.0 Date: 2025-11-11 Purpose: Guide for updating user cases from v3.0 to v4.0

📋 Overview​

This document outlines all changes needed to update existing user cases (UC-01 through UC-16) to reflect the v4.0 schema changes.

Major Changes in V4.0:

  • Multi-company crew support
  • Equipment tracking with availability
  • Global functions + company custom functions
  • Crew capabilities & company private notes
  • Communication audit log
  • Multi-currency support
  • Enhanced file storage with access control

🎯 Impact by User Case​

UC-01: Create New Project​

File: 01-admin-project-management.md Status: Minor updates needed

Changes Required:

  1. Step 3: Add Project Details

    • Add note about project dates being informational
    • Add: "Bookings can be outside these dates (for pre-visits, post-production, etc.)"

  2. Step 4: Budget Setup

    • Add new section: "Equipment Budget"
      • Add company equipment with availability checking
      • Set rates (adjustable from defaults)
    • Add new section: "Generic Budget Items"
      • Add line items for rentals, venue costs, catering
      • Free-text description + amount + currency

  3. Step 5: Contract Template

    • Add: "Select contract template (defaults from company settings, can customize for this project)"
    • Add: "Rich text editor with merge fields"

Example Addition:

**Step 3b: Add Equipment (Optional)**

**UI Actions:**
1. Click "+ Add Equipment" on Equipment tab
2. Select equipment from company inventory dropdown
   - Shows: Name, default rate, current availability status
3. Set booking dates (can be outside project dates)
4. Adjust rate if needed (defaults from equipment settings)
5. System checks availability:
   - ✅ "OB-Van Alpha is available"
   - ⚠️ "GFX Server 1 is already booked Aug 12-15 for Project X"
6. Click "Add to Project"

**System Actions:**
- Creates `project_equipment` record
- Links equipment to project with dates
- Stores rate (cents + currency)
- Displays in Equipment tab with availability calendar

UC-02: Manage Project Crew Requirements​

File: 01-admin-project-management.md Status: Minor updates needed

Changes Required:

  1. Functions Selection
    • Update to show both global and company custom functions
    • Add: "Source" column (Global / Custom badge)
    • Add: "Default Fee" (company-specific, even for global functions)

Example SQL Update:

-- Old (v3.0):
SELECT * FROM functions_catalog
WHERE company_id = {company_id};

-- New (v4.0):
SELECT fc.*,
       gf.name as global_function_name,
       CASE WHEN fc.global_function_id IS NOT NULL
            THEN 'Global'
            ELSE 'Custom'
       END as source
FROM functions_catalog fc
LEFT JOIN global_functions gf ON fc.global_function_id = gf.id
WHERE fc.company_id = {company_id};

UC-03: Update Project Budget​

File: 01-admin-project-management.md Status: Moderate updates needed

Changes Required:

  1. Budget Components

    • Add new section: "Equipment Costs"
    • Add new section: "Generic Budget Items"
    • Add currency conversion display

  2. Total Calculation

    • Update formula to include equipment + generic items
    • Show conversion to company base currency if needed

Example Addition:

**Budget Breakdown:**

**Crew Costs:**
- Camera Operators: 2 × (3 work days @ 5,500 SEK + 2 travel days @ 2,750 SEK) = 38,500 SEK
- Sound Engineers: 1 × (3 work days @ 4,500 SEK + 2 travel days @ 2,250 SEK) = 18,000 SEK
**Subtotal Crew**: 56,500 SEK

**Equipment Costs:** (NEW in v4.0)
- OB-Van Alpha: 5 days @ 15,000 SEK/day = 75,000 SEK
- GFX Server 1: 3 days @ 8,000 SEK/day = 24,000 SEK
**Subtotal Equipment**: 99,000 SEK

**Generic Budget Items:** (NEW in v4.0)
- Rental: External crane = 25,000 SEK
- Venue parking fees = 5,000 SEK
- Catering = 12,000 SEK
**Subtotal Generic**: 42,000 SEK

**Total Budget**: 197,500 SEK (17,775 EUR at 0.09 rate)

UC-04: Send Assignment Offer​

File: 02-admin-staffing.md Status: MAJOR updates needed

Changes Required:

  1. Crew Selection

    • Add employment status display (Staff / Freelance)
    • Add capabilities preview
    • Add availability checking (staff only)
    • Remove visibility of other company relationships

  2. New Fields

    • Add "Role Note" field (e.g., "Main", "Backup")
    • Add "Team Label" field (e.g., "Camera A")
    • Add currency selector for rates

  3. Availability Warnings (NEW)

    • Only for staff members
    • Soft warnings (can still book)

Complete Rewrite Example:

### UC-04: Send Assignment Offer (V4.0)

**Actor**: Admin (Susanne)
**Preconditions**:
- Project exists
- Required functions defined
- Crew members in directory

**Trigger**: Susanne clicks "Send Offer" for a project function

---

**Step 1: Select Crew Member**

**UI Actions:**
1. Search box autocomplete
2. Type crew name (e.g., "Lisa")
3. View search results showing:
   - Photo + name
   - Employment status: "Freelancer" or "Staff at [Company]"
   - Functions: "Camera Operator (Senior), Lighting Technician (Mid)"
   - Capabilities: "Handheld, Steadicam, Sony cameras..."
   - Availability indicator (if staff): ✅ Available / ⚠️ Limited / ❌ Busy

**System Actions:**
- Queries crew_profiles joined with company_crew (only THIS company's relationship)
- Displays crew with matching functions
- For staff: Checks crew_availability for conflicts
- Shows warning if project dates overlap with existing bookings

**Business Rules:**
- Cannot see if crew works for other companies (data isolation)
- Availability only shown for staff (where employer_id = company_id)
- Freelancers show no availability status

---

**Step 2: Set Assignment Details**

**UI Actions:**
1. Select function from dropdown (shows global + custom functions)
2. Enter role note (NEW in v4.0):
   - Free-text: "Main camera operator" or "Backup"
   - Optional field
3. Enter team label (NEW in v4.0):
   - Free-text: "Camera A" or "Audio Main"
   - Optional field for organization
4. Set work days: 5
5. Set travel days: 2
6. Set dates: Aug 15-21 (can be outside project dates of Aug 17-19)
7. Set departure city: "Stockholm"

**System Actions:**
- Loads default rates from functions_catalog
- Calculates date range
- If staff: Checks for conflicts and shows warning
- If dates outside project dates: Shows info message

**System Check - Availability (Staff Only):**
```sql
-- Check if this crew member (if staff) has conflicts
SELECT * FROM crew_availability ca
JOIN crew_users cu ON ca.crew_user_id = cu.id
WHERE cu.id = (SELECT claimed_by_user_id FROM crew_profiles WHERE id = {crew_profile_id})
  AND cu.employer_id = {company_id}  -- Only check if employed here
  AND ca.company_id = {company_id}
  AND (
    (ca.start_date BETWEEN {booking_start} AND {booking_end})
    OR (ca.end_date BETWEEN {booking_start} AND {booking_end})
  );

Warning displayed: ⚠️ "Lisa has marked herself unavailable Aug 16-18 (Vacation). Send offer anyway?"

Step 3: Set Rates & Currency (NEW in v4.0)

UI Actions:

  1. Select currency: SEK (dropdown: SEK, EUR, USD, etc.)
  2. Set work day rate: 5,500 SEK (default from function shown as suggestion)
  3. Set travel day rate: 2,750 SEK (default shown)
  4. View total calculation: 5 × 5,500 + 2 × 2,750 = 33,000 SEK

System Actions:

  • Loads default_fee from functions_catalog for this company
  • Converts to selected currency if needed (using exchange_rates table)
  • Calculates total
  • Displays in both selected currency and company base currency

Step 4: Add Personal Message

UI Actions:

  1. View pre-filled template (from company settings)
  2. Edit message:
    • Use merge fields: {crew_name}, {project_name}, {dates}
    • Customize for this specific offer
  3. Preview how email will look

System Template Example:

Hi {crew_name},

We'd love to have you join us for {project_name} in {location}.

Dates: {dates}
Role: {function} - {role_note}
Team: {team_label}

Rates:
- Work days: {work_days} days @ {work_rate} {currency}
- Travel days: {travel_days} days @ {travel_rate} {currency}
Total: {total_amount} {currency}

Looking forward to working with you!

Best regards,
{sender_name}

Step 5: Choose Booking Type (NEW in v4.0)

UI Actions:

  1. Select booking type:
    • ⭕ Send Offer (default) - Standard offer/negotiation flow
    • ⚪ Book Directly - Immediate assignment (for staff, self-assignment)
  2. View help text explaining difference

System Logic:

  • If "Send Offer": Creates assignment_offer with is_direct_booking = false
  • If "Book Directly": Creates assignment_offer with is_direct_booking = true
    • AND immediately creates assignment
    • AND sends confirmation email (not offer email)

Step 6: Send Offer

UI Actions:

  1. Click "Send Offer" button

System Actions:

  1. Create assignment_offer record:
INSERT INTO assignment_offers (
  id, project_function_id, crew_profile_id,
  is_direct_booking,
  work_day_rate_cents, travel_day_rate_cents, rate_currency,
  departure_city, status, personal_message,
  created_by_user_id, created_at
) VALUES (
  uuid_generate_v4(),
  {project_function_id},
  {crew_profile_id},
  false,  -- Send offer (not direct booking)
  550000,  -- 5,500 SEK in cents
  275000,  -- 2,750 SEK in cents
  'SEK',
  'Stockholm',
  'pending',
  {personal_message},
  {current_user_id},
  NOW()
);
  1. Create communication_logs entry:
INSERT INTO communication_logs (
  id, company_id, crew_profile_id,
  recipient_email, recipient_name,
  type, subject, message_content, status,
  project_id, offer_id,
  sent_by_user_id, sent_at, created_at
) VALUES (
  uuid_generate_v4(),
  {company_id},
  {crew_profile_id},
  'lisa@example.com',
  'Lisa Andersson',
  'booking_request',
  'Assignment Offer: Champions League Final 2025',
  {full_email_content},
  'sent',
  {project_id},
  {offer_id},
  {current_user_id},
  NOW(),
  NOW()
);
  1. Send email to crew member
  2. Display success message
  3. Update offer management view

Result:

  • Offer sent to Lisa
  • Status: Pending
  • Communication logged
  • Susanne can track in Communication Log tab

---

### UC-05: Direct Crew Booking
**File**: `02-admin-staffing.md`
**Status**: Needs update to reflect new is_direct_booking flow

**Changes Required:**
1. Update to use new "Book Directly" option
2. Add role note and team label fields
3. Add currency selection
4. Update communication logging

---

### UC-06: Manage Crew Availability
**File**: `02-admin-staffing.md`
**Status**: **MAJOR rewrite needed**

**Complete Replacement Needed:**

```markdown
### UC-06: Manage Crew Availability (V4.0)

**Actor**: Admin (Susanne) or Crew Member (Johan - if staff)
**Preconditions**:
- Crew member exists
- Crew member is employed (staff) by company

**Trigger**: Need to mark crew member as unavailable

**IMPORTANT**: Availability tracking only for STAFF members (where employer_id is set)

---

**Step 1: Check Employment Status**

**UI Actions:**
1. Navigate to Crew Profile
2. View employment status badge

**System Check:**
```sql
SELECT cu.employer_id, c.name as employer_name
FROM crew_profiles cp
LEFT JOIN crew_users cu ON cp.claimed_by_user_id = cu.id
LEFT JOIN companies c ON cu.employer_id = c.id
WHERE cp.id = {crew_profile_id};

Business Rules:

  • If employer_id IS NULL → Freelancer → No availability tracking

    • Display message: "Freelancers manage their own availability by accepting/declining offers"
    • Hide Availability tab

  • If employer_id = current_company_id → Staff at this company → Can track availability

    • Display message: "This crew member is employed by your company"
    • Show Availability tab

  • If employer_id = other_company_id → Staff at another company → Read-only

    • Display message: "This crew member is employed by another company"
    • No availability tracking shown
    • Can still book (staff rental scenario)

Step 2: Add Unavailable Period (Staff Only)

UI Actions (only if staff at this company):

  1. Click "Availability" tab
  2. View calendar showing existing blocks
  3. Click "+ Add Unavailable Period"
  4. Set start date: Aug 10
  5. Set end date: Aug 15
  6. Select reason/type: "Vacation"
  7. Add notes: "Summer holiday, confirmed"
  8. Click "Save"

System Actions:

-- Only if crew is staff at this company
INSERT INTO crew_availability (
  id, crew_user_id, company_id,
  start_date, end_date, status, notes,
  created_at, updated_at
) VALUES (
  uuid_generate_v4(),
  {crew_user_id},  -- From crew_users (claimed account)
  {company_id},     -- Current company
  '2025-08-10',
  '2025-08-15',
  'unavailable',
  'Summer holiday, confirmed',
  NOW(),
  NOW()
);

Validation Rules:

  • Must have claimed_by_user_id (crew must have registered account)
  • Must have employer_id = company_id (must be staff)
  • Start date < End date
  • Cannot delete past availability blocks

Step 3: Availability Checking in Booking Flow

When admin tries to book this crew member:

System Check:

-- Check if crew member has marked themselves unavailable
-- (Only relevant if they're staff at this company)
SELECT ca.*
FROM crew_availability ca
JOIN crew_users cu ON ca.crew_user_id = cu.id
WHERE cu.id = {crew_user_id}
  AND cu.employer_id = {company_id}  -- Only check if employed here
  AND ca.company_id = {company_id}
  AND ca.status = 'unavailable'
  AND (
    (ca.start_date BETWEEN {booking_start} AND {booking_end})
    OR (ca.end_date BETWEEN {booking_start} AND {booking_end})
    OR ({booking_start} BETWEEN ca.start_date AND ca.end_date)
  );

If conflict found:

  • ⚠️ Display warning: "Johan has marked himself unavailable Aug 10-15 (Vacation). Send offer anyway?"
  • Allow admin to proceed (soft warning, not blocking)
  • Log override in communication

If no conflict or freelancer:

  • ✅ No warning shown
  • Proceed with booking normally

Multi-Company Scenarios:

Scenario A: Johan is staff at Company A, booked by Company B

  • Company A: Can see/edit Johan's availability (employer)
  • Company B: Cannot see Johan's availability (not employer)
  • Company B can still book Johan (staff rental)
  • No availability conflict warnings for Company B

Scenario B: Lisa is freelancer, works for Company A and Company B

  • No company tracks her availability
  • Lisa manages conflicts herself (accept/decline offers)
  • No availability warnings ever shown

Scenario C: Ken is staff at Company A, only works for Company A

  • Company A: Full availability tracking
  • Ken can view/edit own availability in crew portal
  • Availability warnings shown when booking

---

### UC-07: Add Crew Member to Directory
**File**: `03-admin-operations.md`
**Status**: **MAJOR rewrite needed**

**Complete Replacement:**

```markdown
### UC-07: Add Crew Member to Directory (V4.0)

**Actor**: Admin (Susanne)
**Preconditions**: None
**Trigger**: Need to add new crew member

**TWO OPTIONS AVAILABLE:**
1. **Add Crew Directly** - Admin creates profile, crew claims later
2. **Send Invitation** - Crew self-registers via email link

---

## OPTION A: Add Crew Directly

**Step 1: Check if Email Exists**

**UI Actions:**
1. Navigate to Crew Directory
2. Click "+ Add Crew"
3. Select "Add Crew Directly" tab
4. Enter email: "lisa@example.com"

**System Actions:**
```sql
-- Check if this email already has a crew_users account
SELECT cu.id, cu.email,
       COUNT(DISTINCT cc.company_id) as company_count
FROM crew_users cu
LEFT JOIN crew_profiles cp ON cu.id = cp.claimed_by_user_id
LEFT JOIN company_crew cc ON cp.id = cc.crew_profile_id
WHERE cu.email = 'lisa@example.com'
GROUP BY cu.id, cu.email;

Business Rules:

  • If email not found: Proceed with new crew creation
  • If email found (crew works for other companies):
    • Display message: "This email is already in use. Creating profile will link to existing account when crew registers."
    • Admin can proceed
    • Complete data isolation maintained (Company A can't see Company B's data)

Step 2: Enter Crew Information

UI Form Fields:

Basic Information:

  • First name: "Lisa"
  • Last name: "Andersson"
  • Email: "lisa@example.com" (for future account claiming)
  • Phone: "+46 70 123 4567"
  • Home base city: "Stockholm"

Capabilities (NEW in v4.0 - PUBLIC field):

  • Text area: "Handheld camera, Steadicam, Sony FX9 experience, 10 years live sports broadcasting"
  • Help text: "This information will be visible to the crew member"

Functions/Roles:

  • Select functions: "Camera Operator" (Seniority: Senior)
  • Add function: "Lighting Technician" (Seniority: Mid)

Company Private Notes (NEW in v4.0 - SEPARATE, PRIVATE):

  • Text area: "Prefers morning shifts, has back problems, needs frequent breaks"
  • Warning: "⚠️ NOT visible to crew member - Company-specific confidential notes"
  • Help text: "GDPR-sensitive information"

Additional Information:

  • Address, nationality, passport, emergency contact, preferences, etc.

Step 3: Create Crew Profile

UI Actions:

  1. Click "Save & Add to Directory"

System Actions:

-- 1. Create crew_profile (without account)
INSERT INTO crew_profiles (
  id, claimed_by_user_id,
  first_name, last_name, email, phone,
  capabilities,  -- NEW in v4.0
  home_base_city, photo_url,
  created_at, updated_at
) VALUES (
  uuid_generate_v4(),
  NULL,  -- No account yet, can be claimed later
  'Lisa',
  'Andersson',
  'lisa@example.com',  -- Used for future account claiming
  '+46 70 123 4567',
  'Handheld camera, Steadicam, Sony FX9 experience, 10 years live sports broadcasting',
  'Stockholm',
  NULL,  -- No photo yet
  NOW(),
  NOW()
);

-- 2. Create company_crew relationship with PRIVATE notes
INSERT INTO company_crew (
  id, company_id, crew_profile_id,
  private_notes,  -- NEW in v4.0
  created_at, updated_at
) VALUES (
  uuid_generate_v4(),
  {company_id},
  {crew_profile_id},
  'Prefers morning shifts, has back problems, needs frequent breaks',
  NOW(),
  NOW()
);

-- 3. Add functions
INSERT INTO profile_functions (
  id, crew_profile_id, function_id, seniority, created_at
) VALUES
  (uuid_generate_v4(), {crew_profile_id}, {camera_operator_function_id}, 'senior', NOW()),
  (uuid_generate_v4(), {crew_profile_id}, {lighting_technician_function_id}, 'mid', NOW());

Result:

  • Crew profile created (claimed_by_user_id = NULL)
  • Company-crew relationship established with private notes
  • Crew can be booked immediately
  • Crew can register later and "claim" this profile

Account Status Badge: "Not Registered"

Step 4: Crew Claims Profile Later (Separate workflow)

When Lisa registers via invitation or discovers her profile:

  1. Lisa enters email: "lisa@example.com"
  2. System finds unclaimed crew_profiles with matching email
  3. Lisa creates account (crew_users)
  4. System links profiles via claimed_by_user_id:
-- Create crew_users account
INSERT INTO crew_users (
  id, email, password, employer_id,
  created_at, updated_at
) VALUES (
  uuid_generate_v4(),
  'lisa@example.com',
  {hashed_password},
  NULL,  -- Freelancer
  NOW(),
  NOW()
);

-- Link all crew_profiles with this email
UPDATE crew_profiles
SET claimed_by_user_id = {crew_user_id},
    updated_at = NOW()
WHERE email = 'lisa@example.com'
  AND claimed_by_user_id IS NULL;
  1. Lisa can now:
    • Login to crew.pbs.com
    • See assignments from ALL companies
    • Edit her capabilities and basic info
    • View offers and respond
    • Cannot see private notes (data isolation)

Account Status Badge: "Registered"

OPTION B: Send Invitation​

Step 1: Send Invitation

UI Actions:

  1. Click "+ Invite Crew"
  2. Enter email: "ken@example.com"
  3. Select auto-approve: Yes/No
  4. Add optional personal message
  5. Click "Send Invitation"

System Actions:

-- 1. Check if email exists
SELECT * FROM crew_users WHERE email = 'ken@example.com';

-- 2. Create staff_invitation
INSERT INTO staff_invitations (
  id, company_id, email, token,
  auto_approve, status, sent_at,
  invited_by_user_id, created_at, updated_at
) VALUES (
  uuid_generate_v4(),
  {company_id},
  'ken@example.com',
  {unique_token},  -- For registration URL
  true,  -- Auto-approve after registration
  'pending',
  NOW(),
  {current_user_id},
  NOW(),
  NOW()
);

-- 3. Send email with link: crew.pbs.com/register/{token}

Email Content:

Subject: Invitation to join [Company Name]'s crew directory

Hi,

You've been invited to join [Company Name]'s crew directory.

Click here to register: https://crew.pbs.com/register/{token}

[Optional personal message from Susanne]

Best regards,
[Company Name]

Step 2: Crew Registers (See UC-12 for full registration flow)

Multi-Company Handling:

  • If email already exists (crew works for other company):
    • Registration flow shows: "Welcome back! Login to link to [Company Name]"
    • Crew logs in
    • System creates new company_crew relationship
    • Crew sees combined assignments from all companies

Result:

  • Crew profile created
  • Company-crew relationship established
  • Crew can login and see assignments
  • Admin can add private notes after profile creation

---

### UC-11 to UC-16: Staff Workflows
**File**: `04-staff-workflows.md`
**Status**: Multiple updates needed

**UC-11: View My Assignments** - Add multi-company filtering
**UC-12: Accept/Decline Offer** - Add currency display, role notes
**UC-13: Complete Profile** - Add capabilities section
**UC-14: View Assignment Details** - Add team label, role note display
**UC-15: Update Availability** - MAJOR rewrite for staff-only tracking
**UC-16: Registration Flow** - MAJOR rewrite for account claiming

---

## 🔧 SQL Query Updates Reference

### Common Query Patterns in V4.0

**Get Crew with Employment Status:**
```sql
SELECT cp.*,
       cu.employer_id,
       c.name as employer_name,
       CASE
         WHEN cu.employer_id IS NOT NULL THEN 'Staff'
         ELSE 'Freelance'
       END as employment_type,
       cc.private_notes  -- Company-specific, hidden from crew
FROM crew_profiles cp
LEFT JOIN crew_users cu ON cp.claimed_by_user_id = cu.id
LEFT JOIN companies c ON cu.employer_id = c.id
INNER JOIN company_crew cc ON cp.id = cc.crew_profile_id
WHERE cc.company_id = {company_id};

Check Availability (Staff Only):

SELECT ca.*
FROM crew_availability ca
JOIN crew_users cu ON ca.crew_user_id = cu.id
JOIN crew_profiles cp ON cu.id = cp.claimed_by_user_id
WHERE cp.id = {crew_profile_id}
  AND cu.employer_id = {company_id}  -- Only if staff at this company
  AND ca.company_id = {company_id}
  AND ca.status = 'unavailable'
  AND (
    ({booking_start} BETWEEN ca.start_date AND ca.end_date)
    OR ({booking_end} BETWEEN ca.start_date AND ca.end_date)
  );

Get Functions (Global + Custom):

SELECT fc.*,
       gf.name as global_name,
       gf.category as global_category,
       CASE
         WHEN fc.global_function_id IS NOT NULL THEN 'Global'
         ELSE 'Custom'
       END as source
FROM functions_catalog fc
LEFT JOIN global_functions gf ON fc.global_function_id = gf.id
WHERE fc.company_id = {company_id}
ORDER BY source, fc.category, fc.name;

Create Assignment with All New Fields:

INSERT INTO assignments (
  id, project_function_id, crew_profile_id,
  work_day_rate_cents, travel_day_rate_cents, rate_currency,
  planned_work_days, planned_travel_days,
  role_note,     -- NEW in v4.0
  team_label,    -- NEW in v4.0
  departure_city, current_status,
  start_date, end_date,
  created_at, updated_at
) VALUES (
  uuid_generate_v4(),
  {project_function_id},
  {crew_profile_id},
  550000,  -- 5,500 SEK in cents
  275000,  -- 2,750 SEK in cents
  'SEK',
  5, 2,
  'Main camera operator',  -- Role note
  'Camera A',              -- Team label
  'Stockholm',
  'confirmed',
  '2025-08-15',
  '2025-08-21',
  NOW(),
  NOW()
);

Log Communication:

INSERT INTO communication_logs (
  id, company_id, crew_profile_id,
  recipient_email, recipient_name,
  type, subject, message_content, status,
  project_id, assignment_id, offer_id,
  sent_by_user_id, sent_at, created_at
) VALUES (
  uuid_generate_v4(),
  {company_id},
  {crew_profile_id},
  'lisa@example.com',
  'Lisa Andersson',
  'booking_request',
  'Assignment Offer: Champions League Final 2025',
  {full_message_html},
  'sent',
  {project_id},
  NULL,  -- No assignment yet
  {offer_id},
  {current_user_id},
  NOW(),
  NOW()
);

📝 Documentation String Updates​

Views References​

All user cases should reference updated view specifications:

  • "See View 4: Crew Directory (v4.0)" instead of "See View 4"
  • Reference new views: "See View 9: Equipment Management"
  • Reference new tabs: "Communication Log tab (View 3)"

Terminology Updates​

  • "Staff Directory" → "Crew Directory"
  • "Profile" → "Crew Profile"
  • Add "Employment Status" mentions where relevant
  • Add "Currency" mentions for all financial displays
  • "Availability" → "Availability (Staff Only)"

✅ Validation Checklist​

Before marking user case as v4.0 compliant, verify:

Multi-Company Support:

  • No visibility of other company relationships
  • Private notes clearly marked and separated
  • Account claiming workflow explained
  • Multi-company filtering shown in crew portal

Equipment:

  • Equipment booking workflows included where relevant
  • Availability checking demonstrated
  • Budget calculations include equipment

Functions:

  • Global vs custom functions distinction clear
  • Company-specific fees shown
  • Capabilities field used

Currency:

  • All financial amounts show currency code
  • Multi-currency bookings handled
  • Conversion to base currency shown in reports

Availability:

  • Staff-only restriction clearly stated
  • Freelancer handling explained
  • Soft warnings (not blocking) demonstrated

Communication:

  • All communications logged
  • Log viewing demonstrated
  • Status tracking shown

New Fields:

  • role_note field used in booking flows
  • team_label field used for organization
  • capabilities field shown in crew creation/editing

🎯 Priority Order for Updates​

High Priority (Break existing functionality if not updated):

  1. UC-06: Manage Crew Availability
  2. UC-07: Add Crew Member
  3. UC-04: Send Assignment Offer
  4. UC-16: Registration Flow

Medium Priority (New features, good to document): 5. UC-01: Create Project (equipment section) 6. UC-03: Update Project Budget (equipment + generic items) 7. UC-11: View My Assignments (multi-company filtering)

Low Priority (Minor enhancements): 8. UC-02: Manage Project Crew Requirements (function source) 9. UC-05: Direct Crew Booking (currency) 10. UC-13: Complete Profile (capabilities)

Next Steps:

  1. Start with High Priority user cases
  2. Use examples from this guide
  3. Test SQL queries with v4.0 schema
  4. Update screenshots/mockups if generated
  5. Cross-reference with updated views.md

Estimated Effort:

  • High Priority: 8-12 hours
  • Medium Priority: 4-6 hours
  • Low Priority: 2-3 hours
  • Total: 14-21 hours

Version: 4.0 Last Updated: 2025-11-11 Maintainer: Update as user cases are migrated