create-yss-spec 2.2.9 → 3.0.0

package/template/.agents/skills/yss-ui-business-page-generation/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: yss-ui-business-page-generation
+description: 指导生成或改造 Vue3 YSS UI CRUD、列表、表单、详情、左树右表和弹窗抽屉页面，覆盖组件选型、模块拆分、Orval API、响应式高度、主题和原型验收；当用户要求生成 YSS UI 业务页或 CRUD 模块时使用。
+---
+
+# YSS UI 业务页面生成 Skill
+
+## 触发条件
+
+- 用户要求生成或改造业务页面、CRUD 模块、列表页、表单页、详情页、左树右表、树表联动页面。
+- 页面涉及 `YTable`、`YTree`、`YFormily`、`YButton`、`YCard`、`YSplitPane`、`YConditionBuilder` 等 YSS UI 组件。
+- 需要让 AI 优先复用 YSS UI 组件、hooks、utils，而不是直接使用 Ant Design Vue 或重复造工具函数。
+- 用户提供旧项目路径、原型截图、目标截图或要求“照旧项目/照原型还原”。
+
+## 不适用场景
+
+- 只修改 yss-ui 组件库内部实现：回到 yss-ui 源仓库，使用其 `categories.library` 维护流程；该类 skill 不随业务模板分发。
+- 只写文档、提交信息或发版流程，不生成业务页面代码。
+- 用户明确要求不用 YSS UI 组件库。
+
+## 必读参考
+
+- 组件来源速查：`./references/component-map.md`
+- Hooks 速查：`./references/hooks-map.md`
+- Utils 速查：`./references/utils-map.md`
+- 表格细节：`../ytable-usage/SKILL.md`
+- 编辑表格细节：`../yedit-table-usage/SKILL.md`
+- 树形细节：`../ytree-usage/SKILL.md`
+- 表单细节：`../yss-formily/SKILL.md`
+- 原型还原验收：`../prototype-page-acceptance/SKILL.md`
+- 主题 Token 与换肤：`../theme-token-usage/SKILL.md`
+- 文件导出下载：`../file-export-download/SKILL.md`
+- Orval 接口与错误处理：`../yss-api-integration/SKILL.md`
+
+## 文档检索顺序
+
+1. 当前会话可用 yss-ui MCP 时，生成业务代码前先调用一次 `get_codegen_rules`；不确定导出时用 `list_components`，配置组件/Hook/Utils 前用 `get_component_docs`，复杂场景用 `get_demo`，不确定归属时用 `search_docs`。
+2. MCP 查询未命中时，先用 `list_components` 或 `search_docs` 校正名称；只有 MCP 工具不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。
+3. MCP/`llms-full.txt` 与当前项目的依赖版本或导出不一致时，使用当前项目源码、CodeGraph 和可编译导出交叉核验，明确记录差异，不猜测 API。
+4. 当前 Skill 已被本地加载时不得再用 `get_skill` 查询自身；仅在所需子 Skill 未同步到本地时才用 `list_skills/get_skill` 兜底。
+
+## 硬约束（禁止/必须）
+
+- 生成页面前必须先判定组件来源：YSS UI 已封装的组件从 `@yss-ui/components` 导入。
+- 表单默认使用 `YFormily + JSON Schema`，业务代码禁止导入 `@formily/antdv` UI 组件。
+- 所有 `YFormily` 横向业务表单必须显式设置固定 `labelWidth` 与 `labelAlign: 'right'`，并使用 `FormLayout -> FormGrid -> 字段` 响应式结构；禁止用 `minColumns: maxColumns` 固定列数破坏响应式。
+- 标准列表/CRUD 查询区必须采用 `YCard -> search-content -> search-form(YFormily) + search-actions(YButton 查询/重置)` 的纵向布局；按钮行独占下一行并右对齐，缩放或窄屏字段换行后仍位于搜索卡片右下角。
+- 查询区禁止横向放“表单 + 按钮”并用大 `gap`、`align-items: flex-start`、`padding-top` 硬调按钮位置。
+- 抽屉/弹窗编辑表单默认 `labelWidth: 140`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`，备注/长文本字段用 `gridSpan` 占满整行。
+- 下拉选择器（`Select`/`TreeSelect`/`Radio.Group`）异步数据源必须通过 `enum` 或 `x-reactions` / `field.dataSource` 注入，严禁写入 `x-component-props.options`（会导致首次打开弹窗显示“暂无数据”、关闭再打开才展示的经典时序 Bug）；弹窗基础下拉字典优先在打开前 `await` 或页面初始化提前拉取。
+- 表格默认使用 `YTable`；远程分页使用 `pageable + pagination.remote + @page-change`，事件参数固定读取 `{ current, pageSize }`，禁止使用 `currentPage`。
+- 编辑表格默认使用 `YEditTable`；需求出现“编辑表格/添加行/删除行/行内下拉”时禁止直接用 `a-table` 手搓。
+- 左树右表优先使用 `YSplitPane + YCard + YTree + YTable`，高度使用 `useTreeHeight/useTableHeight`。
+- 标准列表必须使用 `YTable` 真实 API：`:data`、`:columns`、`:loading`、`pageable`、`v-model:pagination`、`@page-change`；禁止臆造 `request/search-params` 等 Prop。实例 `refresh()` 只刷新当前 vxe 表格数据，远程重新查询必须调用业务 Hook。
+- 新增/导入/批量操作等主操作直接放入 `#toolbar-right` 插槽；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
+- 删除确认默认使用 `YTable actionConfig.buttons[].isConfirm` 按钮项或 AntDV `Popconfirm` 气泡确认，禁止默认使用居中 `Modal.confirm`。
+- 样式抽离到 `style.less`，在 SFC 中使用 `<style scoped lang="less">@import './style.less';</style>`。
+- `index.vue` 原则上不超过 150 行；状态、API、副作用和处理方法进入 `hooks/`，列定义和静态配置进入 `constant.ts`。
+- 所有导出函数、hooks、类型和静态配置必须使用中文 JSDoc。
+- Orval 请求必须使用真实生成导出和 DTO；禁止 `if (res?.success)` 冗余包裹，也禁止在 `else`/`catch` 重复 `message.error`。
+- 页面、公共组件、内联样式、TS 渲染配置和 SVG 必须遵循 `theme-token-usage`；禁止硬编码品牌色及 hover/active/selected/focus 色阶，主色透明态必须由真实动态 Token 派生。
+- 页面包含导出、报表、模板或附件下载时必须遵循 `file-export-download`，使用 `handleBlobResponse(res.data, res.headers)`，并检查生成方法是否已包含 `responseType: 'blob'`。
+- 若用户给出旧项目路径或截图，开发前必须先提取 UI/交互验收清单；交付前逐项对照，不允许只实现字段和接口。
+
+## 标准代码骨架
+
+```text
+src/views/{module-name}/
+├── index.vue
+├── constant.ts
+├── style.less
+├── hooks/
+│   ├── use{Module}List.ts
+│   └── use{Module}Form.ts
+├── type.ts              # 独立类型较多时增加
+└── components/          # 多个私有视图时增加
+    ├── {Module}Table.vue
+    └── {Module}Modal.vue
+```
+
+## 生成流程
+
+1. 读取本 skill 的三个 reference，并按上述文档检索顺序核对真实 API 与导出，禁止根据旧示例猜测。
+2. 读取 `theme-token-usage`，检查项目真实主题变量与运行时同步链路。
+3. 若有截图或旧项目路径，先按 `prototype-page-acceptance` 提取布局、按钮位置、表格高度、抽屉宽度、字段控件类型等验收项。
+4. 按需求类型加载细分 skill：列表读 `page-list-module` 和 `ytable-usage`；表单读 `yss-formily`；编辑表格读 `yedit-table-usage`；树读 `ytree-usage`；导出下载读 `file-export-download`。
+5. 先设计 `constant.ts`、`style.less` 和 hooks；独立类型或私有视图确有需要时再增加 `type.ts`/`components/`，最后写 `index.vue` 组合视图。
+6. 对 API 请求使用 Orval 真实生成类型和导出，在 hooks 内封装 loading、分页映射和失败后状态；错误 Toast 由 mutator 统一处理。
+7. 交付前检查导入来源、真实组件 API、分页字段、Formily schema 层级、主题 Token、查询按钮右下角布局、表格工具栏、样式作用域、删除确认和原型对照清单。
+
+## 最小组合示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YButton, YCard, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { TABLE_COLUMNS } from './constant';
+import { useRuleList } from './hooks/useRuleList';
+
+const emit = defineEmits<{ create: [] }>();
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight, isReady } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
+const { loading, dataList, pagination, handlePageChange } = useRuleList();
+
+/** 打开新增表单，实际项目中由表单 Hook 实现。 */
+const openCreate = (): void => {
+  emit('create');
+};
+</script>
+
+<template>
+  <YCard class="page-card">
+    <div ref="tableAreaRef" class="table-area">
+      <YTable
+        v-if="isReady"
+        :height="tableHeight"
+        :data="dataList"
+        :columns="TABLE_COLUMNS"
+        :loading="loading"
+        pageable
+        v-model:pagination="pagination"
+        @page-change="handlePageChange"
+      >
+        <template #toolbar-right>
+          <YButton type="primary" @click="openCreate">新增</YButton>
+        </template>
+      </YTable>
+    </div>
+  </YCard>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+## 交付检查清单
+
+- [ ] 已优先复用 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils`。
+- [ ] `index.vue` 不超过 150 行，业务逻辑、常量、列配置和样式已按职责拆分。
+- [ ] 未出现未导出的 Y 前缀组件。
+- [ ] 未导入 `@formily/antd-v3`、`@formily/antd` 或业务层 `@formily/antdv` UI 组件。
+- [ ] `YTable` 分页字段为 `current/pageSize/total`。
+- [ ] `YTable` 未臆造 `request/search-params` Prop，也未把实例 `refresh()` 当作远程请求。
+- [ ] 主表格主操作放在 `#toolbar-right`，仅在业务需要列设置时才配置了 `toolbar-config.custom`。
+- [ ] 编辑表格场景使用 `YEditTable`，下拉可输入/多选等能力通过列 `props` 配置。
+- [ ] `YFormily` 未使用不存在的详情开关 prop，表单 label 固定宽度右对齐，`FormGrid` 保持响应式。
+- [ ] 查询区按钮在外部 `.xxx__search-actions` 右对齐独占一行，缩窄后仍处于搜索卡片右下角。
+- [ ] 主题色、状态色、中性色及交互态使用动态 Token；未依赖未同步变量的固定色 fallback。
+- [ ] 导出下载使用 `handleBlobResponse`，且 Blob 配置、响应头、loading 与错误链路已验证。
+- [ ] 已核对 Orval 真实导出，未使用 `if (res?.success)` 或重复错误 Toast。
+- [ ] 若有截图或旧项目参考，已逐项对照布局、按钮、表格高度、抽屉响应式和字段控件类型。
+
+## 失败兜底策略
+
+- 组件来源不确定时，先用 MCP `list_components/get_component_docs/search_docs` 交叉确认；MCP 不可用时才查 `component-map.md` 和 `llms-full.txt`，仍无法确认时报告待确认项，不得将猜测的导入直接落地。
+- 页面复杂度过高时，先落地最小列表/表单闭环，再拆分私有组件和 hooks。
+- API 契约不稳定时，先在 hook 内做最小字段映射，不把兼容逻辑散落到模板。

