# Story 4.1: Timeline Creation

## Epic Reference
**Epic 4:** Case Timeline System

## User Story
As an **admin**,
I want **to create case timelines for clients**,
So that **I can track and communicate progress on their legal matters**.

## Story Context

### Existing System Integration
- **Integrates with:** timelines table, users table
- **Technology:** Livewire Volt, Flux UI
- **Follows pattern:** Admin CRUD pattern
- **Touch points:** User relationship, client dashboard

## Acceptance Criteria

### Timeline Creation Form
- [ ] Select client (search by name/email)
- [ ] Case name/title (required)
- [ ] Case reference number (optional, unique if provided)
- [ ] Initial notes (optional)

### Behavior
- [ ] Timeline assigned to selected client
- [ ] Creation date automatically recorded
- [ ] Status defaults to 'active'
- [ ] Can create multiple timelines per client
- [ ] Confirmation message on successful creation
- [ ] Timeline immediately visible to client

### Validation
- [ ] Case name required
- [ ] Case reference unique if provided
- [ ] Client must exist

### Quality Requirements
- [ ] Audit log entry created
- [ ] Bilingual labels and messages
- [ ] Tests for creation flow

## Technical Notes

### Database Schema
```php
// timelines table
Schema::create('timelines', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('case_name');
    $table->string('case_reference')->nullable()->unique();
    $table->enum('status', ['active', 'archived'])->default('active');
    $table->timestamps();
});
```

### Volt Component
```php
<?php

use App\Models\{Timeline, User};
use Livewire\Volt\Component;

new class extends Component {
    public string $search = '';
    public ?int $selectedUserId = null;
    public ?User $selectedUser = null;
    public string $caseName = '';
    public string $caseReference = '';
    public string $initialNotes = '';

    public function selectUser(int $userId): void
    {
        $this->selectedUserId = $userId;
        $this->selectedUser = User::find($userId);
    }

    public function create(): void
    {
        $this->validate([
            'selectedUserId' => ['required', 'exists:users,id'],
            'caseName' => ['required', 'string', 'max:255'],
            'caseReference' => ['nullable', 'string', 'max:50', 'unique:timelines,case_reference'],
        ]);

        $timeline = Timeline::create([
            'user_id' => $this->selectedUserId,
            'case_name' => $this->caseName,
            'case_reference' => $this->caseReference ?: null,
            'status' => 'active',
        ]);

        // Add initial notes as first update if provided
        if ($this->initialNotes) {
            $timeline->updates()->create([
                'admin_id' => auth()->id(),
                'update_text' => $this->initialNotes,
            ]);
        }

        AdminLog::create([
            'admin_id' => auth()->id(),
            'action_type' => 'create',
            'target_type' => 'timeline',
            'target_id' => $timeline->id,
            'new_values' => $timeline->toArray(),
            'ip_address' => request()->ip(),
        ]);

        session()->flash('success', __('messages.timeline_created'));
        $this->redirect(route('admin.timelines.show', $timeline));
    }
};
```

## Definition of Done

- [ ] Can search and select client
- [ ] Can enter case name and reference
- [ ] Timeline created with correct data
- [ ] Initial notes saved as first update
- [ ] Unique reference validation works
- [ ] Client can view timeline immediately
- [ ] Audit log created
- [ ] Tests pass
- [ ] Code formatted with Pint

## Dependencies

- **Epic 1:** Database schema, authentication
- **Epic 2:** User accounts

## Estimation

**Complexity:** Low-Medium
**Estimated Effort:** 2-3 hours