soybean-admin Documentation

Technical Documentation: soybeanjs/soybean-admin

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[!NOTE]
如果您觉得 SoybeanAdmin对您有所帮助，或者您喜欢我们的项目，请在 GitHub 上给我们一个 ⭐️。您的支持是我们持续改进和增加新功能的动力！感谢您的支持！

[!NOTE]
SoybeanAdmin 快速上手系列视频已在 Bilibili 上线 点击这里 前往查看

[!IMPORTANT]
SoybeanAdmin 3.0 版本正在开发中，将基于 ubean 全栈框架与 VeanUI 组件库进行整体重构，进展与方案请查看 Roadmap Issue #941。

[!WARNING]
2.3 将是 2.x 系列最后一个维护的大版本。2.x 后续只在该版本上提供维护更新，新特性将集中在 3.0 中实现，建议新项目关注 3.0 进展。

简介 Copy Chapter

SoybeanAdmin 是一个清新优雅、高颜值且功能强大的后台管理模板，基于最新的前端技术栈，包括 Vue3, Vite8, TypeScript, Pinia 和 UnoCSS。它内置了丰富的主题配置和组件，代码规范严谨，实现了自动化的文件路由系统。此外，它还采用了基于 ApiFox 的在线Mock数据方案。SoybeanAdmin 为您提供了一站式的后台管理解决方案，无需额外配置，开箱即用。同样是一个快速学习前沿技术的最佳实践。

特性 Copy Chapter

• 前沿技术应用：采用 Vue3, Vite8, TypeScript, Pinia 和 UnoCSS 等最新流行的技术栈。
• 清晰的项目架构：采用 pnpm monorepo 架构，结构清晰，优雅易懂。
• 严格的代码规范：遵循 SoybeanJS 规范，集成了eslint、oxlint、oxfmt 和 vp hooks，保证代码的规范性。
• TypeScript： 支持严格的类型检查，提高代码的可维护性。
• 丰富的主题配置：内置多样的主题配置，与 UnoCSS 完美结合。
• 内置国际化方案：轻松实现多语言支持。
• 自动化文件路由系统：自动生成路由导入、声明和类型。更多细节请查看 Elegant Router。
• 灵活的权限路由：同时支持前端静态路由和后端动态路由。
• 丰富的页面组件：内置多样页面和组件，包括403、404、500页面，以及布局组件、标签组件、主题配置组件等。
• 命令行工具：内置高效的命令行工具，git提交、删除文件、发布等。
• 移动端适配：完美支持移动端，实现自适应布局。

版本 Copy Chapter

[!IMPORTANT]
3.0 版本正在开发中（Roadmap Issue #941）；2.3 是 2.x 系列最后一个维护的大版本。

• NaiveUI 版本:
  • 预览地址
  • Github 仓库
  • Gitee 仓库
  • Gitcode 仓库
• AntDesignVue 版本:
  • 预览地址
  • Github 仓库
  • Gitee 仓库
  • Gitcode 仓库
• ElementPlus 版本:
  • 预览地址
  • Github 仓库
  • Gitee 仓库
  • Gitcode 仓库
• 旧版:
  • 预览地址
  • Github 仓库
  • Gitee 仓库
  • Gitcode 仓库

文档 Copy Chapter

• 地址
• 旧版文档

合作事项 Copy Chapter

我们非常感谢大家对 SoybeanAdmin 的支持！为了进一步回馈社区，并助力企业和开发者实现个性化需求，我们现提供多种合作服务，期待与您携手共赢。

1、定制化管理后台开发

针对企业和开发者的特定业务需求，我们提供基于 SoybeanAdmin 的定制化管理后台开发服务。我们的团队具备丰富的行业经验，能够迅速理解并实现您的需求，打造高效、灵活且安全的定制化解决方案。

• 定制开发：我们将根据您的具体需求，提供从需求分析、UI设计到功能实现的全方位服务，确保项目高效交付。
• 功能扩展：在 SoybeanAdmin 基础上，扩展您所需的特定功能模块，提升管理后台的功能和用户体验。

2、企业外包服务

我们承接各类企业级外包项目，特别是在管理后台系统的开发、集成与运维方面。我们以精益求精的态度，确保项目的质量和进度，为您的业务提供强有力的技术支持。

• 项目开发：无论是全新的项目，还是现有系统的优化与集成，我们都将为您量身打造高效可靠的解决方案。
• 系统集成与维护：我们也提供基于 SoybeanAdmin 的系统集成与长期维护服务，确保您的系统稳定、安全地运行。

