@famgia/omnify-laravel 0.0.87 → 0.0.89

package/stubs/ai-guides/cursor/laravel-testing.mdc.stub

@@ -0,0 +1,138 @@
+---
+description: "PEST testing rules - 正常系/異常系, naming conventions"
+globs: ["tests/**", "**/*Test.php"]
+alwaysApply: false
+---
+
+# Testing Rules (PEST)
+
+> **Agent:** Act as **@tester** agent
+> - Read `.claude/guides/laravel/testing.md` for full guide
+
+## How to Run Tests
+
+```bash
+# Run ALL tests (from project root - uses Docker wrapper)
+./artisan test
+
+# Run specific test file
+./artisan test --filter=UserControllerTest
+
+# Run specific test method
+./artisan test --filter="creates user with valid data"
+
+# Run with coverage (if xdebug installed)
+./artisan test --coverage
+```
+
+> **Note:** The root `./artisan` script is a wrapper that runs commands inside Docker container.
+
+## Testing Process
+
+1. **Before writing tests:**
+   - Read the Controller to understand endpoints
+   - Read the Request to understand validation rules
+   - Read the Resource to understand response structure
+
+2. **Write tests covering:**
+   - 正常系 (Normal cases) - success scenarios
+   - 異常系 (Abnormal cases) - failure scenarios
+
+3. **Run tests to verify:**
+   ```bash
+   cd backend && ./artisan test
+   ```
+
+4. **All tests must pass before committing**
+
+## Critical Rules
+
+1. **PEST Syntax** - Use `describe()` + `it()`, not PHPUnit
+2. **正常系 + 異常系** - Cover both success and failure
+3. **Naming** - Use `正常:` and `異常:` prefixes
+4. **Coverage** - All endpoints, all validation rules
+5. **RefreshDatabase** - MUST use for SQLite in-memory
+
+## Database Trait - IMPORTANT
+
+```php
+// ✅ CORRECT - Use RefreshDatabase for SQLite in-memory
+use Illuminate\Foundation\Testing\RefreshDatabase;
+uses(RefreshDatabase::class);
+
+// ❌ WRONG - DatabaseTransactions doesn't run migrations
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+uses(DatabaseTransactions::class);  // Will fail with "no such table"
+```
+
+| Trait                  | When to Use                       | Notes                           |
+| ---------------------- | --------------------------------- | ------------------------------- |
+| `RefreshDatabase`      | SQLite in-memory (default)        | Runs migrations, then truncates |
+| `DatabaseTransactions` | MySQL/PostgreSQL with existing DB | Only wraps in transaction       |
+
+## Test Naming
+
+```php
+// 正常系 (Normal) - success behavior
+it('正常: returns paginated users')
+it('正常: creates user with valid data')
+it('正常: deletes user')
+
+// 異常系 (Abnormal) - failure behavior
+it('異常: fails to create user with missing email')
+it('異常: fails to create user with invalid kana format')
+it('異常: returns 404 when user not found')
+it('異常: returns 401 when not authenticated')
+```
+
+## Coverage Matrix
+
+| Endpoint | 正常系             | 異常系                |
+| -------- | ------------------ | --------------------- |
+| index    | List, filter, sort | Empty, invalid params |
+| store    | Creates → 201      | 422 (each field)      |
+| show     | Returns → 200      | 404                   |
+| update   | Updates → 200      | 404, 422              |
+| destroy  | Deletes → 204      | 404                   |
+
+## Template
+
+```php
+describe('POST /api/users', function () {
+    // 正常系
+    it('正常: creates user with valid data', function () {
+        $response = $this->postJson('/api/users', validUserData());
+        
+        $response->assertCreated();
+        $this->assertDatabaseHas('users', ['email' => 'test@example.com']);
+    });
+    
+    // 異常系 - Required fields
+    it('異常: fails to create user with missing email', function () {
+        $data = validUserData();
+        unset($data['email']);
+        
+        $this->postJson('/api/users', $data)
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors(['email']);
+    });
+    
+    // 異常系 - Format validation
+    it('異常: fails to create user with invalid email format', function () {
+        $this->postJson('/api/users', validUserData(['email' => 'invalid']))
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors(['email']);
+    });
+});
+```
+
+## Japanese Field Tests
+
+```php
+it('異常: fails with hiragana in kana field', function () {
+    $this->postJson('/api/users', validUserData([
+        'name_kana_lastname' => 'たなか'  // hiragana - should fail
+    ]))->assertUnprocessable()
+       ->assertJsonValidationErrors(['name_kana_lastname']);
+});
+```

