create-yss-spec 2.2.0 → 2.2.2

package/template/.agents/skills/yedit-table-usage/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: yedit-table-usage
+description: 指导 YSS UI 业务页面使用 @yss-ui/components 的 YEditTable 实现可编辑表格、行内编辑、添加/删除行、下拉多选与可创建 tags、行级候选联动、表头筛选、校验和查看态；当需求出现编辑表格、明细行、扩展属性、可编辑列或 YEditTableColumn 时使用。
+---
+
+# YEditTable 使用
+
+## 触发条件
+
+- 需求包含可编辑表格、行内编辑、明细行、扩展属性、行级候选联动或表格校验。
+- 需要使用 `YEditTableColumn`、`validate()`、`addable`、`filterOptions` 或表头筛选。
+
+## 不适用场景
+
+- 主列表只展示和分页：使用 `../ytable-usage/SKILL.md`。
+- 表单主体不是表格：使用 `../yss-formily/SKILL.md`。
+
+## 实施流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YEditTable` 的 Props、Events、Methods、`YEditTableColumn` 和操作列配置；需要添加行、多选/可创建下拉、行级联动或校验时，再用 `get_demo` 获取对应官方 Demo。
+2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+3. 区分列编辑器、行级候选、表头筛选三种职责，再设计行类型和校验。
+4. 把行类型、列配置、新行工厂和纯操作配置放到 `constant.ts`；把数据状态、API、联动和事件放到 Hook。
+5. 显式实现 `@add`、查看态、删除确认与 `validate()` 链路，再对照真实返回类型检查提交。
+
+## 硬约束（禁止/必须）
+
+- 业务可编辑表格必须优先使用 `YEditTable`，从 `@yss-ui/components` 导入 `YEditTable`、`YEditTableColumn`、`YTableActionConfig`；不用 `a-table` 手搭编辑态。
+- 有 `component` 的列会由组件自动补齐 `edit-render`，业务列不需要重复写 `editRender: {}`。
+- `component: 'form-item-select'` 的 `props.multiple: true` 表示从现有候选中多选；`props.allowCreate: true` 会进入 Ant Design Vue `tags` 模式，值必须按数组建模。
+- 当前实现中 `multiple` 优先于 `allowCreate`，同时配置并不会得到“多选且可新建”。该需求必须明确说明当前能力缺口，使用自定义插槽或先增强组件，禁止继续生成错误 demo。
+- 行级候选使用 `rowOptionsFieldName` 指定的行字段，或列级 `filterOptions({ field, optionsMap, row })`；不修改全局 `optionsMap` 影响其他行。
+- `filterOptions` 只过滤编辑态候选；表头筛选使用 `filterable + filters + filterMethod`，文本面板优先使用 `filterRender: { name: 'VxeInput', props: {...} }`。
+- `addable` 只渲染添加按钮并发出 `add`，不会自动创建行。必须监听 `@add` 并修改 `v-model:data`；业务插入位置要与 `addPosition` 一致。
+- `disabled` 只禁用表格编辑，不会自动隐藏添加按钮和操作列。查看态必须同时设置 `:addable="false"` 并移除操作列/按钮。
+- 删除使用 `type: 'action' + actionConfig.buttons[].isConfirm`；不默认使用 `Modal.confirm`。
+- `validate()` 真实返回 `Promise<{ valid: boolean; errorMsg: Map<string, string> }>`。组件 ref 未就绪时不得误判为校验成功。
+- 弹窗/抽屉内使用添加按钮时，高度 Hook 配置 `withAddButton: true`；如果同时分页或开启工具栏，一并开启对应偏移。
+- API 失败由 `mutator.ts` 统一提示并 reject。Hook 中不写 `success === false` 分支，不在 `else/catch` 重复 `message.error`；清理状态放在 `finally`。
+
+## 标准代码骨架
+
+```typescript
+import type { YEditTableColumn, YTableActionConfig } from '@yss-ui/components';
+
+/** 扩展属性行。 */
+export interface ExtRow {
+  id?: string;
+  _rowKey: string;
+  extName?: string;
+  extValues?: string[];
+  memo?: string;
+}
+
+/** 可编辑表格列。 */
+export const EDIT_COLUMNS: YEditTableColumn[] = [
+  {
+    field: 'extName',
+    title: '扩展属性',
+    minWidth: 220,
+    component: 'form-item-select',
+    props: { placeholder: '请选择扩展属性' },
+    customRule: (value, _row, _field, all) => {
+      if (!value) return { errMsg: '扩展属性不能为空' };
+      if (all.filter(item => item.extName === value).length > 1) return { errMsg: '扩展属性不能重复' };
+      return {};
+    },
+  },
+  {
+    field: 'extValues',
+    title: '扩展值',
+    minWidth: 240,
+    component: 'form-item-select',
+    props: { multiple: true, placeholder: '请选择扩展值' },
+    customRule: value =>
+      Array.isArray(value) && value.some(item => String(item).length > 100)
+        ? { errMsg: '单个扩展值最多 100 个字符' }
+        : {},
+  },
+  {
+    field: 'memo',
+    title: '备注',
+    minWidth: 240,
+    component: 'form-item-input',
+    props: { placeholder: '请输入备注' },
+    customRule: value => (String(value ?? '').length > 200 ? { errMsg: '最多 200 个字符' } : {}),
+  },
+  { type: 'action', title: '操作', width: 100, fixed: 'right' },
+];
+
+/** 表格字典数据；实际项目可由 Hook 响应式提供。 */
+export const EDIT_OPTIONS_MAP = {
+  extName: [
+    { label: '类型', value: 'type' },
+    { label: '级别', value: 'level' },
+  ],
+  extValues: [
+    { label: '默认', value: 'default' },
+    { label: '扩展', value: 'extended' },
+  ],
+};
+
+/** 创建前端新行。 */
+export const createEmptyRow = (): ExtRow => ({
+  _rowKey: `temp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  extValues: [],
+});
+
+/** 创建带删除确认的操作配置。 */
+export const createActionConfig = (onDelete: (row: ExtRow) => void): YTableActionConfig => ({
+  buttons: [
+    {
+      value: 'delete',
+      label: '删除',
+      type: 'link',
+      isConfirm: true,
+      confirmProps: { title: '是否确认删除此条数据？', okText: '确定', cancelText: '取消' },
+      click: ({ row }) => onDelete(row),
+    },
+  ],
+});
+```
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { YEditTable } from '@yss-ui/components';
+import { createActionConfig, createEmptyRow, EDIT_COLUMNS, EDIT_OPTIONS_MAP, type ExtRow } from './constant';
+
+/** 组件模式。0-新增，1-编辑，2-查看。 */
+interface Props {
+  mode: 0 | 1 | 2;
+}
+
+const props = defineProps<Props>();
+const rows = ref<ExtRow[]>([]);
+const tableRef = ref<InstanceType<typeof YEditTable>>();
+const readonly = computed(() => props.mode === 2);
+const columns = computed(() => (readonly.value ? EDIT_COLUMNS.filter(column => column.type !== 'action') : EDIT_COLUMNS));
+const actionConfig = createActionConfig(row => {
+  rows.value = rows.value.filter(item => item._rowKey !== row._rowKey);
+});
+
+/** 处理组件 add 事件，显式更新 v-model:data。 */
+const handleAddRow = () => {
+  rows.value = [...rows.value, createEmptyRow()];
+};
+
+/** 校验全部编辑行。 */
+const validateRows = async (): Promise<boolean> => {
+  if (!tableRef.value) return false;
+  const { valid } = await tableRef.value.validate();
+  return valid;
+};
+</script>
+
+<template>
+  <YEditTable
+    ref="tableRef"
+    v-model:data="rows"
+    :columns="columns"
+    :action-config="actionConfig"
+    :options-map="EDIT_OPTIONS_MAP"
+    :row-config="{ keyField: '_rowKey', useKey: true }"
+    :table-config="{ editConfig: { trigger: 'click', mode: 'row', autoClear: false } }"
+    :disabled="readonly"
+    :addable="!readonly"
+    add-btn-text="添加一行"
+    add-position="bottom"
+    @add="handleAddRow"
+  />
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+## Select 值类型边界
+
+```typescript
+/** allowCreate 对应 tags 模式，字段按数组存储。 */
+interface CreatableRow {
+  tags?: string[];
+}
+
+const creatableColumn: YEditTableColumn = {
+  field: 'tags',
+  title: '标签',
+  component: 'form-item-select',
+  props: { allowCreate: true, placeholder: '请选择或输入标签' },
+};
+```
+
+## 表头筛选
+
+```typescript
+const textFilterColumn: YEditTableColumn = {
+  field: 'columnName',
+  title: '目标列名称',
+  component: 'form-item-input',
+  filterable: true,
+  filters: [{ data: '' }],
+  filterMethod: ({ option, cellValue }) =>
+    String(cellValue ?? '').toLowerCase().includes(String(option?.data ?? '').trim().toLowerCase()),
+  filterRender: { name: 'VxeInput', props: { clearable: true, placeholder: '请输入关键词' } },
+};
+```
+
+- 远程筛选监听 `@filter-change`，并设置 `filterMethod: () => true` 禁用本地二次筛选。
+- 切换数据源或新增行后，可调用 `tableRef.value?.getTableInstance()?.clearFilter()`。
+- 只在面板高度定制时使用 `#<field>-filter`；修改 `option.data` 后调用 `updateFilterOptionStatus(option, !!option.data)` 同步状态。
+
+## 交付检查清单
+
+- [ ] `addable/@add/v-model:data/addPosition` 形成真实新增闭环。
+- [ ] `allowCreate` 和 `multiple` 未被错误组合，行字段类型与 Select 模式匹配。
+- [ ] 查看态同时禁用编辑、隐藏添加按钮和移除操作列。
+- [ ] `validate()` 按 `{ valid, errorMsg }` 处理，组件 ref 未就绪时不提交。
+- [ ] API Hook 没有重复 `message.error`，前端临时 key 不传给后端。
+
+## 失败兜底策略
+
+- 添加按钮无反应时，先确认已监听 `@add` 并更新 `v-model:data`，不继续调整 `addPosition`。
+- 查看态仍能删除/添加时，移除操作列并将 `addable` 设为 `false`，不只依赖 `disabled`。
+- 可创建多选与字段类型冲突时，回到 `allowCreate => tags 数组`、`multiple => 现有候选多选` 的真实实现；当前组合能力不足时明确报告。
+- API 联动失败时在 `finally` 恢复行级 loading，不捕获后重复 `message.error` 或继续使用失败结果。

