v0.3.0: 单 sources 入口 + 路径后缀覆盖约定

破坏性重构。框架对外只暴露一个 `sources` glob 入口,消费侧任何 .vue
都按文件路径后缀匹配同后缀覆盖:

- shrimp/components/<name>.vue 同后缀覆盖框架内置(login/layout/topbar/ShrimpTable/...)
- shrimp/components/fields/Field<X>.vue 注册类型 <x>(首字母小写)
- shrimp/module/<key>.vue 业务模块

变更:
- 删除 customFields / moduleSources / overrideField / registerField 旧入口
- 删除 fieldOverrides Map,字段表纯靠 glob 扫描注册
- 框架内 .vue 对可覆盖 peer 改用 defineAsyncComponent(resolveVue(...))
  (login → ShrimpLangSwitch / layout → sideM/navMenu/topbar/userbar/logo /
   ShrimpTable → ShrimpEditDrawer/ShrimpFilterDrawer/...)
- views/ 全部并入 components/,App.vue 上提到 src/ 根
- LangSwitch → ShrimpLangSwitch,PowerTree → ShrimpPowerTree
- module/FieldRelativeTime.vue → components/fields/FieldRelativeTime.vue
- module/user.vue 改用 #column-updatedAt slot 替代旧的 overrideField

字段类型约定从 'field' + Name 改为 lowercase-first(FieldString → 'string'),
内置和消费侧统一。

README.md

@@ -7,8 +7,7 @@ Shrimp 框架前端 —— 一种**经典解决方案**(不是框架本身),消
 ## 安装
 
 ```bash
-# 推荐 HTTP
+npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.3.0
-npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.1.0
 ```
 
 shrimp-admin 是**源码 ship**(.ts + .vue 直接发),由消费侧 Vite 编译。
@@ -20,6 +19,8 @@ shrimp-admin 是**源码 ship**(.ts + .vue 直接发),由消费侧 Vite 编译
 import { createApp } from 'vue'
 import { createShrimpAdmin, App } from 'shrimp-admin'
 import 'shrimp-admin/style'
