# Technical Documentation: soybeanjs/soybean-admin

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/soybeanjs/soybean-admin)

### Overview (`README.md`)

<div align="center">
	<img src="https://img.soybeanjs.dev/logo-soybean-admin.svg?20261009211" width="160" />
	<h1>SoybeanAdmin</h1>
  <span>中文 | <a href="./README.en_US.md">English</a></span>
</div>

---

[](./LICENSE)
[](https://github.com/soybeanjs/soybean-admin)
[](https://github.com/soybeanjs/soybean-admin)
[](https://gitee.com/honghuangdc/soybean-admin)
[](https://gitcode.com/soybeanjs/soybean-admin)

<div style="display: flex; gap: 12px; align-items: center;">
  <a href="https://trendshift.io/repositories/7963" target="_blank"><img src="https://trendshift.io/api/badge/repositories/7963" alt="soybeanjs%2Fsoybean-admin | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
  <a href="https://hellogithub.com/repository/1298f27d5fe54959a16cf9686516ddb3" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=1298f27d5fe54959a16cf9686516ddb3&claim_uid=IiDXWmP4TEntjbV" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
</div>

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

> [!NOTE]
> `SoybeanAdmin` 快速上手系列视频已在 [Bilibili](https://www.bilibili.com/video/BV1YKdRYXELC) 上线 [点击这里](https://www.bilibili.com/video/BV1YKdRYXELC) 前往查看

> [!IMPORTANT]
> `SoybeanAdmin` 3.0 版本正在开发中，将基于 ubean 全栈框架与 VeanUI 组件库进行整体重构，进展与方案请查看 [Roadmap Issue #941](https://github.com/soybeanjs/soybean-admin/issues/941)。

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

<div align="center">
  <table width="100%">
    <tr>
      <td align="left">
        <table>
          <tr>
            <td>
              <a href="https://veanui.com">
                <img alt="VeanUI" src="https://img.soybeanjs.dev/logo-vean-ui.svg" width="52" />
              </a>
            </td>
            <td>
              <a href="https://veanui.com">
                <img
                  alt="VeanUI"
                  src="https://img.shields.io/badge/VeanUI-Aria%20%2B%20UI-6366f1?style=for-the-badge&labelColor=312e81"
                />
              </a>
            </td>
          </tr>
        </table>
        <strong>面向 Vue 3 的强大而优雅的组件系统，提供 Aria 层交互能力与开箱即用的样式封装。</strong><br />
        <sub>采用 Aria + UI 两层架构，复用底层交互能力，统一上层界面表达。</sub>
        <br /><br />
        <img alt="Vue 3" src="https://img.shields.io/badge/Vue%203-Component%20Library-6366f1?style=flat-square&labelColor=4338ca" />
        <img alt="Aria" src="https://img.shields.io/badge/Aria-Logic%20%26%20State-818cf8?style=flat-square&labelColor=3730a3" />
        <img alt="Admin" src="https://img.shields.io/badge/Admin-Professional%20UI-a5b4fc?style=flat-square&labelColor=4f46e5" />
      </td>
      <td align="right">
        <a href="https://veanui.com">
          <img
            alt="Visit VeanUI"
            src="https://img.shields.io/badge/%E7%AB%8B%E5%8D%B3%E8%AE%BF%E9%97%AE-veanui.com-6366f1?style=for-the-badge&labelColor=312e81&logo=vercel&logoColor=white"
          />
        </a>
      </td>
    </tr>
  </table>
</div>

## 简介

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

## 特性

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

## 版本

> [!IMPORTANT]
> 3.0 版本正在开发中（[Roadmap Issue #941](https://github.com/soybeanjs/soybean-admin/issues/941)）；`2.3` 是 2.x 系列最后一个维护的大版本。

- **NaiveUI 版本:**
  - [预览地址](https://naive.soybeanjs.cn/)
  - [Github 仓库](https://github.com/soybeanjs/soybean-admin)
  - [Gitee 仓库](https://gitee.com/honghuangdc/soybean-admin)
  - [Gitcode 仓库](https://gitcode.com/soybeanjs/soybean-admin)
- **AntDesignVue 版本:**
  - [预览地址](https://antd.soybeanjs.cn/)
  - [Github 仓库](https://github.com/soybeanjs/soybean-admin-antd)
  - [Gitee 仓库](https://gitee.com/honghuangdc/soybean-admin-antd)
  - [Gitcode 仓库](https://gitcode.com/soybeanjs/soybean-admin-antd)
- **ElementPlus 版本:**
  - [预览地址](https://elp.soybeanjs.cn/)
  - [Github 仓库](https://github.com/soybeanjs/soybean-admin-element-plus)
  - [Gitee 仓库](https://gitee.com/honghuangdc/soybean-admin-element-plus)
  - [Gitcode 仓库](https://gitcode.com/soybeanjs/soybean-admin-element-plus)
- **旧版:**
  - [预览地址](https://legacy.soybeanjs.cn/)
  - [Github 仓库](https://github.com/soybeanjs/soybean-admin/tree/legacy)
  - [Gitee 仓库](https://gitee.com/honghuangdc/soybean-admin/tree/legacy)
  - [Gitcode 仓库](https://gitcode.com/soybeanjs/soybean-admin/tree/legacy)

## 文档

- [地址](https://docs.soybeanjs.cn)
- [旧版文档](https://legacy-docs.soybeanjs.cn)

## 合作事项

我们非常感谢大家对 [`SoybeanAdmin`](https://github.com/soybeanjs/soybean-admin) 的支持！为了进一步回馈社区，并助力企业和开发者实现个性化需求，我们现提供多种合作服务，期待与您携手共赢。

##### 1、定制化管理后台开发

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

- **定制开发**：我们将根据您的具体需求，提供从需求分析、UI设计到功能实现的全方位服务，确保项目高效交付。
- **功能扩展**：在 [`SoybeanAdmin`](https://github.com/soybeanjs/soybean-admin) 基础上，扩展您所需的特定功能模块，提升管理后台的功能和用户体验。

##### 2、企业外包服务

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

- **项目开发**：无论是全新的项目，还是现有系统的优化与集成，我们都将为您量身打造高效可靠的解决方案。
- **系统集成与维护**：我们也提供基于 [`SoybeanAdmin`](https://github.com/soybeanjs/soybean-admin) 的系统集成与长期维护服务，确保您的系统稳定、安全地运行。

##### 3、联系方式

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

- **Email**: [soybeanjs@outlook.com](mailto:soybeanjs@outlook.com)
- **GitHub Issues**: 欢迎通过 [GitHub Issues](https://github.com/soybeanjs/soybean-admin/issues/new) 联系我们，进行初步的合作洽谈。
- **商务合作微信**: honghuangdc

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

## 示例图片













## 使用

**环境准备**

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

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

**克隆项目**

```bash
# 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
```

**安装依赖**

```bash
pnpm i
```

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

**启动项目**

```bash
pnpm dev
```

**构建项目**

```bash
pnpm build
```

**代码同步**

参考 [代码同步](https://docs.soybeanjs.cn/zh/guide/sync) 文档。

## 周边生态

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

更多周边生态请翻阅 [周边生态](https://docs.soybeanjs.cn/zh/awesome) 文档。

## 如何贡献

我们热烈欢迎并感谢所有形式的贡献。如果您有任何想法或建议，欢迎通过提交 [pull requests](https://github.com/soybeanjs/soybean-admin/pulls) 或创建 GitHub [issue](https://github.com/soybeanjs/soybean-admin/issues/new) 来分享。

## Git 提交规范

本项目已内置 `commit` 命令，您可以通过执行 `pnpm commit` 来生成符合 [Conventional Commits](<[conventionalcommits](https://www.conventionalcommits.org/)>) 规范的提交信息。在提交PR时，请务必使用 `commit` 命令来创建提交信息，以确保信息的规范性。

## 浏览器支持

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

| [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png" alt="IE" width="24px" height="24px"  />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt=" Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| not support                                                                                                                                                                                                                             | last 2 versions                                                                                                                                                                               | last 2 versions                                                                                                                                                                                       | last 2 versions                                                                                                                                                                                    | last 2 versions                                                                                                                                                                                    |

## 开源作者

[Soybean](https://github.com/honghuangdc)

## 贡献者

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

<a href="https://github.com/soybeanjs/soybean-admin/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=soybeanjs/soybean-admin" />
</a>

---

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

<a href="https://openomy.com/soybeanjs/soybean-admin" target="_blank" style="display: block; width: 100%;" align="center">
  <img src="https://www.openomy.com/svg?repo=soybeanjs/soybean-admin&chart=list&latestMonth=12" target="_blank" alt="Contribution Leaderboard" style="display: block; width: 100%;" />
</a>

## 交流

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

<div>
  <p>飞书群</p>
  <img src="https://img.soybeanjs.dev/soybean-admin-feishu.png?v=202610092025" style="width:200px" />
</div>

## Star 趋势

[](https://star-history.dera.page/#soybeanjs/soybean-admin&Date)

## 开源协议

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

---

### V3 (`docs/v3.md`)

# soybean-admin v3.0 实现方案

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

---

## 1. 背景与目标

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

1. **整体技术栈升级为全栈框架**：以 [ubean](https://github.com/soybeanjs/ubean)（v0.4.1，Vue 全栈框架，Hono 内核）为基座，构建工具链切换为 vite-plus（`vp`），UI 层切换为 [VeanUI](https://veanui.com)（`@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` 客户端内核 + 自定义后端，任意语言后端可接入）。

### 非目标

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

---

## 2. 技术选型总览

| 层              | v2.x 现状                                                         | v3.0 选型                                                                                                                                                              | 选型依据                                                                                               |
| --------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 应用框架        | 纯前端 SPA（Vite 手工装配）                                       | **ubean 0.4.x**（`mode: 'fullstack'`, `ssr: false`）                                                                                                                   | README 明确 admin panel 是 fullstack 模式的典型用例；client+server 双构建、无 SSR 开销                 |
| 构建/工程工具链 | Vite + ESLint + Prettier + Turbo（无）+ 手写脚本                  | **vite-plus（`vp`）**：dev/build/test/lint/fmt/pack 一体；catalog 中 `vite: npm:@voidzero-dev/vite-plus-core`                                                          | ubean 深度绑定 vite-plus；soybean-unify 已验证该工作区编排（`vp check --fix` staged、oxlint/oxfmt）    |
| 路由            | elegant-router 插件生成 + 手写守卫                                | **ubean 文件式页面路由**（`src/pages/**` + `definePage` 宏 + `.ubean/routes.d.ts` 类型化路径），守卫注入 `defineApp({ router: { setup } })`                            | 与 elegant-router 同族的文件约定，且额外获得动态段 matcher、keep-alive、复用路由、并行/拦截路由        |
| 状态管理        | Pinia + `@sa/*` 私有包                                            | **Pinia**（经 `@ubean/integrations/pinia`，`pinia: true`）                                                                                                             | 框架不内置 store；unify 验证 6 个 store 足够                                                           |
| UI 组件         | Naive UI（架构级耦合：NConfigProvider/四大 Provider/TableColumn） | **SoybeanUI 0.30+**（`@vean/ui` styled + `@vean/aria`）+ `@vean/theme` + `@vean/unocss`                                                                                | `SAppShell` 一个组件承接 v2 全部 6 种布局模式与菜单形态（见 §5.2）；ubean `ui: true` 自动接 UiResolver |
| HTTP 客户端     | `@sa/axios`（axios 内核 flat request）                            | **`@soybeanjs/fetch`**（`createRequest`/`toFlatRequest` + `/openapi` 子路径 `createTypedClient`/`toFlatTypedClient`，含 `createUploadProgressAdapter`/`downloadFile`） | ubean 官方指定客户端（`examples/ubean-test/src/request/client.ts` 即此用法）；fetch 内核免 axios 依赖  |
| 工程 CLI        | `@sa/scripts`（`sa git-commit`/`release`/`changelog`/`cleanup`）  | **`@soybeanjs/cli`**（1.8.x，bin `soy`：`git-commit`/`git-commit-verify`/`changelog`/`release`/`cleanup`/`ncu`/`config`）                                              | 官方维护通用 CLI，能力覆盖 `@sa/scripts`；`gen-route` 由文件式路由天然替代                             |
| 后端            | Apifox 在线 mock（无真实服务）                                    | **ubean 后端**：`src/routes/api/**` 文件路由（Hono handler 链）+ valibot 校验 + `@ubean/server` 原语（db/cache/session…）                                              | unify 的 server（Hono + Drizzle + RBAC）即为该形态的手写版，ubean 将其框架化                           |
| 数据层          | 无                                                                | **Drizzle ORM + db0 connector**（dev 默认 SQLite/内存，prod 可切 Postgres）+ drizzle 迁移                                                                              | `defineDatabase`/`useDatabase` 原语；unify 的 13 表 schema 可直接移植                                  |
| 鉴权            | mock 假登录 + 前端 roles 过滤                                     | **JWT 双 token + Redis/内存黑名单**（unify 方案）或 `@ubean/auth`（Better Auth）；RBAC 权限码 `api:${method}:${template}`                                              | 见 §6.4；`@ubean/auth` 成熟度待观察，首版建议沿用 unify 自研 JWT 方案以可控                            |
| 类型共享        | 手写 `typings/api/*.d.ts`                                         | **单一契约源**：`src/schema/`（Valibot，前后端源码直消费）+ OpenAPI codegen（`.ubean/openapi.d.ts`）→ `toFlatTypedClient<paths>`                                       | Hono 路由 → `/_openapi.json` → openapi-typescript 闭环，ubean 内置；应用单包化后 schema 无需独立包     |
| 主题            | naive themeOverrides + 4 个 JSON 预设                             | **`@vean/theme`**（`createTheme` CSS 变量引擎）+ `SConfigProvider`/`SThemeCustomizer`                                                                                  | shadcn 风格全量语义 token，light/dark 双份，`SThemeCustomizer` 即现成主题抽屉                          |
| i18n            | vue-i18n 手工装配                                                 | **`@ubean/i18n`**（vue-i18n 11 + 约束前缀语言路由 + `src/locales/` 扫描）                                                                                              | 配置化（`i18n: { locales, defaultLocale }`），`.ubean/i18n.d.ts` 类型生成                              |
| 图标            | iconify + unplugin-icons + svg-icons 三套                         | **`@ubean/icon`**（`icon: true`，Iconify）+ `SIcon`（`IconValue`）+ 本地 svg 约定                                                                                      | soybean-ui 数据模型（menu/table 的 `icon` 字段）直接吃 iconify 字符串                                  |

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

---

## 3. 仓库与工程结构

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

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）

|          | `main`（全栈版，默认）                                                | `lite`（前端版，新分支）                                                                                                                                                                                                        |
| -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 框架入口 | `ubean`（`ubean/client`、`ubean/server` 全量）                        | 仅 `@ubean/vue` + `@ubean/client`（或纯 `@ubean/vue` 内核，参照 `examples/client-only-spa`）                                                                                                                                    |
| 后端     | `src/routes/api/**` + `@ubean/server` 原语 + Drizzle                  | **无后端代码**；`src/request/` 指向用户自备 API（任意语言），契约用 OpenAPI 文档 + `openapi-typescript` 手工生成                                                                                                                |
| 构建     | `ubean dev/build`（client+server 双构建）                             | `vp build`（纯 Vite SPA），`vite.config.ts` 用 `ubeanVueVite()`                                                                                                                                                                 |
| 路由     | 文件式 `src/pages` + virtual routes                                   | 同样文件式（`@ubean/vue` 是多目录页面路由唯一所有者），无 loader/SSR 数据层                                                                                                                                                     |
| 鉴权     | JWT 双 token + RBAC 中间件                                            | 前端流程保留（登录页/守卫/token 存储/权限过滤），接口路径与响应码 env 可配                                                                                                                                                      |
| mock     | 不需要（真后端）                                                      | 可选保留轻量本地 mock（`routeRules.proxy` 或 MSW），默认提供 unify 风格 `docs/api-contract.md` 接口契约说明                                                                                                                     |
| 共享代码 | `src/schema`、`src/store`、`src/layouts`、`src/components` 等绝大部分 | 与 main 尽量保持目录与代码一致，差异集中在：`ubean.config.ts`、`vite.config.ts`、`src/routes/`+`src/services/`+`src/db/`（删除）、`src/server.ts`（删除）、`src/request/`（改 baseURL 来源）、`src/schema/`（保留但仅前端消费） |

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

---

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

### 4.1 布局与导航

| v2.x 能力                                                                                                                                | v2.x 实现                                | v3.0 实现                                                                                                                                                                                                                                                                                                                                                         | 状态                          |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| 6 种布局模式（vertical / horizontal / vertical-mix / vertical-hybrid-header-first / top-hybrid-sidebar-first / top-hybrid-header-first） | 自研 AdminLayout + 6 套 global-menu 组件 | **`SAppShell` 单组件 6 模式**：`mode = 'sidebar' \| 'top' \| SplitNavMode`，其中 SplitNavMode 4 种（dual-vertical / vertical-horizontal / horizontal-vertical / horizontal-dual-vertical）；模式名描述**菜单形态**而非方向——一级垂直即全高侧栏（orientation 派生为 `horizontal`），一级水平即顶栏；`items` 一棵菜单树供全部渲染器消费；侧栏宽度由实际渲染面板推导 | ✅ 组件化承接（见 §5.2）      |
| 侧栏菜单树（first/menu 混合树、折叠记忆、手风琴）                                                                                        | 自研 global-menu + menu store 派生       | 侧栏类模式渲染 `STreeMenu`、拆分类渲染 `SSplitNav` 子面板；`expandStrategy: 'selected' \| 'keep'` 控制折叠后展开策略；`collapsible: 'offcanvas' \| 'icon'`/`collapsedWidth`/`--sidebar-*` 经 `layoutProps` 透传内部 `SLayout`                                                                                                                                     | ✅ 组件化承接                 |
| 面包屑（菜单派生、下拉切换兄弟菜单）                                                                                                     | 自研 breadcrumb store                    | `SBreadcrumb` 默认由 `items` + 激活值**自动派生**，传 `breadcrumbs` 才覆盖；下拉切换兄弟菜单经 `breadcrumbProps` 下沉（⚠️ 需应用层包装，原 store 下拉逻辑迁移）                                                                                                                                                                                                   | ✅ 派生内化，下拉需包装       |
| 头部（品牌 logo/标题、折叠触发、明暗切换、用户区）                                                                                       | global-header + 手摆插槽                 | `#header` 系插槽 + `headerStart/headerCenter/headerEnd`；触发按钮跟随一级菜单位置（shell 统一安排）；品牌经 `#logo`/`#title` + `logoPlacement`；明暗 = `SThemeModeSwitch`                                                                                                                                                                                         | ✅ 组件化承接                 |
| 移动端抽屉（<768px 全量菜单）                                                                                                            | 自研 MobileDrawer                        | 恒以 `sidebar` 骨架渲染**全量菜单树抽屉**，`v-model:mobileOpen` 受控；备份恢复保留在 app store                                                                                                                                                                                                                                                                    | ✅ 组件化承接                 |
| 主题配置抽屉（外观/布局/通用/操作 4 Tab，约 40 项配置）                                                                                  | 自研 theme-drawer                        | **`SThemeCustomizer`** 内置面板 + 应用层补充 admin 专属项（布局模式卡片、页签风格、水印、搜索开关等），配置模型 = theme store → `layoutProps` 一层映射（unify 范式）                                                                                                                                                                                              | ✅ 大部分内置，admin 项需扩展 |
| 页签：3 风格（chrome/button/slider）、拖拽排序、右键菜单、中键关闭、固定、缓存、自定义标题、多标签                                       | 自研 GlobalTab + @better-scroll          | **`SAppShell` 内置页签**（底层 `SPageTabs`，经 `tabs`/`v-model:tabValue`/`tabProps`/`tabUi` 喂入）：beforeClose、中键关闭、pin 自动排序、draggable、contextMenu 全内置；多标签（query 区分）、页签缓存、setTabLabel 在 tab store 承接                                                                                                                             | ✅ 组件化承接                 |
| 水印（文本/用户名/实时时间 7 格式）                                                                                                      | NWatermark                               | **`SWatermark`**（`@vean/aria` 已有 watermark 原语）+ watermarkContent 派生逻辑保留                                                                                                                                                                                                                                                                               | ✅                            |
| 全局搜索（菜单模糊搜索、键盘导航、高亮）                                                                                                 | 自研 search-modal                        | **`SCommand`**（命令面板原语）+ 菜单索引；`routeRules` 无关，纯前端                                                                                                                                                                                                                                                                                               | ✅ 组件化重写                 |
| 页面切换动画 7 种                                                                                                                        | transition.css                           | `SAppShell`（经 `layoutProps` 转发内部 `SLayout`）页面过渡 props + `@ubean/vue` 页面过渡能力 + view transitions                                                                                                                                                                                                                                                   | ✅                            |
| 滚动模式 wrapper/content、固定头部/页签/底部                                                                                             | AdminLayout props                        | 内部 `SLayout`（经 `SAppShell` `layoutProps` 透传）`scrollBehavior`/`fixedTop`/`fixedFooter` 原生                                                                                                                                                                                                                                                                 | ✅                            |
| Footer（显隐/固定/高度/居右）                                                                                                            | global-footer                            | `SAppShell` `#footer` 插槽 + 内部 `SLayout` Footer（visible/height 经 layoutProps）                                                                                                                                                                                                                                                                               | ✅                            |
| 灰色/色弱模式                                                                                                                            | documentElement filter                   | 应用层保留（css filter），theme store 驱动                                                                                                                                                                                                                                                                                                                        | ✅ 保留                       |
| 全屏内容切换                                                                                                                             | app store fullContent                    | 内部 `SLayout` `fullContent` prop（经 `SAppShell` `layoutProps`）                                                                                                                                                                                                                                                                                                 | ✅                            |

### 4.2 路由与权限

| v2.x 能力                                            | v3.0 实现                                                                                                                                                                                                                | 状态                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| elegant-router 自动生成 + `RouteKey`/`RouteMap` 类型 | `.ubean/routes.d.ts` + `typed-router.d.ts`（`useRoute('RouteName')` 参数推断）+ 动态段 matcher（`[id=numeric].vue`）                                                                                                     | ✅ 等价且更强（matcher 校验、复用路由、拦截路由） |
| 静态/动态双权限模式（`VITE_AUTH_ROUTE_MODE`）        | 保留双模式：static = 本地菜单数据 + roles 过滤；dynamic = `GET /api/menu/user` 返回菜单树 → `transformMenusToAutoRoutes`（unify 范式，菜单驱动路由/页签/标题一元模型）                                                   | ✅                                                |
| 路由守卫链（progress → route → title）               | `defineApp({ router: { setup } })` 注册 beforeEach：auth 守卫 + 首屏 loading + 进度条（soybean-ui `progress`）；标题由菜单 `i18nKey` 驱动                                                                                | ✅ 注入点变化，逻辑保留                           |
| 15 项 meta 字段                                      | `definePage({ meta })`：requiresAuth/roles/keepAlive/multiTab/pinned/tabbable/href/activeMenu/order/icon/hideInMenu/query/isDev 全部保留；title/i18nKey 改由菜单数据承载（unify 简化），纯静态路由提供 `routeTitle` 兜底 | ✅（title 语义迁移，见 §5.3 说明）                |
| 按钮级权限（userInfo.buttons + hasAuth + 演示页）    | `useAuth().hasAuth(code)` + **`v-auth` 指令**（v2 无指令、v3 补上）+ 角色管理分配按钮权限弹窗                                                                                                                            | ✅ 增强                                           |
| 403/404 判定（路径存在但无权限 → 403）               | 保留：NotFound 捕获时 `checkIsRouteExist`（static 查表 / dynamic `POST /api/menu/exist-path`）                                                                                                                           | ✅                                                |
| keep-alive 按 meta 收集 + exclude 精确重置           | `@ubean/vue` 页面缓存（`useCacheViews`/`enablePageCache`/`invalidatePageCache`）+ route store cachedRoutes                                                                                                               | ✅                                                |
| iframe 外链页、`href` 外链新窗口                     | `(builtin)/iframe/[url].vue` 保留；meta.href 行为保留                                                                                                                                                                    | ✅                                                |
| root redirect = 动态 home                            | 菜单接口返回 home → 改写 ROOT redirect（unify 同款）                                                                                                                                                                     | ✅                                                |

### 4.3 请求与后端

| v2.x 能力                                                 | v3.0 实现                                                                                                      | 状态                             |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| flat request（`{data,error}` 免 try/catch）               | `toFlatRequest`（`@soybeanjs/fetch`）                                                                          | ✅                               |
| Bearer 注入、响应解包、业务码判定                         | onRequest/transform/isBackendSuccess 约 80 行范式（unify）                                                     | ✅                               |
| token 过期刷新 + 并发去重 + 原请求重放                    | **v2 有、unify 缺**——v3 必须接线：401/过期码 → `refreshTokenPromise` 去重 → 重放队列（保留 v2 shared.ts 逻辑） | ✅ 保留（吸取 unify 未完成教训） |
| LOGOUT_CODES / MODAL_LOGOUT_CODES 弹窗登出                | env 可配 + `SDialog`/`useToast` 实现                                                                           | ✅                               |
| 错误消息去重栈                                            | errMsgStack 逻辑保留                                                                                           | ✅                               |
| 多 baseURL（demoRequest / `VITE_OTHER_SERVICE_BASE_URL`） | `routeRules.proxy`（`/_p/{key}` 前缀代理）+ 多 client 实例                                                     | ✅                               |
| dev 代理 + 终端彩色日志                                   | vite-plus proxy / routeRules proxy；日志用 `@ubean/server` logger                                              | ✅                               |
| 版本更新检测（轮询 buildTime meta）                       | 保留（prod 特性开关 `VITE_AUTOMATICALLY_DETECT_UPDATE`）；或改 `/_health` 版本端点                             | ✅                               |
| Apifox mock                                               | **删除**，由真实后端 + seed 数据替代；lite 分支提供接口契约文档 + 可选 MSW                                     | 🔄 架构替换                      |
| 手写 `service/api/*.ts` + `typings/api/*.d.ts`            | **删除**，`createTypedClient<paths, '/api'>` 直接按路径调用；服务端进程内 `createInternalAdapter` 零网络复用   | ✅ 简化                          |

### 4.4 状态管理

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

| store                       | v3.0 职责变化                                                                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| app                         | 不变：isMobile、reloadSignal、fullContent、drawer 开关、移动端布局备份恢复                                                                         |
| auth                        | 接真实登录接口；跨用户切换清页签、lastLoginUserId 保留                                                                                             |
| theme                       | settings → `ThemeOptions`（`@vean/theme`）+ `layoutProps` 派生；naive themeOverrides 生成逻辑删除；生产缓存 + `overrideThemeSettings` 版本覆盖保留 |
| route                       | 动态路由注册（`addRoute` 仍可用，vue-router 5 实例由框架创建）+ cacheRoutes                                                                        |
| tab                         | 不变（对接 `SAppShell` 内置页签：`tabs` + `v-model:tabValue`，事件 `tabClick`/`tabClose` 回写 store）                                              |
| menu（新增，自 route 拆分） | 菜单树 + map + 面包屑 + routeMenu；监听语言变化重建（unify 范式）                                                                                  |

### 4.5 i18n / 主题 / 图标

| v2.x                                            | v3.0                                                                                                                   |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| vue-i18n 手工装配、zh-cn/en-us 两套 Schema 类型 | `@ubean/i18n` 配置化 + `.ubean/i18n.d.ts` 类型生成；`src/locales/` JSON 组织；保留 `remove-i18n` 一键裁剪脚本（unify） |
| naive locale/dateLocale 联动                    | `SConfigProvider` locale + `@vean/aria/locale`（13 语言包）；dayjs locale 联动保留                                     |
| 语言切换联动 title/menu/tab/dayjs               | 全部保留（menu store + tab store 监听）                                                                                |
| 4 个主题预设 JSON（default/dark/compact/azir）  | `@soybeanjs/shadcn-theme` 内置预设 + 自定义 preset/overrides；`VITE_THEME_PRESET` env 选择                             |
| iconify 离线 provider + 本地 svg 双模           | `icon: true`（`@ubean/icon`）+ 本地 svg collection 约定保留；`SIcon` 的 `IconValue` 统一数据模型                       |

### 4.6 页面功能对齐清单

| v2.x 页面                                                                                                                   | v3.0 处理                                                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 登录（pwd/验证码/注册/重置密码/绑定微信 5 模块）                                                                            | 全部实现；后端真实签发 token；图形验证码用 `@ubean/server` cache 存储答案                                                                                          |
| 首页 dashboard（问候横幅/4 统计卡/折线/饼图/项目动态）                                                                      | 全部实现；图表用 `@soybeanjs/chart` + echarts（`useEcharts` hook 保留）；CountTo 用 `useTransition`                                                                |
| manage：用户/角色/菜单/按钮权限管理（example）                                                                              | 升级为 unify 的 8 套 CRUD：menu/user/role/permission/org/api/dict/dict-item，统一"搜索卡 + 分页表格 + operate 弹窗"范式（`usePaginatedTable` + `useTableOperate`） |
| function：标签页/多标签/请求演示/切换权限/隐藏子菜单/超管页                                                                 | 全部保留，请求演示对接真实错误码端点 `POST /api/auth/error`                                                                                                        |
| multi-menu 三级嵌套                                                                                                         | 保留（文件目录天然表达）                                                                                                                                           |
| plugin：copy/icon/echarts/antv/vchart/wangEditor/vditor/excel/pdf/print/barcode/pinyin/video/map/swiper/typeit/vtable/gantt | 全部保留为第三方集成示例页；依赖清单见 §5.8                                                                                                                        |
| about（依赖版本表/构建时间/技术栈卡片）                                                                                     | 保留；版本表改读 catalog                                                                                                                                           |
| user-center 占位                                                                                                            | 升级为完整 profile + settings 页（unify 占位教训，v3 补齐）                                                                                                        |
| 403/404/500                                                                                                                 | 保留（`exception-base` → soybean-ui `SEmpty` + 本地 svg）                                                                                                          |
| alova 示例 / pro-naive-ui 示例                                                                                              | **不迁移**（alova 与框架请求层重复；pro-naive-ui 属 naive 生态）                                                                                                   |

### 4.7 工程能力

| v2.x                                       | v3.0                                                                                                                                                                                          |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ESLint + oxlint + oxfmt + simple-git-hooks | `vp lint` / `vp fmt`（oxc 系）+ `vp check --fix` staged；共享 `@soybeanjs/oxc-config`                                                                                                         |
| `sa git-commit` 交互式提交（@sa/scripts）  | **`soy git-commit`**（`@soybeanjs/cli`，devDependency 引入），commit-msg 钩子换 `soy git-commit-verify`；`soy release`/`soy changelog`/`soy cleanup`/`soy ncu` 覆盖 v2 `@sa/scripts` 全部能力 |
| vue-tsc typecheck                          | 保留（ubean `prepare` 生成 `.ubean/` 类型后跑 vue-tsc）                                                                                                                                       |
| bundle 体积无约束                          | 引入 ubean `pnpm analyze` 基线回归（gzip 增长 >5% CI 失败）                                                                                                                                   |
| GitHub Actions lint/release                | 保留；release 走 `soy release`（内部 bumpp + @soybeanjs/changelog）                                                                                                                           |
| env 约 25 个变量                           | 精简至约 15 个（见 §5.10）：删除 naive 专属、mock 专属；新增 `VITE_API_ENV`/`VITE_API_PROXY`/`VITE_THEME_PRESET`                                                                              |

---

## 5. 前端详细设计

### 5.1 应用入口与生命周期

```ts
// 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）

```vue
<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 映射表：

| v2 layout.mode               | SAppShell `mode`           | 渲染器                  |
| ---------------------------- | -------------------------- | ----------------------- |
| vertical                     | `sidebar`                  | `STreeMenu`（单栏）     |
| vertical-mix                 | `dual-vertical`            | `SSplitNav`（双栏）     |
| horizontal                   | `top`                      | `STreeNav`（横排）      |
| top-hybrid-sidebar-first     | `vertical-horizontal`      | `SSplitNav`（侧栏优先） |
| top-hybrid-header-first      | `horizontal-vertical`      | `SSplitNav`（头部优先） |
| vertical-hybrid-header-first | `horizontal-dual-vertical` | `SSplitNav`（混合）     |

### 5.3 路由与菜单一元模型

- 页面即文件：`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 请求层

```ts
// 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 鉴权流程

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 主题系统

- 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 范式

`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 第三方集成页依赖

保留 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 必须保留的"隐形能力"清单（回归测试用例来源）

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

### 5.10 env 变量精简

```
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 分支）

### 6.1 分层

```
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 数据库与驱动

- 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）

| 模块                                      | 端点                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| auth                                      | `POST /login`（pwd/captcha 双类型）、`POST /register`、`POST /token/refresh`、`POST /logout`、`GET /user-info`、`POST /error`（演示码）、`GET /captcha` |
| menu                                      | `GET /public`、`GET /user`、`POST /exist-path`、CRUD + tree                                                                                             |
| role                                      | CRUD + `GET /user`（角色码）+ 菜单/按钮权限分配                                                                                                         |
| user                                      | CRUD + 状态 + 分配角色                                                                                                                                  |
| permission / api / org / dict / dict-item | CRUD（unify 8 套范式）                                                                                                                                  |

### 6.4 鉴权方案取舍

- **首版**：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 差异化价值）

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

---

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

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

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 适配器在独立仓库开发，不进本仓库

- 独立仓库（建议命名 `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 当前缺口与对策

| 缺口（docs/roadmap P0/P1）                                                                        | v3 对策                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Upload                                                                                            | 优先自建（`@vean/aria` 无该原语）：文件列表 + 拖拽 + 进度，样式用 S\* 拼装，上传走 `@soybeanjs/fetch` 的 `createUploadProgressAdapter`；若直接用目标库 Upload，则由 §7.2 适配器对齐样式 |
| Descriptions / TreeSelect / Transfer / Timeline / Statistic / Result / Typography / Image / Space | 应用层小组件先行（`components/custom/`），同步向 soybean-ui 提 issue/PR，成熟后替换                                                                                                     |
| 表格虚拟滚动已有（virtualizer）；图表仅 4 件                                                      | dashboard 图表继续用 echarts + `@soybeanjs/chart` container                                                                                                                             |

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

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）

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

```ts
// 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>/<PageView>`。
- 移除：`src/routes/`、`src/server.ts`、`ubean.config.ts`、loader/usePage 数据层、`@ubean/i18n`（改手工 vue-i18n 装配，与 v2 一致）、SSR 相关一切。
- 请求层：`toFlatTypedClient<paths>` 的 `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. 实施路线图

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

- 单包工程重建：根目录平铺（`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 — 后端内核

- 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 — 前端架子

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

### Phase 3 — 业务页面

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

### Phase 4 — 插件演示与增值

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

### Phase 5 — 适配对接与发布

- 与独立适配器仓库（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

### 分支与版本计划

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

---

## 10. 风险与对策

| 风险                                                      | 等级 | 对策                                                                                                                                                    |
| --------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ubean 0.4.x API 破坏性变更（0.3→0.4 刚重构入口）          | 高   | lock 精确版本；封装 `src/shared/ubean-compat.ts` 隔离高频 API；每升级一个 ubean minor 跑全量 e2e；v3.0 stable 前不追新                                  |
| ubean "声明宽于默认"（DB/queue 默认内存实现）             | 高   | 首版后端只依赖已验证子集（Hono 路由/中间件/cache/db0 显式接线）；生产部署文档强制 connector 配置检查                                                    |
| soybean-ui 缺口组件（Upload/Descriptions 等 22 个 P0/P1） | 中   | §7.3 清单化；缺口组件应用层先行 + 向 ui 仓库提 PR 双向收敛                                                                                              |
| `SAppShell` API 尚在 beta（0.50.0-beta.9）                | 中   | 架子 API 以 `SAppShell` 命名为目标设计；beta 期 API 调整通过 §5.2 一层映射隔离，应用层不直接触 props                                                    |
| vite-plus 工具链（oxlint/oxfmt）团队与社区接受度          | 中   | 保留 eslint 兼容配置导出；CI 双跑一个 Phase 后收敛                                                                                                      |
| `SAppShell` 模式组合盲区（6 mode × 配置项）               | 中   | Phase 2 第一周产出"模式 × 配置项"矩阵 PoC（模式名=菜单形态、orientation 派生已消除大半组合面），盲区项降级为 5 模式或 `layoutProps` 透传 `SLayout` 兜底 |
| lite/main 双分支漂移                                      | 中   | 差异文件清单 CI 校验；每季度 main→lite 单向同步                                                                                                         |
| 功能回归遗漏（隐形能力）                                  | 中   | §5.9 清单转 e2e 用例（Playwright，ubean vitest 5 浏览器模式）                                                                                           |
| 与 v2 用户迁移断层                                        | 低   | 第三方组件样式适配器（独立仓库）+ 迁移指南 + 字段映射表（§7.4）                                                                                         |

---

## 11. 附录

### 11.1 关键参考路径

- 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 术语

- **一元数据模型**：菜单记录 = 导航条目 + 路由定义 + 页签标题来源（`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