@famgia/omnify-laravel 0.0.118 → 0.0.120

package/stubs/ai-guides/cursor/omnify-schema.mdc.stub

@@ -0,0 +1,339 @@
+---
+description: "Omnify schema YAML syntax and examples. Apply when creating or editing schema files in schemas/ folder. Covers property types, relationships, validations, and Japanese compound types."
+globs: ["schemas/**/*.yaml", "schemas/**/*.yml", "{{LARAVEL_BASE}}/database/migrations/**"]
+alwaysApply: false
+---
+
+# Omnify Schema Creation Workflow
+
+> **Usage:** This rule auto-applies when editing schema files, or mention `@omnify-schema` in chat
+
+## 📋 Workflow Steps
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. READ GUIDE     →  Read schema guide documentation           │
+│  2. CREATE SCHEMA  →  Create/modify YAML schema file            │
+│  3. GENERATE       →  Run `npx omnify generate`                 │
+│  4. VALIDATE       →  Check generated code matches requirements │
+│  5. MIGRATE        →  Run database migration                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Step 1: Read Schema Guide 📖
+
+**MUST READ before creating schema:**
+
+```bash
+# Read the schema guide
+cat .claude/omnify/guides/omnify/schema-guide.md
+# OR
+cat packages/omnify/ai-guides/schema-guide.md
+```
+
+**Key Documentation:**
+- Schema syntax and property types
+- Relationships (belongsTo, hasMany, etc.)
+- Validation rules (nullable, minLength, maxLength)
+- Display names (ja, en, vi)
+- Special types (JapaneseName, JapaneseAddress, etc.)
+
+---
+
+## Step 2: Create Schema 📝
+
+### Schema File Location
+
+```
+schemas/
+├── {domain}/           # Group by domain
+│   ├── {Model}.yaml    # PascalCase filename
+│   └── {Enum}.yaml     # Enum schemas
+└── shared/             # Shared enums/types
+```
+
+### Basic Schema Template
+
+```yaml
+# schemas/{domain}/{ModelName}.yaml
+name: ModelName
+kind: object
+
+displayName:
+  ja: モデル名
+  en: Model Name
+
+options:
+  timestamps: true      # created_at, updated_at
+  softDelete: false     # deleted_at
+
+properties:
+  # Required field
+  name:
+    type: String
+    length: 100
+    displayName:
+      ja: 名前
+      en: Name
+    placeholder:
+      ja: 例：田中太郎
+      en: e.g. John Doe
+
+  # Optional field
+  description:
+    type: Text
+    nullable: true
+    displayName:
+      ja: 説明
+      en: Description
+
+  # Enum field
+  status:
+    type: OrderStatus
+    default: pending
+    displayName:
+      ja: ステータス
+      en: Status
+
+  # Relationship
+  category:
+    type: Category
+    relation: belongsTo
+    nullable: true
+```
+
+### From SQL/Database Requirements
+
+When creating schema from SQL or database design:
+
+```yaml
+# SQL: VARCHAR(255) NOT NULL
+property_name:
+  type: String
+  length: 255
+
+# SQL: VARCHAR(100) NULL
+property_name:
+  type: String
+  length: 100
+  nullable: true
+
+# SQL: TEXT
+property_name:
+  type: Text
+
+# SQL: INT / BIGINT
+property_name:
+  type: Int  # or BigInt
+
+# SQL: DECIMAL(10,2)
+property_name:
+  type: Float
+
+# SQL: BOOLEAN DEFAULT false
+property_name:
+  type: Boolean
+  default: false
+
+# SQL: DATE
+property_name:
+  type: Date
+
+# SQL: DATETIME / TIMESTAMP
+property_name:
+  type: DateTime
+
+# SQL: ENUM('draft', 'published', 'archived')
+# → Create separate enum schema
+```
+
+---
+
+## Step 3: Generate Code 🔧
+
+```bash
+# Generate all code from schemas
+npx omnify generate
+```
+
+**What gets generated:**
+- TypeScript types & Zod schemas
+- Laravel migrations & models
+- API resources & controllers
+- Form requests & validation
+
+---
+
+## Step 4: Validate Generated Code ✅
+
+### ⚠️ CRITICAL for SQL-based schemas
+
+**If creating schema from SQL requirements, MUST verify:**
+
+```bash
+# 1. Check generated migration matches SQL design
+cat database/migrations/*_create_{table_name}_table.php
+
+# 2. Check TypeScript types match requirements
+cat resources/ts/omnify/schemas/{ModelName}.ts
+
+# 3. Check Laravel model relationships
+cat app/Models/{ModelName}.php
+```
+
+### Validation Checklist
+
+| Check | What to Verify |
+|-------|----------------|
+| ✅ Column names | snake_case in migration matches schema |
+| ✅ Column types | VARCHAR, TEXT, INT match schema types |
+| ✅ Nullable | NULL/NOT NULL matches `nullable: true/false` |
+| ✅ Defaults | DEFAULT values match `default:` in schema |
+| ✅ Foreign keys | Relationships generate correct FK |
+| ✅ Indexes | Required indexes are present |
+
+### If Generated Code is Wrong
+
+```
+┌─────────────────────────────────────────┐
+│  Generated code doesn't match SQL?      │
+│                                         │
+│  1. Fix the YAML schema                 │
+│  2. Run `npx omnify generate` again     │
+│  3. Verify generated code               │
+│  4. Repeat until correct                │
+└─────────────────────────────────────────┘
+```
+
+**Common fixes:**
+
+```yaml
+# Problem: Column should be nullable
+# Fix: Add nullable: true
+property_name:
+  type: String
+  nullable: true  # ← Add this
+
+# Problem: Wrong column length
+# Fix: Adjust length
+property_name:
+  type: String
+  length: 255  # ← Change this
+
+# Problem: Missing default value
+# Fix: Add default
+status:
+  type: OrderStatus
+  default: pending  # ← Add this
+
+# Problem: Wrong relationship type
+# Fix: Change relation
+category:
+  type: Category
+  relation: belongsTo  # belongsTo, hasMany, hasOne, belongsToMany
+```
+
+---
+
+## Step 5: Run Migration 🗄️
+
+```bash
+# Run migration
+php artisan migrate
+
+# If migration fails, rollback and fix
+php artisan migrate:rollback
+# Fix schema, regenerate, try again
+```
+
+---
+
+## 🔄 Complete Workflow Example
+
+```bash
+# 1. Read guide
+cat .claude/omnify/guides/omnify/schema-guide.md
+
+# 2. Create schema file
+# schemas/shop/Product.yaml
+
+# 3. Generate code
+npx omnify generate
+
+# 4. Validate (especially for SQL-based requirements)
+cat database/migrations/*_create_products_table.php
+# If wrong: fix schema → regenerate → validate again
+
+# 5. Run migration
+php artisan migrate
+```
+
+---
+
+## 📌 Quick Reference
+
+### Property Types
+
+| Type | SQL | TypeScript |
+|------|-----|------------|
+| `String` | VARCHAR | `string` |
+| `Text` | TEXT | `string` |
+| `LongText` | LONGTEXT | `string` |
+| `Int` | INT | `number` |
+| `BigInt` | BIGINT | `number` |
+| `Float` | DECIMAL | `number` |
+| `Boolean` | BOOLEAN | `boolean` |
+| `Date` | DATE | `string` |
+| `DateTime` | DATETIME | `string` |
+| `Email` | VARCHAR | `string` |
+| `Url` | VARCHAR | `string` |
+| `Json` | JSON | `Record<string, unknown>` |
+
+### Japanese Compound Types
+
+| Type | Fields Generated |
+|------|------------------|
+| `JapaneseName` | `{prefix}_lastname`, `{prefix}_firstname`, `{prefix}_kana_lastname`, `{prefix}_kana_firstname` |
+| `JapaneseAddress` | `{prefix}_postal_code`, `{prefix}_prefecture`, `{prefix}_address1`, `{prefix}_address2`, `{prefix}_address3` |
+| `JapaneseBankAccount` | `{prefix}_bank_code`, `{prefix}_bank_name`, `{prefix}_branch_code`, etc. |
+
+### Relationship Types
+
+| Relation | Description | Foreign Key |
+|----------|-------------|-------------|
+| `belongsTo` | N:1 | `{property}_id` on this table |
+| `hasMany` | 1:N | `{this_model}_id` on related table |
+| `hasOne` | 1:1 | `{this_model}_id` on related table |
+| `belongsToMany` | N:N | Pivot table |
+
+---
+
+## ⚠️ Common Mistakes
+
+```yaml
+# ❌ Wrong: camelCase property name (use camelCase, converts to snake_case)
+firstName:  # ✅ Correct - will become first_name in DB
+
+# ❌ Wrong: Missing displayName for non-English projects
+name:
+  type: String
+  # Missing displayName!
+
+# ✅ Correct: Always add displayName
+name:
+  type: String
+  displayName:
+    ja: 名前
+    en: Name
+
+# ❌ Wrong: Hardcoded enum values in property
+status:
+  type: String
+  enum: [draft, published]  # Don't do this
+
+# ✅ Correct: Create separate enum schema
+status:
+  type: PostStatus  # Reference enum schema
+```