diry 3 dias atrás
pai
commit
a237abbe25

+ 119 - 0
development/sapit-dev-web/sapit-antd-vue/SKILL.md

@@ -0,0 +1,119 @@
+---
+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 开关) |

+ 146 - 0
development/sapit-dev-web/sapit-antd-vue/references/00-生成流程.md

@@ -0,0 +1,146 @@
+# 生成流程(材料 → 代码)
+
+用户一般给「需求文件 + 原型 + 表结构 + 项目目录」四样,按本文顺序走完即可产出可运行代码。
+
+---
+
+## 一、需求输入槽位
+
+用户的实际提示词长这样:
+
+```text
+项目根目录:D:\xxx\业务项目
+需求文件:xxx.doc / xxx.md          # 业务规则、必填、状态流转
+原型图:vue + mock.js               # 页面结构、查询条件、列、表单分组
+表结构:ER 图 或 xxx.sql            # 字段、类型、长度、外键
+其他要求:…
+```
+
+槽位不齐时按第三节处理,不要凭空编字段。
+
+---
+
+## 二、解析顺序(先出字段清单,再写代码)
+
+| 步 | 做什么 | 查哪份 |
+|---|---|---|
+| 1 | 读表结构 → 字段、类型、长度、外键 | `07-材料解析.md` 第二节 |
+| 2 | 读原型 → 查询条件、列、表单分组、控件、字段名 | `07-材料解析.md` 第一节、第三节 |
+| 3 | 读需求 → 必填、校验、默认值、按钮、特殊排版 | `07-材料解析.md` 第四节 |
+| 4 | 合成字段清单,**先在对话里出表让用户确认** | `07-材料解析.md` 第七节 |
+| 5 | 确认后按第四、七节生成文件 | — |
+
+字段清单没确认就写代码,返工概率很高。
+
+---
+
+## 三、缺省决策表
+
+| 槽位 | 缺失时怎么处理 |
+|---|---|
+| 页面中文名 | 取表名或菜单 hrefs 最后一段转中文(`deviceLedger` → 设备台账) |
+| 菜单 hrefs | **必须问**,决定 `src/views/` 下的目录名 |
+| 接口路径前缀 | 默认按表名转 kebab(`md_standard` → `/md-standard`),集中写在 api 顶部便于一处改 |
+| 接口网关 | 默认 `VITE_APP_SYS_SERVER_NAME`;组织/用户/角色/字典/文件用 `VITE_APP_PORTAL_SERVER_NAME` |
+| 功能范围 | 默认**全套**:分页查询、新增、修改、删除、导入、导出、详情 |
+| 权限码 | 默认 `add` / `edit` / `remove` / `export` / `import` |
+| 字段必填 | 表结构 `NOT NULL` 且无默认值 → 必填;需求里写「必填」覆盖表结构 |
+| 字典类型 | 优先字段注释,其次 `表名_字段`;两者都没有就停下来问 |
+| 表结构缺失 | 按 mock 字段生成,类型一律文本/数字,交付时标注「类型待后端确认」 |
+| 原型缺失 | 按字段清单 + 常规布局(查询 3 项、表单 2 列、长文本 `full`) |
+| 后端接口未就绪 | api 顶部 `const USE_MOCK = false`,置 `true` 页面可先跑通 |
+
+**必须停下来问的只有三处**:菜单 hrefs 未知、字段清单为空、字典类型查不到。
+
+---
+
+## 四、默认功能与产物清单
+
+需求没特殊说明时,列表页默认做全套(分页查询、新增、修改、删除、导入、导出、详情)。
+
+**产物文件数量不固定,先按需求列功能项,再据此推文件。** 下面是判定表,逐条过一遍需求,命中的才生成:
+
+| 需求里出现 | 产物 | 备注 |
+|---|---|---|
+| 任何页面 | `src/api/<api文件>.js` | 只写这次真正调用的接口,用不到的接口不留空壳 |
+| 列表 / 查询 / 分页 | `src/views/<模块>/<页面>/index.vue` | |
+| 新增 | `form.vue` 的 `add()` | |
+| 修改 | `form.vue` 的 `edit(id)` | |
+| 查看 / 详情 | `form.vue` 的 `view(id)` 只读模式 | 排版、字段与表单一致就复用 |
+| 详情排版或内容与表单明显不一致 | 另加 `<页面>/detail.vue` | 抄 `assets/detail-page.vue` |
+| 无任何表单入口,纯列表 | 不出 `form.vue` | |
+| 需求是纯表单页 / 纯详情页,没有列表 | 只出 `form.vue` / `detail.vue` | 不出 `index.vue` |
+| 导入 | `index.vue` 导入按钮 + api 四个导入接口 + 上传地址 | 不做就整块不生成 |
+| 导出 | `index.vue` 导出按钮 + api 导出函数 | |
+| 删除 | 操作列删除 + api 删除函数 | 只做逻辑删除时按钮文案按需求写 |
+| 左侧组织/分类树 | 不外挂文件:`index.vue` 启用 `#tree` + api 左树两段 | |
+| 主表带明细子表 | 不外挂文件:`form.vue` 内嵌子表 | 子表要独立维护成单独接口/页面时才拆 |
+| 页内多个分组/标签页 | 不外挂文件:`s-tab` 或 `s-collapses` 分区 | 分区体量大且独立时才拆 |
+| 字段多需要整页编辑 | 不外挂页面:`form.vue` 换 `s-form-layout` | |
+
+判定完把「本次产出文件清单」写进字段清单确认表一起给用户,确认后再写代码。
+
+**路由不用写**:菜单配好 `hrefs` 后自动匹配 `src/views/**/<hrefs>/index.vue`,`page-entries.js` 保持空。
+
+---
+
+## 五、占位符替换规则
+
+模板里 `__全大写__` 是待替换标记:
+
+| 占位符 | 替换成 | 示例 |
+|---|---|---|
+| `__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` 这类示例值同样要清掉。
+
+---
+
+## 六、命名规范
+
+| 对象 | 规范 | 示例 |
+|---|---|---|
+| 列表组件 name | `__COMPONENT__List` | `StandardList` |
+| 表单组件 name | `__COMPONENT__FormModal` | `StandardFormModal` |
+| 详情组件 name | `__COMPONENT__DetailModal` | `StandardDetailModal` |
+| api 函数 | `page` / `getById` / `save` / `deleteById` / `deleteByIds` / `exportExcel` / `templateDownload` / `importPreview` / `importData` / `exportExceptionData` | — |
+| 页面内 api 别名 | `page as pageApi` | 避免和分页变量重名 |
+| 查询条件 | `queryParam` | — |
+| 表单对象 | `form`,初始值收敛到 `defaultForm()` | — |
+| i18n 命名空间 | 等于模块目录名 | `window.useI18n('master-data')` |
+
+---
+
+## 七、生成顺序
+
+按第四节判定出的文件清单逐个生成,顺序按依赖走:
+
+1. `src/api/<api文件>.js` —— 从 `assets/api.js` 起,只留用得上的接口,先定函数名
+2. `src/views/<模块>/<页面>/index.vue` —— 有列表才出,从 `assets/list-page.vue` 起
+3. `src/views/<模块>/<页面>/form.vue` —— 有新增/修改/查看才出,从 `assets/form-modal.vue` 起(三模式)
+4. `src/views/<模块>/<页面>/detail.vue` —— 仅详情排版或内容不一致时
+5. `src/views/<模块>/i18n.js` —— 模块词条,格式见 `01-说明文档.md` 第四节
+
+需求里没有的条目直接跳过,不建空文件、不留 TODO 注释。
+
+---
+
+## 八、输出前自检
+
+- [ ] **产出文件与需求功能项一一对应**:需求没提的功能不出代码,需求提了的都有落点
+- [ ] 页面在 `src/views/<模块>/<页面>/index.vue`,目录名 = 菜单 hrefs 最后一段
+- [ ] 无 `__` 占位符、无 `xxx` 示例残留
+- [ ] `page()` 返回 `{ list, total }`;区间字段在 api 层拆成起止日期
+- [ ] 工具栏按钮、操作列按钮与需求里列的功能一致(没导入就不留导入按钮和接口)
+- [ ] `form.vue` 暴露的方法与列表里的入口对得上(有修改才有 `edit`,有详情才有 `view`)
+- [ ] 每个 `s-form-item` 都有 `name`,`rules` 键与之一致
+- [ ] 字典下拉 value 用字典 `value`;组织树提交转 `officeId`;开关转 `1/0`;附件 `join(',')`
+- [ ] 文案走 `$l('中文')`,模块词条在 `views/<模块>/i18n.js`
+- [ ] 没装新依赖(vue / antd / axios / dayjs 基座已带)
+- [ ] 起过服务打开过页面,验完把进程关掉

+ 166 - 0
development/sapit-dev-web/sapit-antd-vue/references/01-说明文档.md

@@ -0,0 +1,166 @@
+# 说明文档
+
+## 一、业务项目目录
+
+从 `mode` 模板复制一份就是业务项目,结构如下。`★` 是日常要动的目录。
+
+```
+业务项目/
+├─ index.html                    # 只改了 title 注入,一般不动
+├─ vite.config.js                # 端口、代理、别名、dedupe(见 05-工具配置文档)
+├─ .env / .env.development / .env.production
+├─ src/
+│  ├─ main.js                    # 入口:注册基座 + 页面 glob,不动
+│  ├─ App.vue                    # 根组件,不动
+│  ├─ assets/main.less           # 全局样式变量,可按需加
+│  ├─ config/
+│  │  ├─ web-config.js           # 运行时可改的配置(会被打进 config.json)
+│  │  └─ app-config.js           # 构建期配置:覆盖登录页/首页、静态路由、语言包
+│  ├─ router/page-entries.js     # 老项目兼容用的页面登记表,新项目留空
+│  ├─ locales/components/i18n.js # 公共词条(按钮名等),靠基座 components 命名空间兜底
+│  ├─ api/                       ★ 接口层,按后端模块建文件
+│  └─ views/                     ★ 页面层
+│     └─ <模块>/<页面>/index.vue
+└─ refresh-mode.ps1 / refresh-build.ps1   # 基座更新后重新拉依赖再起服务
+```
+
+## 二、页面怎么被路由到
+
+启动链路:`main.js` 用 `import.meta.glob('@/views/**/*.vue')` 收集所有页面 → 交给基座 → 基座按**后端菜单的 `hrefs`** 去匹配页面文件。
+
+匹配规则:把菜单的 `hrefs` 和 glob 出来的 key 一起转小写,找包含 `/<hrefs>/index.vue` 的那一项。
+
+| 菜单 hrefs | 页面必须放的路径 |
+|---|---|
+| `position` | `src/views/任意模块/position/index.vue` |
+| `basicData/position` | `src/views/basicData/position/index.vue` |
+| `system/user` | `src/views/system/user/index.vue` |
+
+要点:
+
+- **只有 `index.vue` 参与匹配**。同目录下的 `form.vue`、`view.vue`、`components/*.vue` 由 `index.vue` 自己 import,不要指望被路由到。
+- 后端只给一段(如 `position`)时,任意模块下叫 `position` 的目录都能命中;给全路径时目录层级必须一致。
+- 大小写不敏感,但建议目录名和 hrefs 完全一致。
+
+### 不依赖后端菜单的固定页面
+
+在 `src/config/app-config.js` 的 `staticRoutes` 里配:
+
+```js
+export default {
+  staticRoutes: [
+    {
+      path: '/developmentProcess',
+      name: 'developmentProcess',
+      layout: false, // false = 不带侧边栏和头部,独立整页
+      component: () => import('@/views/static/page/DevelopmentProcess.vue'),
+      meta: { title: '开发流程', public: true, hidden: true }
+    }
+  ]
+}
+```
+
+`public: true` 免登录,`hidden: true` 不进侧边菜单。
+
+## 三、页面文件怎么组织
+
+一个业务模块推荐这样放:
+
+```
+src/views/<模块>/<页面>/
+├─ index.vue        # 列表页,被路由到
+├─ form.vue         # 弹窗表单 / 新增编辑页,index.vue import
+├─ view.vue         # 详情页
+├─ components/      # 本页面私有子组件
+└─ i18n.js          # 本模块词条(可选)
+```
+
+页面上的 `name` 用 `defineOptions({ name: 'XxxList' })` 显式声明,方便 keep-alive 和调试。
+
+## 四、国际化
+
+基座按目录自动分配命名空间:`views/<模块>/i18n.js` → 命名空间 `<模块>`。
+
+```js
+// src/views/position/i18n.js
+export default {
+  岗位名称: 'Position Name',
+  请输入岗位名称: 'Please enter position name'
+}
+```
+
+页面里二选一:
+
+```js
+// 写法一:setup 里拿到 $l(推荐,模板和脚本都能用)
+const { $l } = window.useI18n('position')
+```
+
+```vue
+<!-- 写法二:模板里直接用全局 $l,命名空间按当前页面目录自动推断 -->
+<a-button>{{ $l('添加') }}</a-button>
+```
+
+规则:
+
+- 词条 key 就是**中文原文**,值是对应英文。没配英文时英文环境会显示中文,不会空白。
+- 按钮、通用提示(添加/删除/保存/操作成功)基座已内置,不用自己配。
+- `$l('中文')` 里的中文必须是字面量,不要拼变量,否则切语言不生效。
+
+## 五、按钮级权限
+
+后端返回的 `button_code` 与指令值**整体相等**才通过。
+
+```vue
+<!-- 无权限时元素被移出 DOM -->
+<a-button v-action="'add'">添加</a-button>
+<span v-action="'edit'"><a @click="edit(record)">修改</a></span>
+```
+
+```js
+// 或/且这类指令表达不了的场景,用函数
+const canEdit = window.$utils.hasAction('edit') || window.$utils.hasAction('add')
+```
+
+列表工具栏按钮也会自动挂 `v-action`,`key` 就是按钮编码(`add` / `remove` / `import` / `export`)。
+
+## 六、全局方法与工具
+
+组件内用 `this.$xxx`,`<script setup>` 里用 `window.$xxx`。
+
+| 方法 | 用途 |
+|---|---|
+| `$l(中文)` | 国际化 |
+| `$message.success / warn / error / info` | 顶部轻提示 |
+| `$notice.success({ message, description })` | 右上角通知(带标题和描述) |
+| `$modal.confirm({ title, content, onOk })` | 二次确认弹窗 |
+| `$confirm({...})` | 同 `$modal.confirm` |
+| `$push(path, query)` | 站内跳转(`location.href`,自动拼 `VITE_APP_BASE_URL`) |
+| `$open(path, query)` | 新标签页打开 |
+| `$utils.http` | 请求实例(见 05-工具配置文档) |
+| `$utils.env` | 当前环境变量对象 |
+| `$utils.hasAction(code)` | 按钮权限判断 |
+| `$utils.uuid()` | 生成 uuid |
+| `$utils.isFunction / isArray / isString` | 类型判断 |
+| `$utils.ls.get / set` | localStorage 封装 |
+| `$icons` | 全部 antd 图标,`$icons.PlusOutlined` |
+| `window.useI18n(ns)` | 取当前命名空间的 `$l` |
+
+图标除了 `$icons`,也可以直接从 `@ant-design/icons-vue` 引入,基座已带该依赖:
+
+```js
+import { PlusOutlined, CheckOutlined } from '@ant-design/icons-vue'
+```
+
+## 七、页面骨架怎么选
+
+| 场景 | 骨架 | 说明 |
+|---|---|---|
+| 标准业务列表(标题 + 按钮 + 查询 + 表格 + 分页) | `s-list-layout` | 高度自适应,表格铺满剩余空间,一行代码不用写样式 |
+| 列表里带左侧组织树 | `s-list-layout` + `#tree` 插槽 | 插槽给了左侧树和拖拽分隔条 |
+| 卡片列表 | `s-list-card-layout` | 同类 API,把表格换成卡片,用 `#default` 渲染卡片内容 |
+| 弹窗里新增/编辑 | `s-modal` + `s-form` | 宽度默认 60vw,可全屏、可拖拽 |
+| 独立的整页表单 | `s-form-layout` + `s-form` | 自带标题栏、底部保存/取消按钮、右侧锚点 |
+| 抽屉里编辑 | `s-drawer` + `s-form` | 适合简单的单列表单 |
+| 详情展示 | `s-form-layout` + `s-form`(`:disabled` 全禁用)或 `s-panel-layout` | — |
+| 嵌在标签页里的列表 | `s-filter-table-toolbar` | 无标题条,查询区 + 表格 |