package/template/.agents/skills/yss-api-integration/SKILL.md

@@ -1,11 +1,13 @@
 ---
-name: api-integration
+name: yss-api-integration
 description: Guide AI to correctly use Orval-generated API clients in Vue 3 micro-applications. This skill must be used whenever the user needs backend API integration, including list queries, CRUD actions, detail loading, submit flows, or API refactoring. It covers type-safe API imports, request/response mapping, and especially standardized useRequest integration patterns (manual/run/runAsync, pagination parameters, unified error handling, loading state, and success callbacks).
 ---
 
 # API 集成 Skill
 
-目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 Router alias 解析，不再维护第二份内容。
+
+目录、frontmatter、注册表 ID 和 Router canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 Router alias 表中解析为本技能。
 
 ## 📋 目标
 
@@ -56,6 +58,14 @@ packages/src/api/
 
 ## 🚀 使用步骤
 
+## YSS canonical execution rules
+
+- 先检查当前生成文件、`mutator.ts` 和冻结的 OpenAPI JSON 派生证据，不根据示例猜测导出名或响应形状。
+- 普通 JSON 请求中，`success === false` 已由 mutator reject；业务 Hook 不得再写 `if (res?.success)` 或重复 `message.error`。
+- loading 在 `finally` 中恢复；只有显式传入 `skipBusinessError` 或 `skipErrorHandler` 时，才允许实现局部错误交互。
+- 文件流必须保留 `{ data, headers }`，交给 `file-export-download` 的 `handleBlobResponse`；不得修改生成文件。
+- 长整型 ID 按冻结契约保持字符串，不得用 `Number`、`parseInt` 或位运算恢复为 number。
+
 ### 1. 查看可用 API
 
 打开 `packages/src/api/generated/api.ts` 查看所有可用的 API 函数。

