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。

docs/array-object-field-design.md

@@ -0,0 +1,74 @@
+# Array / Object 字段类型 —— 设计草案（暂未实现）
+
+> 状态：**搁置待需求**。当前没有字段需要它（powers 已用自定义类型 `powers` 解决，dropList 用自定义 type + Mixed 解决）。
+> 等出现「既要结构化数组/对象、又要框架级递归校验 + 自动表单渲染」的真实字段时，再按本文档实现。
+
+## 背景：为什么有这份文档
+
+### 触发点：powers 字段类型错误
+角色权限字段 `powers` 实际存的是权限 key 数组（`string[]`），但 `roleFields` 里错标成 `type: "string"`。在「字段前置验证」（`ShrimpTableModule.validateField`）加上类型校验后，String 分支 `typeof value !== 'string'` 把数组判为类型错误。
+
+### 已采用的解法（v0.6.2，已上线）
+把 powers 改成自定义类型 `type: "powers"`。原理：`validateField` 的类型校验是 switch-case，只认 string/number/boolean/date 四个内置类型，**任何自定义 type 不匹配任何 case → 自动跳过类型校验**；且未注册 typeHandler → 无 reqFilter/resFilter → 数组原样存取，不破坏前端权限树。required/rules 仍生效。
+
+这是最小解，powers 问题已闭环。**本文档的 array/object 不是为 powers——powers 不需要它**。
+
+## 何时才该实现本设计
+
+满足以下条件之一再做，否则属于过度设计：
+- 出现一个字段，值是**结构化数组**（如 `[{itemId,count,weight}]`），且希望**框架级递归校验** + **自动按子字段渲染表单**（而非像 dropList 那样手写专属前端组件 + 跳过校验）。
+- 多个字段重复出现「对象数组」形态，自定义类型方案的手写成本变得不划算。
+
+判别：需求会把"要不要去重 / 要不要嵌套 / 摘要怎么显示"这些问题自然定下来，比现在凭空猜更准。
+
+## 设计要点（实现时参考）
+
+### 与 multiple 的关系（关键，A 方案）
+`multiple` 与 `array` 是**两个正交维度，不合并**：
+- `multiple`：**选择基数修饰符**，依附 select/relation，含义"从固定候选集里选几个"，**集合语义（不可重复）**。保持现状不动。
+- `array`：**值形态类型**，开放列表，元素类型由 `item` 定，可嵌套。
+- 判别标准：值来自**固定选项集**→ select/relation + multiple；值是**开放列表**→ array。
+
+### 后端 shrimp-server
+
+**1. `IShrimpType.ts`**
+```ts
+// ShrimpFieldTypes 增加
+Array: "array", Object: "object"
+// IFieldConfig 增加（复用 IFieldConfig 自身递归 —— tab 的 tabs[].fields 已有先例）
+item?: IFieldConfig       // array 元素的类型定义
+fields?: IFieldConfig[]   // object 的子字段定义
+unique?: boolean          // array 是否去重（集合语义，默认 false）
+```
+
+**2. `ShrimpTableModule.validateField` 递归校验**
+- `array` 分支：值必须是数组 → 对每个元素递归 `validateField(field.item, 元素, item)`；`unique:true` 查重报错；min/max 已支持数组长度。
+- `object` 分支：值必须是对象 → 对 `field.fields` 每个子字段递归 `validateField(子字段, value[子key], value)`。
+- **multiple 特殊处理**：`multiple:true` 字段值是数组，但元素校验走字段自己的 options/relation；在类型 switch 里 multiple 字段**跳过标量类型检查**（防止 powers 那类问题复发）。
+
+**3. typeHandler**
+- array/object **不注册 resFilter**（不同于 json 会 `JSON.stringify`）——结构原样进出，前端直接拿到结构化数据。
+
+### 前端 shrimp-admin
+
+字段渲染机制：约定式自动注册 —— `components/fields/Field<X>.vue` → 自动注册类型 `<x>`（首字母小写）。`vueAdmin.getFieldComponent(moduleKey, type, key)` 按 type 取组件，未知 type 兜底为 string。**范本见 `FieldTab.vue`**：用 `getFieldComponent(childField.type)` 递归渲染子字段。
+
+**1. `components/fields/FieldArray.vue`（新）** 类型 `array`
+- edit：列表渲染，每项 `getFieldComponent(field.item.type)` 递归 + 增/删行。
+- display：摘要（JSON 截断，或「N 项」）。
+- props 标准接口：`{field, modelValue, mode:'display'|'edit'|'filter', disabled}`。
+
+**2. `components/fields/FieldObject.vue`（新）** 类型 `object`
+- edit：按 `field.fields` 逐个 `el-form-item` + 递归组件（≈ FieldTab 去掉 tab 选择层）。
+- display：摘要。
+
+**递归天然支持嵌套**：array 的 `item` 可以是 `{type:"object",fields:[...]}`（对象数组），object 的某字段可以是 `{type:"array",...}`，任意层级。
+
+### powers 若迁移到 array（可选，非必须）
+`{ key:"powers", type:"array", item:{type:"string"}, unique:true }`（集合去重）。但 powers 现用 `"powers"` 自定义类型已工作，**无强需求迁移**。
+
+## 发版
+实现并前后端验证（后端 `tsc --noEmit`、前端 `vue-tsc`/build）通过后，shrimp-server + shrimp-admin 一起升 **0.7.0**，业务项目引用同步更新。
+
+## 关联
+- 另一个已知待办：`field.validate`（字段级自定义验证函数，`IFieldConfig.validate`）在 `IShrimpType.ts` 定义了，但 `prepareAddItem`/`prepareEditItem` 只调了 `handler.validate`（typeHandler 级），**`field.validate` 从未被调用** —— 漏接，待补。

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-server",
-    "version": "0.6.2",
+    "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