+ 426 - 0
development/sapit-dev-web/sapit-antd-vue/references/02-组件文档-列表页.md

@@ -0,0 +1,426 @@
+# 组件文档 · 列表页
+
+列表页三层结构:**工具栏**(标题 + 按钮)→ **查询区**(`s-filter-item`)→ **表格**(`s-table`)。`s-list-layout` 把三层拼好并管高度,直接用即可。
+
+---
+
+## 一、s-list-layout(标准列表页)
+
+```vue
+<s-list-layout
+  ref="layoutRef"
+  :title="$l('岗位管理')"
+  :buttons="buttons"
+  :columns="columns"
+  :loadData="loadData"
+  :isSelection="true"
+  @reset="reset"
+  @btnCallback="btnCallback"
+>
+</s-list-layout>
+```
+
+### Props
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `title` | String | 必填 | 页面标题 |
+| `loadData` | Function | 必填 | 取数函数,**返回 `{ list, total }`** |
+| `columns` | Array | `[]` | 列配置,见第四节 |
+| `buttons` | Array | 添加/批量删除/导入/导出 | 工具栏按钮,传 `[]` 清空 |
+| `isSelection` | Boolean | `false` | 显示 checkbox 列(配了 `remove` 按钮会自动开) |
+| `showPagination` | Boolean | `true` | 是否分页 |
+| `rowKey` | String / Function | `'id'` | 行主键字段 |
+| `pSize` | Number / String | `20` | 每页条数 |
+| `selectedRowKeysArr` | Array | `[]` | 初始勾选的行 key(选择器弹窗场景) |
+
+### 插槽
+
+| 插槽 | 作用域 | 说明 |
+|---|---|---|
+| `filter` | — | 查询区主行,里面放 `s-filter-wrap` + `s-filter-item` |
+| `filterMore` | — | 「更多」展开后的查询条件,有它才出现"更多/收起" |
+| `otherBtns` | `{ selections }` | 工具栏按钮右侧追加内容 |
+| `tree` | — | 左侧树,出现后自带拖拽分隔条 |
+| `desc` | — | 查询区上方的说明文字区 |
+| `tabs` | — | 表格上方的标签页区 |
+| `empty` | — | 有它则整块内容区被替换(空状态/引导页) |
+| `other` | — | 根节点末尾,通常放弹窗组件 |
+| `<dataIndex>` | `{ text, record, index, item }` | 列插槽,列名即插槽名,见第四节 |
+| `action` | `{ record }` | 操作列(`dataIndex: 'action'` 时生效) |
+
+### 事件
+
+| 事件 | 参数 | 说明 |
+|---|---|---|
+| `reset` | — | 点了查询区"条件重置"。**业务自己清空查询参数再调 `reload()`** |
+| `btnCallback` | `(key, selectedRowKeys)` | 点任意工具栏按钮都抛,业务在这里分发 |
+| `tableColCallback` | `(field, record)` | 点了 `isClick: true` 的列 |
+
+### 实例方法
+
+通过 `ref` 调用:
+
+| 方法 / 属性 | 说明 |
+|---|---|
+| `reload()` | 回到第一页重新请求 |
+| `selectedRowKeys` | 当前勾选的行 key 数组 |
+| `spinning` | 工具栏按钮请求中的 loading(内部用) |
+| `setStateBtn(key, { show, disabled })` | 动态改按钮显隐/禁用,`key` 可传数组批量改 |
+| `table` | 内部 `s-table` 实例,需要更细操作时用 |
+
+---
+
+## 二、buttons 配置
+
+每项是一个对象:
+
+```js
+const buttons = ref([
+  { name: '添加', key: 'add', type: 'primary', icon: true },
+  {
+    name: '导入',
+    key: 'import',
+    icon: true,
+    importUploadUrl: IMPORT_UPLOAD_URL,      // 上传地址
+    importColumns: importColumns,             // 预览表头
+    importApis: { templateDownload, importPreview, importData, exportExceptionData }
+  },
+  { name: '导出', key: 'export', icon: true, api: exportExcel },
+  { name: '批量删除', key: 'remove', icon: true, api: deleteByIds, confirm: true }
+])
+```
+
+| 字段 | 说明 |
+|---|---|
+| `name` | 按钮文案,会过 `$l()` |
+| `key` | 唯一标识,同时作为**按钮权限编码**和 `btnCallback` 的第一个参数 |
+| `show` | `false` 直接不渲染(默认 `true`) |
+| `disabled` | 禁用 |
+| `type` | `primary` / `default`,不填时 `add` 自动 primary |
+| `icon` | `true` 用内置图标(按 key 映射),也可传图标名字符串 |
+| `api` | 点击要调的接口,**接收选中行 key 数组** |
+| `confirm` | 配了 `api` 时先弹确认框,确认后才调 |
+| `selection` | `false` 时不校验是否勾选 |
+
+内置 `key` 的行为:
+
+| key | 行为 |
+|---|---|
+| `add` | 只抛 `btnCallback('add')`,业务自己打开新增弹窗 |
+| `remove` / `delete` | 走 `api(selectedRowKeys)`,自动校验"请选择要删除的数据",成功后刷新 |
+| `import` | 配了 `importUploadUrl` 就打开内置导入弹窗;没配则只抛 `btnCallback('import')` |
+| `export` | 走 `api()`,无选中行要求 |
+
+其他自定义 key:配了 `api` 就走"校验勾选 → 确认 → 请求 → 提示 → 刷新";没配 `api` 就只抛 `btnCallback`,业务自己在事件里处理。
+
+---
+
+## 三、取数函数 loadData
+
+```js
+// 查询条件单独放一个 reactive,翻页参数由组件传进来
+const queryParam = reactive({ name: undefined, type: undefined })
+
+const loadData = (parameter = {}) => pageApi(queryParam, parameter)
+```
+
+`parameter` 是组件传进来的分页/排序对象:
+
+```js
+{ pageNo: 1, pageSize: 20, sortField: '', sortOrder: '', ...filters }
+```
+
+返回值必须是:
+
+```js
+{ list: [...], total: 100 }
+```
+
+- `list` 字段名不能改,`total` 不能少,否则列表空白或分页错乱。
+- 也可以返回 `{ list, total, pageNo }`,`pageNo` / `pageNum` 会被用来回填当前页。
+- 删完最后一条时组件会自动往前翻一页。
+
+---
+
+## 四、columns 配置
+
+在 antd 列配置基础上加了三个约定字段:
+
+| 字段 | 作用 |
+|---|---|
+| `template: true` | 该列用**同名插槽**渲染,插槽名 = `dataIndex` |
+| `isClick: true` | 该列渲染成可点击的 `<a>`,点击抛 `tableColCallback`;值为对象时取 `name` 显示 |
+| `dataIndex: 'action'` | 操作列,用 `#action` 插槽渲染,一般配 `fixed: 'right'` |
+
+```js
+const columns = ref([
+  { title: '岗位名称', dataIndex: 'name', ellipsis: true, template: true },
+  { title: '岗位编码', dataIndex: 'code', ellipsis: true },
+  { title: '岗位类型', dataIndex: 'typeLabel', width: 150, align: 'center', ellipsis: true },
+  { title: '是否启用', dataIndex: 'useable', width: 100, align: 'center', template: true },
+  { title: '操作', dataIndex: 'action', width: 200, align: 'center', fixed: 'right' }
+])
+```
+
+```vue
+<template #name="{ record }">
+  <a @click="view(record)">{{ record.name }}</a>
+</template>
+
+<template #useable="{ record }">
+  <CheckOutlined v-if="record.useable" style="color: var(--s-color-success)" />
+</template>
+
+<template #action="{ record }">
+  <span v-action="'edit'">
+    <a @click="edit(record)">修改</a>
+    <a-divider type="vertical" />
+  </span>
+  <span v-action="'remove'">
+    <a style="color: red" @click="onDelete(record)">删除</a>
+  </span>
+</template>
+```
+
+其余字段与 antd 的 `a-table` 列一致:`width`、`align`、`ellipsis`、`fixed`、`sorter`、`customRender` 都能用。
+
+---
+
+## 五、完整列表页
+
+见 `assets/list-page.vue`,直接复制改字段即可。结构:
+
+```
+<s-list-layout>
+  #filter      主查询条件(输入框、下拉、日期)
+  #filterMore  更多条件
+  #name 等     列插槽
+  #action      操作列
+  #other       弹窗组件
+</s-list-layout>
+```
+
+配合的脚本:
+
+```js
+const layoutRef = ref(null)
+const formRef = ref(null)
+const queryParam = reactive({ name: undefined })
+
+const loadData = (parameter = {}) => pageApi(queryParam, parameter)
+const reload = () => layoutRef.value.reload()
+const paramChange = () => reload()          // 查询条件变化立刻刷新
+
+const reset = () => {                       // 条件重置
+  Object.assign(queryParam, { name: undefined })
+  reload()
+}
+
+const btnCallback = (key) => {
+  if (key === 'add') formRef.value.add()
+  if (key === 'export') exportExcel(queryParam)
+}
+
+const edit = (record) => formRef.value.edit(record.id)
+```
+
+---
+
+## 六、查询区:s-filter-toolbar / s-filter-wrap / s-filter-item
+
+`s-list-layout` 内部已经把查询区画好了,**直接用 `s-filter-wrap` + `s-filter-item`**;只有在自定义页面里才单独用 `s-filter-toolbar`。
+
+### s-filter-item
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `label` | String | 必填 | 标签文案 |
+| `labelWidth` | Number | `70` | 标签宽度 px |
+| `width` | Number | `280` | 整项宽度 px(含标签) |
+| `full` | Boolean | `false` | 独占一行 |
+| `colon` | Boolean | `false` | 标签后加冒号 |
+| `mb` | Number | `0` | 底部间距 px |
+| `isNormal` | Boolean | `true` | `true` 描边样式;`false` 无边框(用于复选框、纯按钮) |
+
+```vue
+<template #filter>
+  <s-filter-wrap>
+    <s-filter-item label="名称">
+      <a-input v-model:value="queryParam.name" placeholder="请输入名称" @pressEnter="paramChange" />
+    </s-filter-item>
+    <s-filter-item label="状态">
+      <a-select v-model:value="queryParam.status" :allowClear="true" placeholder="请选择" @change="paramChange">
+        <a-select-option :value="1">启用</a-select-option>
+        <a-select-option :value="0">停用</a-select-option>
+      </a-select>
+    </s-filter-item>
+    <s-filter-item label="包含下级" :labelWidth="90" :isNormal="false">
+      <a-checkbox v-model:checked="queryParam.includeChild" @change="paramChange" />
+    </s-filter-item>
+  </s-filter-wrap>
+</template>
+```
+
+`s-filter-wrap` 是 `flex-wrap` 容器,放多个 `s-filter-item` 自动换行;`type="filter-more"` 用于"更多"区。
+
+### s-filter-toolbar(独立使用)
+
+| 插槽 | 说明 |
+|---|---|
+| `filter` | 主查询行 |
+| `filterMore` | 更多查询行 |
+
+| 事件 | 说明 |
+|---|---|
+| `reset` | 点条件重置,业务清空参数后自行刷新 |
+| `toggle` | 更多区展开/收起,参数为是否展开 |
+
+暴露 `isMoreFilter`、`toggleFilter()`、`filterReset()`、`collapse()`。
+
+---
+
+## 七、无标题列表:s-filter-table-toolbar
+
+嵌在标签页、面板、抽屉里时不想要那 60px 标题条,用它:查询区 + 表格,没有工具栏。
+
+```vue
+<s-filter-table-toolbar
+  ref="tableRef"
+  :columns="columns"
+  :data="loadData"
+  :pageSize="20"
+  @reset="reset"
+>
+  <template #filter>
+    <s-filter-wrap>
+      <s-filter-item label="名称">
+        <a-input v-model:value="queryParam.name" @pressEnter="refresh" />
+      </s-filter-item>
+    </s-filter-wrap>
+  </template>
+
+  <template #status="{ record }">
+    <a-tag :color="record.status ? 'green' : 'default'">{{ record.status ? '启用' : '停用' }}</a-tag>
+  </template>
+</s-filter-table-toolbar>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `data` | Function | 必填 | 取数函数,返回 `{ list, total }` |
+| `columns` | Array | `[]` | 列配置,`template` / `isClick` / `action` 同 `s-list-layout` |
+| `rowKey` | String / Function | `'id'` | — |
+| `pageSize` | Number | `10` | — |
+| `size` | String | `'middle'` | `small` / `middle` / `large` |
+| `scrollX` | String / Number | `'100%'` | 横向滚动宽度 |
+| `tableHeight` | Number | `300` | 表体最小高度,空间足够时按实际可用高度 |
+
+事件 `reset`;方法 `refresh(回第一页?)`、`reload()`、`resize()`、`tableRef`。
+
+`s-table-toolbar` 就是它去掉查询区,属性方法一致。
+
+---
+
+## 八、s-table(裸表格)
+
+需要自己写工具栏、或者表格要放在非常规容器里时直接用。
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `data` | Function | 必填 | 取数函数,返回 `{ list, total }` |
+| `columns` | Array | — | antd 列配置 |
+| `rowKey` | String / Function | `'key'` | **默认是 `'key'`,业务数据一般是 `id`,务必显式传** |
+| `pageSize` | Number | `10` | — |
+| `pageNo` | Number | `1` | — |
+| `showPagination` | Boolean / `'auto'` | `'auto'` | `false` 关闭分页 |
+| `showSizeChanger` | Boolean | `true` | 显示每页条数切换 |
+| `rowSelection` | Object | `null` | 同 antd,`{ selectedRowKeys, onChange }` |
+| `loading` | Boolean | `false` | 外部控制的 loading |
+| `expandedRowKeys` | Array | — | 展开行,`v-model:expanded-row-keys` |
+
+方法:`refresh(true)` 回第一页刷新,`refresh(false)` 留在当前页。
+
+```vue
+<s-table ref="tableRef" :columns="columns" :data="loadData" rowKey="id" :pageSize="20" />
+```
+
+---
+
+## 九、左侧树 s-tree
+
+放在 `s-list-layout` 的 `#tree` 插槽里,出现后左侧自带拖拽分隔条。
+
+```vue
+<template #tree>
+  <s-tree
+    :levelOneChildren="levelOneChildren"
+    :levelTwoChildren="levelTwoChildren"
+    :expandAll="false"
+    @select:modelValue="onTreeSelect"
+  />
+</template>
+```
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `levelTwoChildren` | Function | **初始化**根节点:调用时传空串 `''`,返回根级节点数组 |
+| `levelOneChildren` | Function | **展开某节点**时懒加载其子级,入参是节点 id |
+| `expandAll` | Boolean | 是否默认展开全部 |
+| `checkable` | Boolean | 显示复选框 |
+| `showIcon` | Boolean | 显示节点图标 |
+| `selectFirstOne` | Boolean | 初始化后自动选中第一个节点 |
+| `modelValue` | String / Array | 选中项,`v-model` 双向绑定 |
+
+节点数据按 antd 默认字段:`title`(显示文本)、`key`(唯一标识)、`children`。后端字段不一致时在 api 层 map:
+
+```js
+const levelTwoChildren = async () => {
+  const list = await officeTree({ parentId: '' })
+  return list.map((o) => ({ ...o, title: o.name, key: o.id, value: o.id }))
+}
+```
+
+选中事件拿到的是 antd 的 `(selectedKeys, info)`,原始节点在 `info.node.dataRef`:
+
+```js
+const selectNode = ref({})
+const onTreeSelect = (keys, info) => {
+  const node = info?.node?.dataRef || {}
+  selectNode.value = info?.selected ? node : {}
+  queryParam.officeId = info?.selected ? node.id : undefined
+  layoutRef.value.reload()
+}
+```
+
+---
+
+## 十、分页与排序参数
+
+`loadData` 收到的对象:
+
+| 字段 | 来源 |
+|---|---|
+| `pageNo` | 当前页(从 1 开始) |
+| `pageSize` | 每页条数 |
+| `sortField` | 排序列的 `dataIndex`,没排序时不传 |
+| `sortOrder` | `'ascend'` / `'descend'` |
+| 其余 | 列的 `filters` 值 |
+
+后端接口参数名不一致时在 api 层转换,页面层不用管:
+
+```js
+// src/api/position.js
+export function page(query = {}, parameter = {}) {
+  return window.$utils.http({
+    url: `/${window.$utils.env.VITE_APP_SYS_SERVER_NAME}/position/page`,
+    data: {
+      ...query,
+      pageNum: parameter.pageNo,
+      pageSize: parameter.pageSize,
+      orderField: parameter.sortField,
+      orderType: parameter.sortOrder
+    }
+  })
+}
+```