3、联系方式

如有合作意向或项目咨询，请通过以下方式与我们联系：

• Email: [email protected]
• GitHub Issues: 欢迎通过 GitHub Issues 联系我们，进行初步的合作洽谈。
• 商务合作微信: honghuangdc

期待与您开展深入合作，共同推动 SoybeanAdmin 项目及其在更多领域的成功应用！

示例图片 Copy Chapter

使用 Copy Chapter

环境准备

确保你的环境满足以下要求：

• git: 你需要git来克隆和管理项目版本。
• NodeJS: >=20.19.0，推荐 20.19.0 或更高。
• pnpm: >= 10.5.0，推荐 10.5.0 或更高。

克隆项目

# github
git clone https://github.com/soybeanjs/soybean-admin.git
# gitee
git clone https://gitee.com/honghuangdc/soybean-admin.git
# gitcode
git clone https://gitcode.com/soybeanjs/soybean-admin.git

安装依赖

pnpm i

由于本项目采用了 pnpm monorepo 的管理方式，因此请不要使用 npm 或 yarn 来安装依赖。

启动项目

pnpm dev

构建项目

pnpm build

代码同步

参考 代码同步 文档。

周边生态 Copy Chapter

• skyroc-admin: SoybeanAdmin的React版本实现.
• electron-mock-admin: 一个 Mock Api 管理系统，帮助前端开发伙伴快速实现接口的 mock。
• T-Shell: 是一个可配置命令提示的终端模拟器和 SSH 客户端。
• pea : 采用SpringBoot3.2 + JDK21、MyBatis-Plus、SpringSecurity安全框架等，适配 soybean-admin 开发的简单权限系统。
• MalusAdmin: 基于 Vue3/TypeScript/NaiveUI 和 NET7 & Sqlsugar 开发的后台管理框架。采用最原生最简洁的方式来实现, 前端清新优雅高颜值，后端 结构清晰，优雅易懂，功能强大。
• PanisAdmin: 采用SpringBoot3、SaToken、MySQL等框架开发，二次修改 soybean-admin，适配动态菜单/按钮级别的鉴权，保留原汁原味、清新优雅、高颜值的后台管理系统脚手架。
• snail-job: 一款兼具 “高性能、高颜值、高活跃” 的分布式任务重试和分布式任务调度平台。
• SuperApi: 快速将你的 idea 变成线上稳定运行的产品！ 无实体建库建表，对无实体库表进行增删改查，支持 15 种条件查询，以及分页，列表，无限级树形列表 等功能的 API 部署！ 拥有接口文档，Auth 授权，接口限流，获取客户端真实 IP，先进的服务器缓存组件，动态 API 等功能，期待您的体验！
• FastSoyAdmin: 基于 FastAPI+Vue3+Naive UI 的现代化轻量管理平台.
• ba: 基于goFrame框架开发的后端服务对接soybean-admin,适配动态路由,接口鉴权限。
• soybean-admin-go:基于gin+gorm框架开发的go语言后端服务对接soybean-admin的example分支,适配动态路由,接口鉴权限。

更多周边生态请翻阅 周边生态 文档。

如何贡献 Copy Chapter

我们热烈欢迎并感谢所有形式的贡献。如果您有任何想法或建议，欢迎通过提交 pull requests 或创建 GitHub issue 来分享。

Git 提交规范 Copy Chapter

本项目已内置 commit 命令，您可以通过执行 pnpm commit 来生成符合 Conventional Commits 规范的提交信息。在提交PR时，请务必使用 commit 命令来创建提交信息，以确保信息的规范性。

浏览器支持 Copy Chapter

推荐使用最新版的 Chrome 浏览器进行开发，以获得更好的体验。

开源作者 Copy Chapter

Soybean

贡献者 Copy Chapter

感谢以下贡献者的贡献。如果您想为本项目做出贡献，请参考 如何贡献。

以下是近一年中活跃度较高的贡献者，感谢各位的支持，让项目得以持续发展。

交流 Copy Chapter

SoybeanAdmin 是完全开源免费的项目，在帮助开发者更方便地进行中大型管理系统开发，同时提供飞书群供大家交流，使用问题欢迎在群内提问。

飞书群

Star 趋势 Copy Chapter

开源协议 Copy Chapter

项目基于 MIT © 2021 Soybean 协议，仅供学习参考，商业使用请保留作者版权信息，作者不保证也不承担任何软件的使用风险。

V3 (`docs/v3.md`) Copy Section

soybean-admin v3.0 实现方案

基于 ubean + vite-plus + soybean-ui 的全栈重构方案

