create-lumal-admin 0.0.4-beta → 0.0.5-beta

package/templates/modes/http/tests/http.test.ts.template

@@ -0,0 +1,165 @@
+// @vitest-environment node
+import type { AddressInfo } from 'node:net'
+import { createServer } from 'node:http'
+import { setTimeout as delay } from 'node:timers/promises'
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'
+import { createHttpBackend } from '../src/services/data-source'
+import { createApplicationSession } from '../src/services/session-runtime'
+
+const tokens = new Map<string, string>()
+const refreshTokens = new Map<string, string>()
+const expired = new Set<string>()
+const calls = new Map<string, number>()
+let failRefresh = false
+let failLogout = false
+let baseURL = ''
+const server = createServer(async (request, response) => {
+  const path = new URL(request.url!, 'http://localhost').pathname
+  calls.set(path, (calls.get(path) ?? 0) + 1)
+  let body = ''
+  for await (const part of request)
+    body += String(part)
+  const input = body ? JSON.parse(body) as Record<string, string> : {}
+  const token = request.headers.authorization?.replace('Bearer ', '') ?? ''
+  function send(data: unknown, status = 200) {
+    response.writeHead(status, { 'content-type': 'application/json' })
+    response.end(JSON.stringify(data))
+  }
+  function issue(username: string) {
+    const accessToken = crypto.randomUUID()
+    const refreshToken = crypto.randomUUID()
+    tokens.set(accessToken, username)
+    refreshTokens.set(refreshToken, username)
+    return { accessToken, refreshToken }
+  }
+  if (path === '/auth/login') {
+    if (input.password !== 'valid')
+      return send({ message: '登录失败' }, 401)
+    return send(issue(input.username!))
+  }
+  if (path === '/auth/refresh') {
+    await delay(40)
+    const username = refreshTokens.get(input.refreshToken!)
+    return !failRefresh && username ? send(issue(username)) : send({ message: '刷新失败' }, 401)
+  }
+  const username = tokens.get(token)
+  if (!username || expired.has(token))
+    return send({ message: '已过期' }, 401)
+  if (path === '/session/me')
+    return send({ id: username, name: username, username })
+  if (path === '/session/access')
+    return send({ roles: [username], permissions: [`${username}:read`] })
+  if (path === '/menus')
+    return send([{ path: '/deep', name: 'Deep', component: 'dashboard/index', meta: { title: username } }])
+  if (path === '/auth/logout') {
+    tokens.delete(token)
+    return send({}, failLogout ? 503 : 200)
+  }
+  if (path.startsWith('/system/'))
+    return send({ items: [{ id: '1', owner: username }], total: 1 })
+  send({}, 404)
+})
+beforeAll(async () => {
+  await new Promise<void>(done => server.listen(0, '127.0.0.1', done))
+  baseURL = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+})
+beforeEach(() => {
+  calls.clear()
+  tokens.clear()
+  refreshTokens.clear()
+  expired.clear()
+  failRefresh = false
+  failLogout = false
+})
+afterAll(async () => {
+  server.closeAllConnections()
+  await new Promise<void>((done, reject) => server.close(error => error ? reject(error) : done()))
+})
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    getItem: key => values.get(key) ?? null,
+    setItem: (key, value) => { values.set(key, value) },
+    removeItem: (key) => { values.delete(key) },
+    clear: () => values.clear(),
+    key: index => [...values.keys()][index] ?? null,
+    get length() { return values.size },
+  }
+}
+function application(url = baseURL) {
+  const storage = memoryStorage()
+  return createApplicationSession(context => createHttpBackend(context, url), storage, storage)
+}
+describe('真实 HTTP 应用服务', () => {
+  it('配置缺失明确失败，不产生演示会话', async () => {
+    const app = application('')
+    await expect(app.login({ username: 'alice', password: 'valid' })).rejects.toThrow('VITE_API_BASE_URL')
+    expect(app.isAuthenticated()).toBe(false)
+    expect(calls.size).toBe(0)
+  })
+  it('登录失败、成功、用户权限菜单与真实 CRUD 请求', async () => {
+    const app = application()
+    await expect(app.login({ username: 'alice', password: 'wrong' })).rejects.toThrow()
+    expect(app.currentUser.value).toBeNull()
+    await app.login({ username: 'alice', password: 'valid' })
+    expect(app.ready.value).toBe(true)
+    expect(app.currentUser.value?.username).toBe('alice')
+    expect(app.permissionStore.permissions).toEqual(['alice:read'])
+    expect(app.permissionStore.roles).toEqual(['alice'])
+    expect(app.menus.value[0]?.path).toBe('/deep')
+    expect(await app.service.list('users', { page: 1, pageSize: 10, query: {} })).toEqual({ items: [{ id: '1', owner: 'alice' }], total: 1 })
+    await Promise.all([app.initialize(), app.initialize()])
+    expect(calls.get('/session/me')).toBe(1)
+  })
+  it('401 并发请求只刷新一次，重放使用新凭据', async () => {
+    const app = application()
+    await app.login({ username: 'alice', password: 'valid' })
+    expired.add(app.session.getToken()!)
+    const signal = new AbortController().signal
+    const [user, access, menus] = await Promise.all([app.service.getUser(signal), app.service.getAccess(signal), app.service.getMenus(signal)])
+    expect(user.username).toBe('alice')
+    expect(access.permissions).toEqual(['alice:read'])
+    expect(menus[0]?.path).toBe('/deep')
+    expect(calls.get('/auth/refresh')).toBe(1)
+    expect(calls.get('/session/me')).toBe(3)
+  })
+  it('刷新失败清理凭据、权限、菜单、标签和动态状态回调', async () => {
+    const app = application()
+    await app.login({ username: 'alice', password: 'valid' })
+    let resets = 0
+    app.onReset(() => {
+      resets += 1
+    })
+    expired.add(app.session.getToken()!)
+    failRefresh = true
+    await expect(app.service.getUser(new AbortController().signal)).rejects.toThrow()
+    expect(app.isAuthenticated()).toBe(false)
+    expect(app.currentUser.value).toBeNull()
+    expect(app.menus.value).toEqual([])
+    expect(app.permissionStore.permissions).toEqual([])
+    expect(resets).toBe(1)
+  })
+  it('退出接口失败不保留本地身份', async () => {
+    const app = application()
+    await app.login({ username: 'alice', password: 'valid' })
+    failLogout = true
+    await expect(app.logout()).rejects.toThrow()
+    expect(app.isAuthenticated()).toBe(false)
+    expect(app.permissionStore.roles).toEqual([])
+    expect(calls.get('/auth/logout')).toBe(1)
+  })
+  it('刷新在途时切换账号，旧响应不能污染新用户', async () => {
+    const app = application()
+    await app.login({ username: 'alice', password: 'valid' })
+    expired.add(app.session.getToken()!)
+    const old = app.service.getUser(new AbortController().signal).catch(error => error)
+    while (!calls.get('/auth/refresh'))
+      await delay(1)
+    await app.login({ username: 'bob', password: 'valid' })
+    await old
+    await delay(50)
+    expect(app.currentUser.value?.username).toBe('bob')
+    expect(app.permissionStore.permissions).toEqual(['bob:read'])
+    expect(app.ready.value).toBe(true)
+  })
+})