+ 428 - 0
development/sapit-dev-web/sapit-antd-vue/references/03-组件文档-表单与弹窗.md

@@ -0,0 +1,428 @@
+# 组件文档 · 表单与弹窗
+
+表单三件套:**容器**(`s-form-layout` 整页 / `s-modal` 弹窗 / `s-drawer` 抽屉)+ **`s-form`**(网格布局 + 校验)+ **`s-form-item`**(单字段)。
+
+---
+
+## 一、s-form(表单核心)
+
+```vue
+<s-form ref="formRef" :model="form" :rules="rules" :column="2">
+  <s-form-item label="名称" name="name">
+    <a-input v-model:value="form.name" placeholder="请输入名称" :maxlength="200" />
+  </s-form-item>
+  <s-form-item label="备注" name="remark" full>
+    <a-textarea v-model:value="form.remark" :rows="3" />
+  </s-form-item>
+</s-form>
+```
+
+### Props
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `model` | Object | `{}` | 表单数据对象 |
+| `rules` | Object | `{}` | 校验规则,键是 `s-form-item` 的 `name` |
+| `column` | Number / String | `1` | 每行列数,**最大 4**,超过按 4 处理 |
+| `layout` | String | `'vertical'` | `vertical` 标签在上;`horizontal` 标签在左 |
+| `labelWidth` | Number / String | `80` | `horizontal` 时的标签宽度 px |
+
+表单内部是 CSS Grid(`repeat(column, 1fr)`),格子宽度自动均分,不用写栅格。
+
+### 实例方法
+
+```js
+const formRef = ref(null)
+
+// 校验:Promise 式(推荐)
+formRef.value.validate().then(() => { /* 通过 */ }).catch(() => { /* 未通过,可留空 */ })
+
+// 校验指定字段
+formRef.value.validate(['name', 'code']).then(...)
+
+// 回调式(老项目迁移代码常见)
+formRef.value.validate((valid, err) => { if (valid) submit() })
+
+// 单字段校验
+formRef.value.validateField('code')
+
+formRef.value.setFieldsValue({ name: 'x' })   // 赋值
+formRef.value.getFieldsValue()                 // 取值
+formRef.value.resetFields()                    // 重置(回到初始值并清校验)
+formRef.value.clearValidate()                  // 只清校验提示
+```
+
+### 校验规则
+
+```js
+const rules = {
+  name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
+  code: [
+    { required: true, message: '请输入编码', trigger: 'blur' },
+    { max: 50, message: '最多 50 个字符', trigger: 'blur' }
+  ],
+  phone: [{ pattern: /^1[3-9]\d{9}$/, message: '手机号格式不正确', trigger: 'blur' }],
+  sort: [{ validator: positiveInteger, trigger: 'blur' }]
+}
+
+// 自定义校验:返回 resolve 通过,reject 报错
+const positiveInteger = (rule, value) => {
+  if (!value) return Promise.resolve()
+  return /^[1-9]+[0-9]*$/.test(value) ? Promise.resolve() : Promise.reject(new Error('请输入正整数'))
+}
+```
+
+规则依赖运行时状态(如"是否必填"跟着开关变)时,用 `computed` 生成 rules:
+
+```js
+const rules = computed(() => ({
+  loginName: [{ required: createAccount.value, message: '请输入账号', trigger: 'blur' }]
+}))
+```
+
+---
+
+## 二、s-form-item
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `label` | String | `''` | 字段标签 |
+| `name` | String / Array | `''` | 校验字段名,须与 `model` 字段一致;数组表示嵌套字段 `['db', 'code']` |
+| `labelWidth` | Number / String | `'100%'` | 单独指定标签宽度 |
+| `full` | Boolean | `false` | 多列布局下独占一整行 |
+
+`name` 必须写,否则 `rules` 里对应的规则不生效、`validate()` 也校验不到这个字段。
+
+隐藏字段照常放:
+
+```vue
+<s-form-item label="id" name="id" v-show="false">
+  <a-input :value="form.id" />
+</s-form-item>
+```
+
+字段级禁用:直接给控件加 `:disabled`,或整体只读时给控件统一传。
+
+布尔类属性(`disabled` / `allowClear` / `showSearch` / `multiple` …)统一传布尔值,用 `!!` 显式转换:`:disabled="!!(cond && obj.id)"`。
+
+---
+
+## 三、s-form-layout(整页表单)
+
+自带标题栏、内容区、底部固定按钮(取消 / 保存),内容区超宽时居中并限宽。
+
+```vue
+<s-form-layout :title="$l('人员-新增')" :loading="spinning" @footer-callback="onFooter">
+  <template #form>
+    <s-form ref="formRef" :model="form" :rules="rules" :column="2">
+      <s-form-item label="姓名" name="name">
+        <a-input v-model:value="form.name" />
+      </s-form-item>
+    </s-form>
+  </template>
+</s-form-layout>
+```
+
+### Props
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `title` | String | 必填 | 页面标题 |
+| `subTitle` | String | `''` | 标题后问号图标的提示文案 |
+| `loading` | Boolean | `false` | 内容区 loading 遮罩 |
+| `showAnchor` | Boolean | `true` | 右侧锚点导航(配 `#collapses` 用) |
+| `goBack` | Boolean | `true` | 显示"取消"按钮 |
+| `isShowSave` | Boolean | `true` | 显示"保存"按钮 |
+| `saveBtnText` | String | `'保存'` | 保存按钮文案 |
+| `width` | String | `'1000px'` | 表单内容区宽度,超出容器时自适应 |
+| `formStyle` | Object | `{}` | 表单区自定义样式 |
+| `steps` | Array | `[]` | 步骤条标题数组,传了才显示步骤区 |
+| `stepDefaultActive` | Number | `0` | 步骤条起始下标 |
+| `stepValid` | Function | — | 切换下一步前的校验,返回 Promise\<Boolean\> |
+| `tabs` | Array | `[]` | 页签配置,传了才显示页签 |
+| `tabKey` | Object | `{ label: 'label', value: 'value' }` | 页签字段映射 |
+
+### 插槽
+
+| 插槽 | 说明 |
+|---|---|
+| `form` | 表单主体(放 `s-form`) |
+| `collapses` | 分组折叠区(放 `s-collapses` + `s-collapses-item`),配 `showAnchor` 自动生成右侧锚点 |
+| `otherBtns` | 标题栏右侧按钮 |
+| `footer` | 底部按钮区追加内容 |
+| `other` | 根节点末尾,通常放弹窗 |
+
+### 事件
+
+`@footer-callback="(type) => {}"`,`type` 取值:
+
+| type | 触发时机 |
+|---|---|
+| `'save'` | 点保存 |
+| `'cancel'` | 点取消(`goBack` 为 true 时) |
+| `'prev'` | 步骤条上一步,第二参为当前步 |
+| `'next'` | 步骤条下一步(`stepValid` 返回 true 才切) |
+
+另有 `@tabsChange="(item) => {}"`,参数是选中的那条 `tabs` 配置。
+
+```js
+const onFooter = (type) => {
+  if (type === 'save') handleSave()
+  if (type === 'cancel') router.back()
+}
+```
+
+### 分组表单
+
+```vue
+<s-form-layout :title="$l('设备台账')">
+  <template #collapses>
+    <s-collapses>
+      <s-collapses-item title="基本信息" :column="2">
+        <s-form-item label="设备名称" name="name"><a-input v-model:value="form.name" /></s-form-item>
+        <s-form-item label="设备编号" name="no"><a-input v-model:value="form.no" /></s-form-item>
+      </s-collapses-item>
+      <s-collapses-item title="扩展信息" :column="3">
+        <s-form-item label="厂商" name="vendor"><a-input v-model:value="form.vendor" /></s-form-item>
+      </s-collapses-item>
+    </s-collapses>
+  </template>
+</s-form-layout>
+```
+
+`s-collapses-item` 属性:`title`(分组标题)、`column`(组内列数,最大 4)、`full`(独占一行)。
+
+> 用 `#collapses` 时 `s-form-item` 的校验仍要挂在一个 `s-form` 上。做法:`#form` 里放一个空的 `s-form` 包裹 `#collapses`,或把整块内容放进 `#form` 里用 `s-collapses` 分隔(推荐后者,校验链完整)。
+
+---
+
+## 四、s-modal(弹窗)
+
+```vue
+<s-modal v-model:value="visible" :title="title" width="50%" :loading="spinning" @handCancel="close">
+  <s-form ref="formRef" :model="form" :rules="rules" :column="2">
+    <s-form-item label="名称" name="name"><a-input v-model:value="form.name" /></s-form-item>
+  </s-form>
+
+  <template #footer>
+    <a-button @click="close">取消</a-button>
+    <a-button type="primary" :loading="spinning" @click="handleSave">保存</a-button>
+  </template>
+</s-modal>
+```
+
+### Props
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | Boolean | `false` | 显隐,`v-model:value` |
+| `title` | String | `''` | 标题(标题栏可拖动窗口) |
+| `width` | String / Number | `'60vw'` | 弹窗宽度 |
+| `loading` | Boolean | `false` | 内容区 loading 遮罩 |
+| `centered` | Boolean | `true` | 垂直居中 |
+| `maskClosable` | Boolean | `true` | 点遮罩关闭 |
+| `mask` | Boolean | `true` | 显示遮罩 |
+| `keyboardOpen` | Boolean | `true` | 支持 Esc 关闭 |
+| `destroyOnClose` | Boolean | `false` | 关闭后销毁内容 |
+| `showFullScreen` | Boolean | `true` | 标题栏显示全屏按钮 |
+| `bodyStyle` | Object | 纵向滚动 | 内容区样式 |
+| `tabs` | Array | `[]` | 页签配置 |
+| `tabKey` | Object | `{ label, value }` | 页签字段映射 |
+| `steps` | Array | `[]` | 步骤条标题数组 |
+| `stepDefaultActive` | Number | `0` | — |
+| `stepValid` | Function | — | 下一步前校验 |
+| `saveBtnText` | String | `'保存'` | 内置底部保存按钮文案 |
+
+### 事件
+
+| 事件 | 说明 |
+|---|---|
+| `update:value` | 显隐变化(`v-model` 自动处理) |
+| `handCancel` | 点右上角关闭 / 遮罩关闭 |
+| `afterClose` | 关闭动画结束 |
+| `handSave` | 用了**内置底部按钮**时点"保存"(自定义 `#footer` 就不触发) |
+
+### 插槽
+
+| 插槽 | 说明 |
+|---|---|
+| `default` | 弹窗内容 |
+| `footer` | 自定义底部按钮;不写则渲染"关闭 + 保存"两个按钮 |
+
+### 弹窗表单标准写法
+
+父页面:
+
+```vue
+<template #other>
+  <FormModal ref="formRef" @reload="reload" />
+</template>
+```
+
+```js
+const formRef = ref(null)
+const reload = () => layoutRef.value.reload()
+const add = () => formRef.value.add()
+const edit = (record) => formRef.value.edit(record.id)
+```
+
+`form.vue`:
+
+```vue
+<s-modal v-model:value="visible" :title="title" width="50%" :loading="spinning">
+  <s-form ref="formRef" :model="form" :rules="rules" :column="2">...</s-form>
+  <template #footer>
+    <a-button @click="close">取消</a-button>
+    <a-button type="primary" :loading="spinning" @click="handleSave">保存</a-button>
+  </template>
+</s-modal>
+```
+
+```js
+const emit = defineEmits(['reload'])
+const visible = ref(false)
+const spinning = ref(false)
+const title = ref('')
+const formRef = ref(null)
+const form = reactive({ id: undefined, name: '' })
+
+const add = () => {
+  title.value = '新增'
+  Object.assign(form, { id: undefined, name: '' })
+  formRef.value?.clearValidate()
+  visible.value = true
+}
+
+const edit = (id) => {
+  title.value = '编辑'
+  spinning.value = true
+  getById(id).then((res) => {
+    Object.assign(form, res)
+    visible.value = true
+  }).finally(() => (spinning.value = false))
+}
+
+const handleSave = () => {
+  formRef.value.validate().then(() => {
+    spinning.value = true
+    save({ ...form }).then(() => {
+      window.$notice.success({ message: '操作成功', description: '保存成功' })
+      visible.value = false
+      emit('reload')
+    }).finally(() => (spinning.value = false))
+  }).catch(() => {})
+}
+
+const close = () => { visible.value = false }
+
+defineExpose({ add, edit })
+```
+
+要点:
+
+- 弹窗自己管 `visible`,对外只暴露 `add()` / `edit(id)`。
+- 保存成功后 `emit('reload')` 让父页面刷新列表,再关弹窗。
+- **不要用 `resetFields()` 清空**:它回到初始值而不是空值,新增/编辑切换容易串数据。要么 `Object.assign` 显式赋值,要么给弹窗加 `destroyOnClose` 让内容重建。
+
+---
+
+## 五、s-drawer(抽屉)
+
+```vue
+<s-drawer v-model:value="visible" title="编辑" mode="right" :width="600" @confirm="handleSave">
+  <s-form ref="formRef" :model="form" :rules="rules">...</s-form>
+</s-drawer>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | Boolean | `false` | 显隐,`v-model:value` |
+| `title` | String | `''` | 标题 |
+| `mode` | String | `'right'` | `right` / `left` / `top` / `bottom` |
+| `width` | Number | `500` | 左右方向宽度 px |
+| `height` | Number | `378` | 上下方向高度 px |
+
+事件:`update:value`、`confirm`(点内置"确定")。插槽:`default`、`footer`(不写则内置"取消 + 确定")。
+
+---
+
+## 六、s-footer-tool-bar(自定义底栏)
+
+不用 `s-form-layout` 但需要贴底按钮条时:
+
+```vue
+<s-footer-tool-bar>
+  <template #extra>
+    <span>共 12 项</span>
+  </template>
+  <a-button @click="close">取消</a-button>
+  <a-button type="primary" @click="save">保存</a-button>
+</s-footer-tool-bar>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `fixed` | Boolean | `true` | 是否贴底固定 |
+| `extra` | String / Object | `''` | 左侧内容(有 `#extra` 插槽时以插槽为准) |
+
+插槽 `#extra` 左区,默认插槽右区。用 `fixed` 时记得给页面内容留底部空间。
+
+---
+
+## 七、s-import-modal(导入弹窗)
+
+列表页 `import` 按钮已内置一个,需要独立调用时:
+
+```vue
+<s-import-modal
+  v-model:value="importVisible"
+  :upload-url="IMPORT_UPLOAD_URL"
+  :columns="importColumns"
+  :apis="{ templateDownload, importPreview, importData, exportExceptionData }"
+  @reload="reload"
+/>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | Boolean | `false` | 显隐,`v-model:value` |
+| `title` | String | `'批量导入'` | — |
+| `width` | String / Number | `1000` | — |
+| `uploadUrl` | String | `''` | 文件上传地址(含网关名) |
+| `columns` | Array | `[]` | 预览表头,接口返回 `headerRow` 后以接口为准 |
+| `apis` | Object | `{}` | `{ templateDownload, importPreview, importData, exportExceptionData }` |
+| `typeSelect` | Object | `null` | 附加下拉 `{ options, value, placeholder, loading }` |
+| `extraKey` | String | `'deviceTypeId'` | 下拉值提交时的字段名 |
+
+事件:`update:value`、`reload`(导入成功)。
+
+---
+
+## 八、详情页
+
+详情用 `s-form-layout` + `s-form`,所有控件统一禁用即可(不用另找展示组件):
+
+```vue
+<s-form-layout :title="$l('详情')" :isShowSave="false" @footer-callback="onFooter">
+  <template #form>
+    <s-form :model="form" :column="2">
+      <s-form-item label="名称"><a-input :value="form.name" disabled /></s-form-item>
+      <s-form-item label="状态">
+        <a-select :value="form.status" disabled>
+          <a-select-option :value="1">启用</a-select-option>
+        </a-select>
+      </s-form-item>
+    </s-form>
+  </template>
+</s-form-layout>
+```
+
+或者用 `s-panel-layout`(只有标题栏 + 内容区,没有底部按钮):
+
+```vue
+<s-panel-layout title="设备详情" height="100%">
+  <div>...</div>
+</s-panel-layout>
+```
+
+`s-panel-layout` 属性:`title`、`showTitle`(默认 true)、`height`(默认 `'100%'`)、`width`(默认 `'100%'`,传固定值则居中)、`headerSticky`(内容滚动时标题吸顶)。插槽:`default`、`title`、`extra`、`footer`。

+ 411 - 0
development/sapit-dev-web/sapit-antd-vue/references/04-组件文档-业务控件.md

@@ -0,0 +1,411 @@
+# 组件文档 · 业务控件
+
+基座已封好的业务级控件,全部全局注册,模板里直接写标签,不用 import。
+
+| 控件 | 用途 |
+|---|---|
+| `s-file-upload` | 图片/文件上传(拖拽排序、预览、下载、删除) |
+| `s-choose-user` | 弹窗选人 |
+| `s-user-select` | 下拉选人 |
+| `s-user-select-button` | 按钮 + 弹窗选人 |
+| `s-office-select` | 岗位选择 |
+| `s-data-range-tree-select` | 组织/校区/单位树选择 |
+| `s-tree-select` | 通用下拉树(自定义数据源) |
+| `s-editor` | 富文本 |
+| `s-tab` | 可横向滚动的标签页 |
+| `s-empty` | 空状态 |
+| `s-icon` | 图标 |
+
+---
+
+## 一、字典下拉(最常用)
+
+字典不单独封组件,用 `$utils` 里的字典方法 + `a-select`。
+
+```js
+// 按类型批量取字典,返回 { 类型转驼峰: [{ label, value, id }] }
+const res = await window.$utils.mapByDictTypes('sys_position_type', 'card_type')
+// res.sysPositionType / res.cardType
+```
+
+```vue
+<a-select
+  v-model:value="form.type"
+  :allowClear="true"
+  :showSearch="true"
+  :filterOption="$utils.filterSelectOption"
+  placeholder="请选择岗位类型"
+  style="width: 100%"
+>
+  <a-select-option v-for="item in types" :key="item.value" :value="item.value">
+    {{ item.label }}
+  </a-select-option>
+</a-select>
+```
+
+```js
+const types = ref([])
+onMounted(async () => {
+  const res = await window.$utils.mapByDictTypes('sys_position_type')
+  types.value = res.sysPositionType || []
+})
+```
+
+字典工具(`window.$utils.*`):
+
+| 方法 | 说明 |
+|---|---|
+| `mapByDictTypes(...类型)` | 批量取字典,返回 `{ 驼峰类型名: [{ label, value, id }] }` |
+| `dictTypes()` | 字典类型清单 |
+| `toDictOptions(list)` | 转 `[{ label, value }]` |
+| `dictName(list, value)` | 按字典值取文案,取不到返回 `'--'` |
+| `filterSelectOption(inputValue, option)` | `a-select` 本地搜索的 `filterOption` 回调 |
+
+**下拉的 `value` 一律用字典项的 `value`(字典值),不要用 `id`(主键)。**
+
+---
+
+## 二、s-file-upload(上传)
+
+```vue
+<s-file-upload
+  path="sysEmployee"
+  :list="fileList"
+  :maxFileCount="1"
+  accept="image/*"
+  listType="card"
+  @handChange="onFileChange"
+/>
+```
+
+```js
+const fileList = ref([])
+const onFileChange = (list) => { fileList.value = list }
+```
+
+### Props
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `list` | Array | `[]` | 文件列表,见下方项结构 |
+| `label` | String | `''` | 控件上方标题 |
+| `accept` | String | `'image/*'` | 可选文件类型,如 `.pdf,.docx` 或 `image/*` |
+| `listType` | String | `'card'` | `card` 卡片(图片显原图)/ `list` 列表(图标 + 文件名) |
+| `maxFileCount` | Number | `5` | 最多文件数 |
+| `fileSize` | Number | `200` | 单文件大小上限,**单位 KB** |
+| `path` | String | — | 上传目录,一般传业务表名 |
+| `businessKey` | String | — | 业务主键,随上传一起提交 |
+| `readonly` | Boolean | `false` | 只读(不能加/删/拖) |
+| `detailMode` | Boolean | `false` | 详情模式:只留预览和下载入口 |
+| `isAdd` | Boolean | `true` | `false` 隐藏新增入口 |
+| `showPreview` | Boolean | `true` | 显示预览按钮 |
+| `showDownload` | Boolean | `true` | 显示下载按钮 |
+| `showRemove` | Boolean | `true` | 显示删除按钮 |
+| `noDrag` | Boolean | `false` | 关闭拖拽排序 |
+| `picStyle` | Object | `{}` | 列表容器样式 |
+
+### 事件
+
+| 事件 | 参数 | 说明 |
+|---|---|---|
+| `handChange` | `fileList` | 上传/删除/排序后触发,**用这个** |
+| `change` | `fileList` | 同上(历史别名) |
+| `dragChange` | `fileList` | 拖拽排序后 |
+| `download` | `record` | 点下载 |
+
+### 列表项结构
+
+```js
+{ uid: '唯一标识', url: '文件地址', imageUrl: '图片地址', name: '文件名', type: 'image/png', sort: 1 }
+```
+
+回显后端数据时按这个结构拼:
+
+```js
+fileList.value = res.imageUrl
+  ? [{ uid: res.imageUrl, url: res.imageUrl, imageUrl: res.imageUrl, name: '照片', sort: 1 }]
+  : []
+```
+
+提交时取 `fileList.value.map(i => i.imageUrl || i.url)`。
+
+---
+
+## 三、s-choose-user(弹窗选人)
+
+点输入框弹出选人窗口,适合表单里选一个/多个人。
+
+```vue
+<s-choose-user
+  v-model:value="chooseVisible"
+  v-model:selectedIds="form.userIds"
+  :multiple="true"
+  @callback="onUserSelected"
+/>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | Boolean | `false` | 弹窗显隐,`v-model:value` |
+| `selectedIds` | Array | `[]` | 多选回显,`v-model:selectedIds` |
+| `selectedId` | String | `''` | 单选回显,`v-model:selectedId` |
+| `multiple` | Boolean | `false` | 是否多选 |
+| `required` | Boolean | `false` | 未选时提示"请选择人员" |
+| `title` | String | `'选择人员'` | 弹窗标题 |
+| `searchPlaceholder` | String | 按姓名/工号/手机号搜索 | 搜索框占位 |
+
+事件 `@callback="(list) => {}"`,`list` 是选中人员的完整对象数组,确认时触发;直接关闭时回调不带参数,形参给默认值 `[]`:
+
+```js
+const onUserSelected = (list = []) => {
+  form.userIds = list.map((i) => i.id)
+  form.userNames = list.map((i) => i.name).join('、')
+}
+```
+
+---
+
+## 四、s-user-select(下拉选人)
+
+表单里最常用的选人控件,外观是下拉框,点开是选人面板。
+
+```vue
+<s-user-select
+  v-model:value="form.superiorLeaderId"
+  :multiple="false"
+  placeholder="请选择上级领导"
+  @change="onLeaderChange"
+/>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | String / Array | `''` | 单选为 id 字符串,多选为 id 数组 |
+| `multiple` | Boolean | **`true`** | **默认多选,单选必须显式传 `:multiple="false"`** |
+| `placeholder` | String | `'请选择'` | — |
+| `title` | String | `'人员选择'` | 弹窗标题 |
+
+事件 `@change="(tags, nameList, idList, list) => {}"`:
+
+| 参数 | 内容 |
+|---|---|
+| `tags` | 选中的显示文本(数组) |
+| `nameList` | 姓名数组 |
+| `idList` | id 数组 |
+| `list` | 完整对象数组(要存姓名时用这个) |
+
+```js
+const onLeaderChange = (tags, nameList, idList, list) => {
+  const one = list && list[0]
+  form.superiorLeaderId = one ? one.id : ''
+  form.superiorLeaderName = one ? one.name : ''
+}
+```
+
+---
+
+## 五、s-user-select-button(按钮选人)
+
+栅格/卡片里选人,或者需要"选择人员"按钮而不是输入框时用。
+
+```vue
+<s-user-select-button
+  v-model:value="form.memberIds"
+  :multiple="true"
+  buttonText="选择人员"
+  type="primary"
+  @change="onMembersChange"
+/>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | String / Array | `''` | 同 `s-user-select` |
+| `multiple` | Boolean | `true` | — |
+| `buttonText` | String | `'选择人员'` | 按钮文案 |
+| `type` | String | `'default'` | `default` / `primary` / `dashed` / `link` / `text` |
+| `size` | String | `'middle'` | `large` / `middle` / `small` |
+| `disabled` | Boolean | `false` | — |
+| `title` | String | `'人员选择'` | 弹窗标题 |
+| `placeholder` | String | — | 未选时文案 |
+
+事件 `@change` 参数同 `s-user-select`。
+
+---
+
+## 六、s-office-select(岗位选择)
+
+```vue
+<s-form-item label="主岗" name="mainPositionId">
+  <s-office-select v-model:value="form.mainPositionId" :multiple="false" placeholder="请选择主岗" />
+</s-form-item>
+<s-form-item label="副岗" name="deputyPositionIds">
+  <s-office-select v-model:value="form.deputyPositionIds" :multiple="true" placeholder="请选择副岗" />
+</s-form-item>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | String / Array | — | 单选为 id,多选为 id 数组 |
+| `multiple` | Boolean | **`true`** | **默认多选,单选显式传 false** |
+| `placeholder` | String | `'请选择'` | — |
+| `title` | String | `'岗位选择'` | 弹窗标题 |
+
+事件 `@change="(tags, nameList, idList, list) => {}"`,参数同 `s-user-select`。
+
+---
+
+## 七、s-data-range-tree-select(组织树选择)
+
+组织 / 校区 / 单位三合一的树选择器,支持数据权限过滤。
+
+```vue
+<!-- 选组织(带数据权限) -->
+<s-data-range-tree-select
+  v-model:value="form.campusIds"
+  :treeCheckable="false"
+  :showOnlyOrganization="true"
+  :isDataScopeFilter="true"
+  :maxTagCount="1"
+  @change="onCampusChange"
+/>
+
+<!-- 选单位(数据源来自上级组织,禁用校区和单位分组) -->
+<s-data-range-tree-select
+  v-model:value="form.unitIds"
+  :treeSelectData="units"
+  :disabledGroup="['1', '2']"
+  :maxTagCount="1"
+/>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | String / Array | `null` | 选中的组织 id 集合(**一般用数组**) |
+| `treeSelectData` | Boolean / Array | `false` | 传数组则不请求接口,直接用这个数据源 |
+| `showOnlyOrganization` | Boolean | `false` | 只显示组织层级 |
+| `isDataScopeFilter` | Boolean | `false` | 按当前用户数据权限过滤 |
+| `autoSysConfig` | Boolean | `false` | 数据范围跟随系统配置(`dataScope`) |
+| `defaultValue` | Boolean | `true` | 默认选中当前登录用户组织(仅 `showOnlyOrganization` 生效) |
+| `disabledGroup` | String / Array | `''` | 禁用某类节点:`'1'` 组织 / `'2'` 校区 / `'3'` 单位,可传数组 |
+| `multiple` | Boolean | `false` | 是否多选 |
+| `treeCheckable` | Boolean | `false` | 是否显示复选框 |
+| `maxTagCount` | Number | `1` | 最多显示几个 tag |
+| `allowClear` | Boolean | `true` | 可清空 |
+| `showSearch` | Boolean | `true` | 可搜索 |
+| `treeDefaultExpandAll` | Boolean | `true` | 默认展开全部 |
+| `placeholder` | String | `''` | — |
+
+事件 `@change="(val) => {}"`,`val` 是选中的 id 数组。
+
+> `treeCheckable` 为 `false` 时返回的仍是数组(如 `[id]`),取值时按数组处理。
+
+---
+
+## 八、s-tree-select(通用下拉树)
+
+数据源完全自定义,适合分类、部门、地区这类自己管数据的树。
+
+```vue
+<s-tree-select
+  v-model:value="form.categoryId"
+  :recursionChildren="loadChildren"
+  :props="{ label: 'name', value: 'id', children: 'children' }"
+  :expandAll="true"
+  placeholder="请选择分类"
+/>
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `value` | String / Array | `''` | 选中值 |
+| `recursionChildren` | Function | — | 取数函数,入参是父节点 id |
+| `props` | Object | `{ children: 'children', label: 'name', value: 'value' }` | 节点字段映射 |
+| `multiple` | Boolean | `false` | 多选 |
+| `maxTagCount` | Number | `1` | — |
+| `search` | Boolean | `true` | 可搜索 |
+| `filterField` | String | `'name'` | 搜索匹配字段 |
+| `clear` | Boolean | `true` | 可清空 |
+| `expandAll` | Boolean | `false` | 默认展开全部 |
+| `appendRootNodeAll` | Boolean | `false` | 加一个"全部"根节点 |
+| `disabled` | Boolean | `false` | — |
+| `listHeight` | Number | `232` | 下拉列表高度 px |
+
+---
+
+## 九、s-editor(富文本)
+
+```vue
+<s-editor v-model="form.content" :config="{ minHeight: 300 }" />
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `modelValue` | String | `''` | HTML 字符串,`v-model` |
+| `config` | Object | `{}` | jodit 配置覆盖项 |
+
+内容存 HTML,展示时用 `v-html`。富文本里的图片地址依赖 `VITE_APP_PC_HOST` 配置。
+
+---
+
+## 十、s-tab(可滚动标签页)
+
+标签多时自动出左右箭头,比 `a-tabs` 更适合列表页顶部。
+
+```vue
+<s-tab v-model:activeKey="activeKey" :tabs="tabs" @change="onTabChange">
+  <!-- 或自定义标签内容 -->
+</s-tab>
+
+<s-tab v-model:activeKey="activeKey">
+  <s-tab-item value="all" label="全部" />
+  <s-tab-item value="mine" label="我的" />
+</s-tab>
+```
+
+`s-tab` 属性:`tabs`(`[{ label, value }]`)、`activeKey`(`v-model:activeKey`)、`defaultActiveKey`、`tabKey`(字段映射)、`stepRatio`(滚动步长)。
+`s-tab-item` 属性:`value`、`label`(也可用默认插槽放富内容)。
+
+---
+
+## 十一、s-empty(空状态)
+
+```vue
+<s-empty :desc="$l('暂无数据')" />
+```
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `type` | String / Number | `1` | 插画风格 |
+| `icon` | String / Object | `''` | 自定义图标 |
+| `desc` | String / Boolean | — | 描述文案,传 `false` 不显示 |
+| `iconStyle` | Object | `{}` | 图标样式 |
+
+---
+
+## 十二、s-icon(图标)
+
+```vue
+<s-icon type="plus" />
+<s-icon type="check" :style="{ color: 'var(--s-color-success)' }" />
+```
+
+`type` 支持 kebab 写法(`info-circle`)或 Pascal 名(`InfoCircleOutlined`),内部会转成图标组件。也可以直接用 `$icons` 或从 `@ant-design/icons-vue` import。
+
+---
+
+## 十三、其他可直接用的基座组件
+
+| 组件 | 用途 |
+|---|---|
+| `s-extend-fields-form` | 扩展字段表单(`data` + `defaultValue` + `column`,方法 `validate()` / `getModel()`) |
+| `s-cascader` | 级联选择 |
+| `s-color-picker` | 颜色选择 |
+| `s-import-modal` | 导入弹窗(见 03 文档) |
+| `s-list-card-layout` | 卡片列表 |
+| `s-list-table-tree-layout` | 表格树列表 |
+| `s-super-list-layout` | 左右主从列表 |
+| `s-anchor` | 锚点导航(`s-form-layout` 已内置) |
+| `s-upload` 相关 | 统一用 `s-file-upload` |
+
+antd 原生组件(`a-input`、`a-select`、`a-date-picker`、`a-switch`、`a-radio-group`、`a-checkbox`、`a-textarea`、`a-input-number`、`a-upload` 等)全部可直接使用,无需引入。

+ 312 - 0
development/sapit-dev-web/sapit-antd-vue/references/05-工具配置文档.md

@@ -0,0 +1,312 @@
+# 工具配置文档
+
+## 一、命令
+
+| 命令 | 作用 |
+|---|---|
+| `npm run dev`(或 `yarn dev`) | 起开发服务,端口见 `vite.config.js` |
+| `npm run start` | 先跑 `refresh-mode.ps1` 重新拉基座依赖,再起服务。基座发了新版用这个 |
+| `npm run build` | 先跑 `refresh-build.ps1` 拉依赖,再 `vite build` 出 `dist` |
+| `npm run preview` | 本地预览 `dist` |
+| `npm run lint` | ESLint 自动修 |
+| `npm run format` | Prettier 格式化 `src/` |
+
+包管理统一用 `yarn@1.22.22`(`package.json` 里 `packageManager` 已锁定)。
+
+---
+
+## 二、环境变量
+
+三个文件,后者覆盖前者:`.env`(公共)→ `.env.development` / `.env.production`(环境差异)。
+
+| 变量 | 示例 | 说明 |
+|---|---|---|
+| `NODE_ENV` | `development` | 环境标识 |
+| `VITE_APP_API_BASE_URL` | `http://192.168.200.7:6801/` | 后端服务地址。开发填真实地址,生产留空走 nginx 同源 |
+| `VITE_APP_API_PATH` | `/apig` | 接口统一前缀,与 `BASE_URL` 拼成请求 baseURL |
+| `VITE_APP_API_FILE_URL` | 空 | 文件服务地址(头像、附件预览) |
+| `VITE_APP_SOCKET_URL` | 同 BASE_URL | WebSocket 地址 |
+| `VITE_APP_PREVIEW_ONLINE` | `/filePreview/onlinePreview?url=` | 附件在线预览前缀 |
+| `VITE_APP_BASE_URL` | `/` | 部署子路径,如 `/portal/` |
+| `VITE_APP_CLIENT_ID` | `mm0001` | 认证中心 clientId,每个项目不同 |
+| `VITE_APP_SYS_SERVER_NAME` | `portal` | **业务网关名**,接口 url 前缀就用它 |
+| `VITE_APP_PORTAL_SERVER_NAME` | `portal` | 平台网关(组织、用户、字典、文件接口都在这个网关) |
+| `VITE_APP_MESSAGE_SERVER_NAME` | `message` | 消息网关 |
+| `VITE_APP_FLOW_SERVER_NAME` | `flow` | 工作流网关 |
+| `VITE_APP_PROJECT_NAME` | `平台系统` | 系统名 |
+| `VITE_APP_TITLE` | `统一认证中心` | 浏览器页签标题 |
+| `VITE_APP_VERSION` | `v1.0` | 版本号,页脚展示 |
+| `VITE_APP_LOGIN_PHONE` | `false` | 登录页显示手机号登录 |
+| `VITE_APP_LOGIN_QRCODE` | `false` | 登录页显示扫码登录 |
+| `VITE_APP_LOGIN_PATH_THEME` | `4` | 登录页版式(1 左图右表单 / 2 左表单右背景 / 3 居中表单 / 4 模版默认版式) |
+| `VITE_APP_LOGIN_CASE_NAME` | `辽ICP备...` | 登录页备案号 |
+| `VITE_APP_BASE_CASE_NAME` | 同上 | 系统页脚备案号 |
+| `VITE_APP_FOOTER_VISIBLE` | `false` | 是否显示页脚 |
+| `VITE_APP_MESSAGE_VISIBLE` | `true` | 右上角消息铃铛 |
+| `VITE_APP_LANG_ENABLE` | `false` | 是否启用国际化(关掉时 `$l` 直接返回中文) |
+| `VITE_APP_LANG` | `zh` | 默认语言 `zh` / `en` |
+| `VITE_APP_MENU_THEME` | `dark` | 菜单主题 `dark` / `light` |
+| `VITE_APP_MENU_BAR` | `left` | 菜单位置 `left` / `top` |
+| `VITE_APP_THEME_VALUE` | `blue` | 主题色名,取值由基座主题表提供 |
+| `VITE_APP_PC_HOST` | 空 | PC 访问地址,富文本图片地址替换用 |
+| `VITE_APP_WEB_SITE` | 空 | 官网地址 |
+| `VITE_APP_JSS_LICENSE` | 空 | JSSDK license |
+
+改完环境变量必须重启 `vite`(`.env` 不进热更新)。
+
+---
+
+## 三、三层配置
+
+| 层 | 文件 | 什么时候改 | 改完怎么生效 |
+|---|---|---|---|
+| 基座默认 | 无 | 不改 | — |
+| 项目配置 | `src/config/web-config.js`、`src/config/app-config.js` | 开发期 | 重启服务 |
+| 部署配置 | 构建产物根目录的 `config.json` | 上线后 | 改完刷新浏览器即生效 |
+
+优先级:**基座默认 < 项目配置 < 部署 `config.json`**。
+
+部署后要调网关地址、标题这类值,改部署目录里的 `config.json`;改 `web-config.js` 只对下一次构建生效。同名键以 `config.json` 为准。
+
+### web-config.js
+
+运行时可改的纯值配置。字段与 `.env` 一一对应,从 `import.meta.env` 取值:
+
+```js
+export default {
+  VITE_APP_PROJECT_NAME: import.meta.env?.VITE_APP_PROJECT_NAME,
+  VITE_APP_TITLE: import.meta.env?.VITE_APP_TITLE,
+  VITE_APP_API_BASE_URL: import.meta.env?.VITE_APP_API_BASE_URL,
+  VITE_APP_API_PATH: import.meta.env?.VITE_APP_API_PATH,
+  VITE_APP_SYS_SERVER_NAME: import.meta.env?.VITE_APP_SYS_SERVER_NAME,
+  // 业务自定义的默认首页
+  VITE_APP_DEFAULT_PATH: '/workplace/index',
+  // 仅开发时显示基座 demo 页(业务项目必须 false)
+  VITE_APP_IS_BASE: false
+}
+```
+
+这些值在 `vite build` 时被写进 `dist/config.json`,部署后可以直接改这个 json 调整网关地址、标题、默认首页。
+
+### app-config.js
+
+构建期配置,**含函数和组件,不进 config.json**,部署后不可改。
+
+```js
+export default {
+  // 覆盖基座自带的登录页 / 首页(不配则用基座的)
+  components: {
+    login: () => import('@/views/default/login/index.vue'),
+    home: () => import('@/views/default/home/index.vue')
+  },
+
+  // 不依赖后端菜单的固定页面
+  staticRoutes: [
+    {
+      path: '/developmentProcess',
+      name: 'developmentProcess',
+      layout: false,
+      component: () => import('@/views/static/page/DevelopmentProcess.vue'),
+      meta: { title: '开发流程', public: true, hidden: true }
+    }
+  ],
+
+  // 业务语言包:views/<模块>/i18n.js 与 locales/**/i18n.js 自动收集
+  locales: import.meta.glob(['@/views/**/i18n.js', '@/locales/**/i18n.js'], { eager: true })
+}
+```
+
+`main.js` 把 `web-config` 和 `app-config` 合并后交给基座的 `$registerGlobalConfig`,这一句不要改:
+
+```js
+await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)
+```
+
+---
+
+## 四、vite.config.js
+
+大部分保持模版原样,只动这几处:
+
+| 位置 | 说明 |
+|---|---|
+| `base` | 取自 `VITE_APP_BASE_URL`,子路径部署时改 env |
+| `server.port` | 开发端口,**每个项目不一样** |
+| `server.strictPort: true` | 端口被占直接启动失败而不是自动换端口,改了会让联调地址对不上 |
+| `server.proxy['/apig'].target` | 取 `VITE_APP_API_BASE_URL`,开发跨域靠它 |
+| `resolve.alias['@']` | 指向 `src`,不要动 |
+| `resolve.dedupe` | `vue` / `vue-router` / `pinia` / `vue-i18n` / `ant-design-vue` 必须保留 |
+| `optimizeDeps.exclude` | `sapit-ui-plus`、`sapit-ui-components` 必须保留 |
+| `build.outDir` | `dist` |
+| `build.target` | `es2015`,兼容老浏览器 |
+
+```js
+server: {
+  port: 6599,        // 每个项目改这一个
+  strictPort: true,
+  host: '0.0.0.0',
+  proxy: {
+    '/apig': { target: getViteEnv(res.mode, 'VITE_APP_API_BASE_URL'), changeOrigin: true }
+  }
+}
+```
+
+`dedupe` 和 `optimizeDeps.exclude` 是保证基座和业务共用同一份 vue / router / pinia 实例的开关,删了会出现路由跳不动、store 读写不生效这类怪现象。
+
+构建产物除静态资源外还会生成 `config.json`(由 `web-config.js` + env 合成,已格式化成多行便于手改)。
+
+---
+
+## 五、请求层
+
+### 用法
+
+业务统一用 `window.$utils.http`,不自己装 axios、不自己建实例。
+
+```js
+window.$utils.http({
+  url: `/${window.$utils.env.VITE_APP_SYS_SERVER_NAME}/position/page`,
+  data: { pageNum: 1, pageSize: 20 }
+})
+```
+
+### 行为
+
+| 项 | 说明 |
+|---|---|
+| baseURL | `VITE_APP_API_BASE_URL`(去尾斜杠)+ `VITE_APP_API_PATH`,开发环境下即 `http://后端:端口/apig` |
+| 默认 method | **`post`**,需要 GET 时显式写 `method: 'get'` |
+| 请求头 | 自动带 `user-token`、`client-id`、`user-router`(当前路由),不要手动加 |
+| 超时 | 120 秒 |
+| 返回值 | 后端 `{ status: 1, data }` → 直接拿到 **`data`**,已经解包 |
+| `status: 0` | 弹错误通知并 `reject`,业务只需 `.catch()` |
+| `status: -1` | 登录超时,自动跳登录页并 `reject` |
+| 文件响应 | 响应是 zip/pdf/图片时自动触发浏览器下载 |
+
+所以业务代码里**不要再判断 `res.status` / `res.code`**,拿到的就是业务数据:
+
+```js
+const list = await pageApi(query)   // 直接是 { list, total }
+```
+
+### api 文件写法
+
+按后端模块建文件,放 `src/api/`:
+
+```js
+// src/api/position.js
+const gateway = () => window.$utils.env.VITE_APP_SYS_SERVER_NAME
+
+// 分页列表:query 是页面查询条件,parameter 是表格传的分页排序对象
+export function page(query = {}, parameter = {}) {
+  return window.$utils.http({
+    url: `${gateway()}/position/page`,
+    data: {
+      ...query,
+      pageNum: parameter.pageNo,
+      pageSize: parameter.pageSize,
+      sortField: parameter.sortField,
+      sortOrder: parameter.sortOrder
+    }
+  })
+}
+
+export function getById(id) {
+  return window.$utils.http({
+    url: `${gateway()}/position/getById?id=${id}`,
+    method: 'get'
+  })
+}
+
+export function save(data) {
+  return window.$utils.http({
+    url: `${gateway()}/position/save`,
+    data
+  })
+}
+
+export function deleteById(id) {
+  return window.$utils.http({
+    url: `${gateway()}/position/deleteById?id=${id}`,
+    method: 'get'
+  })
+}
+
+// 批量删除:接收选中行 key 数组(列表工具栏 remove 按钮直接调它)
+export function deleteByIds(ids = []) {
+  return window.$utils.http({
+    url: `${gateway()}/position/deleteByIds`,
+    data: ids
+  })
+}
+
+// 导出:响应是文件流,浏览器会自动下载
+export function exportExcel(query = {}) {
+  return window.$utils.http({
+    url: `${gateway()}/position/exportExcel`,
+    data: query
+  })
+}
+
+// 上传地址(给 s-file-upload / 导入弹窗用,需要完整前缀)
+export const IMPORT_UPLOAD_URL = `${window.$utils.env.VITE_APP_API_BASE_URL || ''}${window.$utils.env.VITE_APP_API_PATH || ''}/${window.$utils.env.VITE_APP_SYS_SERVER_NAME}/position/import`
+```
+
+页面里:
+
+```js
+import { page as pageApi, save, getById, deleteById } from '@/api/position'
+```
+
+### 网关选择
+
+| 接口类型 | 用哪个网关变量 |
+|---|---|
+| 业务自己的接口 | `VITE_APP_SYS_SERVER_NAME` |
+| 组织、用户、角色、字典、文件、参数 | `VITE_APP_PORTAL_SERVER_NAME` |
+| 消息、待办 | `VITE_APP_MESSAGE_SERVER_NAME` |
+| 工作流 | `VITE_APP_FLOW_SERVER_NAME` |
+
+### 文件上传
+
+```js
+const formData = new FormData()
+formData.append('file', file)
+window.$utils.http({
+  url: `/${window.$utils.env.VITE_APP_PORTAL_SERVER_NAME}/file/upload?businessTableName=xxx&uid=${uid}`,
+  data: formData,
+  headers: { 'Content-Type': 'multipart/form-data' }
+})
+```
+
+表单里的上传直接用 `s-file-upload`,它会处理好这些。
+
+---
+
+## 六、主题与布局
+
+| 需求 | 改哪里 |
+|---|---|
+| 主题色 | `.env` 的 `VITE_APP_THEME_VALUE`(值由基座主题表定义,默认 `blue`) |
+| 菜单深/浅色 | `VITE_APP_MENU_THEME` = `dark` / `light` |
+| 菜单在左/在顶 | `VITE_APP_MENU_BAR` = `left` / `top` |
+| 登录页版式 | `VITE_APP_LOGIN_PATH_THEME` |
+| 默认首页 | `web-config.js` 的 `VITE_APP_DEFAULT_PATH` |
+| 页脚 / 备案号 | `VITE_APP_FOOTER_VISIBLE`、`VITE_APP_BASE_CASE_NAME` |
+| 全局样式变量 | `src/assets/main.less`(CSS 变量以 `--s-` 开头,如 `var(--s-color-success)`) |
+
+代码里取主题对象用 `window.$theme`,不要自己写色值:
+
+```vue
+<span style="color: var(--s-color-success)">启用</span>
+```
+
+常用 CSS 变量:`--s-bg-color-container`、`--s-bg-color`、`--s-text-color-regular`、`--s-border-color-split`、`--s-color-success`、`--s-color-error`、`--s-menu-bg`。
+
+---
+
+## 七、基座有新版时
+
+1. 改 `package.json` 里 `sapit-ui-plus` 的版本或分支(当前是 `git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git`)
+2. `npm run start`(会先执行 `refresh-mode.ps1` 重新拉取依赖)
+3. 起不来先删 `node_modules/.vite` 缓存再试

