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。

README.md

@@ -96,6 +96,33 @@ import type { IFieldConfig, IMenuItem, IMeResult } from "shrimp-server/types"
 
 ## 约定
 
+shrimp 不是铁板一块的协议,它是**一组可选拼装件**。每个件对外有自己的契约,你用了哪个件就被哪个件的契约绑住,不用就不必遵守。盘点时按**作用域**分两层。
+
+### 🌐 全局约定(只要你说"我在写 shrimp",就跑不掉)
+
+| 契约 | 说明 |
+|---|---|
+| `IModuleInfo` 形状 | 任何模块声明都得这么写 — 见 [src/IShrimpType.ts](src/IShrimpType.ts) `IModuleInfo` |
+| `IFieldConfig` 形状 | 字段就这样描述(`name` / `label` / `type` / `relation` / `rules` …) |
+| Shrimp 树结构 | `parent`/`children` 嵌套、`getFullPath()` 路径语义 |
+| Power / Role 声明 | `power` 树形 + `role` 持 `powers[]` |
+| `ILabel` 多语言形态 | 见下方 §国际化 — 6 选 1 的标签类型 |
+
+### 🔌 条件约定(用了某个件,才被它的契约绑住)
+
+| 启用前提 | 它的契约 |
+|---|---|
+| **使用 `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`(数组关联挂数组) |
+| **使用 `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) |
+| **使用默认 `Field*.vue` 渲染**(前端) | • 字段 `type` 必须是内置枚举之一,否则需注册 `typeHandler` 才能渲染 |
+| **使用 Shrimp 子模块机制** | • 子表 `ownerKey` 是后端注册侧独占,**不进 fields[]**<br>• 前端只发通用 `ownerId`,不感知 `ownerKey` 的实际字段名 |
+
+> 替换某个件,这个件的条件契约自动失效。例如:你换掉 `ShrimpTable` 用 AG-Grid,list 响应格式和字段 type 枚举两条对你都不再生效;你不挂 `OperationLogModule`,日志契约就不存在。
+
+---
+
 ### 国际化 (ILabel)
 
 所有前端可见文本字段(`label` / `tip` / `menu.label` / `power.label` / `field.label` / `rule.message` …)统一类型 `ILabel`。**用哪种形态取决于你写在哪一层**。

docs/array-object-field-design.md

@@ -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` 从未被调用** —— 漏接，待补。

package.json

@@ -1,30 +1,24 @@
 {
     "name": "shrimp-server",
-    "version": "0.5.0",
+    "version": "0.6.5",
-    "private": true,
     "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)",
-    "main": "src/main/index.ts",
+    "main": "dist/main/index.js",
-    "types": "src/main/index.ts",
+    "types": "dist/main/index.d.ts",
     "exports": {
         ".": {
-            "types": "./src/main/index.ts",
+            "types": "./dist/main/index.d.ts",
-            "default": "./src/main/index.ts"
+            "default": "./dist/main/index.js"
-        },
-        "./expmon": {
-            "types": "./src/main/expmon.ts",
-            "default": "./src/main/expmon.ts"
-        },
-        "./types": {
-            "types": "./src/main/types.ts",
-            "default": "./src/main/types.ts"
         },
         "./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"

src/IShrimpType.ts

@@ -1,6 +1,12 @@
 /**
- * Shrimp 前后端共用类型定义
+ * Shrimp 类型契约 — 前后端 wire protocol 定义
- * 定义错误码、协议、通用数据格式
+ *
+ * @contractVersion 1.0.0
+ *
+ * 改动此文件需要:
+ *   1. 升 @contractVersion(语义化版本)
+ *   2. 同步到 shrimp-admin/src/IShrimpType.ts,更新其 @syncedFrom
+ *   3. 通知消费侧对齐
  */
 
 /** 业务错误码 */
@@ -242,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>
     /** 新增时的默认值（静态值或工厂函数） */
@@ -270,6 +278,13 @@ export interface IFieldConfig {
     rules?: IFieldRule[]          // 通用验证规则（前后端共用）
     /** tab 类型专用：每个 type 对应的子字段配置 */
     tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
+    /** tab 类型专用：展示文本(表格列 `${key}_label`)，给人看、可有损好看，默认 JSON.stringify。
+     *  relLabels 是已解析的子 relation 名(`{childKey: 名 | 名[]}`)，单选为名、multiple 为名数组 */
+    format?: (value: any, relLabels?: Record<string, any>) => string
+    /** tab 类型专用：export 序列化，须与 parse 可逆(机器往返)，默认 JSON.stringify */
+    stringify?: (value: any) => string
+    /** tab 类型专用：import 反序列化，须与 stringify 可逆，默认 JSON.parse */
+    parse?: (text: string) => any
 }
 
 /** 通用验证规则（前后端共用） */

src/Shrimp/ShrimpTableModule.ts

@@ -48,24 +48,21 @@ 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) => {
+        // 本体原样下发对象(不再 stringify)；展示文本走 _label，用 format(给人看,可有损)
-            if (value == null) return value
+        // 第二参是已批量解析的子 relation 名(item.__tabRel[field.key])，让 format 能显示关联名而非 id
-            if (typeof value === "object") {
+        resLabel: (value, field, item) => (field.format ?? JSON.stringify)(value, item?.__tabRel?.[field.key]),
-                return JSON.stringify(value)
-            }
-            return value
-        },
     },
 }
 