package/templates/modes/local/src/services/data-source.ts

@@ -0,0 +1,176 @@
+import type { LumalMenuRecord } from '@lumal/core/router'
+import type { AccessSnapshot, ApplicationService, CurrentUser, DataRow, ServiceContext } from './contracts'
+import { localMenus } from '../router/views'
+
+export const demoAccount = import.meta.env.DEV ? { username: 'admin', password: 'lumal123' } : null
+
+// 本地演示数据独立于 HTTP 模板，生产构建默认拒绝演示认证。
+export function createBackend(context: ServiceContext): ApplicationService {
+  const permissions = [...new Set(localMenus.flatMap((menu) => {
+    const prefix = String(menu.meta?.permissionPrefix ?? '')
+    return prefix ? ['list', 'view', 'create', 'update', 'delete', 'authorize'].map(action => `${prefix}:${action}`) : []
+  }))]
+  const initial: Record<string, DataRow[]> = {
+    users: [
+      { id: 'admin', username: 'admin', nickname: '管理员', roles: ['admin'], status: 'enabled' },
+      { id: 'guest', username: 'guest', nickname: '访客', roles: ['guest'], status: 'enabled' },
+    ],
+    roles: [
+      { id: 'admin', code: 'admin', name: '管理员', status: 'enabled', permissions },
+      { id: 'guest', code: 'guest', name: '访客', status: 'enabled', permissions: [] },
+    ],
+    menus: localMenus.map(menu => ({
+      id: menu.name ?? menu.path,
+      title: menu.meta?.title,
+      path: menu.path,
+      name: menu.name,
+      component: menu.component,
+      permission: menu.meta?.authority,
+      type: 'menu',
+      hidden: false,
+    })),
+    config: [{ id: 'appName', key: 'appName', value: 'Lumal Admin' }, { id: 'pageSize', key: 'pageSize', value: '10' }],
+  }
+  function readRows(resource: string): DataRow[] {
+    const value = localStorage.getItem(`demo:system:${resource}`)
+    return value ? JSON.parse(value) as DataRow[] : structuredClone(initial[resource] ?? [])
+  }
+  function assertDemo(): void {
+    if (import.meta.env.PROD && import.meta.env.VITE_ENABLE_LOCAL_DEMO !== 'true')
+      throw new Error('生产环境已禁用本地演示，请使用 HTTP 模式或显式启用演示')
+  }
+  function getUser(): CurrentUser {
+    assertDemo()
+    const raw = sessionStorage.getItem(`demo:${context.getSession()?.accessToken ?? ''}`)
+    if (!raw)
+      throw new Error('本地演示会话已失效')
+    return JSON.parse(raw) as CurrentUser
+  }
+  function getAccess(): AccessSnapshot {
+    const user = getUser()
+    const record = readRows('users').find(row => row.username === user.username)
+    if (!record || record.status === 'disabled')
+      throw new Error('本地账号已停用或删除，请重新登录')
+    const roles = Array.isArray(record.roles) ? record.roles.map(String) : []
+    return {
+      roles,
+      permissions: [...new Set(readRows('roles').filter(role => roles.includes(String(role.code)) && role.status !== 'disabled').flatMap(role => Array.isArray(role.permissions) ? role.permissions.map(String) : []))],
+    }
+  }
+  function writeRows(resource: string, rows: DataRow[]): void {
+    localStorage.setItem(`demo:system:${resource}`, JSON.stringify(rows))
+  }
+  function assertWrite(resource: string, action: string): void {
+    const menu = localMenus.find(menu => menu.meta?.resource === resource)
+    const prefix = String(menu?.meta?.permissionPrefix ?? '')
+    if (!prefix || !getAccess().permissions.includes(`${prefix}:${action}`))
+      throw new Error('无操作权限')
+  }
+  function buildMenus(rows: DataRow[]): LumalMenuRecord[] {
+    const active = new Set<string>()
+    const identities = new Set(rows.map(row => String(row.id)))
+    const visit = (parentId = ''): LumalMenuRecord[] => rows
+      .filter(row => String(row.parentId ?? '') === parentId && row.type !== 'button')
+      .sort((left, right) => Number(left.order ?? 0) - Number(right.order ?? 0))
+      .map((row) => {
+        const id = String(row.id)
+        if (active.has(id))
+          throw new Error('菜单存在循环父节点')
+        active.add(id)
+        const original = localMenus.find(menu => menu.component === row.component)
+        if (row.type !== 'directory' && !original)
+          throw new Error(`菜单组件不在预设白名单中：${String(row.component)}`)
+        const children = visit(id)
+        active.delete(id)
+        return {
+          path: String(row.path),
+          name: String(row.name),
+          component: row.type === 'directory' ? undefined : original?.component,
+          children,
+          meta: { ...original?.meta, title: String(row.title), hideInMenu: Boolean(row.hidden), authority: row.permission as string | string[], order: Number(row.order ?? 0) },
+        }
+      })
+    for (const row of rows) {
+      const parents = new Set([String(row.id)])
+      let parent = String(row.parentId ?? '')
+      while (parent) {
+        if (parents.has(parent) || !identities.has(parent))
+          throw new Error('菜单父节点不存在或形成循环')
+        parents.add(parent)
+        parent = String(rows.find(item => String(item.id) === parent)?.parentId ?? '')
+      }
+      if (typeof row.path !== 'string' || !row.path.startsWith('/') || !row.name)
+        throw new Error('菜单必须配置绝对路径与唯一名称')
+    }
+    return visit()
+  }
+  return {
+    async login(input, signal) {
+      assertDemo()
+      signal.throwIfAborted()
+      const account = readRows('users').find(row => row.username === input.username)
+      if (!account || account.status === 'disabled' || input.password !== 'lumal123')
+        throw new Error('账号或密码不正确')
+      const accessToken = crypto.randomUUID()
+      sessionStorage.setItem(`demo:${accessToken}`, JSON.stringify({ id: input.username, name: input.username, username: input.username }))
+      return { accessToken }
+    },
+    getUser: async (signal) => {
+      signal.throwIfAborted()
+      return getUser()
+    },
+    getAccess: async (signal) => {
+      signal.throwIfAborted()
+      return getAccess()
+    },
+    getMenus: async (signal) => {
+      signal.throwIfAborted()
+      getUser()
+      // 只解析本预设组件白名单；菜单可编辑层级，不接受任意远程 import。
+      return buildMenus(readRows('menus'))
+    },
+    logout: async (token) => { sessionStorage.removeItem(`demo:${token}`) },
+    clearCache() {},
+    async list(resource, input) {
+      assertWrite(resource, resource === 'config' ? 'view' : 'list')
+      const keyword = String(input.query.keyword ?? '').trim()
+      const rows = readRows(resource).filter(row => (!keyword || Object.values(row).some(value => String(value).includes(keyword)))
+        && (!input.query.typeCode || row.typeCode === input.query.typeCode))
+      if (typeof input.query.sortField === 'string' && input.query.sortOrder) {
+        const field = input.query.sortField
+        rows.sort((left, right) => String(left[field] ?? '').localeCompare(String(right[field] ?? ''), 'zh-CN', { numeric: true }) * (input.query.sortOrder === 'desc' ? -1 : 1))
+      }
+      return { items: rows.slice((input.page - 1) * input.pageSize, input.page * input.pageSize), total: rows.length }
+    },
+    async save(resource, model, id) {
+      assertWrite(resource, id ? 'update' : 'create')
+      if (resource === 'roles' && Array.isArray(model.permissions))
+        assertWrite(resource, 'authorize')
+      const rows = readRows(resource)
+      if (id && !rows.some(row => row.id === id))
+        throw new Error('记录不存在')
+      const record: DataRow = { ...model, id: id ?? crypto.randomUUID() }
+      const uniqueField = resource === 'users' ? 'username' : resource === 'roles' ? 'code' : undefined
+      if (uniqueField && rows.some(row => row.id !== id && row[uniqueField] === record[uniqueField]))
+        throw new Error(`${uniqueField} 重复`)
+      if (resource === 'users' && id === 'admin' && (record.status === 'disabled' || !Array.isArray(record.roles) || !record.roles.includes('admin')))
+        throw new Error('不能停用或移除内置管理员角色')
+      const assignedPermissions = record.permissions
+      if (resource === 'roles' && id === 'admin' && (record.code !== 'admin' || record.status === 'disabled' || !Array.isArray(assignedPermissions) || !permissions.every(code => assignedPermissions.includes(code))))
+        throw new Error('不能停用或移除内置管理员权限')
+      const next = id ? rows.map(row => row.id === id ? record : row) : [...rows, record]
+      if (resource === 'menus')
+        buildMenus(next)
+      writeRows(resource, next)
+      return record
+    },
+    async remove(resource, id) {
+      assertWrite(resource, 'delete')
+      if (['users', 'roles'].includes(resource) && id === 'admin')
+        throw new Error('不能删除内置管理员')
+      if (resource === 'menus' && readRows(resource).some(row => row.parentId === id))
+        throw new Error('请先删除子菜单')
+      writeRows(resource, readRows(resource).filter(row => row.id !== id))
+    },
+  }
+}