package/stubs/ai-guides/cursor/laravel.mdc.stub

@@ -0,0 +1,82 @@
+---
+description: "Laravel backend development rules - security, performance, patterns"
+globs: ["{{LARAVEL_BASE}}/**"]
+alwaysApply: false
+---
+
+# Laravel Rules
+
+> **Documentation:** `.claude/guides/laravel/`
+> **Specific Rules:** See also `laravel-controller.mdc`, `laravel-resource.mdc`, `laravel-request.mdc`, `laravel-testing.mdc`
+
+## Critical Rules
+
+1. **Thin Controller** - Validate → Delegate → Respond (see `laravel-controller.mdc`)
+2. **Schema-First** - Use Omnify schemas, don't create migrations manually
+3. **Security** - Always use `$request->validated()`, never `$request->all()`
+4. **Performance** - Use `with()` for relations, `paginate()` for lists
+5. **Dates** - Store UTC, return `->toISOString()`
+6. **Testing** - Write 正常系 + 異常系 tests (see `laravel-testing.mdc`)
+7. **Imports** - Always `use` and short class names, never FQCN inline
+
+## File-Specific Rules
+
+| File Type  | Rule File               | Key Focus                    |
+| ---------- | ----------------------- | ---------------------------- |
+| Controller | `laravel-controller.mdc` | Thin, Query Builder, OpenAPI |
+| Resource   | `laravel-resource.mdc`   | Schema matches output        |
+| Request    | `laravel-request.mdc`    | Schema matches validation    |
+| Test       | `laravel-testing.mdc`    | 正常系 + 異常系 coverage     |
+
+## Security Checklist
+
+- [ ] `$fillable` defined in Model
+- [ ] `$hidden` for sensitive fields
+- [ ] `$request->validated()` not `$request->all()`
+- [ ] No raw SQL with user input
+- [ ] `with()` for eager loading
+- [ ] `whenLoaded()` in Resources
+- [ ] `paginate()` for list endpoints
+
+## When to Use What
+
+| Scenario         | Solution           |
+| ---------------- | ------------------ |
+| Simple CRUD      | Controller + Model |
+| Multi-step logic | Service            |
+| Reusable action  | Action class       |
+| Async task       | Job                |
+
+## Pre-Edit Checklist
+
+**BEFORE editing any file, MUST:**
+
+1. **Read the file first** - Check existing imports, patterns, style
+2. **Check imports** - Add `use` if class not imported
+3. **Follow existing style** - Match indentation, naming, patterns
+4. **Never use FQCN inline** - Always import first
+
+## Imports Rule
+
+```php
+// ❌ WRONG: Inline FQCN
+public function store(): \Illuminate\Http\JsonResponse
+
+// ✅ CORRECT: Import and use short name
+use Illuminate\Http\JsonResponse;
+public function store(): JsonResponse
+```
+
+## Don't Over-Engineer
+
+| ❌ DON'T                             | ✅ DO                      |
+| ----------------------------------- | ------------------------- |
+| Add workaround to hide bugs         | Fix root cause or report  |
+| Repository for simple CRUD          | Use Eloquent directly     |
+| Service that just wraps Model       | Controller + Model        |
+| Interface with 1 implementation     | Concrete class            |
+| Manual 404 check with route binding | Trust framework           |
+| "Improve" unrelated code            | Change only what's needed |
+| Build for future "just in case"     | YAGNI - build when needed |
+
+**Full examples:** `.claude/guides/laravel/architecture.md`

package/stubs/ai-guides/laravel/README.md.stub