@@ -114,21 +111,20 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
             }
         }
 
-        switch (field.type) {
+        // multiple 字段值是数组，类型校验需逐元素进行（与上面 options 校验保持一致）；
-            case ShrimpFieldTypes.String:
+        // 非 multiple 则整体校验单值。否则数组会被标量类型分支整体判为类型错误。
-                if (typeof value !== 'string') return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+        const checkType = (v: any): boolean => {
-                break
+            switch (field.type) {
-            case ShrimpFieldTypes.Number:
+                case ShrimpFieldTypes.String: return typeof v === 'string'
-                if (typeof value !== 'number' || Number.isNaN(value)) return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+                case ShrimpFieldTypes.Number: return typeof v === 'number' && !Number.isNaN(v)
-                break
+                case ShrimpFieldTypes.Boolean: return typeof v === 'boolean'
-            case ShrimpFieldTypes.Boolean:
+                case ShrimpFieldTypes.Date: return typeof v === 'number' || v instanceof Date || !isNaN(Date.parse(v))
-                if (typeof value !== 'boolean') return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+                default: return true // 非内置标量类型（relation/json/自定义等）不在此校验
-                break
+            }
-            case ShrimpFieldTypes.Date:
+        }
-                if (typeof value !== 'number' && !(value instanceof Date) && isNaN(Date.parse(value))) {
+        const typeTargets = field.multiple && Array.isArray(value) ? value : [value]
-                    return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
+        for (const v of typeTargets) {
-                }
+            if (!checkType(v)) return { t: 'shrimp.fieldTypeError', params: { field: field.label } }
-                break
         }
 
         if (field.rules) {
@@ -226,7 +222,11 @@ 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)
+            }
         }
+        delete result.__tabRel // 临时挂的子 relation 解析结果，不下发
         return result
     }
 
@@ -236,6 +236,7 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         if (populates.length > 0 && this.dataSource.populateItems) {
             await this.dataSource.populateItems(items, populates, this.root.crudRegistry)
         }
+        await this.populateTabRelations(items)
         return Promise.all(items.map(item => this.processResItem(item)))
     }
 
@@ -245,9 +246,62 @@ export class ShrimpTableModule<T, P extends ITableCrudProto<T> = ITableCrudProto
         if (populates.length > 0 && this.dataSource.populateItems) {
             await this.dataSource.populateItems([item], populates, this.root.crudRegistry)
         }
+        await this.populateTabRelations([item])
         return this.processResItem(item)
     }
 
