soybean-admin

name

soybean-admin

description

在基于 soybean-admin-element-plus 的 Vue 3 + Element Plus 后台项目中，按现有布局、主题、列表页、搜索区和抽屉表单范式创建或修改 CRUD 页面。适用于识别到 `@sa/materials`、`@sa/hooks`、`src/hooks/common/table.ts`、`src/layouts/base-layout` 等项目特征，或用户明确要求“按 soybean 风格”“参考项目现有模式”“用标准后台列表页方式实现”时，用于构建、重构、扩展或标准化管理列表页、搜索表单、新增/编辑抽屉、表格操作和相关视图模块。若在其他 Vue 3 + Element Plus 项目中复用这套模式，遇到缺失的 hooks、共享组件、TSX、国际化或 UnoCSS / presetIcons 等工程能力时，应先补齐依赖或补建等价基础设施，再实现业务页面，不要直接降级成另一套页面方案。

Soybean Admin

概述

用这个 skill 在 soybean-admin-element-plus 项目中新增或改造后台页面时，优先复用现有的布局、主题、表格、搜索区、抽屉表单和表格操作 hooks，而不是重新发明一套页面组织方式。

目标不是复制整个项目，而是让代理稳定产出“看起来就是这个项目原生代码”的页面。

如果这套 skill 被用于其他 Vue 3 + Element Plus 项目，默认策略不是“因为缺依赖就简化实现”，而是先补齐支撑 Soybean 风格页面所需的依赖和基础设施，再继续实现。

触发条件

满足以下任一条件时，应优先启用此 skill：

项目特征识别

• package.json 或 workspace 中存在 @sa/materials、@sa/hooks、@sa/axios
• 项目采用 Vue 3 + Element Plus + UnoCSS
• 存在 src/hooks/common/table.ts、src/hooks/common/form.ts
• 存在 src/layouts/base-layout、src/layouts/modules/global-content

任务类型

• 创建新的标准后台 CRUD 页面
• 在已有列表页上增加筛选项、列、操作按钮或表单字段
• 将非标准页面改造成项目统一风格
• 抽取新的实体页面骨架供后续复用
• 修正不符合项目约定的列表页、搜索区或抽屉表单实现

用户显式要求

• “按 soybean 的风格写”
• “参考项目现有页面结构”
• “用标准列表页模式实现”
• “按后台管理页统一规范整理一下”

工作流程

1. 先确认任务属于哪一类：
   • 新增标准后台 CRUD 页面
   • 扩展已有列表页
   • 改造非标准页面
   • 抽象页面骨架
2. 如果目标项目不是原始 soybean 项目，先做依赖探测：
   • 是否已有 src/hooks/common/table.ts、src/hooks/common/form.ts
   • 是否已有 TableHeaderOperation 之类的共享列表操作组件
   • 是否支持 lang="tsx" 或 JSX formatter
   • 是否已有 $t() 对应的国际化能力
   • 是否已有 UnoCSS、presetIcons 与 @iconify-json/ic 等图标原子类能力
3. 缺少强依赖时，按以下顺序处理：
   • 第一步：读取 references/dependency-bootstrap.md 了解依赖分级策略（一类：页面结构强依赖，二类：工程表达强依赖）
   • 第二步：如果是工程能力缺失（TSX/国际化/UnoCSS/presetIcons），继续读取 references/engineering-capability-bootstrap.md 了解如何补齐这几类工程能力
   • 第三步：如果是首次在新项目导入这套模式，继续读取 references/cross-project-adoption-playbook.md 了解完整的 10 步落地流程
   • 第四步：如果需要真实案例参考，继续读取 references/user-manage-migration-case.md 查看 UserManage 页面的完整迁移过程
   • 第五步：补齐依赖后，再创建业务页面
4. 按需读取参考文档，避免无差别全量加载：
   • 先读 references/layout-and-theme.md
   • 再读 references/hooks-and-conventions.md
   • 如果是标准 CRUD 页面，再读 references/crud-page-pattern.md
   • 需要搜索区时读 references/search-form-pattern.md
   • 需要新增/编辑抽屉时读 references/drawer-form-pattern.md
5. 需要快速起页时，优先使用 assets/ 下的模板。
6. 按业务替换模板占位符、类型、API、国际化 key 和表单字段。
7. 生成代码后，至少完成与本次改动直接相关的定向验证，不要只写代码不验证。

