@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/workflows/bug-fix.md.stub

@@ -0,0 +1,201 @@
+# Bug Fix Workflow
+
+> Step-by-step guide for fixing bugs.
+
+## Overview
+
+```mermaid
+flowchart LR
+    Reproduce --> Locate --> Fix --> Test --> PR
+```
+
+| Step | Action                | Output                         |
+| ---- | --------------------- | ------------------------------ |
+| 1    | Reproduce the bug     | Clear reproduction steps       |
+| 2    | Locate the cause      | File(s) and line(s) identified |
+| 3    | Write failing test    | Test that reproduces bug       |
+| 4    | Fix the bug           | Code changes                   |
+| 5    | Verify test passes    | `./artisan test`               |
+| 6    | Check for regressions | All tests pass                 |
+| 7    | Create PR             | Pull request                   |
+
+---
+
+## Step 1: Reproduce
+
+Before fixing, confirm you can reproduce:
+
+```bash
+# Check logs
+tail -f backend/storage/logs/laravel.log
+
+# Test the endpoint
+curl -X GET https://api.boilerplate.app/api/users
+```
+
+**Document:**
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Error message/stack trace
+
+---
+
+## Step 2: Locate the Cause
+
+### Common Locations
+
+| Symptom             | Check                            |
+| ------------------- | -------------------------------- |
+| 500 error           | `storage/logs/laravel.log`       |
+| 422 validation      | `*Request.php` rules             |
+| Wrong data returned | `*Resource.php`                  |
+| 404 not found       | `routes/api.php` + model binding |
+| N+1 queries         | Missing `with()` in controller   |
+| Date format wrong   | Missing `->toISOString()`        |
+
+### Debug Commands
+
+```bash
+# Check route exists
+./artisan route:list | grep users
+
+# Check model
+./artisan tinker
+>>> User::find(1)
+```
+
+---
+
+## Step 3: Write Failing Test
+
+**ALWAYS write a test that reproduces the bug first.**
+
+```php
+// tests/Feature/Api/UserControllerTest.php
+
+it('異常: bug #123 - returns 500 when name is null', function () {
+    // This should NOT happen but currently does
+    $response = $this->postJson('/api/users', [
+        'email' => 'test@example.com',
+        'password' => 'password123',
+        // name is missing - should return 422, not 500
+    ]);
+    
+    $response->assertUnprocessable(); // Currently fails with 500
+});
+```
+
+Run test to confirm it fails:
+
+```bash
+./artisan test --filter="bug #123"
+```
+
+---
+
+## Step 4: Fix the Bug
+
+Make the minimal change to fix the issue.
+
+**Don't:**
+- Refactor unrelated code
+- Add features
+- Change coding style
+
+**Do:**
+- Fix only the bug
+- Keep changes focused
+- Follow existing patterns
+
+---
+
+## Step 5: Verify Fix
+
+```bash
+# Run the specific test
+./artisan test --filter="bug #123"
+
+# Run all tests for the affected controller
+./artisan test --filter=UserControllerTest
+
+# Run all tests
+./artisan test
+```
+
+---
+
+## Step 6: Check for Regressions
+
+```bash
+# All backend tests
+./artisan test
+
+# Specific test file
+./artisan test tests/Feature/Api/UserControllerTest.php
+```
+
+---
+
+## Step 7: Create PR
+
+### PR Title Format
+
+```
+fix: [#issue] brief description
+```
+
+Example: `fix: [#123] return 422 instead of 500 when name is missing`
+
+### PR Description
+
+```markdown
+## Bug
+
+[Link to issue or description]
+
+## Root Cause
+
+[Explanation of what caused the bug]
+
+## Fix
+
+[Description of the fix]
+
+## Test
+
+- [ ] Added test that reproduces bug
+- [ ] Test passes after fix
+- [ ] All existing tests pass
+```
+
+---
+
+## Debugging Tips
+
+### Laravel Logs
+
+```php
+// Add temporary logging
+Log::info('Debug', ['user' => $user, 'request' => $request->all()]);
+```
+
+### Database Queries
+
+```php
+// Enable query log
+DB::enableQueryLog();
+
+// ... your code ...
+
+// Dump queries
+dd(DB::getQueryLog());
+```
+
+### Tinker
+
+```bash
+./artisan tinker
+>>> User::where('email', 'test@example.com')->first()
+>>> app(UserService::class)->someMethod()
+```