+import zhCn from './locales/zh-cn.json'
+import en from './locales/en.json'
 
 const app = createApp(App)
 app.use(createShrimpAdmin({
@@ -27,22 +28,62 @@ app.use(createShrimpAdmin({
         API_URL: '/admin-api',
         TIMEOUT: 10000,
     },
-    moduleSources: import.meta.glob('./module/**/*.vue'),
+    locales: { 'zh-cn': zhCn, en },
-    customFields: import.meta.glob('./module/fields/Field*.vue'),
+    sources: import.meta.glob('./shrimp/**/*.vue'),
 }))
 app.mount('#app')
 ```
 
+## 唯一约定: `sources` 路径后缀覆盖
+
+消费侧把所有要交给框架的 .vue 通过单个 `sources` 入口注入(`import.meta.glob` 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。
+
+```
+项目/
+└── src/shrimp/                       消费侧目录,可任意命名
+    ├── components/
+    │   ├── login.vue                 覆盖框架内置 login 页
+    │   ├── topbar.vue                覆盖顶栏
+    │   └── fields/
+    │       └── FieldRelativeTime.vue 注册字段类型 relativeTime
+    └── module/
+        ├── product.vue               业务模块,routed by moduleKey
+        └── user/
+            └── orders.vue            子模块,parent=user
+```
+
+### 框架内置 slot(可覆盖,suffix 列表)
+
+```
+components/login.vue           components/404.vue            components/layout.vue
+components/logo.vue            components/navMenu.vue        components/sideM.vue
+components/topbar.vue          components/userbar.vue
+components/ShrimpLangSwitch.vue           components/ShrimpPowerTree.vue
+components/ShrimpTable.vue                components/ShrimpEditDrawer.vue
+components/ShrimpFilterDrawer.vue         components/ShrimpFilterTrigger.vue
+components/ShrimpSearchInput.vue
+components/fields/Field{String,Boolean,Date,Json,Number,Password,Relation,Select,Tab,Textarea,RelativeTime}.vue
+```
+
+### 字段类型注册
+
+`components/fields/Field<X>.vue` 自动注册类型 `<x>`(首字母小写):
+
+| 文件                     | type 注册键        |
+| ------------------------ | ------------------ |
+| `FieldString.vue`        | `string`           |
+| `FieldRelativeTime.vue`  | `relativeTime`     |
+| 你自己的 `FieldMyType.vue` | `myType`         |
+
+后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。
+
+### 业务模块
+
+`components/X.vue` 命中 `moduleKey === 'X'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。
+
 ## 消费的契约
 
 参见 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.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-admin",
-    "version": "0.2.4",
+    "version": "0.3.0",
     "private": true,
     "description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现",
     "main": "src/index.ts",

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/VueAdmin.ts

@@ -10,7 +10,6 @@ import { createI18n, I18n } from 'vue-i18n'
 import { IShrimpResponse, ILabel } from './IShrimpType'
 
 import { ShrimpClient, handleShrimpResponse, type IShrimpTipper, type IRouteInfo } from './ShrimpClient'
-import FieldString from './components/fields/FieldString.vue'
 
 // ============== 工具 ==============
 
@@ -39,50 +38,62 @@ 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>>
+     * 消费侧 .vue 源,推荐 `import.meta.glob('./shrimp/**\/*.vue')`。
-    /** 业务字段组件:`import.meta.glob('./module/fields/Field*.vue')`,文件名 FieldXxx → type='fieldXxx' */
+     * - `shrimp/components/<name>.vue` 同后缀覆盖框架内置(login/layout/topbar/ShrimpTable/...)
-    customFields?: Record<string, () => Promise<{ default: Component } | Component>>
+     * - `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 }[]
 }
 
+// ============== 源注册表 ==============
+//
+// 唯一约定:消费侧把 .vue 源放进 `sources`,框架按文件路径后缀解析。
+// 框架内部对可覆盖的 .vue 也用 resolveVue 解析(而不是静态 import),保证 consumer 覆盖在框架内部使用点也生效。
+
+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
+    }
+    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)
+function deriveFieldType(path: string): string | null {
-fieldRegistry.set('boolean', defineAsyncComponent(() => import('./components/fields/FieldBoolean.vue')))
+    const m = path.match(/\/components\/fields\/Field([A-Z][A-Za-z0-9]*)\.vue$/)
-fieldRegistry.set('date', defineAsyncComponent(() => import('./components/fields/FieldDate.vue')))
+    if (!m) return null
-fieldRegistry.set('number', defineAsyncComponent(() => import('./components/fields/FieldNumber.vue')))
+    return m[1][0].toLowerCase() + m[1].slice(1)
-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')))
 
-// 框架自带模块组件 — vite glob 相对本文件解析,扫到的是 shrimp-admin 内部的 module/
+for (const path in internalSources) {
-const internalModules = import.meta.glob<Component>('./module/**/*.vue')
+    const type = deriveFieldType(path)
-
+    if (type) fieldRegistry.set(type, defineAsyncComponent(internalSources[path] as any))
-// 业务模块由消费侧通过 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
 }
 
 // ============== LocalData ==============
@@ -110,20 +121,8 @@ export class VueAdmin extends ShrimpClient {
     config: ShrimpAdminConfig
     langList: { lang: string; name: string }[]
 
-    registerField(type: string, comp: Component) { fieldRegistry.set(type, comp) }
+    getFieldComponent(_moduleKey: string, type: string, _fieldKey?: string): Component {
-
+        return fieldRegistry.get(type) || fieldRegistry.get('string')!
-    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 {
-        if (fieldKey) {
-            const override = fieldOverrides.get(`${moduleKey}.${fieldKey}`)
-            if (override && fieldRegistry.has(override)) return fieldRegistry.get(override)!
-        }
-        return fieldRegistry.get(type) || FieldString
     }
 
     state = reactive({ isMobile: false })
@@ -161,15 +160,11 @@ export class VueAdmin extends ShrimpClient {
         this.config = opts.config
         this.langList = opts.langList || [{ lang: 'zh-cn', name: '简体中文' }]
 
-        // 业务模块/字段注册
+        if (opts.sources) {
-        if (opts.moduleSources) Object.assign(externalModules, opts.moduleSources)
+            Object.assign(externalSources, opts.sources)
-        if (opts.customFields) {
+            for (const path in opts.sources) {
-            for (const path in opts.customFields) {
+                const type = deriveFieldType(path)
-                const match = path.match(/\/Field(.+)\.vue$/)
+                if (type) fieldRegistry.set(type, defineAsyncComponent(opts.sources[path] as any))
-                if (match) {
-                    const name = 'field' + match[1]
-                    fieldRegistry.set(name, defineAsyncComponent(opts.customFields[path] as any))
-                }
             }
         }
 
@@ -244,8 +239,10 @@ export class VueAdmin extends ShrimpClient {
 
     registerRoute(info: IRouteInfo) {
         const componentPath = info.componentPath || info.moduleKey
-        const importer = resolveModuleComponent(componentPath)
+        let importer: VueLoader
-        if (!importer) {
+        try {
+            importer = resolveVue(`module/${componentPath}.vue`)
+        } catch {
             console.warn(`[shrimp-admin] module component not found: module/${componentPath}.vue`)
             return
         }
@@ -265,17 +262,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'),
+                    component: resolveVue('components/login.vue'),
                     meta: { title: { t: 'login.signIn' } }
                 },
                 {
                     path: "/:pathMatch(.*)",
-                    component: () => import('./views/404.vue'),
+                    component: resolveVue('components/404.vue'),
                 },
             ],
         })

src/components/ShrimpTable.vue

@@ -78,21 +78,22 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, computed, useSlots, onMounted, type Component } from 'vue'
+import { defineAsyncComponent, ref, computed, useSlots, onMounted, type Component } from 'vue'
 import { ITableCrudProto, IFieldConfig, IModuleInfo, IPageQuery } from '../IShrimpType'
-import { vueAdmin } from '../VueAdmin'
+import { vueAdmin, resolveVue } 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'
 import { ElMessageBox, ElMessage } from 'element-plus'
 import { useI18n } from 'vue-i18n'
 import { useRoute, useRouter } from 'vue-router'
 import { useTableUrlSync } from '../composables/useTableUrlSync'
-import ShrimpEditDrawer from './ShrimpEditDrawer.vue'
-import ShrimpFilterDrawer from './ShrimpFilterDrawer.vue'
-import ShrimpSearchInput from './ShrimpSearchInput.vue'
-import ShrimpFilterTrigger from './ShrimpFilterTrigger.vue'
 import * as XLSX from 'xlsx'
 
+const ShrimpEditDrawer = defineAsyncComponent(resolveVue('components/ShrimpEditDrawer.vue'))
+const ShrimpFilterDrawer = defineAsyncComponent(resolveVue('components/ShrimpFilterDrawer.vue'))
+const ShrimpSearchInput = defineAsyncComponent(resolveVue('components/ShrimpSearchInput.vue'))
+const ShrimpFilterTrigger = defineAsyncComponent(resolveVue('components/ShrimpFilterTrigger.vue'))
+
 const { t } = useI18n()
 
 interface Props {

src/components/layout.vue

@@ -43,14 +43,15 @@
 </template>
 
 <script lang="ts" setup>
-import SideM from "./sideM.vue";
+import { defineAsyncComponent, ref, watch } from "vue";
-import { ref, watch } from "vue";
+import { vueAdmin, resolveVue } from "../VueAdmin";
-import navMenu from "./navMenu.vue";
-import Topbar from "./topbar.vue";
-import Userbar from "./userbar.vue";
-import { vueAdmin } from "../VueAdmin";
 import { type IMenuItem } from "../IShrimpType";
-import Logo from "./logo.vue";
+
+const SideM = defineAsyncComponent(resolveVue('components/sideM.vue'));
+const navMenu = defineAsyncComponent(resolveVue('components/navMenu.vue'));
+const Topbar = defineAsyncComponent(resolveVue('components/topbar.vue'));
+const Userbar = defineAsyncComponent(resolveVue('components/userbar.vue'));
+const Logo = defineAsyncComponent(resolveVue('components/logo.vue'));
 
 // 初始化选中菜单
 let currentPath = vueAdmin.router.currentRoute.value.path;

src/components/login.vue

@@ -30,10 +30,11 @@
 </template>
 
 <script lang="ts" setup>
-import { vueAdmin } from "../VueAdmin";
+import { vueAdmin, resolveVue } from "../VueAdmin";
-import { reactive, computed, onMounted } from "vue";
+import { defineAsyncComponent, reactive, computed, onMounted } from "vue";
 import { useI18n } from "vue-i18n";
-import LangSwitch from "../components/LangSwitch.vue";
+
+const LangSwitch = defineAsyncComponent(resolveVue('components/ShrimpLangSwitch.vue'));
 
 vueAdmin.token = null;
 

src/components/sideM.vue

@@ -33,10 +33,11 @@
 </template>
 
 <script lang="ts" setup>
-import navMenu from "./navMenu.vue";
+import { defineAsyncComponent, ref } from "vue";
-import Logo from "./logo.vue";
+import { vueAdmin, resolveVue } from '../VueAdmin';
-import { ref } from "vue";
+
-import { vueAdmin } from '../VueAdmin';
+const navMenu = defineAsyncComponent(resolveVue('components/navMenu.vue'));
+const Logo = defineAsyncComponent(resolveVue('components/logo.vue'));
 
 let nav = ref(false);
 function showMobileNav() { nav.value = true; }

src/components/userbar.vue

@@ -20,8 +20,10 @@
 </template>
 
 <script lang="ts" setup>
-import { vueAdmin } from "../VueAdmin";
+import { vueAdmin, resolveVue } from "../VueAdmin";
-import LangSwitch from "../components/LangSwitch.vue";
+import { defineAsyncComponent } from "vue";
+
+const LangSwitch = defineAsyncComponent(resolveVue('components/ShrimpLangSwitch.vue'));
 
 function screen() {
 	vueAdmin.fullscreen();

src/index.ts

@@ -47,6 +47,7 @@ export {
     VueAdmin,
     vueAdmin,
     createShrimpAdmin,
+    resolveVue,
     type ShrimpAdminOptions,
     type ShrimpAdminConfig,
 } from './VueAdmin'
@@ -58,14 +59,16 @@ export {
     type IRouteInfo,
 } from './ShrimpClient'
 
-// 框架组件 — 业务页面想直接复用就 import 这些
+// 框架组件 — 业务页面想直接复用就 import 这些。
+// 注意:这些是「静态」导出,直接 import 拿到的就是框架内置版本,不会被消费侧 sources 覆盖。
+// 要让 consumer 覆盖在所有引用点都生效,框架内部已统一改用 resolveVue 动态解析。
 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 ShrimpPowerTree } from './components/ShrimpPowerTree.vue'
-export { default as LangSwitch } from './components/LangSwitch.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/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>
@@ -48,12 +48,13 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, onMounted } from 'vue'
+import { defineAsyncComponent, ref, onMounted } from 'vue'
 import { useI18n } from 'vue-i18n'
-import { vueAdmin } from '../VueAdmin'
+import { vueAdmin, resolveVue } from '../VueAdmin'
 import { IRole, IRoleProto, WithId, ILabel } from '../IShrimpType'
 import { ElMessage } from 'element-plus'
-import PowerTree from '../components/PowerTree.vue'
+
+const ShrimpPowerTree = defineAsyncComponent(resolveVue('components/ShrimpPowerTree.vue'))
 
 interface IPowerItem {
     key: string

src/module/user.vue

@@ -1,13 +1,17 @@
 <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 { defineAsyncComponent } from 'vue'
-import { vueAdmin } from '../VueAdmin'
+import { resolveVue } from '../VueAdmin'
-import FieldRelativeTime from './FieldRelativeTime.vue'
 
-vueAdmin.overrideField('user', 'updatedAt', FieldRelativeTime)
+const ShrimpTable = defineAsyncComponent(resolveVue('components/ShrimpTable.vue'))
+const FieldRelativeTime = defineAsyncComponent(resolveVue('components/fields/FieldRelativeTime.vue'))
 </script>
 
 <style scoped>

src/module/user/operationLog.vue

@@ -11,11 +11,12 @@
 </template>
 
 <script lang="ts" setup>
-import { ref, computed, onMounted, watch } from 'vue'
+import { defineAsyncComponent, ref, computed, onMounted, watch } from 'vue'
 import { useRoute } from 'vue-router'
 import { useI18n } from 'vue-i18n'
-import ShrimpTable from '../../components/ShrimpTable.vue'
+import { vueAdmin, resolveVue } from '../../VueAdmin'
-import { vueAdmin } from '../../VueAdmin'
+
+const ShrimpTable = defineAsyncComponent(resolveVue('components/ShrimpTable.vue'))
 
 const route = useRoute()
 const { t } = useI18n()