create-yss-spec 2.2.9 → 2.2.10

package/template/.cursor/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/.cursor/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 查询参数。

package/template/.cursor/skills/yss-use-table-height/SKILL.md

@@ -1,349 +1,130 @@
 ---
 name: yss-use-table-height
-description: Use when working with YTable that needs responsive height, pagination, or a toolbar and the useTableHeight hook is involved.
+description: 指导 YTable、YEditTable、左树右表、分页列表、工具栏表格和弹窗/抽屉内表格使用 @yss-ui/hooks 的 useTableHeight 实现稳定自适应高度；当需要避免双滚动条、底部空白、容器撑开闪烁，或需要计入分页、工具栏、添加按钮偏移时使用。
 ---
 
-# useTableHeight 表格高度计算 Hook
+# useTableHeight 使用
 
-本目录是表格高度的 canonical 技能；历史名称 `use-table-height` 仅通过注册表和 Router alias 解析。
+## 触发条件
 
-## YSS canonical execution rules
+- YTable/YEditTable 需要自适应滚动高度，或页面出现双滚动条、底部空白和容器撑开闪烁。
+- 表格内含分页、工具栏、添加按钮，或位于弹窗/抽屉/shrink-wrap 容器内。
 
-- 使用真实签名 `useTableHeight(containerRef, options)`，结果解构为 `tableHeight`、`isReady` 和 `recalculateHeight`。
-- `YTable` 必须绑定 `:height="tableHeight"`；不要只绑定 `max-height`，也不要用固定魔法高度替代 Hook。
-- `pageable`、工具栏和 `YEditTable` 添加按钮分别对应 `withPagination`、`withToolbar` 和 `withAddButton`。
-- 容器使用 `flex: 1; min-height: 0; overflow: hidden`，避免观察由表格内容反向撑开的直属容器。
+## 不适用场景
 
-## Authoritative Docs And Boundary
+- 纯短表且页面不需要独立滚动区。
+- 当前布局组件已完整托管表格高度，且没有内部偏移需要扣减。
 
-- YSS UI hooks documentation: `http://192.168.164.27:3200/hooks`
-- Local reference index: `references/frontend-docs.md`
+## 实施流程
 
-This skill only covers `useTableHeight` wiring. Use `yss-components` for table layout/rendering rules and `yss-hook` for request/pagination state.
+1. MCP 可用时，先用 `get_component_docs` 精确查询 `useTableHeight`，需要示例时再调用 `get_demo`；不要仅凭 Skill 中的静态签名推断当前 API。
+2. 精确查询无结果时，先用 `search_docs` 校正名称；仅在 MCP 不可用、调用失败或仍无结果时，回退读取最新 `llms-full.txt`。文档版本与当前依赖不一致时，再核对 Hook 源码、CodeGraph 和真实导出。
+3. 先确认容器是稳定 flex 区域还是被表格内容撑开的 shrink-wrap 区域。
+4. 盘点表格内部实际开启的分页、工具栏、YEditTable 添加按钮和额外 padding。
+5. 把受约束的容器 `ref` 传给 Hook，将 `tableHeight` 绑定到表格 `height`。
+6. 在弹窗/抽屉动画结束或布局切换后视情况调用 `recalculateHeight()` 验证最终高度。
 
-中文说明：这里只处理表格高度计算，不处理表格列渲染、接口请求或分页数据逻辑。
+## 硬约束（禁止/必须）
 