状态：草案（供评审）
基线：soybean-admin v2.x（main = 脚手架内核，example = 全功能演示）
参考实现：soybean-unify（简约全栈参考）、ubean examples/ubean-test（全栈骨架参考）

1. 背景与目标 Copy Chapter

soybean-admin v2.x 是纯前端 SPA 模板：Vue 3 + Vite + Naive UI + Pinia + UnoCSS + elegant-router，后端能力完全依赖 Apifox 在线 mock 或用户自备服务。v3.0 的目标：

1. 整体技术栈升级为全栈框架：以 ubean（v0.4.1，Vue 全栈框架，Hono 内核）为基座，构建工具链切换为 vite-plus（vp），UI 层切换为 VeanUI（@vean/ui + @vean/aria）。
2. 能力对齐：完整实现 v2.x（main + example）的全部能力，不丢"隐形能力"（见 §5.9）。
3. 简约优先：以 soybean-unify 的简约实现为参考范式——单一契约源（src/schema/ Valibot）、OpenAPI 类型化客户端、菜单驱动路由/页签/标题的一元数据模型、零自研布局、单包平铺工程结构。
4. 架子 + 样式适配：用 soybean-ui 搭好完整架子（布局/导航/页签/主题）；第三方 UI 库（naive-ui / element-plus / ant-design-vue）的样式适配器（让第三方组件对齐 soybean-ui 的颜色、圆角等设计 token）在独立仓库开发，使 v2 各发行版平滑过渡到 v3。
5. 双版本交付：
   • main 分支：全栈版（ubean 完整能力：文件路由 API + DB + 鉴权 + OpenAPI 类型共享）；
   • lite 分支（新分支承载）：前端版（仅 @ubean/vue 客户端内核 + 自定义后端，任意语言后端可接入）。

非目标 Copy Section

• 不实现 v2.x 从未存在过的能力（锁屏、cropper、ripple 等不在 example 基线内，不列入）。
• v3.0 首版不做 SSR/SSG（admin 面板模式官方推荐 mode: 'fullstack' + ssr: false）。
• 不做 naive-ui 等旧版组件级 1:1 转发适配（原因见 §7.1），适配器只做样式 token 对齐；适配器实现不进本仓库（§7.2）。

2. 技术选型总览 Copy Chapter

版本风险声明：ubean 当前 0.4.1、README 标注"不可生产"，0.3→0.4 刚做过入口大重构。v3.0 发布节奏必须与 ubean 版本锁定策略绑定（见 §10）。

3. 仓库与工程结构 Copy Chapter

3.1 项目结构（main 分支 = 全栈版，单包平铺） Copy Section

v3 不再使用 monorepo：应用直接落在仓库根目录（等价于把 v2 设想中 apps/admin/ 的内容平铺），全栈应用的天然属性（前端 + API + 数据库同仓同进程）使 workspace 分层失去意义。

/* Detailed source-code truncated for AI context efficiency. */

要点：

