@omnifyjp/ts 3.19.4 → 3.20.0

package/dist/php/service-generator.js

@@ -218,9 +218,16 @@ function generateBaseService(name, schema, reader, config) {
     const hasAuditUpdatedBy = schemaAudit?.updatedBy ?? globalAudit?.updatedBy ?? false;
     const hasAuditDeletedBy = schemaAudit?.deletedBy ?? globalAudit?.deletedBy ?? false;
     const hasAnyAudit = hasAuditCreatedBy || hasAuditUpdatedBy || hasAuditDeletedBy;
-    // Translatable fields
+    // Translatable fields + sidecar table info (#76: lookup/sort need join rewrite)
     const translatableFields = reader.getTranslatableFields(name);
     const hasTranslatable = translatableFields.length > 0;
+    const modelSnake = toSnakeCase(name);
+    const translationCtx = {
+        mainTable: reader.getTableName(name),
+        translationTable: `${modelSnake}_translations`,
+        fkColumn: `${modelSnake}_id`,
+        translatableFields,
+    };
     // Eager load / count (#75.1: rejoin YAML-split `rel:col,col` tokens)
     const eagerLoad = reconstructRelationTokens(svc.eagerLoad ?? []);
     const eagerCount = svc.eagerCount ?? [];
@@ -255,7 +262,7 @@ function generateBaseService(name, schema, reader, config) {
     // Allowed sort columns whitelist (#75.2: prevent SQL injection via sort filter)
     const allowedSortColumns = buildAllowedSortColumns(searchableFields, filterableFields, sortableFields, defaultSort, hasSoftDelete);
     // list() method
-    sections.push(buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns));
+    sections.push(buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns, translationCtx));
     // findById() method
     sections.push(buildFindByIdMethod(modelName, eagerLoad, eagerCount));
     // ── Create section ────────────────────────────────────────────────────────
@@ -284,7 +291,7 @@ function generateBaseService(name, schema, reader, config) {
     if (lookup) {
         sections.push('');
         sections.push(buildSectionComment('Lookup'));
-        sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort));
+        sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort, translationCtx));
     }
     // ── Translatable helpers ──────────────────────────────────────────────────
     if (hasTranslatable) {
@@ -294,19 +301,31 @@ function generateBaseService(name, schema, reader, config) {
         sections.push(buildSyncTranslationsMethod(modelName));
     }
     // ── Assemble file ─────────────────────────────────────────────────────────
+    const classDoc = buildClassDocblock({
+        modelName,
+        schemaName: name,
+        modelFqcn: `${modelNs}\\${modelName}`,
+        searchableFields,
+        filterableFields,
+        allowedSortColumns,
+        defaultSort,
+        perPage,
+        eagerLoad,
+        eagerCount,
+        translatableFields,
+        hasSoftDelete,
+        hasAnyAudit,
+        lookup,
+        lookupFields,
+        locales,
+    });
     const content = `<?php
 
 namespace ${baseNs};
 
-/**
- * DO NOT EDIT - This file is auto-generated by Omnify.
- * Any changes will be overwritten on next generation.
- *
- * @generated by omnify
- */
-
 ${imports.join('\n')}
 
+${classDoc}
 class ${modelName}ServiceBase
 {
 ${sections.join('\n')}
@@ -322,6 +341,81 @@ function buildSectionComment(title) {
     //  ${title}
     // =========================================================================`;
 }