模板占位符

使用 assets/ 中的模板时，优先替换以下占位符：

占位符	示例值	说明	使用场景
{{EntityName}}	User	实体名称，大驼峰	组件名、类型名
{{entity-name}}	user-manage	实体名称，短横线形式	文件名、路由路径
{{entity}}	user	实体名称，小写形式	变量名、函数名
{{Namespace}}	SystemManage	API 命名空间	服务层类型、接口分组
{{scope}}	manage	国际化作用域	locale key 前缀
{{primaryField}}	userName	页面主展示字段	搜索项、表格核心列、表单主要字段
{{idField}}	id	实体主键字段	row-key、编辑/删除、批量操作唯一标识

替换示例：

假设要创建"用户管理"页面：

// 替换前
import { fetch{{EntityName}}List } from '@/service/api';
const { columns } = useUIPaginatedTable<Api.{{Namespace}}.{{EntityName}}>({...});

// 替换后
import { fetchUserList } from '@/service/api';
const { columns } = useUIPaginatedTable<Api.SystemManage.User>({...});

注意事项：

• 替换时只替换业务相关内容，不要破坏模板里的容器结构、分页位置、按钮组织和标准交互流
• 不要只替换组件名，漏掉 locale key、类型名和接口名
• 确保所有占位符都被替换，避免遗漏导致编译错误

跨项目复用与依赖补齐

如果在其他项目里复用这套模式，优先按下面的顺序补件：

1. 先补 hooks：
   • 缺少 useUIPaginatedTable、useTableOperate、defaultTransform 时，先补 table 相关 hooks
   • 缺少 useForm、useFormRules 时，先补 form 相关 hooks
2. 再补共享组件：
   • 缺少 TableHeaderOperation 时，先创建本地公共组件
3. 再补工程能力：
   • 如果列表页使用 lang="tsx" 和 JSX formatter，先补 TSX / JSX 支持
   • 如果模板走 $t()，先补国际化能力与 locale key
   • 如果样式依赖 UnoCSS 原子类，先补 UnoCSS 或明确建立等价的原子类体系
   • 如果搜索区依赖 i-ic-round-* 图标类，先补 presetIcons + @iconify-json/ic
4. 只有在用户明确接受差异化实现时，才允许偏离上述依赖补齐策略。

工程能力的详细补齐步骤，优先参考 references/engineering-capability-bootstrap.md。

工作规则

1. 保持项目原有视觉语言

• 不要擅自替换主题系统
• 不要把列表页改造成完全不同的信息架构
• 不要在没有明确需求时引入新的状态管理或 UI 封装层

2. 优先复用现有 hooks

• 表格分页优先使用 useUIPaginatedTable
• 列表页新增/编辑切换优先使用 useTableOperate
• 表单校验优先使用 useForm 和 useFormRules
• 只有当现有 hooks 明显不适配时，才新增局部扩展

3. 优先延续现有页面拆分方式

• 页面入口文件负责组织数据流和组合模块
• 搜索区、弹层表单、特殊弹窗放到 modules/
• 复杂页面的辅助类型或共享常量优先放在同级 modules/shared.ts 或贴近业务的局部文件中

4. 优先使用抽屉表单

• 标准后台管理页的新增/编辑交互以 ElDrawer + ElForm 为主
• 只有用户明确要求“新增页”“详情页”“分步表单页”时才偏离这一模式

5. 模板替换时只替换业务相关内容

• 替换 API 名称、类型名、字段名、文案 key、列定义、表单项
• 保留容器结构、按钮布局、分页位置、批量操作入口和成功提示语义

6. 保持项目编码风格

• 所有界面文本优先走 $t()
• 优先使用 UnoCSS 原子类，而不是新增大量局部样式
• 表格复杂列优先使用 JSX formatter
• 危险操作优先使用 ElPopconfirm
• 生成代码时补充必要的中文注释，但不要写低信息量注释
• 涉及文章正文、公告正文、帮助中心等富文本场景时，优先复用项目内已存在的成熟编辑器依赖或封装，不要回退到 contenteditable + execCommand 这类临时实现
• 富文本编辑器如果放在 ElCard 里且会弹出浮层、下拉、工具面板或插入菜单，优先给承载它的 ElCard 加 body-class="overflow-visible"，不要误以为这个属性应该加在编辑器组件自身

