feat(tab): format 可拿到子 relation 解析名(批量,无 N+1)

tab 字段的 relation 子字段(如 sellType.goods)原只有 id,format 显示不了关联名。
新增 populateTabRelations：批量(每个关联模块一次 $in via crud.list)解析子 relation 的
labelKey 名，挂到 item.__tabRel[fieldKey][childKey]，作为 format 第二参 relLabels 传入；
不污染 tab 本体(避免回灌进库)，响应末尾删除 __tabRel。

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-server",
-    "version": "0.6.3",
+    "version": "0.6.5",
     "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)",
     "main": "dist/main/index.js",
     "types": "dist/main/index.d.ts",

src/IShrimpType.ts

@@ -278,9 +278,12 @@ export interface IFieldConfig {
     rules?: IFieldRule[]          // 通用验证规则（前后端共用）
     /** tab 类型专用：每个 type 对应的子字段配置 */
     tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
-    /** tab 类型专用：自定义序列化(export 列 / `${key}_label` 用)，默认 JSON.stringify */
+    /** tab 类型专用：展示文本(表格列 `${key}_label`)，给人看、可有损好看，默认 JSON.stringify。
+     *  relLabels 是已解析的子 relation 名(`{childKey: 名 | 名[]}`)，单选为名、multiple 为名数组 */
+    format?: (value: any, relLabels?: Record<string, any>) => string
+    /** tab 类型专用：export 序列化，须与 parse 可逆(机器往返)，默认 JSON.stringify */
     stringify?: (value: any) => string
-    /** tab 类型专用：自定义反序列化(import 还原对象)，默认 JSON.parse */
+    /** tab 类型专用：import 反序列化，须与 stringify 可逆，默认 JSON.parse */
     parse?: (text: string) => any
 }
 

src/Shrimp/ShrimpTableModule.ts

@@ -60,8 +60,9 @@ export const defaultTypeHandlers: Record<string, IFieldTypeHandler> = {
             }
             return value
         },
-        // 本体原样下发对象(不再 stringify)；展示文本走 _label
-        resLabel: (value, field) => (field.stringify ?? JSON.stringify)(value),
+        // 本体原样下发对象(不再 stringify)；展示文本走 _label，用 format(给人看,可有损)
+        // 第二参是已批量解析的子 relation 名(item.__tabRel[field.key])，让 format 能显示关联名而非 id
+        resLabel: (value, field, item) => (field.format ?? JSON.stringify)(value, item?.__tabRel?.[field.key]),
     },
 }
 
@@ -225,6 +226,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
                 result[`${field.key}_label`] = handler.resLabel(result[field.key], field, result)
             }
         }
+        delete result.__tabRel // 临时挂的子 relation 解析结果，不下发
         return result
     }
 
@@ -234,6 +236,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         if (populates.length > 0 && this.dataSource.populateItems) {
             await this.dataSource.populateItems(items, populates, this.root.crudRegistry)
         }
+        await this.populateTabRelations(items)
         return Promise.all(items.map(item => this.processResItem(item)))
     }
 
@@ -243,9 +246,62 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         if (populates.length > 0 && this.dataSource.populateItems) {
             await this.dataSource.populateItems([item], populates, this.root.crudRegistry)
         }
+        await this.populateTabRelations([item])
         return this.processResItem(item)
     }
 
+    /**
+     * 解析 tab 字段里 relation 子字段的名字，批量(每个关联模块一次 $in)，
+     * 挂到 item.__tabRel[fieldKey][childKey]，供该字段的 format 第二参使用。
+     * 不污染 tab 本体对象(避免回灌进库)，__tabRel 在 processResItem 末尾删除。
+     */
+    private async populateTabRelations(items: any[]): Promise<void> {
+        const tabFields = this.fields.filter(f => f.type === ShrimpFieldTypes.Tab && Array.isArray(f.tabs))
+        if (tabFields.length === 0 || items.length === 0) return
+
+        const need = new Map<string, { labelKey: string; ids: Set<string> }>()
+        const refs: { item: any; fieldKey: string; childKey: string; moduleKey: string; multiple: boolean }[] = []
+        for (const item of items) {
+            for (const tf of tabFields) {
+                const val = item[tf.key]
+                if (!val || typeof val !== "object") continue
+                const tab = tf.tabs!.find(t => t.key === val.type)
+                if (!tab) continue
+                for (const child of tab.fields) {
+                    if (child.type !== ShrimpFieldTypes.Relation || !child.relation || val[child.key] == null) continue
+                    const { moduleKey, labelKey } = child.relation
+                    let bucket = need.get(moduleKey)
+                    if (!bucket) need.set(moduleKey, (bucket = { labelKey, ids: new Set() }))
+                    const cv = val[child.key]
+                    ;(Array.isArray(cv) ? cv : [cv]).forEach((id: any) => id != null && bucket!.ids.add(String(id)))
+                    refs.push({ item, fieldKey: tf.key, childKey: child.key, moduleKey, multiple: !!child.multiple })
+                }
+            }
+        }
+        if (refs.length === 0) return
+
+        const labelMaps = new Map<string, Map<string, any>>()
+        for (const [moduleKey, b] of need) {
+            const m = new Map<string, any>()
+            const crud = this.root.crudRegistry.get(moduleKey)
+            if (crud && b.ids.size > 0) {
+                const res = await crud.list({ where: { _id: { in: Array.from(b.ids) } }, limit: b.ids.size })
+                for (const doc of res.list as any[]) m.set(String(doc._id), doc[b.labelKey])
+            }
+            labelMaps.set(moduleKey, m)
+        }
+
+        for (const ref of refs) {
+            const m = labelMaps.get(ref.moduleKey)!
+            const cv = ref.item[ref.fieldKey][ref.childKey]
+            const label = ref.multiple
+                ? (Array.isArray(cv) ? cv.map((id: any) => m.get(String(id)) ?? null) : [])
+                : m.get(String(cv)) ?? null
+            const bag = (ref.item.__tabRel ||= {})
+            ;(bag[ref.fieldKey] ||= {})[ref.childKey] = label
+        }
+    }
+
     private excludeKeys(item: any, keys: string[]): any {
         if (keys.length === 0) return item
         const result = { ...item }
@@ -395,13 +451,15 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         delete shrimpQuery.limit
         const result = await this.dataSource.list(shrimpQuery)
         result.list = await this.prepareResponseItems(result.list)
-        // 导出是"给人看"的边界：把带 resLabel 的结构化字段(如 tab)用其字符串文本替换对象本体，
-        // 列保持可读，且能被 import 的 reqFilter(parse)原样还原；去掉额外的 _label 列。
+        // 导出是机器往返的边界：结构化字段(如 tab)用可逆的 stringify 序列化(默认 JSON)，
+        // import 端的 reqFilter(parse) 能原样还原；展示用的 _label 不进导出，去掉。
         const labelFields = this.fields.filter(f => this.getTypeHandler(f)?.resLabel)
         return result.list.map(item => {
             const row = this.filterHidden(item)
             for (const f of labelFields) {
-                if (row[`${f.key}_label`] !== undefined) row[f.key] = row[`${f.key}_label`]
+                if (row[f.key] !== undefined && typeof row[f.key] === "object") {
+                    row[f.key] = (f.stringify ?? JSON.stringify)(row[f.key])
+                }
                 delete row[`${f.key}_label`]
             }
             return row