name: sapit-antd-vue description: 赛普 sapit-ui 体系(Vue 3 + Vite 5 + ant-design-vue 4)业务前端生成器与开发手册。用户给出项目目录、需求文档、原型(vue + mock.js)、表结构(ER 图或 sql)时,直接生成可运行代码:列表页 + 新增/编辑/详情弹窗 + api 接口。当用户说「做一个 XX 页面 / 加个列表页 / 生成表单 / 新建模块 / 写个接口 / 加个弹窗」,或涉及 sapit-ui、sapit-ui-plus、mode 模板、SListLayout、SFormLayout、SModal、SFilterItem、loadData 时使用。不用于 element-plus 项目。
布局、组件、路由、请求、登录都由基座 npm 包 sapit-ui-plus 提供。业务项目从 mode 模板复制,只写自己的页面和接口,不碰基座。
| 层 | 是什么 | 你该做什么 |
|---|---|---|
基座 sapit-ui-plus(npm 依赖) |
布局、全局组件、动态路由、请求封装、国际化、登录页/工作台/待办/消息/错误页 | 不动。缺能力找维护方发版 |
业务项目(从 mode 复制) |
src/views、src/api、src/config、.env*、vite.config.js |
所有开发都在这一层 |
| 材料 | 取什么 | 查哪份 |
|---|---|---|
| 项目根目录 | 文件写哪 | — |
| 需求文档 | 规则、必填、校验、默认值、按钮、特殊排版 | references/07-材料解析.md 第四节 |
| 原型(vue + mock.js) | 页面结构、查询条件、列、表单分组、控件、字段名 | references/07-材料解析.md 第一、三节 |
| 表结构(ER 图 / sql) | 字段、类型、长度、可空、外键、注释 | references/07-材料解析.md 第二、五节 |
先解析成字段清单,出表让用户确认,再写代码。 流程见 references/00-生成流程.md。
需求没特殊说明时,列表页默认做全套:分页查询、新增、修改、删除、导入、导出、详情。
产物文件按需求实际内容算,不套固定数量。 先列功能项,再据此定文件:
| 需求里有 | 产物 |
|---|---|
| 任何页面(必有) | src/api/<api文件>.js — 只放这个需求真正用到的接口 |
| 列表/查询 | src/views/<模块>/<页面>/index.vue |
| 新增 / 修改 / 查看 | 共用 <页面>/form.vue(add / edit / view 三模式) |
| 详情排版或内容与表单明显不一致 | 另加 <页面>/detail.vue(独立详情弹窗) |
| 只有列表、没有任何表单入口 | 不出 form.vue |
| 没有导入 / 导出 | 对应按钮、api 函数、上传地址整块不生成 |
| 需要左侧组织/分类树 | 不出新文件,index.vue 启用 #tree 插槽 + api 加左树两段 |
| 主表带明细子表 | 不出新文件,form.vue 内嵌子表;子表结构独立且要单独维护时才拆文件 |
| 页面内有多个标签页 | 不出新文件,index.vue 用 s-tab 分区;分区独立成体量较大的业务块时才拆 |
| 需求本身是纯表单/纯详情页(无列表) | 只出 form.vue 或 detail.vue,不出 index.vue |
判完在字段清单确认时一并列出本次要产出的文件清单,让用户看到再动手。能复用就不新建,不为了凑齐数量硬造文件,也不为了省事把该有的拆开塞进一个文件。
| 场景 | 抄哪个模板 |
|---|---|
| 列表页(含添加/导入/导出、查看/修改/删除) | assets/list-page.vue |
| 新增 / 编辑 / 详情弹窗(三模式) | assets/form-modal.vue |
| 独立详情弹窗(仅排版不一致时) | assets/detail-page.vue |
| api 文件(分页、导入、左树) | assets/api.js |
| 列表带左侧组织树 | assets/list-page.vue 的 #tree 注释段 + assets/api.js 左树两段 |
| 无标题列表(嵌在标签页/面板里) | references/02-组件文档-列表页.md |
| 独立整页表单 | assets/form-modal.vue 改成 s-form-layout,见 references/03-组件文档-表单与弹窗.md |
| 占位符 | 替换成 | 示例 |
|---|---|---|
__MODULE__ |
模块目录名(= i18n 命名空间) | master-data |
__PAGE__ |
页面目录名(= 菜单 hrefs 最后一段) | standard |
__NAME__ |
页面中文名 | 数据标准 |
__API__ |
api 文件名 / 上传 path | master-data |
__PATH__ |
接口路径前缀 | /master-data |
__COMPONENT__ |
组件 name 前缀 | Standard |
__DICT_TYPE__ / __DICT_KEY__ |
字典类型 / 驼峰键 | data_type / dataType |
替换完在生成目录里搜 __,必须零命中;xxx 这类示例值同样要清掉。
| # | 约定 |
|---|---|
| 1 | 页面必须 src/views/<模块>/<页面>/index.vue,菜单 hrefs 按 /src/views/**/<hrefs>/index.vue 匹配,其他文件名不参与路由 |
| 2 | 只改 src/views、src/api、src/config、.env*。走菜单的页面不写路由,page-entries.js 保持空 |
| 3 | 基座组件全部全局注册,模板里直接 <s-list-layout> / <s-modal> / <a-input>,不用 import |
| 4 | 不装基座已内置的依赖:vue、vue-router、pinia、vue-i18n、ant-design-vue、axios、dayjs、@vueuse/core |
| 5 | 列表取数函数接收一个参数对象,必须返回 { list, total };后端字段不一致在 api 层转 |
| 6 | 页面文案写 $l('中文'),模块词条放 src/views/<模块>/i18n.js |
| 7 | 接口 url 只写 /${网关名}/接口路径,域名和 /apig 前缀由 baseURL 拼 |
| 8 | 字段类型按 references/06-字段控件映射.md 落控件,不自己造轮子 |
| 9 | 详情优先复用 form.vue 的 view(id),不默认新增文件 |
| 10 | 不需要的功能(如导入)连按钮带接口一起删,不留半截注释 |
index.vue 参与路由__ 占位符、无 xxx 示例残留page() 返回 { list, total };区间字段在 api 层拆成起止日期form.vue 暴露 add / edit / view,列表三处都能调s-form-item 都有 name,rules 键与之一致value、组织树转 officeId、开关转 1/0、附件 join(',')$l('中文')| 文件 | 内容 |
|---|---|
references/00-生成流程.md |
输入槽位、解析顺序、缺省决策、产物清单、占位符、命名、生成顺序、自检 |
references/01-说明文档.md |
目录结构、页面与路由注册、i18n、权限、全局方法 |
references/02-组件文档-列表页.md |
s-list-layout、工具栏按钮契约、导入配置、s-filter-table-toolbar、s-table、查询区、左侧树、列配置 |
references/03-组件文档-表单与弹窗.md |
s-form-layout、s-form、s-form-item、s-modal、s-drawer、s-import-modal |
references/04-组件文档-业务控件.md |
上传、选人、组织树、岗位、字典下拉、标签页、空状态 |
references/05-工具配置文档.md |
环境变量、三层配置、vite.config.js、请求与 api 写法、命令端口、主题 |
references/06-字段控件映射.md |
字段类型 → 控件 + 属性 + 校验 + 列渲染 + 提交转换 |
references/07-材料解析.md |
需求 / 原型 mock / sql / ER 图 → 字段清单 |
assets/list-page.vue |
列表页模板(添加/导入/导出、查看/修改/删除) |
assets/form-modal.vue |
新增/编辑/详情三模式弹窗模板 |
assets/detail-page.vue |
独立详情弹窗模板(仅排版不一致时) |
assets/api.js |
api 模板(分页、导入、左树、mock 开关) |