@@ -248,6 +248,8 @@ export interface IFieldTypeHandler {
     reqFilter?: (value: any, field: IFieldConfig, item: Record<string, any>) => any | Promise<any>
     /** 响应过滤：数据库取出 → 返回前端前转换（如密码脱敏为 ***、日期格式化） */
     resFilter?: (value: any, field: IFieldConfig, item: Record<string, any>) => any
+    /** 响应附带的展示文本：返回值写入 `${key}_label`，本体不变。用于结构化字段(如 tab)给人看的字符串，前端表格直接显示，不必自己序列化 */
+    resLabel?: (value: any, field: IFieldConfig, item: Record<string, any>) => string
     /** 验证：保存前校验，返回错误 ILabel 或 null（可直接返回字面字符串、{t}、{tc} 等） */
     validate?: (value: any, field: IFieldConfig, item: Record<string, any>) => ILabel | null | Promise<ILabel | null>
     /** 新增时的默认值（静态值或工厂函数） */
@@ -276,6 +278,13 @@ export interface IFieldConfig {
     rules?: IFieldRule[]          // 通用验证规则（前后端共用）
     /** tab 类型专用：每个 type 对应的子字段配置 */
     tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
+    /** 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 反序列化，须与 stringify 可逆，默认 JSON.parse */
+    parse?: (text: string) => any
 }
 
 /** 通用验证规则（前后端共用） */

src/Shrimp/ShrimpTableModule.ts

@@ -48,24 +48,21 @@ export const defaultTypeHandlers: Record<string, IFieldTypeHandler> = {
         },
     },
     [ShrimpFieldTypes.Tab]: {
-        reqFilter: (value) => {
+        // tab 是结构化字段：库里/响应/编辑全程是对象，只在"给人看"的边界(import/export/label)走字符串。
+        reqFilter: (value, field) => {
             if (value == null || value === "") return undefined
             if (typeof value === "string") {
                 try {
-                    return JSON.parse(value)
+                    return (field.parse ?? JSON.parse)(value)
                 } catch {
                     throw new ShrimpError({ t: 'shrimp.invalidJson' })
                 }
             }
             return value
         },
-        resFilter: (value) => {
+        // 本体原样下发对象(不再 stringify)；展示文本走 _label，用 format(给人看,可有损)
-            if (value == null) return value
+        // 第二参是已批量解析的子 relation 名(item.__tabRel[field.key])，让 format 能显示关联名而非 id
-            if (typeof value === "object") {
+        resLabel: (value, field, item) => (field.format ?? JSON.stringify)(value, item?.__tabRel?.[field.key]),
-                return JSON.stringify(value)
-            }
-            return value
-        },
     },
 }
 
@@ -114,21 +111,20 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
             }
         }
 
-        switch (field.type) {
+        // multiple 字段值是数组，类型校验需逐元素进行（与上面 options 校验保持一致）；
-            case ShrimpFieldTypes.String:
+        // 非 multiple 则整体校验单值。否则数组会被标量类型分支整体判为类型错误。
-                if (typeof value !== 'string') return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+        const checkType = (v: any): boolean => {
-                break
+            switch (field.type) {
-            case ShrimpFieldTypes.Number:
+                case ShrimpFieldTypes.String: return typeof v === 'string'
-                if (typeof value !== 'number' || Number.isNaN(value)) return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+                case ShrimpFieldTypes.Number: return typeof v === 'number' && !Number.isNaN(v)
-                break
+                case ShrimpFieldTypes.Boolean: return typeof v === 'boolean'
-            case ShrimpFieldTypes.Boolean:
+                case ShrimpFieldTypes.Date: return typeof v === 'number' || v instanceof Date || !isNaN(Date.parse(v))
-                if (typeof value !== 'boolean') return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+                default: return true // 非内置标量类型（relation/json/自定义等）不在此校验
-                break
+            }
-            case ShrimpFieldTypes.Date:
+        }
-                if (typeof value !== 'number' && !(value instanceof Date) && isNaN(Date.parse(value))) {
+        const typeTargets = field.multiple && Array.isArray(value) ? value : [value]
-                    return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+        for (const v of typeTargets) {
-                }
+            if (!checkType(v)) return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
-                break
         }
 
         if (field.rules) {
@@ -226,7 +222,11 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
             if (handler?.resFilter && result[field.key] !== undefined) {
                 result[field.key] = await handler.resFilter(result[field.key], field, result)
             }
+            if (handler?.resLabel && result[field.key] !== undefined) {
+                result[`${field.key}_label`] = handler.resLabel(result[field.key], field, result)
+            }
         }
+        delete result.__tabRel // 临时挂的子 relation 解析结果，不下发
         return result
     }
 
@@ -236,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)))
     }
 
@@ -245,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 }
@@ -397,7 +451,19 @@ 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)
-        return result.list.map(item => this.filterHidden(item))
+        // 导出是机器往返的边界：结构化字段(如 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] !== undefined && typeof row[f.key] === "object") {
+                    row[f.key] = (f.stringify ?? JSON.stringify)(row[f.key])
+                }
+                delete row[`${f.key}_label`]
+            }
+            return row
+        })
     }
     async import(data?: T[], ownerId?: string): Promise<void> {
         if (!data || data.length === 0) return