fix(crud): add/edit 返回普通对象(toObject/lean),不再抖出 mongoose Document 内部

add 用 create 返回 Document、edit 用 findByIdAndUpdate 返回 Document,下游 processResItem
的 {...item} 会把 $__/_doc/$isNew 等内部属性展开、真数据埋进 _doc。改:add 转 toObject、
edit 加 .lean()(与 list/get 一致)。响应回归干净 POJO。

package.json

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

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,
 }
 
 /** 字段可编辑状态 */
@@ -248,8 +249,6 @@ 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>
     /** 新增时的默认值（静态值或工厂函数） */
@@ -278,9 +277,11 @@ export interface IFieldConfig {
     rules?: IFieldRule[]          // 通用验证规则（前后端共用）
     /** tab 类型专用：每个 type 对应的子字段配置 */
     tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
-    /** tab 类型专用：自定义序列化(export 列 / `${key}_label` 用)，默认 JSON.stringify */
+    /** object 类型专用：嵌套字段组 */
-    stringify?: (value: any) => string
+    fields?: IFieldConfig[]
-    /** tab 类型专用：自定义反序列化(import 还原对象)，默认 JSON.parse */
+    /** array 类型专用：每个元素的字段配置(递归 IFieldConfig；元素无需 key，label 用作每项标题) */
+    item?: IFieldConfig
+    /** tab 类型专用：import 反序列化(把字符串还原成对象，如 xlsx 导入)，默认 JSON.parse */
     parse?: (text: string) => any
 }
 
@@ -318,6 +319,7 @@ export interface IPageResult<T> {
     page: number       // 当前页码
     pageSize: number   // 每页数量
     totalPages: number // 总页数
+    refs?: Record<string, Record<string, any>>  // relation 显示名字典: { moduleKey: { id: 显示名 } }，前端显示时查名，替代逐行 _label
 }
 
 // ============== 数据源查询协议 ==============

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) => {
@@ -60,8 +40,6 @@ export const defaultTypeHandlers: Record<string, IFieldTypeHandler> = {
             }
             return value
         },
-        // 本体原样下发对象(不再 stringify)；展示文本走 _label
-        resLabel: (value, field) => (field.stringify ?? JSON.stringify)(value),
     },
 }
 
@@ -221,31 +199,65 @@ 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)
-            }
         }
         return result
     }
 
     private async prepareResponseItems(items: any[]): Promise<any[]> {
         if (items.length === 0) return items
-        const populates = this.getRelationPopulates()
-        if (populates.length > 0 && this.dataSource.populateItems) {
-            await this.dataSource.populateItems(items, populates, this.root.crudRegistry)
-        }
         return Promise.all(items.map(item => this.processResItem(item)))
     }
 
     private async prepareResponseItem(item: any): Promise<any> {
         if (!item) return item
-        const populates = this.getRelationPopulates()
-        if (populates.length > 0 && this.dataSource.populateItems) {
-            await this.dataSource.populateItems([item], populates, this.root.crudRegistry)
-        }
         return this.processResItem(item)
     }
 
+    /**
+     * relation 字段(含 tab 分支里的嵌套 relation)批量解析成 refs 字典: { moduleKey: { id: 显示名 } }。
+     * 整页一次性、按模块各查一次 $in，去重；替代逐行注入 ${key}_label。前端显示时按 id 查名。
+     */
+    private async buildRefs(rows: any[]): Promise<Record<string, Record<string, any>>> {
+        if (rows.length === 0) return {}
+        const buckets = new Map<string, { labelKey: string; ids: Set<string> }>()
+        const add = (moduleKey: string, labelKey: string, id: any) => {
+            let b = buckets.get(moduleKey)
+            if (!b) buckets.set(moduleKey, (b = { labelKey, ids: new Set() }))
+            b.ids.add(String(id))
+        }
+        for (const row of rows) {
+            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>> = {}
+        for (const [moduleKey, b] of buckets) {
+            const dict: Record<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 d of res.list as any[]) dict[String(d._id)] = d[b.labelKey]
+            }
+            refs[moduleKey] = dict
+        }
+        return refs
+    }
+
+    /** 递归收集 relation 引用：relation 叶子直接收；tab 按 value.type 进选中分支继续下钻(覆盖嵌套/tab套tab) */
+    /** 单个 (字段,值) 收集 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)
+        }
+    }
+
     private excludeKeys(item: any, keys: string[]): any {
         if (keys.length === 0) return item
         const result = { ...item }
@@ -259,18 +271,6 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         return this.excludeKeys(item, this.fields.filter(f => f.hidden).map(f => f.key))
     }
 
-    private getRelationFields(): IFieldConfig[] {
-        return this.fields.filter(f => f.type === "relation" && f.relation)
-    }
-
-    private getRelationPopulates(): IShrimpPopulate[] {
-        return this.getRelationFields().map(f => ({
-            key: f.key,
-            moduleKey: f.relation!.moduleKey,
-            labelKey: f.relation!.labelKey,
-        }))
-    }
-
     private buildQuery(query?: IPageQuery & any): IShrimpQuery {
         const { keyword, page, pageSize, sortBy, sortOrder, filter, ownerId } = query || {}
         const p = page || 1
@@ -285,6 +285,11 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
             const stringLikeTypes = new Set(['string', 'textarea'])
             const where: Record<string, IShrimpCondition> = {}
             for (const [key, value] of Object.entries(filter)) {
+                // _id 始终放行精确过滤(单项查看/relation 跳转用)，无需配 filterable
+                if (key === '_id') {
+                    if (value != null && value !== '') where['_id'] = { eq: value }
+                    continue
+                }
                 const field = filterableFields.get(key)
                 if (!field) continue
                 if (value == null) continue
@@ -339,6 +344,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         const result = await this.dataSource.list(shrimpQuery)
         result.list = await this.prepareResponseItems(result.list)
         result.list = result.list.map(item => this.filterHidden(item))
+        result.refs = await this.buildRefs(result.list)
         return result
     }
 
@@ -395,17 +401,9 @@ 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)用其字符串文本替换对象本体，
+        // export 只取全量原始数据，不做序列化；结构化字段(如 tab)的字符串化交前端(生成 xlsx 时)。
-        // 列保持可读，且能被 import 的 reqFilter(parse)原样还原；去掉额外的 _label 列。
+        // import 端如传字符串，由各类型 reqFilter(如 tab 的 parse)还原。
-        const labelFields = this.fields.filter(f => this.getTypeHandler(f)?.resLabel)
+        return result.list.map(item => this.filterHidden(item))
-        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`]
-                delete row[`${f.key}_label`]
-            }
-            return row
-        })
     }
     async import(data?: T[], ownerId?: string): Promise<void> {
         if (!data || data.length === 0) return

src/forMongo/MongoShrimpCrud.ts

@@ -107,10 +107,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)