+    /**
+     * 解析 tab 字段里 relation 子字段的名字，批量(每个关联模块一次 $in)，
+     * 挂到 item.__tabRel[fieldKey][childKey]，供该字段的 format 第二参使用。
+     * 不污染 tab 本体对象(避免回灌进库)，__tabRel 在 processResItem 末尾删除。
+     */
+    private async populateTabRelations(items: any[]): Promise<void> {
+        const tabFields = this.fields.filter(f => f.type === ShrimpFieldTypes.Tab && Array.isArray(f.tabs))
+        if (tabFields.length === 0 || items.length === 0) return
+
+        const need = new Map<string, { labelKey: string; ids: Set<string> }>()
+        const refs: { item: any; fieldKey: string; childKey: string; moduleKey: string; multiple: boolean }[] = []
+        for (const item of items) {
+            for (const tf of tabFields) {
+                const val = item[tf.key]
+                if (!val || typeof val !== "object") continue
+                const tab = tf.tabs!.find(t => t.key === val.type)
+                if (!tab) continue
+                for (const child of tab.fields) {
+                    if (child.type !== ShrimpFieldTypes.Relation || !child.relation || val[child.key] == null) continue
+                    const { moduleKey, labelKey } = child.relation
+                    let bucket = need.get(moduleKey)
+                    if (!bucket) need.set(moduleKey, (bucket = { labelKey, ids: new Set() }))
+                    const cv = val[child.key]
+                    ;(Array.isArray(cv) ? cv : [cv]).forEach((id: any) => id != null && bucket!.ids.add(String(id)))
+                    refs.push({ item, fieldKey: tf.key, childKey: child.key, moduleKey, multiple: !!child.multiple })
+                }
+            }
+        }
+        if (refs.length === 0) return
+
+        const labelMaps = new Map<string, Map<string, any>>()
+        for (const [moduleKey, b] of need) {
+            const m = new Map<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 doc of res.list as any[]) m.set(String(doc._id), doc[b.labelKey])
+            }
+            labelMaps.set(moduleKey, m)
+        }
+
+        for (const ref of refs) {
+            const m = labelMaps.get(ref.moduleKey)!
+            const cv = ref.item[ref.fieldKey][ref.childKey]
+            const label = ref.multiple
+                ? (Array.isArray(cv) ? cv.map((id: any) => m.get(String(id)) ?? null) : [])
+                : m.get(String(cv)) ?? null
+            const bag = (ref.item.__tabRel ||= {})
+            ;(bag[ref.fieldKey] ||= {})[ref.childKey] = label
+        }
+    }
+
     private excludeKeys(item: any, keys: string[]): any {
         if (keys.length === 0) return item
         const result = { ...item }
@@ -397,7 +451,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

src/Shrimp/UserRoleModule.ts

@@ -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 },
 ]

src/main/expmon.ts