@@ -0,0 +1,59 @@
+# Backend Guides
+
+> Laravel 12, PHP 8.4, MySQL 8
+
+## Quick Navigation
+
+| Guide                                | Description                                   |
+| ------------------------------------ | --------------------------------------------- |
+| [architecture.md](./architecture.md) | Design philosophy, when to use Service/Action |
+| [controller.md](./controller.md)     | Thin controller pattern, CRUD template        |
+| [request.md](./request.md)           | Form validation, FormRequest                  |
+| [resource.md](./resource.md)         | API response format, dates                    |
+| [service.md](./service.md)           | When & how to use services                    |
+| [testing.md](./testing.md)           | PEST, 正常系/異常系                           |
+| [openapi.md](./openapi.md)           | Swagger documentation                         |
+| [datetime.md](./datetime.md)         | Carbon, UTC handling                          |
+
+## Related
+
+| Topic                    | Location                                                    |
+| ------------------------ | ----------------------------------------------------------- |
+| **Security rules**       | [/rules/security.md](../../rules/security.md)               |
+| **Performance rules**    | [/rules/performance.md](../../rules/performance.md)         |
+| **Naming conventions**   | [/rules/naming.md](../../rules/naming.md)                   |
+| **Checklist**            | [/checklists/backend.md](../../checklists/backend.md)       |
+| **New feature workflow** | [/workflows/new-feature.md](../../workflows/new-feature.md) |
+
+## Quick Patterns
+
+### Thin Controller
+
+```php
+public function store(UserStoreRequest $request): UserResource
+{
+    return new UserResource(User::create($request->validated()));
+}
+```
+
+### Resource with Dates
+
+```php
+public function toArray($request): array
+{
+    return [
+        'id' => $this->id,
+        'name' => $this->name,
+        'created_at' => $this->created_at?->toISOString(),
+    ];
+}
+```
+
+### When to Use What
+
+| Question                   | Answer          |
+| -------------------------- | --------------- |
+| Simple CRUD?               | Controller only |
+| Multi-step business logic? | Service         |
+| Single reusable action?    | Action class    |
+| Async task?                | Job             |

package/stubs/ai-guides/laravel/architecture.md.stub