package/templates/modes/local/tests/local.test.ts.template

@@ -0,0 +1,92 @@
+// @vitest-environment node
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { localMenus } from '../src/router/views'
+import { createBackend } from '../src/services/data-source'
+import { createApplicationSession } from '../src/services/session-runtime'
+
+function storage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    getItem: key => values.get(key) ?? null,
+    setItem: (key, value) => { values.set(key, value) },
+    removeItem: (key) => { values.delete(key) },
+    clear: () => values.clear(),
+    key: index => [...values.keys()][index] ?? null,
+    get length() { return values.size },
+  }
+}
+beforeEach(() => {
+  vi.unstubAllEnvs()
+  vi.stubGlobal('localStorage', storage())
+  vi.stubGlobal('sessionStorage', storage())
+})
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.unstubAllEnvs()
+})
+function application() {
+  return createApplicationSession(createBackend, localStorage, sessionStorage)
+}
+describe('本地应用服务', () => {
+  it('认证、动态菜单和重新初始化使用同一服务契约', async () => {
+    const app = application()
+    await expect(app.login({ username: 'admin', password: 'wrong' })).rejects.toThrow('账号或密码')
+    await app.login({ username: 'admin', password: 'lumal123' })
+    expect(app.currentUser.value?.username).toBe('admin')
+    expect(app.menus.value.some(menu => menu.path === '/dashboard')).toBe(true)
+    const token = app.session.getToken()
+    const restored = application()
+    await restored.initialize()
+    expect(restored.session.getToken()).toBe(token)
+    expect(restored.ready.value).toBe(true)
+    await restored.logout()
+    expect(sessionStorage.getItem(`demo:${token}`)).toBeNull()
+    expect(restored.permissionStore.roles).toEqual([])
+  })
+  it('生产默认拒绝演示账号，显式启用仅用于演示站点', async () => {
+    vi.stubEnv('PROD', true)
+    vi.stubEnv('VITE_ENABLE_LOCAL_DEMO', '')
+    await expect(application().login({ username: 'admin', password: 'lumal123' })).rejects.toThrow('生产环境')
+    vi.stubEnv('VITE_ENABLE_LOCAL_DEMO', 'true')
+    await expect(application().login({ username: 'admin', password: 'lumal123' })).resolves.toBeUndefined()
+  })
+  it('管理能力按预设启用，访客无写权限', async () => {
+    const app = application()
+    await app.login({ username: 'admin', password: 'lumal123' })
+    if (localMenus.some(menu => menu.component === 'system/users')) {
+      await app.service.save('users', { username: 'new-user', nickname: '新增', roles: ['guest'], status: 'enabled' })
+      const result = await app.service.list('users', { page: 1, pageSize: 10, query: { keyword: 'new-user' } })
+      expect(result.total).toBe(1)
+      await app.service.remove('users', String(result.items[0]?.id))
+      await expect(app.service.remove('users', 'admin')).rejects.toThrow('内置管理员')
+      await expect(app.service.save('users', { username: 'admin' })).rejects.toThrow('重复')
+      await expect(app.service.save('roles', { code: 'admin', status: 'disabled', permissions: [] }, 'admin')).rejects.toThrow('内置管理员')
+      await app.service.save('roles', { code: 'reader', name: '只读角色', status: 'enabled', permissions: ['system:user:list'] })
+      await app.service.save('users', { username: 'reader', roles: ['reader'], status: 'enabled' })
+      await app.service.save('dictionaries/items', { typeCode: 'status', label: '启用', value: 'enabled' })
+      expect((await app.service.list('dictionaries/items', { page: 1, pageSize: 10, query: { typeCode: 'other' } })).total).toBe(0)
+      await app.service.save('menus', { title: '目录', path: '/group', name: 'Group', type: 'directory' })
+      const group = (await app.service.list('menus', { page: 1, pageSize: 10, query: { keyword: 'Group' } })).items[0]!
+      await expect(app.service.save('menus', { ...group, parentId: group.id }, String(group.id))).rejects.toThrow('循环')
+      await expect(app.service.save('menus', { title: '恶意', path: '/bad', name: 'Bad', type: 'menu', component: 'https://evil.invalid/a.js' })).rejects.toThrow('白名单')
+      await app.login({ username: 'reader', password: 'lumal123' })
+      expect(app.permissionStore.permissions).toEqual(['system:user:list'])
+      await expect(app.service.list('users', { page: 1, pageSize: 10, query: {} })).resolves.toHaveProperty('total')
+      await expect(app.service.save('users', { username: 'denied' })).rejects.toThrow('无操作权限')
+    }
+    else if (localMenus.some(menu => menu.component === 'migration/users')) {
+      expect(app.permissionStore.permissions).toContain('system:user:create')
+      await app.service.save('users', { username: 'migration-only', nickname: '迁移用户', roles: ['guest'], status: 'enabled' })
+      const result = await app.service.list('users', { page: 1, pageSize: 10, query: { keyword: 'migration-only' } })
+      expect(result.total).toBe(1)
+      await app.service.remove('users', String(result.items[0]?.id))
+      expect((await app.service.list('users', { page: 1, pageSize: 10, query: { keyword: 'migration-only' } })).total).toBe(0)
+    }
+    else {
+      await expect(app.service.list('users', { page: 1, pageSize: 10, query: {} })).rejects.toThrow('无操作权限')
+    }
+    await app.login({ username: 'guest', password: 'lumal123' })
+    expect(app.permissionStore.permissions).toEqual([])
+    await expect(app.service.save('users', { username: 'denied' })).rejects.toThrow('无操作权限')
+  })
+})

