Krow-workspace/apps/mobile/ai_prompts/3-data-domain.md

TASK: Create the shared domain package.

Domain Details:

1. Core Domain Logic

1.1 Domain Entities Overview

The KROW platform has 49 domain entities organized into 8 logical groups:

┌────────────────────────────────────────────────────────────────────┐
│                        KROW DOMAIN MODEL                           │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │   USERS &   │    │  BUSINESS & │    │  EVENTS &   │             │
│  │ MEMBERSHIP  │    │ ORGANIZATION│    │   SHIFTS    │             │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤             │
│  │ User        │    │ Business    │    │ Event       │             │
│  │ Staff       │    │ BusinessSet │    │ EventShift  │             │
│  │ Membership  │    │ Hub         │    │ Position    │             │
│  │ BizMember   │    │ HubDept     │    │ Assignment  │             │
│  │ HubMember   │    │ BizContract │    │ WorkSession │             │
│  └─────────────┘    └─────────────┘    └─────────────┘             │
│                                                                    │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │  SKILLS &   │    │  FINANCIAL  │    │  RATINGS &  │             │
│  │   CERTS     │    │   PAYROLL   │    │  PENALTIES  │             │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤             │
│  │ Skill       │    │ Invoice     │    │ StaffRating │             │
│  │ SkillCat    │    │ InvoiceItem │    │ PenaltyLog  │             │
│  │ StaffSkill  │    │ InvDecline  │    │ BizStaffPref│             │
│  │ Certificate │    │ StaffPayment│    │             │             │
│  │ SkillKit    │    │             │    │             │             │
│  └─────────────┘    └─────────────┘    └─────────────┘             │
│                                                                    │
│  ┌─────────────┐    ┌─────────────┐                                │
│  │   STAFF     │    │   SUPPORT   │                                │
│  │   PROFILE   │    │    CONFIG   │                                │
│  ├─────────────┤    ├─────────────┤                                │
│  │ EmergencyC  │    │ Addon       │                                │
│  │ BankAccount │    │ Tag         │                                │
│  │ Accessibl   │    │ Media       │                                │
│  │ Schedule    │    │ WorkingArea │                                │
│  └─────────────┘    └─────────────┘                                │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

1.2 Key Entity Definitions

User & Authentication

Entity	Description	Key Fields
User	Base auth entity (Firebase)	id, email, phone, role
Staff	Worker profile	auth_provider_id, name, email, phone, status, address, avatar, live_photo
Membership	Polymorphic org membership	user_id, memberable_id, memberable_type, role

Staff Status Flow:

registered → pending → completed_profile → verified → [active | blocked | inactive]

Business & Organization

Entity	Description	Key Fields
Business	Client company	name, registration, status, avatar
BusinessSetting	Payroll config	prefix, overtime, clock_in, clock_out
Hub	Branch location	business_id, name, address, status
HubDepartment	Dept within hub	hub_id, name

Events & Shifts

Entity	Description	Key Fields
Event	Job posting	business_id, hub_id, name, date, status, contract_type
EventShift	Work session	event_id, name, address
EventShiftPosition	Job opening	shift_id, skill_id, count, rate, start_time, end_time, break
EventShiftPositionStaff	Assignment	staff_id, position_id, status, clock_in, clock_out

Event Status Flow:

draft → pending → assigned → confirmed → active → finished → completed → closed
                                                           ↘ under_review

Assignment Status Flow:

assigned → confirmed → ongoing → completed
         ↘ decline_by_staff → [penalty logged]
         ↘ canceled_by_staff → [penalty logged]
         ↘ no_showed → [penalty logged]

Skills & Certifications

Entity	Description	Key Fields
Skill	Job category	category_id, name, price
StaffSkill	Worker qualification	staff_id, skill_id, level, experience, status
Certificate	Required credential	name, required
SkillKit	Uniform/equipment req	skill_id, name, is_required, type

Skill Levels: beginner | skilled | professional

Financial & Payroll

Entity	Description	Key Fields
Invoice	Business bill	event_id, business_id, status, total, work_amount, addons_amount
InvoiceItem	Line item	invoice_id, staff_id, work_hours, rate, amounts
StaffPayment	Worker payout	staff_id, assignment_id, amount, status, paid_at

Invoice Status Flow:

open → disputed → resolved → verified → paid/reconciled
     ↘ overdue

1.3 Core Business Workflows

Workflow 1: Event Lifecycle

sequenceDiagram
    participant Client as Client App
    participant API as Backend API
    participant Admin as Admin
    participant Staff as Worker App

    Note over Client,API: 1. Event Creation
    Client->>API: Create Event with Shifts & Positions
    API-->>Client: Event Created (Draft)
    Client->>API: Publish Event
    API-->>Client: Event Published

    opt 2. Staff Assignment (Optional)
        Note over Admin,API: Optional Staff Assignment
        Admin->>API: Assign Staff to Shift
        API-->>Admin: Assignment Confirmed
        API->>Staff: Notification: New Shift
    end

    Note over Staff,API: 3. Shift Acceptance
    Staff->>API: Accept Shift
    API-->>Staff: Shift Confirmed

    Note over Client,Staff: 4. Day of Event
    Client->>Client: Generate QR Code
    Staff->>Staff: Scan QR Code
    Staff->>API: Clock In
    Staff->>API: Clock Out

    Note over Client,API: 5. Post-Event
    Client->>API: Rate Staff
    API->>API: Generate Invoice
    Client->>API: Approve Invoice

Workflow 2: Staff Onboarding

1. Registration (Firebase Phone Auth)
   ├── Create Staff record (status: registered)
   └── Profile created with auth_provider_id

2. Profile Completion
   ├── Personal info (name, email, address)
   ├── Avatar upload
   ├── Emergency contacts
   └── Bank account details

3. Skills Declaration
   ├── Add skills with level/experience
   └── Status: pending → verified (admin)

4. Certification Upload
   ├── Upload certificates
   └── Status: pending → verified (admin)

5. Equipment Confirmation
   ├── Confirm uniforms per skill
   ├── Confirm equipment per skill
   └── Upload photos as proof

6. Profile Submission
   ├── Complete verification checklist
   └── Status: completed_profile → verified

Workflow 3: Payroll Calculation

Work Hours = (clock_out - clock_in) - break_duration

Overtime Rules:
├── Regular Hours (1x):     hours <= 8
├── Overtime Hours (1.5x):  8 < hours <= 10
└── Doubletime Hours (2x):  hours > 10

Payment = (regular_hours × rate × 1.0)
        + (overtime_hours × rate × 1.5)
        + (doubletime_hours × rate × 2.0)
        + addons_amount

You must:

1. Create domain entities for ALL KROW entities provided
2. Group entities by logical folders
3. Use immutable models
4. Do NOT add JSON, serialization, or Firebase annotations
5. Do NOT add business logic
6. Use enums for all status flows
7. Add Doc comments for readability of the code.

Entities MUST match:

• Names
• Fields
• Status flows

Include:

• Enums for status flows
• Value objects where appropriate
• Clear folder structure

Exclude:

• DTOs
• Repositories
• Firebase logic
• Validation logic

Create packages/domain/lib/domain.dart (barrel file) This file must export ALL entities and enums.

All other packages will import ONLY: import 'package:domain/domain.dart';

Must follow archtiecture principles defined in:

• docs/01-architecture-principles.md

Must Follow Agent rules defined in:

• docs/02-agent-development-rules.md

Output:

• Folder structure
• Dart files
• Short explanation of grouping strategy