-## 💡 何时使用
+- 使用真实签名 `useTableHeight(tableAreaRef, options)` 和真实返回值 `tableHeight/isReady/recalculateHeight`。
+- `tableAreaRef` 支持原生 DOM 或 Vue 组件实例（如 `YCard`）。绑定 DOM 时使用表格的直接父容器；绑定 Card 时 Hook 会尝试获取 `.ant-card-body`。
+- 稳定布局使用“外层可计算高度 + flex column，表格区 `flex: 1; min-height: 0; overflow: hidden`”。禁止用大常量高度替代 Hook。
+- YTable 开启 `pageable` 时设置 `withPagination: true`；开启 `toolbarConfig.custom` 或工具栏插槽时设置 `withToolbar: true`；YEditTable 显示 `addable` 按钮时设置 `withAddButton: true`。
+- 默认偏移常量分别是分页 48px、工具栏 48px、添加按钮 40px；只在实际样式不同时使用 `paginationHeight/toolbarHeight/addButtonHeight` 覆盖。
+- 把结果绑定到 `YTable/YEditTable` 的 `:height="tableHeight"`，不只设置 `max-height`。
+- 直属容器由表格内容撑开时，不要观察该容器形成“子元素改变父高度、父高度又改变子元素”循环；传入更外层稳定容器 `boundaryRef`，并用 `extraOffset` 扣除边界内其他区域。
+- Hook 已用 `ResizeObserver` 监听容器尺寸。不强制为每个弹窗/抽屉写 watch；只在动画或隐藏初始化导致高度不准时，于可见后 `nextTick(recalculateHeight)`。
 