package/template/.agents/skills/yss-components/SKILL.md

@@ -12,7 +12,7 @@ description: Use when YSS Vue 页面涉及布局、YTable、YEditTable、YFormil
 - YSS UI 组件文档：`http://192.168.164.27:3200/components`（组件契约以该手册为准；本技能依据 2026-08-18 可见内容整理）
 - 本地引用索引：`references/frontend-docs.md`
 
-本技能只负责页面组件、布局和交互呈现规范。请求、分页参数、接口映射交给 `yss-hook` 或 `api-integration`；完整页面生成流程交给 `yss-page-module-development`；表格/树高度细节交给 `yss-use-table-height` 或 `yss-use-tree-height`。
+本技能只负责页面组件、布局和交互呈现规范。请求、分页参数、接口映射交给 `yss-hook` 或 `yss-api-integration`；完整页面生成流程交给 `yss-page-module-development`；表格/树高度细节交给 `yss-use-table-height` 或 `yss-use-tree-height`。
 
 组件文档与当前项目的已验证用法冲突时，先检查当前项目代码和依赖版本，再决定是否迁移；不得把上游 Ant Design Vue、vxe-table、Univer 或 Monaco 的未验证 API 当作 YSS 顶层契约。
 

package/template/.agents/skills/yss-design-system/SKILL.md

@@ -89,7 +89,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
 | 原型阶段的 Ant Design v6 组件 / token / demo 查询 | `yss-antd-design`（只用于原型设计构建；前端落地改用 `yss-ui`） |
 | Codex 原型交接前的视觉 QA | `design-qa`；token / 字体对照读 `references/design-qa-theme.md`，以项目覆盖为准 |
-| API 契约 / 接入 | `yss-openapi-governance` / `api-integration` |
+| API 契约 / 接入 | `yss-openapi-governance` / `yss-api-integration` |
 
 ## 更新设计系统