@famgia/omnify-laravel 0.0.87 → 0.0.89

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

@@ -0,0 +1,391 @@
+---
+description: "Controller development rules - thin controller, query builder, OpenAPI"
+globs: ["{{LARAVEL_BASE}}/Http/Controllers/**"]
+alwaysApply: false
+---
+
+# Controller Rules
+
+## Golden Rule: Thin Controller
+
+```php
+// ✅ PERFECT
+public function store(UserStoreRequest $request): UserResource
+{
+    return new UserResource(User::create($request->validated()));
+}
+
+// ❌ BAD: Fat controller with logic
+public function store(Request $request)
+{
+    $validated = $request->validate([...]); // Use FormRequest!
+    // 50 lines of business logic... // Use Service!
+}
+```
+
+## Index Method - Query Builder Template
+
+```php
+use Spatie\QueryBuilder\AllowedFilter;
+use Spatie\QueryBuilder\QueryBuilder;
+
+public function index(): AnonymousResourceCollection
+{
+    $users = QueryBuilder::for(User::class)
+        ->allowedFilters([
+            AllowedFilter::callback('search', function ($query, $value) {
+                $query->where(function ($q) use ($value) {
+                    $q->where('name', 'like', "%{$value}%")
+                      ->orWhere('email', 'like', "%{$value}%");
+                });
+            }),
+        ])
+        ->allowedSorts(['id', 'name', 'email', 'created_at'])
+        ->defaultSort('-id')
+        ->paginate(request()->input('per_page', 10));
+
+    return UserResource::collection($users);
+}
+```
+
+## OpenAPI - Schema MUST Match Code
+
+Frontend needs exact response/request structure. Always verify against actual code.
+
+### Golden Rule: Verify Before Writing OpenAPI
+
+1. **Response** → Check `*Resource.php` schema  
+2. **Request** → Check `*Request.php` schema  
+3. **Parameters** → Check `allowedFilters()` / `allowedSorts()`
+
+### Schema Location
+
+| Type                     | Define At                | Ref In Controller                       |
+| ------------------------ | ------------------------ | --------------------------------------- |
+| Response                 | `*Resource.php`          | `#/components/schemas/User`             |
+| Request body             | `*Request.php`           | `#/components/schemas/UserStoreRequest` |
+| Pagination               | `Schemas.php`            | `#/components/schemas/PaginationMeta`   |
+| Common params            | `Schemas.php`            | `#/components/parameters/QueryPage`     |
+| Resource-specific params | **Inline in Controller** | N/A                                     |
+
+### Common refs from `Schemas.php`
+
+```php
+// Parameters
+new OA\Parameter(ref: '#/components/parameters/QueryPage'),
+new OA\Parameter(ref: '#/components/parameters/QueryPerPage'),
+new OA\Parameter(ref: '#/components/parameters/PathId'),
+
+// Responses
+new OA\Response(ref: '#/components/responses/ValidationError', response: 422),
+new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+new OA\Response(ref: '#/components/responses/NoContent', response: 204),
+
+// Pagination
+new OA\Property(property: 'links', ref: '#/components/schemas/PaginationLinks'),
+new OA\Property(property: 'meta', ref: '#/components/schemas/PaginationMeta'),
+```
+
+### Filter & Sort - MUST Document Specifically
+
+`filter` and `sort` differ per resource → Write inline with specific details.
+
+#### Filter Types (Spatie Query Builder)
+
+| Type              | Code                                       | OpenAPI Description        | Example                 |
+| ----------------- | ------------------------------------------ | -------------------------- | ----------------------- |
+| Callback (search) | `AllowedFilter::callback('search', fn...)` | List all searchable fields | `filter[search]=田中`   |
+| Exact             | `AllowedFilter::exact('status')`           | Exact match                | `filter[status]=active` |
+| Partial           | `AllowedFilter::partial('name')`           | LIKE %value%               | `filter[name]=田中`     |
+| Scope             | `AllowedFilter::scope('active')`           | Model scope                | `filter[active]=1`      |
+
+#### Filter Documentation Template
+
+```php
+// CODE: allowedFilters() configuration
+->allowedFilters([
+    AllowedFilter::callback('search', function ($query, $value) {
+        $query->where(function ($q) use ($value) {
+            $q->where('name_lastname', 'like', "%{$value}%")
+              ->orWhere('name_firstname', 'like', "%{$value}%")
+              ->orWhere('name_kana_lastname', 'like', "%{$value}%")
+              ->orWhere('name_kana_firstname', 'like', "%{$value}%")
+              ->orWhere('email', 'like', "%{$value}%");
+        });
+    }),
+    AllowedFilter::exact('status'),
+])
+
+// OPENAPI: Document EACH filter with specific description
+new OA\Parameter(
+    name: 'filter[search]',
+    in: 'query',
+    description: 'Partial match on: name_lastname, name_firstname, name_kana_lastname, name_kana_firstname, email',
+    schema: new OA\Schema(type: 'string'),
+    example: '田中'
+),
+new OA\Parameter(
+    name: 'filter[status]',
+    in: 'query',
+    description: 'Exact match on status',
+    schema: new OA\Schema(type: 'string', enum: ['active', 'inactive']),
+    example: 'active'
+),
+```
+
+#### Sort Documentation Template
+
+```php
+// CODE: allowedSorts() + defaultSort()
+->allowedSorts(['id', 'name_lastname', 'name_firstname', 'email', 'created_at', 'updated_at'])
+->defaultSort('-id')
+
+// OPENAPI: enum MUST include both asc and desc for each field
+new OA\Parameter(
+    name: 'sort',
+    in: 'query',
+    description: 'Sort field. Prefix `-` for descending. Default: `-id`',
+    schema: new OA\Schema(
+        type: 'string',
+        enum: [
+            'id', '-id',
+            'name_lastname', '-name_lastname',
+            'name_firstname', '-name_firstname',
+            'email', '-email',
+            'created_at', '-created_at',
+            'updated_at', '-updated_at'
+        ]
+    ),
+    example: '-created_at'
+),
+```
+
+#### Checklist: Filter & Sort Documentation
+
+| Item                          | Check                                           |
+| ----------------------------- | ----------------------------------------------- |
+| Each `AllowedFilter`          | Has corresponding `filter[name]` parameter?     |
+| Callback filter               | Description lists ALL searchable fields?        |
+| Exact filter with enum values | `schema.enum` matches valid values?             |
+| `allowedSorts()`              | `sort.enum` includes both `field` and `-field`? |
+| `defaultSort()`               | Mentioned in `sort.description`?                |
+
+### OpenAPI Checklist per Action
+
+#### `index()` - List
+
+**Verify before writing:**
+1. `allowedFilters()` → Each filter has `filter[name]` param with specific description
+2. `allowedSorts()` → `sort.enum` includes all fields + `-field` versions
+3. `defaultSort()` → Mentioned in sort description
+4. Response → ref to Resource + PaginationLinks + PaginationMeta
+
+```php
+#[OA\Get(
+    parameters: [
+        // Each allowedFilter → specific param
+        new OA\Parameter(
+            name: 'filter[search]',
+            in: 'query',
+            description: 'Partial match on: name_lastname, name_firstname, email',  // ← List actual fields!
+            schema: new OA\Schema(type: 'string'),
+            example: '田中'
+        ),
+        // Pagination
+        new OA\Parameter(ref: '#/components/parameters/QueryPage'),
+        new OA\Parameter(ref: '#/components/parameters/QueryPerPage'),
+        // Sort with full enum
+        new OA\Parameter(
+            name: 'sort',
+            in: 'query',
+            description: 'Sort field. Prefix `-` for descending. Default: `-id`',  // ← Include default!
+            schema: new OA\Schema(
+                type: 'string',
+                enum: ['id', '-id', 'name', '-name', 'created_at', '-created_at']  // ← Match allowedSorts!
+            ),
+            example: '-created_at'
+        ),
+    ],
+    responses: [
+        new OA\Response(response: 200, content: new OA\JsonContent(
+            properties: [
+                new OA\Property(property: 'data', type: 'array', items: new OA\Items(ref: '#/components/schemas/User')),
+                new OA\Property(property: 'links', ref: '#/components/schemas/PaginationLinks'),
+                new OA\Property(property: 'meta', ref: '#/components/schemas/PaginationMeta'),
+            ]
+        )),
+    ]
+)]
+```
+
+#### `store()` - Create
+
+```php
+// 1. Request: ref to *StoreRequest schema
+// 2. Response: ref to Resource schema
+// 3. Errors: 422 ValidationError
+
+#[OA\Post(
+    requestBody: new OA\RequestBody(
+        required: true,
+        content: new OA\JsonContent(ref: '#/components/schemas/UserStoreRequest')  // ← Check UserStoreRequest.php
+    ),
+    responses: [
+        new OA\Response(response: 201, content: new OA\JsonContent(
+            properties: [new OA\Property(property: 'data', ref: '#/components/schemas/User')]
+        )),
+        new OA\Response(ref: '#/components/responses/ValidationError', response: 422),
+    ]
+)]
+```
+
+#### `show()` - Get Single
+
+```php
+// 1. Parameter: PathId
+// 2. Response: ref to Resource schema
+// 3. Errors: 404 NotFound
+
+#[OA\Get(
+    parameters: [new OA\Parameter(ref: '#/components/parameters/PathId')],
+    responses: [
+        new OA\Response(response: 200, content: new OA\JsonContent(
+            properties: [new OA\Property(property: 'data', ref: '#/components/schemas/User')]
+        )),
+        new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+    ]
+)]
+```
+
+#### `update()` - Update
+
+```php
+// 1. Parameter: PathId
+// 2. Request: ref to *UpdateRequest schema (NOT StoreRequest!)
+// 3. Response: ref to Resource schema
+// 4. Errors: 404, 422
+
+#[OA\Put(
+    parameters: [new OA\Parameter(ref: '#/components/parameters/PathId')],
+    requestBody: new OA\RequestBody(
+        content: new OA\JsonContent(ref: '#/components/schemas/UserUpdateRequest')  // ← Check UserUpdateRequest.php
+    ),
+    responses: [
+        new OA\Response(response: 200, content: ...),
+        new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+        new OA\Response(ref: '#/components/responses/ValidationError', response: 422),
+    ]
+)]
+```
+
+#### `destroy()` - Delete
+
+```php
+// 1. Parameter: PathId
+// 2. Response: 204 NoContent
+// 3. Errors: 404 NotFound
+
+#[OA\Delete(
+    parameters: [new OA\Parameter(ref: '#/components/parameters/PathId')],
+    responses: [
+        new OA\Response(ref: '#/components/responses/NoContent', response: 204),
+        new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+    ]
+)]
+```
+
+## Response Status Codes
+
+| Action  | Code | Return Type                   |
+| ------- | ---- | ----------------------------- |
+| index   | 200  | Collection                    |
+| store   | 201  | Resource + status             |
+| show    | 200  | Resource                      |
+| update  | 200  | Resource                      |
+| destroy | 204  | `response()->json(null, 204)` |
+
+## Imports - MUST use short names
+
+```php
+// ✅ CORRECT
+use Illuminate\Http\JsonResponse;
+use Spatie\QueryBuilder\QueryBuilder;
+
+public function store(): JsonResponse
+
+// ❌ WRONG - Never FQCN inline
+public function store(): \Illuminate\Http\JsonResponse
+```
+
+## Keep It Simple
+
+```php
+// ✅ DO
+->allowedFilters([
+    AllowedFilter::callback('search', fn($q, $v) => ...),
+])
+->allowedSorts(['id', 'name', 'created_at'])
+
+// ❌ DON'T over-engineer
+->allowedFilters([
+    AllowedFilter::exact('author.company.country'),  // Too nested!
+])
+```
+
+## Don't Mix Concepts
+
+| Concept          | Use For          | DON'T Use For        |
+| ---------------- | ---------------- | -------------------- |
+| `*StoreRequest`  | POST create      | GET list, PUT update |
+| `*UpdateRequest` | PUT/PATCH update | POST create          |
+| `*Resource`      | Response output  | Request input        |
+| `index()`        | List (no body)   | Create/Update        |
+| `store()`        | Create new       | Update existing      |
+| `update()`       | Update existing  | Create new           |
+
+```php
+// ❌ WRONG: Using StoreRequest for update
+public function update(UserStoreRequest $request) // WRONG!
+
+// ✅ CORRECT: Each action has its own Request
+public function store(UserStoreRequest $request)   // Create
+public function update(UserUpdateRequest $request) // Update
+```
+
+## After Coding Checklist
+
+### Code
+1. ✅ Run tests: `./artisan test --filter=ControllerTest`
+
+### OpenAPI (only if annotations changed)
+
+| Check           | Code               | OpenAPI                 | Match                                 |
+| --------------- | ------------------ | ----------------------- | ------------------------------------- |
+| Response        | `*Resource.php`    | `ref: User`             | Schema exists? Properties match?      |
+| Request         | `*Request.php`     | `ref: UserStoreRequest` | Schema exists? Required fields match? |
+| Filters         | `allowedFilters()` | `filter[name]` params   | Each filter documented?               |
+| Callback filter | Fields in callback | `description`           | All fields listed?                    |
+| Exact filter    | Valid values       | `schema.enum`           | Enum matches valid values?            |
+| Sort            | `allowedSorts()`   | `sort.enum`             | Includes `field` AND `-field`?        |
+| Default sort    | `defaultSort()`    | `sort.description`      | Default mentioned?                    |
+
+```bash
+# Generate and verify
+./artisan l5-swagger:generate
+
+# Check json output
+cat backend/storage/api-docs/api-docs.json | jq '.components.schemas.User'
+cat backend/storage/api-docs/api-docs.json | jq '.components.schemas.UserStoreRequest'
+```
+
+### Common Mistakes
+
+| Mistake                         | Fix                                                                       |
+| ------------------------------- | ------------------------------------------------------------------------- |
+| `ref: User` missing             | Add `#[OA\Schema]` to `UserResource.php`                                  |
+| `ref: UserStoreRequest` missing | Add `#[OA\Schema]` to `UserStoreRequest.php`                              |
+| sort enum incomplete            | Include BOTH `field` AND `-field` for each `allowedSorts()`               |
+| sort missing default            | Add "Default: `-id`" to sort description                                  |
+| filter description vague        | List ALL fields: "Partial match on: name_lastname, name_firstname, email" |
+| filter[status] no enum          | Add `enum: ['active', 'inactive']` for exact filters                      |
+| Using StoreRequest for update   | Use UpdateRequest for PUT/PATCH                                           |

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

