0.9.0: 导入导出协议改成 sheet 表(多 sheet)

export 返回 { sheet 名: 行数组 },import 收同样的形状 —— 一份负载对应一个 xlsx
工作簿。默认仍是单张表(以 moduleKey 命名),模块重写 export/import 就能自定义
多 sheet(如商品/商店/销售规则一次搬完),不必再把多张表压扁成 __t/__data 两列
塞进一个 sheet。

import 取同名 sheet、没有就退回第一张:手工在 Excel 里建的表叫 Sheet1,老版本
前端发的是裸数组,两种都不该白导。

README.md

@@ -112,7 +112,7 @@ shrimp 不是铁板一块的协议,它是**一组可选拼装件**。每个件
 
 | 启用前提 | 它的契约 |
 |---|---|
-| **使用 `ShrimpTable`(前端表格组件)** | • list 响应必须是 `IPageResult` = `{ list, total, page, pageSize, totalPages }`<br>• 字段 `type` 必须落在内置枚举:`string` / `number` / `boolean` / `date` / `select` / `textarea` / `password` / `relation` / `json` / `tab` —— 或自行注册 `IFieldTypeHandler`<br>• populate 字段旁挂 `${key}_label`(数组关联挂数组) |
+| **使用 `ShrimpTable`(前端表格组件)** | • list 响应必须是 `IPageResult` = `{ list, total, page, pageSize, totalPages }`<br>• 字段 `type` 必须落在内置枚举(见下方 §字段类型)—— 或自行注册 `IFieldTypeHandler`<br>• populate 字段旁挂 `${key}_label`(数组关联挂数组) |
 | **使用 `buildShrimpRouter` / `ShrimpServer`** | • HTTP 路由形状:`GET /config`、`POST /login`、`GET /me`、`POST /<modulePath>/<event>`<br>• JWT 携带:`Authorization: Bearer <token>`<br>• 后端需实现 `IUserAccessor`(getJwtPayload / isUserActive / getUserRoleIds / isRoleSuperAdmin / getRolePowers / getUserDisplayName) — 见 [src/forExpress/types.ts](src/forExpress/types.ts) |
 | **使用 `MongoShrimp`** | • User/Role/OperationLog 的 mongoose Schema 形状<br>• `onDbConnected` 钩子时序:连接就绪后才能注册需要 DB 的模块 |
 | **挂 `OperationLogModule`** | • CRUD 动作自动写日志的字段集(operator / module / action / target / time) |
