SKILL.md 7.8 KB


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 项目。

agent_created: true

赛普业务前端开发(antd-vue)

布局、组件、路由、请求、登录都由基座 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 不需要的功能(如导入)连按钮带接口一起删,不留半截注释

七、交付前自检

  • 页面路径与菜单 hrefs 对齐,只有 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 开关)