0.8.0: express 收紧到 ^5;契约副本改为 build 时自动同步

破坏性:peerDependencies.express 从 "^4 || ^5" 收成 "^5"。
buildShrimpRouter 的 router.post("/*path") 是 Express 5 才有的写法,
声明支持 4 一直是假的。devDeps 同步升到 express 5.1 / @types/express 5,32 个测试通过。

契约同步:新增 postbuild,把 src/IShrimpType.ts 覆盖到同级 shrimp-admin 的副本
(scripts/check-admin-contract.mjs;找不到同级仓库就跳过,不影响 CI 与消费侧 prepare)。
起因是那份副本靠人工复制,漂了一整代没人发现——停在旧的 json 类型,
缺 object/array/fields/item/parse/refs,而前端对未注册类型静默回落成 string,
漂移不报错、只悄悄渲染错。

删掉 @contractVersion 版本轴:代码无人读取,且从 1.0.0 起从未移动,
期间契约实际改了好几处,数字全程说谎。副本新不新改由字节比对回答,
消费侧看钉的 tag 即可,版本收敛成 package version 一根轴。

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-server",
-    "version": "0.7.5",
+    "version": "0.8.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)。
  */
 
 /** 业务错误码 */

src/Shrimp/ShrimpTableModule.ts

@@ -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)

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