package/template/.agents/skills/yss-ui-business-page-generation/references/component-map.md

@@ -0,0 +1,39 @@
+# YSS UI 组件来源速查
+
+此文件用于业务页面生成前的组件选型。优先使用 YSS UI 已封装组件；未封装能力再从 `ant-design-vue` 导入。
+
+## 从 `@yss-ui/components` 导入
+
+| 组件 | 适用场景 | 备注 |
+| --- | --- | --- |
+| `YButton` | 操作按钮、权限按钮 | 支持 `permissionCode`、`fallback`、`modifiers`；优先替代 `a-button`。 |
+| `YCard` | 页面容器、区域容器 | 支持 `title`、`extra`、`padding`、Meta 插槽。 |
+| `YTable` | 标准列表、分页、操作列、筛选、字典翻译 | 继承 vxe-table 能力，分页用 AntDV Pagination。 |
+| `YEditTable` | 可编辑表格 | 需要底部添加按钮高度时配合 `useTableHeight(tableAreaRef, { withAddButton: true })`。 |
+| `YTree` | 左侧分类树、组织树、搜索过滤树 | 节点操作用 `getNodeActions`。 |
+| `YSplitPane` | 左树右表、可拖拽分割布局 | 左右或上下区域分割。 |
+| `YFormily` | JSON Schema 表单、新增/编辑/查看 | 默认表单方案。 |
+| `YssFormily` | 表单兼容导出 | 仅用于维护历史代码；新代码统一使用 `YFormily`。 |
+| `YConditionBuilder` | 条件构建器、规则配置 | 常用于数据质量、筛选条件配置。 |
+| `YFileImport` | 文件导入 | Formily schema 内也可用 `YFileImport`。 |
+| `YMonaco` | 代码编辑器 | SQL、JSON、脚本编辑。 |
+| `YMonacoDiff` | 代码 Diff | 变更对比场景。 |
+| `YCron` | Cron 表达式编辑 | 定时任务配置。 |
+| `YMonthCalendar` | 月度日历、节假日和连续区间 | 支持单元格、右键菜单和头部插槽。 |
+| `YEcharts` | 图表展示 | 业务图表封装。 |
+| `YSheet` | 协同/类 Excel 表格 | 复杂表格编辑。 |
+| `AuthorityDropdown` | 权限相关下拉 | 可从 `@yss-ui/components` 导入；全局安装后也注册了 `YDropdown` 组件名别名。 |
+
+## 回退到 `ant-design-vue`
+
+`@yss-ui/components` 未导出的组件不要臆造 Y 前缀，应直接从 `ant-design-vue` 导入：
+
+- `Modal`、`Drawer`、`Popconfirm`
+- `Input`、`Select`、`Switch`、`DatePicker`、`Tag`
+- `Steps`、`Tabs`、`Space`、`Tooltip`
+- `message`、`notification`
+
+## 禁止规则
+
+- 不要编造未导出的 Y 前缀组件；弹窗、抽屉、输入框等未封装能力直接从 `ant-design-vue` 导入。
+- 业务层不要从 `@formily/antdv` 导入 `FormItem`、`Input` 等 UI 适配组件。