@@ -248,8 +248,31 @@ export class MyAdmin extends ShrimpServer {
 - `required: true` — 表单必填
 - `defaultValue: ...` — 新增时的默认值
 
-**字段 type 选这些:**
-`string` / `number` / `boolean` / `date` / `textarea` / `password` / `select` / `relation` / `json` / `tab`
+### 字段类型
+
+内置就这 11 个,以 [src/IShrimpType.ts](src/IShrimpType.ts) 的 `ShrimpFieldTypes` 为准:
+
+| type | 用途 |
+|---|---|
+| `string` | 单行文本 |
+| `number` | 数字 |
+| `boolean` | 开关 |
+| `date` | 日期 |
+| `textarea` | 多行文本 |
+| `password` | 密码,列表不回显 |
+| `select` | 枚举,配 `options: [{label, value}]`(属性名就叫 `options`) |
+| `relation` | 关联别的模块,配 `relation: {moduleKey, labelKey}`,见 §3 |
+| `tab` | 分组容器 |
+| `object` | 嵌套对象,配 `fields: IFieldConfig[]` 描述内部字段 |
+| `array` | 数组,配 `item: IFieldConfig` 描述元素 |
+
+字符串数组用 `array` + `item`,不要用 `object`——`object` 要的是 `fields`(一组具名字段),装不下一个同构列表:
+
+```ts
+{ key: 'tags', label: '标签', type: 'array', item: { key: '', label: '标签', type: 'string' } }
+```
+
+**没有 `json` 这个类型。** 写了它不会报错:前端查不到处理器,静默回落成 `string` 渲染(0.8.2 起控制台留一条 warning)。需要别的形状就自行注册 `IFieldTypeHandler`,别借用不存在的名字。
 
 ---
 
@@ -287,6 +310,15 @@ const orderFields: IFieldConfig[] = [
 
 `initCrud()` 注册了 5 个标准事件,如果你需要更多,自己加。
 
+**要注册得更少(只读模块):不调 `initCrud()` 就行。** 模块访问权本身就涵盖 `list` / `get`,不需要也不应该手动 `addEvent('list')`——`initCrud()` 加的是 `add` / `edit` / `delete` 这几个写入口:
+
+```ts
+// 只能看,不能改。前端表格照常出,但没有新增/编辑/删除按钮
+new ShrimpTableModule(this, 'item', new MongoShrimpCrud(itemModel), itemFields, '物品管理')
+```
+
+字段一律配 `editable: 'readonly'` 是另一件事——那管的是表单控件,不管有没有写入口。两个都要做。
+
 ```ts
 class OrderTable extends ShrimpTableModule<IOrder> {
     constructor(parent, dataSource) {
@@ -330,6 +362,35 @@ class UserTable extends ShrimpTableModule<IUser> {
 }
 ```
 
+### 导入导出:多 sheet
+
+`export`/`import` 的负载是 **`IShrimpSheets` = `{ sheet 名: 行数组 }`**,一份对应一个 xlsx 工作簿。
+默认行为:导出一张以 `moduleKey` 命名的 sheet;导入取同名 sheet,没有就退回第一张(手工在 Excel 里建的表叫 `Sheet1`,也能导)。
+
+要一个模块导出多张表(比如"商品 / 商店 / 销售规则"一次搬完),重写这两个方法就行,前端会按 key 自动建 sheet、按名字读回来:
+
+```ts
+class ShopTable extends ShrimpTableModule<IShop> {
+    async export(): Promise<IShrimpSheets> {
+        return {
+            goods: await GoodsDB.find().lean(),
+            shop: await ShopDB.find().lean(),
+            saleRule: await SaleRuleDB.find().lean(),
+        }
+    }
+    async import(data?: IShrimpSheets) {
+        for (const row of data?.goods ?? []) { /* 先建商品,记 oldId → newId */ }
+        for (const row of data?.shop ?? []) { /* 再建商店 */ }
+        for (const row of data?.saleRule ?? []) { /* 最后用映射还原引用 */ }
+    }
+}
+```
+
+注意:
+- sheet 名受 Excel 限制 —— 超 31 字符或含 `[]:*?/\` 会被前端替换/截断,别拿长 key 当 sheet 名。
+- 单元格放不下对象/数组,前端导出时会把它们 `JSON.stringify`;导入时由字段类型的 `reqFilter`(如 `tab` 的 `parse`)还原。所以嵌套结构建议声明成有 handler 的类型,或自己在 `import` 里 parse。
+- 老版本(≤ v0.8.x)的裸数组负载仍能导入,会被当成单张表。
+
 ### 字段级 reqFilter / validate
 通过 `registerTypeHandler` 注册自定义 type 的处理器:
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-server",
-    "version": "0.7.5",
+    "version": "0.9.0",
     "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)",
     "main": "dist/main/index.js",
     "types": "dist/main/index.d.ts",
@@ -18,6 +18,7 @@
     ],
     "scripts": {
         "build": "tsc -p tsconfig.build.json",
+        "postbuild": "node scripts/check-admin-contract.mjs",
         "prepare": "tsc -p tsconfig.build.json",
         "test": "vitest run",
         "test:watch": "vitest",
@@ -25,7 +26,7 @@
     },
     "peerDependencies": {
         "bcrypt": "^5 || ^6",
-        "express": "^4 || ^5",
+        "express": "^5",
         "jsonwebtoken": "^8 || ^9",
         "mongoose": "^6 || ^7 || ^8"
     },
@@ -45,18 +46,15 @@
     },
     "devDependencies": {
         "@types/bcrypt": "^5.0.0",
-        "@types/express": "^4.17.21",
+        "@types/express": "^5.0.0",
         "@types/jsonwebtoken": "^9.0.0",
         "@types/node": "^20.0.0",
         "bcrypt": "^5.1.1",
-        "express": "^4.19.0",
+        "express": "^5.1.0",
         "jsonwebtoken": "^9.0.2",
         "mongoose": "^8.0.0",
         "tsx": "^4.7.0",
         "typescript": "^5.3.0",
         "vitest": "^1.4.0"
-    },
-    "dependencies": {
-        "shrimp-server": "git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.7.4"
     }
 }

scripts/check-admin-contract.mjs

@@ -0,0 +1,31 @@
+/**
+ * build 后把契约同步给同级的 shrimp-admin。
+ *
+ * 契约的真身在这边,shrimp-admin 那份是派生物——所以是单向覆盖,跟 codegen 一个性质,
+ * 不是"两份文件互相对齐"。admin 那份的注释头是它自己的(声明自己是副本),同步时保留。
+ *
+ * 只在本地开发时生效:找不到同级 shrimp-admin(CI、别人只 clone 了这个仓库)就跳过。
+ * 挂在 postbuild 而不是 prepare:消费侧从 git 装本包时跑的是 prepare,不该被这事打扰。
+ *
+ * 为什么要自动做:上次靠人工复制,漂了一整代没人发现——
+ * 副本停在旧的 json 类型、缺 object/array/fields/item/parse/refs,
+ * 而前端对未注册类型静默回落到 string,漂移不报错、只悄悄渲染错。
+ */
+import { existsSync } from "node:fs"
+import { execFileSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
+
+const syncer = fileURLToPath(new URL("../../shrimp-admin/scripts/check-contract.mjs", import.meta.url))
+
+if (!existsSync(syncer)) {
+    console.log("skip: 同级没有 shrimp-admin,契约副本无从同步")
+    process.exit(0)
+}
+
+try {
+    execFileSync(process.execPath, [syncer, "--fix"], { stdio: "inherit" })
+} catch {
+    // 同步脚本自己挂了(权限、文件被占)。契约漂着不能当没事发生,让 build 失败。
+    console.error("❌ 契约副本同步失败,见上方输出")
+    process.exit(1)
+}

src/IShrimpType.ts

@@ -1,12 +1,16 @@
 /**
  * Shrimp 类型契约 — 前后端 wire protocol 定义
  *
- * @contractVersion 1.0.0
+ * 这份是契约本身。shrimp-admin/src/IShrimpType.ts 是它的副本,
+ * 由本仓库 postbuild 自动覆盖过去(scripts/check-admin-contract.mjs),不用手工同步。
  *
- * 改动此文件需要:
- *   1. 升 @contractVersion(语义化版本)
- *   2. 同步到 shrimp-admin/src/IShrimpType.ts,更新其 @syncedFrom
- *   3. 通知消费侧对齐
+ * 改动此文件 = 改 wire protocol,所以:
+ *   1. 发版升 package version(0.x 里破坏性改动升 minor),消费侧按 tag 钉包
+ *   2. 通知消费侧对齐
+ *
+ * 这里原本另有一个 @contractVersion 轴,删了:它从 1.0.0 起没动过,
+ * 期间契约丢了 json、多了 object/array/fields/item/parse/refs,数字全程说谎。
+ * 副本新不新改由字节比对回答(shrimp-admin 的 npm run check:contract)。
  */
 
 /** 业务错误码 */
@@ -119,11 +123,20 @@ export interface ITableProto<T> {
     delete(id: string): Promise<boolean>
 }
 
+/**
+ * 导入导出的负载形态：sheet 名 -> 行数组，对应 xlsx 的一个工作簿。
+ *
+ * 普通模块就是一个 sheet（默认以 moduleKey 命名）；模块重写 export/import
+ * 就能自定义多 sheet（如「商品/商店/销售规则」各一张），前端按 key 建/读 sheet。
+ * 兼容：老版本的裸数组负载等价于「单 sheet」，两端都会归一。
+ */
+export type IShrimpSheets = Record<string, any[]>
+
 /** 完整 Table 协议（后端可用，含管理操作） */
 export interface ITableCrudProto<T> extends ITableProto<T> {
     clear(query?: IPageQuery & any): Promise<boolean>
-    export(query?: IPageQuery & any): Promise<T[]>
-    import(data?: T[], ownerId?: string): Promise<void>
+    export(query?: IPageQuery & any): Promise<IShrimpSheets>
+    import(data?: IShrimpSheets | T[], ownerId?: string): Promise<void>
 }
 
 // ============== 预制数据模型 ==============

src/Shrimp/ShrimpTableModule.ts

@@ -1,6 +1,6 @@
 import {
     IFieldConfig, IFieldTypeHandler, IShrimpQuery, IShrimpCondition, IShrimpPopulate,
-    IPageQuery, IPageResult, ITableCrudProto, ILabel, ShrimpConfig, ShrimpError, ShrimpFieldTypes,
+    IPageQuery, IPageResult, ITableCrudProto, IShrimpSheets, ILabel, ShrimpConfig, ShrimpError, ShrimpFieldTypes,
 } from "../IShrimpType"
 import { Shrimp } from "./Shrimp"
 import { ShrimpModule, IShrimpModuleOptions } from "./ShrimpModule"
@@ -68,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 } }
@@ -196,6 +214,8 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         // 出错只发字段名(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)
         }
@@ -272,7 +292,8 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
     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))
+            // 跳过空串：可选 Relation 常存 ""，混进 { _id: { $in } } 会让 Mongoose 转 ObjectId 抛 CastError、整页 500。
+            ;(Array.isArray(v) ? v : [v]).forEach((id: any) => id != null && id !== "" && 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)
@@ -436,7 +457,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         }
         return await this.dataSource.clear()
     }
-    async export(query?: IPageQuery & any): Promise<T[]> {
+    async export(query?: IPageQuery & any): Promise<IShrimpSheets> {
         const shrimpQuery = this.buildQuery(query)
         delete shrimpQuery.offset
         delete shrimpQuery.limit
@@ -444,11 +465,22 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         result.list = await this.prepareResponseItems(result.list)
         // export 只取全量原始数据，不做序列化；结构化字段(如 tab)的字符串化交前端(生成 xlsx 时)。
         // import 端如传字符串，由各类型 reqFilter(如 tab 的 parse)还原。
-        return result.list.map(item => this.filterHidden(item))
+        // 默认一张以 moduleKey 命名的 sheet；要多 sheet 就重写本方法返回多个 key。
+        return { [this.moduleKey]: result.list.map(item => this.filterHidden(item)) }
     }
-    async import(data?: T[], ownerId?: string): Promise<void> {
-        if (!data || data.length === 0) return
-        for (const raw of data) {
+    /**
+     * 从导入负载里取本模块这一张表的行。
+     * 取 moduleKey 同名 sheet，没有就退回第一张 —— 手工在 Excel 里建的表叫 Sheet1，
+     * 老版本前端发的是裸数组，两种都不该白导。多 sheet 模块请重写 import 自己分派。
+     */
+    protected pickSheet(data?: IShrimpSheets | T[]): any[] {
+        if (!data) return []
+        if (Array.isArray(data)) return data
+        return data[this.moduleKey] ?? Object.values(data)[0] ?? []
+    }
+    async import(data?: IShrimpSheets | T[], ownerId?: string): Promise<void> {
+        const rows = this.pickSheet(data)
+        for (const raw of rows) {
             const item = { ...raw } as Record<string, any>
             if (ownerId && this.ownerKey) item[this.ownerKey] = ownerId
             const id = item._id ? String(item._id) : undefined

src/main/index.ts

@@ -40,6 +40,7 @@ export type {
     IMenuItem,
     ITableProto,
     ITableCrudProto,
+    IShrimpSheets,
     IUser,
     IRole,
     IOperationLog,

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]: "促销" })
     })
 })

test/exportSheets.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest"
+import { Shrimp, ShrimpTableModule, MemoryShrimpCrud, ShrimpFieldTypes } from "../src/main"
+import type { IShrimpSheets } from "../src/main"
+
+type Row = { _id: string; name: string }
+
+function makeModule() {
+    const shrimp = new Shrimp()
+    const crud = new MemoryShrimpCrud<Row>()
+    const mod = new ShrimpTableModule<Row>(shrimp, "tag", crud, [
+        { key: "name", label: "名称", type: ShrimpFieldTypes.String },
+    ], "标签")
+    mod.initCrud()
+    return { crud, mod }
+}
+
+describe("导入导出的 sheet 契约", () => {
+    it("export 返回以 moduleKey 命名的单张 sheet", async () => {
+        const { crud, mod } = makeModule()
+        await crud.add({ name: "热门" } as any)
+        const sheets = await mod.export({})
+        expect(Object.keys(sheets)).toEqual(["tag"])
+        expect(sheets.tag.map(r => r.name)).toEqual(["热门"])
+    })
+
+    it("import 认同名 sheet", async () => {
+        const { crud, mod } = makeModule()
+        await mod.import({ other: [{ name: "别人的" }], tag: [{ name: "热门" }] })
+        const all = await crud.list({})
+        expect(all.list.map(r => r.name)).toEqual(["热门"])
+    })
+
+    it("没有同名 sheet 时退回第一张(手工 Excel 的 Sheet1)", async () => {
+        const { crud, mod } = makeModule()
+        await mod.import({ Sheet1: [{ name: "热门" }] })
+        expect((await crud.list({})).list.map(r => r.name)).toEqual(["热门"])
+    })
+
+    it("老版本前端发的裸数组仍然能导", async () => {
+        const { crud, mod } = makeModule()
+        await mod.import([{ name: "热门" }] as any)
+        expect((await crud.list({})).list.map(r => r.name)).toEqual(["热门"])
+    })
+
+    it("多 sheet 由模块重写 export/import 自行分派", async () => {
+        const shrimp = new Shrimp()
+        const goods = new MemoryShrimpCrud<Row>()
+        const shops = new MemoryShrimpCrud<Row>()
+        class ShopModule extends ShrimpTableModule<Row> {
+            async export(): Promise<IShrimpSheets> {
+                return { goods: (await goods.list({})).list, shop: (await shops.list({})).list }
+            }
+            async import(data?: IShrimpSheets): Promise<void> {
+                for (const row of data?.goods ?? []) await goods.add(row as any)
+                for (const row of data?.shop ?? []) await shops.add(row as any)
+            }
+        }
+        const mod = new ShopModule(shrimp, "shop", shops, [
+            { key: "name", label: "名称", type: ShrimpFieldTypes.String },
+        ], "商店")
+
+        await mod.import({ goods: [{ name: "木剑" }], shop: [{ name: "杂货铺" }] })
+        const sheets = await mod.export()
+        expect(sheets.goods.map(r => r.name)).toEqual(["木剑"])
+        expect(sheets.shop.map(r => r.name)).toEqual(["杂货铺"])
+    })
+})