• 删除 v2 的 packages/ 私有包体系（@sa/axios、@sa/materials、@sa/hooks、@sa/color、@sa/scripts、@sa/uno-preset、@sa/alova、@sa/ofetch）与根 pnpm-workspace.yaml：其职责分别由 @soybeanjs/fetch、soybean-ui、@soybeanjs/utils、@vean/theme、@soybeanjs/cli、vp 承担，全部以已发布 npm 包消费，仓库内不再维护本地包。
• schema 下沉 src/schema/：全栈应用前后端同进程、同 tsconfig，Valibot schema 直接以相对路径 import（#/schema/auth），无需 workspace 包；DTO 类型即 schema 推导类型，单一契约源不变。
• 第三方 UI 样式适配不放本仓库：由独立仓库开发（见 §7.2），本项目只保留对接约定。
• mock 服务退役：src/service/api/* 手写 API 层与 Apifox mock 全部删除，接口由 src/routes/api/** 真实实现，dev 即跑真后端（同进程，Vite middlewareMode + Hono）。
• v2 src/views → src/pages：文件约定基本同构（[id].vue 动态段、(group) 路由组、_builtin → (builtin)），迁移以目录重命名 + meta 改写为主。
• 路径别名统一 #/ → src/（vite-plus tsconfigPaths + ubean 默认约定）。

3.2 双版本分支策略（要求 8） Copy Section

同步机制：lite 分支定期从 main rebase/merge，冲突面控制在上述差异点（集中在 5 个文件/目录）。CI 对两分支都跑 typecheck + build。文档站分别说明两种起步方式：pnpm create 模板对应 main；lite 作为"接入自定义后端"的官方示例。

4. 现有能力 vs v3.0 能力实现对比（核心） Copy Chapter

4.1 布局与导航 Copy Section

4.2 路由与权限 Copy Section

4.3 请求与后端 Copy Section

4.4 状态管理 Copy Section

v2 的 5 个 store（app/auth/route/tab/theme）+ v3 新增 menu，全部保留为 Pinia setup store（unify 验证 6 store 结构）：

4.5 i18n / 主题 / 图标 Copy Section

4.6 页面功能对齐清单 Copy Section

4.7 工程能力 Copy Section

5. 前端详细设计 Copy Chapter

5.1 应用入口与生命周期 Copy Section

// src/app.ts
import { defineApp } from 'ubean/client';
import { setupStore } from './store';

export default defineApp({
  appRoot: () => import('./app.vue'), // SConfigProvider 包装层
  plugins: [setupStore], // pinia 经 @ubean/integrations/pinia
  router: {
    setup(router) {
      router.beforeEach(authGuard); // 登录/权限/动态路由初始化
      router.beforeEach(progressGuard); // soybean-ui progress
      router.afterEach(titleGuard); // document.title（菜单 i18nKey 驱动）
    }
  },
  onClientReady() {
    setupLoading(); // 首屏 HTML loading（主题色联动）
  }
});

app.vue（appRoot）：SConfigProvider（theme/persistTheme/dir/locale）+ Toast/Dialog Provider 挂载 + 全局水印 SWatermark。

5.2 布局架子（layouts/default.vue） Copy Section

<script setup lang="ts">
import { SAppShell } from '@vean/ui';

const active = ref('');
// items：菜单树（AppShellMenuItem[]，唯一数据入口；面包屑/高亮路径由 shell 派生）
</script>
<template>
  <SAppShell
    v-model="active"
    v-model:tab-value="tabStore.activeTab"
    mode="dual-vertical"
    :items="menuStore.items"
    :tabs="tabStore.tabs"
    expand-strategy="keep"
    @tab-click="tabStore.switchTab"
    @tab-close="tabStore.removeTab"
  >
    <template #logo><AppLogo /></template>
    <template #headerStart>
      
    </template>
    <template #headerCenter><GlobalSearch /></template>
    <template #headerEnd>
      <UserAvatar />
      <ThemeModeSwitch />
    </template>
    <template #default><RouterView /></template>
    <template #footer v-if="footerVisible"><LayoutFooter /></template>
  </SAppShell>
</template>

要点：

• mode 承接 v2 全部 6 种布局：sidebar（原 vertical / vertical-mix 的侧栏形态）、top（原 horizontal）、dual-vertical（原 vertical-mix）、vertical-horizontal（原 top-hybrid-sidebar-first）、horizontal-vertical（原 top-hybrid-header-first）、horizontal-dual-vertical（原 vertical-hybrid-header-first）。模式名描述菜单形态而非方向：一级菜单垂直 = 全高侧栏，一级水平 = 顶栏；orientation 等布局朝向由 shell 从 mode 派生（相对旧 SLayout 直填 props 是反转的），应用层不再手写。
• 一棵菜单树喂所有渲染器：items: AppShellMenuItem[] 是唯一菜单数据入口，sidebar/top 渲染 STreeMenu/STreeNav，4 种 split 模式渲染 SSplitNav，无需按模式切换组件。
• breadcrumbs 默认由 items + 激活值自动派生（原 menu store 派生逻辑内化），传入才覆盖；expandStrategy: 'selected' | 'keep' 控制折叠后展开策略（top 模式无此项；menuProps.tree/split 优先级更高）。
• 品牌/标题仅经 #logo/#title 插槽注入，logoPlacement: 'auto' | 'sidebar' | 'sidebar-bottom' | 'header' 控制落位（sidebar-bottom 仅 sidebar/dual-vertical 生效）；折叠触发按钮位置跟随一级菜单位置，由 shell 统一安排。
• 移动端恒以 sidebar 骨架渲染全量菜单树抽屉（767.9px 断点；props 保留宿主传值），v-model:mobileOpen 受控。
• 主题/布局配置映射：theme store → layoutProps 转发内部 SLayout（shell 自己持有 open/orientation/sidebarVisible/isMobile/pxToRem，应用层只喂配置面）；样式三层 ui / layoutUi / menuUi（tree/split/treeNav）。
• 与路由无关：纯数据入（items/tabs/breadcrumbs）+ 事件出（update:open / update:mobileOpen / update:modelValue / select / open / update:tabValue / update:tabs / tabClick / tabClose），路由联动留在 route/menu store。

v2 layout.mode → SAppShell mode 映射表：

5.3 路由与菜单一元模型 Copy Section

• 页面即文件：src/pages/** 自动生成路由表（routing: { mode: 'virtual' }，admin 无需生成文件；lite 分支同样使用）。
• definePage({ requiresAuth: true, meta: { keepAlive, multiTab, pinned, ... } }) 编译期宏，零运行时开销。
• 动态路由：dynamic 模式下后端菜单（menuType menu|page）→ transformMenusToAutoRoutes → router.addRoute；routeName/routePath 与页面路由表做一致性校验（启动断言，防漂移）。
• 标题：菜单 i18nKey 单一来源；无菜单条目的静态页（异常页等）用 definePage({ meta: { title } }) 兜底。此为对 v2 "meta.i18nKey 全局唯一来源"的简化统一。

5.4 请求层 Copy Section

// src/request/client.ts
import { createRequest } from '@soybeanjs/fetch';
import { toFlatTypedClient } from '@soybeanjs/fetch/openapi';
import type { paths } from '../../.ubean/openapi';

const request = createRequest(
  { baseURL: '/api' },
  {
    transform: response => response.data.data,
    isBackendSuccess: response => response.data.code === import.meta.env.VITE_SERVICE_SUCCESS_CODE,
    onRequest: config => {
      /* 注入 Bearer token */
    },
    onError: error => {
      /* 登出码 / 弹窗登出 / 过期刷新重放 / 错误去重 */
    }
  }
);