@@ -0,0 +1,112 @@
+---
+description: "FormRequest rules - OpenAPI Schema must match validation rules"
+globs: ["{{LARAVEL_BASE}}/Http/Requests/**"]
+alwaysApply: false
+---
+
+# Request Rules
+
+## Golden Rule: Schema MUST Match Validation Rules
+
+OpenAPI Schema properties MUST match the actual `schemaRules()` fields.
+
+## Before Editing Request
+
+1. **Read `OmnifyBase/*RequestBase.php`** to see actual validation rules
+2. **Compare with `#[OA\Schema]`** properties
+3. **Ensure `required` array matches** required validation rules
+4. **Match constraints** (maxLength, minLength, format)
+
+## Checklist
+
+```php
+// Check OmnifyBase/*StoreRequestBase.php → schemaRules()
+return [
+    'name_lastname' => ['required', 'string', 'max:50'],
+    'name_firstname' => ['required', 'string', 'max:50'],
+    'email' => ['required', 'string', 'max:255', 'unique:users'],
+    'password' => ['required', 'string', 'max:255'],
+];
+
+// #[OA\Schema] MUST match
+#[OA\Schema(
+    schema: 'UserStoreRequest',
+    required: ['name_lastname', 'name_firstname', 'email', 'password'],  // ← Match 'required' rules
+    properties: [
+        new OA\Property(property: 'name_lastname', type: 'string', maxLength: 50),  // ← max:50
+        new OA\Property(property: 'name_firstname', type: 'string', maxLength: 50),
+        new OA\Property(property: 'email', type: 'string', format: 'email', maxLength: 255),
+        new OA\Property(property: 'password', type: 'string', format: 'password', maxLength: 255),
+    ]
+)]
+```
+
+## Mapping Validation Rules to OpenAPI
+
+| Laravel Rule | OpenAPI Property            |
+| ------------ | --------------------------- |
+| `required`   | Add to `required: []` array |
+| `max:50`     | `maxLength: 50`             |
+| `min:8`      | `minLength: 8`              |
+| `email`      | `format: 'email'`           |
+| `string`     | `type: 'string'`            |
+| `integer`    | `type: 'integer'`           |
+| `boolean`    | `type: 'boolean'`           |
+| `nullable`   | `nullable: true`            |
+
+## StoreRequest vs UpdateRequest
+
+| Type             | `required`          | Notes                  |
+| ---------------- | ------------------- | ---------------------- |
+| `*StoreRequest`  | All required fields | Creating new resource  |
+| `*UpdateRequest` | Empty or partial    | Partial update allowed |
+
+```php
+// StoreRequest - all fields required
+#[OA\Schema(
+    schema: 'UserStoreRequest',
+    required: ['name_lastname', 'name_firstname', 'email', 'password'],
+    ...
+)]
+
+// UpdateRequest - no required (partial update)
+#[OA\Schema(
+    schema: 'UserUpdateRequest',
+    // No 'required' array - all fields optional
+    properties: [...]
+)]
+```
+
+## Common Mistakes
+
+| Mistake                 | Fix                                  |
+| ----------------------- | ------------------------------------ |
+| Missing field in schema | Check *RequestBase.php schemaRules() |
+| Wrong maxLength         | Match `max:X` rule                   |
+| Missing required        | Check if rule has `required`         |
+| Extra field in schema   | Remove if not in rules               |
+
+## Custom Rules in Child Class
+
+If you override rules in the child Request class, update schema accordingly:
+
+```php
+// UserStoreRequest.php
+public function rules(): array
+{
+    return array_merge($this->schemaRules(), [
+        'email' => ['required', 'string', 'email', 'max:255', 'unique:users'],  // Added 'email' format
+        'password' => ['required', 'string', 'min:8', 'max:255'],  // Added min:8
+    ]);
+}
+
+// Update schema to match
+new OA\Property(property: 'email', type: 'string', format: 'email'),  // ← Added format
+new OA\Property(property: 'password', type: 'string', minLength: 8),  // ← Added minLength
+```
+
+## After Editing
+
+```bash
+./artisan l5-swagger:generate
+```

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

