draftgo-cli 2.0.3 → 2.0.9

package/resources/skill/rules/data-table.md

@@ -1,320 +0,0 @@
----
-name: draftgo-data-table-guideline
-description: Reference UI/UX guidance for data list/table pages. Use it to improve data density, filtering, states, and responsive behavior without forcing every page into one fixed template.
-version: 1.0.0
----
-
-# 数据列表 UI/UX 设计规范
-
-> **使用原则**：开发数据列表、表格、多数据管理类页面时，可参考本规范提升信息密度、筛选效率、状态完整和响应式体验；具体布局、控件数量、分页方式和动效由业务目标、数据复杂度和页面风格决定。
->
-> 不要为了套用结构而强行加入搜索、高级筛选、列配置或分页；用户真正需要快速找到、比较、编辑、批量处理哪些数据，才是设计依据。
-
----
-
-## 1. 工作台空间模型
-
-数据列表 / 表格 / 多数据管理页通常是**操作型页面**，应先建立占满可用空间的工作台容器，再放筛选、表格、分页等组件。不要把页面写成普通文档流。
-
-- 页面根容器占满可用视口 / iframe 内容区，常用 `display:flex; flex-direction:column; min-height:100vh; overflow:hidden`。
-- Toolbar / Filter Bar 是稳定控制区，`flex-shrink:0`。
-- 表格 / 列表主体是主工作区，`flex:1; min-height:0; overflow:auto`，数据少时也保留工作区空白。
-- Pagination / 批量操作栏 / 底部保存栏是流程控制区，`flex-shrink:0`，应贴在当前工作区底部或保持稳定位置。
-- 数据只有 1-2 条时，分页不应跟随最后一行上浮；数据很多时，滚动应优先发生在表格主体，而不是把分页挤出视野。
-
-### 常见布局参考
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ [🔍 搜索框] [高级筛选▼]                         [列配置⚙️] │  ← Toolbar
-├─────────────────────────────────────────────────────────────────┤
-│ [状态:已发布 ×] [类型:文章 ×] [清除全部]                       │  ← Filter Bar（有筛选时显示）
-├─────────────────────────────────────────────────────────────────┤
-│ □ │ 列A  │ 列B  │ 列C  │ 列D  │  操作                        │  ← 表头（sticky）
-│───┼──────┼──────┼──────┼──────┼────────────────────────────── │
-│ □ │      │      │      │      │  [编辑] [删除] [...]          │  ← 数据行
-│ □ │      │      │      │      │                                │
-│   │      │      │      │      │                                │  ← 剩余数据区留白
-│   │      │      │      │      │                                │
-│   │      │      │      │      │                                │
-├─────────────────────────────────────────────────────────────────┤
-│ 共128条 · 第2/13页  每页[20▼]条       [◀ ‹ 1 2 ③ 4 5…13 › ▶] │  ← Pagination
-└─────────────────────────────────────────────────────────────────┘
-```
-
-上图是高密度管理页的常见结构，不是唯一模板。轻量列表、卡片列表、看板、时间线、图库或移动端优先页面，都可以根据内容形态采用更合适的呈现方式。
-
-### CSS 骨架参考
-
-```css
-.table-workbench {
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-  overflow: hidden;
-}
-.table-toolbar,
-.filter-bar,
-.pagination-bar {
-  flex-shrink: 0;
-}
-.table-region {
-  flex: 1;
-  min-height: 0;
-  overflow: auto;
-}
-```
-
----
-
-## 2. Toolbar 参考
-
-### 常见布局
-
-```html
-<div class="toolbar-area">
-  <div class="toolbar-left">
-    <input class="search-input" placeholder="搜索名称、ID…" />
-    <button class="filter-toggle-btn">高级筛选 ▼</button>
-  </div>
-  <div class="toolbar-right">
-    <button class="column-config-btn"><i class="fa-solid fa-gear"></i></button>
-  </div>
-</div>
-```
-
-- **toolbar-left**：搜索框 + 高级筛选按钮，左对齐
-- **toolbar-right**：列配置按钮，`margin-left: auto` 独立右对齐
-- 语义分离：筛选 = 数据范围，列配置 = 视图偏好
-
-### 搜索体验建议
-
-- 搜索框尺寸应匹配工具栏密度和页面宽度，常见管理页可从 240px 起步
-- placeholder 写明可搜索的字段（如"搜索名称、ID…"），避免只写"搜索"
-- 输入后使用短 debounce，避免频繁请求；具体时长按数据规模和响应速度调整
-- 有内容时右侧显示 × 清除按钮
-
-### 高级筛选建议
-
-- 字段较多、条件组合复杂或用户需要反复筛选时再提供高级筛选
-- 高级筛选通常放在搜索框附近，便于形成同一组数据范围控制
-- 点击展开面板（GSAP slideDown），面板内根据字段类型提供控件
-- 确认后在 Filter Bar 显示 pills 标签（如 `状态: 已发布 ×`）
-- 支持单个 pill 移除，或「清除全部」
-
-### 列配置建议
-
-- 字段多、角色关注点不同或表格需要长期使用时，可提供列配置
-- 常见做法是 popover + checkbox 控制列显隐
-- 视图偏好可存 `localStorage`，同页面下次打开保持
-- 可选：支持拖拽排序列顺序
-
----
-
-## 3. 分页组件
-
-### 布局
-
-| 位置 | 内容 |
-|------|------|
-| 左侧 | `共{total}条 · 第{current}/{totalPages}页` + `每页 [10/20/50/100▼] 条` |
-| 右侧 | `◀` 首页 · `‹` 上一页 · 页码 · 下一页 `›` · 尾页 `▶` |
-
-### 页码省略规则
-
-- 总页数 ≤ 7：全部显示
-- 总页数 > 7：当前页 ±2 + 首尾页 + 省略号
-  - 示例：`1 2 ③ 4 5 … 13`
-  - 示例：`1 … 5 6 ⑦ 8 9 … 13`
-- 点击省略号弹出输入框跳转
-
-### 交互规则
-
-- 当前页高亮（accent 色背景 + 白色文字）
-- 首页/末页边界时禁用对应按钮（`opacity: 0.5; cursor: not-allowed`）
-- 切换每页条数后重置到第 1 页
-- 默认每页数量按数据密度和屏幕空间决定，管理页可从 20 条起步
-
-### CSS 参考
-
-```css
-.pagination-bar {
-  padding: 12px 24px;
-  border-top: 1px solid var(--dg-border, #E2E8F0);
-  background: var(--dg-bg-base, #F8FAFC);
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  flex-shrink: 0;
-}
-.pagination-info {
-  font-size: 13px;
-  color: var(--dg-text-muted, #64748B);
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-.page-num-btn {
-  min-width: 32px; height: 32px;
-  padding: 0 8px; font-size: 13px;
-  border: 1px solid var(--dg-border, #E2E8F0);
-  background: var(--dg-bg-surface, #fff);
-  color: var(--dg-text-primary, #334155);
-  cursor: pointer; border-radius: 6px;
-  transition: all 0.2s;
-}
-.page-num-btn.active {
-  background: var(--dg-accent); color: white;
-  border-color: var(--dg-accent); font-weight: 600;
-}
-.page-num-btn:disabled {
-  opacity: 0.5; cursor: not-allowed;
-}
-```
-
----
-
-## 4. 表格本体
-
-| 规则 | 说明 |
-|------|------|
-| 表头 sticky | 滚动时固定，底部 1px shadow 分隔 |
-| 行 hover | `var(--dg-bg-base)` 浅色背景，transition 0.15s |
-| 操作列 | 固定右侧，≤3 个内联按钮 + 更多(…) 下拉 |
-| 行选择 | 左侧 checkbox，表头全选；选中后顶部出现批量操作栏 |
-| 排序 | 可排序列表头带排序图标，点击切换 asc/desc/none |
-| 空状态 | icon + 描述文案 + 可选操作按钮，布局可参考 `.empty-dg` |
-| 加载态 | 优先使用骨架屏或局部 loading，避免让整个页面空白等待 |
-
-### CSS 参考
-
-```css
-.table-dense {
-  width: 100%; border-collapse: collapse; text-align: left;
-}
-.table-dense th {
-  background: var(--dg-bg-base, #F8FAFC);
-  font-size: 13px; font-weight: 600;
-  color: var(--dg-text-muted, #64748B);
-  padding: 10px 16px;
-  border-bottom: 1px solid var(--dg-border, #E2E8F0);
-  position: sticky; top: 0; z-index: 10;
-}
-.table-dense td {
-  padding: 10px 16px;
-  border-bottom: 1px solid var(--dg-border, #E2E8F0);
-  font-size: 13px;
-  color: var(--dg-text-primary, #334155);
-  vertical-align: middle;
-}
-.table-dense tr:hover td {
-  background-color: var(--dg-bg-base, #F8FAFC);
-}
-```
-
----
-
-## 5. GSAP 动效
-
-本地可用插件（全部 GSAP 3.15.0，禁止境外 CDN）：
-
-| 路径 | 插件 | 用途 |
-|------|------|------|
-| `/assets/vendor/gsap/gsap.min.js` | 核心库 | 必须首先引入 |
-| `/assets/vendor/gsap/ScrollTrigger.min.js` | ScrollTrigger | 滚动触发动画 |
-| `/assets/vendor/gsap/ScrollToPlugin.min.js` | ScrollToPlugin | 滚动定位 |
-| `/assets/vendor/gsap/Observer.min.js` | Observer | 输入事件观察 |
-| `/assets/vendor/gsap/Draggable.min.js` | Draggable | 拖拽交互 |
-| `/assets/vendor/gsap/Flip.min.js` | Flip | 布局过渡（FLIP） |
-| `/assets/vendor/gsap/MotionPathPlugin.min.js` | MotionPathPlugin | 路径动画 |
-| `/assets/vendor/gsap/SplitText.min.js` | SplitText | 文字拆分动画 |
-| `/assets/vendor/gsap/TextPlugin.min.js` | TextPlugin | 文字逐字动画 |
-| `/assets/vendor/gsap/CustomEase.min.js` | CustomEase | 自定义缓动曲线 |
-| `/assets/vendor/gsap/EasePack.min.js` | EasePack | 扩展缓动（Bounce/Elastic 等） |
-| `/assets/vendor/gsap/DrawSVGPlugin.min.js` | DrawSVGPlugin | SVG 路径描边动画 |
-| `/assets/vendor/gsap/MorphSVGPlugin.min.js` | MorphSVGPlugin | SVG 形变动画 |
-
-引入方式（按需引入，核心库必须在插件前）：
-```html
-<script src="/assets/vendor/gsap/gsap.min.js"></script>
-<!-- 按需添加插件，例如： -->
-<script src="/assets/vendor/gsap/ScrollTrigger.min.js"></script>
-<script src="/assets/vendor/gsap/CustomEase.min.js"></script>
-```
-
-插件注册（引入后必须注册才能使用）：
-```javascript
-gsap.registerPlugin(ScrollTrigger, CustomEase);
-```
-
-动效设计以"帮助用户理解状态变化"为目标，不固定参数。可优先考虑：
-
-- 首次加载：列表项有节奏地进入，减少突然跳变
-- 翻页 / 筛选：旧数据离场、新数据入场，让变化可感知
-- 筛选面板：展开收起保持轻快，不抢夺操作注意力
-- filter pill：新增、移除时有明确反馈
-- 空态 / 批量操作栏：出现和消失要稳定、清楚、不中断任务
-
-具体 `duration`、`stagger`、`ease`、位移距离由页面密度、设备性能和品牌气质决定。
-
-### 翻页动效实现示例
-
-```javascript
-async function switchPage(newData) {
-  const rows = document.querySelectorAll('.table-dense tbody tr');
-  await gsap.to(rows, { opacity: 0, y: -8, duration: 0.15, stagger: 0.02 });
-  renderRows(newData);
-  const newRows = document.querySelectorAll('.table-dense tbody tr');
-  gsap.from(newRows, { opacity: 0, y: 12, duration: 0.25, stagger: 0.04, ease: 'power2.out' });
-}
-```
-
----
-
-## 6. 响应式策略
-
-| 断点 | 行为 |
-|------|------|
-| ≥1024px | 完整表格模式 |
-| 768–1023px | 隐藏次要列，列配置可恢复 |
-| <768px | 切换为卡片列表模式，分页改为「加载更多」按钮 |
-
----
-
-## 7. 数据加载模式
-
-```javascript
-const App = window.parent?.App;
-let currentPage = 1, pageSize = 20, totalItems = 0;
-
-async function loadData() {
-  const res = await App.get('db/items', {
-    page: currentPage,
-    page_size: pageSize,
-    search: searchKeyword || undefined,
-    ...activeFilters
-  });
-  if (res.code !== 200) { App.showError(res.message || '加载失败'); return; }
-  const { items, total } = res.data;
-  totalItems = total;
-  renderTable(items);
-  renderPagination();
-}
-```
-
-### 首次加载骨架屏
-
-页面初始化时先渲染 3-5 行骨架占位，异步拿到数据后替换为真实行并播放入场动画。
-
----
-
-## 8. 适用范围
-
-本规范适用于所有数据列表/表格类页面，包括但不限于：
-- 用户管理、角色管理
-- 页面管理、导航管理
-- 日志列表、反馈列表
-- 动态 DB 数据管理
-- 任何使用分页展示多条数据的场景
-
-**优先级**：用户有特殊 UIUX 指示时，以用户指示为准。