export const api = toFlatTypedClient<paths, '/api'>(request, '/api');
// 用法：const { data, error } = await api.get('/user/list', { params });

• 内核为 fetch（免 axios 依赖），上传进度用 createUploadProgressAdapter，文件下载用内置 downloadFile。
• baseRequest 承担：Bearer 注入、{ code, message, data } 解包、业务码分支（登出/弹窗登出/过期刷新重放）、错误去重。全部逻辑 ≤150 行。
• 服务端进程内复用：createInternalAdapter(c) 注入 adapter，internal.ts 零网络直调 handler（unify/ubean-test 同款）。

5.5 鉴权流程 Copy Section

1. POST /api/auth/login（valibot 校验 + 验证码）→ 返回 { accessToken, refreshToken } → localStg 存储。
2. 守卫首次进入：GET /api/auth/user-info + GET /api/role/user + GET /api/menu/user → 初始化路由/菜单/页签。
3. 登出：调 POST /api/auth/logout（拉黑 refreshToken）+ 前端 resetStore（修复 unify 未调后端的问题）。
4. 刷新链路：过期码 → 单飞 refreshTokenPromise → 重放队列 → 失败则登出。

5.6 主题系统 Copy Section

• theme store settings（保留 v2 全量配置项语义）→ 双路输出：① ThemeOptions（base/primary/radius/preset/overrides）→ createTheme CSS 变量；② layoutProps → SAppShell（模式派生 orientation，见 §5.2）。
• 暗色：useColorMode → SConfigProvider dark selector .dark；SSR 防闪烁脚本暂不需要（无 SSR），首帧防闪烁沿用 plugins/loading.ts 思路。
• 主题抽屉：SThemeCustomizer 承担外观 Tab；布局/通用/操作三个 Tab 应用层实现（配置项清单照搬 v2 theme-drawer）。

5.7 表格与 CRUD 范式 Copy Section

usePaginatedTable（soybean-ui 内置）+ useTableOperate（应用 composable）+ defaultTableTransform：

• STable 列模型（TableColumnType: 'index'|'selection'|'expand' + sortable + virtual）替代 NaiveUI.TableColumn。
• v2 table-column-setting（列勾选/固定/拖拽排序）、table-header-operation 用 SDropdownMenu + vue-draggable-plus 重写，保留为全局组件。
• 校验：SForm + StandardSchema（直接复用 src/schema/ 的 valibot schema，前后端同一份校验规则）。

5.8 第三方集成页依赖 Copy Section

