--- 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/.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/**//index.vue` 匹配,其他文件名不参与路由 | | 2 | 只改 `src/views`、`src/api`、`src/config`、`.env*`。走菜单的页面不写路由,`page-entries.js` 保持空 | | 3 | 基座组件全部全局注册,模板里直接 `` / `` / ``,不用 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 开关) |