Scaffold Dev Guide

脚手架项目二次开发指南

项目概览

基于 Vue 3 + Vite + TypeScript 的中后台管理系统脚手架，面向二开场景。

核心技术栈: Vue 3.5, Ant Design Vue 4.2, Tailwind CSS, Shadcn-ui, Pinia, Vue Router, Vue Query (TanStack Query), VxeTable, i18n, Axios

应用入口: apps/admin/src/

Vben 框架核心机制

本项目基于 Vben Admin 配置型框架，通过配置而非编码来完成大部分开发工作。理解以下机制至关重要：

组件注册机制（不要绕过）

框架有 两套组件注册体系，分别用于不同场景：

1. VbenForm 组件（schema 中使用）

定义在 adapter/component/index.ts，通过 globalShareState.setComponents() 注册。在 schema 的 component 字段中 只能使用这些注册过的名称：

Input, InputNumber, InputPassword, Select, ApiSelect, TreeSelect,
ApiTreeSelect, RadioGroup, Checkbox, CheckboxGroup, Switch, DatePicker,
RangePicker, TimePicker, Textarea, Upload, Editor, IconPicker, AutoComplete,
Mentions, Rate, Divider, Space, DefaultButton, PrimaryButton, ApiTree

2. Template 全局组件（template 中使用）

定义在 registerGlobComp.ts，通过 app.use() 全局注册。在 template 中 直接用 a-* 前缀：

<a-button>, <a-tag>, <a-popconfirm>, <a-input>, <a-select>,
<a-tree>, <a-table>, <a-dropdown>, <a-menu>, <a-card>, <a-space>,
<a-switch>, <a-tabs>, <a-divider>, <a-layout>

禁止: import { Tag, Button } from 'ant-design-vue' 然后在 template 中用 <Tag> 或 <Button>。

配置驱动模式（不要自己写逻辑）

目录结构速查

apps/admin/src/
├── api/                  # API 层（两层架构）
│   ├── generated/        # ← protobuf 自动生成，禁止手动编辑
│   ├── client.ts         # ← ApiClient 单例（ClientTransport 适配器）
│   └── composables/      # ← Vue Query hooks 层：use*/fetch*/枚举工具
├── adapter/              # VbenForm + VxeTable 适配器配置
├── router/routes/modules/# ← 路由模块（按功能拆分）
├── stores/               # Pinia 状态管理
├── views/app/            # 业务页面（按功能模块组织）
├── locales/langs/        # i18n 国际化文件
│   ├── zh-CN/            # enum.json, menu.json, page.json, ui.json
│   └── en-US/
└── transport/rest/       # HTTP 传输层（PaginationQuery, requestApi）

关键约定（必须遵守）

数据层约定

1. 禁止直接引用 #/api/generated/ 路径 — 业务层通过 #/api 统一入口导入
2. composables 直接使用 apiClient — 导入 apiClient from #/api/client，调用 apiClient.xxxService.Method()
3. 组件内用 use* hooks，组件外（Store/路由守卫）用 fetch* 函数
4. 更新操作只传变化字段 — useUpdate* 内部自动生成 updateMask
5. Pinia Store 中不可依赖 useRouter() — Store 初始化时路由可能未就绪
6. 所有列表查询统一使用 PaginationQuery

Vben 框架强规约

7. 表单组件必须使用注册名 — schema 中 component 字段只能使用 adapter/component/index.ts 中注册的名称（如 Input、Select、ApiSelect），不要使用 Ant Design Vue 原始组件名（如 AInput、ASelect）或原生 HTML 标签
8. Template 中使用 a-* 前缀 — Ant Design Vue 组件已全局注册，在 template 中直接用 <a-button>、<a-tag>、<a-popconfirm> 等，不需要 import { Tag } from 'ant-design-vue'
9. 图标在 :icon prop 中必须用 h() 渲染 — :icon="h(LucideFilePenLine)"，图标组件从 @vben/icons 导入
10. 日期列用 formatter: 'formatDateTime' — 不要在 Slot 中用 dayjs 手动格式化
11. 表单校验用内置规则名 — rules: 'required' 或 rules: 'selectRequired'，不要用 Zod 表达式
12. 删除操作必须二次确认 — 使用 <a-popconfirm>，不要用 window.confirm 或直接删除
13. 国际化文本不硬编码 — 使用 $t() 引用 locales 文件中的 key
14. 使用严格相等运算符 === — 禁止使用 ==

新建业务模块 Checklist

二开时创建新模块的标准流程：

- [ ] Step 1: 确认 generated 层已有类型（protobuf 已生成）
- [ ] Step 2: 创建 composables 层（src/api/composables/xxx.ts）
- [ ] Step 3: 注册导出（composables/index.ts）
- [ ] Step 4: 添加 i18n 翻译（zh-CN + en-US）
- [ ] Step 5: 创建路由模块（router/routes/modules/app/xxx.ts）
- [ ] Step 6: 创建视图页面（views/app/xxx/）

Step 1: 确认 generated 类型

确保 src/api/generated/admin/service/v1 中包含目标模块的：

• 类型定义: xxxservicev1_EntityName
• 请求/响应类型
• ApiClient 中已有 xxxService getter

Step 2-3: API 层开发

详见 api-patterns.md，包含完整的 composable 模板代码。

Step 4: i18n 国际化

在四个 JSON 文件中添加对应 key：

en-US/ 目录下同步添加英文翻译。

Step 5: 路由配置

新建 router/routes/modules/app/xxx.ts：

import type { RouteRecordRaw } from 'vue-router';
import { BasicLayout } from '#/layouts';
import { $t } from '#/locales';

const routes: RouteRecordRaw[] = [
  {
    path: '/xxx',
    name: 'XxxManagement',
    component: BasicLayout,
    redirect: '/xxx/list',
    meta: {
      order: 3001,           // 菜单排序
      icon: 'lucide:xxx',    // lucide 图标
      title: $t('menu.xxx.moduleName'),
      authority: ['sys:platform_admin', 'sys:tenant_manager'],
    },
    children: [
      {
        path: 'list',
        name: 'XxxList',
        meta: {
          title: $t('menu.xxx.list'),
          authority: ['sys:platform_admin'],
        },
        component: () => import('#/views/app/xxx/index.vue'),
      },
    ],
  },
];
export default routes;

Step 6: 视图页面开发

详见 view-patterns.md，包含列表页、Drawer 表单页的完整模板。

导入路径约定

// API 导入 — 统一通过 #/api 入口
import { useListUsers, PaginationQuery, userStatusToName } from '#/api';

// 类型导入 — 也通过 #/api（re-export 了 generated 类型）
import { type identityservicev1_User as User } from '#/api';

// 适配器导入
import { useVbenForm } from '#/adapter/form';
import { useVbenVxeGrid } from '#/adapter/vxe-table';

// 布局与通用组件
import { Page, useVbenDrawer } from '@vben/common-ui';

// 国际化
import { $t } from '@vben/locales';

// 图标（lucide）
import { LucideFilePenLine, LucideTrash2 } from '@vben/icons';

参考文件

• API 两层架构详细模板和模式: api-patterns.md
• 视图/页面/表单/表格详细模板: view-patterns.md

Source: tx7do/go-wind-cms — distributed by TomeVault.