7. 遇到强依赖先补齐，不直接降级

• 缺少 hooks 时，优先补本地 hooks 文件，而不是把重复状态逻辑散落到每个页面
• 缺少共享组件时，优先补公共组件，而不是每个页面手写一套按钮区
• 缺少 TSX、国际化、原子化样式能力时，优先补工程能力，再继续复用当前模板
• 只有用户明确同意改变实现路线时，才允许改成另一套更简化的页面组织方式

默认决策

在用户没有额外说明时，按以下默认值执行：

• 页面容器：延续现有 bg-layout、p-16px、gap-16px 的内容区节奏
• 列表外壳：搜索卡片 + 表格卡片
• 表格头部：标题在左，TableHeaderOperation 在右
• 操作列：编辑 在前，删除 在后；危险操作使用 ElPopconfirm
• 批量操作：通过 checkedRowKeys 和表头删除入口触发
• 新增/编辑：统一用抽屉
• 提交反馈：成功后使用 window.$message?.success(...)
• 列表刷新：提交、删除、批量删除成功后回到当前列表刷新

文件选择指南

根据任务类型，优先参考这些文件：

• 主题与布局：
  • src/theme/settings.ts
  • src/layouts/modules/global-content/index.vue
• 标准用户列表页：
  • src/views/manage/user/index.vue
  • src/views/manage/user/modules/user-search.vue
  • src/views/manage/user/modules/user-operate-drawer.vue
• 标准角色列表页：
  • src/views/manage/role/index.vue
  • src/views/manage/role/modules/role-search.vue
  • src/views/manage/role/modules/role-operate-drawer.vue
• 复杂一些的管理页：
  • src/views/manage/menu/index.vue
  • src/views/manage/menu/modules/menu-operate-modal.vue
• 通用 hooks：
  • src/hooks/common/table.ts
  • src/hooks/common/form.ts
• 跨项目补件参考：
  • references/dependency-bootstrap.md
  • references/engineering-capability-bootstrap.md
  • references/cross-project-adoption-playbook.md
  • references/user-manage-migration-case.md

模板文件

快速起页时优先使用这些模板：

• assets/list-page.vue.tpl
  • 列表页入口骨架
  • 包含搜索模块、表格模块、分页、抽屉调用和标准表格操作流
• assets/search-card.vue.tpl
  • 搜索卡片骨架
  • 适合实体筛选项较多的场景
• assets/operate-drawer.vue.tpl
  • 新增/编辑抽屉骨架
  • 包含标题切换、模型初始化、校验、提交和打开时的数据准备
• assets/table-support.ts.tpl
  • 在目标项目缺少表格 hooks 时，用来补齐 useUIPaginatedTable、useTableOperate、defaultTransform
• assets/form-support.ts.tpl
  • 在目标项目缺少表单 hooks 时，用来补齐 useForm、useFormRules
• assets/table-header-operation.vue.tpl
  • 在目标项目缺少标准表头操作组件时，创建本地公共组件的起点模板
• assets/request-client.ts.tpl
  • 在目标项目缺少统一请求层时，先补最小 request 方法
• assets/service-api-index.ts.tpl
  • 在目标项目缺少服务层统一出口时，先补 service/api/index.ts
• assets/option-utils.ts.tpl
  • 在目标项目缺少 translateOptions 时，先补选项翻译工具
• assets/business-constants.ts.tpl
  • 在目标项目缺少状态、性别等业务常量映射时，先补本地常量文件
• assets/i18n-setup.ts.tpl
  • 在目标项目缺少国际化能力时，先补基础 i18n 接入层
• assets/page-locale.zh-cn.ts.tpl
  • 页面级中文 locale 模板
• assets/page-locale.en-us.ts.tpl
  • 页面级英文 locale 模板
• assets/vite-vue-jsx.snippet.ts.tpl
  • 在目标项目缺少 TSX / JSX 能力时，补 Vite JSX 插件配置
  • 搜索区图标由 UnoCSS presetIcons + @iconify-json/ic 提供，不依赖额外 Vue 图标组件注册
• assets/uno-config.ts.tpl
  • 在目标项目缺少 UnoCSS 时，补最小 UnoCSS 配置
• assets/main-bootstrap.snippet.ts.tpl
  • 在目标项目入口文件里接入 i18n 和 uno.css