@@ -0,0 +1,73 @@
+---
+description: "Resource class rules - OpenAPI Schema must match actual output"
+globs: ["{{LARAVEL_BASE}}/Http/Resources/**"]
+alwaysApply: false
+---
+
+# Resource Rules
+
+## Golden Rule: Schema MUST Match Output
+
+OpenAPI Schema properties MUST match the actual `toArray()` / `schemaArray()` output.
+
+## Before Editing Resource
+
+1. **Read `OmnifyBase/*ResourceBase.php`** to see actual fields
+2. **Compare with `#[OA\Schema]`** properties
+3. **Add missing fields** to schema
+4. **Remove non-existent fields** from schema
+
+## Checklist
+
+```php
+// Check OmnifyBase/*ResourceBase.php → schemaArray()
+return [
+    'id' => $this->id,
+    'name_lastname' => $this->name_lastname,
+    'name_full_name' => $this->name_full_name,      // ← Computed field!
+    'email' => $this->email,
+    'created_at' => $this->created_at?->toISOString(),
+];
+
+// #[OA\Schema] MUST have ALL these properties
+#[OA\Schema(
+    properties: [
+        new OA\Property(property: 'id', ...),
+        new OA\Property(property: 'name_lastname', ...),
+        new OA\Property(property: 'name_full_name', ...),  // ← Don't forget!
+        new OA\Property(property: 'email', ...),
+        new OA\Property(property: 'created_at', ...),
+    ]
+)]
+```
+
+## Common Mistakes
+
+| Mistake                                  | Fix                     |
+| ---------------------------------------- | ----------------------- |
+| Missing computed fields (name_full_name) | Check *ResourceBase.php |
+| Schema has field not in output           | Remove from schema      |
+| Field type mismatch                      | Match actual PHP type   |
+| Missing nullable                         | Check if `?->` used     |
+
+## JapaneseName Type Fields
+
+JapaneseName expands to multiple fields including computed ones:
+
+```php
+// All these come from JapaneseName type
+'name_lastname' => $this->name_lastname,
+'name_firstname' => $this->name_firstname,
+'name_kana_lastname' => $this->name_kana_lastname,
+'name_kana_firstname' => $this->name_kana_firstname,
+'name_full_name' => $this->name_full_name,           // Computed!
+'name_full_name_kana' => $this->name_full_name_kana, // Computed!
+```
+
+**MUST include ALL in OpenAPI Schema!**
+
+## After Editing
+
+```bash
+./artisan l5-swagger:generate
+```

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