package/dist/knowledge/workflows/code-review.md.stub

@@ -0,0 +1,164 @@
+# Code Review Workflow
+
+> Checklist for reviewing pull requests.
+
+## Overview
+
+```mermaid
+flowchart LR
+    Read --> Security --> Performance --> Quality --> Test --> Approve
+```
+
+---
+
+## 1. Understand the Change
+
+- [ ] Read PR description
+- [ ] Understand the purpose
+- [ ] Check linked issue/ticket
+
+---
+
+## 2. Security Review
+
+> **Reference:** [/rules/security.md](../rules/security.md)
+
+### Must Check
+
+| Item            | Look For                                            |
+| --------------- | --------------------------------------------------- |
+| Mass Assignment | Using `$request->validated()` not `$request->all()` |
+| SQL Injection   | No raw SQL with user input                          |
+| `$fillable`     | Defined in models, no sensitive fields              |
+| `$hidden`       | Password and tokens hidden                          |
+| XSS             | No `{!! $userInput !!}` in Blade                    |
+
+### Code Review
+
+```php
+// ❌ REJECT: Mass assignment vulnerability
+User::create($request->all());
+
+// ✅ APPROVE: Using validated data
+User::create($request->validated());
+```
+
+---
+
+## 3. Performance Review
+
+> **Reference:** [/rules/performance.md](../rules/performance.md)
+
+### Must Check
+
+| Item          | Look For                         |
+| ------------- | -------------------------------- |
+| N+1 Queries   | `with()` used for relationships  |
+| Pagination    | List endpoints use `paginate()`  |
+| Resources     | `whenLoaded()` for relationships |
+| Eager Loading | No lazy loading in loops         |
+
+### Code Review
+
+```php
+// ❌ REJECT: N+1 problem
+$posts = Post::all();
+foreach ($posts as $post) {
+    echo $post->author->name;
+}
+
+// ✅ APPROVE: Eager loaded
+$posts = Post::with('author')->get();
+```
+
+---
+
+## 4. Code Quality Review
+
+### Must Check
+
+| Item          | Look For                           |
+| ------------- | ---------------------------------- |
+| Validation    | FormRequest not inline validation  |
+| Response      | Resource not raw model             |
+| Route binding | `User $user` not `findOrFail($id)` |
+| Dates         | `->toISOString()` in Resources     |
+| Types         | Return type hints on methods       |
+
+### Naming
+
+> **Reference:** [/rules/naming.md](../rules/naming.md)
+
+| Type       | Pattern                  |
+| ---------- | ------------------------ |
+| Controller | `{Model}Controller`      |
+| Request    | `{Model}{Action}Request` |
+| Resource   | `{Model}Resource`        |
+| Test       | `{Model}ControllerTest`  |
+
+---
+
+## 5. Test Review
+
+### Must Have
+
+| Endpoint | 正常系             | 異常系                |
+| -------- | ------------------ | --------------------- |
+| index    | List, filter, sort | Empty, invalid params |
+| store    | Creates → 201      | 422 (validation)      |
+| show     | Returns → 200      | 404                   |
+| update   | Updates → 200      | 404, 422              |
+| destroy  | Deletes → 204      | 404                   |
+
+### Test Naming
+
+```php
+// ✅ Good naming
+it('正常: creates user with valid data')
+it('異常: fails to create user with invalid email')
+it('異常: returns 404 when user not found')
+```
+
+---
+
+## 6. Final Checks
+
+- [ ] All tests pass
+- [ ] No debug code (`dd()`, `dump()`, `Log::debug()`)
+- [ ] No commented-out code
+- [ ] No console.log or debug statements
+- [ ] Follows existing patterns in codebase
+
+---
+
+## Review Decision
+
+### ✅ Approve If
+
+- All security checks pass
+- All performance checks pass
+- Tests cover 正常系 + 異常系
+- Code follows conventions
+
+### 🔄 Request Changes If
+
+- Security vulnerability found
+- Performance issue (N+1, no pagination)
+- Missing tests
+- Naming/pattern violations
+
+### Example Comments
+
+```markdown
+## Security Issue
+❌ Line 45: Using `$request->all()` - please use `$request->validated()`
+
+## Performance Issue
+❌ Line 23: Missing `with('author')` - will cause N+1 queries
+
+## Missing Test
+❌ No test for 422 validation error case
+
+## Naming
+❌ `UserCreateRequest` should be `UserStoreRequest` (Laravel convention)
+```

