create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-ui/references/quick-recipes.md

@@ -0,0 +1,280 @@
+# yss-ui Quick Recipes
+
+## 使用说明
+
+- 当任务是“新建页面”时，优先选用最接近的模板再改字段与交互。
+- 当任务是“重构页面”时，按“列定义 -> 插槽 -> 请求 -> 分页 -> 路由”顺序迁移。
+- 模板默认基于 Vue 3 + TypeScript + `@yss-ui/components`。
+- 组件与 Demo 先对照 `../assets/reference-index.md` 和 `../assets/demos/*` 再编码。
+
+---
+
+## 组件样例速查（docs 对照）
+
+- YTable：`../assets/demos/table/*`
+- YEditTable：`../assets/demos/edit-table/*`
+- YssFormily：`../assets/demos/formily/*`
+- YTree：`../assets/demos/tree/*`
+- SplitPane：`../assets/demos/split-pane/*`
+- YMonaco：`../assets/demos/monaco/*`
+- YEcharts：`../assets/demos/echarts/*`
+- YFileImport：`../assets/demos/file-import/*`
+- YConditionBuilder：`../assets/demos/condition-builder/*`
+- YCron：`../assets/demos/cron/*`
+- YCard：`../assets/demos/card/*`
+- YButton：`../assets/demos/button/*`
+
+---
+
+## 模板 1：列表管理页（带勾选、分页、状态、操作）
+
+```ts
+import { reactive, ref } from "vue";
+import { YTable, type YTableColumn } from "@yss-ui/components";
+
+const loading = ref(false);
+const tableData = ref<any[]>([]);
+const pagination = reactive({
+  current: 1,
+  pageSize: 10,
+  total: 0,
+  showSizeChanger: true,
+  showQuickJumper: true,
+});
+
+const columns = reactive<YTableColumn[]>([
+  { type: "checkbox", width: 50, align: "center" },
+  { type: "seq", title: "序号", width: 60, align: "center" },
+  { field: "name", title: "名称", minWidth: 180 },
+  { field: "owner", title: "负责人", width: 120 },
+  { field: "updatedAt", title: "更新时间", width: 180 },
+  { field: "status", title: "状态", width: 110 },
+  { field: "action", title: "操作", width: 180, fixed: "right" as const },
+]);
+```
+
+```vue
+<YTable
+  :columns="columns"
+  :row-config="{ keyField: 'id' }"
+  :data="tableData"
+  :loading="loading"
+  :pagination="pagination"
+  :checkbox-config="{ highlight: true }"
+  @change="handlePageChange"
+>
+  <template #status="{ row }">
+    <span :class="['status-dot', row.status === 'ENABLED' ? 'enabled' : 'disabled']"></span>
+    {{ row.status === "ENABLED" ? "启用" : "停用" }}
+  </template>
+  <template #action="{ row }">
+    <a @click="handleEdit(row)">编辑</a>
+    <a @click="handleDetail(row)">详情</a>
+    <a style="color: #ff4d4f" @click="handleDelete(row)">删除</a>
+  </template>
+</YTable>
+```
+
+---
+
+## 模板 2：待办审批页（列表 + 详情抽屉）
+
+```ts
+import { ref, reactive } from "vue";
+import { YTable, type YTableColumn } from "@yss-ui/components";
+
+const detailVisible = ref(false);
+const activeRecord = ref<any>(null);
+
+const columns = reactive<YTableColumn[]>([
+  { type: "checkbox", width: 50, align: "center" },
+  { type: "seq", title: "序号", width: 60, align: "center" },
+  { field: "approvalName", title: "审批名称", width: 220 },
+  { field: "submitter", title: "提交人", width: 120 },
+  { field: "submittedAt", title: "提交时间", width: 180 },
+  { field: "status", title: "状态", width: 110 },
+  { field: "action", title: "操作", width: 220, fixed: "right" as const },
+]);
+```
+
+```vue
+<YTable :columns="columns" :row-config="{ keyField: 'id' }" :data="tableData">
+  <template #approvalName="{ row }">
+    <a @click="openDetail(row)">{{ row.approvalName }}</a>
+  </template>
+  <template #action="{ row }">
+    <a @click="handleApprove(row)">同意</a>
+    <a style="color: #ff4d4f" @click="handleReject(row)">拒绝</a>
+    <a @click="openDetail(row)">详情</a>
+  </template>
+</YTable>
+```
+
+---
+
+## 模板 3：步骤创建页（步骤二节点表格）
+
+```ts
+import { reactive, ref } from "vue";
+import { YTable, type YTableColumn } from "@yss-ui/components";
+
+const nodeList = ref<any[]>([]);
+
+const nodeColumns = reactive<YTableColumn[]>([
+  { type: "seq", title: "序号", width: 70, align: "center" },
+  { field: "nodeName", title: "节点名称", minWidth: 160 },
+  { field: "taskType", title: "任务策略类型", width: 140 },
+  { field: "approverType", title: "审批人类型", width: 140 },
+  { field: "approvers", title: "审批人", minWidth: 220 },
+  { field: "action", title: "操作", width: 130, fixed: "right" as const },
+]);
+```
+
+```vue
+<YTable
+  :columns="nodeColumns"
+  :row-config="{ keyField: 'id' }"
+  :data="nodeList"
+  :border="true"
+>
+  <template #taskType="{ row }">
+    {{ row.taskType === "AUTO" ? "自动通过审批" : "人工审批" }}
+  </template>
+  <template #approvers="{ row }">
+    {{ row.approvers.join("、") || "-" }}
+  </template>
+  <template #action="{ row }">
+    <a @click="openEditDrawer(row)">编辑</a>
+    <a style="color: #ff4d4f" @click="removeNode(row.id)">删除</a>
+  </template>
+</YTable>
+```
+
+---
+
+## 模板 4：列表请求 + API 接入
+
+```ts
+const fetchData = async () => {
+  loading.value = true;
+  try {
+    const res = await getListApi({
+      page: pagination.current,
+      pageSize: pagination.pageSize,
+      keyword: query.keyword || undefined,
+      status: query.status || undefined,
+    });
+    tableData.value = res?.data?.list || [];
+    pagination.total = res?.data?.total || 0;
+  } finally {
+    loading.value = false;
+  }
+};
+
+const handleSearch = () => {
+  pagination.current = 1;
+  fetchData();
+};
+
+const handlePageChange = (page: number, size: number) => {
+  pagination.current = page;
+  pagination.pageSize = size;
+  fetchData();
+};
+```
+
+Mock 返回建议结构：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "list": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 10
+  }
+}
+```
+
+---
+
+## 模板 5：树表页面（YTree + useTreeHeight + SplitPane）
+
+```ts
+import { ref } from "vue";
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from "@yss-ui/hooks";
+
+const treeWrapRef = ref<HTMLDivElement>();
+const selectedKeys = ref<(string | number)[]>([]);
+const searchValue = ref("");
+const { treeHeight } = useTreeHeight(treeWrapRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT,
+});
+```
+
+```vue
+<div class="layout">
+  <YSplitPane :initial-width="300" :min-width="240" :max-width="480">
+    <template #left>
+      <div ref="treeWrapRef" class="tree-wrap">
+        <YTree
+          v-model:searchValue="searchValue"
+          v-model:selectedKeys="selectedKeys"
+          :height="treeHeight"
+          :tree-data="treeData"
+          filterable
+          @select="handleTreeSelect"
+        />
+      </div>
+    </template>
+    <template #right>
+      <YTable :columns="columns" :data="tableData" :row-config="{ keyField: 'id' }" />
+    </template>
+  </YSplitPane>
+</div>
+```
+
+---
+
+## 模板 6：YssFormily 模式切换（新增/编辑/查看）
+
+```ts
+const mode = ref<0 | 1 | 2>(0);
+const formData = ref<Record<string, any>>({});
+```
+
+```vue
+<YssFormily v-model="formData" :schema="schema" :mode="mode">
+  <template #detail-owner="{ value }">
+    <a-tag color="blue">{{ value || "-" }}</a-tag>
+  </template>
+</YssFormily>
+```
+
+规则要点：
+
+- 查看态插槽固定命名：`detail-<字段路径>`，路径中的 `.` 改为 `-`
+- 输入类事件优先 `onUpdate:value`，跨字段逻辑优先 `x-reactions/effects`
+
+---
+
+## 模板 7：文件导入两步流（YFileImport）
+
+```vue
+<YFileImport
+  v-model="visible"
+  :file-type-list="['xls', 'xlsx', 'csv']"
+  :import-result="importResult"
+  @nextStep="handleNextStep"
+  @finalImport="handleFinalImport"
+  @exportErrorData="handleExportErrorData"
+/>
+```
+
+要点：
+
+- 走“选择文件 -> 结果确认”两步交互
+- 失败数据通过 `exportErrorData` 下载回溯
+- 与表单联动时可复用 `formily.vue` 示例模式

package/template/.cursor/skills/yss-ui/references/theme-locale-overlay.md

@@ -0,0 +1,25 @@
+# 主题、Locale 与浮层门禁
+
+## 主题
+
+- 通过项目 `ConfigProvider`、`@yss-ui/theme`、语义 token 或项目 CSS variables 消费主题。
+- 禁止页面硬编码表面色、状态色、任意圆角、阴影和 z-index。
+- 暗色和紧凑模式由项目主题层切换，页面只消费语义角色。
+
+## Locale 与格式化
+
+- AntDV locale、时区和日期库由应用入口统一配置。
+- 页面不得混用 dayjs、moment、原生字符串拼接和不同金额格式化器。
+- 日期、金额、枚举、空值显示复用项目公共能力。
+
+## Popup / Teleport
+
+- Modal、Drawer、Dropdown、Popover、Tooltip、Select、DatePicker 使用项目统一 popup container。
+- 微应用中明确宿主根节点、Shadow DOM/Teleport 目标和卸载行为。
+- 禁止页面自行增加 z-index 解决遮挡；先修正挂载层级和项目 token。
+
+## 生命周期与焦点
+
+- 弹层关闭时清理临时表单、异步请求和订阅。
+- 根据项目版本选择正确的销毁属性，不猜测最新官网 API。
+- 打开后聚焦合理入口，关闭后恢复触发元素焦点。

package/template/.cursor/skills/yss-ui/references/verification.md

@@ -0,0 +1,20 @@
+# YSS UI 分层验证
+
+按影响面执行，未命中项记录 `not-applicable` 及原因。
+
+```text
+格式化
+→ lint
+→ type-check
+→ 组件测试
+→ 关键交互测试
+→ 响应式检查
+→ 主题、locale、popup 检查
+→ 必要的 E2E / 视觉回归
+```
+
+优先使用前端工程已有 `pnpm` scripts，不自行发明命令。Fresh verification 记录命令、退出码、环境、证据文件和未覆盖风险。
+
+最低人工检查：加载/空态/错误/权限、键盘和焦点、危险操作确认、窄屏布局、暗色/紧凑模式、浏览器 console warning。
+
+完成后返回 YSS Skill Execution Result 所需 changed files、evidence files、actual verification、deferred seams、drift/new impacts。

package/template/.cursor/skills/yss-up-springboot3/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: yss-up-springboot3
+description: Use when YSS Spring Boot 3 / Spring Cloud 升级辅助技能。Use when auditing or migrating YSS backend services/components from Spring Boot 2.x or Spring Cloud 2021-era dependencies toward Spring Boot 3, Jakarta namespace, newer Spring Security, MyBatis, OpenFeign, gateway, validation, and related compatibility changes.
+---
+
+# yss-up-springboot3
+
+Use this skill for YSS backend upgrade analysis and migration tasks around Spring Boot 3 / Spring Cloud compatibility.
+
+中文说明：这个技能是升级核查入口，不替代具体组件技能。遇到缓存、审计、MyBatis、DTO、Excel、JDBC 等组件细节时，应同时读取对应专项技能和源码索引。
+
+## When To Use
+
+- The user asks to upgrade YSS backend code to Spring Boot 3 or newer Spring Cloud baselines.
+- The task mentions `javax.*` to `jakarta.*`, Spring Security migration, validation changes, Servlet API changes, Gateway/OpenFeign compatibility, or dependency BOM changes.
+- The task involves checking whether a YSS component can run on Spring Boot 3.
+
+## Workflow
+
+1. Identify affected modules and current dependency versions from the local repository.
+2. Check for Jakarta namespace changes (`javax.servlet`, `javax.validation`, `javax.annotation`, JPA APIs, and related imports).
+3. Check Spring Security configuration style, deprecated adapters, authorization server dependencies, and filter registration behavior.
+4. Check component-specific integration by loading specialist skills such as `yss-mybatis`, `yss-dto`, `yss-cache`, `yss-audit-log`, `yss-excel-mvc`, or `yss-jdbc`.
+5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-source-index/references/source-location.md` before recommending code changes.
+6. Produce an upgrade checklist or patch with explicit compatibility risks and verification commands.
+
+## Common Checks
+
+- Maven BOM and plugin versions are aligned before changing code.
+- `javax.*` imports are migrated only where the target framework expects Jakarta APIs.
+- Spring Security configuration no longer depends on removed `WebSecurityConfigurerAdapter` patterns.
+- Validation annotations and exception handlers still map to the expected DTO/Result contract.
+- MyBatis interceptors, auto configurations, and starter metadata are compatible with Spring Boot 3 auto-configuration loading.
+- Tests or sample modules are updated together with framework code.
+
+## Do Not
+
+- Do not blindly rewrite all `javax.*` imports without checking whether the dependency still uses the old namespace.
+- Do not mix unrelated business refactors into migration patches.
+- Do not assume component compatibility from memory; inspect source and specialist skill indexes.

package/template/.cursor/skills/yss-up-springboot3/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Spring Boot 3 Upgrade"
+  short_description: "YSS 后端 Spring Boot 3 升级核查"
+  default_prompt: "Use $yss-up-springboot3 to audit a YSS backend module for Spring Boot 3 compatibility."