+ 99 - 0
development/sapit-dev-web/sapit-antd-vue/references/06-字段控件映射.md

@@ -0,0 +1,99 @@
+# 字段控件映射
+
+用户说「XX 字段」时,按下表直接落成控件 + 校验 + 列渲染,不用再问。
+
+---
+
+## 一、类型对照表
+
+| 用户说的类型 | 表单控件 | 必传属性 | 列表列 |
+|---|---|---|---|
+| 文本 / 名称 / 编码 | `<a-input>` | `:maxlength="50"`、`autocomplete="off"`、`placeholder` | `ellipsis: true` |
+| 长文本 / 备注 / 描述 | `<a-textarea>` | `:rows="3"`、`full`、`:maxlength="255"` | `ellipsis: true`,或不显示 |
+| 数字 / 排序 / 数量 | `<a-input-number>` | `:precision="0"`、`:min="0"`、`style="width: 100%"` | `width: 80`、`align: 'center'` |
+| 金额 / 价格 | `<a-input-number>` | `:precision="2"`、`:min="0"`、`:step="0.01"` | `width: 120`、`align: 'right'` |
+| 百分比 | `<a-input-number>` | `:precision="2"`、`:min="0"`、`:max="100"` | `align: 'right'`,后缀 `%` |
+| 日期 | `<a-date-picker>` | `value-format="YYYY-MM-DD"`、`style="width: 100%"` | `width: 120`、`align: 'center'` |
+| 日期时间 | `<a-date-picker>` | `show-time`、`value-format="YYYY-MM-DD HH:mm:ss"` | `width: 180` |
+| 日期区间 | `<a-range-picker>` | `value-format="YYYY-MM-DD"`、`style="width: 100%"` | 拆成两个字段或 `ellipsis` |
+| 时间 | `<a-time-picker>` | `value-format="HH:mm:ss"` | `width: 100` |
+| 字典下拉 | `<a-select>` + `mapByDictTypes` | `:allowClear`、`:showSearch`、`:filterOption="$utils.filterSelectOption"` | `template: true`,插槽里显示 `label` |
+| 固定枚举(2~4 个) | `<a-select>` + 手写 `<a-select-option>` | 同上 | `template: true`,配 `a-tag` |
+| 单选 / 是否 | `<a-radio-group>` | 选项 ≤ 4 个时用它,不用下拉 | `template: true`,显示文字 |
+| 开关 / 启用状态 | `<a-switch>` | `v-model:checked`,提交时转 `1 / 0` | `template: true`,配 `a-tag` |
+| 多选 | `<a-select mode="multiple">` 或 `<a-checkbox-group>` | `:maxTagCount="3"` | 数组 `join('、')` |
+| 组织 / 校区 / 单位 | `<s-data-range-tree-select>` | `:treeCheckable="false"`、`:maxTagCount="1"`;带数据权限加 `:isDataScopeFilter="true"` | `ellipsis: true` |
+| 人员(单选) | `<s-user-select>` | **必须** `:multiple="false"`(默认多选) | 显示姓名 |
+| 人员(多选) | `<s-user-select>` | `:multiple="true"` | 姓名 `join('、')` |
+| 人员(按钮式) | `<s-user-select-button>` | `buttonText`、`:multiple` | — |
+| 岗位 | `<s-office-select>` | **必须**显式传 `:multiple` | 显示岗位名 |
+| 自定义树(分类 / 地区) | `<s-tree-select>` | `:recursionChildren`、`:props` | 显示名称 |
+| 附件 / 文件 | `<s-file-upload>` | `path`(业务表名)、`:maxFileCount`、`accept` | 显示「N 个附件」或图标 |
+| 图片 / 头像 | `<s-file-upload>` | `accept="image/*"`、`listType="card"`、`:maxFileCount="1"` | 缩略图插槽 |
+| 富文本 / 正文 | `<s-editor>` | `v-model`、`:config="{ minHeight: 300 }"`、`full` | 不显示或截断 |
+| 级联(省市区等) | `<s-cascader>` | `:options` | `ellipsis: true` |
+| 密码 | `<a-input-password>` | `:maxlength="32"`、`autocomplete="new-password"` | 不显示 |
+
+---
+
+## 二、校验规则模板
+
+| 类型 | rules |
+|---|---|
+| 必填文本 | `{ required: true, message: '请输入名称', trigger: 'blur' }` |
+| 限长 | `{ max: 50, message: '最多 50 个字符', trigger: 'blur' }` |
+| 必选(下拉 / 日期 / 树 / 选人) | `{ required: true, message: '请选择状态', trigger: 'change' }` |
+| 手机号 | `{ pattern: /^1[3-9]\d{9}$/, message: '手机号格式不正确', trigger: 'blur' }` |
+| 邮箱 | `{ type: 'email', message: '邮箱格式不正确', trigger: 'blur' }` |
+| 正整数 | 自定义 validator,见 `03-组件文档-表单与弹窗.md` |
+| 数字范围 | `{ type: 'number', min: 0, max: 999999, message: '超出范围', trigger: 'blur' }` |
+
+文案规则:输入类 `请输入XX`,选择类 `请选择XX`,与 `label` 保持一致。
+
+---
+
+## 三、列配置速查
+
+```js
+const columns = ref([
+  { title: '名称', dataIndex: 'name', ellipsis: true, template: true },  // 需要自定义渲染才加 template
+  { title: '编码', dataIndex: 'code', ellipsis: true },
+  { title: '状态', dataIndex: 'status', width: 100, align: 'center', template: true },
+  { title: '创建时间', dataIndex: 'createTime', width: 180, align: 'center' },
+  { title: '操作', dataIndex: 'action', width: 160, align: 'center', fixed: 'right' }
+])
+```
+
+- `template: true` → 必须配同名插槽 `<template #列dataIndex="{ record }">`,插槽名就是 `dataIndex`。
+- 操作列固定 `width: 160` 起(每多一个按钮加 60),`fixed: 'right'`。
+- 长文本列一律 `ellipsis: true`,不加就直接撑破表格。
+- 时间列统一 `width: 180`,日期 `120`,状态 `100`,排序 `80`。
+
+---
+
+## 四、查询区怎么排
+
+| 条件 | 放哪 |
+|---|---|
+| 名称 / 编码类模糊查询 | `#filter`,`a-input` + `@pressEnter="paramChange"` |
+| 状态 / 类型下拉 | `#filter`,`a-select` + `@change="paramChange"` |
+| 日期区间 | `#filterMore`(放更多里,别占主行) |
+| 组织 / 分类 | 主查询区用 `s-data-range-tree-select`,或做成左侧树 |
+| 是否包含下级 | `#filterMore`,`a-checkbox` + `:isNormal="false"` |
+| 超过 4 个条件 | 前 3~4 个放 `#filter`,其余全放 `#filterMore` |
+
+每个查询控件都要绑 `@change`(输入框用 `@pressEnter`)触发 `paramChange`,它内部调 `reload()`。
+重置时要把 `queryParam` 整体 `Object.assign` 回初始值,再 `reload()`。
+
+---
+
+## 五、字段命名与提交转换
+
+| 场景 | 规则 |
+|---|---|
+| 组织树返回值 | 组件返回**数组**,表单里存 `officeIds`,提交前转标量 `officeId = officeIds[0]` |
+| 开关 | 表单用布尔 `status: true`,提交转 `1 / 0`;回显 `!!res.status` |
+| 选人 | 只存 id 不够,展示用的姓名另外存 `xxxName` 字段(`@change` 里一并赋值) |
+| 多选 | 提交数组,不要 `join(',')`,除非后端明确要字符串 |
+| 附件 | 提交 `fileList.map(i => i.imageUrl || i.url).join(',')`,回显按数组结构拼 |
+| 后端返回前缀 `is` | `isEnable` 类似字段按布尔处理,`!!` 转换 |