+function buildClassDocblock(c) {
+    const lines = [];
+    lines.push('/**');
+    lines.push(` * ${c.modelName}ServiceBase — auto-generated service layer for the ${c.schemaName} schema.`);
+    lines.push(' *');
+    lines.push(` * Model:     ${c.modelFqcn}`);
+    lines.push(' * Extends:   (none) — consumers extend this via the sibling non-Base file,');
+    lines.push(' *            which is never overwritten.');
+    lines.push(' *');
+    lines.push(' * === list() filter contract ===');
+    if (c.searchableFields.length > 0) {
+        const searchCols = c.searchableFields
+            .map(f => f.translatable ? `${f.colName} (translated)` : f.colName)
+            .join(', ');
+        lines.push(` *   search        (LIKE)  — against: ${searchCols}`);
+    }
+    for (const f of c.filterableFields) {
+        const phpType = resolvePhpFilterType(f.type);
+        const note = f.translatable ? ' (translatable)' : '';
+        lines.push(` *   ${f.colName.padEnd(13)} (${phpType})${note} — from options.service.filterable`);
+    }
+    lines.push(` *   sort          (col)   — whitelisted: ${c.allowedSortColumns.join(', ')}.`);
+    lines.push(` *                          Default: ${c.defaultSort}. Prefix '-' for DESC.`);
+    if (c.hasSoftDelete) {
+        lines.push(' *   only_trashed  (bool)  — wins over with_trashed when both set.');
+        lines.push(' *   with_trashed  (bool)');
+    }
+    lines.push(` *   per_page      (int)   — default ${c.perPage}.`);
+    lines.push(' *');
+    if (c.eagerLoad.length > 0 || c.eagerCount.length > 0) {
+        lines.push(' * === Relations ===');
+        if (c.eagerLoad.length > 0) {
+            lines.push(` *   Eager loads:   ${c.eagerLoad.join(', ')}`);
+        }
+        if (c.eagerCount.length > 0) {
+            lines.push(` *   Eager counts:  ${c.eagerCount.join(', ')}`);
+        }
+        lines.push(' *');
+    }
+    if (c.translatableFields.length > 0) {
+        lines.push(' * === Translatable ===');
+        lines.push(` *   Fields:     ${c.translatableFields.join(', ')}`);
+        lines.push(` *   Locales:    ${c.locales.join(', ')}`);
+        lines.push(` *   Sidecar:    ${toSnakeCase(c.schemaName)}_translations (synced in create/update)`);
+        lines.push(' *');
+        lines.push(' *   Input format (preferred — Astrotomic-native flat, see #78):');
+        const sampleField = c.translatableFields[0] ?? 'name';
+        const sampleLocale = c.locales[0] ?? 'ja';
+        lines.push(` *     [ "${sampleField}:${sampleLocale}" => "...", "${sampleField}:${c.locales[1] ?? 'en'}" => "..." ]`);
+        lines.push(' *');
+        lines.push(' *   Legacy "translations" wrapper is accepted but deprecated — it emits');
+        lines.push(' *   a E_USER_DEPRECATED notice and will be removed in omnify v3.21.0.');
+        lines.push(' *');
+        lines.push(' *   Lookup/sort on translatable columns rewrites to a LEFT JOIN on the');
+        lines.push(' *   sidecar for the request locale + fallback (see #76).');
+        lines.push(' *');
+    }
+    if (c.hasSoftDelete) {
+        lines.push(' * Soft delete: enabled (delete → trash, forceDelete → hard delete, restore → untrash).');
+    }
+    if (c.hasAnyAudit) {
+        lines.push(' * Audit:       created_by/updated_by/deleted_by forced from Auth::id() (client');
+        lines.push(' *              values are discarded — see #75 item 3).');
+    }
+    if (c.lookup) {
+        lines.push(` * Lookup:      returns ${c.lookupFields.join(', ')} (default limit 100, hard cap 500 — #75.8).`);
+    }
+    lines.push(' *');
+    lines.push(' * DO NOT EDIT - This file is auto-generated by Omnify.');
+    lines.push(' * Any changes will be overwritten on next generation.');
+    lines.push(' *');
+    lines.push(' * @generated by omnify');
+    lines.push(' */');
+    return lines.join('\n');
+}
 function buildEagerLoadChain(eagerLoad, eagerCount) {
     const parts = [];
     if (eagerLoad.length > 0) {
@@ -367,12 +461,18 @@ function buildAllowedSortColumns(searchableFields, filterableFields, sortableFie
         set.add(defaultCol);
     return Array.from(set).sort();
 }
-function buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns) {
+function buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns, tx) {
     const lines = [];
-    // PHPDoc with filter shape
+    // PHPDoc with filter shape (#77: documented, @throws, intent)
     const filterShape = buildFilterDocShape(filterableFields, hasSoftDelete);
     lines.push(`
     /**
+     * List ${modelName} records with filters, search, sort and pagination.
+     *
+     * Filter keys are whitelisted from the schema's options.service config;
+     * unknown keys are ignored. The sort column is whitelisted against
+     * searchable + filterable + standard audit columns (#75.2).
+     *
      * @param  array{${filterShape}}  $filters
      */
     public function list(array $filters = []): LengthAwarePaginator
@@ -413,7 +513,7 @@ function buildListMethod(modelName, searchableFields, filterableFields, sortable
     }
     // Sort
     lines.push('');
-    lines.push(buildSortSection(sortableFields, defaultSort, allowedSortColumns));
+    lines.push(buildSortSection(sortableFields, defaultSort, allowedSortColumns, tx));
     // Paginate
     lines.push(`
         return $query->paginate($filters['per_page'] ?? ${perPage});
@@ -473,11 +573,14 @@ ${clauses.join('\n')}
             });
         });`;
 }
-function buildSortSection(_sortableFields, defaultSort, allowedSortColumns) {
+function buildSortSection(_sortableFields, defaultSort, allowedSortColumns, tx) {
     const defaultCol = defaultSort.replace(/^-/, '');
     const allowedList = allowedSortColumns.map(c => `'${c}'`).join(', ');
-    // #75.2: whitelist sort column to prevent SQL injection / arbitrary column access
-    return `        // -- Sort (#75.2: whitelist guards against SQL injection) --
+    const hasTranslatableSortable = tx.translatableFields.length > 0 &&
+        allowedSortColumns.some(c => tx.translatableFields.includes(c));
+    if (!hasTranslatableSortable) {
+        // Fast path: nothing translatable in the allowlist, plain orderBy works.
+        return `        // -- Sort (#75.2: whitelist guards against SQL injection) --
         $sort = $filters['sort'] ?? '${defaultSort}';
         $direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
         $column = ltrim($sort, '-');
@@ -486,12 +589,58 @@ function buildSortSection(_sortableFields, defaultSort, allowedSortColumns) {
             $column = '${defaultCol}';
         }
         $query->orderBy($column, $direction);`;
+    }
+    // #76: one or more whitelisted columns live in the translation sidecar.
+    // Runtime-branch on $column: translatable → leftJoin + orderByRaw with
+    // COALESCE(locale, fallback); non-translatable → plain orderBy.
+    const translatablePhpList = tx.translatableFields
+        .filter(f => allowedSortColumns.includes(f))
+        .map(f => `'${f}'`)
+        .join(', ');
+    const mainTable = tx.mainTable;
+    const trTable = tx.translationTable;
+    const fk = tx.fkColumn;
+    return `        // -- Sort (#75.2 whitelist + #76 translatable join rewrite) --
+        $sort = $filters['sort'] ?? '${defaultSort}';
+        $direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
+        $column = ltrim($sort, '-');
+        $allowedSortColumns = [${allowedList}];
+        if (! in_array($column, $allowedSortColumns, true)) {
+            $column = '${defaultCol}';
+        }
+        $translatableSortColumns = [${translatablePhpList}];
+        if (in_array($column, $translatableSortColumns, true)) {
+            // #76: sort column lives in '${trTable}'. LEFT JOIN once on the
+            // request locale and once on the fallback locale, then COALESCE
+            // so missing translations don't push rows to the top/bottom.
+            $locale = app()->getLocale();
+            $fallback = config('translatable.fallback_locale', 'en');
+            $query
+                ->leftJoin('${trTable} as tr_sort', function ($j) use ($locale) {
+                    $j->on('tr_sort.${fk}', '=', '${mainTable}.id')
+                      ->where('tr_sort.locale', $locale);
+                })
+                ->leftJoin('${trTable} as tr_sort_fb', function ($j) use ($fallback) {
+                    $j->on('tr_sort_fb.${fk}', '=', '${mainTable}.id')
+                      ->where('tr_sort_fb.locale', $fallback);
+                })
+                ->select('${mainTable}.*')
+                ->orderByRaw("COALESCE(tr_sort.\`{$column}\`, tr_sort_fb.\`{$column}\`) " . strtoupper($direction));
+        } else {
+            $query->orderBy($column, $direction);
+        }`;
 }
 // ── findById() ──────────────────────────────────────────────────────────────
 function buildFindByIdMethod(modelName, eagerLoad, eagerCount) {
     const eagerChain = buildEagerLoadChain(eagerLoad, eagerCount);
     const chain = eagerChain ? `\n${eagerChain}\n            ` : '';
     return `
+    /**
+     * Load a single ${modelName} by primary key with the configured eager
+     * loads applied. Throws ModelNotFoundException (→ HTTP 404) on miss.
+     *
+     * @throws \\Illuminate\\Database\\Eloquent\\ModelNotFoundException
+     */
     public function findById(string $id): ${modelName}
     {
         return $this->model::query()${chain}->findOrFail($id);
@@ -544,7 +693,21 @@ function buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, transl
     }
     return `
     /**
+     * Create a new ${modelName}.
+     *
+     * Runs inside a DB transaction so partial failures roll back cleanly.
+     * Behaviour derived from the schema:${hasAuditCreatedBy ? `
+     *   - created_by_id is forced from Auth::id(); any client-supplied value
+     *     is discarded before the insert (#75 item 3 — prevents audit forgery).` : ''}${defaults.length > 0 ? `
+     *   - Schema defaults are applied for fields not present in $data.` : ''}${hasTranslatable ? `
+     *   - Translatable fields are extracted from either flat ("name:ja") or
+     *     nested ("translations.ja.name") input and persisted to the sidecar
+     *     translation table after the main row is inserted.` : ''}${eagerLoad.length + eagerCount.length > 0 ? `
+     *   - Eager relations are loaded onto the returned model so the caller
+     *     can render it directly.` : ''}
+     *
      * @param  array<string, mixed>  $data
+     * @throws \\Illuminate\\Database\\QueryException on constraint violation
      */
     public function create(array $data): ${modelName}
     {
@@ -588,7 +751,15 @@ function buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerL
     }
     return `
     /**
+     * Update an existing ${modelName}.
+     *
+     * Same transaction + cascade contract as create():${hasAuditUpdatedBy ? `
+     *   - updated_by_id is forced from Auth::id() (#75 item 3).` : ''}${hasTranslatable ? `
+     *   - Translatable fields are re-synced via translateOrNew() so only the
+     *     locales present in $data are touched; other locales remain intact.` : ''}
+     *
      * @param  array<string, mixed>  $data
+     * @throws \\Illuminate\\Database\\QueryException on constraint violation
      */
     public function update(${modelName} $model, array $data): ${modelName}
     {
@@ -609,6 +780,12 @@ function buildDeleteMethod(modelName, hasSoftDelete, hasAuditDeletedBy) {
     }
     bodyLines.push(`            return $model->delete();`);
     return `
+    /**
+     * ${hasSoftDelete ? 'Soft-delete' : 'Delete'} a ${modelName}${hasSoftDelete ? ' (moves to trash, restorable via restore())' : ''}.${hasAuditDeletedBy && hasSoftDelete ? `
+     *
+     * deleted_by_id is stamped from Auth::id() inside the same transaction
+     * so audit trails stay consistent even if the delete fails.` : ''}
+     */
     public function delete(${modelName} $model): bool
     {
         return DB::transaction(function () use ($model) {
@@ -623,6 +800,9 @@ function buildRestoreMethod(modelName, eagerLoad, eagerCount) {
         ? `            $model->restore();\n\n            return $model\n                ${loadChain};`
         : `            $model->restore();\n\n            return $model;`;
     return `
+    /**
+     * Restore a soft-deleted ${modelName} and return it with eager loads applied.
+     */
     public function restore(${modelName} $model): ${modelName}
     {
         return DB::transaction(function () use ($model) {
@@ -634,6 +814,9 @@ ${returnLine}
 function buildForceDeleteMethod(modelName, hasTranslatable) {
     if (!hasTranslatable) {
         return `
+    /**
+     * Hard-delete a ${modelName} (bypasses soft-delete, removes the row).
+     */
     public function forceDelete(${modelName} $model): bool
     {
         return DB::transaction(fn () => $model->forceDelete());
@@ -642,6 +825,14 @@ function buildForceDeleteMethod(modelName, hasTranslatable) {
     // #75.7: explicitly drop translations inside the same transaction so the
     // service contract does not rely on the FK's ON DELETE behaviour.
     return `
+    /**
+     * Hard-delete a ${modelName} and its translation rows.
+     *
+     * We explicitly delete translations inside the transaction instead of
+     * relying on the FK's ON DELETE behaviour — the migration may or may
+     * not emit CASCADE, and we don't want forceDelete()'s correctness to
+     * depend on schema quirks (#75.7).
+     */
     public function forceDelete(${modelName} $model): bool
     {
         return DB::transaction(function () use ($model) {
@@ -656,6 +847,9 @@ function buildForceDeleteMethod(modelName, hasTranslatable) {
 function buildEmptyTrashMethod(hasTranslatable) {
     if (!hasTranslatable) {
         return `
+    /**
+     * Permanently delete every trashed row. Returns rows-affected count.
+     */
     public function emptyTrash(): int
     {
         return $this->model::onlyTrashed()->forceDelete();
@@ -665,10 +859,16 @@ function buildEmptyTrashMethod(hasTranslatable) {
     // so translations would be orphaned. Chunk through trashed rows and
     // delegate to forceDelete() which cascades explicitly.
     return `
+    /**
+     * Permanently delete every trashed row, cascading translations.
+     *
+     * Iterates via chunkById(100) and delegates to forceDelete() so the
+     * translation cascade in forceDelete() runs per row. A query-builder
+     * DELETE would be faster but would skip that cascade and orphan
+     * translation rows — see #75 followup comment.
+     */
     public function emptyTrash(): int
     {
-        // #75 followup: delegate to per-model forceDelete so the translation
-        // cascade in forceDelete() runs. A query-builder DELETE would skip it.
         $count = 0;
         $this->model::onlyTrashed()->chunkById(100, function ($batch) use (&$count) {
             foreach ($batch as $model) {
@@ -681,18 +881,34 @@ function buildEmptyTrashMethod(hasTranslatable) {
     }`;
 }
 // ── 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
+function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSort, tx) {
+    const snakeLookup = lookupFields.map(f => toSnakeCase(f));
+    const returnShape = snakeLookup.map(f => `${f}: mixed`).join(', ');
     const sortCol = defaultSort.replace(/^-/, '');
     const sortDir = defaultSort.startsWith('-') ? 'desc' : 'asc';
+    const translatableSet = new Set(tx.translatableFields);
+    const hasTranslatableLookup = snakeLookup.some(f => translatableSet.has(f)) ||
+        (translatableSet.has(sortCol) && tx.translationTable.length > 0);
     // Apply filterable columns — reuse buildFilterLine so Boolean handling
-    // matches list() (#75.4: `?? null` collapses `false` so lookup() silently
-    // dropped `is_hidden=false`; list() uses isset() which is correct).
+    // matches list() (#75.4).
     const filterLines = filterableFields.map(f => buildFilterLine(f));
-    return `
+    const filterBlock = filterLines.length > 0 ? filterLines.join('\n') + '\n\n' : '';
+    // #75.8: cap results (shared by both branches)
+    const limitBlock = `        // #75.8: cap results so type-ahead / dropdown endpoints never load the
+        // entire table. Caller can override via ?limit=... up to a hard ceiling.
+        $limit = min((int) ($filters['limit'] ?? 100), 500);
+        $query->limit($limit);`;
+    if (!hasTranslatableLookup) {
+        // Fast path — no translatable columns involved.
+        const selectFields = snakeLookup.map(f => `'${f}'`).join(', ');
+        return `
     /**
+     * Lightweight list-projection for dropdowns, type-aheads and autocomplete.
+     *
+     * Returns a flat array of {${returnShape}} rows (never a paginator). Honours
+     * every key that list() honours for filterable columns. Default row cap
+     * is 100 (caller override via ?limit=..., hard ceiling 500 — see #75.8).
+     *
      * @param  array<string, mixed>  $filters
      * @return array<int, array{${returnShape}}>
      */
@@ -702,11 +918,73 @@ function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSo
             ->select([${selectFields}])
             ->orderBy('${sortCol}', '${sortDir}');
 
-${filterLines.length > 0 ? filterLines.join('\n') + '\n' : ''}
-        // #75.8: cap results so type-ahead / dropdown endpoints never load the
-        // entire table. Caller can override via ?limit=... up to a hard ceiling.
-        $limit = min((int) ($filters['limit'] ?? 100), 500);
-        $query->limit($limit);
+${filterBlock}${limitBlock}
+
+        return $query->get()->toArray();
+    }`;
+    }
+    // #76: translatable branch — leftJoin the sidecar keyed by
+    // request locale + fallback locale, COALESCE the translated columns so
+    // missing translations fall back gracefully.
+    const translatedCols = snakeLookup.filter(f => translatableSet.has(f));
+    const plainCols = snakeLookup.filter(f => !translatableSet.has(f));
+    const mainTable = tx.mainTable;
+    const trTable = tx.translationTable;
+    const fk = tx.fkColumn;
+    const selectParts = [];
+    selectParts.push(`'${mainTable}.id'`);
+    for (const col of plainCols) {
+        if (col !== 'id')
+            selectParts.push(`'${mainTable}.${col}'`);
+    }
+    // COALESCE for translatable columns
+    for (const col of translatedCols) {
+        selectParts.push(`DB::raw('COALESCE(tr_current.\`${col}\`, tr_fallback.\`${col}\`) AS \`${col}\`')`);
+    }
+    const selectList = selectParts.join(',\n                ');
+    const sortIsTranslatable = translatableSet.has(sortCol);
+    const orderByLine = sortIsTranslatable
+        ? `->orderByRaw("COALESCE(tr_current.\`${sortCol}\`, tr_fallback.\`${sortCol}\`) ${sortDir.toUpperCase()}")`
+        : `->orderBy('${mainTable}.${sortCol}', '${sortDir}')`;
+    return `
+    /**
+     * Lightweight list-projection for dropdowns, type-aheads and autocomplete.
+     *
+     * Returns a flat array of {${returnShape}} rows (never a paginator). One or
+     * more of the returned columns is translatable, so this method LEFT JOINs
+     * the sidecar ${trTable} on both the request locale and the fallback
+     * locale, then COALESCEs the translated column so missing translations
+     * degrade gracefully instead of surfacing as NULL (#76).
+     *
+     * Default row cap is 100 (caller override via ?limit=..., hard ceiling
+     * 500 — see #75.8).
+     *
+     * @param  array<string, mixed>  $filters
+     * @return array<int, array{${returnShape}}>
+     */
+    public function lookup(array $filters = []): array
+    {
+        // #76: translatable columns live in '${trTable}'. Join once on the
+        // request locale and once on the configured fallback so missing
+        // translations degrade gracefully instead of returning NULL.
+        $locale = app()->getLocale();
+        $fallback = config('translatable.fallback_locale', 'en');
+
+        $query = $this->model::query()
+            ->select([
+                ${selectList},
+            ])
+            ->leftJoin('${trTable} as tr_current', function ($j) use ($locale) {
+                $j->on('tr_current.${fk}', '=', '${mainTable}.id')
+                  ->where('tr_current.locale', $locale);
+            })
+            ->leftJoin('${trTable} as tr_fallback', function ($j) use ($fallback) {
+                $j->on('tr_fallback.${fk}', '=', '${mainTable}.id')
+                  ->where('tr_fallback.locale', $fallback);
+            })
+            ${orderByLine};
+
+${filterBlock}${limitBlock}
 
         return $query->get()->toArray();
     }`;
@@ -719,9 +997,16 @@ function buildExtractTranslationsMethod(translatableFields, locales) {
     /**
      * Extract translation data from input.
      *
-     * Supports two formats:
-     *   1. Flat:   { "name:ja": "テスト", "name:en": "Test" }
-     *   2. Nested: { "translations": { "ja": { "name": "テスト" }, "en": { "name": "Test" } } }
+     * Preferred format (Astrotomic-native, flat):
+     *     [ "name:ja" => "テスト", "name:en" => "Test" ]
+     *
+     * Legacy format (DEPRECATED — will be removed in a future major release,
+     * see #78):
+     *     [ "translations" => [ "ja" => [ "name" => "テスト" ] ] ]
+     *
+     * The flat "attr:locale" form is what Astrotomic's own Translatable::fill()
+     * consumes natively (see Translatable::getAttributeAndLocale()), so sticking
+     * to it keeps request bodies, FormRequest rules and OpenAPI schemas flat.
      *
      * @return array<string, array<string, string>>  locale => [attr => value]
      */
@@ -731,15 +1016,24 @@ function buildExtractTranslationsMethod(translatableFields, locales) {
         $locales = [${localesArray}];
         $translations = [];
 
-        // Format 2: nested "translations" key
+        // Legacy wrapper format (#78 — deprecated). Still accepted for backward
+        // compat, but emits a deprecation notice so consumers migrate ahead of
+        // the v3.21.0 removal.
         if (isset($data['translations']) && is_array($data['translations'])) {
+            @trigger_error(
+                'The "translations" wrapper input format is deprecated (omnify #78). '
+                . 'Use the flat "attr:locale" form (e.g. "name:ja" => "..." ) which '
+                . 'Astrotomic Translatable consumes natively. This path will be '
+                . 'removed in omnify v3.21.0.',
+                E_USER_DEPRECATED
+            );
             $translations = $data['translations'];
             unset($data['translations']);
 
             return $translations;
         }
 
-        // Format 1: flat "attr:locale" keys
+        // Preferred: flat "attr:locale" keys
         foreach ($translatedAttributes as $attr) {
             foreach ($locales as $locale) {
                 $key = "{$attr}:{$locale}";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/ts",
-  "version": "3.19.4",
+  "version": "3.20.0",
   "description": "TypeScript model type generator from Omnify schemas.json",
   "type": "module",
   "main": "dist/index.js",