create-yss-spec 2.1.9 → 2.1.11

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

@@ -0,0 +1,386 @@
+---
+name: "yss-components"
+description: Use when YSS Vue 页面涉及布局、YTable、YEditTable、YFormily、YTree、ConditionBuilder、空态、弹窗或业务组件选型。
+---
+
+# YSS 页面组件开发标准
+
+本技能用于统一 `views/**` 页面层的组件设计方式，参考 `QualityReportData` 页面沉淀标准，目标是提升一致性、可维护性与可复用性。
+
+## 0. 权威资料与边界
+
+- 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`。
+
+组件文档与当前项目的已验证用法冲突时，先检查当前项目代码和依赖版本，再决定是否迁移；不得把上游 Ant Design Vue、vxe-table、Univer 或 Monaco 的未验证 API 当作 YSS 顶层契约。
+
+## 0.1 组件选型速查
+
+| 场景 | 首选组件 | 关键边界 |
+| --- | --- | --- |
+| 常规动作、权限控制、操作下拉 | `YButton`、`AuthorityDropdown` | 用 `permissionCode` + `fallback` 控制隐藏/禁用；按需导入下拉必须使用 `AuthorityDropdown`，不使用仅全量注册的 `YDropdown` 别名。 |
+| 信息分组、统计卡片 | `YCard` | 组件不处理卡片布局；使用 CSS Grid/Flex 排版，`padding` 与 `bodyStyle.padding` 同时提供时以后者为准。 |
+| 左树右表、上下内容区 | `YSplitPane` | 轻内容使用默认实时拖拽；树、宽表、编辑器、图表等重内容使用 `resize-mode="deferred"` + `collapse-animation="transform"`。 |
+| 树、目录、资源导航 | `YTree` | 受控选择使用 `v-model:selected-keys`；大量节点必须给 `height`，再按需设置 `virtual`，不能只靠 CSS 高度。 |
+| 查询、编辑、详情表单 | `YFormily` | 新代码使用公开导出 `YFormily`；`YssFormily` 仅为历史兼容名。查询动作、展开状态和跨字段联动都以 schema / `scope` / `x-reactions` 表达。 |
+| 常规展示、选择、分页、筛选、操作列 | `YTable` | 远程分页和远程筛选由 Hook 管理；多选必须声明业务 `row-config.keyField`，不能依赖内部 `_X_ROW_KEY`。 |
+| 行内编辑、单元格校验、拖拽排序 | `YEditTable` | 只在确有编辑闭环时使用；保存前调用 `validate()`，以 `v-model:data` 与公开 `updateRow` 事件接回受控数据。 |
+| 嵌套 AND/OR、字段-操作符-值联动 | `YConditionBuilder` | 保存和请求映射在 Hook；组件只维护 `ConditionGroup`。复杂筛选不是把字段硬编码回普通 `YFormily` 模板。 |
+| 月视图、排班、日程状态 | `YMonthCalendar` | 是单日期选择与展示月份的独立状态，不是日期范围输入器；范围查询继续在 `YFormily` 的日期字段完成。 |
+| SQL / JSON / 配置编辑、日志阅读 | `YMonaco` / `YMonacoDiff` | 容器变更后必要时调用 `layout()`；日志追加使用 `appendContent()`，不反复 `setValue()`。 |
+| Cron 配置 | `YCron` | 输出为七段 `秒 分 时 天 月 周 年`；只使用其 `v-model`、`disabled`、`show-second`、`show-year` 公开契约。 |
+| 类 Excel 协作编辑 | `YSheet` | 必须给明确高度；只通过 Facade API 更新工作簿，卸载后释放实例；评估 Univer/React/RxJS 的包体影响。 |
+| 两步文件导入与失败结果下载 | `YFileImport` | 默认阻止 Upload 自动上传；在 `nextStep` / `finalImport` 事件中由业务实现校验、上传和结果回显。 |
+| 图表 | `YssEcharts` | 先阅读当前版本组件页面与项目现有图表实践，再确定 option、数据更新和容器尺寸方案。 |
+
+## 1. 触发场景
+
+当需求涉及以下任一内容时，优先按本技能执行：
+
+- 新建页面或重构页面结构
+- 左树右表、左右分栏、主从布局
+- YTable 列渲染、分页、空态
+- YFormily（或历史代码中的 YssFormily）查询区与 schema 配置
+- 页面级弹窗、详情抽屉、Header 信息区
+
+## 2. 页面目录规范
+
+单页面推荐结构：
+
+```text
+views/PageName/
+  components/
+    XxxBlock/
+      index.vue
+      style.less
+      type.ts
+      hooks/
+  hooks/
+    usePageTable.ts
+  schemas/
+    searchSchema.ts
+  index.vue
+  style.less
+```
+
+约束要求：
+
+- `index.vue` 仅编排页面，不承载复杂数据转换
+- `components/` 放展示型或区块型组件
+- `hooks/` 放页面业务逻辑 Hook
+- `schemas/` 放 YFormily 元数据定义
+
+## 3. 页面骨架规范（YSplitPane + YTree）
+
+页面容器使用 `YSplitPane`，并提供宽度边界与 `storage-key`。
+
+```vue
+<template>
+  <div class="page-name">
+    <YSplitPane
+      :initial-width="280"
+      :min-width="280"
+      :max-width="480"
+      collapsible
+      storage-key="page-name-split"
+    >
+      <template #left>
+        <div class="tree-panel"></div>
+      </template>
+      <template #right>
+        <div class="content-panel"></div>
+      </template>
+    </YSplitPane>
+  </div>
+</template>
+```
+
+补充要求：
+
+- 左侧区域承载目录、筛选树、统计导航
+- 右侧区域按顺序组织 Header、查询区、数据区
+- 右侧无选中对象时必须提供明确空态
+- 尺寸需要受控时使用 `v-model:left-width`（纵向使用 `v-model:top-height`）；`storage-key` 仅保存用户尺寸，不替代页面状态。
+- 左树使用业务主键配置 `field-names`，选中状态使用 `v-model:selected-keys`。树数据量大时传入明确 `height`，必要时启用虚拟滚动；搜索区通过 `#search`、`#header-left`、`#header-right` 扩展，不复制内置搜索逻辑。
+- 节点“更多”操作使用 `get-node-actions` 和 `@action`；默认点击更多会选中该节点，若不应改变主内容选择，显式设置 `:select-on-action-click="false"`。
+- 折叠树时默认保留内容状态（`destroy-on-collapse=false`）。只有确需释放重 DOM、且允许丢失树展开/勾选/滚动状态时才设为 `true`。
+
+## 4. 查询区规范（YFormily）
+
+查询表单必须采用 schema 驱动，页面中只负责绑定 `schema`、`scope`、初始值与插槽。
+
+```vue
+<YFormily
+  ref="formRef"
+  :schema="searchSchema"
+  :model-value="initialValues"
+  :scope="scope"
+>
+  <template #searchVal>
+    <a-input-group compact>
+      <a-select v-model:value="searchField" :options="tableFields" />
+      <a-input v-model:value="searchVal" />
+    </a-input-group>
+  </template>
+</YFormily>
+```
+
+schema 约束：
+
+- 使用 `FormLayout + FormGrid + FormItem` 组织字段
+- 按钮区使用 `AutoButtonGroup + Submit`
+- 行为通过 `onSubmit: '{{ handleQuery }}'` 等 scope 方法绑定
+- 新页面统一使用 `YFormily`；`YssFormily` 不作为新代码的组件名或类型来源。
+- 查询表单需要折叠时启用 `collapsible`，并用 `v-model:expanded` 管理外部状态。使用 `#actions` 自定义操作区后，组件会把折叠入口置于其左侧；不要再手写第二套展开逻辑。
+- 字段显隐、禁用、数据源联动使用 `x-reactions`；单字段输入优先监听底层组件的 `onUpdate:value`，选择/失焦事件以 Ant Design Vue 对应事件为准。复杂异步、副作用和跨页面可复用逻辑下沉到 Hook。
+- 详情页使用 `mode="2"`，字段插槽固定为 `#detail-<path>`（路径中的 `.` 替换为 `-`）；不要为只读页另建一套模板。
+
+## 5. 数据区规范（YTable）
+
+表格统一使用 `YTable`，要求支持分页与插槽渲染。
+
+```vue
+<YTable
+  :columns="columns"
+  :data="tableData"
+  :pageable="true"
+  :pagination="pagination"
+  :row-config="{ isCurrent: true, isHover: true, useKey: true }"
+  @page-change="onPageChange"
+  @size-change="onSizeChange"
+>
+  <template #quality_error_data="{ row }">
+    <a-typography-text :content="row.quality_error_data" :ellipsis="true" copyable />
+  </template>
+</YTable>
+```
+
+列定义建议：
+
+- 先固定序号列，再拼接动态列
+- 列字段名与接口字段保持一致
+- 长文本列优先 `showOverflow` 或省略显示
+- 按业务主键设置 `:row-config="{ keyField: 'id', useKey: true }"`；涉及刷新、树表、勾选或批量操作时这是必需项。
+- 分页数据来自服务端时在 `pagination` 中明确 `remote: true`，由 Hook 响应 `page-change` / `size-change` 后刷新数据和 `total`；不得让组件在远程数据上再次切片。
+- 远程列筛选监听 `filter-change`，列上提供稳定的 `filters`，并设置 `filterMethod: () => true` 禁用 vxe-table 本地过滤；本地筛选才编写真实 `filterMethod`。
+- 多选首列为 `type: 'checkbox'`，用 `v-model:selected-row-keys` 或 `v-model:selected-rows` 受控。批量动作放在 `#toolbar-right`，成功后重置选中键或调用 `clearSelection()`。
+- 插槽统一使用 kebab-case：`#<field>-header`、`#<field>-filter`、`#expand-row`、`#group-header`、`#toolbar-left`、`#toolbar-right`。不要把 camelCase 旧兼容写法用于新模板。
+- 最后一列宽度必须精确控制时设置 `:auto-flex-column="false"`；默认自动填满余宽。数据量达到组件阈值时让默认 `virtualXConfig` / `virtualYConfig` 生效，避免手动拼接分页假象。
+
+### 5.1 可编辑表格的升级条件
+
+只有同时满足“用户需要在行内编辑”和“编辑前校验、保存或取消回退”时，从 `YTable` 升级到 `YEditTable`：
+
+- 列通过 `component`（可为纯函数）声明编辑器；按行差异由 `cellProps(ctx)` 决定，函数不得有副作用。
+- 必填和自定义校验通过 `editRules` / `customRule` 声明，提交前调用 `tableRef.value.validate()`；校验失败不得发起保存请求。
+- 以 `v-model:data` 接收完整数据，或在 Vue 模板监听公开 `updateRow` 事件的 kebab-case 写法 `@update-row` 接收单元格变更；保存失败由业务层回退受控数据或保持编辑态，不能假定组件自动持久化。
+- 行级候选项优先级为“行对象 `rowOptionsFieldName`（默认 `options`）→ 列 `options` → `optionsMap[field]`”。字段联动、异步候选和清空关联值必须落在 Hook 的单一数据流中。
+- 编辑表的表头筛选仍是 `filterable + filters + filterMethod`；编辑态 `filterOptions` 只过滤该行下拉候选，二者不可混用。
+
+## 6. 交互状态规范
+
+页面至少覆盖以下状态：
+
+- `loading`：查询或刷新时显示 `a-spin`
+- `empty`：无列或无数据时显示 `AEmpty`
+- `selected`：依赖选中节点时，未选中显示引导空态
+- `error`：请求失败提示 `message.error`
+
+### 6.1 复杂条件、日历和导入的状态契约
+
+#### `YConditionBuilder`
+
+- 用于可嵌套的 AND/OR 条件树，根值必须是 `ConditionGroup`：`{ id, type: 'GROUP', logicalOp: 'AND' | 'OR', children }`；叶子是 `{ id, type: 'LEAF', field, operator, value, betweenValue1?, betweenValue2? }`。
+- 静态操作符使用 `operator-options`；字段切换需改变操作符或值候选时使用 `get-operators(field)` 与 `load-values({ q, field, operator })`。远程字段搜索使用 `load-fields(q)`。
+- 默认严格校验；提交前调用 `ref.validate()`。只有明确允许未完成草稿时才能关闭 `strict-mode`。
+- 嵌套深度由 `max-depth` 限制（默认 3）。条件树到接口筛选 DSL 的序列化、恢复与错误兜底必须放在 `hooks/useXxx.ts`，保留组件内的标准模型。
+- `readonly` 已废弃且不生效；展示态统一传 `disabled`。
+
+#### `YMonthCalendar`
+
+- `v-model` 管理一个选中 `Dayjs`，`v-model:month` 管理展示月份；两者不要混为一个日期范围字段。
+- `valid-range` 限制可选范围，`disabled-date` 处理业务禁用日期。`validRange` 起止传反时组件会自动交换，但业务仍应在 Hook 中规范化输入。
+- 需要连续假期/日程视觉时使用 `cell-layout="grid"` 和 `#date-cell` / `#date-cell-extra`；自定义单元格必须根据 `isToday`、`isSelected`、`isDisabled` 等上下文自行保留状态语义。
+- 父容器高度确定且需要填满时才使用 `fill-height`；它要求父容器有明确高度。键盘、右键或双击动作接入 `select`、`cell-contextmenu`、`cell-dblclick`，不覆盖组件默认焦点行为。
+
+#### `YFileImport`
+
+- 以 `v-model` 管理弹窗显示；选择文件、`nextStep` 校验/预检、结果回显、`finalImport` 确认构成两步流程。事件会提供 `fileList`、`loadingName` 和 `close`。
+- 默认 `beforeUpload` 始终返回 `false`，因此不能期待 `action` 自动上传。需要直传时只在 `upload-props.customRequest` 实现，文件类型规则由 `accept` 或 `file-type-list` 统一配置。
+- `importResult` 用于展示成功、失败和总数；失败文件下载用 `exportErrorData` 事件。遮罩、居中等弹窗配置只放 `modal-props`，上传器配置只放 `upload-props`。
+
+### 6.2 编辑器、Cron、Sheet 与图表
+
+- `YMonaco` 默认 `auto-layout`；在分栏折叠、抽屉打开等容器尺寸变化后确认编辑器已布局。只读日志使用 `language="log"` 或 `"yss-log"`，并用 `appendContent()` 追加；超大内容避免频繁重设完整字符串。
+- `YCron` 的业务值就是七段表达式。页面仅负责双向绑定和禁用态；Cron 到后端调度模型的转换、时区和生效校验属于接口/Hook 层。
+- `YSheet` 的 `modelValue` 是工作簿数据；初始化后经 `getUniverAPI()` / `getWorkbook()` 的 Facade 修改并用 `save()` 取值，禁止直接改 `IWorkbookData`。必须设置容器高度；使用前确认 optionalDependencies 已被私服安装成功。
+- `YssEcharts` 的 option、数据更新策略和容器尺寸以当前版本手册与项目既有实践为准；不得把原生 ECharts 初始化、实例销毁和 ResizeObserver 再复制进页面层。
+
+## 7. 组件编码规范
+
+- 使用 `<script setup lang="ts">`
+- 使用 `defineOptions({ name: 'PageOrComponentName' })`
+- 优先使用 `@yss-ui/components` 与 `ant-design-vue`
+- 样式默认 `style.less`，并在组件中显式引入
+- 页面脚本内保留编排逻辑，重逻辑下沉至 hooks
+
+## 8. 页面开发检查清单
+
+交付前自检：
+
+- 布局是否符合“左导航、右内容”分区
+- 查询区是否 schema 化且可扩展
+- 表格分页、空态、加载态是否完整
+- 插槽列是否处理长文本与复制/详情能力
+- 页面状态切换是否可回退且无脏数据残留
+
+## 9. 标准执行流程
+
+处理页面搭建需求时，按以下顺序执行：
+
+1. 先建立目录骨架（`components/hooks/schemas/index.vue/style.less`）
+2. 再完成布局分区（左树右表或主从分区）
+3. 再接入查询区（schema + scope + 插槽）
+4. 最后接入数据区（YTable + 分页 + 空态 + 详情弹窗）
+
+## 10. 输出内容模板
+
+完成任务后，输出建议包含以下四段：
+
+```markdown
+### 组件结构
+
+- 新增/调整了哪些页面区块
+
+### 数据交互
+
+- 查询、分页、空态如何衔接
+
+### 关键规范
+
+- 本次遵循了哪些 yss-components 规则
+
+### 文件清单
+
+- file path 1
+- file path 2
+```
+
+## 11. 禁止项
+
+- 不在 `index.vue` 写大段数据转换与请求编排
+- 不绕过 YSS 组件直接引入其他重型 UI 表格方案
+- 不把查询字段硬编码在模板中而跳过 schema
+- 不省略空态、加载态与错误提示
+
+## 12. 需求到实现示例
+
+示例需求：
+
+```text
+基于 QualityReportData 新建一个质量明细页面，要求左侧树筛选、右侧查询+表格+详情弹窗。
+```
+
+推荐实现要点：
+
+- 页面骨架复用 `YSplitPane`
+- 左侧封装独立树组件并通过事件回传选中节点
+- 查询条件全部放到 `schemas/searchSchema.ts`
+- 表格使用 `YTable`，详情使用插槽 + 弹窗
+
+## 13. 触发判定速查
+
+满足任一条件即可触发本技能：
+
+- 用户提到“页面搭建、页面重构、页面区块拆分”
+- 用户提到“YTable、YEditTable、YFormily、YTree、YSplitPane、ConditionBuilder”
+- 用户提到“左树右表、查询区、表格区、空态、详情弹窗”
+- 用户要求“参考 QualityReportData 做一个新页面”
+
+优先级建议：
+
+- 页面结构与组件编排问题，优先 `yss-components`
+- 请求与参数治理问题，优先 `yss-hook`
+
+## 14. 典型请求示例
+
+应触发示例：
+
+- “帮我按 QualityReportData 的结构搭一个新页面，左侧树右侧表格。”
+- “把这个页面查询区改成 YFormily schema 驱动。”
+- “YTable 需要加分页和空态，顺便补一个详情弹窗。”
+
+不应优先触发示例：
+
+- “这个接口请求参数怎么合并分页参数？”（更适合 `yss-hook`）
+- “useRequest 的 onSuccess 怎么做数据兜底？”（更适合 `yss-hook`）
+
+## 15. useRequest 与组件层协作边界
+
+本章节用于避免页面组件与 Hook 职责交叉。页面层允许使用 `useRequest`，但仅限轻量、一次性动作。
+
+### 15.1 页面层允许使用 useRequest 的场景
+
+- 导出下载、调试、校验、单次预览等动作型请求
+- 与当前页面强绑定、复用价值低、参数简单的请求
+- 不会引入分页治理和复杂数据映射的请求
+
+推荐写法：
+
+```typescript
+const { run: runExport, loading: exportLoading } = useRequest(exportApi, {
+  manual: true,
+  onSuccess: (res) => {
+    // 处理下载或成功提示
+  },
+  onError: () => {
+    message.error("导出失败");
+  },
+});
+```
+
+### 15.2 页面层不应承载 useRequest 的场景
+
+- 列表查询、分页查询、搜索联动请求
+- 需要 `currentParams` 统一治理的请求
+- 包含复杂数据转换、字段映射、树结构组装的请求
+
+这类逻辑必须下沉到 `hooks/useXxx.ts`，由 `yss-hook` 规范约束。
+
+### 15.3 组件与 Hook 的调用关系
+
+- 组件层负责收集参数、触发动作、渲染状态
+- Hook 层负责请求、数据转换、参数治理、异常兜底
+- 组件层通过 `scope`、事件回调、方法调用接入 Hook，不复制 Hook 内逻辑
+
+### 15.4 协作判定快表
+
+- 若请求影响表格分页状态：放 Hook
+- 若请求结果需要多处复用：放 Hook
+- 若请求仅服务当前按钮动作：可留组件层
+- 若请求需要导出复用筛选参数：放 Hook 并接入 `currentParams`
+
+## 16. 冲突决策三步法（组件 or Hook）
+
+当页面编排和请求逻辑同时出现时，按以下三步快速判定归属：
+
+1. **先看是否影响分页或筛选参数状态**
+   - 会影响 `page/pageSize/currentParams`：归 `yss-hook`
+   - 不影响：进入第 2 步
+2. **再看是否需要复用**
+   - 多页面/多区块复用：归 `yss-hook`
+   - 仅当前页面单点动作：进入第 3 步
+3. **最后看是否为一次性动作请求**
+   - 导出、调试、校验、单次预览：可留在 `yss-components`
+   - 列表查询、联动筛选、结构转换：归 `yss-hook`
+
+## 17. 二选一决策表
+
+- **场景：左树右表页面搭建** → 使用 `yss-components`
+- **场景：查询区改造为 schema 驱动** → 使用 `yss-components`
+- **场景：分页参数与筛选参数统一治理** → 使用 `yss-hook`
+- **场景：onSuccess/onError 数据兜底与映射** → 使用 `yss-hook`
+- **场景：导出按钮单次请求且不参与分页状态** → 可在 `yss-components` 就地处理
+- **场景：导出要复用 currentParams 并与列表一致** → 使用 `yss-hook`