+ 170 - 0
development/sapit-dev-web/sapit-antd-vue/references/07-材料解析.md

@@ -0,0 +1,170 @@
+# 材料解析(需求 / 原型 / 表结构 → 字段清单)
+
+用户通常给三类材料,**先解析成字段清单,再生成代码**,不要拿着材料直接写页面。
+
+| 材料 | 从里面取 | 权威范围 |
+|---|---|---|
+| 需求文档(md / doc / docx) | 业务规则、必填、校验、默认值、状态流转、按钮 | 规则与文案 |
+| 原型(vue + mock.js) | 页面结构、查询条件、列、表单分组、控件形态、字段名 | 控件与布局 |
+| 表结构(`.sql` / ER 图) | 字段、类型、长度、可空、主键、外键、注释 | 类型与长度 |
+
+冲突时按 **表结构定类型 → 原型定控件与布局 → 需求定规则与文案** 处理,冲突点在交付时列出来让用户拍板。
+
+---
+
+## 一、从 mock.js 提字段
+
+mock 里的对象 key 就是字段名,值类型决定控件。
+
+```js
+// 原型里的 mock
+const list = [
+  { id: '1', name: '标准A', dataType: 1, officeName: '总部', status: 1, createDate: '2026-01-01' }
+]
+
+const formData = {
+  name: '',
+  dataType: undefined,
+  officeIds: null,
+  ownerId: '',
+  status: true,
+  remark: ''
+}
+```
+
+| mock 值 | 推断 |
+|---|---|
+| `''` | 文本 |
+| `0` / `123` | 数字(`sort` / `*_num` 用 `a-input-number` `precision: 0`) |
+| `0.00` | 金额,`precision: 2` |
+| `true` / `false` | 开关 |
+| `'2026-01-01'` | 日期;`'2026-01-01 10:00:00'` 日期时间 |
+| `undefined` + `*Ids` | 组织树 / 多选 |
+| `[]` | 多选或上传,看字段名 |
+| 嵌套对象 / 数组 | 关联数据,按 ER 关系处理(见第五节) |
+
+- 列表 mock 的第一条 → 列表列字段与顺序。
+- 表单 mock → 表单字段与初始值。
+- mock 里只有 `xxxName` 没有 `xxxId` → 该字段是只读展示,表单里不出现。
+
+---
+
+## 二、从 sql 提字段
+
+### 类型映射
+
+| sql 类型 | 控件 | 属性 |
+|---|---|---|
+| `varchar(n)` / `char(n)` | `a-input` | `:maxlength="n"` |
+| `text` / `longtext` / `mediumtext` | `a-textarea` | `:rows="3" full` |
+| `int` / `bigint` / `smallint` | `a-input-number` | `:precision="0"` |
+| `decimal(p,2)` | `a-input-number` | `:precision="2"`、`:step="0.01"` |
+| `tinyint(1)` | `a-switch` | 提交转 `1 / 0` |
+| `tinyint` / `enum` | `a-select` | 取值看注释,没注释就问 |
+| `datetime` / `timestamp` | `a-date-picker` | `show-time`、`value-format="YYYY-MM-DD HH:mm:ss"` |
+| `date` | `a-date-picker` | `value-format="YYYY-MM-DD"` |
+| `time` | `a-time-picker` | `value-format="HH:mm:ss"` |
+| `json` | `a-textarea` | 业务明确要结构化再换控件 |
+
+`NOT NULL` 且无默认值 → 必填;有 `DEFAULT` → 非必填并带上默认值。
+
+### 列名后缀规则
+
+| 列名特征 | 判定 |
+|---|---|
+| `office_id` / `org_id` / `dept_id` / `campus_id` | 组织树 `s-data-range-tree-select` |
+| `user_id` / `owner_id` / `create_by` / `update_by` | 选人 `s-user-select`(`create_by` / `update_by` 只展示不进表单) |
+| `*_url` / `*_path` / `file` / `attachment` / `image` | 上传 `s-file-upload` |
+| `status` / `is_*` / `enabled` / `enable_flag` | 开关 + 列表标签 |
+| `*_type` / `*_status` / `*_category` | 字典下拉,字典类型优先取字段注释,其次 `表名_字段` |
+| `sort` / `order_num` / `seq` | `a-input-number` `:min="1"` |
+| `remark` / `description` / `memo` / `content` | 文本域,`full` |
+| `create_time` / `update_time` / `create_by` / `update_by` / `del_flag` | 只展示或不展示,**不进表单** |
+| `id` / `*_id`(主键) | 隐藏字段 |
+
+表名前缀(如 `md_standard`)去掉后再转驼峰做 api 文件名:`md_standard` → `standard`,`sys_position` → `position`。
+
+---
+
+## 三、从原型 vue 提结构
+
+| 原型里有 | 取什么 |
+|---|---|
+| `s-filter-item` 顺序 | 查询区顺序;超过 4 个,前 3~4 个留主行,其余进 `#filterMore` |
+| `columns` | 列顺序、`width`、`align`、哪些列有 `template` |
+| `s-collapses-item` | 表单分组标题与组内列数 |
+| `s-form` 的 `column` | 每行列数,最大 4 |
+| 工具栏按钮文案 | 映射 key:添加 `add`、导入 `import`、导出 `export`、批量删除 `remove` |
+| 操作列按钮 | 查看 / 修改 / 删除,对应 `view` / `edit` / `remove` |
+| `mock.js` 的接口名 | api 函数命名参照(`page` / `save` / `getById` / `deleteById`) |
+
+原型没写的布局细节按常规来:查询区 3~4 项、表单 2 列、长文本与附件 `full`。
+
+---
+
+## 四、从需求文档提规则
+
+| 需求里的说法 | 落到 |
+|---|---|
+| 「必填」「不能为空」 | `rules` 加 `required`,`trigger` 输入类 `blur`、选择类 `change` |
+| 「唯一」「不能重复」 | 前端不做唯一校验,交给接口;只在交付说明里提一句 |
+| 「最长 N 字」 | `:maxlength="N"` + `rules` 的 `max: N` |
+| 「手机号 / 邮箱 / 身份证」 | `rules` 加 `pattern` |
+| 「同一时间只能…」「按 X 联动显示」 | `computed` 生成 `rules` 或 `v-if` 控制显隐 |
+| 「默认启用」「默认当前组织」 | `defaultForm()` 里给默认值 |
+| 状态流转(草稿→审批) | 列表状态列用不同颜色标签,操作列按状态显隐按钮 |
+| 特殊排版要求 | 记下来,决定表单是否要分组 / 是否单独出详情文件 |
+
+---
+
+## 五、ER 图关系处理
+
+| 关系 | 落地 |
+|---|---|
+| N:1(明细属于组织) | 表单里做成下拉 / 组织树,存 `xxxId` |
+| 1:N(主表带明细行) | 用 `s-list-table-tree-layout` 或子表组件,单独确认后再做 |
+| N:N(多对多) | 多选控件,提交数组 |
+| 有外键但原型没有 | 按外键列名走第二节的后缀规则 |
+
+ER 图只给了图、没给字段名时,**按原型 mock 的字段名走**,并在交付时标注「字段名取自原型,需与后端核对」。
+
+---
+
+## 六、材料不全时
+
+| 缺什么 | 怎么办 |
+|---|---|
+| 表结构 | 按 mock 字段生成,类型一律文本或数字,交付时标注「类型待后端确认」 |
+| 原型 | 按需求字段清单 + 常规列表布局(查询 3 项、表单 2 列) |
+| 需求文档 | 按表结构字段全量生成标准 CRUD,不做业务规则 |
+| 三者都只有文字描述 | 只按文字里的字段名生成,缺的字段不编造 |
+
+---
+
+## 七、字段清单产出格式
+
+解析完先在对话里出这张表,用户确认后再生成代码:
+
+| 字段名 | 中文 | 类型 | 控件 | 必填 | 列表 | 查询 | 说明 |
+|---|---|---|---|---|---|---|---|
+| `name` | 数据名称 | varchar(50) | `a-input` | 是 | ✓ | ✓ | 模糊查询 |
+| `dataType` | 数据类型 | tinyint | 字典 `data_type` | 是 | ✓ 标签 | ✓ | — |
+| `officeIds` | 所属组织 | varchar(32) | 组织树 | 是 | 显示 `officeName` | 左侧树过滤 | 提交转 `officeId` |
+| `ownerId` | 负责人 | varchar(32) | 选人单选 | 否 | 显示 `ownerName` | — | 同时存 `ownerName` |
+| `status` | 启用状态 | tinyint(1) | `a-switch` | 否 | ✓ 标签 | ✓ | 提交转 `1/0` |
+| `fileUrl` | 附件 | varchar(500) | `s-file-upload` | 否 | — | — | 逗号分隔多文件 |
+| `remark` | 备注 | varchar(255) | `a-textarea` | 否 | — | — | `full` |
+| `createDate` | 创建日期 | date | `a-date-picker` | 否 | ✓ | 区间进「更多」 | — |
+
+这张表就是后续 api、列表、表单、详情四处的唯一依据。
+
+字段表下面再跟一段本次产出清单,文件按需求功能项算(判定表见 `00-生成流程.md` 第四节),不是固定几个:
+
+| 产出文件 | 因为需求里有 |
+|---|---|
+| `src/api/master-data.js` | 全部功能 |
+| `src/views/master-data/standard/index.vue` | 列表、查询、导入、导出 |
+| `src/views/master-data/standard/form.vue` | 新增、修改、详情(复用只读) |
+| `src/views/master-data/i18n.js` | 页面文案 |
+
+需求里没有的功能不出文件、不出代码,清单里也不列。