package/template/.agents/skills/yss-ui-business-page-generation/references/hooks-map.md

@@ -0,0 +1,70 @@
+# YSS UI Hooks 速查
+
+业务页面生成时优先从 `@yss-ui/hooks` 复用以下 hooks。
+
+## useTableHeight
+
+```ts
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight, isReady, recalculateHeight } = useTableHeight(tableAreaRef, {
+  withPagination: true,
+  withToolbar: true,
+  withAddButton: false,
+  extraOffset: 16,
+});
+```
+
+- 必须传入表格父容器 `ref`。
+- 返回值是 `recalculateHeight`，不要使用旧的错误返回名。
+- 可选项：`boundaryRef`、`minHeight`、`defaultHeight`、`extraOffset`、`withPagination`、`withToolbar`、`withAddButton`、`paginationHeight`、`toolbarHeight`、`addButtonHeight`。
+
+## useTreeHeight
+
+```ts
+const treeAreaRef = ref<HTMLDivElement>();
+const { treeHeight, recalculateHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT + 16,
+});
+```
+
+- 必须传入树区域父容器 `ref`。
+- 搜索树可引入 `YTREE_SEARCH_HEIGHT`。
+
+## useLoading
+
+```ts
+const { loading, withLoading, setLoading, toggleLoading } = useLoading();
+
+await withLoading(fetchData);
+```
+
+- 默认捕获错误，避免未处理 Promise rejection。
+- 需要外层捕获时设置 `rethrowError: true`。
+- Orval API 的业务错误和 HTTP/网络错误已由 mutator 提示，禁止在 `onError` 重复 `message.error`。
+- `onError` 只用于更新局部错误状态、上报或处理非 mutator 任务；如要自定义 API 错误交互，必须先显式传入 `skipBusinessError`/`skipErrorHandler`。
+
+## usePollingTask
+
+```ts
+const { start, stop, restart, runNow, isActive, isRunning } = usePollingTask(
+  async ({ signal, isCurrent }) => {
+    const res = await fetch('/api/list', { signal });
+    if (!isCurrent()) return;
+    return res.json();
+  },
+  { interval: 3000, pauseWhenHidden: true }
+);
+```
+
+- 只负责轮询调度，不接管业务 `loading/data/error`。
+- 适合页面级静默刷新、任务状态轮询。
+
+## useUrlState
+
+- 用于把查询条件、分页、Tab 等状态同步到 URL。
+- 适合列表页返回恢复、分享链接保留筛选条件。
+
+## useFullscreen
+
+- 用于容器全屏、图表全屏、编辑器全屏。
+- 传入目标元素或目标 getter，按需配置退出提示。