package/templates/vben-compatible/MIGRATION.md

@@ -0,0 +1,28 @@
+# Vben 5 Element Plus 迁移基准
+
+基准 v5.7.0，commit `63a38dce49ba109f61607994e21ba921d8e970e9`。
+本项目不加载 VXE Table / vee-validate / Vben Store。
+
+1. `#/adapter/form` 和 `#/adapter/vxe-table` 改为 `@lumal/vben-compat/v5`。
+2. 保留 `[Form, formApi]`、单数 `schema`、`[Grid, gridApi]`、顶层 `formOptions`。
+3. 业务 API 接到本项目 ApplicationService。query 仍接收
+   `{ page: { currentPage, pageSize }, sort }` 和第二参数 formValues。
+4. 默认结果为 `{ items, total }`，不同响应在 `proxyConfig.response` 明确配置。
+5. Element Plus 控件属性沿用；Tailwind 布局需转成项目 CSS，
+   `wrapperClass` 的基础 grid-cols-N 映射为原生响应式列数。
+6. 原 Vben Drawer/Modal 改为 Element Plus Dialog 或 Lumal CRUD 编辑器。
+7. `@vben/access` 的高频用法可改为本入口的 AccessControl / useAccess；
+   路由数据先经 adaptVbenMenus，authority 按角色匹配。
+
+本模板 `migration/form` 对应 web-ele/demos/form/basic 与共享 rules/dynamic
+场景；`migration/users` 对应共享 vxe-table/form 和 system/user 的
+查询、分页、列配置、插槽操作、弹窗校验、增删改与按钮权限。
+不是声称原始页面仅换 import 就可以完整运行。
+
+不支持：任意自定义表单组件注册、VXE renderer、虚拟滚动、高级编辑、
+表单嵌套路径、fieldMappingTime、Vben 全局偏好 Store/Drawer/Modal。
+配置不在受支持类型内时会明确报错，不静默忽略。
+Zod 校验器可由应用自行安装后传入 rules；兼容包不内置或导出 z。
+Lumal Form 泛型约束模型字段，不是 Vben 的控件名称泛型；显式泛型需调整。
+配置通过 hook/setState 更新，不接受 schema/gridOptions 组件 props。
+Zod transform 需在应用提交边界处理；Grid 的命令式 query/reload 会向调用方传播错误。

