fix(populate): 跳过空串关联 id，避免可选 Relation 存 "" 时 $in 转 ObjectId 抛 CastError 整页 500

bump 0.7.11

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-server",
-    "version": "0.6.10",
+    "version": "0.7.11",
     "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)",
     "main": "dist/main/index.js",
     "types": "dist/main/index.d.ts",
@@ -24,21 +24,29 @@
         "typecheck": "tsc --noEmit"
     },
     "peerDependencies": {
+        "bcrypt": "^5 || ^6",
         "express": "^4 || ^5",
-        "mongoose": "^6 || ^7 || ^8",
         "jsonwebtoken": "^8 || ^9",
-        "bcrypt": "^5 || ^6"
+        "mongoose": "^6 || ^7 || ^8"
     },
     "peerDependenciesMeta": {
-        "express": { "optional": true },
-        "mongoose": { "optional": true },
-        "jsonwebtoken": { "optional": true },
-        "bcrypt": { "optional": true }
+        "express": {
+            "optional": true
+        },
+        "mongoose": {
+            "optional": true
+        },
+        "jsonwebtoken": {
+            "optional": true
+        },
+        "bcrypt": {
+            "optional": true
+        }
     },
     "devDependencies": {
+        "@types/bcrypt": "^5.0.0",
         "@types/express": "^4.17.21",
         "@types/jsonwebtoken": "^9.0.0",
-        "@types/bcrypt": "^5.0.0",
         "@types/node": "^20.0.0",
         "bcrypt": "^5.1.1",
         "express": "^4.19.0",

src/IShrimpType.ts

@@ -235,8 +235,9 @@ export const ShrimpFieldTypes = {
     Textarea: "textarea" as ShrimpFieldType,
     Password: "password" as ShrimpFieldType,
     Relation: "relation" as ShrimpFieldType,
-    Json: "json" as ShrimpFieldType,
     Tab: "tab" as ShrimpFieldType,
+    Object: "object" as ShrimpFieldType,
+    Array: "array" as ShrimpFieldType,
 }
 
 /** 字段可编辑状态 */
@@ -276,6 +277,10 @@ export interface IFieldConfig {
     rules?: IFieldRule[]          // 通用验证规则（前后端共用）
     /** tab 类型专用：每个 type 对应的子字段配置 */
     tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
+    /** object 类型专用：嵌套字段组 */
+    fields?: IFieldConfig[]
+    /** array 类型专用：每个元素的字段配置(递归 IFieldConfig；元素无需 key，label 用作每项标题) */
+    item?: IFieldConfig
     /** tab 类型专用：import 反序列化(把字符串还原成对象，如 xlsx 导入)，默认 JSON.parse */
     parse?: (text: string) => any
 }

src/Shrimp/ShrimpTableModule.ts

@@ -27,26 +27,6 @@ export const defaultTypeHandlers: Record<string, IFieldTypeHandler> = {
     [ShrimpFieldTypes.Boolean]: {
         defaultValue: false,
     },
-    [ShrimpFieldTypes.Json]: {
-        reqFilter: (value) => {
-            if (value == null || value === "") return undefined
-            if (typeof value === "string") {
-                try {
-                    return JSON.parse(value)
-                } catch {
-                    throw new ShrimpError({ t: 'shrimp.invalidJson' })
-                }
-            }
-            return value
-        },
-        resFilter: (value) => {
-            if (value == null) return value
-            if (typeof value === "object") {
-                return JSON.stringify(value)
-            }
-            return value
-        },
-    },
     [ShrimpFieldTypes.Tab]: {
         // tab 是结构化字段：库里/响应/编辑全程是对象，只在"给人看"的边界(import/export/label)走字符串。
         reqFilter: (value, field) => {
@@ -88,9 +68,27 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         return ShrimpTableModule.typeHandlers.get(field.type)
     }
 
+    /** 按类型递归判定"空":tab=没选type / object=所有子字段都空 / array=无元素或所有元素都空(多维递归)/ 标量=null|'' / 空数组 */
+    private isEmptyValue(field: IFieldConfig, value: any): boolean {
+        if (value === undefined || value === null) return true
+        switch (field.type) {
+            case ShrimpFieldTypes.Tab:
+                return typeof value !== "object" || value.type == null
+            case ShrimpFieldTypes.Object:
+                if (typeof value !== "object" || !Array.isArray(field.fields)) return true
+                return field.fields.every(f => this.isEmptyValue(f, value[f.key]))
+            case ShrimpFieldTypes.Array:
+                if (!Array.isArray(value) || value.length === 0) return true
+                return field.item ? value.every(el => this.isEmptyValue(field.item!, el)) : false
+            default:
+                // 标量/relation/select:'' 或空数组(multiple)算空；0、false 不算空
+                return value === "" || (Array.isArray(value) && value.length === 0)
+        }
+    }
+
     /** 前置验证 */
     private async validateField(field: IFieldConfig, value: any, item: Record<string, any>): Promise<ILabel | null> {
-        const isEmpty = value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0)
+        const isEmpty = this.isEmptyValue(field, value)
 
         if (field.required && isEmpty) {
             return field.rules?.find(r => r.required)?.message || { t: 'shrimp.fieldRequired', params: { field: field.label } }
@@ -171,8 +169,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
                 result[field.key] = await handler.reqFilter(result[field.key], field, result)
             }
 
-            const fieldErr = await this.validateField(field, result[field.key], result)
-            if (fieldErr) throw new ShrimpError(fieldErr)
+            await this.validateNode(field, result[field.key], [field.key], result)
 
             if (handler?.validate && result[field.key] !== undefined) {
                 const err = await handler.validate(result[field.key], field, result)
@@ -201,8 +198,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
                 result[field.key] = await handler.reqFilter(result[field.key], field, result)
             }
 
-            const fieldErr = await this.validateField(field, result[field.key], result)
-            if (fieldErr) throw new ShrimpError(fieldErr)
+            await this.validateNode(field, result[field.key], [field.key], result)
 
             if (handler?.validate) {
                 const err = await handler.validate(result[field.key], field, result)
@@ -212,6 +208,35 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         return result
     }
 
+    /** 递归校验:本节点 validateField，出错即抛(带 path)；再下钻复合(tab/object/array)子节点。第一版 fail-fast */
+    private async validateNode(field: IFieldConfig, value: any, path: (string | number)[], rootItem: Record<string, any>): Promise<void> {
+        const err = await this.validateField(field, value, rootItem)
+        // 出错只发字段名(label) + i18n key 的 message，不把开发用的 path 拼进可见文案。
+        // path 仍递归往下传(供将来 inline 标红按结构化方式携带，不在这里塞进 message)。
+        if (err) throw new ShrimpError(err)
+        // 空的复合(走到这必是非必填)→ 不下钻校验子：整个结构缺席，里面的 required 不该触发
+        if (this.isEmptyValue(field, value)) return
+        for (const child of this.childrenOf(field, value)) {
+            await this.validateNode(child.field, child.value, [...path, child.key], rootItem)
+        }
+    }
+
+    /** 复合类型吐出子 (字段, 值) 对：tab 选中分支的 fields / object 的 fields / array 每个元素套 item。叶子或空 → [] */
+    private childrenOf(field: IFieldConfig, value: any): { key: string | number; field: IFieldConfig; value: any }[] {
+        if (value == null || typeof value !== "object") return []
+        if (field.type === ShrimpFieldTypes.Tab && Array.isArray(field.tabs)) {
+            const branch = field.tabs.find(t => t.key === value.type)
+            return branch ? branch.fields.map(f => ({ key: f.key, field: f, value: value[f.key] })) : []
+        }
+        if (field.type === ShrimpFieldTypes.Object && Array.isArray(field.fields)) {
+            return field.fields.map(f => ({ key: f.key, field: f, value: value[f.key] }))
+        }
+        if (field.type === ShrimpFieldTypes.Array && field.item && Array.isArray(value)) {
+            return value.map((el, i) => ({ key: i as number, field: field.item!, value: el }))
+        }
+        return []
+    }
+
     private async processResItem(item: Record<string, any>): Promise<Record<string, any>> {
         const result = { ...item }
         for (const field of this.fields) {
@@ -246,7 +271,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
             b.ids.add(String(id))
         }
         for (const row of rows) {
-            this.collectRefs(this.fields, (k) => row[k], add)
+            for (const f of this.fields) this.collectOne(f, row[f.key], add)
         }
         if (buckets.size === 0) return {}
         const refs: Record<string, Record<string, any>> = {}
@@ -263,16 +288,18 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
     }
 
     /** 递归收集 relation 引用：relation 叶子直接收；tab 按 value.type 进选中分支继续下钻(覆盖嵌套/tab套tab) */
-    private collectRefs(fields: IFieldConfig[], valueOf: (key: string) => any, add: (moduleKey: string, labelKey: string, id: any) => void): void {
-        for (const f of fields) {
-            const v = valueOf(f.key)
-            if (v == null) continue
-            if (f.type === "relation" && f.relation) {
-                ;(Array.isArray(v) ? v : [v]).forEach((id: any) => id != null && add(f.relation!.moduleKey, f.relation!.labelKey, id))
-            } else if (f.type === ShrimpFieldTypes.Tab && Array.isArray(f.tabs) && typeof v === "object") {
-                const branch = f.tabs.find(t => t.key === v.type)
-                if (branch) this.collectRefs(branch.fields, (k) => v[k], add)
-            }
+    /** 单个 (字段,值) 收集 relation 引用，递归复合(tab/object/array)。array 的 item 无 key —— 元素即值 */
+    private collectOne(f: IFieldConfig, v: any, add: (moduleKey: string, labelKey: string, id: any) => void): void {
+        if (v == null) return
+        if (f.type === "relation" && f.relation) {
+            ;(Array.isArray(v) ? v : [v]).forEach((id: any) => id != null && add(f.relation!.moduleKey, f.relation!.labelKey, id))
+        } else if (f.type === ShrimpFieldTypes.Tab && Array.isArray(f.tabs) && typeof v === "object") {
+            const branch = f.tabs.find(t => t.key === v.type)
+            if (branch) for (const c of branch.fields) this.collectOne(c, v[c.key], add)
+        } else if (f.type === ShrimpFieldTypes.Object && Array.isArray(f.fields) && typeof v === "object") {
+            for (const c of f.fields) this.collectOne(c, v[c.key], add)
+        } else if (f.type === ShrimpFieldTypes.Array && f.item && Array.isArray(v)) {
+            for (const el of v) this.collectOne(f.item, el, add)
         }
     }
 
@@ -286,7 +313,21 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
     }
 
     private filterHidden(item: any): any {
-        return this.excludeKeys(item, this.fields.filter(f => f.hidden).map(f => f.key))
+        // __v 是 mongoose 版本键，前端无用，统一剥掉(连同 hidden 字段)
+        return this.excludeKeys(item, ["__v", ...this.fields.filter(f => f.hidden).map(f => f.key)])
+    }
+
+    /** 递归收集标了 filterable 的字段 → 点路径(object 子 / tab 分支子)。array 暂不下钻(后续) */
+    private collectFilterablePaths(fields: IFieldConfig[], base: string[], out: Map<string, IFieldConfig>): void {
+        for (const f of fields) {
+            const path = [...base, f.key]
+            if (f.filterable) out.set(path.join("."), f)
+            if (f.type === ShrimpFieldTypes.Tab && Array.isArray(f.tabs)) {
+                for (const t of f.tabs) this.collectFilterablePaths(t.fields, path, out)
+            } else if (f.type === ShrimpFieldTypes.Object && Array.isArray(f.fields)) {
+                this.collectFilterablePaths(f.fields, path, out)
+            }
+        }
     }
 
     private buildQuery(query?: IPageQuery & any): IShrimpQuery {
@@ -299,7 +340,9 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         }
 
         if (filter && typeof filter === 'object') {
-            const filterableFields = new Map(this.fields.filter(f => f.filterable).map(f => [f.key, f]))
+            // filterable 路径(含 object/tab 嵌套叶子，点路径如 condition.level)→ 白名单。点路径本就是 mongoose 嵌套查询，翻译逻辑不变
+            const filterableFields = new Map<string, IFieldConfig>()
+            this.collectFilterablePaths(this.fields, [], filterableFields)
             const stringLikeTypes = new Set(['string', 'textarea'])
             const where: Record<string, IShrimpCondition> = {}
             for (const [key, value] of Object.entries(filter)) {

src/forMongo/MongoShrimpCrud.ts

@@ -79,9 +79,10 @@ export class MongoShrimpCrud<T> implements ShrimpCrud<T> {
             const allRefIds = new Set<string>()
             for (const item of items) {
                 const val = (item as any)[pop.key]
+                // 跳过空串：可选 Relation 常存 ""，混进 { _id: { $in } } 会让 Mongoose 转 ObjectId 抛 CastError、整页 500。
                 if (Array.isArray(val)) {
-                    val.forEach((id: any) => { if (id != null) allRefIds.add(String(id)) })
-                } else if (val != null) {
+                    val.forEach((id: any) => { if (id != null && id !== "") allRefIds.add(String(id)) })
+                } else if (val != null && val !== "") {
                     allRefIds.add(String(val))
                 }
             }
@@ -107,10 +108,11 @@ export class MongoShrimpCrud<T> implements ShrimpCrud<T> {
         return await this.model.findById(id).lean() as T | null
     }
     async add(item: Omit<T, '_id'>): Promise<T> {
-        return await this.model.create(item)
+        const doc = await this.model.create(item)
+        return doc.toObject() as T   // 转普通对象，否则下游 {...item} 展开的是 mongoose Document 内部($__/_doc/$isNew)
     }
     async edit(id: string, item: Partial<T>): Promise<T | null> {
-        return await this.model.findByIdAndUpdate(id, item, { new: true })
+        return await this.model.findByIdAndUpdate(id, item, { new: true }).lean() as T | null
     }
     async delete(id: string): Promise<boolean> {
         const result = await this.model.findByIdAndDelete(id)

test/crudRegistry.test.ts

@@ -34,6 +34,7 @@ describe("crudRegistry 自动登记", () => {
         await productCrud.add({ code: "P001", tagIds: [t1._id, t2._id] } as any)
 
         const result = await productModule.list({})
-        expect((result.list[0] as any).tagIds_label).toEqual(["热门", "促销"])
+        // _label 逐行机制已退场:relation 显示名走整页 refs 字典(refs[moduleKey][id])
+        expect((result as any).refs?.tag).toEqual({ [t1._id]: "热门", [t2._id]: "促销" })
     })
 })