fix(pkg): 删掉 shrimp-server 对自身的 git 依赖(致 npm install OOM)

dependencies 误列了 shrimp-server 自引用(#v0.7.4)→ arborist 顺着自引用无限解析依赖树、堆爆 OOM。真正依赖全在 peerDependencies,该块整体删除。含 0.7.6 的 isEmptyValue 递归判空。
feat(required): 按类型递归判定空(tab/object/array 各自语义)
2026-06-30 17:22:39 +08:00 · 2026-06-30 16:52:08 +08:00 · 2026-06-30 16:01:20 +08:00 · 2026-06-30 15:17:58 +08:00 · 2026-06-30 14:49:48 +08:00 · 2026-06-30 14:09:44 +08:00
5 changed files with 332 additions and 239 deletions
@@ -1,6 +1,6 @@
 {
    "name": "shrimp-server",
-    "version": "0.6.7",
+    "version": "0.7.7",
    "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",
@@ -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,11 +277,11 @@ export interface IFieldConfig {
    rules?: IFieldRule[]          // 通用验证规则（前后端共用）
    /** tab 类型专用：每个 type 对应的子字段配置 */
    tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
-    /** tab 类型专用：展示文本(表格列 `${key}_label`)，给人看、可有损好看，默认 JSON.stringify */
-    format?: (value: any) => string
-    /** tab 类型专用：export 序列化，须与 parse 可逆(机器往返)，默认 JSON.stringify */
-    stringify?: (value: any) => string
-    /** tab 类型专用：import 反序列化，须与 stringify 可逆，默认 JSON.parse */
+    /** object 类型专用：嵌套字段组 */
+    fields?: IFieldConfig[]
+    /** array 类型专用：每个元素的字段配置(递归 IFieldConfig；元素无需 key，label 用作每项标题) */
+    item?: IFieldConfig
+    /** tab 类型专用：import 反序列化(把字符串还原成对象，如 xlsx 导入)，默认 JSON.parse */
    parse?: (text: string) => any
 }

@@ -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，用 format(给人看,可有损)
-        resLabel: (value, field) => (field.format ?? JSON.stringify)(value),
    },
 }

@@ -90,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 } }
@@ -173,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)
@@ -203,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)
@@ -214,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) {
@@ -221,9 +244,6 @@ 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
    }
@@ -239,23 +259,21 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
    }

    /**
-     * 顶层 relation 字段批量解析成 refs 字典: { moduleKey: { id: 显示名 } }。
+     * relation 字段(含 tab 分支里的嵌套 relation)批量解析成 refs 字典: { moduleKey: { id: 显示名 } }。
     * 整页一次性、按模块各查一次 $in，去重；替代逐行注入 ${key}_label。前端显示时按 id 查名。
     */
    private async buildRefs(rows: any[]): Promise<Record<string, Record<string, any>>> {
-        const relFields = this.getRelationFields()
-        if (relFields.length === 0 || rows.length === 0) return {}
+        if (rows.length === 0) return {}
        const buckets = new Map<string, { labelKey: string; ids: Set<string> }>()
-        for (const row of rows) {
-            for (const f of relFields) {
-                const v = row[f.key]
-                if (v == null) continue
-                const { moduleKey, labelKey } = f.relation!
-                let b = buckets.get(moduleKey)
-                if (!b) buckets.set(moduleKey, (b = { labelKey, ids: new Set() }))
-                ;(Array.isArray(v) ? v : [v]).forEach((id: any) => id != null && b!.ids.add(String(id)))
-            }
+        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> = {}
@@ -269,6 +287,22 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
        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 }
@@ -279,11 +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)])
    }