@@ -0,0 +1,69 @@
+---
+description: "Code review checklist - security, performance, quality"
+globs: []
+alwaysApply: false
+---
+
+# Code Review Rules
+
+> Review process for Laravel code
+
+## Review Process
+
+1. Security Check → 2. Performance Check → 3. Quality Check → 4. Test Check
+
+## Security Checklist
+
+| Check           | Look For                     |
+| --------------- | ---------------------------- |
+| Mass Assignment | `$request->validated()`      |
+| SQL Injection   | No raw SQL                   |
+| `$fillable`     | Defined, no sensitive fields |
+| `$hidden`       | Password hidden              |
+
+## Performance Checklist
+
+| Check      | Look For               |
+| ---------- | ---------------------- |
+| N+1        | `with()` for relations |
+| Pagination | `paginate()` for lists |
+| Resources  | `whenLoaded()`         |
+
+## Quality Checklist
+
+| Check      | Look For        |
+| ---------- | --------------- |
+| Validation | FormRequest     |
+| Response   | Resource        |
+| Dates      | `toISOString()` |
+
+## Code Style Checklist
+
+| Check       | Look For                               |
+| ----------- | -------------------------------------- |
+| **Imports** | No FQCN inline (`\Full\Path\Class`)    |
+| Use         | All classes imported with `use` at top |
+| Naming      | Follows conventions                    |
+
+## Test Checklist
+
+| Endpoint | 正常系 | 異常系   |
+| -------- | ------ | -------- |
+| store    | 201    | 422      |
+| show     | 200    | 404      |
+| update   | 200    | 404, 422 |
+| destroy  | 204    | 404      |
+
+## Output Format
+
+```markdown
+## Security
+✅ Using `$request->validated()`
+❌ Missing `$hidden` for password
+
+## Performance
+✅ Eager loading
+❌ Missing pagination
+
+## Recommendation: Request Changes
+```