+ 153 - 0
development/sapit-dev-web/sapit-element-vue/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: sapit-element-vue
+description: 按公司规范完成数据库结构设计与编码。当用户需要设计表结构、生成建库 SQL、编写业务代码、修复缺陷或 review AI 生成的代码时使用。强制先设计后编码、修复先写复现测试、四类高危逻辑不代写。
+---
+
+# 开发编码助手
+
+按《08.开发部-作业规范-开发工程师 V2.0》工作。核心原则:**先设计后编码,AI 只写说得清的部分,四类高危逻辑不碰。**
+
+## 何时使用
+
+- 用户说"设计表结构""出建库脚本""这个功能怎么建表"
+- 用户说"写这个接口""实现这个功能""补这段代码"
+- 用户说"帮我 review 这段代码""看看这段有问题吗"
+
+## 第一步:料件体检
+
+| 料 | 必需性 | 缺了怎么办 |
+|---|---|---|
+| 需求说明书(含字段级定义) | 必需 | **停止**,先去要需求文档 |
+| 技术栈与版本(框架、JDK、数据库版本) | 必需 | **停止**,版本不对会生成不存在的 API |
+| 现有表结构与命名规范 | 必需 | 新库可缺,但需确认命名规范 |
+| 原型或接口约定 | 必需 | 缺了标「按我方约定,待前端确认」 |
+| 部署环境约束(单体/微服务、是否分库) | 建议 | 缺了按单体处理并注明 |
+
+输出体检结论:
+
+> 已收到:需求说明书 v1.2(F-003 请假申请)、技术栈 Spring Boot 3.2 + JDK 17 + MySQL 8.0、现有表 12 张。缺少接口约定,按 RESTful 默认风格生成,待前端确认。
+
+## 第二步:先出设计,不写代码
+
+数据库设计必须先经人确认,再进入编码。
+
+输出三样:
+
+1. **ER 图**(mermaid erDiagram)
+2. **建表 SQL**(含索引、注释、字符集)
+3. **与现有表的冲突点**(字段重名、类型不一致、外键缺失)
+
+```markdown
+## 表结构设计:请假模块
+
+### ER
+```mermaid
+erDiagram
+  leave_apply ||--o{ leave_apply_flow : "1:N"
+  leave_apply {
+    bigint id PK
+    varchar apply_no UK "单号"
+    ...
+  }
+```
+
+### 冲突点
+- `leave_apply.status` 与现有 `attendance_record.status` 枚举值含义不同,建议改名 `approve_status`
+- 现有库统一用 `create_time`,需求文档写的是 `created_at`,按现有库为准
+```
+
+## 第三步:分批编码
+
+**一次只写一个类或一个接口**,不要一次生成整个模块。
+
+每轮开头声明:
+
+> 本轮实现:`LeaveApplyService.submit()`。依赖已存在的 `LeaveApplyMapper`、`HrClient`。不修改其他文件。
+
+写码约束:
+
+- 只用当前技术栈版本支持的 API,不确定的标注「需确认版本支持」
+- 不引入新依赖,需要时先说明理由等确认
+- 公共方法必须有注释说明参数与副作用
+- 复杂逻辑先写步骤注释,再填代码
+
+### 修 bug 必须先写复现测试
+
+这条是硬的。**没有复现测试就改代码,等于不知道到底修好没有。**
+
+顺序不能倒:
+
+1. 先写一个测试,让它能稳定复现这个 bug
+2. 跑一次,**确认它是红的**(这一步省掉,后面全是自欺)
+3. 再改代码
+4. 再跑,变绿,且原有测试没被改坏
+
+如果写不出复现测试,说明根因还没定位,回去继续查,不要先改代码试。
+
+### 核心逻辑先写边界测试
+
+新增的校验、计算、状态转换,先列边界值(0、空、超长、负数、临界值),把测试写在前头,避免"先写完再补测试"补出一堆只测正常路径的假测试。
+
+## 第四步:交付前自检
+
+```markdown
+## 自检记录
+- [ ] 编译通过(无未定义引用)
+- [ ] 无硬编码(连接串、密钥、绝对路径)
+- [ ] 空值与边界已处理(null、空集合、0、负数、超长)
+- [ ] 事务边界明确(哪些操作在同一事务内)
+- [ ] SQL 有索引支撑(where / join 字段)
+- [ ] 无 N+1 查询
+- [ ] 日志不打印敏感信息(密码、证件号、银行卡)
+- [ ] 四类高危逻辑已标出,等待人工实现或确认
+```
+
+## 硬性禁止
+
+| 禁止 | 原因 | 正确做法 |
+|---|---|---|
+| 金额、结算、舍入计算 | 出错直接是钱的问题 | 只写方法签名与调用点,标 `// TODO 人工实现`,并说明需要的计算口径 |
+| 权限判定逻辑 | 越权是安全事故 | 只调权限组件,不自己写判断,标出需要的权限点 |
+| 状态机流转 | 卡错状态流程走不下去 | 只画状态与转换条件,实现交人工 |
+| 对账 / 核销 | 对不上是财务问题 | 同上,人工实现 |
+| 加密、签名、令牌生成 | 自研实现基本都有漏洞 | 用现成库,不自己写算法 |
+
+遇到用户要求"这四类也一起写了",回应:
+
+> 这四类我按规范不代写,只给出结构和方法签名,具体实现请人工确认。我可以把需要判断的条件列出来,减少你的工作量。
+
+## 第五步:可解释性要求
+
+AI 写出的每一段代码,人都要能讲清楚为什么这么写。做不到就说明不该交给 AI。
+
+出现以下情况,直接重写而不是修补:
+
+- 用了你不认识的写法或注解
+- 代码能跑但说不清边界为什么这样处理
+- 一段逻辑里嵌套超过 3 层
+- 为了修一个 bug 加了 3 个以上的 try-catch
+
+## 第六步:完成前自证
+
+**不许说"改好了""已完成"。** 按下面格式交代:
+
+```markdown
+## 完成自证
+- 已实现:LeaveApplyService.submit(),含 6 条规则
+- 已验证:单测 12 条全绿;边界(余额=0、时间倒挂、重复提交)已覆盖
+- 修 bug 场景:复现测试 BalanceZeroTest 先红后绿,原有用例未受影响
+- 未实现:金额/权限/状态机/对账四类,已留 TODO 待人工
+- 未验证:并发场景(缺压测环境)、前端联调(接口未对接)
+```
+
+被问"改好了吗",正确回答:
+
+> 主流程跑通、单测绿了,并发没测,前端还没联调。
+
+而不是"改好了"。**说不清没做什么,等于把风险留给下一个人。**
+
+## 参考文件
+
+- `references/模板与提示词.md` — 表结构模板、编码提示词、review 提示词
+- `references/模板-接口设计.md` — 接口设计说明书格式,写接口或对接外部系统时读
+- `references/复核清单.md` — 交付前检查项与常见 AI 代码缺陷对照