package/template/.cursor/skills/yss-components/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Components"
+  short_description: "页面布局、表格、树、弹窗、空态与交互行为设计落地规范"
+  default_prompt: "Use $yss-components to design a YSS page layout with YTable, YTree, YssFormily, dialogs, and standard empty states."

package/template/.cursor/skills/yss-components/references/frontend-docs.md

@@ -0,0 +1,9 @@
+# yss-components Frontend Documentation
+
+Generated: 2026-08-17T12:03:37.436Z
+
+Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
+
+- components: http://192.168.164.27:3200/components
+
+When documentation and local code differ, inspect the current project code before editing and prefer established local usage.

package/template/.cursor/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: yss-ddd-scaffold-generator
+description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户要求从零创建符合 YSS 规范的 Domain、Application、Infrastructure、Adapter、Bootstrap 工程骨架时调用。
+---
+
+# yss-ddd-scaffold-generator
+
+这是一个脚手架生成型 skill。优先运行脚本和模板，不要手工拼装整套多模块工程。
+
+在产品生命周期中，本 skill 属于 Engineering Baseline / YSS DDD Review 阶段：用于从零创建后端服务骨架，或为架构设计提供标准模块边界输入。它不是业务实现阶段的替代品。
+
+## 何时使用
+
+- 用户要求从零创建新的 YSS 后端服务。
+- 用户要求一次性生成完整多模块工程骨架。
+- 用户需要标准的 Domain、Application、Infrastructure、Adapter、Bootstrap 目录和基础模板。
+
+## 不适用
+
+- 只补单个领域模型时，优先 `yss-domain`。
+- 只补持久层时，优先 `yss-repository`。
+- 只补 Web 层时，优先 `yss-web-controller`。
+
+## 优先流程
+
+1. 确认项目名、基础包名、输出目录、数据库类型。
+   Harness 内输出目录必须是 `apps/backend/` 容器，生成器再以 `project_name` 创建 `apps/backend/<project>/`；禁止使用 `app/backend/`、`app/frontend/` 或把 `apps/backend/` 之外的容器根当作后端项目根。
+2. 运行 `node scripts/generate_scaffold.mjs` 生成骨架。
+3. 检查生成的模块名、POM、基础配置文件和包路径。
+4. 由生命周期受控工作单元在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；生成器打印的下一步命令不构成验证证据。
+5. 如需继续细化，再追加其他 YSS skill 补全领域、仓储和 Web。
+
+受控验证命令由本 skill 的 `node scripts/run_scaffold_verification.mjs` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、耗时、执行时间和 `scaffold-verification.json`；任何一条命令失败或未执行都必须阻断。
+
+## 推荐命令
+
+```bash
+node scripts/generate_scaffold.mjs \
+  --project-name my-service \
+  --base-package com.yss.myservice \
+  --output-dir /path/to/implementation-repo \
+  --database mysql \
+  --contract-id <approved-scaffold-contract-id> \
+  --contract-version <current-version> \
+  --approval-ref <lifecycle-approval-ref> \
+  --router-draft-ref <router-draft-ref> \
+  --persisted-ref <persisted-contract-ref> \
+  --contract-file /path/to/persisted-scaffold-contract.json
+```
+
+## 生成结果应包含
+
+- 父工程 POM
+- `*-domain`
+- `*-application`
+- `*-infrastructure`
+- `*-adapter`
+- `*-bootstrap`
+- 基础配置、机械模板、构建脚本
+
+## 使用约束
+
+- 先在生命周期批准的脚手架受控生成合同下生成骨架，再做业务化定制；不要直接把脚手架当最终代码交付。
+- 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
+- 若仓库已经存在相同工程，先核对覆盖范围。
+- 输出目录必须显式指定；非空目录默认拒绝写入，确认覆盖时才使用 `--force`。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
+- 不要在 skill 里硬编码用户业务字段或真实连接信息。
+- 生成后要检查依赖关系是否仍符合分层约束。
+- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。
+- 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
+- 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
+- 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
+- 脚手架合同必须携带 `contract_id`、`contract_version`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
+- 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation` 和固定三条验证命令，不接受仅凭任意字符串引用的放行。
+- 生成项目必须写入非业务元数据清单 `.yss/scaffold-generation.json`，回勾合同 ID、版本、批准引用、生成输入、受控模式和固定验证命令；清单缺失时不得交给后续 Router。
+- 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
+- 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板；非空目标目录使用 `--force` 默认禁止，除非覆盖范围、备份、回滚点和批准引用已经进入当前合同。
+- 脚手架完成后，所有后续生成的后端代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract 和对应 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
+- `.mvn/settings.xml` 只能通过 `${env.MAVEN_REPO_USERNAME}` 和 `${env.MAVEN_REPO_PASSWORD}` 读取 Maven 仓库凭据；内部仓库构建前由 CI 或本地安全环境注入变量，禁止把 Maven 仓库用户名、明文密码或 Maven 加密密码写入 skill、模板或生成工程。
+- 涉及 API 契约时，先确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
+
+## 按需读取
+
+- 主脚本：`scripts/generate_scaffold.mjs`
+- 受控验证器：`scripts/run_scaffold_verification.mjs`
+- 模板目录：`assets/templates/`
+- 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
+
+## 阶段 7 合同
+
+- 仅在实现仓库/输出目录、`scaffold_status=required` 和批准合同明确时运行。
+- 工程骨架属于 `controlled-generation`，必须记录生成器输入、预期文件和 `./mvnw ...` 编译/测试结果；不得将业务状态机、权限、事务或查询逻辑混入生成步骤。
+- 生成结果必须包含 `.yss/scaffold-generation.json`，并由验证器回勾该清单；清单与批准合同不一致时阻断。
+- `./mvnw validate`、`./mvnw test`、`./mvnw package` 必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、耗时、stdout/stderr 引用和执行时间；只列命令计划、生成器成功或打印输出均视为缺失证据并阻断。
+- 生成后按统一 `YSS Skill Execution Result` 返回 changed/evidence files、实际验证结果和新增影响，再由 Router 为业务工作单元重新路由。

package/template/.cursor/skills/yss-ddd-scaffold-generator/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS DDD Scaffold"
+  short_description: "生成多模块 YSS DDD 后端脚手架与工程骨架规范"
+  default_prompt: "Use $yss-ddd-scaffold-generator only with a lifecycle-approved scaffold contract JSON to create a pure YSS DDD backend skeleton with domain, application, infrastructure, adapter, and bootstrap module boundaries; route all business code back through yss-router and the applicable YSS skills."

package/template/.cursor/skills/yss-ddd-scaffold-generator/assets/templates/config/application.yml.template

@@ -0,0 +1,37 @@
+server:
+  port: 8080
+
+spring:
+  application:
+    name: {{project_name}}
+
+  datasource:
+    primary:
+      url: {{jdbc_url}}
+      username: ${DB_USERNAME:}
+      password: ${DB_PASSWORD:}
+      driver-class-name: {{driver_class}}
+      hikari:
+        maximum-pool-size: 20
+        minimum-idle: 5
+        connection-timeout: 30000
+        idle-timeout: 600000
+        max-lifetime: 1800000
+
+mybatis-plus:
+  configuration:
+    map-underscore-to-camel-case: true
+    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
+  global-config:
+    db-config:
+      id-type: assign_id
+      logic-delete-field: deleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+
+logging:
+  level:
+    {{base_package}}: DEBUG
+    org.springframework.jdbc: DEBUG
+  pattern:
+    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"

package/template/.cursor/skills/yss-ddd-scaffold-generator/assets/templates/config/logback-spring.xml.template

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <springProperty scope="context" name="appName" source="spring.application.name"/>
+    <property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"/>
+
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>${LOG_PATTERN}</pattern>
+        </encoder>
+    </appender>
+
+    <root level="INFO">
+        <appender-ref ref="CONSOLE"/>
+    </root>
+</configuration>

package/template/.cursor/skills/yss-ddd-scaffold-generator/assets/templates/config/parent-pom.xml.template

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <groupId>com.yss.datamiddle</groupId>
+        <artifactId>yss-datamiddle-parent</artifactId>
+        <version>2.0.0-SNAPSHOT</version>
+        <relativePath/>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>{{group_id}}</groupId>
+    <artifactId>{{project_name}}-parent</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <name>{{project_name}}-parent</name>
+    <description>{{project_description}}</description>
+
+    <properties>
+        <yss-components.version>2.0.0-SNAPSHOT</yss-components.version>
+        <mapstruct.version>1.5.5.Final</mapstruct.version>
+    </properties>
+
+    <modules>
+        <module>{{project_name}}-domain</module>
+        <module>{{project_name}}-application</module>
+        <module>{{project_name}}-infrastructure</module>
+        <module>{{project_name}}-adapter</module>
+        <module>{{project_name}}-bootstrap</module>
+    </modules>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>com.yss.cloud</groupId>
+                <artifactId>yss-components-bom</artifactId>
+                <version>${yss-components.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+
+            <!-- 内部模块依赖 -->
+            <dependency>
+                <groupId>{{group_id}}</groupId>
+                <artifactId>{{project_name}}-domain</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>{{group_id}}</groupId>
+                <artifactId>{{project_name}}-application</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>{{group_id}}</groupId>
+                <artifactId>{{project_name}}-infrastructure</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/template/.cursor/skills/yss-ddd-scaffold-generator/assets/templates/pom/adapter-pom.xml.template

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.yss.datamiddle</groupId>
+        <artifactId>{{project_name}}-parent</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>{{project_name}}-adapter</artifactId>
+    <packaging>pom</packaging>
+
+    <modules>
+        <module>{{project_name}}-web</module>
+    </modules>
+</project>