docs: 内置字段类型照 fields/ 目录重列——删掉不存在的 json，补上 array/object，点明未注册类型是静默回落

headerWidgets 是往 userbar 里插组件的口子:VueAdmin 收一个组件数组、userbar 用
v-for 渲染。它绕开了本包唯一的覆盖机制(sources 路径后缀),等于给同一件事开了
第二条路——而且是条窄路,只能往那一处塞,插进去的东西也没法参与 userbar 自身的
布局与样式。

撤掉它,同时把真问题补上:userbar 之前根本不可覆盖(layout.vue 静态 import),
消费侧就算按约定放了 shrimp/components/userbar.vue 也会被静默忽略——这才是当初
需要 headerWidgets 的原因。现在 userbar 走 resolveVue,整条顶栏都能换。

代价:想改顶栏得整份重写内置那 92 行,不能只插一个部件。这是有意的,覆盖颗粒度
本来就停在入口级(README 那张表),不为单个部件开代理。

README 同步:补上 userbar 这一行,并写明表外路径会被静默忽略、不报错。

README.md

@@ -4,45 +4,256 @@ Shrimp 框架前端 —— 一种**经典解决方案**(不是框架本身),消
 
 如果你想换 UI 库或者换前端技术栈,直接照 shrimp-server 的约定再写一份就行,不依赖本包。
 
-## 安装
+shrimp-admin 是**源码 ship**(.ts + .vue 直接发),不带构建产物,由消费侧 Vite 编译。这省掉了框架的构建步骤,代价是**有几件事 npm 装完不会自动生效**,必须消费侧显式配 —— 下面的接入模板已经把它们全写进去了。
 
-```bash
-# 推荐 HTTP
-npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.1.0
+---
+
+# 接入模板
+
+> **整段抄,不要自己攒。** 标了「⚠️ 不能删」的行看起来多余,删掉的后果写在每行旁边;
+> 现存的 theseus-admin / hand-admin / bug-book 三个项目里,这些行一行不差全都在。
+
+## 1. package.json
+
+```jsonc
+{
+    "type": "module",
+    "scripts": { "dev": "vite", "build": "vite build" },
+    "dependencies": {
+        "shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.8.2",
+
+        // ⚠️ 不能删 —— 下面 6 个是 shrimp-admin 的 peerDependencies,
+        // 必须由消费侧显式装进自己的 dependencies,不能指望 npm 提升碰巧能 import 到
+        "vue": "^3.5.0",
+        "vue-router": "^4.5.0",
+        "vue-i18n": "^9.14.0",
+        "axios": "^1.7.0",
+        "element-plus": "^2.10.0",
+        "@element-plus/icons-vue": "^2.3.0"
+    },
+    "devDependencies": {
+        "@vitejs/plugin-vue": "^5.2.0",
+        "sass-embedded": "^1.80.0",     // ⚠️ 不能删 —— shrimp-admin/style 是 .scss
+        "typescript": "^5.6.0",
+        "vite": "^6.0.0"
+    }
+}
 ```
 
-shrimp-admin 是**源码 ship**(.ts + .vue 直接发),由消费侧 Vite 编译。
+服务端那侧另有一条硬约束:**shrimp-server 要求 Express 5**(它的兜底路由用了 `/*path` 具名通配,Express 4 只会当字面路径)。装成 4 的症状是能登录、能出菜单,但**所有** `POST /<moduleKey>/list` 都 404。
 
-## 使用
+## 2. vite.config.ts
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+    plugins: [vue()],
+    optimizeDeps: {
+        // ⚠️ 不能删 —— 删了整页白屏,报 resolveVue: components/layout.vue not found in sources
+        exclude: ['shrimp-admin'],
+    },
+    resolve: {
+        // ⚠️ 不能删 —— 删了 element-plus 与 shrimp-admin 各带一份 vue/dayjs,互操作错位
+        dedupe: ['vue', 'vue-i18n', 'vue-router', 'element-plus', 'dayjs'],
+    },
+    server: {
+        // 开发期后台接口由 vite 转发,前端一律走相对路径,不注入任何后端地址
+        proxy: { '/admin-api': { target: 'http://127.0.0.1:8080', changeOrigin: true } },
+    },
+})
+```
+
+## 3. src/main.ts
 
 ```ts
-// main.ts
 import { createApp } from 'vue'
-import { createShrimpAdmin, App } from 'shrimp-admin'
+
+// ⚠️ 不能删,且必须在 shrimp-admin/style 之前 ——
+// 删了页面能出来但整个掉样式,最显眼的症状是图标被撑到巨大
+import 'element-plus/dist/index.css'
+import 'element-plus/theme-chalk/display.css'
 import 'shrimp-admin/style'
 
+import { createShrimpAdmin, App } from 'shrimp-admin'
+import zhCn from './locales/zh-cn.json'
+import en from './locales/en.json'
+
 const app = createApp(App)
 app.use(createShrimpAdmin({
     config: {
-        API_URL: '/admin-api',
+        API_URL: '/admin-api',   // 相对路径,由 vite proxy 转发
         TIMEOUT: 10000,
     },
-    moduleSources: import.meta.glob('./module/**/*.vue'),
-    customFields: import.meta.glob('./module/fields/Field*.vue'),
+    locales: { 'zh-cn': zhCn, en },
+    // ⚠️ import.meta.glob 必须写在消费侧的文件里(vite 静态扫描相对本文件),
+    // 不能封装成函数从别处调
+    sources: import.meta.glob('./shrimp/**/*.vue'),
 }))
 app.mount('#app')
 ```
 
-## 消费的契约
+## 4. 每个业务模块一个薄壳 `src/shrimp/module/<key>.vue`
+
+⚠️ **不能省。**后端有几个 moduleKey,这里就得有几个文件 —— 这**不是「覆盖」,是「注册」**:框架的内置兜底只兜自己的 login/layout/404,不认识你的业务模块,少一个那个菜单就点不开。
+
+```vue
+<!-- src/shrimp/module/product.vue —— 后端 moduleKey === 'product' -->
+<template>
+    <ShrimpTable moduleKey="product" />
+</template>
+
+<script setup lang="ts">
+// 字段、筛选、编辑全由后端 moduleInfo 声明,ShrimpTable 自动渲染,这里不写业务代码
+import { ShrimpTable } from 'shrimp-admin'
+</script>
+```
+
+反过来,内置的 `login.vue` / `layout.vue` / `404.vue` **一个都不用写** —— 框架内置兜底,只在你真有增量时才覆盖(见下面「唯一约定」)。
+
+---
+
+# 出错对照表
+
+接入时按症状反查,不必先懂原理。
+
+| 你看到的 | 病因 | 改哪 |
+| --- | --- | --- |
+| `resolveVue: components/layout.vue not found in sources`,整页白屏 | shrimp-admin 被 vite 预打包了 | vite.config `optimizeDeps.exclude: ['shrimp-admin']` |
+| `module component not found: module/<key>.vue`,菜单点不开 | 少了业务模块薄壳 | 补 `src/shrimp/module/<key>.vue`,模板第 4 节 |
+| 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 |
+| 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` |
+| `does not provide an export named 'default'`(dayjs / element-plus) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
+
+## 验收: 必须在浏览器里打开页面
+
+`vite build` 通过、`curl` 打接口通,**都不算接入完成**。上表前三行全部逃得过构建和接口测试:
+
+- dev 用 esbuild 预打包、build 用 rollup,是**两套转换管线**。rollup 正确处理 node_modules 里的 `import.meta.glob`,所以第 1 行的问题在 `vite build` 下一路绿灯,只在 dev 复现。
+- 样式和路由注册只在浏览器运行时才成立,接口测试根本不经过它们。
+
+# 那几行为什么不能删
+
+## `optimizeDeps.exclude: ['shrimp-admin']`
+
+Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `node_modules/.vite/deps/shrimp-admin.js`。两个后果:
+
+- 框架的内置组件表靠 `import.meta.glob('./{components,module}/**/*.vue')` 收集,这是 **Vite 编译期宏**,esbuild 不认识,会原样抄进产物;等它在 `.vite/deps/` 目录下才被展开时,那个目录里一个 `.vue` 都没有 → 内置表变成空对象 `{}` → 内置兜底全部落空。
+- 预打包等于复制出第二份模块实例,`vueAdmin` 单例会分裂成两个,消费侧拿到的和框架内部用的不是同一个。
+
+## element-plus 的两行 css
+
+`shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。
+
+## 业务模块薄壳
+
+框架靠 `sources` 里扫到的 `module/<key>.vue` 去 `registerRoute`。它没有别的途径知道你有哪些业务模块 —— 后端 moduleInfo 只告诉它「有个 key 叫 product」,渲染成哪个组件得你指定。壳里只有一行 `<ShrimpTable>`,但这一行就是那次指定。
+
+# 唯一约定: `sources` 路径后缀覆盖
+
+消费侧把所有要交给框架的 .vue 通过单个 `sources` 入口注入(`import.meta.glob` 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。
+
+```
+项目/
+└── src/shrimp/                       消费侧目录,可任意命名
+    ├── components/
+    │   ├── login.vue                 覆盖框架内置 login 页
+    │   ├── layout.vue                覆盖整体布局壳
+    │   └── fields/
+    │       └── FieldRelativeTime.vue 注册字段类型 relativeTime
+    └── module/
+        ├── product.vue               业务模块,routed by moduleKey
+        └── user/
+            └── orders.vue            子模块,parent=user
+```
+
+### 覆盖颗粒度只在这几个入口
+
+框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这几类入口,不会一路传递下去:
+
+| 入口 | 后缀 | 说明 |
+| --- | --- | --- |
+| **router targets** | `components/login.vue`、`components/layout.vue`、`components/404.vue` | vue-router 三个根级路由组件 |
+| **module routes** | `module/<key>.vue`、`module/<parent>/<sub>.vue` | 走 `registerRoute` 的业务模块/子模块 |
+| **field registry** | `components/fields/Field<X>.vue` | 字段类型注册表(文件名首字母小写 = type 键) |
+| **顶栏** | `components/userbar.vue` | 右上角那一条(语言、全屏、用户菜单),整体替换 |
+
+**表里没有的路径不会被覆盖,而且不报错**——写了个 `components/topbar.vue` 放进 sources,框架照样用内置那份,页面正常打开、你的文件被静默忽略。想换更细的部件就在消费侧的 `layout.vue` 里自己组装,框架不代理 peer 切换。
+
+### 字段类型注册
+
+`components/fields/Field<X>.vue` 自动注册类型 `<x>`(首字母小写):
+
+| 文件                       | type 注册键      |
+| -------------------------- | ---------------- |
+| `FieldString.vue`          | `string`         |
+| `FieldRelativeTime.vue`    | `relativeTime`   |
+| 你自己的 `FieldMyType.vue` | `myType`         |
+
+后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。
+
+内置类型以 `src/components/fields/` 目录为准,当前是: `array` / `boolean` / `date` / `number` / `object` / `password` / `relation` / `relativeTime` / `select` / `string` / `tab` / `textarea`。其中 `relativeTime` 是本实现独有的,shrimp-server 的 `ShrimpFieldTypes` 里没有。
+
+**没有 `json`。** 后端发一个没注册的 type 过来不会报错,`getFieldComponent` 静默回落成 `string` 渲染,只在控制台留一条 warning——列照样出、内容不对。字符串数组要用 `array` + `item`,嵌套对象用 `object` + `fields`。
+
+### 业务模块
+
+`module/<key>.vue` 命中 `moduleKey === '<key>'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。
+
+### 例子: 覆盖 login 页
+
+```vue
+<!-- src/shrimp/components/login.vue -->
+<template>
+    <div class="custom-login">
+        <h2>{{ vueAdmin.adminConfig.title || 'Admin' }}</h2>
+        <el-form :model="form" :rules="rules" @keyup.enter="login">
+            <el-form-item prop="user">
+                <el-input v-model="form.user" :placeholder="$t('login.userPlaceholder')" />
+            </el-form-item>
+            <el-form-item prop="password">
+                <el-input v-model="form.password" :placeholder="$t('login.PWPlaceholder')" show-password />
+            </el-form-item>
+            <el-button type="primary" :loading="info.islogin" @click="login">
+                {{ $t('login.signIn') }}
+            </el-button>
+        </el-form>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { reactive, computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { vueAdmin } from 'shrimp-admin'
+
+const { t } = useI18n()
+const info = reactive({ islogin: false })
+const form = reactive({ user: '', password: '' })
+const rules = computed(() => ({
+    user: [{ required: true, message: t('login.userError'), trigger: 'blur' }],
+    password: [{ required: true, message: t('login.PWError'), trigger: 'blur' }],
+}))
+
+function login() {
+    info.islogin = true
+    vueAdmin.fetchLogin({ username: form.user, password: form.password })
+        .then(async (data: any) => {
+            vueAdmin.token = data.token
+            await vueAdmin.loadUserInfo()
+            vueAdmin.router.push(vueAdmin.getFirstMenuPath())
+        })
+        .catch((e: any) => console.warn('[Login]', e.message))
+        .finally(() => { info.islogin = false })
+}
+</script>
+```
+
+只要文件落在 `src/shrimp/components/login.vue`,被 `sources` 的 glob 扫到,框架的 `/login` 路由就会用你这份替换内置版本。
+
+# 消费的契约
 
 参见 shrimp-server README `## 约定` 章节。本包消费以下条件契约:
 
 - **ShrimpTable**: list 响应 `{list,total,page,pageSize,totalPages}` / 字段 type 枚举 / populate `${key}_label`
 - **ShrimpServer**: HTTP 路由 / JWT Bearer / IUserAccessor 返回的 powers