package/templates/vben-compatible/src/components/migration/VbenFormExample.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { useVbenForm } from '@lumal/vben-compat/v5'
+import { shallowRef } from 'vue'
+
+/***********************5.7.0 基础控件与动态依赖迁移*********************/
+const submitted = shallowRef('')
+const [Form, formApi] = useVbenForm({
+  layout: 'horizontal',
+  wrapperClass: 'grid-cols-2',
+  handleSubmit(values) { submitted.value = JSON.stringify(values) },
+  schema: [
+    { component: 'Input', fieldName: 'name', label: '姓名', rules: 'required' },
+    { component: 'Select', fieldName: 'role', label: '角色', rules: 'selectRequired', componentProps: { options: [{ label: '管理员', value: 'admin' }, { label: '访客', value: 'guest' }] } },
+    { component: 'DatePicker', fieldName: 'date', label: '日期', rules: 'selectRequired', componentProps: { valueFormat: 'YYYY-MM-DD' } },
+    { component: 'Switch', fieldName: 'enabled', label: '启用扩展', defaultValue: true },
+    {
+      component: 'Input',
+      fieldName: 'remark',
+      label: '备注',
+      dependencies: { triggerFields: ['enabled', 'role'], if: values => Boolean(values.enabled), disabled: values => values.role === 'guest', required: values => values.role === 'admin' },
+    },
+    { component: 'Input', fieldName: 'cssHidden', label: '保留值字段', defaultValue: 'retained', dependencies: { triggerFields: ['enabled'], show: values => Boolean(values.enabled) } },
+  ],
+})
+defineExpose({ formApi })
+</script>
+
+<template>
+  <section>
+    <h2>Vben 5 表单</h2>
+    <Form />
+    <output aria-label="提交结果">{{ submitted }}</output>
+  </section>
+</template>