package/dist/knowledge/workflows/new-feature.md.stub

@@ -0,0 +1,327 @@
+# New Feature Workflow
+
+> Step-by-step guide for implementing a complete feature (Backend + Frontend).
+
+## Overview
+
+```mermaid
+flowchart LR
+    Schema --> Generate --> Migrate --> Backend --> Tests --> OpenAPI --> Frontend
+```
+
+| Step | Command/Action        | Output                                  |
+| ---- | --------------------- | --------------------------------------- |
+| 1    | Create schema         | `.omnify/schemas/{Module}/{Model}.yaml` |
+| 2    | `npx omnify generate` | Migration + Types + Requests            |
+| 3    | `./artisan migrate`   | Database tables                         |
+| 4    | Create Backend        | Model, Controller, Resource, Routes     |
+| 5    | Write Tests           | `tests/Feature/Api/*Test.php`           |
+| 6    | `./artisan test`      | All tests pass                          |
+| 7    | Add OpenAPI           | Swagger documentation                   |
+| 8    | Build Frontend        | Service, Hooks, Components              |
+
+---
+
+## Step 1: Schema
+
+Create `.omnify/schemas/{Module}/{Model}.yaml`:
+
+```yaml
+# .omnify/schemas/Blog/Post.yaml
+name: Post
+tableName: posts
+properties:
+  title:
+    type: String
+    maxLength: 255
+  content:
+    type: Text
+  user_id:
+    type: ForeignId
+    references: users
+  published_at:
+    type: DateTime
+    nullable: true
+options:
+  timestamps: true
+```
+
+> **Guide**: [guides/omnify/schema-guide.md](../guides/omnify/schema-guide.md)
+
+---
+
+## Step 2-3: Generate & Migrate
+
+```bash
+npx omnify generate          # Generate migration + types
+./artisan migrate            # Create database tables
+```
+
+**Verify**:
+- [ ] Check `{{LARAVEL_ROOT}}database/migrations/omnify/` for new migration
+- [ ] Check `frontend/src/types/model/` for TypeScript types
+
+---
+
+## Step 4: Backend Implementation
+
+### 4.1 Model
+
+```php
+// {{LARAVEL_BASE}}/Models/Post.php
+class Post extends PostBaseModel
+{
+    // $fillable, $casts inherited from base
+    
+    public function author(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'user_id');
+    }
+    
+    public function scopePublished($query)
+    {
+        return $query->whereNotNull('published_at');
+    }
+}
+```
+
+### 4.2 Controller (Thin!)
+
+```php
+// {{LARAVEL_BASE}}/Http/Controllers/PostController.php
+class PostController extends Controller
+{
+    public function index(Request $request)
+    {
+        $posts = Post::with('author')
+            ->when($request->search, fn($q, $s) => $q->where('title', 'like', "%{$s}%"))
+            ->paginate($request->input('per_page', 15));
+        
+        return PostResource::collection($posts);
+    }
+    
+    public function store(PostStoreRequest $request): PostResource
+    {
+        $post = Post::create($request->validated());
+        return new PostResource($post);
+    }
+    
+    public function show(Post $post): PostResource
+    {
+        return new PostResource($post->load('author'));
+    }
+    
+    public function update(PostUpdateRequest $request, Post $post): PostResource
+    {
+        $post->update($request->validated());
+        return new PostResource($post);
+    }
+    
+    public function destroy(Post $post): Response
+    {
+        $post->delete();
+        return response()->noContent();
+    }
+}
+```
+
+### 4.3 Resource
+
+```php
+// {{LARAVEL_BASE}}/Http/Resources/PostResource.php
+class PostResource extends PostResourceBase
+{
+    public function toArray($request): array
+    {
+        return array_merge($this->schemaArray(), [
+            'author' => new UserResource($this->whenLoaded('author')),
+        ]);
+    }
+}
+```
+
+### 4.4 Routes
+
+```php
+// routes/api.php
+Route::apiResource('posts', PostController::class);
+```
+
+---
+
+## Step 5: Tests
+
+Create `tests/Feature/Api/PostControllerTest.php`:
+
+```php
+describe('GET /api/posts', function () {
+    it('正常: returns paginated posts', function () {
+        Post::factory()->count(20)->create();
+        
+        $response = $this->getJson('/api/posts');
+        
+        $response->assertOk()
+            ->assertJsonCount(15, 'data')
+            ->assertJsonStructure(['data', 'meta', 'links']);
+    });
+});
+
+describe('POST /api/posts', function () {
+    it('正常: creates post with valid data', function () {
+        $data = ['title' => 'Test', 'content' => 'Content'];
+        
+        $response = $this->postJson('/api/posts', $data);
+        
+        $response->assertCreated();
+        $this->assertDatabaseHas('posts', $data);
+    });
+    
+    it('異常: fails with missing title', function () {
+        $response = $this->postJson('/api/posts', ['content' => 'Content']);
+        
+        $response->assertUnprocessable()
+            ->assertJsonValidationErrors(['title']);
+    });
+});
+
+describe('GET /api/posts/{id}', function () {
+    it('正常: returns post by id', function () {
+        $post = Post::factory()->create();
+        
+        $this->getJson("/api/posts/{$post->id}")
+            ->assertOk()
+            ->assertJsonPath('data.id', $post->id);
+    });
+    
+    it('異常: returns 404 when not found', function () {
+        $this->getJson('/api/posts/99999')
+            ->assertNotFound();
+    });
+});
+```
+
+Run tests:
+
+```bash
+./artisan test --filter=PostControllerTest
+```
+
+> **Full guide**: [guides/laravel/testing.md](../guides/laravel/testing.md)
+
+---
+
+## Step 6: OpenAPI Documentation
+
+Add to controller:
+
+```php
+#[OA\Tag(name: 'Posts', description: 'Post management')]
+class PostController extends Controller
+{
+    #[OA\Get(
+        path: '/api/posts',
+        summary: 'List all posts',
+        tags: ['Posts'],
+        parameters: [
+            new OA\Parameter(ref: '#/components/parameters/QuerySearch'),
+            new OA\Parameter(ref: '#/components/parameters/QueryPage'),
+        ],
+        responses: [
+            new OA\Response(ref: '#/components/responses/Success', response: 200),
+        ]
+    )]
+    public function index() { ... }
+}
+```
+
+Generate:
+
+```bash
+./artisan l5-swagger:generate
+```
+
+> **Full guide**: [guides/laravel/openapi.md](../guides/laravel/openapi.md)
+
+---
+
+## Step 7: Frontend
+
+### 7.1 Service
+
+```typescript
+// services/posts.ts
+export const postService = {
+  list: async (params?: PostListParams): Promise<PaginatedResponse<Post>> => {
+    const { data } = await api.get('/api/posts', { params });
+    return data;
+  },
+  
+  create: async (input: PostCreate): Promise<Post> => {
+    const { data } = await api.post('/api/posts', input);
+    return data.data ?? data;
+  },
+  
+  get: async (id: number): Promise<Post> => {
+    const { data } = await api.get(`/api/posts/${id}`);
+    return data.data ?? data;
+  },
+  
+  update: async (id: number, input: PostUpdate): Promise<Post> => {
+    const { data } = await api.put(`/api/posts/${id}`, input);
+    return data.data ?? data;
+  },
+  
+  delete: async (id: number): Promise<void> => {
+    await api.delete(`/api/posts/${id}`);
+  },
+};
+```
+
+### 7.2 Query Keys
+
+```typescript
+// lib/queryKeys.ts
+export const queryKeys = {
+  posts: {
+    all: ['posts'] as const,
+    list: (params?: PostListParams) => ['posts', 'list', params] as const,
+    detail: (id: number) => ['posts', 'detail', id] as const,
+  },
+};
+```
+
+### 7.3 Usage in Component
+
+```typescript
+// List
+const { data, isLoading } = useQuery({
+  queryKey: queryKeys.posts.list(filters),
+  queryFn: () => postService.list(filters),
+});
+
+// Create
+const createMutation = useMutation({
+  mutationFn: postService.create,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.posts.all });
+    message.success('Created!');
+  },
+});
+```
+
+> **Full guide**: [guides/react/README.md](../guides/react/README.md)
+
+---
+
+## Checklist Summary
+
+- [ ] Schema created and generated
+- [ ] Migration verified and run
+- [ ] Model with relationships
+- [ ] Controller (thin, uses FormRequest)
+- [ ] Resource (ISO 8601 dates)
+- [ ] Routes added
+- [ ] Tests written (正常系 + 異常系)
+- [ ] Tests pass
+- [ ] OpenAPI documented
+- [ ] Frontend service + hooks