161 lines
6.2 KiB
Markdown
161 lines
6.2 KiB
Markdown
# Story 1.1: Project Setup & Database Schema
|
|
|
|
## Epic Reference
|
|
**Epic 1:** Core Foundation & Infrastructure
|
|
|
|
## User Story
|
|
As a **developer**,
|
|
I want **the Laravel 12 project configured with all required packages and complete database schema**,
|
|
So that **the foundation is established for all subsequent feature development**.
|
|
|
|
## Story Context
|
|
|
|
### Existing System Integration
|
|
- **Integrates with:** New project setup (greenfield)
|
|
- **Technology:** Laravel 12, PHP 8.4, Livewire 3, Volt, Flux UI Free, Tailwind CSS 4
|
|
- **Follows pattern:** Laravel 12 streamlined file structure
|
|
- **Touch points:** Database migrations, model factories, development environment
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Functional Requirements
|
|
- [ ] Laravel 12 project created with Livewire 3, Volt, Flux UI
|
|
- [ ] Tailwind CSS 4 configured with `@theme` directive
|
|
- [ ] Database migrations for all core tables:
|
|
- `users` (with user_type, national_id, company fields)
|
|
- `consultations`
|
|
- `timelines`
|
|
- `timeline_updates`
|
|
- `posts`
|
|
- `working_hours`
|
|
- `blocked_times`
|
|
- `notifications`
|
|
- `admin_logs`
|
|
- [ ] Model factories created for testing
|
|
- [ ] Development environment working (`composer run dev`)
|
|
|
|
### Integration Requirements
|
|
- [ ] SQLite configured for development database
|
|
- [ ] All migrations run without errors
|
|
- [ ] Factories generate valid test data
|
|
- [ ] Composer and npm scripts functional
|
|
|
|
### Quality Requirements
|
|
- [ ] All database tables have proper indexes
|
|
- [ ] Foreign key constraints properly defined
|
|
- [ ] Factories cover all required fields
|
|
- [ ] Development server starts without errors
|
|
|
|
## Technical Notes
|
|
|
|
- **Database:** Use SQLite for development (configurable for MariaDB in production)
|
|
- **Environment:** Set `DB_CONNECTION=sqlite` in `.env` for development
|
|
- **Reference:** PRD Section 16.1 for complete schema details
|
|
- **Pattern:** Follow existing Volt class-based component pattern
|
|
- **Structure:** Use Laravel 12 streamlined file structure (no app/Http/Middleware, bootstrap/app.php for config)
|
|
- **Testing:** Use Pest 4 for all tests (`php artisan make:test --pest`)
|
|
- **Models:** Create with `php artisan make:model ModelName -mf` (migration + factory)
|
|
- **Notifications table:** Custom implementation per PRD schema (not Laravel's built-in notifications)
|
|
|
|
### Database Schema Reference
|
|
|
|
```
|
|
users:
|
|
- id, name, email, password, user_type (enum: admin/individual/company)
|
|
- national_id (nullable), company_name (nullable), company_registration (nullable)
|
|
- phone, preferred_language (enum: ar/en), status (enum: active/deactivated)
|
|
- timestamps, email_verified_at
|
|
|
|
consultations:
|
|
- id, user_id, scheduled_date, scheduled_time, duration (default 45)
|
|
- status (enum: pending/approved/completed/cancelled/no_show)
|
|
- type (enum: free/paid), payment_amount (nullable), payment_status
|
|
- problem_summary, admin_notes, timestamps
|
|
|
|
timelines:
|
|
- id, user_id, case_name, case_reference (unique nullable)
|
|
- status (enum: active/archived), timestamps
|
|
|
|
timeline_updates:
|
|
- id, timeline_id, admin_id, update_text, timestamps
|
|
|
|
posts:
|
|
- id, title_ar, title_en, body_ar, body_en
|
|
- status (enum: draft/published), timestamps
|
|
|
|
working_hours:
|
|
- id, day_of_week (0-6), start_time, end_time, is_active, timestamps
|
|
|
|
blocked_times:
|
|
- id, block_date, start_time (nullable), end_time (nullable)
|
|
- reason, timestamps
|
|
|
|
admin_logs:
|
|
- id, admin_id, action_type, target_type, target_id
|
|
- old_values (json), new_values (json), ip_address, timestamps
|
|
```
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] All database migrations created and tested
|
|
- [ ] All model factories functional
|
|
- [ ] Development environment runs with `composer run dev`
|
|
- [ ] Tests pass for model creation using factories
|
|
- [ ] Code formatted with Pint
|
|
- [ ] No errors on fresh install
|
|
|
|
## Test Scenarios
|
|
|
|
All tests should use Pest 4 (`php artisan make:test --pest`).
|
|
|
|
### Migration Tests
|
|
- [ ] All migrations run successfully: `php artisan migrate:fresh`
|
|
- [ ] Migrations can rollback without errors: `php artisan migrate:rollback`
|
|
- [ ] Foreign key constraints are properly created (timeline_updates.timeline_id, timeline_updates.admin_id, consultations.user_id, timelines.user_id, admin_logs.admin_id)
|
|
|
|
### Factory Tests
|
|
- [ ] UserFactory creates valid User with all user_type enum values (admin, individual, company)
|
|
- [ ] ConsultationFactory creates valid Consultation with proper user relationship
|
|
- [ ] TimelineFactory creates valid Timeline with proper user relationship
|
|
- [ ] TimelineUpdateFactory creates valid TimelineUpdate with timeline and admin relationships
|
|
- [ ] PostFactory creates valid Post with bilingual fields
|
|
- [ ] WorkingHoursFactory creates valid WorkingHours for each day_of_week (0-6)
|
|
- [ ] BlockedTimeFactory creates valid BlockedTime entries
|
|
- [ ] NotificationFactory creates valid Notification entries
|
|
- [ ] AdminLogFactory creates valid AdminLog with JSON fields
|
|
|
|
### Enum Validation Tests
|
|
- [ ] User.user_type only accepts: admin, individual, company
|
|
- [ ] User.status only accepts: active, deactivated
|
|
- [ ] User.preferred_language only accepts: ar, en
|
|
- [ ] Consultation.status only accepts: pending, approved, completed, cancelled, no_show
|
|
- [ ] Consultation.type only accepts: free, paid
|
|
- [ ] Timeline.status only accepts: active, archived
|
|
- [ ] Post.status only accepts: draft, published
|
|
|
|
### Edge Case Tests
|
|
- [ ] Nullable fields accept null values (national_id, company_name, case_reference, etc.)
|
|
- [ ] JSON fields (old_values, new_values) store and retrieve correctly
|
|
- [ ] Unique constraint on case_reference allows multiple nulls but no duplicate values
|
|
|
|
## Dependencies
|
|
|
|
- None (this is the foundation story)
|
|
|
|
## Risk Assessment
|
|
|
|
- **Primary Risk:** Schema design changes required later
|
|
- **Mitigation:** Follow PRD specifications closely, validate with stakeholder
|
|
- **Rollback:** Fresh migration reset possible in development
|
|
|
|
### Error Handling
|
|
|
|
- **Migration failures:** Run `php artisan migrate:status` to identify failed migrations, fix the issue, then `php artisan migrate` to continue
|
|
- **Foreign key errors:** Ensure referenced tables are created before dependent tables (migrations run in filename order)
|
|
- **Factory errors:** Ensure factories define all required (non-nullable) fields and use valid enum values
|
|
|
|
## Estimation
|
|
|
|
**Complexity:** Medium
|
|
**Estimated Effort:** 4-6 hours
|