-    private getRelationFields(): IFieldConfig[] {
-        return this.fields.filter(f => f.type === "relation" && f.relation)
+    /** 递归收集标了 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 {
@@ -296,10 +340,17 @@ 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)) {
+                // _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
@@ -411,19 +462,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)
-        // 导出是机器往返的边界：结构化字段(如 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
-        })
+        // export 只取全量原始数据，不做序列化；结构化字段(如 tab)的字符串化交前端(生成 xlsx 时)。
+        // import 端如传字符串，由各类型 reqFilter(如 tab 的 parse)还原。
+        return result.list.map(item => this.filterHidden(item))
    }
    async import(data?: T[], ownerId?: string): Promise<void> {
        if (!data || data.length === 0) return
@@ -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)
Author	SHA1	Message	Date
wc24	0f2b4d6428	fix(pkg): 删掉 shrimp-server 对自身的 git 依赖(致 npm install OOM) dependencies 误列了 shrimp-server 自引用(#v0.7.4)→ arborist 顺着自引用无限解析依赖树、堆爆 OOM。真正依赖全在 peerDependencies,该块整体删除。含 0.7.6 的 isEmptyValue 递归判空。	2026-06-30 17:22:39 +08:00
wc24	06aec7f0dc	feat(required): 按类型递归判定空(tab/object/array 各自语义) isEmptyValue(field,value) 递归: tab=没选type / object=所有子字段都空 / array=无元素或所有元素都空(多维递归) / 标量=null\|''/空数组(0、false 不算空)。required=!isEmpty 自动对所有类型生效。validateNode: 空的复合(非必填)不下钻校验子(整个结构缺席)。	2026-06-30 16:52:08 +08:00
wc24	172c49816e	feat(filter): 嵌套 filterable 叶子 → 点路径过滤(object/tab) collectFilterablePaths 递归收集标了 filterable 的字段(object 子/tab 分支子)连同点路径; buildQuery 白名单从顶层字段扩成路径(点路径本就是 mongoose 嵌套查询，翻译逻辑不变)。 array 下钻、tab 判别值过滤留后续。	2026-06-30 16:01:20 +08:00
wc24	a8cd07f851	fix(validate): 错误信息不再拼开发用的 [path]，回归干净字段名+i18n 校验错只发 {t:i18nKey, params:{field:label}}(不能为空走语言包 key、字段名走 label)，不把 groups.0.title 这种路径塞进可见文案。path 仍递归传递，留给将来 inline 标红结构化携带。	2026-06-30 15:17:58 +08:00
wc24	24afc42de9	feat(validate): 递归校验引擎(校验下沉到任意深度) childrenOf(field,value): tab 选中分支 fields / object fields / array 元素套 item → 子(字段,值)对。 validateNode 递归: 每节点跑 validateField，出错即抛(带 path)，再下钻复合。接入 prepareAddItem/prepareEditItem(替原顶层 validateField)。第一版 fail-fast，嵌套错 message 缀 [path] 定位。默认/transform 下沉、collect-all、inline 标红留后续。	2026-06-30 14:49:48 +08:00
wc24	6383aade98	fix(crud): 响应统一剥掉 mongoose 版本键 __v filterHidden 出口加剥 __v(连同 hidden 字段),list/get/add/edit 全覆盖。前端无用的 __v 不再下发。	2026-06-30 14:09:44 +08:00
wc24	d12877f846	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。	2026-06-30 14:06:40 +08:00
wc24	c264ec6673	feat!: 去掉 json 类型(object 取代) + 版本统一 0.7.0 - object 字段已能声明式表达嵌套结构,freeform 的 json 类型不再需要: 删 ShrimpFieldTypes.Json + defaultTypeHandlers[Json](reqFilter/resFilter)。 - 源码无任何 type:json 使用,安全移除。 - 前后端版本自此统一:一起推的版本用相同版本号,本批 = 0.7.0。	2026-06-29 22:25:58 +08:00
wc24	f437e2e5e0	feat(composite): 新增 object/array 字段类型(refs 下钻 + 类型常量/配置) - ShrimpFieldTypes 加 Object/Array - IFieldConfig 加 fields(object 嵌套字段) + item(array 元素配置,递归) - collectRefs 重构成 collectOne(单字段+值),加 object(遍历 fields)/array(遍历元素套 item) 分支 → refs 下钻覆盖 object/array 里的嵌套 relation。显示/编辑组件在 shrimp-admin。第一版从简:无 min/max、无排序、无递归校验引擎。	2026-06-29 22:21:26 +08:00
wc24	ad5f7f18f5	refactor(export): 去掉后端可逆序列化(resLabel + export stringify)，序列化交前端 export 只返回原始数据;结构化字段的字符串化交前端(生成 xlsx 时)。删: tab resLabel、IFieldTypeHandler.resLabel、processResItem 的 _label 段、 export() 的 stringify 折叠、IFieldConfig.format/stringify。保留 tab reqFilter(import parse) + IFieldConfig.parse。彻底清掉 tab 显示搬前端后那个 _label 遗留。	2026-06-29 21:47:08 +08:00
wc24	e04d01a80c	feat(refs): buildRefs 递归下钻 tab，覆盖嵌套 relation collectRefs 递归收集:relation 叶子直接收，tab 按 value.type 进选中分支继续下钻 (顺带覆盖 tab 套 tab)。refs 字典现含嵌套关联名(如 sellType.goods)，为 tab 显示搬前端(子组件渲染 + relation 查 refs)铺好地基。	2026-06-29 21:28:32 +08:00
wc24	eb339ccc49	feat(filter): buildQuery 放行 _id 精确过滤(单项查看/relation 跳转) filter 原本只认 filterable 字段,_id 会被丢弃。新增: key==='_id' 时始终以 eq 放行, 让 ?filter={_id} 能过滤到单条。_id 是主键精确匹配、用户已有列表权限,无安全顾虑。	2026-06-29 20:40:28 +08:00