generated sotries

2025-12-20 21:04:23 +02:00
parent d889b24f12
commit 8f95089814
65 changed files with 9501 additions and 0 deletions
@@ -0,0 +1,187 @@
+# Story 2.2: Company/Corporate Client Account Management
+
+## Epic Reference
+**Epic 2:** User Management System
+
+## User Story
+As an **admin**,
+I want **to create, view, edit, and manage company/corporate client accounts**,
+So that **I can serve corporate clients with their unique data requirements**.
+
+## Story Context
+
+### Existing System Integration
+- **Integrates with:** Users table, potential contact_persons table
+- **Technology:** Livewire Volt, Flux UI forms
+- **Follows pattern:** Same CRUD pattern as individual clients
+- **Touch points:** User model, admin dashboard
+
+## Acceptance Criteria
+
+### Create Company Client
+- [ ] Form with required fields:
+  - Company Name (required)
+  - Company Registration Number (required, unique)
+  - Contact Person Name (required)
+  - Contact Person ID (required)
+  - Email Address (required, unique)
+  - Phone Number (required)
+  - Password (admin-set, required)
+  - Preferred Language (Arabic/English dropdown)
+- [ ] Validation for all required fields
+- [ ] Duplicate email/registration number prevention
+- [ ] Success message on creation
+
+### Multiple Contact Persons (Optional Enhancement)
+- [ ] Support unlimited contact persons per company
+- [ ] Each contact: Name, ID, Phone, Email
+- [ ] Primary contact indicator
+- [ ] Add/remove contacts dynamically
+
+### List View
+- [ ] Display all company clients (user_type = 'company')
+- [ ] Columns: Company Name, Contact Person, Email, Reg #, Status, Created Date
+- [ ] Pagination (10/25/50 per page)
+- [ ] Default sort by created date
+
+### Search & Filter
+- [ ] Search by company name, email, or registration number
+- [ ] Filter by status (active/deactivated/all)
+- [ ] Real-time search with debounce
+
+### Edit Company
+- [ ] Edit all company information
+- [ ] Update contact person details
+- [ ] Validation same as create
+- [ ] Success message on update
+
+### View Company Profile
+- [ ] Display all company information
+- [ ] List all contact persons
+- [ ] Show consultation history summary
+- [ ] Show timeline history summary
+
+### Quality Requirements
+- [ ] Bilingual form labels and messages
+- [ ] Proper form validation
+- [ ] Audit log entries for all operations
+- [ ] Tests for CRUD operations
+
+## Technical Notes
+
+### User Model Scope
+```php
+public function scopeCompany($query)
+{
+    return $query->where('user_type', 'company');
+}
+```
+
+### Database Fields for Company
+```
+users table:
+  - company_name (nullable, required for company type)
+  - company_registration (nullable, unique when not null)
+  - contact_person_name (nullable, required for company)
+  - contact_person_id (nullable, required for company)
+```
+
+### Alternative: Separate Contact Persons Table
+```php
+// contact_persons migration
+Schema::create('contact_persons', function (Blueprint $table) {
+    $table->id();
+    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+    $table->string('name');
+    $table->string('national_id');
+    $table->string('phone')->nullable();
+    $table->string('email')->nullable();
+    $table->boolean('is_primary')->default(false);
+    $table->timestamps();
+});
+```
+
+### Validation Rules
+```php
+public function rules(): array
+{
+    return [
+        'company_name' => ['required', 'string', 'max:255'],
+        'company_registration' => ['required', 'string', 'unique:users,company_registration'],
+        'contact_person_name' => ['required', 'string', 'max:255'],
+        'contact_person_id' => ['required', 'string'],
+        'email' => ['required', 'email', 'unique:users,email'],
+        'phone' => ['required', 'string'],
+        'password' => ['required', 'string', 'min:8'],
+        'preferred_language' => ['required', 'in:ar,en'],
+    ];
+}
+```
+
+### Volt Component for Create
+```php
+<?php
+
+use App\Models\User;
+use Livewire\Volt\Component;
+use Illuminate\Support\Facades\Hash;
+
+new class extends Component {
+    public string $company_name = '';
+    public string $company_registration = '';
+    public string $contact_person_name = '';
+    public string $contact_person_id = '';
+    public string $email = '';
+    public string $phone = '';
+    public string $password = '';
+    public string $preferred_language = 'ar';
+
+    public function create(): void
+    {
+        $validated = $this->validate();
+
+        $user = User::create([
+            ...$validated,
+            'user_type' => 'company',
+            'name' => $this->company_name, // For display purposes
+            'password' => Hash::make($this->password),
+            'status' => 'active',
+        ]);
+
+        // Log action
+        // Send welcome email
+
+        session()->flash('success', __('messages.company_created'));
+        $this->redirect(route('admin.users.index'));
+    }
+};
+```
+
+## Definition of Done
+
+- [ ] Create company client form works
+- [ ] List view displays all company clients
+- [ ] Search and filter functional
+- [ ] Edit company works with validation
+- [ ] View profile shows complete information
+- [ ] Duplicate prevention works
+- [ ] Audit logging implemented
+- [ ] Bilingual support complete
+- [ ] Tests pass for all CRUD operations
+- [ ] Code formatted with Pint
+
+## Dependencies
+
+- **Epic 1:** Authentication system, database schema
+- **Story 2.1:** Same CRUD patterns
+
+## Risk Assessment
+
+- **Primary Risk:** Complex contact persons relationship
+- **Mitigation:** Start simple (single contact), enhance later if needed
+- **Rollback:** Use simple fields on users table
+
+## Estimation
+
+**Complexity:** Medium
+**Estimated Effort:** 4-5 hours