19959a2b3f
Introduces the first versions of client and staff mobile application prototypes, including platform-specific assets, screens, and configuration for Android, iOS, macOS, Linux, and Windows. Adds documentation, AI prompt guides, and a new staff payments feature module with repository, use cases, and presentation logic. Also includes generated localization files and supporting resources for both client and staff apps.
252 lines
10 KiB
Markdown
252 lines
10 KiB
Markdown
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
|
||
|
||
```mermaid
|
||
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
|