310 lines
9.3 KiB
Markdown
310 lines
9.3 KiB
Markdown
# Story 3.6: Calendar File Generation (.ics)
|
|
|
|
## Epic Reference
|
|
**Epic 3:** Booking & Consultation System
|
|
|
|
## User Story
|
|
As a **client**,
|
|
I want **to receive a calendar file when my booking is approved**,
|
|
So that **I can easily add the consultation to my calendar app**.
|
|
|
|
## Story Context
|
|
|
|
### Existing System Integration
|
|
- **Integrates with:** Consultation model, email attachments
|
|
- **Technology:** iCalendar format (RFC 5545)
|
|
- **Follows pattern:** Service class for generation
|
|
- **Touch points:** Approval email, client dashboard download
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Calendar File Generation
|
|
- [ ] Generate valid .ics file on booking approval
|
|
- [ ] File follows iCalendar specification (RFC 5545)
|
|
- [ ] Compatible with major calendar apps:
|
|
- Google Calendar
|
|
- Apple Calendar
|
|
- Microsoft Outlook
|
|
- Other standard clients
|
|
|
|
### Event Details
|
|
- [ ] Event title: "Consultation with Libra Law Firm" (bilingual)
|
|
- [ ] Date and time (correct timezone)
|
|
- [ ] Duration: 45 minutes
|
|
- [ ] Location (office address or "Phone consultation")
|
|
- [ ] Description with:
|
|
- Booking reference
|
|
- Consultation type (free/paid)
|
|
- Contact information
|
|
- [ ] Reminder: 1 hour before
|
|
|
|
### Delivery
|
|
- [ ] Attach to approval email
|
|
- [ ] Available for download from client dashboard
|
|
- [ ] Proper MIME type (text/calendar)
|
|
- [ ] Correct filename (consultation-{date}.ics)
|
|
|
|
### Language Support
|
|
- [ ] Event title in client's preferred language
|
|
- [ ] Description in client's preferred language
|
|
|
|
### Quality Requirements
|
|
- [ ] Valid iCalendar format (passes validators)
|
|
- [ ] Tests for file generation
|
|
- [ ] Tests for calendar app compatibility
|
|
|
|
## Technical Notes
|
|
|
|
### Calendar Service
|
|
```php
|
|
<?php
|
|
|
|
namespace App\Services;
|
|
|
|
use App\Models\Consultation;
|
|
use Carbon\Carbon;
|
|
|
|
class CalendarService
|
|
{
|
|
public function generateIcs(Consultation $consultation): string
|
|
{
|
|
$user = $consultation->user;
|
|
$locale = $user->preferred_language ?? 'ar';
|
|
|
|
$startDateTime = Carbon::parse(
|
|
$consultation->scheduled_date->format('Y-m-d') . ' ' . $consultation->scheduled_time
|
|
);
|
|
$endDateTime = $startDateTime->copy()->addMinutes($consultation->duration);
|
|
|
|
$title = $locale === 'ar'
|
|
? 'استشارة مع مكتب ليبرا للمحاماة'
|
|
: 'Consultation with Libra Law Firm';
|
|
|
|
$description = $this->buildDescription($consultation, $locale);
|
|
$location = $this->getLocation($locale);
|
|
|
|
$uid = sprintf(
|
|
'consultation-%d@libra.ps',
|
|
$consultation->id
|
|
);
|
|
|
|
$ics = [
|
|
'BEGIN:VCALENDAR',
|
|
'VERSION:2.0',
|
|
'PRODID:-//Libra Law Firm//Consultation Booking//EN',
|
|
'CALSCALE:GREGORIAN',
|
|
'METHOD:REQUEST',
|
|
'BEGIN:VTIMEZONE',
|
|
'TZID:Asia/Jerusalem',
|
|
'BEGIN:STANDARD',
|
|
'DTSTART:19701025T020000',
|
|
'RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU',
|
|
'TZOFFSETFROM:+0300',
|
|
'TZOFFSETTO:+0200',
|
|
'END:STANDARD',
|
|
'BEGIN:DAYLIGHT',
|
|
'DTSTART:19700329T020000',
|
|
'RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1FR',
|
|
'TZOFFSETFROM:+0200',
|
|
'TZOFFSETTO:+0300',
|
|
'END:DAYLIGHT',
|
|
'END:VTIMEZONE',
|
|
'BEGIN:VEVENT',
|
|
'UID:' . $uid,
|
|
'DTSTAMP:' . gmdate('Ymd\THis\Z'),
|
|
'DTSTART;TZID=Asia/Jerusalem:' . $startDateTime->format('Ymd\THis'),
|
|
'DTEND;TZID=Asia/Jerusalem:' . $endDateTime->format('Ymd\THis'),
|
|
'SUMMARY:' . $this->escapeIcs($title),
|
|
'DESCRIPTION:' . $this->escapeIcs($description),
|
|
'LOCATION:' . $this->escapeIcs($location),
|
|
'STATUS:CONFIRMED',
|
|
'SEQUENCE:0',
|
|
'BEGIN:VALARM',
|
|
'TRIGGER:-PT1H',
|
|
'ACTION:DISPLAY',
|
|
'DESCRIPTION:Reminder',
|
|
'END:VALARM',
|
|
'END:VEVENT',
|
|
'END:VCALENDAR',
|
|
];
|
|
|
|
return implode("\r\n", $ics);
|
|
}
|
|
|
|
private function buildDescription(Consultation $consultation, string $locale): string
|
|
{
|
|
$lines = [];
|
|
|
|
if ($locale === 'ar') {
|
|
$lines[] = 'رقم الحجز: ' . $consultation->id;
|
|
$lines[] = 'نوع الاستشارة: ' . ($consultation->type === 'free' ? 'مجانية' : 'مدفوعة');
|
|
if ($consultation->type === 'paid') {
|
|
$lines[] = 'المبلغ: ' . number_format($consultation->payment_amount, 2) . ' شيكل';
|
|
}
|
|
$lines[] = '';
|
|
$lines[] = 'للاستفسارات:';
|
|
$lines[] = 'مكتب ليبرا للمحاماة';
|
|
$lines[] = 'libra.ps';
|
|
} else {
|
|
$lines[] = 'Booking Reference: ' . $consultation->id;
|
|
$lines[] = 'Consultation Type: ' . ucfirst($consultation->type);
|
|
if ($consultation->type === 'paid') {
|
|
$lines[] = 'Amount: ' . number_format($consultation->payment_amount, 2) . ' ILS';
|
|
}
|
|
$lines[] = '';
|
|
$lines[] = 'For inquiries:';
|
|
$lines[] = 'Libra Law Firm';
|
|
$lines[] = 'libra.ps';
|
|
}
|
|
|
|
return implode('\n', $lines);
|
|
}
|
|
|
|
private function getLocation(string $locale): string
|
|
{
|
|
// Configure in config/libra.php
|
|
return config('libra.office_address.' . $locale, 'Libra Law Firm');
|
|
}
|
|
|
|
private function escapeIcs(string $text): string
|
|
{
|
|
return str_replace(
|
|
[',', ';', '\\'],
|
|
['\,', '\;', '\\\\'],
|
|
$text
|
|
);
|
|
}
|
|
|
|
public function generateDownloadResponse(Consultation $consultation): \Symfony\Component\HttpFoundation\Response
|
|
{
|
|
$content = $this->generateIcs($consultation);
|
|
$filename = sprintf(
|
|
'consultation-%s.ics',
|
|
$consultation->scheduled_date->format('Y-m-d')
|
|
);
|
|
|
|
return response($content)
|
|
->header('Content-Type', 'text/calendar; charset=utf-8')
|
|
->header('Content-Disposition', 'attachment; filename="' . $filename . '"');
|
|
}
|
|
}
|
|
```
|
|
|
|
### Email Attachment
|
|
```php
|
|
// In BookingApproved notification
|
|
public function toMail(object $notifiable): MailMessage
|
|
{
|
|
$locale = $notifiable->preferred_language ?? 'ar';
|
|
|
|
return (new MailMessage)
|
|
->subject($this->getSubject($locale))
|
|
->markdown('emails.booking.approved.' . $locale, [
|
|
'consultation' => $this->consultation,
|
|
'paymentInstructions' => $this->paymentInstructions,
|
|
])
|
|
->attachData(
|
|
$this->icsContent,
|
|
'consultation.ics',
|
|
['mime' => 'text/calendar']
|
|
);
|
|
}
|
|
```
|
|
|
|
### Download Route
|
|
```php
|
|
// routes/web.php
|
|
Route::middleware(['auth'])->group(function () {
|
|
Route::get('/consultations/{consultation}/calendar', function (Consultation $consultation) {
|
|
// Verify user owns this consultation
|
|
abort_unless($consultation->user_id === auth()->id(), 403);
|
|
abort_unless($consultation->status === 'approved', 404);
|
|
|
|
return app(CalendarService::class)->generateDownloadResponse($consultation);
|
|
})->name('client.consultations.calendar');
|
|
});
|
|
```
|
|
|
|
### Client Dashboard Button
|
|
```blade
|
|
@if($consultation->status === 'approved')
|
|
<flux:button
|
|
size="sm"
|
|
href="{{ route('client.consultations.calendar', $consultation) }}"
|
|
>
|
|
<flux:icon name="calendar" class="w-4 h-4 me-1" />
|
|
{{ __('client.add_to_calendar') }}
|
|
</flux:button>
|
|
@endif
|
|
```
|
|
|
|
### Testing Calendar File
|
|
```php
|
|
use App\Services\CalendarService;
|
|
use App\Models\Consultation;
|
|
|
|
it('generates valid ics file', function () {
|
|
$consultation = Consultation::factory()->approved()->create([
|
|
'scheduled_date' => '2024-03-15',
|
|
'scheduled_time' => '10:00:00',
|
|
'duration' => 45,
|
|
]);
|
|
|
|
$service = new CalendarService();
|
|
$ics = $service->generateIcs($consultation);
|
|
|
|
expect($ics)
|
|
->toContain('BEGIN:VCALENDAR')
|
|
->toContain('BEGIN:VEVENT')
|
|
->toContain('DTSTART')
|
|
->toContain('DTEND')
|
|
->toContain('END:VCALENDAR');
|
|
});
|
|
|
|
it('includes correct duration', function () {
|
|
$consultation = Consultation::factory()->approved()->create([
|
|
'scheduled_date' => '2024-03-15',
|
|
'scheduled_time' => '10:00:00',
|
|
'duration' => 45,
|
|
]);
|
|
|
|
$service = new CalendarService();
|
|
$ics = $service->generateIcs($consultation);
|
|
|
|
// Start at 10:00, end at 10:45
|
|
expect($ics)
|
|
->toContain('DTSTART;TZID=Asia/Jerusalem:20240315T100000')
|
|
->toContain('DTEND;TZID=Asia/Jerusalem:20240315T104500');
|
|
});
|
|
```
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] .ics file generated on approval
|
|
- [ ] File follows iCalendar RFC 5545
|
|
- [ ] Works with Google Calendar
|
|
- [ ] Works with Apple Calendar
|
|
- [ ] Works with Microsoft Outlook
|
|
- [ ] Attached to approval email
|
|
- [ ] Downloadable from client dashboard
|
|
- [ ] Bilingual event details
|
|
- [ ] Includes 1-hour reminder
|
|
- [ ] Tests pass for generation
|
|
- [ ] Code formatted with Pint
|
|
|
|
## Dependencies
|
|
|
|
- **Story 3.5:** Booking approval (triggers generation)
|
|
- **Epic 8:** Email system (for attachment)
|
|
|
|
## Risk Assessment
|
|
|
|
- **Primary Risk:** Calendar app compatibility issues
|
|
- **Mitigation:** Test with multiple calendar apps, follow RFC strictly
|
|
- **Rollback:** Provide manual calendar details if .ics fails
|
|
|
|
## Estimation
|
|
|
|
**Complexity:** Medium
|
|
**Estimated Effort:** 3-4 hours
|