@@ -0,0 +1,424 @@
+# Design Philosophy
+
+> This document explains the architectural decisions and design principles for this Laravel backend.
+
+## Architecture: Thin Controller + Service (When Needed)
+
+```mermaid
+flowchart TD
+    subgraph HTTP["HTTP Layer"]
+        Route[Route] --> Middleware --> FormRequest
+    end
+
+    FormRequest --> Controller
+
+    subgraph Controller["Controller Layer (Thin)"]
+        C[Orchestrate request → response]
+    end
+
+    Controller --> Model
+    Controller --> Service
+
+    subgraph Data["Data Layer"]
+        Model["Model (Simple CRUD)"]
+        Service["Service (Complex ops)"]
+    end
+
+    Model --> Resource
+    Service --> Resource
+
+    subgraph Output["Response Layer"]
+        Resource[Resource - JSON format]
+    end
+```
+
+| Layer      | Responsibility                 | Rules                               |
+| ---------- | ------------------------------ | ----------------------------------- |
+| HTTP       | Routing, auth, validation      | No business logic                   |
+| Controller | Orchestrate request → response | Delegate to Model or Service        |
+| Model      | Simple CRUD                    | `User::create()`, `$user->update()` |
+| Service    | Complex operations             | `OrderService`, `PaymentService`    |
+| Resource   | Format JSON response           | Dates to ISO 8601                   |
+
+---
+
+## Core Principle: Don't Over-Engineer
+
+### ❌ BAD: Over-Engineering Simple CRUD
+
+```php
+// DON'T create all these for simple CRUD:
+app/
+├── Repositories/
+│   ├── UserRepositoryInterface.php
+│   └── UserRepository.php
+├── Services/
+│   └── UserService.php
+├── DTOs/
+│   └── UserDTO.php
+└── Contracts/
+    └── UserServiceInterface.php
+
+// Controller calls Service calls Repository calls Model
+// 4 layers for a simple User::create()!
+```
+
+### ✅ GOOD: Simple CRUD = Controller + Model
+
+```php
+// Simple CRUD - Controller is enough
+class UserController extends Controller
+{
+    public function store(UserStoreRequest $request): UserResource
+    {
+        $user = User::create($request->validated());
+        return new UserResource($user);
+    }
+}
+
+// That's it! No extra layers needed.
+```
+
+---
+
+## When to Add Each Layer
+
+### Layer Decision Matrix
+
+| Scenario                  | Controller | Service | Action | Job |
+| ------------------------- | ---------- | ------- | ------ | --- |
+| Simple CRUD               | ✅          | ❌       | ❌      | ❌   |
+| CRUD + send email         | ✅          | ❌       | ❌      | ✅   |
+| Multi-step business logic | ✅          | ✅       | ❌      | ❌   |
+| Reusable single operation | ✅          | ❌       | ✅      | ❌   |
+| Long-running task         | ✅          | ❌       | ❌      | ✅   |
+
+### Detailed Examples
+
+#### 1. Simple CRUD → Controller Only
+
+```php
+// ✅ Direct model operations
+public function store(UserStoreRequest $request): UserResource
+{
+    $user = User::create($request->validated());
+    return new UserResource($user);
+}
+
+public function update(UserUpdateRequest $request, User $user): UserResource
+{
+    $user->update($request->validated());
+    return new UserResource($user);
+}
+```
+
+#### 2. CRUD + Side Effects → Controller + Job/Event
+
+```php
+// ✅ Use Job for async operations
+public function store(UserStoreRequest $request): UserResource
+{
+    $user = User::create($request->validated());
+    
+    SendWelcomeEmail::dispatch($user);  // Async job
+    event(new UserRegistered($user));   // Or event
+    
+    return new UserResource($user);
+}
+```
+
+#### 3. Complex Business Logic → Service
+
+```php
+// ✅ Use Service for multi-step operations
+class OrderController extends Controller
+{
+    public function __construct(
+        private OrderService $orderService
+    ) {}
+
+    public function store(OrderRequest $request): OrderResource
+    {
+        $order = $this->orderService->checkout(
+            cart: Cart::find($request->cart_id),
+            user: $request->user(),
+            paymentMethod: $request->payment_method
+        );
+
+        return new OrderResource($order);
+    }
+}
+
+// Service handles complex logic
+class OrderService
+{
+    public function checkout(Cart $cart, User $user, string $paymentMethod): Order
+    {
+        // 1. Validate cart items in stock
+        $this->validateInventory($cart);
+        
+        // 2. Calculate totals
+        $totals = $this->calculateTotals($cart);
+        
+        // 3. Process payment
+        $payment = $this->paymentService->charge($user, $totals, $paymentMethod);
+        
+        // 4. Create order
+        $order = Order::create([...]);
+        
+        // 5. Update inventory
+        $this->updateInventory($cart);
+        
+        // 6. Send notifications
+        event(new OrderPlaced($order));
+        
+        return $order;
+    }
+}
+```
+
+#### 4. Single Reusable Operation → Action
+
+```php
+// ✅ Use Action for reusable single-purpose operations
+class CreateInvoiceAction
+{
+    public function execute(Order $order): Invoice
+    {
+        $invoice = Invoice::create([
+            'order_id' => $order->id,
+            'number' => $this->generateNumber(),
+            'total' => $order->total,
+        ]);
+        
+        GenerateInvoicePdf::dispatch($invoice);
+        
+        return $invoice;
+    }
+}
+
+// Used in multiple places
+class OrderController
+{
+    public function store(OrderRequest $request, CreateInvoiceAction $createInvoice)
+    {
+        $order = Order::create($request->validated());
+        $createInvoice->execute($order);
+        return new OrderResource($order);
+    }
+}
+
+class RecurringBillingJob
+{
+    public function handle(CreateInvoiceAction $createInvoice)
+    {
+        foreach ($this->getSubscriptions() as $subscription) {
+            $order = $subscription->createRenewalOrder();
+            $createInvoice->execute($order);
+        }
+    }
+}
+```
+
+---
+
+## Why NOT Repository Pattern?
+
+### Problem: Eloquent IS Already a Repository
+
+```php
+// Eloquent provides repository-like methods
+User::find($id);
+User::where('email', $email)->first();
+User::create($data);
+$user->update($data);
+$user->delete();
+
+// Adding Repository layer = duplicate abstraction
+interface UserRepositoryInterface {
+    public function find(int $id): ?User;
+    public function findByEmail(string $email): ?User;
+    public function create(array $data): User;
+    // ... same methods as Eloquent!
+}
+```
+
+### When Repository MIGHT Make Sense
+
+```php
+// Only if you genuinely need to swap data sources
+// (rare in real projects)
+
+interface ProductCatalogInterface {
+    public function search(string $query): Collection;
+}
+
+class EloquentProductCatalog implements ProductCatalogInterface { ... }
+class ElasticsearchProductCatalog implements ProductCatalogInterface { ... }
+```
+
+**Reality**: 99% of Laravel projects never swap databases. Don't add abstraction for hypothetical future needs.
+
+---
+
+## Design Principles
+
+### 1. YAGNI (You Aren't Gonna Need It)
+
+```php
+// ❌ DON'T: Create interfaces "just in case"
+interface UserServiceInterface { ... }
+class UserService implements UserServiceInterface { ... }
+
+// ✅ DO: Add abstraction only when needed
+class UserService { ... }  // Concrete class is fine
+```
+
+### 2. Single Responsibility
+
+```php
+// ❌ DON'T: Fat controller
+class UserController
+{
+    public function store(Request $request)
+    {
+        $validated = $request->validate([...]);  // Validation in controller
+        $user = User::create($validated);
+        Mail::send(...);                          // Email logic in controller
+        $this->calculatePoints($user);           // Business logic in controller
+        return response()->json($user);          // Manual JSON formatting
+    }
+}
+
+// ✅ DO: Each layer has one job
+class UserController
+{
+    public function store(UserStoreRequest $request): UserResource  // Type-hinted
+    {
+        $user = User::create($request->validated());  // FormRequest validates
+        event(new UserRegistered($user));             // Event handles side effects
+        return new UserResource($user);               // Resource formats output
+    }
+}
+```
+
+### 3. Explicit Over Implicit
+
+```php
+// ❌ DON'T: Magic methods, hidden behavior
+class User extends Model
+{
+    public function __call($method, $args) { ... }  // Magic
+}
+
+// ✅ DO: Clear, readable code
+class User extends Model
+{
+    public function orders(): HasMany { ... }       // Explicit relationship
+    public function scopeActive($query) { ... }    // Clear scope
+}
+```
+
+### 4. Fail Fast
+
+```php
+// ✅ Validate early with FormRequest
+class OrderStoreRequest extends FormRequest
+{
+    public function rules(): array
+    {
+        return [
+            'cart_id' => ['required', 'exists:carts,id'],
+            'payment_method' => ['required', 'in:card,bank'],
+        ];
+    }
+}
+
+// ✅ Throw exceptions for invalid states
+class OrderService
+{
+    public function checkout(Cart $cart): Order
+    {
+        if ($cart->items->isEmpty()) {
+            throw new EmptyCartException();
+        }
+        
+        if (!$this->hasInventory($cart)) {
+            throw new InsufficientInventoryException();
+        }
+        
+        // ... proceed with valid cart
+    }
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. ❌ Repository for Everything
+
+```php
+// DON'T
+class UserRepository {
+    public function all() { return User::all(); }
+    public function find($id) { return User::find($id); }
+    // Pointless wrapper around Eloquent
+}
+```
+
+### 2. ❌ Service for Simple CRUD
+
+```php
+// DON'T
+class UserService {
+    public function create(array $data) {
+        return User::create($data);  // Just wrapping model method
+    }
+}
+```
+
+### 3. ❌ DTOs for Request Data
+
+```php
+// DON'T
+class UserDTO {
+    public function __construct(
+        public string $name,
+        public string $email,
+    ) {}
+}
+
+// FormRequest already does this!
+$request->validated();  // Returns validated array
+```
+
+### 4. ❌ Interfaces Without Implementations
+
+```php
+// DON'T create interface for single implementation
+interface UserServiceInterface { ... }
+class UserService implements UserServiceInterface { ... }
+
+// DO use interface only when you have multiple implementations
+interface PaymentGatewayInterface { ... }
+class StripePaymentGateway implements PaymentGatewayInterface { ... }
+class PayPalPaymentGateway implements PaymentGatewayInterface { ... }
+```
+
+---
+
+## Summary
+
+| Principle           | Guideline                         |
+| ------------------- | --------------------------------- |
+| **Simple CRUD**     | Controller + Model + Resource     |
+| **Side effects**    | Events, Jobs, Observers           |
+| **Complex logic**   | Service (only when truly complex) |
+| **Reusable action** | Action class                      |
+| **Validation**      | FormRequest (always)              |
+| **Response format** | Resource (always)                 |
+| **Repository**      | ❌ Don't use (Eloquent is enough)  |
+| **Interfaces**      | Only for multiple implementations |
+
+**Golden Rule**: Start simple. Add layers only when complexity demands it.