feat(filter): buildQuery 放行 _id 精确过滤(单项查看/relation 跳转)

filter 原本只认 filterable 字段,_id 会被丢弃。新增: key==='_id' 时始终以 eq 放行, 让 ?filter={_id} 能过滤到单条。_id 是主键精确匹配、用户已有列表权限,无安全顾虑。
feat(relation): 用整页 refs 字典替代逐行 _label
2026-06-29 20:40:28 +08:00 · 2026-06-29 20:17:26 +08:00 · 2026-06-29 17:33:52 +08:00 · 2026-06-29 16:56:45 +08:00 · 2026-06-29 16:42:11 +08:00 · 2026-06-29 15:45:58 +08:00
6 changed files with 172 additions and 48 deletions
@@ -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` 从未被调用** —— 漏接，待补。
@@ -1,22 +1,24 @@
 {
    "name": "shrimp-server",
-    "version": "0.6.0",
-    "private": true,
+    "version": "0.6.8",
    "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)",
-    "main": "src/main/index.ts",
-    "types": "src/main/index.ts",
+    "main": "dist/main/index.js",
+    "types": "dist/main/index.d.ts",
    "exports": {
        ".": {
-            "types": "./src/main/index.ts",
-            "default": "./src/main/index.ts"
+            "types": "./dist/main/index.d.ts",
+            "default": "./dist/main/index.js"
        },
        "./package.json": "./package.json"
    },
    "files": [
+        "dist",
        "src",
        "README.md"
    ],
    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "prepare": "tsc -p tsconfig.build.json",
        "test": "vitest run",
        "test:watch": "vitest",
        "typecheck": "tsc --noEmit"
@@ -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,12 @@ 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 */
+    parse?: (text: string) => any
 }

 /** 通用验证规则（前后端共用） */
@@ -312,6 +320,7 @@ export interface IPageResult<T> {
    page: number       // 当前页码
    pageSize: number   // 每页数量
    totalPages: number // 总页数
+    refs?: Record<string, Record<string, any>>  // relation 显示名字典: { moduleKey: { id: 显示名 } }，前端显示时查名，替代逐行 _label
 }

 // ============== 数据源查询协议 ==============
@@ -48,24 +48,20 @@ 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) => {
-            if (value == null) return value
-            if (typeof value === "object") {
-                return JSON.stringify(value)
-            }
-            return value
-        },
+        // 本体原样下发对象(不再 stringify)；展示文本走 _label，用 format(给人看,可有损)
+        resLabel: (value, field) => (field.format ?? JSON.stringify)(value),
    },
 }

@@ -114,21 +110,20 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
            }
        }

+        // multiple 字段值是数组，类型校验需逐元素进行（与上面 options 校验保持一致）；
+        // 非 multiple 则整体校验单值。否则数组会被标量类型分支整体判为类型错误。
+        const checkType = (v: any): boolean => {
            switch (field.type) {
-            case ShrimpFieldTypes.String:
-                if (typeof value !== 'string') return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
-                break
-            case ShrimpFieldTypes.Number:
-                if (typeof value !== 'number' || Number.isNaN(value)) return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
-                break
-            case ShrimpFieldTypes.Boolean:
-                if (typeof value !== 'boolean') return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
-                break
-            case ShrimpFieldTypes.Date:
-                if (typeof value !== 'number' && !(value instanceof Date) && isNaN(Date.parse(value))) {
-                    return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+                case ShrimpFieldTypes.String: return typeof v === 'string'
+                case ShrimpFieldTypes.Number: return typeof v === 'number' && !Number.isNaN(v)
+                case ShrimpFieldTypes.Boolean: return typeof v === 'boolean'
+                case ShrimpFieldTypes.Date: return typeof v === 'number' || v instanceof Date || !isNaN(Date.parse(v))
+                default: return true // 非内置标量类型（relation/json/自定义等）不在此校验
            }
-                break
+        }
+        const typeTargets = field.multiple && Array.isArray(value) ? value : [value]
+        for (const v of typeTargets) {
+            if (!checkType(v)) return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
        }

        if (field.rules) {
@@ -226,28 +221,54 @@ 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 字段批量解析成 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 {}
+        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 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
+    }
+
    private excludeKeys(item: any, keys: string[]): any {
        if (keys.length === 0) return item
        const result = { ...item }
@@ -265,14 +286,6 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
        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
@@ -287,6 +300,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
@@ -341,6 +359,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
    }

@@ -397,7 +416,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
@@ -94,7 +94,7 @@ const roleFields: IFieldConfig[] = [
    { key: "name", label: { t: "role.name" }, type: "string", required: true, searchable: true },
    { key: "description", label: { t: "role.description" }, type: "textarea" },
    { key: "isSuperAdmin", label: { t: "role.isSuperAdmin" }, type: "boolean" },
-    { key: "powers", label: { t: "role.powers" }, type: "string" },
+    { key: "powers", label: { t: "role.powers" }, type: "powers" },
    { key: "createdAt", label: { t: "role.createdAt" }, type: "date", editable: "readonly", sortable: true },
    { key: "updatedAt", label: { t: "role.updatedAt" }, type: "date", editable: "readonly", sortable: true },
 ]
@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist", "test"]
+}
Author	SHA1	Message	Date
wc24	eb339ccc49	feat(filter): buildQuery 放行 _id 精确过滤(单项查看/relation 跳转) filter 原本只认 filterable 字段,_id 会被丢弃。新增: key==='_id' 时始终以 eq 放行, 让 ?filter={_id} 能过滤到单条。_id 是主键精确匹配、用户已有列表权限,无安全顾虑。	2026-06-29 20:40:28 +08:00
wc24	8f9dfd40e0	feat(relation): 用整页 refs 字典替代逐行 _label list 响应新增 refs: { moduleKey: { id: 显示名 } }，整页一次性按模块批量查、去重；去掉 relation 的 populateItems→${key}_label 逐行注入。前端显示时按 id 查 refs。 tab 的 resLabel/_label 不动(留待复合那步)。这是嵌套引用的地基:collectRefs 以后加 tab 的 children() 下钻即可覆盖任意深度。	2026-06-29 20:17:26 +08:00
wc24	ee35b47f69	revert(tab): 撤回 v0.6.5 嵌套 relation 解析，回到 format 纯展示 populateTabRelations / format 第二参是 tab 专属特例,太狭隘(object/array 同类问题未覆盖), 通用复合解析另当专门事做。嵌套关联名(如商品名)的展示需求改放业务侧(模块重写 list/get)。框架只保留: format(同步纯展示) + stringify/parse(可逆往返)。	2026-06-29 17:33:52 +08:00
wc24	bc54b475cf	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。	2026-06-29 16:56:45 +08:00
wc24	4b51d31e9f	feat(tab): 拆开展示与序列化 — field.format(展示) vs stringify/parse(可逆往返) v0.6.3 用同一个 stringify 同时扛表格展示和 export 序列化,二者诉求冲突: 展示要好看可有损,export 要可逆完整。现拆为: - field.format → _label 展示文本(给人看,可有损),默认 JSON.stringify - field.stringify/parse → export/import 可逆对(机器往返),默认 JSON export 改用 stringify(可逆)而非 _label,import 的 parse 能还原。	2026-06-29 16:42:11 +08:00
wc24	c5c06bee13	feat(tab): 结构化字段端到端传对象，给人看的边界走 _label/stringify tab 字段原把对象 JSON.stringify 成字符串下发(复用 json 的 resFilter)，导致前端 FieldTab 收到字符串：表格 display 显示 '-'、编辑回退默认值。改为： - 库/响应/编辑全程对象(去掉 tab 的 resFilter stringify) - 新增 resLabel 钩子 → 写入 ${key}_label，承载给人看的字符串文本 - export 边界用 _label 文本替换对象列(可读且可被 import 的 parse 还原) - 字段级可配 stringify/parse，默认 JSON	2026-06-29 15:45:58 +08:00
wc24	f94a01e0a1	fix(shrimp): 修复 multiple 字段类型校验逻辑	2026-06-15 14:34:36 +08:00
wc24	5ecbf2cc01	docs: array/object 字段类型设计草案（搁置待需求，含前后端方案）	2026-06-10 15:47:57 +08:00
wc24	9fff8c472d	v0.6.2: powers 字段改自定义类型，绕过前置验证的标量类型校验	2026-06-08 19:22:56 +08:00
wc24	187c6f6030	v0.6.1: 改为编译 ship,通过 npm prepare hook 自动构建 - 加 tsconfig.build.json,排除 test,rootDir 设为 src - package.json: main/types/exports 指向 dist/main/index.{js,d.ts} - prepare hook: 消费侧 git 安装后自动 tsc,产物不进 git - 解决消费侧 "tsc + 裸 node" 链路 (theseus-server 等) 找不到 .js 的问题	2026-06-01 19:32:48 +08:00