@@ -1,99 +0,0 @@
-/**
- * Shrimp expmon 入口 — Express + Mongoose 整合方案
- *
- * 在 core 之上把 forMongo(MongoShrimp + 数据源)和 forExpress(buildShrimpRouter
- * + JWT)拼起来,导出开箱即用的 ShrimpServer 装配体。
- *
- * 这一入口需要消费方安装 peer:express / mongoose / jsonwebtoken / bcrypt。
- * 不需要时改从 'shrimp-server' 导入,不会触发任何 peer。
- *
- * 想换掉其中一块的高级用法:
- *   - 自己造 ITokenAuth(看 createJwtTokenAuth 实现)
- *   - 自己造 dataSource(实现 ShrimpCrud 接口)
- *   - 直接 buildShrimpRouter(deps) 拼自己的 Express app,绕开本类
- */
-
-import { Router } from "express"
-import { MongoShrimp, UserSchema, RoleSchema, OperationLogSchema } from "../forMongo/MongoShrimp"
-import { buildShrimpRouter } from "../forExpress/buildShrimpRouter"
-import { createJwtTokenAuth } from "../forExpress/jwtAuth"
-import type { ITokenAuth, IUserAccessor } from "../forExpress/types"
-import type { RootShrimpPower } from "../Shrimp/ShrimpPower"
-import type { IUser, IRole, WithId } from "../IShrimpType"
-
-// 再导出所有 core 的符号,'shrimp-server/expmon' 单一入口就够用
-export * from "./index"
-
-// ===== forMongo / forExpress 公开符号 =====
-export { MongoShrimp, UserSchema, RoleSchema, OperationLogSchema } from "../forMongo/MongoShrimp"
-export { MongoShrimpCrud } from "../forMongo/MongoShrimpCrud"
-export { buildShrimpRouter } from "../forExpress/buildShrimpRouter"
-export { createJwtTokenAuth } from "../forExpress/jwtAuth"
-export type { IJwtTokenAuthOptions } from "../forExpress/jwtAuth"
-export type { ITokenAuth, IUserAccessor, IShrimpRouterDeps } from "../forExpress/types"
-
-// ============== ShrimpServer ==============
-
-export class ShrimpServer extends MongoShrimp implements IUserAccessor {
-    router: Router
-    jwtSecret: string
-    config: Record<string, any>
-    globalOptions: Record<string, any> = {}
-    forcedOptionAccess = new Map<string, RootShrimpPower>()
-
-    constructor(jwtSecret: string, config: Record<string, any> = {}, mongodbUri: string = "mongodb://localhost:27017/shrimp") {
-        super(mongodbUri)
-        this.jwtSecret = jwtSecret
-        this.config = config
-
-        this.router = buildShrimpRouter({
-            shrimp: this,
-            userModule: this.userModule,
-            roleModule: this.roleModule,
-            operationLogModule: this.operationLogModule,
-            tokenAuth: this.createTokenAuth(),
-            config: this.config,
-            globalOptions: this.globalOptions,
-            forcedOptionAccess: this.forcedOptionAccess,
-            userAccessor: this,
-        })
-    }
-
-    registerOptions(key: string, options: any, access?: RootShrimpPower) {
-        this.globalOptions[key] = options
-        if (access) {
-            this.forcedOptionAccess.set(key, access)
-        }
-    }
-
-    /** 创建 Token 鉴权,默认 JWT。子类可覆盖换成 session 之类。 */
-    protected createTokenAuth(): ITokenAuth {
-        return createJwtTokenAuth(this.jwtSecret)
-    }
-
-    // ============== 可覆盖的用户/角色字段访问钩子(实现 IUserAccessor) ==============
-
-    getJwtPayload(user: WithId<IUser>): Record<string, any> {
-        return { _id: user._id, roleId: user.roleId }
-    }
-
-    isUserActive(user: WithId<IUser>): boolean {
-        return user.active === true
-    }
-
-    getUserRoleIds(user: WithId<IUser>): string[] {
-        return Array.isArray(user.roleId) ? user.roleId.map(String) : user.roleId ? [String(user.roleId)] : []
-    }
-
-    isRoleSuperAdmin(role: WithId<IRole> | null): boolean {
-        return !!role?.isSuperAdmin
-    }
-
-    getRolePowers(role: WithId<IRole> | null): string[] {
-        return role?.powers || []
-    }
-
-    getUserDisplayName(user: WithId<IUser>): string {
-        return user.nickname || ""
-    }
-}

src/main/index.ts

@@ -1,19 +1,28 @@
 /**
- * Shrimp 核心入口 — 0 重依赖
+ * Shrimp 单一入口 — 完整后端栈
  *
- * 只暴露 Shrimp 框架本体 + 内存数据源 + 类型定义,不引入
+ * 包含框架核心 + 类型契约 + Express + Mongoose + JWT 装配体。
- * express / mongoose / jsonwebtoken。bcrypt 是 lazy import,
- * 不走 Password 字段就不会触发。
  *
- * 适用场景:
+ * 安装 peer:express / mongoose / jsonwebtoken / bcrypt。
- *  - 只想用 Shrimp 的 RPC dispatch + 模块/字段声明 + 内存 CRUD
- *  - 自己接 HTTP / 自己写存储层
- *  - 跑测试 / 跑无 DB 的 demo
  *
- * 需要完整后台(Express + Mongoose + JWT)请从 'shrimp-server/expmon' 导入。
+ * 前端只想要类型契约,**不要**从这里 import — 见 shrimp-admin 的
+ * IShrimpType.ts(契约副本),避免把 mongoose/express 牵进前端 bundle。
+ *
+ * 想换掉其中一块的高级用法:
+ *   - 自己造 ITokenAuth(看 createJwtTokenAuth 实现)
+ *   - 自己造 dataSource(实现 ShrimpCrud 接口)
+ *   - 直接 buildShrimpRouter(deps) 拼自己的 Express app,绕开 ShrimpServer
  */
 