package/templates/vben-compatible/src/components/migration/VbenUsers.vue

@@ -0,0 +1,135 @@
+<script setup lang="ts">
+import type { ApplicationService, DataRow } from '../../services/contracts'
+import { AccessControl, useAccess, useVbenForm, useVbenVxeGrid } from '@lumal/vben-compat/v5'
+import { ElButton, ElDialog, ElMessageBox } from 'element-plus'
+import { nextTick, shallowRef } from 'vue'
+
+/***********************业务服务与权限边界*********************/
+const props = defineProps<{ service: Pick<ApplicationService, 'list' | 'save' | 'remove'> }>()
+const { hasAccessByCodes } = useAccess()
+const visible = shallowRef(false)
+const editingId = shallowRef<string>()
+const failure = shallowRef('')
+function rowId(row: DataRow): string {
+  if (typeof row.id !== 'string' && typeof row.id !== 'number')
+    throw new Error('用户缺少 id')
+  return String(row.id)
+}
+
+/***********************5.7.0 查询分页与列插槽迁移*********************/
+const [Grid, gridApi] = useVbenVxeGrid({
+  tableTitle: '用户迁移示例',
+  formOptions: { schema: [{ component: 'Input', fieldName: 'keyword', label: '关键词' }], submitOnEnter: true },
+  gridOptions: {
+    columns: [
+      { type: 'checkbox', width: 48 },
+      { type: 'seq', title: '序号', width: 64 },
+      { field: 'username', title: '用户名', sortable: true },
+      { field: 'nickname', title: '昵称' },
+      { field: 'status', title: '状态' },
+      { field: 'id', title: '操作', slots: { default: 'operation' } },
+    ],
+    rowConfig: { keyField: 'id' },
+    pagerConfig: { pageSize: 10 },
+    proxyConfig: {
+      ajax: {
+        query: ({ page, sort }, formValues) => props.service.list('users', {
+          page: page.currentPage,
+          pageSize: page.pageSize,
+          query: { ...formValues, sortField: sort.field, sortOrder: sort.order },
+        }),
+      },
+    },
+    toolbarConfig: { custom: true, refresh: true, search: true },
+  },
+})
+
+/***********************新增编辑弹窗与失败恢复*********************/
+const [Form, formApi] = useVbenForm({
+  showDefaultActions: false,
+  schema: [
+    { component: 'Input', fieldName: 'username', label: '用户名', rules: 'required' },
+    { component: 'Input', fieldName: 'nickname', label: '昵称', rules: 'required' },
+    { component: 'Select', fieldName: 'roles', label: '角色', defaultValue: ['guest'], componentProps: { multiple: true, options: [{ label: '访客', value: 'guest' }, { label: '管理员', value: 'admin' }] } },
+    { component: 'Select', fieldName: 'status', label: '状态', defaultValue: 'enabled', componentProps: { options: [{ label: '启用', value: 'enabled' }, { label: '停用', value: 'disabled' }] } },
+  ],
+})
+const saving = shallowRef(false)
+async function open(row?: DataRow): Promise<void> {
+  editingId.value = row ? rowId(row) : undefined
+  failure.value = ''
+  visible.value = true
+  await nextTick()
+  await formApi.resetForm()
+  if (row)
+    await formApi.setValues(row)
+}
+async function save(): Promise<void> {
+  if (saving.value || !(await formApi.validate()).valid)
+    return
+  saving.value = true
+  try {
+    await props.service.save('users', await formApi.getValues(), editingId.value)
+    visible.value = false
+    await gridApi.query()
+  }
+  catch (error) {
+    failure.value = error instanceof Error ? error.message : String(error)
+  }
+  finally {
+    saving.value = false
+  }
+}
+async function remove(row: DataRow): Promise<void> {
+  try {
+    await ElMessageBox.confirm(`删除 ${String(row.username)}？`, '删除确认')
+  }
+  catch {
+    return // Element Plus 的取消和关闭都表示不执行删除。
+  }
+  try {
+    await props.service.remove('users', rowId(row))
+    await gridApi.query()
+  }
+  catch (error) {
+    failure.value = error instanceof Error ? error.message : String(error)
+  }
+}
+defineExpose({ gridApi })
+</script>
+
+<template>
+  <section>
+    <p v-if="failure" role="alert">
+      {{ failure }}
+    </p>
+    <Grid>
+      <template #toolbar-tools>
+        <AccessControl type="code" :codes="['system:user:create']">
+          <ElButton type="primary" @click="open()">
+            新增用户
+          </ElButton>
+        </AccessControl>
+      </template>
+      <template #operation="{ row }">
+        <ElButton v-if="hasAccessByCodes(['system:user:update'])" link @click="open(row)">
+          编辑
+        </ElButton>
+        <ElButton v-if="hasAccessByCodes(['system:user:delete'])" link type="danger" @click="remove(row)">
+          删除
+        </ElButton>
+      </template>
+    </Grid>
+    <ElDialog v-model="visible" :title="editingId ? '编辑用户' : '新增用户'" destroy-on-close width="min(640px, 92vw)">
+      <Form />
+      <template #footer>
+        <ElButton @click="visible = false">
+          取消
+        </ElButton>
+        <ElButton type="primary" :loading="saving" @click="save">
+          保存
+        </ElButton>
+      </template>
+    </ElDialog>
+  </section>
+</template>