-当页面中使用 `YTable` 组件且需要以下功能时，**必须**使用此 Hook：
-
-- ✅ 表格需要自适应容器高度
-- ✅ 表格启用了分页 (`pageable`)
-- ✅ 表格启用了工具栏 (`toolbar-config`)
-- ✅ 表格在弹窗 (Modal) 或抽屉 (Drawer) 中
-
----
-
-## ⚠️ Critical Rules（必读）
-
-### 规则 1：必须使用解构语法
-
-```typescript
-// ❌ 错误：直接赋值（这是最常见的错误！）
-const tableHeight = useTableHeight(tableAreaRef);
-
-// ✅ 正确：必须解构返回值
-const { tableHeight } = useTableHeight(tableAreaRef);
-```
-
-> **为什么**：`useTableHeight` 返回的是对象 `{ tableHeight, isReady, recalculateHeight }`，不是数字。
-
----
-
-### 规则 2：启用分页必须传 `withPagination: true`
-
-```typescript
-// ❌ 错误：YTable 启用了 pageable 但没有告知 Hook（分页会被遮挡！）
-const { tableHeight } = useTableHeight(tableAreaRef);
-
-// ✅ 正确：必须同步配置
-const { tableHeight } = useTableHeight(tableAreaRef, {
-  withPagination: true,  // 会自动减去 48px 分页高度
-});
-```
-
-> **为什么**：不传此配置，Hook 不会预留分页区域空间，导致分页被挤出可视区域。
-
----
-
-### 规则 3：启用工具栏必须传 `withToolbar: true`
-
-```typescript
-// ❌ 错误：有工具栏但没配置
-const { tableHeight } = useTableHeight(tableAreaRef);
-
-// ✅ 正确：
-const { tableHeight } = useTableHeight(tableAreaRef, {
-  withPagination: true,
-  withToolbar: true,  // 会自动减去 48px 工具栏高度
-});
-```
-
----
-
-### 规则 4：容器必须设置 Flex 布局
-
-```vue
-<template>
-  <!-- ❌ 错误：容器没有 flex 布局 -->
-  <div ref="tableAreaRef">
-    <YTable :max-height="tableHeight" />
-  </div>
-
-  <!-- ✅ 正确：容器设置 flex: 1 + overflow: hidden -->
-  <div ref="tableAreaRef" class="table-container">
-    <YTable :max-height="tableHeight" />
-  </div>
-</template>
-
-<style scoped lang="less">
-.table-container {
-  flex: 1;           // ← 必须：占据剩余空间
-  overflow: hidden;  // ← 必须：防止内容溢出
-}
-</style>
-```
-
----
-
-### 规则 5：ref 绑定到容器而非 YTable
-
-```vue
-<!-- ❌ 错误：ref 绑定到 YTable 组件 -->
-<YTable ref="tableAreaRef" :max-height="tableHeight" />
-
-<!-- ✅ 正确：ref 绑定到包裹 YTable 的容器 div -->
-<div ref="tableAreaRef" class="table-container">
-  <YTable :max-height="tableHeight" />
-</div>
-```
-
----
-
-## 📖 API 速查
-
-### 导入
-
-```typescript
-import { useTableHeight } from '@yss-ui/hooks';
-```
-
-### 基本用法
-
-```typescript
-const { tableHeight, isReady, recalculateHeight } = useTableHeight(containerRef, options);
-//       ↑ 绑定到 :max-height   ↑ 高度就绪标志     ↑ 手动重算（少用）
-```
-
-### 关键配置（必须掌握）
-
-以下是 **最常出错** 的配置项，必须根据实际场景正确设置：
-
-| 配置 | 何时必须设为 `true` | 不配置的后果 |
-|------|---------------------|-------------|
-| `withPagination` | YTable 启用 `pageable` 时 | **分页被遮挡** |
-| `withToolbar` | 有工具栏 (`toolbar-config`) 时 | 工具栏被遮挡 |
-| `withAddButton` | YEditTable 底部有添加按钮时 | 按钮被遮挡 |
-
-### 完整 API 参考
-
-> 💡 **完整参数和类型定义**请查阅：
-> - 在线文档：`http://192.168.164.27:3200/hooks/use-table-height`
-> - 源码类型：`packages/hooks/src/useTableHeight/types.ts`
-> - LLM 索引：`http://192.168.164.27:3200/llms-full.txt`（搜索 "useTableHeight"）
-
----
-
-## ✅ 完整正确示例
-
-### 场景：搜索栏 + 表格 + 分页
+## 标准代码骨架
 
 ```vue
 <script setup lang="ts">
-import { ref, onMounted, reactive } from 'vue';
-import { YCard, YTable } from '@yss-ui/components';
+import { ref } from 'vue';
+import { YTable, type YTableColumn } from '@yss-ui/components';
 import { useTableHeight } from '@yss-ui/hooks';
-import { Input } from 'ant-design-vue';
-import { TABLE_COLUMNS } from './constant';
-import type { UserItem, UserQuery } from './type';
-
-defineOptions({ name: 'UserManagePage' });
 
-// 1. 创建容器 ref
 const tableAreaRef = ref<HTMLDivElement>();
-
-// 2. 使用 Hook（必须解构 + 必须配置 withPagination）
-const { tableHeight } = useTableHeight(tableAreaRef, {
-  withPagination: true,  // ← YTable 启用了 pageable，必须开启
-});
-
-// 列表数据
-const loading = ref(false);
-const dataList = ref<UserItem[]>([]);
-const totalCount = ref(0);
-const query = reactive<UserQuery>({
-  pageIndex: 1,
-  pageSize: 20,
-  keyword: '',
+const dataList = ref<Array<{ id: string; name: string }>>([]);
+const columns: YTableColumn[] = [
+  { type: 'seq', title: '序号', width: 70 },
+  { field: 'name', title: '名称', minWidth: 180 },
+];
+const { tableHeight, isReady, recalculateHeight } = useTableHeight(tableAreaRef, {
+  withPagination: true,
+  withToolbar: true,
 });
-
-const fetchData = async () => {
-  loading.value = true;
-  // ... API 调用
-  loading.value = false;
-};
-
-const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }) => {
-  query.pageIndex = current;
-  query.pageSize = pageSize;
-  fetchData();
-};
-
-onMounted(() => fetchData());
 </script>
 
 <template>
-  <div class="page-container">
-    <YCard title="用户管理" class="content-card">
-      <template #extra>
-        <Input.Search
-          v-model:value="query.keyword"
-          placeholder="请输入关键词"
-          style="width: 240px"
-          @search="fetchData"
-        />
-      </template>
-
-      <!-- 3. ref 绑定到容器 div，不是 YTable -->
-      <div ref="tableAreaRef" class="table-container">
-        <!-- 4. 使用 :max-height 绑定高度 -->
-        <YTable
-          :columns="TABLE_COLUMNS"
-          :data="dataList"
-          :loading="loading"
-          :max-height="tableHeight"
-          :pagination="{
-            current: query.pageIndex,
-            pageSize: query.pageSize,
-            total: totalCount,
-          }"
-          pageable
-          @page-change="handlePageChange"
-        />
-      </div>
-    </YCard>
+  <div class="page">
+    <div ref="tableAreaRef" class="table-area">
+      <YTable
+        v-if="isReady"
+        :height="tableHeight"
+        :data="dataList"
+        :columns="columns"
+        :toolbar-config="{ custom: true }"
+        pageable
+      />
+    </div>
   </div>
 </template>
 
 <style scoped lang="less">
-.page-container {
-  height: 100%;
-  display: flex;
-  flex-direction: column;
-}
+@import './style.less';
+</style>
+```
 
