docs: 字段类型表照实重列——删掉不存在的 json，补上 object/array；select 的属性名是 options；补只读模块怎么注册

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 一根轴。
2026-08-11 16:57:35 +08:00 · 2026-08-10 19:42:52 +08:00 · 2026-07-29 15:34:13 +08:00
7 changed files with 510 additions and 590 deletions
@@ -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) {
@@ -1,6 +1,6 @@
 {
    "name": "shrimp-server",
-    "version": "0.7.11",
+    "version": "0.8.1",
    "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,11 +46,11 @@
    },
    "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",
@@ -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)
+}
@@ -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)。
 */

 /** 业务错误码 */
@@ -292,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)
@@ -79,10 +79,9 @@ export class MongoShrimpCrud<T> implements ShrimpCrud<T> {
            const allRefIds = new Set<string>()
            for (const item of items) {
                const val = (item as any)[pop.key]
-                // 跳过空串：可选 Relation 常存 ""，混进 { _id: { $in } } 会让 Mongoose 转 ObjectId 抛 CastError、整页 500。
                if (Array.isArray(val)) {
-                    val.forEach((id: any) => { if (id != null && id !== "") allRefIds.add(String(id)) })
-                } else if (val != null && val !== "") {
+                    val.forEach((id: any) => { if (id != null) allRefIds.add(String(id)) })
+                } else if (val != null) {
                    allRefIds.add(String(val))
                }
            }