-- **默认 Field*.vue**: 字段 type 必须是内置枚举之一,或通过 `customFields` 注册
-
-## 扩展点
-
-- `customFields` — 业务字段组件(`Field<Name>.vue`)
-- `moduleSources` — 业务模块组件(`module/<key>.vue` / `module/<parent>/<sub>.vue`)
-- `vueAdmin.registerField(type, comp)` / `overrideField(moduleKey, fieldKey, comp)` — 运行时也可

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "shrimp-admin",
-    "version": "0.1.0",
+    "version": "0.8.3",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "shrimp-admin",
-            "version": "0.1.0",
+            "version": "0.8.3",
             "dependencies": {
                 "shrimp-server": "git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.5.0"
             },

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-admin",
-    "version": "0.1.0",
+    "version": "0.8.3",
     "private": true,
     "description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现",
     "main": "src/index.ts",
@@ -17,8 +17,9 @@
         "src",
         "README.md"
     ],
-    "dependencies": {
-        "shrimp-server": "git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.5.0"
+    "scripts": {
+        "check:contract": "node scripts/check-contract.mjs",
+        "sync:contract": "node scripts/check-contract.mjs --fix"
     },
     "peerDependencies": {
         "vue": "^3.3.0",

scripts/check-contract.mjs

@@ -0,0 +1,61 @@
+/**
+ * 契约副本工具:比对 / 同步 src/IShrimpType.ts 与 shrimp-server 那份。
+ *
+ *   node scripts/check-contract.mjs          比对,漂了就非零退出
+ *   node scripts/check-contract.mjs --fix    从 shrimp-server 复制过来(自动保留前端副本的注释头)
+ *
+ * 为什么需要它:副本靠人工同步,漂了一整代都没被发现——
+ * 副本停在旧的 json 类型、缺 object/array/fields/item/parse/refs。
+ * 前端对未注册的字段类型静默回落到 string,所以漂移不报错、只悄悄渲染错。
+ * (同样是"改了就复制过去"的约定,goby 的 GobyClient.ts 四份拷贝已经全漂了,
+ *  区别只在于那份复制后归消费侧拥有、漂了无所谓,而这份两边必须字节一致。)
+ *
+ * 只比对注释块之后的正文:两边的头部本来就该不同,一份是契约、一份声明自己是副本。
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { dirname, resolve } from "node:path"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const mine = resolve(here, "../src/IShrimpType.ts")
+const fix = process.argv.includes("--fix")
+const argPath = process.argv.find(a => !a.startsWith("--") && a !== process.argv[0] && a !== process.argv[1])
+
+const theirs = [
+    argPath && resolve(argPath, "src/IShrimpType.ts"),
+    resolve(here, "../node_modules/shrimp-server/src/IShrimpType.ts"),
+    resolve(here, "../../shrimp-server/src/IShrimpType.ts"),
+].filter(Boolean).find(existsSync)
+
+if (!theirs) {
+    // 消费侧的前端项目不装后端包,找不到是正常的,不该让它们的构建挂掉
+    console.log("skip: 找不到 shrimp-server 源码,无从比对")
+    process.exit(0)
+}
+
+const split = f => {
+    const s = readFileSync(f, "utf8")
+    const i = s.indexOf("*/") + 2
+    return { head: s.slice(0, i), body: s.slice(i) }
+}
+
+const a = split(mine)
+const b = split(theirs)
+
+if (a.body === b.body) {
+    console.log("✅ 契约副本与 shrimp-server 一致")
+    process.exit(0)
+}
+
+if (fix) {
+    writeFileSync(mine, a.head + b.body)
+    console.log("✅ 已从 shrimp-server 同步契约副本(保留原注释头)")
+    console.log("   " + theirs + "\n → " + mine)
+    process.exit(0)
+}
+
+console.error("❌ 契约副本已漂移")
+console.error("   副本: " + mine)
+console.error("   契约: " + theirs)
+console.error("   修法: npm run sync:contract")
+process.exit(1)

src/App.vue

@@ -6,7 +6,7 @@
 
 <script lang="ts" setup>
 import { computed } from "vue";
-import { vueAdmin } from "../VueAdmin";
+import { vueAdmin } from "./VueAdmin";
 import zhCn from 'element-plus/es/locale/lang/zh-cn'
 import en from 'element-plus/es/locale/lang/en'
 
@@ -20,5 +20,5 @@ const locale = computed(() => {
 });
 </script>
 <style lang="scss">
-@use "../style/style.scss";
+@use "./style/style.scss";
 </style>

src/IShrimpType.ts

@@ -0,0 +1,387 @@
+/**
+ * Shrimp 类型契约 — 前后端 wire protocol 定义(前端副本)
+ *
+ * 这是 shrimp-server/src/IShrimpType.ts 的逐字副本(除本注释块外)。
+ * 不要在这里改 wire protocol,先改 shrimp-server 那份升版本,再整份 cp 过来。
+ *
+ * 本文件由 shrimp-server 的 postbuild 自动同步过来,手改会被下次 build 覆盖。
+ * 手动同步: npm run sync:contract   只想看漂没漂: npm run check:contract
+ * 自动同步这件事存在的原因是:曾经靠人工复制,漂了一整代都没人发现——
+ * 副本停在旧的 json 类型、缺 object/array/fields/item/parse/refs,
+ * 而前端对未注册类型静默回落到 string,所以漂移不会报错、只会悄悄渲染错。
+ *
+ * 故意保留副本而不 import 'shrimp-server' 的原因:
+ *   - shrimp-server 默认入口会把 mongoose / express 牵进前端 bundle
+ *   - 前端项目不该为一份纯类型去装后端包
+ */
+
+/** 业务错误码 */
+export enum ShrimpCode {
+    OK = 0,
+    FAIL = 1,
+    UNAUTHORIZED = 401,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    SERVER_ERROR = 500,
+}
+
+/** 业务错误 - tip 展示给用户 */
+export class ShrimpError extends Error {
+    code: ShrimpCode
+    tip: ILabel
+    constructor(tip: ILabel, code: ShrimpCode = ShrimpCode.FAIL) {
+        super(extractILabelText(tip))
+        this.code = code
+        this.tip = tip
+        this.name = 'ShrimpError'
+    }
+}
+
+/** 抽取 ILabel 的字符串形态用于 Error.message / 日志(非展示) */
+function extractILabelText(v: ILabel): string {
+    if (typeof v === 'string') return v
+    if (v && typeof v === 'object') {
+        const o = v as any
+        if ('t' in o) return o.t
+        if ('tc' in o) return o.tc
+        if ('d' in o) return String(o.d)
+        if ('n' in o) return String(o.n)
+    }
+    return '[ILabel]'
+}
+
+/** 统一响应格式 */
+export interface IShrimpResponse<T = any> {
+    code: ShrimpCode
+    data?: T
+    tip?: ILabel         // 给用户看的提示
+    log?: string         // 给开发者看的日志
+}
+
+/** 模块信息（结构元数据，扁平表示：子模块与主模块同列，通过 parent 关联） */
+export interface IModuleInfo {
+    moduleKey: string
+    events: string[]
+    label: ILabel
+    fields: IFieldConfig[]
+    icon?: string                 // 子模块跳转按钮图标（element-plus icon 名称）
+    parent?: string               // 父模块 moduleKey；存在即为子模块（不进菜单、路径嵌套）
+}
+
+/** 登录结果（仅 token） */
+export interface ILoginResult {
+    token: string
+}
+
+/** 当前用户信息 */
+export interface IMeResult {
+    nickname?: string
+    moduleInfo: IModuleInfo[]
+    menuTree: IMenuItem[]
+    options?: Record<string, any>
+}
+
+// ============== 通用类型 ==============
+
+/**
+ * 通用国际化标签 - 所有前端可见文本字段统一类型
+ *
+ * 形态:
+ *  - string                                  字面量,前端原样显示
+ *  - { t: 'i18n.key', params?: ... }         翻译(vue-i18n t)
+ *  - { tc: 'i18n.key', count, params?: ... } 复数(vue-i18n tc)
+ *  - { d: Date|number, format? }             日期格式化(vue-i18n d)
+ *  - { n: number, format? }                  数字/货币格式化(vue-i18n n)
+ *  - { zh: '提交', en: 'Submit' }            内联多语言
+ *
+ * params 值本身可以是 ILabel,前端递归解析
+ */
+export type ILabel =
+    | string
+    | { t: string; params?: Record<string, ILabel | any> }
+    | { tc: string; count: number; params?: Record<string, ILabel | any> }
+    | { d: number | Date; format?: string }
+    | { n: number; format?: string }
+    | Record<string, string>
+
+/** 菜单项 */
+export interface IMenuItem {
+    name: string
+    icon?: string
+    label: ILabel                // 菜单显示名称
+    path?: string
+    moduleKey?: string
+    children?: IMenuItem[]
+}
+
+// ============== Proto 协议定义 ==============
+
+/** 标准 Table CRUD 协议（前端可见） */
+export interface ITableProto<T> {
+    list(query?: IPageQuery & any): Promise<IPageResult<T>>
+    get(id: string): Promise<T | null>
+    add(item: Omit<T, '_id'>, ownerId?: string): Promise<T>
+    edit(id: string, item: Partial<T>): Promise<T | null>
+    delete(id: string): Promise<boolean>
+}
+
+/** 完整 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 interface IUser {
+    username: string
+    password: string
+    nickname: string
+    roleId: string[]
+    active: boolean
+    createdAt: number
+    updatedAt: number
+}
+
+/** 角色 */
+export interface IRole {
+    name: string
+    description: string
+    isSuperAdmin: boolean
+    powers: string[]
+    createdAt: number
+    updatedAt: number
+}
+
+/** 操作日志 */
+export interface IOperationLog {
+    operatorId: string | null   // 操作者 userId,登录失败等场景为 null
+    ip: string                  // 来源 IP
+    method: string              // RPC 路径,如 "user.edit"、"login"
+    args: string                // 参数(已脱敏 + JSON.stringify + 截断)
+    success: boolean
+    errorMsg: string            // success=false 时填错误信息
+    createdAt: number
+}
+
+/** 为数据模型注入 _id 的泛型工具类型 */
+export type WithId<T> = T & { _id: string }
+
+/** 操作者契约 - 框架层通用操作者上下文，不依赖具体用户模型 */
+export interface IShrimpOperator {
+    userId: string
+    roleId: string[]
+    isSuperAdmin: boolean
+}
+
+/** 权限 */
+export interface IShrimpPowerData {
+    _id: string
+    powerKey: string
+}
+
+// ============== 前端客户端接口 ==============
+
+/** 底层请求函数类型 */
+export type ShrimpRequestFn = (path: string[], ...args: any[]) => Promise<IShrimpResponse>
+
+/** Shrimp 客户端接口（前端实现） */
+export interface IShrimpClient {
+    shrimpRequest: ShrimpRequestFn
+    hasEvent(moduleKey: string, eventName: string): boolean
+}
+
+// ============== 字段配置 ==============
+//
+// 【功能说明 - 给前端】
+//
+// IFieldConfig 是 Shrimp 框架的动态字段配置系统。
+// 后端模块定义 fields 后，前端通过 GET /me 获取 moduleInfo[].fields，
+// 即可自动生成表格列、搜索栏、新增/编辑表单，无需硬编码页面结构。
+//
+// 注意: _id 由框架自动注入(tableHide=true), 不需要在 fields 中配置, 数据返回但表格不显示。
+//
+// 使用流程：
+//   1. 调用 GET /me → 拿到 moduleInfo 数组
+//   2. 每个 moduleInfo 包含: moduleKey(模块名), events(可调用接口), fields(字段配置)
+//   3. 根据 fields 渲染:
+//      - 表格列: 非 hidden 且非 tableHide 的字段 → 列标题=label, 数据=key
+//      - 搜索栏: searchable=true 的字段 → 渲染对应类型的搜索输入
+//      - 表单:   非 hidden 且 editable≠"readonly" 的字段, 根据 editable 决定:
+//                  editable="always" 或缺省 → 新增/编辑都可编辑
+//                  editable="readonly"      → 新增/编辑都不可编辑(只读,如createdAt)
+//                  editable="addOnly"       → 新增可编辑, 编辑时不可编辑(如username)
+//                required=true 的字段标记必填, defaultValue 填入默认值
+//      - 排序:   sortable=true 的字段 → 表头可点击排序
+//
+// type 与前端控件映射建议:
+//   string    → Input 文本框
+//   number    → InputNumber 数字框
+//   boolean   → Switch 开关
+//   date      → DatePicker 日期选择器
+//   select    → Select 下拉框, 选项由 options 提供
+//   textarea  → Input.TextArea 多行文本
+//   password  → Input.Password 密码框
+//   relation  → Select 下拉框, 选项从 moduleKey 指定的模块 list 接口获取,
+//               显示字段为 labelKey, 值为 _id
+//
+
+/** 字段类型（string 基础类型，前端可自由扩展自定义类型） */
+export type ShrimpFieldType = string
+
+/** 框架内置字段类型常量（前端可直接使用或在此基础上扩展） */
+export const ShrimpFieldTypes = {
+    String: "string" as ShrimpFieldType,
+    Number: "number" as ShrimpFieldType,
+    Boolean: "boolean" as ShrimpFieldType,
+    Date: "date" as ShrimpFieldType,
+    Select: "select" as ShrimpFieldType,
+    Textarea: "textarea" as ShrimpFieldType,
+    Password: "password" as ShrimpFieldType,
+    Relation: "relation" as ShrimpFieldType,
+    Tab: "tab" as ShrimpFieldType,
+    Object: "object" as ShrimpFieldType,
+    Array: "array" as ShrimpFieldType,
+}
+
+/** 字段可编辑状态 */
+export type FieldEditable = "always" | "readonly" | "addOnly"
+
+/** 字段类型处理器：定义每种 type 在请求/响应时的转换、验证、默认值 */
+export interface IFieldTypeHandler {
+    /** 请求过滤：前端提交 → 保存前转换（如密码哈希、trim） */
+    reqFilter?: (value: any, field: IFieldConfig, item: Record<string, any>) => any | Promise<any>
+    /** 响应过滤：数据库取出 → 返回前端前转换（如密码脱敏为 ***、日期格式化） */
+    resFilter?: (value: any, field: IFieldConfig, item: Record<string, any>) => any
+    /** 验证：保存前校验，返回错误 ILabel 或 null（可直接返回字面字符串、{t}、{tc} 等） */
+    validate?: (value: any, field: IFieldConfig, item: Record<string, any>) => ILabel | null | Promise<ILabel | null>
+    /** 新增时的默认值（静态值或工厂函数） */
+    defaultValue?: any | (() => any)
+}
+
+/** 字段配置 */
+export interface IFieldConfig {
+    key: string                   // 字段名（对应数据对象的属性名）
+    label: ILabel                 // 显示名称（表格列标题、表单标签）
+    type: ShrimpFieldType         // 字段类型（决定前端渲染哪种控件）
+    required?: boolean            // 是否必填（表单校验）
+    hidden?: boolean              // 数据不返回给前端
+    tableHide?: boolean           // 表格中不显示此列，但数据仍返回（如 _id）
+    editable?: FieldEditable      // 可编辑状态: always(默认,始终可编辑) | readonly(始终只读,如createdAt) | addOnly(仅添加可编辑,编辑时只读,如username)
+    searchable?: boolean          // 是否可搜索（出现在搜索栏）
+    sortable?: boolean            // 是否可排序（表头可点击排序）
+    filterable?: boolean          // 是否可筛选（出现在筛选栏，用于 filter 精确匹配）
+    options?: { label: ILabel; value: any }[] | string  // select 类型的可选项，或全局 options key
+    relation?: {                  // relation 类型的关联配置
+        moduleKey: string         // 关联模块名（从该模块的 list 接口获取选项）
+        labelKey: string          // 关联模块中用作显示的字段名
+    }
+    defaultValue?: any            // 新增时的默认值（优先级高于 typeHandler.defaultValue）
+    multiple?: boolean            // 是否支持多选（relation、select 等）
+    rules?: IFieldRule[]          // 通用验证规则（前后端共用）
+    /** tab 类型专用：每个 type 对应的子字段配置 */
+    tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
+    /** object 类型专用：嵌套字段组 */
+    fields?: IFieldConfig[]
+    /** array 类型专用：每个元素的字段配置(递归 IFieldConfig；元素无需 key，label 用作每项标题) */
+    item?: IFieldConfig
+    /** tab 类型专用：import 反序列化(把字符串还原成对象，如 xlsx 导入)，默认 JSON.parse */
+    parse?: (text: string) => any
+}
+
+/** 通用验证规则（前后端共用） */
+export interface IFieldRule {
+    required?: boolean
+    min?: number
+    max?: number
+    pattern?: string
+    message?: ILabel
+}
+
+// ============== 预制协议 ==============
+
+/** 分页查询参数 */
+export interface IPageQuery {
+    page?: number            // 页码，从 1 开始
+    pageSize?: number        // 每页数量，默认 ShrimpConfig.defaultPageSize
+    keyword?: string         // 关键词搜索，按 searchable 字段模糊匹配
+    sortBy?: string          // 排序字段（对应 field.key）
+    sortOrder?: 'asc' | 'desc'  // 排序方向
+    filter?: Record<string, any>  // 字段精确匹配条件（AND 关系）
+    ownerId?: string         // 子表场景: 父记录 _id。后端按模块 ownerKey 配置翻译为 filter 注入(用户无法绕过)
+}
+
+/** Shrimp 全局配置 */
+export class ShrimpConfig {
+    static defaultPageSize: number = 100000
+}
+
+/** 分页结果 */
+export interface IPageResult<T> {
+    list: T[]         // 当前页数据
+    total: number       // 总记录数
+    page: number       // 当前页码
+    pageSize: number   // 每页数量
+    totalPages: number // 总页数
+    refs?: Record<string, Record<string, any>>  // relation 显示名字典: { moduleKey: { id: 显示名 } }，前端显示时查名，替代逐行 _label
+}
+
+// ============== 数据源查询协议 ==============
+//
+// IShrimpQuery 是数据源无关的查询协议。
+// ShrimpTableModule 负责将前端参数(IPageQuery)翻译为 IShrimpQuery，
+// 各 ShrimpCrud 实现(MemoryCrud/MongoShrimpCrud)负责执行。
+//
+// 查询语义:
+//   WHERE (where 全部满足) AND (orWhere 至少一组满足)
+//   ORDER BY order
+//   LIMIT limit OFFSET offset
+//
+
+/** 查询条件运算符 */
+export interface IShrimpCondition {
+    eq?: any           // 精确匹配 (=)
+    in?: any[]         // IN 查询
+    like?: string      // 模糊匹配 (不区分大小写)
+    gte?: any          // 大于等于 (>=)
+    lte?: any          // 小于等于 (<=)
+}
+
+/** 判断值是否为 IShrimpCondition 对象 */
+export function isShrimpCondition(val: any): val is IShrimpCondition {
+    return val != null && typeof val === 'object' && !Array.isArray(val)
+        && ('eq' in val || 'in' in val || 'like' in val || 'gte' in val || 'lte' in val)
+}
+
+/** 关联填充指令 */
+export interface IShrimpPopulate {
+    key: string           // 当前模块的字段名 (如 roleId)
+    moduleKey: string     // 关联模块名 (如 role)
+    labelKey: string      // 关联模块中用作显示的字段 (如 name)
+}
+
+/** 通用查询协议 (数据源无关) */
+export interface IShrimpQuery {
+    where?: Record<string, IShrimpCondition | any>  // AND 条件 (原始值=eq简写)
+    orWhere?: Record<string, IShrimpCondition>[]    // OR 条件组 (用于 keyword)
+    order?: [string, 'asc' | 'desc'][]              // 排序
+    offset?: number                                  // 偏移量
+    limit?: number                                   // 限制数量
+    populate?: IShrimpPopulate[]                     // 关联填充 (输出 {key}_label)
+}
+
+/** 权限项 */
+export interface IPowerItem {
+    key: string
+    label: ILabel
+}
+
+/** 用户模块协议 */
+export interface IUserProto extends ITableCrudProto<WithId<IUser>> { }
+
+/** 角色模块协议 */
+export interface IRoleProto extends ITableCrudProto<WithId<IRole>> {
+    allPower(): Promise<IPowerItem[]>
+}

src/ShrimpClient.ts

@@ -2,7 +2,7 @@
  * ShrimpClient — Shrimp 框架前端基类
  * 框架无关层，包含协议通信、模块管理、菜单树操作
  */
-import { ShrimpCode, ShrimpRequestFn, IShrimpResponse, IModuleInfo, IMenuItem, ILoginResult, IMeResult, IShrimpClient, ILabel } from 'shrimp-server/types'
+import { ShrimpCode, ShrimpRequestFn, IShrimpResponse, IModuleInfo, IMenuItem, ILoginResult, IMeResult, IShrimpClient, ILabel } from './IShrimpType'
 
 /** tip 展示接口（由框架层实现，如 Element Plus）。msg 是 ILabel,实现层负责翻译后展示 */
 export interface IShrimpTipper {

src/VueAdmin.ts

@@ -7,10 +7,25 @@ import { createRouter, createWebHashHistory, Router } from 'vue-router'
 import zh_cn from './locales/zh-cn.json'
 import en from './locales/en.json'
 import { createI18n, I18n } from 'vue-i18n'
-import { IShrimpResponse, ILabel } from 'shrimp-server/types'
+import { IShrimpResponse, ILabel } from './IShrimpType'
 
 import { ShrimpClient, handleShrimpResponse, type IShrimpTipper, type IRouteInfo } from './ShrimpClient'
-import FieldString from './components/fields/FieldString.vue'
+
+// ============== 工具 ==============
+
+/** locale 深合并:嵌套对象按 key 递归 merge,非对象值 src 覆盖 dst。仅服务于 i18n messages,没必要拉 lodash。 */
+function deepMerge(dst: Record<string, any>, src: Record<string, any>): Record<string, any> {
+    const out: Record<string, any> = { ...dst }
+    for (const key in src) {
+        const sv = src[key], dv = out[key]
+        if (sv && typeof sv === 'object' && !Array.isArray(sv) && dv && typeof dv === 'object' && !Array.isArray(dv)) {
+            out[key] = deepMerge(dv, sv)
+        } else {
+            out[key] = sv
+        }
+    }
+    return out
+}
 
 // ============== Options ==============
 
@@ -23,50 +38,87 @@ export interface ShrimpAdminConfig {
     LS_ENCRYPTION_key?: string
 }
 
+type VueLoader = () => Promise<any>
+
 export interface ShrimpAdminOptions {
     config: ShrimpAdminConfig
-    /** 业务模块组件:`import.meta.glob('./module/**\/*.vue')` 的结果 */
-    moduleSources?: Record<string, () => Promise<{ default: Component } | Component>>
-    /** 业务字段组件:`import.meta.glob('./module/fields/Field*.vue')`,文件名 FieldXxx → type='fieldXxx' */
-    customFields?: Record<string, () => Promise<{ default: Component } | Component>>
+    /**
+     * 消费侧 .vue 源,推荐 `import.meta.glob('./shrimp/**\/*.vue')`。
+     * - `shrimp/components/<name>.vue` 同后缀覆盖框架内置(login/layout/topbar/ShrimpTable/...)
+     * - `shrimp/components/fields/Field<X>.vue` 注册字段类型 `<x>`(首字母小写),同名覆盖内置
+     * - `shrimp/module/<key>.vue` 业务模块组件(routed by moduleKey)
+     */
+    sources?: Record<string, VueLoader>
     /** 语言资源,与框架自带的合并(消费侧同 key 覆盖框架默认) */
     locales?: Record<string, any>
     /** 语言列表,默认 [{ lang: 'zh-cn', name: '简体中文' }] */
     langList?: { lang: string; name: string }[]
 }
 
+// ============== 源注册表 ==============
+//
+// 框架在 3 个入口点用消费侧 sources 覆盖内置(按路径后缀同后缀覆盖):
+//   1. router: components/{layout,login,404}.vue
+//   2. registerRoute: module/<key>.vue 等业务模块
+//   3. fieldRegistry: components/fields/Field<X>.vue (按文件名导出的字段类型)
+// 框架内 .vue 之间的 peer 引用是硬编码静态 import,override 颗粒度就停在上面这些"入口"。
+
+const internalSources = import.meta.glob<Component>('./{components,module}/**/*.vue')
+const externalSources: Record<string, VueLoader> = {}
+
+/**
+ * 路径后缀匹配解析: 消费侧优先,内置兜底。
+ * suffix 形如 `components/login.vue` / `module/user.vue` / `module/user/operationLog.vue`。
+ */
+export function resolveVue(suffix: string): VueLoader {
+    const tail = '/' + suffix
+    for (const key in externalSources) {
+        if (key.endsWith(tail)) return externalSources[key]
+    }
+    for (const key in internalSources) {
+        if (key.endsWith(tail)) return internalSources[key] as any
+    }
+    // 内置表整个是空的,说明本包被 esbuild 预打包了——import.meta.glob 是 vite 编译期宏,
+    // 预打包不认它,内置组件一个都收不到。报"找不到 layout.vue"会把人引向错误的方向。
+    if (Object.keys(internalSources).length === 0) {
+        throw new Error(
+            `[shrimp-admin] 内置组件表为空,本包没有被 vite 正常转换。\n` +
+            `  消费侧 vite.config 需要: optimizeDeps: { exclude: ["shrimp-admin"] }\n` +
+            `  (或直接用 shrimp-admin/vite 提供的插件,它会自动加上)`
+        )
+    }
+    throw new Error(`[shrimp-admin] resolveVue: ${suffix} not found in sources`)
+}
+
 // ============== 字段组件注册表 ==============
+//
+// 约定:`components/fields/Field<X>.vue` → 字段类型 `<x>`(首字母小写)。
+// 后端 moduleInfo 的 field.type 命中这里的 key 就用对应组件,否则回退到 string。
 
 const fieldRegistry = new Map<string, Component>()
-const fieldOverrides = new Map<string, string>()
 
-fieldRegistry.set('string', FieldString)
-fieldRegistry.set('boolean', defineAsyncComponent(() => import('./components/fields/FieldBoolean.vue')))
-fieldRegistry.set('date', defineAsyncComponent(() => import('./components/fields/FieldDate.vue')))
-fieldRegistry.set('number', defineAsyncComponent(() => import('./components/fields/FieldNumber.vue')))
-fieldRegistry.set('password', defineAsyncComponent(() => import('./components/fields/FieldPassword.vue')))
-fieldRegistry.set('relation', defineAsyncComponent(() => import('./components/fields/FieldRelation.vue')))
-fieldRegistry.set('select', defineAsyncComponent(() => import('./components/fields/FieldSelect.vue')))
-fieldRegistry.set('textarea', defineAsyncComponent(() => import('./components/fields/FieldTextarea.vue')))
-fieldRegistry.set('json', defineAsyncComponent(() => import('./components/fields/FieldJson.vue')))
-fieldRegistry.set('tab', defineAsyncComponent(() => import('./components/fields/FieldTab.vue')))
+/** 未注册类型每种只喊一次——表格逐格调 getFieldComponent,不去重会刷屏 */
+const warnedTypes = new Set<string>()
+function warnOnce(type: string, moduleKey?: string, fieldKey?: string) {
+    if (warnedTypes.has(type)) return
+    warnedTypes.add(type)
+    console.warn(
+        `[shrimp-admin] 字段类型 "${type}" 没有对应组件,已按 string 渲染` +
+        (moduleKey || fieldKey ? `(出现在 ${moduleKey ?? '?'}.${fieldKey ?? '?'})` : '') +
+        `\n  已注册: ${[...fieldRegistry.keys()].sort().join(', ')}` +
+        `\n  要么后端把 type 改成上面之一,要么消费侧补一个 shrimp/components/fields/Field${type.charAt(0).toUpperCase() + type.slice(1)}.vue`
+    )
+}
 
-// 框架自带模块组件 — vite glob 相对本文件解析,扫到的是 shrimp-admin 内部的 module/
-const internalModules = import.meta.glob<Component>('./module/**/*.vue')
+function deriveFieldType(path: string): string | null {
+    const m = path.match(/\/components\/fields\/Field([A-Z][A-Za-z0-9]*)\.vue$/)
+    if (!m) return null
+    return m[1][0].toLowerCase() + m[1].slice(1)
+}
 
-// 业务模块由消费侧通过 createShrimpAdmin({ moduleSources }) 注册
-const externalModules: Record<string, () => Promise<any>> = {}
-
-function resolveModuleComponent(componentPath: string): (() => Promise<any>) | null {
-    const suffix = `/module/${componentPath}.vue`
-    // 业务优先(允许覆盖同名内置)
-    for (const key in externalModules) {
-        if (key.endsWith(suffix)) return externalModules[key]
-    }
-    for (const key in internalModules) {
-        if (key.endsWith(suffix)) return internalModules[key] as any
-    }
-    return null
+for (const path in internalSources) {
+    const type = deriveFieldType(path)
+    if (type) fieldRegistry.set(type, defineAsyncComponent(internalSources[path] as any))
 }
 
 // ============== LocalData ==============
@@ -93,21 +145,22 @@ export class VueAdmin extends ShrimpClient {
     userName = ''
     config: ShrimpAdminConfig
     langList: { lang: string; name: string }[]
+    /** 已注册成功的模块路由(moduleKey → IRouteInfo)，供 relation 跳转/单项查看解析路由 */
+    moduleRoutes = new Map<string, IRouteInfo>()
 
-    registerField(type: string, comp: Component) { fieldRegistry.set(type, comp) }
-
-    overrideField(moduleKey: string, fieldKey: string, comp: Component) {
-        const registryKey = `__override_${moduleKey}_${fieldKey}`
-        fieldRegistry.set(registryKey, comp)
-        fieldOverrides.set(`${moduleKey}.${fieldKey}`, registryKey)
+    getFieldComponent(_moduleKey: string, type: string, _fieldKey?: string): Component {
+        const hit = fieldRegistry.get(type)
+        if (hit) return hit
+        // 类型词汇表是开放的(消费侧放个 Field<X>.vue 就能扩),所以这里不能报错、只能回落。
+        // 但静默回落等于打错字永远发现不了——曾经有个 json 类型这么活了一整代。
+        warnOnce(type, _moduleKey, _fieldKey)
+        return fieldRegistry.get('string')!
     }
 
-    getFieldComponent(moduleKey: string, type: string, fieldKey?: string): Component {
-        if (fieldKey) {
-            const override = fieldOverrides.get(`${moduleKey}.${fieldKey}`)
-            if (override && fieldRegistry.has(override)) return fieldRegistry.get(override)!
-        }
-        return fieldRegistry.get(type) || FieldString
+    /** 目标模块能否作为「单项查看」跳转目标:已按权限注册路由 且 非子模块。返回其路由信息或 undefined(不可跳) */
+    routeForModule(moduleKey: string): IRouteInfo | undefined {
+        if (this.moduleInfo.find(m => m.moduleKey === moduleKey)?.parent) return undefined
+        return this.moduleRoutes.get(moduleKey)
     }
 
     state = reactive({ isMobile: false })
@@ -145,15 +198,11 @@ export class VueAdmin extends ShrimpClient {
         this.config = opts.config
         this.langList = opts.langList || [{ lang: 'zh-cn', name: '简体中文' }]
 
-        // 业务模块/字段注册
-        if (opts.moduleSources) Object.assign(externalModules, opts.moduleSources)
-        if (opts.customFields) {
-            for (const path in opts.customFields) {
-                const match = path.match(/\/Field(.+)\.vue$/)
-                if (match) {
-                    const name = 'field' + match[1]
-                    fieldRegistry.set(name, defineAsyncComponent(opts.customFields[path] as any))
-                }
+        if (opts.sources) {
+            Object.assign(externalSources, opts.sources)
+            for (const path in opts.sources) {
+                const type = deriveFieldType(path)
+                if (type) fieldRegistry.set(type, defineAsyncComponent(opts.sources[path] as any))
             }
         }
 
@@ -169,14 +218,14 @@ export class VueAdmin extends ShrimpClient {
     }
 
     initI18n(extraLocales?: Record<string, any>) {
-        const merged: Record<string, any> = {
-            'zh-cn': { ...zh_cn, ...(extraLocales?.['zh-cn'] || {}) },
-            'en': { ...en, ...(extraLocales?.['en'] || {}) },
-        }
-        if (extraLocales) {
-            for (const key in extraLocales) {
-                if (!(key in merged)) merged[key] = extraLocales[key]
-            }
+        // 深合并:框架自带 locale 在底,业务侧叠在上。
+        // 旧版用 spread 浅合并,业务侧只要定义了同名一级键(如 user)就会把框架的 user.* 全部替换,
+        // 表现是控制台 [intlify] Not found 'user.operationLog' key 之类的报错。
+        const builtins: Record<string, any> = { 'zh-cn': zh_cn, 'en': en }
+        const merged: Record<string, any> = {}
+        const langs = new Set([...Object.keys(builtins), ...Object.keys(extraLocales || {})])
+        for (const lang of langs) {
+            merged[lang] = deepMerge(builtins[lang] || {}, extraLocales?.[lang] || {})
         }
         this.i18n = createI18n({
             locale: this.localData.get("lang") || 'zh-cn',
@@ -228,8 +277,10 @@ export class VueAdmin extends ShrimpClient {
 
     registerRoute(info: IRouteInfo) {
         const componentPath = info.componentPath || info.moduleKey
-        const importer = resolveModuleComponent(componentPath)
-        if (!importer) {
+        let importer: VueLoader
+        try {
+            importer = resolveVue(`module/${componentPath}.vue`)
+        } catch {
             console.warn(`[shrimp-admin] module component not found: module/${componentPath}.vue`)
             return
         }
@@ -240,6 +291,7 @@ export class VueAdmin extends ShrimpClient {
             props: { moduleKey: info.moduleKey, events: info.events },
             meta: { title: info.label }
         })
+        this.moduleRoutes.set(info.moduleKey, info)
     }
 
     initRouter() {
@@ -249,17 +301,17 @@ export class VueAdmin extends ShrimpClient {
                 {
                     name: "layout",
                     path: "/",
-                    component: () => import('./views/layout.vue'),
+                    component: resolveVue('components/layout.vue'),
                     children: []
                 },
                 {
                     path: "/login",
-                    component: () => import('./views/login.vue'),
-                    meta: { title: "t:login.signIn" }
+                    component: resolveVue('components/login.vue'),
+                    meta: { title: { t: 'login.signIn' } }
                 },
                 {
                     path: "/:pathMatch(.*)",
-                    component: () => import('./views/404.vue'),
+                    component: resolveVue('components/404.vue'),
                 },
             ],
         })
@@ -327,7 +379,7 @@ export class VueAdmin extends ShrimpClient {
                 }
             },
             (error) => {
-                ElMessage.error(this.t('t:base.netError'))
+                ElMessage.error(this.t({ t: 'base.netError' }))
                 throw error
             }
         )

src/components/ShrimpEditDrawer.vue

@@ -22,7 +22,7 @@
 
 <script lang="ts" setup>
 import { provide, computed, ref } from 'vue'
-import { IFieldConfig, IFieldRule } from 'shrimp-server/types'
+import { IFieldConfig, IFieldRule } from '../IShrimpType'
 import { vueAdmin } from '../VueAdmin'
 import type { FormInstance, FormItemRule } from 'element-plus'
 
@@ -53,7 +53,7 @@ function buildRules(field: IFieldConfig): FormItemRule[] {
     if (field.required) {
         rules.push({
             required: true,
-            message: vueAdmin.t('shrimp.fieldRequired'),
+            message: vueAdmin.t({ t: 'shrimp.fieldRequired', params: { field: field.label } }),
             trigger: 'change',
             ...(field.type === 'string' || field.type === 'textarea' || field.type === 'password' ? { trigger: 'blur' } : {}),
         })

src/components/ShrimpFilterDrawer.vue

@@ -4,11 +4,18 @@
         <el-form :model="localFilterData">
             <template v-for="field in filterableFields" :key="field.key">
                 <el-form-item :label="vueAdmin.t(field.label)">
+                    <div class="filter-field-row">
+                        <div class="filter-field-control">
                             <slot :name="`filter-${field.key}`" :field="field" :data="localFilterData">
-                        <component :is="vueAdmin.getFieldComponent(moduleKey, field.type, field.key)" :field="field"
-                            :model-value="localFilterData[field.key]"
+                                <component :is="vueAdmin.getFieldComponent(moduleKey, field.type, field.key)"
+                                    :field="field" :model-value="localFilterData[field.key]"
                                     @update:model-value="onFieldChange(field.key, $event)" mode="filter" />
                             </slot>
+                        </div>
+                        <!-- 单独清空该字段:常驻、无值时禁用(不 v-if,避免按钮显隐导致布局闪动) -->
+                        <el-button link :icon="CircleClose" class="filter-clear"
+                            :disabled="!hasValue(field.key)" @click="clearField(field.key)" />
+                    </div>
                 </el-form-item>
             </template>
         </el-form>
@@ -21,7 +28,8 @@
 
 <script lang="ts" setup>
 import { ref, watch } from 'vue'
-import { IFieldConfig } from 'shrimp-server/types'
+import { CircleClose } from '@element-plus/icons-vue'
+import { IFieldConfig } from '../IShrimpType'
 import { vueAdmin } from '../VueAdmin'
 
 interface Props {
@@ -68,6 +76,21 @@ function onFieldChange(key: string, value: any) {
     localFilterData.value = { ...localFilterData.value, [key]: value }
 }
 
+// 该字段当前是否有筛选值(决定单独清空按钮是否出现);范围 {gte,lte}/数组按内容判空
+function hasValue(key: string): boolean {
+    const v = localFilterData.value[key]
+    if (v == null || v === '') return false
+    if (Array.isArray(v)) return v.length > 0
+    if (typeof v === 'object') return Object.keys(v).length > 0
+    return true
+}
+
+// 单独清空某个字段:只摘掉这一个 key,其余筛选条件不动
+function clearField(key: string) {
+    const { [key]: _, ...rest } = localFilterData.value
+    localFilterData.value = rest
+}
+
 function handleReset() {
     closedByReset.value = true
     localFilterData.value = {}
@@ -101,4 +124,23 @@ function handleConfirm() {
 .shrimp-drawer .el-drawer__body .el-form-item {
     margin-bottom: 20px;
 }
+
+.filter-field-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    width: 100%;
+}
+
+.filter-field-control {
+    flex: 1;
+    min-width: 0;
+}
+
+.filter-clear {
+    flex: none;
+    padding: 0;
+    font-size: 16px;
+    color: var(--el-text-color-secondary);
+}
 </style>

src/components/ShrimpPowerTree.vue

@@ -8,7 +8,7 @@
 <script lang="ts" setup>
 import { ref, computed, watch, nextTick } from 'vue'
 import { vueAdmin } from '../VueAdmin'
-import type { IMenuItem, ILabel } from 'shrimp-server/types'
+import type { IMenuItem, ILabel } from '../IShrimpType'
 
 interface IPowerItem {
     key: string

src/components/ShrimpTable.vue

@@ -29,13 +29,13 @@
                             <slot :name="`column-${field.key}`" :row="row" :field="field">
                                 <component :is="vueAdmin.getFieldComponent(moduleKey, field.type, field.key)" :field="field"
                                     :model-value="row[field.key]" mode="display"
-                                    v-bind="field.type === 'relation' || field.type === 'textarea' ? { displayLabel: row[field.key + '_label'] } : {}" />
+                                    v-bind="field.type === 'textarea' ? { displayLabel: row[field.key + '_label'] } : {}" />
                             </slot>
                         </template>
                     </el-table-column>
                 </template>
 
-                <el-table-column :label="$t('base.operation')" :width="rowActionsWidth" v-if="hasRowActions">
+                <el-table-column :label="$t('base.operation')" :width="resolvedRowActionsWidth" v-if="hasRowActions">
                     <template #default="{ row }">
                         <el-button v-if="hasActiveField && can('edit')" link :type="row.active ? 'warning' : 'success'" :icon="row.active ? VideoPause : VideoPlay" size="large" @click="handleToggleActive(row)" />
                         <el-button v-if="can('edit')" link type="primary" :icon="Edit" size="large" @click="handleEdit(row)" />
@@ -78,8 +78,8 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, computed, useSlots, onMounted, type Component } from 'vue'
-import { ITableCrudProto, IFieldConfig, IModuleInfo, IPageQuery } from 'shrimp-server/types'
+import { ref, computed, useSlots, onMounted, provide, type Component } from 'vue'
+import { ITableCrudProto, IFieldConfig, IModuleInfo, IPageQuery } from '../IShrimpType'
 import { vueAdmin } from '../VueAdmin'
 import { Plus, Delete as DeleteIcon, Download, Upload, Edit, VideoPlay, VideoPause, Operation } from '@element-plus/icons-vue'
 import * as ElIcons from '@element-plus/icons-vue'
@@ -100,6 +100,8 @@ interface Props {
     pageSize?: number
     /** 显式锁定的筛选条件(覆盖自动 ownerKey 推断);用户无法修改,会合并进 filter 并在筛选抽屉中隐藏 */
     baseFilter?: Record<string, any>
+    /** 显式指定操作列宽度;传入后覆盖按内置按钮数量自动计算的宽度,适用于 row-actions 插槽塞了多个按钮的场景 */
+    rowActionsWidth?: number | string
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -132,8 +134,18 @@ const {
 
 const searchVisible = ref(false)
 
+// relation 跳转用 ?filter={_id} 锁定单条；_id 是隐形 pin(不在筛选抽屉里)，
+// 用户一旦搜索/改筛选就清掉它，避免被看不见的 _id 一直 AND 着导致结果莫名为空
+function stripJumpPin() {
+    if ('_id' in filterData.value) {
+        const { _id, ...rest } = filterData.value
+        filterData.value = rest
+    }
+}
+
 function onSearch() {
     searchKeyword.value = keyword.value
+    stripJumpPin()
     currentPage.value = 1
     refresh()
 }
@@ -151,7 +163,8 @@ const hasFilter = computed(() => {
 })
 
 async function handleFilterConfirm(newFilterData: Record<string, any>) {
-    filterData.value = newFilterData
+    const { _id, ...rest } = newFilterData   // 确认筛选 → 丢弃跳转 pin
+    filterData.value = rest
     currentPage.value = 1
     await refresh()
 }
@@ -201,9 +214,24 @@ const formFields = computed(() => {
     return list.filter(f => f.editable !== 'readonly')
 })
 const searchableFields = computed(() => fields.value.filter(f => f.searchable))
+// 递归收集 filterable 字段(含 object/tab 嵌套叶子)，生成 key=点路径的"合成字段"。
+// 这样筛选抽屉/buildFilter/URL 同步全按 field.key 走即可——key 就是 condition.level 这种路径。
+function collectFilterablePaths(list: IFieldConfig[], base: string[], out: any[]) {
+    for (const f of list) {
+        const path = [...base, f.key]
+        if (f.filterable) out.push({ ...f, key: path.join('.') })
+        if (f.type === 'tab' && Array.isArray((f as any).tabs)) {
+            for (const t of (f as any).tabs) collectFilterablePaths(t.fields, path, out)
+        } else if (f.type === 'object' && Array.isArray((f as any).fields)) {
+            collectFilterablePaths((f as any).fields, path, out)
+        }
+    }
+}
 const filterableFields = computed(() => {
     const lockedKeys = new Set(Object.keys(props.baseFilter || {}))
-    return fields.value.filter(f => f.filterable && !lockedKeys.has(f.key))
+    const out: any[] = []
+    collectFilterablePaths(fields.value, [], out)
+    return out.filter(f => !lockedKeys.has(f.key))
 })
 
 const formSlotNames = computed(() => Object.keys(slots).filter(name => name.startsWith('form-')))
@@ -214,6 +242,9 @@ const filterSlotNames = computed(() => Object.keys(slots).filter(name => name.st
 const data = ref<any[]>([])
 const loading = ref(false)
 const total = ref(0)
+// relation 显示名字典 { moduleKey: { id: 名 } }，由 list 响应带回，provide 给表格里的字段组件查名
+const refs = ref<Record<string, Record<string, any>>>({})
+provide('shrimpRefs', refs)
 
 // ---- 对话框状态 ----
 
@@ -258,7 +289,8 @@ function handleSubJump(sub: IModuleInfo, row: any) {
 
 const hasRowActions = computed(() => can('edit') || can('delete') || hasActiveField.value || subModules.value.length > 0 || !!slots['row-actions'])
 
-const rowActionsWidth = computed(() => {
+const resolvedRowActionsWidth = computed(() => {
+    if (props.rowActionsWidth != null && props.rowActionsWidth !== '') return props.rowActionsWidth
     let n = 0
     if (hasActiveField.value && can('edit')) n++
     if (can('edit')) n++
@@ -293,8 +325,10 @@ async function handleAdd() {
             formData.value[field.key] = false
         } else if (field.type === 'number') {
             formData.value[field.key] = 0
-        } else if (field.multiple) {
+        } else if (field.type === 'array' || field.multiple) {
             formData.value[field.key] = []
+        } else if (field.type === 'object') {
+            formData.value[field.key] = {}
         } else {
             formData.value[field.key] = ''
         }
@@ -320,8 +354,10 @@ async function handleSave() {
             formFields.value.forEach(field => {
                 if (field.editable === 'readonly') return
                 if (field.editable === 'addOnly') return
-                const newValue = formData.value[field.key]
-                const oldValue = originalData.value[field.key]
+                // 清空字段值为 undefined 时，JSON.stringify 会丢键 → 后端收不到、看似"提交无效"。
+                // 归一成 null：既保证清空能提交(后端置空)，又让"两边都空"不误判为有改动。
+                const newValue = formData.value[field.key] ?? null
+                const oldValue = originalData.value[field.key] ?? null
                 if (newValue === oldValue) return
                 submitData[field.key] = newValue
             })
@@ -426,7 +462,16 @@ async function handleExport() {
         }
         if (ownerId.value) query.ownerId = ownerId.value
         const list = await api.export(query)
-        const ws = XLSX.utils.json_to_sheet(list)
+        // 后端只发原始对象；xlsx 单元格放不下对象/数组(会变 [object Object])，这里通用地 JSON 序列化
+        // (覆盖 tab 等结构化字段)。import 时这些字符串由后端各类型 reqFilter 还原。
+        const rows = list.map((row: Record<string, any>) => {
+            const out: Record<string, any> = {}
+            for (const [k, v] of Object.entries(row)) {
+                out[k] = (v !== null && typeof v === 'object') ? JSON.stringify(v) : v
+            }
+            return out
+        })
+        const ws = XLSX.utils.json_to_sheet(rows)
         const wb = XLSX.utils.book_new()
         XLSX.utils.book_append_sheet(wb, ws, props.moduleKey)
         XLSX.writeFile(wb, `${props.moduleKey}_export_${Date.now()}.xlsx`)
@@ -501,6 +546,7 @@ async function refresh(query?: Record<string, any>) {
         Object.assign(pageQuery, query)
         const res = await api.list(pageQuery)
         data.value = res.list || []
+        refs.value = res.refs || {}
         total.value = res.total
         currentPage.value = res.page
         currentPageSize.value = res.pageSize

src/components/fields/FieldArray.vue

@@ -0,0 +1,107 @@
+<template>
+    <!-- 显示：逐元素递归渲染 item 的 display 组件 -->
+    <template v-if="mode === 'display'">
+        <span v-if="!items.length">-</span>
+        <span v-else class="arr-display">
+            <span v-for="(el, i) in items" :key="i" class="arr-chip">
+                <component :is="vueAdmin.getFieldComponent(moduleKey, field.item.type, '')"
+                    :field="field.item" :model-value="el" mode="display" />
+            </span>
+        </span>
+    </template>
+    <!-- 编辑：每项一行(标题 + item 编辑组件 + 删除),底部添加。第一版从简:无排序拖拽 -->
+    <div v-else class="field-array">
+        <div v-for="(el, i) in items" :key="i" class="arr-row">
+            <div class="arr-head">
+                <span class="arr-idx">{{ itemTitle }} #{{ i + 1 }}</span>
+                <el-button type="danger" text size="small" @click="removeAt(i)">删除</el-button>
+            </div>
+            <component :is="vueAdmin.getFieldComponent(moduleKey, field.item.type, '')"
+                :field="field.item" :model-value="el"
+                @update:model-value="setAt(i, $event)" mode="edit" :disabled="disabled" />
+        </div>
+        <el-button type="primary" text @click="addOne" :disabled="disabled">+ 添加{{ itemTitle }}</el-button>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { computed, inject } from 'vue'
+import { vueAdmin } from '../../VueAdmin'
+
+const props = defineProps<{
+    field: any
+    modelValue: any
+    mode: 'display' | 'edit' | 'filter'
+    disabled?: boolean
+}>()
+
+const emit = defineEmits<{ 'update:modelValue': [value: any] }>()
+
+const moduleKey = inject('shrimpModuleKey', '')
+
+const items = computed<any[]>(() => Array.isArray(props.modelValue) ? props.modelValue : [])
+const itemTitle = computed(() => vueAdmin.t(props.field.item?.label) || '项')
+
+function setAt(i: number, value: any) {
+    const arr = items.value.slice()
+    arr[i] = value
+    emit('update:modelValue', arr)
+}
+function removeAt(i: number) {
+    const arr = items.value.slice()
+    arr.splice(i, 1)
+    emit('update:modelValue', arr)
+}
+function addOne() {
+    emit('update:modelValue', [...items.value, defaultOf(props.field.item)])
+}
+
+/** 按 item schema 递归生成一个默认元素 */
+function defaultOf(schema: any): any {
+    if (!schema) return null
+    if (schema.defaultValue !== undefined) return schema.defaultValue
+    if (schema.type === 'object') {
+        const obj: any = {}
+        for (const f of schema.fields || []) obj[f.key] = defaultOf(f)
+        return obj
+    }
+    if (schema.type === 'array') return []
+    if (schema.type === 'number') return 0
+    if (schema.type === 'boolean') return false
+    return null
+}
+</script>
+
+<style scoped>
+.arr-display {
+    display: inline-flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4px 12px;
+}
+
+.field-array {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.arr-row {
+    padding: 8px 10px;
+    border: 1px solid var(--el-border-color-lighter);
+    border-radius: 6px;
+}
+
+.arr-head {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 6px;
+}
+
+.arr-idx {
+    color: var(--el-text-color-secondary);
+    font-size: 12px;
+    font-weight: 600;
+}
+</style>

src/components/fields/FieldDate.vue

@@ -42,7 +42,7 @@
         style="width: 100%"
     />
     <el-date-picker v-else :model-value="modelValue" @update:model-value="$emit('update:modelValue', $event)" :disabled="disabled"
-        type="datetime" style="width: 100%" />
+        type="datetime" :clearable="!field.required" style="width: 100%" />
 </template>
 
 <script lang="ts" setup>

src/components/fields/FieldJson.vue

@@ -1,48 +0,0 @@
-<template>
-    <template v-if="mode === 'display'">
-        <el-tooltip v-if="modelValue != null" :content="displayValue" placement="top">
-            <span class="json-display">{{ displayValue }}</span>
-        </el-tooltip>
-        <span v-else>-</span>
-    </template>
-    <el-input
-        v-else
-        :model-value="modelValue"
-        @update:model-value="$emit('update:modelValue', $event)"
-        type="textarea"
-        :rows="4"
-        :disabled="disabled"
-        placeholder="请输入 JSON"
-    />
-</template>
-
-<script lang="ts" setup>
-import { computed } from 'vue'
-
-const props = defineProps<{
-    field: any
-    modelValue: any
-    mode: 'display' | 'edit' | 'filter'
-    disabled?: boolean
-}>()
-
-defineEmits<{
-    'update:modelValue': [value: any]
-}>()
-
-const displayValue = computed(() => {
-    if (props.modelValue == null) return ''
-    if (typeof props.modelValue === 'string') return props.modelValue
-    return JSON.stringify(props.modelValue, null, 2)
-})
-</script>
-
-<style scoped>
-.json-display {
-    display: inline-block;
-    max-width: 200px;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-}
-</style>

src/components/fields/FieldObject.vue

@@ -0,0 +1,69 @@
+<template>
+    <!-- 显示：递归渲染各子字段的 display 组件(relation 子查 refs) -->
+    <template v-if="mode === 'display'">
+        <span v-if="!modelValue || typeof modelValue !== 'object'">-</span>
+        <span v-else class="obj-display">
+            <span v-for="f in field.fields || []" :key="f.key" class="obj-child">
+                <span class="obj-label">{{ vueAdmin.t(f.label) }}:</span>
+                <component :is="vueAdmin.getFieldComponent(moduleKey, f.type, f.key)"
+                    :field="f" :model-value="(modelValue || {})[f.key]" mode="display" />
+            </span>
+        </span>
+    </template>
+    <!-- 编辑：每个子字段一行,递归渲染 edit 组件 -->
+    <div v-else class="field-object">
+        <el-form-item v-for="f in field.fields || []" :key="f.key" :label="vueAdmin.t(f.label)" :required="f.required">
+            <component :is="vueAdmin.getFieldComponent(moduleKey, f.type, f.key)"
+                :field="f" :model-value="(modelValue || {})[f.key]"
+                @update:model-value="onChild(f.key, $event)" mode="edit" :disabled="disabled" />
+        </el-form-item>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { inject } from 'vue'
+import { vueAdmin } from '../../VueAdmin'
+
+const props = defineProps<{
+    field: any
+    modelValue: any
+    mode: 'display' | 'edit' | 'filter'
+    disabled?: boolean
+}>()
+
+const emit = defineEmits<{ 'update:modelValue': [value: any] }>()
+
+const moduleKey = inject('shrimpModuleKey', '')
+
+function onChild(key: string, value: any) {
+    emit('update:modelValue', { ...(props.modelValue || {}), [key]: value })
+}
+</script>
+
+<style scoped>
+.obj-display {
+    display: inline-flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4px 10px;
+}
+
+.obj-child {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+}
+
+.obj-label {
+    color: var(--el-text-color-secondary);
+    font-size: 12px;
+}
+
+.field-object {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    padding-left: 12px;
+    border-left: 2px solid var(--el-border-color-lighter);
+}
+</style>

src/components/fields/FieldRelation.vue

@@ -1,7 +1,13 @@
 <template>
     <template v-if="mode === 'display'">
-        <template v-if="field.multiple && Array.isArray(displayLabel)">{{ displayLabel.filter(Boolean).join(', ') || '-' }}</template>
-        <template v-else>{{ displayLabel || modelValue || '-' }}</template>
+        <template v-if="field.multiple">
+            <span v-if="!displayItems.length">-</span>
+            <template v-for="(it, i) in displayItems" :key="i"><a v-if="jumpable" class="rel-link" @click.stop="goto(it.id)">{{ it.name }}</a><span v-else>{{ it.name }}</span><span v-if="i < displayItems.length - 1">、</span></template>
+        </template>
+        <template v-else>
+            <a v-if="jumpable && modelValue != null" class="rel-link" @click.stop="goto(modelValue)">{{ displayName }}</a>
+            <span v-else>{{ displayName || '-' }}</span>
+        </template>
     </template>
     <el-select
         v-else-if="mode === 'filter'"
@@ -12,31 +18,60 @@
     >
         <el-option v-for="opt in options" :key="opt.value" :label="opt.label" :value="opt.value" />
     </el-select>
-    <el-select v-else :model-value="stringValue" @update:model-value="$emit('update:modelValue', $event)" :disabled="disabled" :multiple="field.multiple" filterable remote :remote-method="onSearch" :loading="loading" style="width: 100%">
+    <el-select v-else :model-value="stringValue" @update:model-value="onEdit" :disabled="disabled" :multiple="field.multiple" :clearable="!field.required" filterable remote :remote-method="onSearch" :loading="loading" style="width: 100%">
         <el-option v-for="opt in options" :key="opt.value" :label="opt.label" :value="opt.value" />
     </el-select>
 </template>
 
 <script lang="ts" setup>
-import { ref, onMounted, computed } from 'vue'
+import { ref, inject, onMounted, computed, type Ref } from 'vue'
 import { vueAdmin } from '../../VueAdmin'
-import { ITableCrudProto } from 'shrimp-server/types'
+import { ITableCrudProto } from '../../IShrimpType'
 
 const props = defineProps<{
     field: any
     modelValue: any
     mode: 'display' | 'edit' | 'filter'
     disabled?: boolean
-    displayLabel?: string | string[]
 }>()
 
-defineEmits<{
+const emit = defineEmits<{
     'update:modelValue': [value: any]
 }>()
 
+// 编辑态清空：el-select 单选清空发 '' 或 undefined，relation 是 ObjectId、且 undefined 会被
+// JSON.stringify 丢键 → 都归一成 null(取消关联)。多选清空是 []，原样。
+function onEdit(v: any) {
+    emit('update:modelValue', v === '' || v == null ? (props.field.multiple ? [] : null) : v)
+}
+
 const options = ref<{ label: string; value: string }[]>([])
 const loading = ref(false)
 
+// 显示用：从 ShrimpTable provide 的 refs 字典按 id 查名（替代旧的 _label）
+const refs = inject<Ref<Record<string, Record<string, any>>>>('shrimpRefs', ref<Record<string, Record<string, any>>>({}))
+const dict = computed(() => refs.value?.[props.field.relation?.moduleKey] ?? {})
+const displayName = computed(() => {
+    const id = props.modelValue
+    if (id == null) return ''
+    return dict.value[String(id)] ?? String(id)
+})
+const displayItems = computed(() =>
+    (Array.isArray(props.modelValue) ? props.modelValue : [])
+        .filter((id: any) => id != null)
+        .map((id: any) => ({ id, name: dict.value[String(id)] ?? String(id) }))
+)
+
+// 单项查看跳转：目标模块可达(已注册路由)且非子模块时，名字可点 → 跳目标模块并过滤到该 _id(单行)
+const jumpable = computed(() =>
+    props.mode === 'display' && !!props.field.relation && !!vueAdmin.routeForModule(props.field.relation.moduleKey)
+)
+function goto(id: any) {
+    const r = props.field.relation && vueAdmin.routeForModule(props.field.relation.moduleKey)
+    if (!r || id == null) return
+    vueAdmin.router.push({ name: r.name, query: { filter: JSON.stringify({ _id: String(id) }) } })
+}
+
 /** 统一转为字符串值，解决 ObjectId 与 el-select 的匹配问题 */
 const stringValue = computed(() => {
     // filter 模式强制 multiple，始终返回数组
@@ -92,3 +127,13 @@ onMounted(async () => {
     }
 })
 </script>
+
+<style scoped>
+.rel-link {
+    color: var(--el-color-primary);
+    cursor: pointer;
+}
+.rel-link:hover {
+    text-decoration: underline;
+}
+</style>

src/components/fields/FieldRelativeTime.vue

@@ -10,7 +10,7 @@
 <script lang="ts" setup>
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
-import { vueAdmin } from '../VueAdmin'
+import { vueAdmin } from '../../VueAdmin'
 
 const { t } = useI18n()
 

src/components/fields/FieldSelect.vue

@@ -21,6 +21,7 @@
         @update:model-value="$emit('update:modelValue', $event)"
         :disabled="disabled"
         :multiple="field.multiple"
+        :clearable="!field.required"
         style="width: 100%"
     >
         <el-option v-for="opt in resolvedOptions" :key="opt.value" :label="vueAdmin.t(opt.label)" :value="opt.value" />

src/components/fields/FieldString.vue

@@ -9,7 +9,7 @@
         </el-tag>
         <el-input v-model="inputValue" @keyup.enter="addTag" @blur="addTag" :placeholder="$t('base.pressEnter')" />
     </div>
-    <el-input v-else :model-value="modelValue" @update:model-value="$emit('update:modelValue', $event)" :disabled="disabled" clearable />
+    <el-input v-else :model-value="modelValue" @update:model-value="$emit('update:modelValue', $event)" :disabled="disabled" :clearable="!field.required" />
 </template>
 
 <script lang="ts" setup>

src/components/fields/FieldTab.vue

@@ -1,13 +1,21 @@
 <template>
     <template v-if="mode === 'display'">
-        <span v-if="!modelValue || typeof modelValue !== 'object'">-</span>
-        <el-tooltip v-else :content="JSON.stringify(modelValue, null, 2)" placement="top">
-            <span class="tab-display">{{ displayText }}</span>
-        </el-tooltip>
+        <!-- 显示=前端递归渲染:分支标签 + 选中分支子字段。没选 type(清空) → 显示 - -->
+        <span v-if="!modelValue || typeof modelValue !== 'object' || modelValue.type == null">-</span>
+        <span v-else class="tab-display">
+            <span class="tab-branch">{{ branchLabel }}</span>
+            <span v-for="childField in selectedTab?.fields || []" :key="childField.key" class="tab-child">
+                <span class="tab-child-label">{{ vueAdmin.t(childField.label) }}:</span>
+                <component :is="vueAdmin.getFieldComponent(moduleKey, childField.type, childField.key)"
+                    :field="childField" :model-value="(modelValue || {})[childField.key]" mode="display" />
+            </span>
+        </span>
     </template>
     <div v-else class="field-tab">
         <el-form-item :label="vueAdmin.t(field.label) + ' - 类型'" :required="field.required">
-            <el-select :model-value="innerValue.type" @update:model-value="onTypeChange" :disabled="disabled">
+            <!-- 非必填可清空 → 清空后 type=null、整个 tab 置空、下面分支消失 -->
+            <el-select :model-value="modelValue?.type ?? undefined" @update:model-value="onTypeChange"
+                :clearable="!field.required" :disabled="disabled">
                 <el-option v-for="tab in field.tabs" :key="tab.key" :label="vueAdmin.t(tab.label)" :value="tab.key" />
             </el-select>
         </el-form-item>
@@ -16,7 +24,7 @@
                 <el-form-item :label="vueAdmin.t(childField.label)" :required="childField.required">
                     <component :is="vueAdmin.getFieldComponent(moduleKey, childField.type, childField.key)"
                         :field="childField"
-                        :model-value="innerValue[childField.key]"
+                        :model-value="(modelValue || {})[childField.key]"
                         @update:model-value="onChildChange(childField.key, $event)"
                         mode="edit"
                         :disabled="disabled" />
@@ -27,7 +35,7 @@
 </template>
 
 <script lang="ts" setup>
-import { computed, inject, onMounted } from 'vue'
+import { computed, inject } from 'vue'
 import { vueAdmin } from '../../VueAdmin'
 
 const props = defineProps<{
@@ -43,39 +51,18 @@ const emit = defineEmits<{
 
 const moduleKey = inject('shrimpModuleKey', '')
 
-const displayText = computed(() => {
-    if (!props.modelValue || typeof props.modelValue !== 'object') return '-'
-    const type = props.modelValue.type
-    const tab = props.field.tabs?.find((t: any) => t.key === type)
-    return tab ? vueAdmin.t(tab.label) : String(type)
-})
+const selectedTab = computed(() =>
+    props.field.tabs?.find((t: any) => t.key === props.modelValue?.type)
+)
 
-const selectedTab = computed(() => {
-    const type = props.modelValue?.type
-    return props.field.tabs?.find((t: any) => t.key === type)
-})
-
-const innerValue = computed(() => {
-    const val = props.modelValue
-    if (val != null && typeof val === 'object' && Object.keys(val).length > 0) {
-        return val
-    }
-    return initValue()
-})
-
-function initValue() {
-    const firstTab = props.field.tabs?.[0]
-    if (!firstTab) return {}
-    const obj: any = { type: firstTab.key }
-    firstTab.fields?.forEach((f: any) => {
-        if (f.defaultValue !== undefined) {
-            obj[f.key] = typeof f.defaultValue === 'function' ? f.defaultValue() : f.defaultValue
-        }
-    })
-    return obj
-}
+const branchLabel = computed(() => selectedTab.value ? vueAdmin.t(selectedTab.value.label) : '')
 
 function onTypeChange(type: any) {
+    // 清空(非必填) → 整个 tab 置空：type=null、空状态、分支消失
+    if (type == null || type === '') {
+        emit('update:modelValue', null)
+        return
+    }
     const tab = props.field.tabs?.find((t: any) => t.key === type)
     const obj: any = { type }
     tab?.fields?.forEach((f: any) => {
@@ -87,24 +74,32 @@ function onTypeChange(type: any) {
 }
 
 function onChildChange(key: string, value: any) {
-    emit('update:modelValue', { ...innerValue.value, [key]: value })
+    emit('update:modelValue', { ...(props.modelValue || {}), [key]: value })
 }
-
-onMounted(() => {
-    const val = props.modelValue
-    if (val == null || val === '' || (typeof val === 'object' && Object.keys(val).length === 0)) {
-        emit('update:modelValue', initValue())
-    }
-})
 </script>
 
 <style scoped>
 .tab-display {
-    display: inline-block;
-    max-width: 200px;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+    display: inline-flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4px 10px;
+}
+
+.tab-branch {
+    font-weight: 600;
+    color: var(--el-color-primary);
+}
+
+.tab-child {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+}
+
+.tab-child-label {
+    color: var(--el-text-color-secondary);
+    font-size: 12px;
 }
 
 .field-tab {

src/components/fields/FieldTextarea.vue

@@ -19,7 +19,7 @@
         :model-value="modelValue"
         @update:model-value="$emit('update:modelValue', $event)"
         :disabled="disabled"
-        clearable
+        :clearable="!field.required"
     />
 </template>
 

src/components/layout.vue

@@ -24,7 +24,7 @@
 		<div v-if="!vueAdmin.state.isMobile && nextMenu.length > 0" class="aminui-side">
 			<div class="adminui-side-scroll">
 				<el-scrollbar>
-					<el-menu :default-active="$route.fullPath" router>
+					<el-menu :default-active="$route.path" router>
 						<navMenu :navMenus="nextMenu"></navMenu>
 					</el-menu>
 				</el-scrollbar>
@@ -43,15 +43,18 @@
 </template>
 
 <script lang="ts" setup>
+import { ref, watch, defineAsyncComponent } from "vue";
+import { vueAdmin, resolveVue } from "../VueAdmin";
+import { type IMenuItem } from "../IShrimpType";
 import SideM from "./sideM.vue";
-import { ref, watch } from "vue";
 import navMenu from "./navMenu.vue";
 import Topbar from "./topbar.vue";
-import Userbar from "./userbar.vue";
-import { vueAdmin } from "../VueAdmin";
-import { type IMenuItem } from "shrimp-server/types";
 import Logo from "./logo.vue";
 
+// 顶栏走 resolveVue,消费侧放 shrimp/components/userbar.vue 即可整体替换。
+// 其余内置组件仍是静态 import——等真有人要覆盖再逐个放开,不预先把整棵树异步化。
+const Userbar = defineAsyncComponent(resolveVue("components/userbar.vue"));
+
 // 初始化选中菜单
 let currentPath = vueAdmin.router.currentRoute.value.path;
 let pick = vueAdmin.getMenuIndex(currentPath);

src/components/login.vue

@@ -33,7 +33,7 @@
 import { vueAdmin } from "../VueAdmin";
 import { reactive, computed, onMounted } from "vue";
 import { useI18n } from "vue-i18n";
-import LangSwitch from "../components/LangSwitch.vue";
+import LangSwitch from "./ShrimpLangSwitch.vue";
 
 vueAdmin.token = null;
 

src/components/sideM.vue

@@ -17,7 +17,7 @@
 			<el-main>
 				<el-scrollbar>
 					<el-menu
-						:default-active="$route.fullPath"
+						:default-active="$route.path"
 						@select="select"
 						router
 						background-color="#212d3d"
@@ -33,10 +33,10 @@
 </template>
 
 <script lang="ts" setup>
-import navMenu from "./navMenu.vue";
-import Logo from "./logo.vue";
 import { ref } from "vue";
 import { vueAdmin } from '../VueAdmin';
+import navMenu from "./navMenu.vue";
+import Logo from "./logo.vue";
 
 let nav = ref(false);
 function showMobileNav() { nav.value = true; }

src/components/userbar.vue

@@ -21,7 +21,7 @@
 
 <script lang="ts" setup>
 import { vueAdmin } from "../VueAdmin";
-import LangSwitch from "../components/LangSwitch.vue";
+import LangSwitch from "./ShrimpLangSwitch.vue";
 
 function screen() {
 	vueAdmin.fullscreen();

src/index.ts

@@ -2,10 +2,52 @@
 //
 // 消费侧用法见 README.md。本文件只做 re-export。
 
+// ===== 类型契约(IShrimpType 是 shrimp-server 那份的副本,由其 postbuild 自动同步)=====
+export {
+    ShrimpCode,
+    ShrimpError,
+    ShrimpFieldTypes,
+    ShrimpConfig,
+    isShrimpCondition,
+} from './IShrimpType'
+
+export type {
+    ILabel,
+    IShrimpResponse,
+    IModuleInfo,
+    ILoginResult,
+    IMeResult,
+    IMenuItem,
+    ITableProto,
+    ITableCrudProto,
+    IUser,
+    IRole,
+    IOperationLog,
+    WithId,
+    IShrimpOperator,
+    IShrimpPowerData,
+    ShrimpRequestFn,
+    IShrimpClient,
+    ShrimpFieldType,
+    FieldEditable,
+    IFieldTypeHandler,
+    IFieldConfig,
+    IFieldRule,
+    IPageQuery,
+    IPageResult,
+    IShrimpCondition,
+    IShrimpPopulate,
+    IShrimpQuery,
+    IPowerItem,
+    IUserProto,
+    IRoleProto,
+} from './IShrimpType'
+
 export {
     VueAdmin,
     vueAdmin,
     createShrimpAdmin,
+    resolveVue,
     type ShrimpAdminOptions,
     type ShrimpAdminConfig,
 } from './VueAdmin'
@@ -17,14 +59,15 @@ export {
     type IRouteInfo,
 } from './ShrimpClient'
 
-// 框架组件 — 业务页面想直接复用就 import 这些
+// 框架组件 — 业务页面想直接复用就 import 这些。
+// 这些是「静态」导出,拿到的就是框架内置版本,不受消费侧 sources 影响。
 export { default as ShrimpTable } from './components/ShrimpTable.vue'
 export { default as ShrimpEditDrawer } from './components/ShrimpEditDrawer.vue'
 export { default as ShrimpFilterDrawer } from './components/ShrimpFilterDrawer.vue'
 export { default as ShrimpFilterTrigger } from './components/ShrimpFilterTrigger.vue'
 export { default as ShrimpSearchInput } from './components/ShrimpSearchInput.vue'
-export { default as PowerTree } from './components/PowerTree.vue'
-export { default as LangSwitch } from './components/LangSwitch.vue'
+export { default as ShrimpPowerTree } from './components/ShrimpPowerTree.vue'
+export { default as ShrimpLangSwitch } from './components/ShrimpLangSwitch.vue'
 
 // 应用入口视图(消费侧 createApp 用)
-export { default as App } from './views/App.vue'
+export { default as App } from './App.vue'

src/locales/en.json

@@ -25,7 +25,10 @@
     "enabled": "Enabled",
     "pressEnter": "Press Enter to add",
     "expand": "Expand",
-    "collapse": "Collapse"
+    "collapse": "Collapse",
+    "back": "Back",
+    "refresh": "Refresh",
+    "notFound": "Not Found"
   },
   "user": {
     "username": "Username",

src/locales/zh-cn.json

@@ -38,6 +38,7 @@
     "active": "启用状态",
     "createdAt": "创建时间",
     "updatedAt": "更新时间",
+    "menuManage": "用户",
     "operationLog": "操作日志"
   },
   "operationLog": {
@@ -55,6 +56,7 @@
     "powers": "权限",
     "createdAt": "创建时间",
     "updatedAt": "更新时间",
+    "menuManage": "角色",
     "menuList": "角色列表",
     "empty": "暂无角色",
     "addRole": "新增角色",
@@ -91,6 +93,9 @@
     "PWError": "请输入密码"
   },
   "power": {
+    "user": "用户",
+    "role": "角色",
+    "zerobase": "Zero Base",
     "add": "新增",
     "edit": "编辑",
     "delete": "删除",

src/module/role.vue

@@ -28,7 +28,7 @@
                         <el-input v-model="formData.description" type="textarea" :rows="3" />
                     </el-form-item>
                     <el-form-item :label="$t('role.powers')">
-                        <PowerTree :modelValue="formData.powers || []" :allPowers="allPowers" :menuTree="vueAdmin.menuTree"
+                        <ShrimpPowerTree :modelValue="formData.powers || []" :allPowers="allPowers" :menuTree="vueAdmin.menuTree"
                             @update:modelValue="val => formData.powers = val" />
                     </el-form-item>
                 </el-form>
@@ -50,10 +50,11 @@
 <script lang="ts" setup>
 import { ref, onMounted } from 'vue'
 import { useI18n } from 'vue-i18n'
+import { useRoute } from 'vue-router'
 import { vueAdmin } from '../VueAdmin'
-import { IRole, IRoleProto, WithId, ILabel } from 'shrimp-server/types'
+import { IRole, IRoleProto, WithId, ILabel } from '../IShrimpType'
 import { ElMessage } from 'element-plus'
-import PowerTree from '../components/PowerTree.vue'
+import ShrimpPowerTree from '../components/ShrimpPowerTree.vue'
 
 interface IPowerItem {
     key: string
@@ -61,12 +62,24 @@ interface IPowerItem {
 }
 
 const { t } = useI18n()
+const route = useRoute()
 
 const props = defineProps<{
     moduleKey: string
     events?: string[]
 }>()
 
+// relation 跳转落到 role 页时带 ?filter={"_id":...}。role 是自定义 master-detail 页(非 ShrimpTable、
+// 不做服务端过滤)，全量加载后按这个 _id 在列表里选中那条；解析不出就走默认(选第一个)。
+function jumpTargetId(): string {
+    try {
+        const f = route.query.filter ? JSON.parse(String(route.query.filter)) : null
+        return f && typeof f === 'object' ? String(f._id || '') : ''
+    } catch {
+        return ''
+    }
+}
+
 const roleApi = vueAdmin.getModule<IRoleProto>('role')
 
 const roleList = ref<WithId<IRole>[]>([])
@@ -138,7 +151,10 @@ async function handleDelete() {
 onMounted(async () => {
     allPowers.value = await roleApi.allPower()
     await loadRoles()
-    if (roleList.value.length > 0) {
+    const jumpId = jumpTargetId()
+    if (jumpId && roleList.value.some(r => r._id === jumpId)) {
+        onSelect(jumpId)
+    } else if (roleList.value.length > 0) {
         onSelect(roleList.value[0]._id)
     }
 })

src/module/user.vue

@@ -1,13 +1,14 @@
 <template>
-    <ShrimpTable moduleKey="user" />
+    <ShrimpTable moduleKey="user">
+        <template #column-updatedAt="{ row }">
+            <FieldRelativeTime :model-value="row.updatedAt" mode="display" :field="{}" />
+        </template>
+    </ShrimpTable>
 </template>
 
 <script lang="ts" setup>
 import ShrimpTable from '../components/ShrimpTable.vue'
-import { vueAdmin } from '../VueAdmin'
-import FieldRelativeTime from './FieldRelativeTime.vue'
-
-vueAdmin.overrideField('user', 'updatedAt', FieldRelativeTime)
+import FieldRelativeTime from '../components/fields/FieldRelativeTime.vue'
 </script>
 
 <style scoped>

src/module/user/operationLog.vue

@@ -14,8 +14,8 @@
 import { ref, computed, onMounted, watch } from 'vue'
 import { useRoute } from 'vue-router'
 import { useI18n } from 'vue-i18n'
-import ShrimpTable from '../../components/ShrimpTable.vue'
 import { vueAdmin } from '../../VueAdmin'
+import ShrimpTable from '../../components/ShrimpTable.vue'
 
 const route = useRoute()
 const { t } = useI18n()

src/style/app.scss

@@ -55,6 +55,11 @@ textarea {
 	display: flex;
 	flex: 1;
 	overflow: auto;
+	/* 挂载点没加 class="aminui" 时的兜底:#app 已经是 height:100%(本文件开头),
+	   但它是块级容器,上面那行 flex:1 在块级父容器里不生效,布局会塌成内容高度——
+	   侧边栏比页面矮一截、还跟着表格异步加载忽长忽短,且不报错、页面照常打开。
+	   父级确实是 .aminui 时,flex:1 1 0% 接管尺寸,这行等价不冲突。 */
+	height: 100%;
 }
 
 /* 全局滚动条样式 */