-.content-card {
-  flex: 1;
+```less
+/* style.less */
+.page {
+  height: 100%;
   display: flex;
   flex-direction: column;
-  overflow: hidden;
-
-  :deep(.ant-card-body) {
-    flex: 1;
-    display: flex;
-    flex-direction: column;
-    overflow: hidden;
-  }
 }
 
-// 5. 容器必须设置 flex: 1 + overflow: hidden
-.table-container {
+.table-area {
   flex: 1;
+  min-height: 0;
   overflow: hidden;
 }
-</style>
-```
-
----
-
-## ❌ 常见错误汇总
-
-### 错误 1：未解构返回值
-
-```typescript
-// ❌ 错误
-const tableHeight = useTableHeight(tableAreaRef);
-// tableHeight 是一个对象，不是数字！
 ```
 
-**结果**：表格高度显示 `[object Object]` 或不生效
+## shrink-wrap 容器
 
-**修复**：
 ```typescript
-const { tableHeight } = useTableHeight(tableAreaRef);
-```
-
----
-
-### 错误 2：启用分页但未配置 withPagination
-
-```typescript
-// ❌ 错误
-const { tableHeight } = useTableHeight(tableAreaRef);
-```
-
-**结果**：分页区域被遮挡或挤出可视区域
+const tableAreaRef = ref<HTMLDivElement>();
+const boundaryRef = ref<HTMLDivElement>();
 
-**修复**：
-```typescript
 const { tableHeight } = useTableHeight(tableAreaRef, {
-  withPagination: true,
+  boundaryRef,
 });
 ```
 
----
-
-### 错误 3：容器缺少 flex 样式
-
-```less
-// ❌ 错误：没有 flex 布局
-.table-container {
-  height: 100%;
-}
-```
-
-**结果**：高度计算不准确，表格可能溢出
+`extraOffset` 必须来自可说明的实际布局占位；如果区域高度会变，优先改成稳定 flex 布局，不固定一个近似大数。
 
-**修复**：
-```less
-.table-container {
-  flex: 1;
-  overflow: hidden;
-}
-```
-
----
+## 弹层可见后补算
 
-### 错误 4：绑定到 height 而非 max-height
-
-```vue
-<!-- ❌ 错误：使用 :height -->
-<YTable :height="tableHeight" />
+```typescript
+import { nextTick } from 'vue';
 
-<!-- ✅ 正确：使用 :max-height -->
-<YTable :max-height="tableHeight" />
+/** 弹层完全展开后重算表格高度。 */
+const handleAfterOpenChange = async (open: boolean) => {
+  if (!open) return;
+  await nextTick();
+  recalculateHeight();
+};
 ```
 
-**说明**：`:max-height` 允许表格在数据少时自适应收缩，`:height` 会强制固定高度。
+## 交付检查清单
 
----
-
-## 🔗 关联 Skills
+- [ ] 观察容器具有稳定高度，需要时已使用 `boundaryRef`。
+- [ ] 分页、工具栏、添加按钮的偏移与实际开关一致，未重复扣减。
+- [ ] 表格绑定 `height`，容器有 `min-height: 0`，无双滚动条和底部大空白。
+- [ ] 只在实际出现隐藏态/动画时机问题时手动调用 `recalculateHeight()`。
 
-- **page-module-development**：页面模块整体开发规范
-- **ytable-usage**：YTable 组件使用规范
-- **use-tree-height**：树组件高度计算（类似逻辑）
-
----
+## 失败兜底策略
 
-**最后更新**: 2026-02-04
+- 高度持续闪烁时，检查被观察容器是否由表格内容撑开；是则使用稳定 `boundaryRef` 或改为 flex 布局。
+- 底部空白或内容被遮挡时，逐项核对 `withPagination/withToolbar/withAddButton` 与实际开关，不反复调大 `extraOffset`。
+- 弹层首次打开高度不准时，在可见或动画结束后 `nextTick(recalculateHeight)`；正常 ResizeObserver 已生效时不增加重复 watch。