保留 v2 example 全部演示页，依赖映射：echarts、@antv/g2、@antv/g6、vchart、wangeditor、vditor、xlsx、vue-pdf-embed、print-js、jsbarcode、pinyin-pro、xgplayer、@fawmi/vue-google-maps（或国内三图 JS SDK 直连）、swiper、typeit、vtable、dhtmlx-gantt。全部经 definePage 懒加载隔离在 pages/plugin/**，不进主包体积（配合 bundle 基线回归）。

5.9 必须保留的"隐形能力"清单（回归测试用例来源） Copy Section

版本更新检测、跨用户登录清页签、主题设置生产缓存 + BUILD_TIME 版本覆盖、错误消息去重、token 刷新并发去重、移动端布局备份恢复、水印定时器按需运行、页签滚轮横滚/中键关闭、isDev 路由、activeMenu/multiTab/fixedIndexInTab/href meta 语义、首屏 loading 主题色联动、登录成功 notification。

5.10 env 变量精简 Copy Section

VITE_APP_TITLE / VITE_APP_DESC
VITE_AUTH_ROUTE_MODE=static|dynamic    VITE_ROUTE_HOME
VITE_ROUTER_HISTORY_MODE=hash|history
VITE_SERVICE_SUCCESS_CODE / VITE_SERVICE_LOGOUT_CODES / VITE_SERVICE_MODAL_LOGOUT_CODES / VITE_SERVICE_EXPIRED_TOKEN_CODES
VITE_STATIC_SUPER_ROLE
VITE_STORAGE_PREFIX
VITE_API_ENV / VITE_API_PROXY          VITE_THEME_PRESET
VITE_AUTOMATICALLY_DETECT_UPDATE

删除：naive 相关、mock baseURL、ICONIFY_URL（改 @ubean/icon 配置）、SOURCE_MAP（ubean build 配置承载）、PROXY_LOG（routeRules 承载）。

6. 后端详细设计（仅 main 分支） Copy Chapter

6.1 分层 Copy Section

src/routes/api/**     文件式 API 路由：defineHandler(defineHandlerMeta, describeRoute, validator('json', schema), handler)
src/server.ts         defineServer：全局 hooks（requestId、日志、错误映射）
src/middleware/       01.auth.ts：Bearer → verifyToken（黑名单+用户状态）→ 权限码匹配 → checkUserHasPermission
src/services/         纯函数/composable 业务层（每资源 *.service.ts）
src/db/               Drizzle schema（移植 unify 13 表：user/role/permission/api/menu/org/dict/dict-item + 4 关系表）+ 迁移 + seed
src/schema/           Valibot DTO（前后端源码直消费，不构建）

• 统一响应：response 中间件重写 c.json → { code:'0000', message, data }；错误 AppError + error 中间件同构输出（含业务码：8888 登出 / 7777 弹窗登出 / 9999 过期，支撑前端演示页）。
• OpenAPI：dev 自动挂 /_openapi.json + /_scalar，替代 v2 "手写接口文档给后端同学"的痛点。
• 数据模型约定沿用 unify：UUID v7 字符串主键、enabled: 'Y'|'N'|'D' 软删、审计四字段。

6.2 数据库与驱动 Copy Section

• dev：defineDatabase 默认 SQLite 文件（better-sqlite3 connector），开箱跑通 + seed 演示数据。
• prod：Postgres（postgres-js）；cloudflare 适配版（D1）作为可选示例目录（参考 unify apps/cloudflare，v3.2 再评估）。
• 风险：ubean DB 原语默认内存实现，必须显式接线 db0 connector 并在文档强调（roadmap 自述风险）。

6.3 接口清单（对齐 v2 mock + unify） Copy Section

6.4 鉴权方案取舍 Copy Section

• 首版：unify 式自研 JWT（hono/jwt + bcryptjs + 黑名单经 useCacheStore，dev 内存 / prod Redis driver）——行为完全可控，与 v2 业务码语义无缝。
• 演进：@ubean/auth（Better Auth）作为 v3.x 可选模块评估切换（session/多 provider 能力更强），通过 defineHandlerMeta({ requiresAuth }) + useAuth() 前端体验统一，切换成本收敛在 auth 模块。

6.5 服务端能力利用（ubean 差异化价值） Copy Section

defineQueue（导出任务异步化）、defineScheduled（字典缓存刷新）、defineWebSocket/createSSEStream（通知中心演示页）、useRateLimit（登录防爆破）、useCacheStore（验证码/字典缓存）、routeRules（dev 代理、prod CDN headers）。这些作为 v3.1+ 增值演示，不进首版关键路径。

7. 架子 + 第三方 UI 样式适配（要求 7） Copy Chapter

7.1 架构原则：架子 100% 基于 soybean-ui，适配只做"样式对齐" Copy Section

v3 的架子层（layout/menu/tabs/theme store/router/store/request）全部构建在 @vean/ui + @vean/aria 之上，不存在"换 UI 库跑同一套架子"的转发层。当业务页需要引入第三方组件时（naive-ui / element-plus / ant-design-vue——无论因 soybean-ui 组件缺口，还是因 v2 迁移用户存量代码），适配器的职责是：让第三方组件适配 soybean-ui 的样式体系（颜色、圆角、字号、明暗等设计 token），保证同一页面视觉一致。

7.2 适配器在独立仓库开发，不进本仓库 Copy Section

• 独立仓库（建议命名 soybean-ui-adapters）承载全部适配实现，soybean-admin 只保留两个对接点：
  1. token 输出：theme store 将生效的 @vean/theme 变量（--primary/--radius/--background/--sidebar-*…，light/dark 双份）以结构化对象暴露（useThemeTokens()），并派发 soybean:theme-change 事件；
  2. 挂载约定：用户在 app.vue（appRoot）按需注册适配器，如 setupNaiveAdapter()。
• 适配原理（按目标库主题机制选择）：
  • naive-ui：ThemeSettings → GlobalThemeOverrides（common.primaryColor/borderRadius/高度字号…），经 NConfigProvider 注入——即 v2 反向能力（naive overrides 跟 soybean token 走）；
  • element-plus：token → --el-color-primary（含 light-3/5/7/8/9、dark-2 派生梯度）、--el-border-radius-base、--el-bg-color 系列 CSS 变量直写；
  • ant-design-vue：token → ConfigProvider :theme="{ token: { colorPrimary, borderRadius, colorBgContainer... }, algorithm: dark ? theme.darkAlgorithm : defaultAlgorithm }"。
• 派生算法对齐：primary 梯度（hover/active/disabled）统一用 @soybeanjs/colord 按 soybean-ui 同一规则生成，避免三库各自派生导致色差。
• 交付形态：每库一个包（@soybeanjs/adapter-naive 等）+ 一个共享核心（token 映射表 + 订阅 theme-change 的 runtime），由适配器仓库独立发布、独立版本。

7.3 soybean-ui 当前缺口与对策 Copy Section

7.4 v2 naive/element/antd 版用户迁移路径 Copy Section

1. pnpm create soybean-admin@v3（全栈版）或 clone lite 分支；
2. 业务页从 views/ 迁到 pages/，useNaiveTable → usePaginatedTable（列模型字段映射表随迁移文档提供）；
3. 存量第三方组件页暂不改写 → 安装对应适配器包（如 @soybeanjs/adapter-naive），第三方组件即自动跟随 soybean-ui 主题（含暗色切换与自定义主色/圆角），页面视觉一致；
4. 随 soybean-ui 组件覆盖度提升逐页替换为 S* 组件，最终移除适配器——一套架子渐进收敛，替代 v2 时代"每个 UI 库 fork 一个仓库"（soybean-admin-element-plus 等）的维护模式。

8. lite 分支（@ubean/vue 前端版）详细设计（要求 8） Copy Chapter

基于 examples/client-only-spa 形态：

// vite.config.ts
import { defineConfig } from 'vite-plus';
import { ubeanVueVite } from '@ubean/vue/vite';
export default defineConfig({ plugins: [ubeanVueVite({ markdown: false, head: true })] });

// main.ts
import { createApp } from 'vue';
import { ubeanVue } from '@ubean/vue';
import routes from 'virtual:ubean-vue-routes';
createApp(App).use(ubeanVue, { routes }).mount('#app');

• 保留：文件式路由 + definePage、动态段 matcher、keep-alive、页面过渡、<Link>/。
• 移除：src/routes/、src/server.ts、ubean.config.ts、loader/usePage 数据层、@ubean/i18n（改手工 vue-i18n 装配，与 v2 一致）、SSR 相关一切。
• 请求层：toFlatTypedClient 的 paths 来自用户 openapi-typescript <用户后端 openapi.json> 生成脚本（pnpm gen:api），文档提供 Java/Go/Python/Node 各后端的契约示例。
• 鉴权：前端流程同 main（守卫/存储/权限过滤），登录接口路径 env 可配（VITE_API_LOGIN_PATH 等），兼容非标准响应码。
• 维护约定：lite 不引入框架未提供的"伪全栈"能力；两分支差异清单固化在 docs/lite-delta.md，CI 校验 main→lite merge 只触碰 5 个差异文件。

9. 实施路线图 Copy Chapter

Phase 0 — 地基（脚手架与工具链） Copy Section

• 单包工程重建：根目录平铺（ubean.config.ts + vite.config.ts + src/），vite-plus 接管 dev/lint/fmt/test，@soybeanjs/cli（soy）接管 commit/changelog/release/cleanup
• ubean 骨架跑通：ubean.config.ts（fullstack/ssr:false/ui/icon/pinia/i18n）+ pages/ 路由 + app.ts 守卫注入
• src/schema/ 建立；.ubean/openapi.d.ts codegen 链路 + @soybeanjs/fetch typed client 打通
• CI：typecheck + build + bundle 基线

Phase 1 — 后端内核 Copy Section

• Drizzle 13 表 + 迁移 + seed（unify 移植）
• auth 模块（双 token + 黑名单 + 验证码）+ 统一响应/错误/业务码
• menu/role/user/permission/api/org/dict/dict-item 8 套 CRUD + RBAC 中间件
• Scalar 文档 + 集成测试（ubean-test 38 例范式，目标 ≥40 例）

Phase 2 — 前端架子 Copy Section

• SAppShell 6 模式布局承接 + theme store/layoutProps
• 菜单驱动路由/页签/标题一元模型（static + dynamic 双模式）
• SAppShell 内置页签全量能力（tabs/tabValue/tabClick/tabClose 对接 tab store）+ keep-alive + reload + 多标签
• 请求层（含 token 刷新重放）+ 登录/注册/验证码全流程
• i18n 双语 + 暗色 + 主题抽屉 + 全局搜索 + 水印 + 移动端适配

Phase 3 — 业务页面 Copy Section

• dashboard 首页（统计卡/图表/动态）
• manage 8 套 CRUD 页（表格范式 + 列设置 + 弹窗表单）
• function 演示页全量（含按钮级权限 v-auth + 角色分配弹窗）
• 403/404/500/iframe/about/profile/settings

Phase 4 — 插件演示与增值 Copy Section

• plugin 演示页（editor/excel/pdf/charts/video/map/gantt...）
• 版本更新检测、错误去重等隐形能力回归测试
• lite 分支切出与差异固化

Phase 5 — 适配对接与发布 Copy Section

• 与独立适配器仓库（soybean-ui-adapters）联调：useThemeTokens() + soybean:theme-change 对接约定落地，naive/element/antd 样式适配验证
• 缺口组件（Upload 等）补齐或桥接
• 文档站更新（v3 指南 + 迁移指南 + API 契约文档）+ 中英 README 重写
• beta（v3.0.0-beta.x 对齐 ubean 0.4.x 锁定版本）→ rc → stable

分支与版本计划 Copy Section

main          v3.0.0-beta → rc → stable（全栈版）
lite          从 main Phase 2 完成后切出，跟随 main 里程碑同步
v2.x          维护分支仅收安全/严重 bug，README 置顶迁移指引

10. 风险与对策 Copy Chapter

11. 附录 Copy Chapter

11.1 关键参考路径 Copy Section

• ubean 全栈骨架：/Users/soybean/Web/Projects/SoybeanJS/ubean/examples/ubean-test/（38 集成测试）
• 纯前端 SPA 形态：ubean/examples/client-only-spa/
• 后端范式：/Users/soybean/Web/Projects/SoybeanJS/soybean-unify/apps/server/src/（routes/services/db/middleware）
• 前端简约范式：soybean-unify/apps/admin/src/（store 6 个、service ~80 行、layouts/base 用 SAppShell）
• 布局组件源码：soybean-ui2/packages/ui/src/components/app-shell/（SAppShell 6 模式；配套 src/styles/app-shell.ts、test/specs/components/app-shell.spec.ts、zh/en 文档 apps/docs/src/content/{zh,en}/ui/components/app-shell.md）
• 主题引擎：soybean-ui/packages/theme/src/{variables.ts,index.ts}
• ubean API 速查与陷阱清单：ubean/AGENTS.md（18 条注意事项）、ubean/skills/ubean/SKILL.md

11.2 术语 Copy Section

• 一元数据模型：菜单记录 = 导航条目 + 路由定义 + 页签标题来源（App.Menu = MenuDTO + RouteKey 收窄），源自 unify。
• 样式适配（adapter）：独立仓库实现，把 soybean-ui 的设计 token（颜色/圆角/明暗…）映射到 naive（themeOverrides）/ element（--el-* 变量）/ antd（ConfigProvider theme token），使第三方组件与 S* 组件同页视觉一致。
• 契约源：src/schema/（Valibot）为 DTO/校验唯一来源；OpenAPI 生成为类型客户端来源。

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~16142 tokens
• Canonical Reference: https://codewiki.google/github.com/soybeanjs/soybean-admin