• assets/message-adapter.ts.tpl

输出检查清单

完成页面后，至少自行检查以下项目：

P0 级别（必须检查，影响功能）

1. ✅ 编译通过：最终代码里不存在无法解析的 import、组件或工程能力缺口
2. ✅ 表格可用：表格使用 row-key，批量选择功能可用
3. ✅ 抽屉可用：抽屉打开时能正确初始化新增或编辑数据
4. ✅ 刷新机制：提交、删除、批量删除后能刷新列表
5. ✅ 依赖补齐：如果目标项目原本缺少强依赖，已经先补齐 hooks、共享组件、TSX、国际化或样式能力

P1 级别（建议检查，影响代码质量）

6. 📋 布局一致：页面符合项目现有布局和间距节奏
7. 📋 结构一致：搜索区、表格区、分页区的位置和项目现有管理页一致
8. 📋 约定一致：表单校验、文案 key、类型引用和项目现有约定一致
9. 📋 注释合理：新增代码里包含必要的中文注释（不要写流水账式注释）
10. 📋 国际化优先：所有界面文本优先使用 $t() 国际化
11. 📋 原子类优先：优先使用 UnoCSS 原子类，而不是堆叠大量自定义样式
12. 📋 JSX 优先：复杂列渲染优先使用 JSX formatter

检查建议：

• P0 级别的检查项必须全部通过，否则页面无法正常使用
• P1 级别的检查项建议通过，但可以根据项目实际情况灵活调整
• 如果时间紧张，至少完成 P0 级别的检查

参考文档

详细规范放在 references/ 目录，按需读取，不要把 SKILL.md 和 references/ 的内容重复堆叠到生成结果里。

文档列表

文档名称	用途	何时阅读
layout-and-theme.md	布局与主题约束	需要了解页面布局规范时
hooks-and-conventions.md	hooks 与项目约定	需要使用或补齐 hooks 时
crud-page-pattern.md	标准 CRUD 页面模式	创建标准列表页时
search-form-pattern.md	搜索区模式	需要添加搜索功能时
drawer-form-pattern.md	抽屉表单模式	需要新增/编辑抽屉时
dependency-bootstrap.md	跨项目补件与依赖补齐策略	目标项目缺少依赖时（必读）
engineering-capability-bootstrap.md	TSX、国际化、UnoCSS 工程能力补齐指南	目标项目缺少工程能力时
cross-project-adoption-playbook.md	从纯 Vue 3 + Element Plus 项目落地到 Soybean CRUD 模式的顺序化演练手册	首次在新项目导入时（必读）
user-manage-migration-case.md	以 UserManage 为例的真实迁移案例	需要完整迁移案例参考时

推荐阅读顺序

场景 1：在原生 Soybean 项目中使用

1. layout-and-theme.md - 了解布局约束和主题系统
2. hooks-and-conventions.md - 了解 hooks 用法和项目约定
3. crud-page-pattern.md - 了解标准 CRUD 页面模式
4. search-form-pattern.md - 了解搜索区的组织方式（需要时）
5. drawer-form-pattern.md - 了解抽屉表单的实现模式（需要时）

场景 2：跨项目迁移（非 Soybean 项目）

1. dependency-bootstrap.md ⭐ - 了解依赖分级策略（必读）
2. engineering-capability-bootstrap.md ⭐ - 了解如何补齐 TSX/国际化/UnoCSS（必读）
3. cross-project-adoption-playbook.md ⭐ - 了解完整的 10 步落地流程（必读）
4. user-manage-migration-case.md - 通过真实案例理解迁移过程（强烈推荐）
5. 再回到"场景 1"的阅读顺序

注意：标记 ⭐ 的文档是跨项目迁移的核心文档，必须按顺序阅读。

使用限制

以下情况不要硬套这个 skill：

1. 页面是营销官网、着陆页或强视觉设计页。
2. 页面不是 CRUD 管理台，而是图表大屏、流程编排器、复杂画布编辑器。
3. 用户明确要求使用新的组件体系或完全不同的交互范式。
4. 目标项目并不具备这个模板的 hooks、目录结构和基础组件时，应先按 references/dependency-bootstrap.md 和 references/cross-project-adoption-playbook.md 补齐依赖，再使用模板代码。只有在用户明确拒绝补齐依赖时，才只能借鉴参考文档的设计思路，不能直接复制模板代码。