-// ===== 类型 / 接口 / 枚举 =====
+import { Router } from "express"
+import { MongoShrimp } from "../forMongo/MongoShrimp"
+import { buildShrimpRouter } from "../forExpress/buildShrimpRouter"
+import { createJwtTokenAuth } from "../forExpress/jwtAuth"
+import type { ITokenAuth, IUserAccessor } from "../forExpress/types"
+import type { RootShrimpPower } from "../Shrimp/ShrimpPower"
+import type { IUser, IRole, WithId } from "../IShrimpType"
+
+// ===== 类型契约 / 枚举 =====
 export {
     ShrimpCode,
     ShrimpError,
@@ -64,9 +73,83 @@ export type { ShrimpCrud } from "../Shrimp/ShrimpCrud"
 export { UserModule, RoleModule } from "../Shrimp/UserRoleModule"
 export { OperationLogModule } from "../Shrimp/OperationLogModule"
 
-// ===== 密码哈希(可注入,默认 bcrypt lazy import) =====
+// ===== 密码哈希 =====
 export { bcryptHasher, plainHasher } from "../PasswordHasher"
 export type { IPasswordHasher } from "../PasswordHasher"
 
-// ===== 数据源(纯内存,无外部依赖) =====
+// ===== 数据源 =====
 export { MemoryShrimpCrud } from "../MemoryShrimpCrud"
+export { MongoShrimp, UserSchema, RoleSchema, OperationLogSchema } from "../forMongo/MongoShrimp"
+export { MongoShrimpCrud } from "../forMongo/MongoShrimpCrud"
+
+// ===== Express 装配 =====
+export { buildShrimpRouter } from "../forExpress/buildShrimpRouter"
+export { createJwtTokenAuth } from "../forExpress/jwtAuth"
+export type { IJwtTokenAuthOptions } from "../forExpress/jwtAuth"
+export type { ITokenAuth, IUserAccessor, IShrimpRouterDeps } from "../forExpress/types"
+
+// ============== ShrimpServer ==============
+
+export class ShrimpServer extends MongoShrimp implements IUserAccessor {
+    router: Router
+    jwtSecret: string
+    config: Record<string, any>
+    globalOptions: Record<string, any> = {}
+    forcedOptionAccess = new Map<string, RootShrimpPower>()
+
+    constructor(jwtSecret: string, config: Record<string, any> = {}, mongodbUri: string = "mongodb://localhost:27017/shrimp") {
+        super(mongodbUri)
+        this.jwtSecret = jwtSecret
+        this.config = config
+
+        this.router = buildShrimpRouter({
+            shrimp: this,
+            userModule: this.userModule,
+            roleModule: this.roleModule,
+            operationLogModule: this.operationLogModule,
+            tokenAuth: this.createTokenAuth(),
+            config: this.config,
+            globalOptions: this.globalOptions,
+            forcedOptionAccess: this.forcedOptionAccess,
+            userAccessor: this,
+        })
+    }
+
+    registerOptions(key: string, options: any, access?: RootShrimpPower) {
+        this.globalOptions[key] = options
+        if (access) {
+            this.forcedOptionAccess.set(key, access)
+        }
+    }
+
+    /** 创建 Token 鉴权,默认 JWT。子类可覆盖换成 session 之类。 */
+    protected createTokenAuth(): ITokenAuth {
+        return createJwtTokenAuth(this.jwtSecret)
+    }
+
+    // ============== 可覆盖的用户/角色字段访问钩子(实现 IUserAccessor) ==============
+
+    getJwtPayload(user: WithId<IUser>): Record<string, any> {
+        return { _id: user._id, roleId: user.roleId }
+    }
+
+    isUserActive(user: WithId<IUser>): boolean {
+        return user.active === true
+    }
+
+    getUserRoleIds(user: WithId<IUser>): string[] {
+        return Array.isArray(user.roleId) ? user.roleId.map(String) : user.roleId ? [String(user.roleId)] : []
+    }
+
+    isRoleSuperAdmin(role: WithId<IRole> | null): boolean {
+        return !!role?.isSuperAdmin
+    }
+
+    getRolePowers(role: WithId<IRole> | null): string[] {
+        return role?.powers || []
+    }
+
+    getUserDisplayName(user: WithId<IUser>): string {
+        return user.nickname || ""
+    }
+}

src/main/types.ts

@@ -1,9 +0,0 @@
-/**
- * Shrimp 纯类型入口
- *
- * 只导出 IShrimpType.ts 的全部协议(类型 + ShrimpCode enum + ShrimpError class),
- * 前端 shrimp-admin / 任何只需要协议定义的消费方从这里 import,
- * 不会触发任何运行时依赖。
- */
-
-export * from "../IShrimpType"

tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist", "test"]
+}