package/templates/vben-compatible/src/modules/vben.ts

@@ -0,0 +1,17 @@
+import { adaptVbenMenus } from '@lumal/vben-compat/v5/router'
+import '@lumal/vben-compat/style.css'
+
+// Vben authority 是角色；按钮权限继续由应用 PermissionStore 管理。
+export const menus = adaptVbenMenus([
+  { path: '/migration/form', name: 'VbenForm', component: 'migration/form', meta: { title: 'Vben 表单迁移', keepAlive: true } },
+  { path: '/migration/users', name: 'VbenUsers', component: 'migration/users', meta: { title: 'Vben 业务迁移', authority: ['admin'], keepAlive: true } },
+]).map((menu) => {
+  if (menu.component !== 'migration/users')
+    return menu
+  // 迁移页也可单独生成，资源权限不能依赖可选的 system 模块。
+  return { ...menu, meta: { ...menu.meta, permissionPrefix: 'system:user', resource: 'users' } }
+})
+export const views = {
+  'migration/form': () => import('../views/migration/VbenFormView.vue'),
+  'migration/users': () => import('../views/migration/VbenUsersView.vue'),
+}

package/templates/vben-compatible/src/views/migration/VbenFormView.vue

@@ -0,0 +1,10 @@
+<script setup lang="ts">
+/***********************迁移表单场景装配*********************/
+import VbenFormExample from '../../components/migration/VbenFormExample.vue'
+</script>
+
+<template>
+  <main class="lumal-admin-page">
+    <VbenFormExample />
+  </main>
+</template>