package/template/.agents/skills/yss-ui-business-page-generation/references/utils-map.md

@@ -0,0 +1,51 @@
+# YSS UI Utils 速查
+
+业务页面生成时优先从 `@yss-ui/utils` 复用工具函数，避免重复实现。
+
+## 权限
+
+- `getAuthBtns(): AuthBtn[]`：读取当前按钮权限列表。
+- `hasAuth(code?: string): boolean`：判断权限码是否可用。
+- `getBtnInfo(code?: string): AuthBtn | null`：获取权限按钮信息。
+- `clearAuthInfo(): void`：清理权限信息。
+
+## 复制
+
+```ts
+const ok = await copyToClipboard(text);
+```
+
+- `copyToClipboard(text): Promise<boolean>`：复制文本到剪贴板。
+
+## 下载
+
+- `downloadFileStream(stream, fileName)`：下载 Blob/二进制流。
+- `getFileNameFromContentDisposition(contentDisposition?)`：从响应头解析 `filename*` 或 `filename`。
+- `handleBlobResponse(data, headers)`：处理 Blob 下载响应并根据 `Content-Disposition` 自动命名；第三个参数已弃用。
+- `downloadFileFromUrl(url, fileName?)`：按 URL 触发下载。
+
+接口导出下载必须读取 `../../file-export-download/SKILL.md`，优先调用 `handleBlobResponse(res.data, res.headers)`，禁止在业务层重复解析文件名和创建下载链接。
+
+当前微应用模板会统一解析 HTTP 4xx/5xx 的 Blob JSON 错误，但不会自动检测 HTTP 200 Blob 内的 `success === false`；发现后者时先修正后端状态码或 mutator，不在页面 Hook 重复解析与提示。
+
+## 格式化
+
+- `formatMoney(amount, precision?, separator?)`：金额格式化。
+- `formatDate(date, format?)`：日期格式化，默认 `YYYY-MM-DD HH:mm:ss`。
+- `formatFileSize(bytes, precision?)`：文件大小格式化。
+- `formatDateRelative(date)`：相对时间格式化。
+
+## 存储
+
+- `localStorage`：封装本地存储读写。
+- `sessionStorage`：封装会话存储读写。
+
+## 主题
+
+- `applyYssTheme(options)`：应用 YSS 主题变量。
+- `lightenColor(hex, factor?)`：颜色变亮。
+- `darkenColor(hex, factor?)`：颜色变暗。
+
+## URL
+
+- `getUrlData(url?, excludeKeys?)`：解析 URL 查询参数。