@omnifyjp/omnify 3.13.1 → 3.14.0

package/ts-dist/php/service-generator.js

@@ -1,12 +1,24 @@
 /**
- * Generates base + editable service classes for schemas with `options.api`.
+ * Generates base + editable service classes for schemas with `options.api`
+ * or `options.service`.
+ *
+ * Issue #57: Full BaseService codegen with translatable, softDelete, audit,
+ * DB::transaction, eagerLoad/eagerCount, lookupFields, defaultSort.
  */
 import { toPascalCase, toSnakeCase } from './naming-helper.js';
 import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace } from './types.js';
-/** Generate service classes for all schemas with api config. */
+// ============================================================================
+// Public entry point
+// ============================================================================
+/** Generate service classes for all schemas with api or service config. */
 export function generateServices(reader, config) {
     const files = [];
-    for (const [name, schema] of Object.entries(reader.getSchemasWithApi())) {
+    // Merge schemas with api OR service options (union)
+    const candidates = {
+        ...reader.getSchemasWithApi(),
+        ...reader.getSchemasWithService(),
+    };
+    for (const [name, schema] of Object.entries(candidates)) {
         files.push(...generateForSchema(name, schema, reader, config));
     }
     return files;
@@ -17,194 +29,237 @@ function generateForSchema(name, schema, reader, config) {
         generateUserService(name, schema, config),
     ];
 }
-// ============================================================================
-// Base service generation
-// ============================================================================
-function generateBaseService(name, schema, reader, config) {
-    const modelName = toPascalCase(name);
-    const api = schema.options?.api ?? {};
-    const bulkDelete = api.bulkDelete ?? false;
-    const restore = api.restore ?? (schema.options?.softDelete ?? false);
-    const perPage = api.perPage ?? 15;
-    const lookup = api.lookup ?? true;
-    const baseNs = resolveModularBaseNamespace(config, name, 'Services', config.services.baseNamespace);
-    const modelNs = config.models.namespace;
+/**
+ * Resolve searchable/filterable fields.
+ *
+ * Priority:
+ *   1. options.service.searchable / .filterable (explicit field name arrays)
+ *   2. Property-level searchable/filterable flags (backward compat)
+ */
+function resolveFieldLists(schema, reader, name) {
     const properties = schema.properties ?? {};
     const propertyOrder = reader.getPropertyOrder(name);
     const expandedProperties = reader.getExpandedProperties(name);
-    // Collect searchable, filterable, sortable fields (compound types expand to sub-columns)
+    const svc = schema.options?.service;
     const searchableFields = [];
     const filterableFields = [];
     const sortableFields = [];
-    for (const propName of propertyOrder) {
-        const prop = properties[propName];
-        if (!prop)
-            continue;
-        const colName = toSnakeCase(propName);
-        const translatable = prop.translatable ?? false;
-        const expansion = expandedProperties[propName];
-        if (prop.searchable) {
+    // If service config has explicit arrays, use those
+    if (svc?.searchable && svc.searchable.length > 0) {
+        for (const fieldName of svc.searchable) {
+            const prop = properties[fieldName];
+            if (!prop)
+                continue;
+            const colName = toSnakeCase(fieldName);
+            const translatable = prop.translatable ?? false;
+            const expansion = expandedProperties[fieldName];
             if (expansion && expansion.columns.length > 0) {
-                // Compound type: search all sub-columns
                 for (const col of expansion.columns) {
-                    if (col.name) {
-                        searchableFields.push({ propName: col.name, colName: col.name, translatable });
-                    }
+                    if (col.name)
+                        searchableFields.push({ propName: col.name, colName: col.name, type: col.type ?? 'String', translatable, prop });
                 }
             }
             else {
-                searchableFields.push({ propName, colName, translatable });
+                searchableFields.push({ propName: fieldName, colName, type: prop.type, translatable, prop });
             }
         }
-        if (prop.filterable) {
+    }
+    else {
+        // Fall back to property-level flags
+        for (const propName of propertyOrder) {
+            const prop = properties[propName];
+            if (!prop || !prop.searchable)
+                continue;
+            const colName = toSnakeCase(propName);
+            const translatable = prop.translatable ?? false;
+            const expansion = expandedProperties[propName];
             if (expansion && expansion.columns.length > 0) {
-                // Compound type: filter on each sub-column
                 for (const col of expansion.columns) {
-                    if (col.name) {
-                        filterableFields.push({ propName: col.name, colName: col.name, type: col.type ?? 'String', prop, translatable });
-                    }
+                    if (col.name)
+                        searchableFields.push({ propName: col.name, colName: col.name, type: col.type ?? 'String', translatable, prop });
                 }
             }
             else {
-                filterableFields.push({ propName, colName, type: prop.type, prop, translatable });
+                searchableFields.push({ propName, colName, type: prop.type, translatable, prop });
             }
         }
-        if (prop.sortable) {
+    }
+    if (svc?.filterable && svc.filterable.length > 0) {
+        for (const fieldName of svc.filterable) {
+            const prop = properties[fieldName];
+            if (!prop)
+                continue;
+            const colName = toSnakeCase(fieldName);
+            const translatable = prop.translatable ?? false;
+            const expansion = expandedProperties[fieldName];
             if (expansion && expansion.columns.length > 0) {
-                // Compound type: sort by primary sub-column (first one)
-                const primaryCol = expansion.columns[0];
-                if (primaryCol?.name) {
-                    sortableFields.push({ propName: colName, colName: primaryCol.name, translatable });
+                for (const col of expansion.columns) {
+                    if (col.name)
+                        filterableFields.push({ propName: col.name, colName: col.name, type: col.type ?? 'String', translatable, prop });
                 }
             }
             else {
-                sortableFields.push({ propName: colName, colName, translatable });
+                filterableFields.push({ propName: fieldName, colName, type: prop.type, translatable, prop });
             }
         }
     }
-    // Build search block
-    const searchBlock = buildSearchBlock(searchableFields);
-    // Build filter block
-    const filterBlock = buildFilterBlock(filterableFields);
-    // Build sort block
-    const sortBlock = buildSortBlock(sortableFields);
-    // Build additional imports
+    else {
+        for (const propName of propertyOrder) {
+            const prop = properties[propName];
+            if (!prop || !prop.filterable)
+                continue;
+            const colName = toSnakeCase(propName);
+            const translatable = prop.translatable ?? false;
+            const expansion = expandedProperties[propName];
+            if (expansion && expansion.columns.length > 0) {
+                for (const col of expansion.columns) {
+                    if (col.name)
+                        filterableFields.push({ propName: col.name, colName: col.name, type: col.type ?? 'String', translatable, prop });
+                }
+            }
+            else {
+                filterableFields.push({ propName, colName, type: prop.type, translatable, prop });
+            }
+        }
+    }
+    // Sortable always from property-level flags (no service-level override for this)
+    for (const propName of propertyOrder) {
+        const prop = properties[propName];
+        if (!prop || !prop.sortable)
+            continue;
+        const colName = toSnakeCase(propName);
+        const translatable = prop.translatable ?? false;
+        const expansion = expandedProperties[propName];
+        if (expansion && expansion.columns.length > 0) {
+            const primaryCol = expansion.columns[0];
+            if (primaryCol?.name)
+                sortableFields.push({ propName: colName, colName: primaryCol.name, type: primaryCol.type ?? 'String', translatable, prop });
+        }
+        else {
+            sortableFields.push({ propName: colName, colName, type: prop.type, translatable, prop });
+        }
+    }
+    return { searchableFields, filterableFields, sortableFields };
+}
+/** Collect properties that have non-null defaults (for create() method). */
+function resolveDefaults(schema, reader, name) {
+    const properties = schema.properties ?? {};
+    const propertyOrder = reader.getPropertyOrder(name);
+    const defaults = [];
+    for (const propName of propertyOrder) {
+        const prop = properties[propName];
+        if (!prop || prop.default === undefined || prop.default === null)
+            continue;
+        // Skip associations, files
+        if (prop.type === 'Association' || prop.type === 'File')
+            continue;
+        const colName = toSnakeCase(propName);
+        const val = prop.default;
+        if (typeof val === 'boolean') {
+            defaults.push({ colName, value: val ? 'true' : 'false' });
+        }
+        else if (typeof val === 'number') {
+            defaults.push({ colName, value: String(val) });
+        }
+        else if (typeof val === 'string') {
+            defaults.push({ colName, value: `'${val}'` });
+        }
+    }
+    return defaults;
+}
+// ============================================================================
+// Base service generation
+// ============================================================================
+function generateBaseService(name, schema, reader, config) {
+    const modelName = toPascalCase(name);
+    const options = schema.options ?? {};
+    const api = options.api ?? {};
+    const svc = options.service ?? {};
+    const hasSoftDelete = options.softDelete ?? false;
+    const perPage = api.perPage ?? 25;
+    const hasApiConfig = options.api != null;
+    const lookup = api.lookup ?? (hasApiConfig ? true : (svc.lookupFields != null && svc.lookupFields.length > 0));
+    // Audit detection — schema-level then global
+    const schemaAudit = options.audit;
+    const globalAudit = reader.getAuditConfig();
+    const hasAuditCreatedBy = schemaAudit?.createdBy ?? globalAudit?.createdBy ?? false;
+    const hasAuditUpdatedBy = schemaAudit?.updatedBy ?? globalAudit?.updatedBy ?? false;
+    const hasAuditDeletedBy = schemaAudit?.deletedBy ?? globalAudit?.deletedBy ?? false;
+    const hasAnyAudit = hasAuditCreatedBy || hasAuditUpdatedBy || hasAuditDeletedBy;
+    // Translatable fields
+    const translatableFields = reader.getTranslatableFields(name);
+    const hasTranslatable = translatableFields.length > 0;
+    // Eager load / count
+    const eagerLoad = svc.eagerLoad ?? [];
+    const eagerCount = svc.eagerCount ?? [];
+    // Default sort
+    const defaultSort = svc.defaultSort ?? '-created_at';
+    // Lookup fields
+    const lookupFields = svc.lookupFields ?? ['id', 'name'];
+    // Field lists
+    const { searchableFields, filterableFields, sortableFields } = resolveFieldLists(schema, reader, name);
+    // Property defaults
+    const defaults = resolveDefaults(schema, reader, name);
+    // Locales (for translatable)
+    const locales = reader.getLocales();
+    const baseNs = resolveModularBaseNamespace(config, name, 'Services', config.services.baseNamespace);
+    const modelNs = config.models.namespace;
+    // Build imports
     const imports = [
         `use ${modelNs}\\${modelName};`,
         `use Illuminate\\Contracts\\Pagination\\LengthAwarePaginator;`,
+        `use Illuminate\\Support\\Facades\\DB;`,
     ];
-    if (restore) {
-        imports.push(`use Illuminate\\Database\\Eloquent\\Collection;`);
+    if (hasAnyAudit) {
+        imports.push(`use Illuminate\\Support\\Facades\\Auth;`);
     }
-    // Build methods
-    const methods = [];
-    // list method
-    methods.push(`
-    /**
-     * List ${modelName} records with search, filter, and sort.
-     *
-     * @param array<string, mixed> $filters
-     */
-    public function list(array $filters): LengthAwarePaginator
-    {
-        $query = ${modelName}::query();
-
-        // Organization scope
-        if (isset($filters['organization_id'])) {
-            $query->where('organization_id', $filters['organization_id']);
-        }
-${searchBlock}${filterBlock}${sortBlock}
-        return $query->paginate($filters['per_page'] ?? ${perPage});
-    }`);
-    // lookup method
-    if (lookup) {
-        methods.push(`
-    /**
-     * Lookup ${modelName} records for select/combobox (lightweight).
-     *
-     * @param array<string, mixed> $filters
-     */
-    public function lookup(array $filters): LengthAwarePaginator
-    {
-        $query = ${modelName}::query();
-
-        if (isset($filters['organization_id'])) {
-            $query->where('organization_id', $filters['organization_id']);
-        }
-
-        if ($search = $filters['search'] ?? null) {
-            $query->where(function ($q) use ($search) {${searchableFields.length > 0 ? `\n${searchableFields.map((f, i) => {
-            if (f.translatable) {
-                return `                $q->${i === 0 ? 'whereTranslationLike' : 'orWhereTranslationLike'}('${f.colName}', "%{$search}%");`;
-            }
-            return `                $q->${i === 0 ? 'where' : 'orWhere'}('${f.colName}', 'like', "%{$search}%");`;
-        }).join('\n')}` : `\n                // No searchable fields defined`}
-            });
-        }
-
-        return $query->paginate($filters['per_page'] ?? 50);
-    }`);
+    // ── Build class body ──────────────────────────────────────────────────────
+    const sections = [];
+    // Model property
+    sections.push(`    protected string $model = ${modelName}::class;`);
+    // ── Query section ─────────────────────────────────────────────────────────
+    sections.push('');
+    sections.push(buildSectionComment('Query'));
+    // list() method
+    sections.push(buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage));
+    // findById() method
+    sections.push(buildFindByIdMethod(modelName, eagerLoad, eagerCount));
+    // ── Create section ────────────────────────────────────────────────────────
+    sections.push('');
+    sections.push(buildSectionComment('Create'));
+    sections.push(buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, translatableFields, eagerLoad, eagerCount, defaults));
+    // ── Update section ────────────────────────────────────────────────────────
+    sections.push('');
+    sections.push(buildSectionComment('Update'));
+    sections.push(buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerLoad, eagerCount));
+    // ── Delete & Restore section ──────────────────────────────────────────────
+    sections.push('');
+    if (hasSoftDelete) {
+        sections.push(buildSectionComment('Delete & Restore'));
     }
-    // create method
-    methods.push(`
-    /**
-     * Create a new ${modelName}.
-     *
-     * @param array<string, mixed> $data
-     */
-    public function create(array $data): ${modelName}
-    {
-        return ${modelName}::create($data);
-    }`);
-    // update method
-    methods.push(`
-    /**
-     * Update an existing ${modelName}.
-     *
-     * @param array<string, mixed> $data
-     */
-    public function update(${modelName} $model, array $data): ${modelName}
-    {
-        $model->update($data);
-
-        return $model->fresh();
-    }`);
-    // delete method
-    methods.push(`
-    /**
-     * Delete a ${modelName}.
-     */
-    public function delete(${modelName} $model): void
-    {
-        $model->delete();
-    }`);
-    // bulkDelete method
-    if (bulkDelete) {
-        methods.push(`
-    /**
-     * Delete multiple ${modelName} records by IDs.
-     *
-     * @param array<int|string> $ids
-     */
-    public function bulkDelete(array $ids): void
-    {
-        ${modelName}::whereIn('id', $ids)->delete();
-    }`);
+    else {
+        sections.push(buildSectionComment('Delete'));
     }
-    // restore method
-    if (restore) {
-        methods.push(`
-    /**
-     * Restore a soft-deleted ${modelName}.
-     */
-    public function restore(string $id): ${modelName}
-    {
-        $model = ${modelName}::withTrashed()->findOrFail($id);
-        $model->restore();
-
-        return $model->fresh();
-    }`);
+    sections.push(buildDeleteMethod(modelName, hasSoftDelete, hasAuditDeletedBy));
+    if (hasSoftDelete) {
+        sections.push(buildRestoreMethod(modelName, eagerLoad, eagerCount));
+        sections.push(buildForceDeleteMethod(modelName));
+        sections.push(buildEmptyTrashMethod());
+    }
+    // ── Lookup section ────────────────────────────────────────────────────────
+    if (lookup) {
+        sections.push('');
+        sections.push(buildSectionComment('Lookup'));
+        sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort));
+    }
+    // ── Translatable helpers ──────────────────────────────────────────────────
+    if (hasTranslatable) {
+        sections.push('');
+        sections.push(buildSectionComment('Translatable Helpers'));
+        sections.push(buildExtractTranslationsMethod(translatableFields, locales));
+        sections.push(buildSyncTranslationsMethod(modelName));
     }
+    // ── Assemble file ─────────────────────────────────────────────────────────
     const content = `<?php
 
 namespace ${baseNs};
@@ -220,138 +275,393 @@ ${imports.join('\n')}
 
 class ${modelName}ServiceBase
 {
-${methods.join('\n')}
+${sections.join('\n')}
 }
 `;
     return baseFile(resolveModularBasePath(config, name, 'Services', `${modelName}ServiceBase.php`, config.services.basePath), content);
 }
 // ============================================================================
-// Search / Filter / Sort block builders
+// Method builders
 // ============================================================================
+function buildSectionComment(title) {
+    return `    // =========================================================================
+    //  ${title}
+    // =========================================================================`;
+}
+function buildEagerLoadChain(eagerLoad, eagerCount) {
+    const parts = [];
+    if (eagerLoad.length > 0) {
+        const list = eagerLoad.map(r => `'${r}'`).join(', ');
+        parts.push(`            ->with([${list}])`);
+    }
+    if (eagerCount.length > 0) {
+        const list = eagerCount.map(r => `'${r}'`).join(', ');
+        parts.push(`            ->withCount([${list}])`);
+    }
+    return parts.join('\n');
+}
+function buildLoadChain(eagerLoad, eagerCount) {
+    const parts = [];
+    if (eagerLoad.length > 0) {
+        const list = eagerLoad.map(r => `'${r}'`).join(', ');
+        parts.push(`->load([${list}])`);
+    }
+    if (eagerCount.length > 0) {
+        const list = eagerCount.map(r => `'${r}'`).join(', ');
+        parts.push(`->loadCount([${list}])`);
+    }
+    return parts.join('\n                ');
+}
+// ── list() ──────────────────────────────────────────────────────────────────
+function buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage) {
+    const lines = [];
+    // PHPDoc with filter shape
+    const filterShape = buildFilterDocShape(filterableFields, hasSoftDelete);
+    lines.push(`
+    /**
+     * @param  array{${filterShape}}  $filters
+     */
+    public function list(array $filters = []): LengthAwarePaginator
+    {
+        $query = $this->model::query()`);
+    // Eager load
+    const eagerChain = buildEagerLoadChain(eagerLoad, eagerCount);
+    if (eagerChain) {
+        lines.push(`${eagerChain};`);
+    }
+    else {
+        // Close the query chain
+        lines[lines.length - 1] += ';';
+    }
+    // Filterable
+    if (filterableFields.length > 0) {
+        lines.push('');
+        lines.push('        // -- Filterable --');
+        for (const f of filterableFields) {
+            lines.push(buildFilterLine(f));
+        }
+    }
+    // Searchable
+    if (searchableFields.length > 0) {
+        lines.push('');
+        lines.push('        // -- Searchable --');
+        lines.push(buildSearchBlock(searchableFields));
+    }
+    // SoftDelete filters
+    if (hasSoftDelete) {
+        lines.push('');
+        lines.push(`        // -- SoftDelete filters --
+        if (! empty($filters['only_trashed'])) {
+            $query->onlyTrashed();
+        } elseif (! empty($filters['with_trashed'])) {
+            $query->withTrashed();
+        }`);
+    }
+    // Sort
+    lines.push('');
+    lines.push(buildSortSection(sortableFields, defaultSort));
+    // Paginate
+    lines.push(`
+        return $query->paginate($filters['per_page'] ?? ${perPage});
+    }`);
+    return lines.join('\n');
+}
+function buildFilterDocShape(filterableFields, hasSoftDelete) {
+    const parts = [];
+    for (const f of filterableFields) {
+        const phpType = resolvePhpFilterType(f.type);
+        parts.push(`${f.colName}?: ${phpType}`);
+    }
+    parts.push('search?: string');
+    if (hasSoftDelete) {
+        parts.push('with_trashed?: bool');
+        parts.push('only_trashed?: bool');
+    }
+    parts.push('sort?: string');
+    parts.push('per_page?: int');
+    return parts.join(', ');
+}
+function resolvePhpFilterType(type) {
+    switch (type) {
+        case 'Boolean': return 'bool';
+        case 'Int':
+        case 'BigInt':
+        case 'TinyInt':
+        case 'Integer': return 'int';
+        case 'Float':
+        case 'Decimal': return 'float';
+        default: return 'string';
+    }
+}
+function buildFilterLine(f) {
+    if (f.translatable) {
+        return `        $query->when(isset($filters['${f.colName}']), fn ($q) => $q->whereTranslation('${f.colName}', $filters['${f.colName}']));`;
+    }
+    switch (f.type) {
+        case 'Boolean':
+            return `        $query->when(isset($filters['${f.colName}']), fn ($q) => $q->where('${f.colName}', $filters['${f.colName}']));`;
+        default:
+            return `        $query->when($filters['${f.colName}'] ?? null, fn ($q, $v) => $q->where('${f.colName}', $v));`;
+    }
+}
 function buildSearchBlock(fields) {
-    if (fields.length === 0)
-        return '';
     const clauses = fields.map((f, i) => {
-        const method = i === 0 ? 'where' : 'orWhere';
         if (f.translatable) {
-            // Astrotomic scope for translatable fields
-            return `                $q->${i === 0 ? 'whereTranslationLike' : 'orWhereTranslationLike'}('${f.colName}', "%{$search}%");`;
+            const method = i === 0 ? 'whereTranslationLike' : 'orWhereTranslationLike';
+            return `                $q->${method}('${f.colName}', "%{$search}%");`;
         }
+        const method = i === 0 ? 'where' : 'orWhere';
         return `                $q->${method}('${f.colName}', 'like', "%{$search}%");`;
     });
-    return `
-        // Search
-        if ($search = $filters['search'] ?? null) {
-            $query->where(function ($q) use ($search) {
+    return `        $query->when($filters['search'] ?? null, function ($q, $search) {
+            $q->where(function ($q) use ($search) {
 ${clauses.join('\n')}
             });
-        }
-`;
+        });`;
 }
-function buildFilterBlock(fields) {
-    if (fields.length === 0)
-        return '';
-    const lines = [];
-    lines.push('');
-    lines.push('        // Filters');
-    for (const f of fields) {
-        const { colName, type, translatable } = f;
-        // Translatable fields use Astrotomic scopes
-        if (translatable) {
-            lines.push(`        if (isset($filters['${colName}'])) {`);
-            lines.push(`            $query->whereTranslation('${colName}', $filters['${colName}']);`);
-            lines.push(`        }`);
-            continue;
-        }
-        switch (type) {
-            case 'Decimal':
-            case 'Int':
-            case 'Float':
-            case 'Integer':
-                // Range filters: field_min, field_max
-                lines.push(`        if (isset($filters['${colName}_min'])) {`);
-                lines.push(`            $query->where('${colName}', '>=', $filters['${colName}_min']);`);
-                lines.push(`        }`);
-                lines.push(`        if (isset($filters['${colName}_max'])) {`);
-                lines.push(`            $query->where('${colName}', '<=', $filters['${colName}_max']);`);
-                lines.push(`        }`);
-                break;
-            case 'Date':
-            case 'Timestamp':
-            case 'DateTime':
-                // Date range filters: field_from, field_to
-                lines.push(`        if (isset($filters['${colName}_from'])) {`);
-                lines.push(`            $query->where('${colName}', '>=', $filters['${colName}_from']);`);
-                lines.push(`        }`);
-                lines.push(`        if (isset($filters['${colName}_to'])) {`);
-                lines.push(`            $query->where('${colName}', '<=', $filters['${colName}_to']);`);
-                lines.push(`        }`);
-                break;
-            case 'Boolean':
-                lines.push(`        if (isset($filters['${colName}'])) {`);
-                lines.push(`            $query->where('${colName}', filter_var($filters['${colName}'], FILTER_VALIDATE_BOOLEAN));`);
-                lines.push(`        }`);
-                break;
-            case 'Enum':
-            case 'EnumRef':
-            case 'String':
-            default:
-                // Exact match
-                lines.push(`        if (isset($filters['${colName}'])) {`);
-                lines.push(`            $query->where('${colName}', $filters['${colName}']);`);
-                lines.push(`        }`);
-                break;
+function buildSortSection(sortableFields, defaultSort) {
+    return `        // -- Sort --
+        $sort = $filters['sort'] ?? '${defaultSort}';
+        $direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
+        $column = ltrim($sort, '-');
+        $query->orderBy($column, $direction);`;
+}
+// ── findById() ──────────────────────────────────────────────────────────────
+function buildFindByIdMethod(modelName, eagerLoad, eagerCount) {
+    const eagerChain = buildEagerLoadChain(eagerLoad, eagerCount);
+    const chain = eagerChain ? `\n${eagerChain}\n            ` : '';
+    return `
+    public function findById(string $id): ${modelName}
+    {
+        return $this->model::query()${chain}->findOrFail($id);
+    }`;
+}
+// ── create() ────────────────────────────────────────────────────────────────
+function buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, translatableFields, eagerLoad, eagerCount, defaults) {
+    const bodyLines = [];
+    // Audit
+    if (hasAuditCreatedBy) {
+        bodyLines.push(`            // -- Audit: inject created_by --
+            if (Auth::check()) {
+                $data['created_by_id'] = $data['created_by_id'] ?? Auth::id();
+            }
+`);
+    }
+    // Defaults
+    if (defaults.length > 0) {
+        bodyLines.push('            // -- Defaults --');
+        for (const d of defaults) {
+            bodyLines.push(`            $data['${d.colName}'] = $data['${d.colName}'] ?? ${d.value};`);
         }
+        bodyLines.push('');
+    }
+    // Translatable
+    if (hasTranslatable) {
+        bodyLines.push(`            // -- Translatable: extract locale-keyed data --
+            $translations = $this->extractTranslations($data);
+`);
+    }
+    bodyLines.push(`            $model = $this->model::create($data);`);
+    if (hasTranslatable) {
+        bodyLines.push(`
+            // -- Translatable: sync translations for all locales --
+            if (! empty($translations)) {
+                $this->syncTranslations($model, $translations);
+            }`);
     }
-    return lines.join('\n') + '\n';
+    // Return with eager load
+    const loadChain = buildLoadChain(eagerLoad, eagerCount);
+    if (loadChain) {
+        bodyLines.push(`
+            return $model
+                ${loadChain};`);
+    }
+    else {
+        bodyLines.push(`
+            return $model;`);
+    }
+    return `
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public function create(array $data): ${modelName}
+    {
+        return DB::transaction(function () use ($data) {
+${bodyLines.join('\n')}
+        });
+    }`;
 }
-function buildSortBlock(sortableFields) {
-    if (sortableFields.length === 0) {
-        return `
-        // Sort
-        $query->orderBy('created_at', 'desc');
-`;
+// ── update() ────────────────────────────────────────────────────────────────
+function buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerLoad, eagerCount) {
+    const bodyLines = [];
+    if (hasAuditUpdatedBy) {
+        bodyLines.push(`            // -- Audit: inject updated_by --
+            if (Auth::check()) {
+                $data['updated_by_id'] = $data['updated_by_id'] ?? Auth::id();
+            }
+`);
+    }
+    if (hasTranslatable) {
+        bodyLines.push(`            // -- Translatable: extract and sync --
+            $translations = $this->extractTranslations($data);
+`);
+    }
+    bodyLines.push(`            $model->update($data);`);
+    if (hasTranslatable) {
+        bodyLines.push(`
+            if (! empty($translations)) {
+                $this->syncTranslations($model, $translations);
+            }`);
+    }
+    const loadChain = buildLoadChain(eagerLoad, eagerCount);
+    if (loadChain) {
+        bodyLines.push(`
+            return $model
+                ${loadChain};`);
+    }
+    else {
+        bodyLines.push(`
+            return $model;`);
+    }
+    return `
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public function update(${modelName} $model, array $data): ${modelName}
+    {
+        return DB::transaction(function () use ($model, $data) {
+${bodyLines.join('\n')}
+        });
+    }`;
+}
+// ── delete() ────────────────────────────────────────────────────────────────
+function buildDeleteMethod(modelName, hasSoftDelete, hasAuditDeletedBy) {
+    const bodyLines = [];
+    if (hasAuditDeletedBy && hasSoftDelete) {
+        bodyLines.push(`            // -- Audit: inject deleted_by --
+            if (Auth::check()) {
+                $model->update(['deleted_by_id' => Auth::id()]);
+            }
+`);
     }
-    // allowedSorts uses logical propName (what user sends in ?sort=)
-    const allowedList = sortableFields.map(f => `'${f.propName}'`).join(', ');
-    // sortMap: logical name → actual column name (compound types map to sub-column)
-    const needsMap = sortableFields.some(f => f.propName !== f.colName);
-    const sortMapEntries = sortableFields
-        .filter(f => f.propName !== f.colName)
-        .map(f => `            '${f.propName}' => '${f.colName}',`)
-        .join('\n');
-    const sortMapDecl = needsMap ? `\n        $sortMap = [\n${sortMapEntries}\n        ];` : '';
-    const sortColResolve = needsMap ? `\n                $sortCol = $sortMap[$sortField] ?? $sortField;` : `\n                $sortCol = $sortField;`;
-    const translatableSorts = sortableFields.filter(f => f.translatable).map(f => `'${f.propName}'`);
-    const translatableCheck = translatableSorts.length > 0
-        ? `\n        $translatableSorts = [${translatableSorts.join(', ')}];`
-        : '';
-    const orderByLine = translatableSorts.length > 0
-        ? `            if (in_array($sortField, $translatableSorts ?? [], true)) {
-                $query->orderByTranslation($sortCol, $direction);
-            } else {
-                $query->orderBy($sortCol, $direction);
-            }`
-        : `            $query->orderBy($sortCol, $direction);`;
+    bodyLines.push(`            return $model->delete();`);
+    return `
+    public function delete(${modelName} $model): bool
+    {
+        return DB::transaction(function () use ($model) {
+${bodyLines.join('\n')}
+        });
+    }`;
+}
+// ── restore() ───────────────────────────────────────────────────────────────
+function buildRestoreMethod(modelName, eagerLoad, eagerCount) {
+    const loadChain = buildLoadChain(eagerLoad, eagerCount);
+    const returnLine = loadChain
+        ? `            $model->restore();\n\n            return $model\n                ${loadChain};`
+        : `            $model->restore();\n\n            return $model;`;
+    return `
+    public function restore(${modelName} $model): ${modelName}
+    {
+        return DB::transaction(function () use ($model) {
+${returnLine}
+        });
+    }`;
+}
+// ── forceDelete() ───────────────────────────────────────────────────────────
+function buildForceDeleteMethod(modelName) {
+    return `
+    public function forceDelete(${modelName} $model): bool
+    {
+        return DB::transaction(fn () => $model->forceDelete());
+    }`;
+}
+// ── emptyTrash() ────────────────────────────────────────────────────────────
+function buildEmptyTrashMethod() {
+    return `
+    public function emptyTrash(): int
+    {
+        return $this->model::onlyTrashed()->forceDelete();
+    }`;
+}
+// ── lookup() ────────────────────────────────────────────────────────────────
+function buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort) {
+    const selectFields = lookupFields.map(f => `'${toSnakeCase(f)}'`).join(', ');
+    const returnShape = lookupFields.map(f => `${toSnakeCase(f)}: mixed`).join(', ');
+    // Sort by first non-id field or default
+    const sortCol = defaultSort.replace(/^-/, '');
+    const sortDir = defaultSort.startsWith('-') ? 'desc' : 'asc';
+    // Apply filterable columns to lookup too
+    const filterLines = filterableFields.map(f => `        $query->when($filters['${f.colName}'] ?? null, fn ($q, $v) => $q->where('${f.colName}', $v));`);
     return `
-        // Sort
-        $sortParam = $filters['sort'] ?? '-created_at';
-        $allowedSorts = [${allowedList}];${sortMapDecl}${translatableCheck}
+    /**
+     * @return array<int, array{${returnShape}}>
+     */
+    public function lookup(array $filters = []): array
+    {
+        $query = $this->model::query()
+            ->select([${selectFields}])
+            ->orderBy('${sortCol}', '${sortDir}');
+
+${filterLines.length > 0 ? filterLines.join('\n') + '\n' : ''}
+        return $query->get()->toArray();
+    }`;
+}
+// ── extractTranslations() ───────────────────────────────────────────────────
+function buildExtractTranslationsMethod(translatableFields, locales) {
+    const fieldsArray = translatableFields.map(f => `'${f}'`).join(', ');
+    const localesArray = locales.map(l => `'${l}'`).join(', ');
+    return `
+    /**
+     * Extract translation data from input.
+     *
+     * Supports two formats:
+     *   1. Flat:   { "name:ja": "テスト", "name:en": "Test" }
+     *   2. Nested: { "translations": { "ja": { "name": "テスト" }, "en": { "name": "Test" } } }
+     *
+     * @return array<string, array<string, string>>  locale => [attr => value]
+     */
+    protected function extractTranslations(array &$data): array
+    {
+        $translatedAttributes = [${fieldsArray}];
+        $locales = [${localesArray}];
+        $translations = [];
 
-        foreach (explode(',', $sortParam) as $sortField) {
-            $sortField = trim($sortField);
-            $direction = 'asc';
+        // Format 2: nested "translations" key
+        if (isset($data['translations']) && is_array($data['translations'])) {
+            $translations = $data['translations'];
+            unset($data['translations']);
 
-            if (str_starts_with($sortField, '-')) {
-                $direction = 'desc';
-                $sortField = substr($sortField, 1);
-            }
+            return $translations;
+        }
 
-            if (in_array($sortField, $allowedSorts, true) || $sortField === 'created_at' || $sortField === 'updated_at') {${sortColResolve}
-${orderByLine}
+        // Format 1: flat "attr:locale" keys
+        foreach ($translatedAttributes as $attr) {
+            foreach ($locales as $locale) {
+                $key = "{$attr}:{$locale}";
+                if (isset($data[$key])) {
+                    $translations[$locale][$attr] = $data[$key];
+                    unset($data[$key]);
+                }
             }
         }
-`;
+
+        return $translations;
+    }`;
+}
+// ── syncTranslations() ─────────────────────────────────────────────────────
+function buildSyncTranslationsMethod(modelName) {
+    return `
+    /**
+     * Sync translations for all provided locales.
+     */
+    protected function syncTranslations(${modelName} $model, array $translations): void
+    {
+        foreach ($translations as $locale => $attrs) {
+            $translation = $model->translateOrNew($locale);
+            $translation->fill($attrs);
+            $translation->save();
+        }
+    }`;
 }
 // ============================================================================
 // User service