create-yss-spec 2.2.9 → 2.2.10

package/template/.codex/skills/yss-use-tree-height/SKILL.md

@@ -1,440 +1,98 @@
 ---
 name: yss-use-tree-height
-description: Use when working with YTree that needs responsive height, virtual scrolling, or built-in search and the useTreeHeight hook is involved.
+description: 指导 YTree、左树右表、组织树、分类树、树搜索和 Tab/抽屉内树区域使用 @yss-ui/hooks 的 useTreeHeight 实现自适应高度；当树区域需要独立滚动、容器切换后高度不正确或需要扣除 YTree 内置搜索高度时使用。
 ---
 
-# useTreeHeight 树组件高度计算 Hook
+# useTreeHeight 使用
 
-本目录是树高度的 canonical 技能；历史名称 `use-tree-height` 仅通过注册表和 Router alias 解析。
+## 触发条件
 
-## YSS canonical execution rules
+- YTree 或左树右表需要独立滚动区和自适应高度。
+- 树区域含内置搜索，或在 Tab/抽屉/折叠面板切换后高度不正确。
 
-- 使用真实签名 `useTreeHeight(containerRef, options)`，结果绑定到 `YTree` 的 `:height`。
-- `filterable` 时配置 `extraOffset: YTREE_SEARCH_HEIGHT`；不得重复扣减或添加无依据偏移。
-- 容器使用 `flex: 1; min-height: 0; overflow: hidden`，隐藏态切换后在可见的 `nextTick` 中调用 `recalculateHeight()`。
-- 不因节点数量少而强制开启虚拟滚动；按实际可见节点阈值决定是否裁剪 DOM。
+## 不适用场景
 
-## 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 `useTreeHeight` wiring. Use `yss-components` for tree layout/rendering rules and `yss-hook` for tree request/selection state.
+1. MCP 可用时，先用 `get_component_docs` 精确查询 `useTreeHeight`，需要示例时再调用 `get_demo`；不要仅凭 Skill 中的静态签名推断当前 API。
+2. 精确查询无结果时，先用 `search_docs` 校正名称；仅在 MCP 不可用、调用失败或仍无结果时，回退读取最新 `llms-full.txt`。文档版本与当前依赖不一致时，再核对 Hook 源码、CodeGraph 和真实导出。
 
-中文说明：这里只处理树高度计算，不处理树数据请求、选中状态或业务联动。
+## 硬约束（禁止/必须）
 
-## 💡 何时使用
+- 把树区域的直接父容器 `ref` 传给 `useTreeHeight(treeAreaRef, options)`，并使用真实返回值 `treeHeight/recalculateHeight`。
+- 最外层必须有可计算高度；树区域使用 `flex: 1; min-height: 0; overflow: hidden;`。
+- 计算结果绑定到 `YTree` 的 `:height="treeHeight"`，不用固定魔法高度替代 Hook，也不为了触发虚拟滚动默认添加 `:virtual="true"`。
+- 使用 YTree 内置搜索时配置 `extraOffset: YTREE_SEARCH_HEIGHT`；搜索区已放在 `treeAreaRef` 外部时不再扣除。
+- `extraOffset` 只用于树区域内部实际占位的搜索、padding 或边框，禁止无依据叠加 `+16` 等偏移。
+- Hook 仅在挂载时为当时存在的 `treeAreaRef` 建立 `ResizeObserver`。优先保持树区域外层容器挂载（如使用 `v-show`）；Tab/抽屉可见后在 `nextTick` 调用 `recalculateHeight()`。
+- 隐藏态容器可能得到 `minHeight` 而不是真实可用高度；不把该值当成最终布局结果。
 
-当页面中使用 `YTree` 组件且需要以下功能时，**必须**使用此 Hook：
-
-- ✅ 树需要自适应容器高度
-- ✅ 树启用了虚拟滚动 (`virtual`)
-- ✅ 树启用了内置搜索框 (`filterable`)
-- ✅ 树在 YSplitPane 的左侧面板中
-
----
-
-## ⚠️ Critical Rules（必读）
-
-### 规则 1：必须使用解构语法
-
-```typescript
-// ❌ 错误：直接赋值
-const treeHeight = useTreeHeight(treeAreaRef);
-
-// ✅ 正确：必须解构返回值
-const { treeHeight } = useTreeHeight(treeAreaRef);
-```
-
-> **为什么**：`useTreeHeight` 返回的是对象 `{ treeHeight, recalculateHeight }`，不是数字。
-
----
-
-### 规则 2：启用 filterable 必须传 `extraOffset: YTREE_SEARCH_HEIGHT`
-
-```typescript
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-
-// ❌ 错误：YTree 启用了 filterable 但没有设置 extraOffset（搜索框会被遮挡！）
-const { treeHeight } = useTreeHeight(treeAreaRef);
-
-// ✅ 正确：必须减去搜索框高度
-const { treeHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,  // 48px，YTree 内置搜索框高度
-});
-```
-
-> **为什么**：YTree 的 `filterable` 会在树顶部渲染一个 48px 的搜索框，如果不减去这个高度，树底部内容会被裁剪。
-
----
-
-### 规则 3：容器必须设置 Flex 布局
-
-```vue
-<template>
-  <!-- ❌ 错误：容器没有 flex 布局 -->
-  <div ref="treeAreaRef">
-    <YTree :height="treeHeight" />
-  </div>
-
-  <!-- ✅ 正确：容器设置 flex: 1 + overflow: hidden -->
-  <div ref="treeAreaRef" class="tree-container">
-    <YTree :height="treeHeight" />
-  </div>
-</template>
-
-<style scoped lang="less">
-.tree-container {
-  flex: 1;           // ← 必须：占据剩余空间
-  overflow: hidden;  // ← 必须：防止内容溢出
-}
-</style>
-```
-
----
-
-### 规则 4：ref 绑定到容器而非 YTree
-
-```vue
-<!-- ❌ 错误：ref 绑定到 YTree 组件 -->
-<YTree ref="treeAreaRef" :height="treeHeight" />
-
-<!-- ✅ 正确：ref 绑定到包裹 YTree 的容器 div -->
-<div ref="treeAreaRef" class="tree-container">
-  <YTree :height="treeHeight" />
-</div>
-```
-
----
-
-### 规则 5：使用 `:height` 而非 `:max-height`
-
-```vue
-<!-- ❌ 错误：YTree 使用 max-height（与 YTable 不同！） -->
-<YTree :max-height="treeHeight" />
-
-<!-- ✅ 正确：YTree 使用 height -->
-<YTree :height="treeHeight" />
-```
-
-> **对比**：YTable 用 `:max-height`，YTree 用 `:height`。
-
----
-
-## 📖 API 速查
-
-### 导入
-
-```typescript
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-```
-
-### 基本用法
-
-```typescript
-const { treeHeight, recalculateHeight } = useTreeHeight(containerRef, options);
-//       ↑ 绑定到 :height      ↑ 手动重算（少用）
-```
-
-### 关键配置（必须掌握）
-
-| 配置 | 何时必须设置 | 不配置的后果 |
-|------|-------------|-------------|
-| `extraOffset: YTREE_SEARCH_HEIGHT` | YTree 启用 `filterable` 时 | **树底部内容被裁剪** |
-
-### 导出常量
-
-| 常量 | 值 | 说明 |
-|------|------|------|
-| `YTREE_SEARCH_HEIGHT` | `48` | YTree 内置搜索框高度 |
-
-### 完整 API 参考
-
-> 💡 **完整参数和类型定义**请查阅：
-> - 在线文档：`http://192.168.164.27:3200/hooks/use-tree-height`
-> - 源码类型：`packages/hooks/src/useTreeHeight/types.ts`
-> - LLM 索引：`http://192.168.164.27:3200/llms-full.txt`（搜索 "useTreeHeight"）
-
----
-
-## ✅ 完整正确示例
-
-### 场景：左树右表布局（YSplitPane）
-
-```vue
-<script setup lang="ts">
-import { ref, computed } from 'vue';
-import { YSplitPane, YCard, YTree, YTable } from '@yss-ui/components';
-import { useTreeHeight, useTableHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-
-defineOptions({ name: 'TreeTablePage' });
-
-// === 左侧树 ===
-const treeAreaRef = ref<HTMLDivElement>();
-const treeData = ref([
-  { key: '1', title: '节点1', children: [{ key: '1-1', title: '子节点1-1' }] },
-  { key: '2', title: '节点2' },
-]);
-const selectedKeys = ref<string[]>([]);
-
-// 使用 Hook（必须解构 + 启用 filterable 时必须配置 extraOffset）
-const { treeHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,  // ← YTree 启用了 filterable，必须开启
-});
-
-// === 右侧表格 ===
-const tableAreaRef = ref<HTMLDivElement>();
-const tableData = ref([]);
-const loading = ref(false);
-
-const { tableHeight } = useTableHeight(tableAreaRef, {
-  withPagination: true,
-});
-
-const handleTreeSelect = (keys: string[]) => {
-  selectedKeys.value = keys;
-  // 根据选中节点加载表格数据
-};
-</script>
-
-<template>
-  <div class="page-container">
-    <YSplitPane :initial-width="280" :min-width="200" :max-width="400" collapsible>
-      <!-- 左侧：树 -->
-      <template #left>
-        <div class="left-panel">
-          <YCard title="分类" class="tree-card">
-            <!-- ref 绑定到容器 div -->
-            <div ref="treeAreaRef" class="tree-container">
-              <YTree
-                v-model:selected-keys="selectedKeys"
-                :tree-data="treeData"
-                :height="treeHeight"
-                filterable
-                virtual
-                @select="handleTreeSelect"
-              />
-            </div>
-          </YCard>
-        </div>
-      </template>
-
-      <!-- 右侧：表格 -->
-      <template #right>
-        <div class="right-panel">
-          <YCard title="数据列表" class="table-card">
-            <div ref="tableAreaRef" class="table-container">
-              <YTable
-                :data="tableData"
-                :loading="loading"
-                :max-height="tableHeight"
-                pageable
-              />
-            </div>
-          </YCard>
-        </div>
-      </template>
-    </YSplitPane>
-  </div>
-</template>
-
-<style scoped lang="less">
-.page-container {
-  height: 100%;
-}
-
-.left-panel,
-.right-panel {
-  height: 100%;
-}
-
-.tree-card,
-.table-card {
-  height: 100%;
-  display: flex;
-  flex-direction: column;
-
-  :deep(.ant-card-body) {
-    flex: 1;
-    display: flex;
-    flex-direction: column;
-    overflow: hidden;
-  }
-}
-
-// 关键：容器必须设置 flex: 1 + overflow: hidden
-.tree-container,
-.table-container {
-  flex: 1;
-  overflow: hidden;
-}
-</style>
-```
-
----
-
-### 场景：自定义搜索框（#search 插槽）
+## 标准代码骨架
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
 import { YTree } from '@yss-ui/components';
 import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-import { Input } from 'ant-design-vue';
-import { ReloadOutlined, PlusOutlined } from '@ant-design/icons-vue';
 
 const treeAreaRef = ref<HTMLDivElement>();
-const searchValue = ref('');
 const treeData = ref([]);
-
-// 即使使用自定义搜索框，仍需配置 extraOffset
-const { treeHeight } = useTreeHeight(treeAreaRef, {
+const { treeHeight, recalculateHeight } = useTreeHeight(treeAreaRef, {
   extraOffset: YTREE_SEARCH_HEIGHT,
 });
-
-const handleRefresh = () => {
-  // 刷新树数据
-};
-
-const handleAdd = () => {
-  // 新增节点
-};
 </script>
 
 <template>
-  <div ref="treeAreaRef" class="tree-container">
-    <YTree
-      v-model:search-value="searchValue"
-      :tree-data="treeData"
-      :height="treeHeight"
-      filterable
-      virtual
-    >
-      <!-- 自定义搜索区插槽 -->
-      <template #search>
-        <div class="tree-toolbar">
-          <Input
-            v-model:value="searchValue"
-            placeholder="搜索"
-            allow-clear
-            class="search-input"
-          />
-          <div class="toolbar-actions">
-            <ReloadOutlined class="action-icon" @click="handleRefresh" />
-            <PlusOutlined class="action-icon" @click="handleAdd" />
-          </div>
-        </div>
-      </template>
-    </YTree>
+  <div ref="treeAreaRef" class="tree-area">
+    <YTree :height="treeHeight" :tree-data="treeData" filterable />
   </div>
 </template>
 
 <style scoped lang="less">
-.tree-container {
-  flex: 1;
-  overflow: hidden;
-}
-
-.tree-toolbar {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px;
-
-  .search-input {
-    flex: 1;
-  }
-
-  .action-icon {
-    cursor: pointer;
-    color: #666;
-    &:hover {
-      color: #1890ff;
-    }
-  }
-}
+@import './style.less';
 </style>
 ```
 
----
-
-## ❌ 常见错误汇总
-
-### 错误 1：未解构返回值
-
-```typescript
-// ❌ 错误
-const treeHeight = useTreeHeight(treeAreaRef);
-```
-
-**结果**：树高度显示 `[object Object]` 或不生效
-
-**修复**：
-```typescript
-const { treeHeight } = useTreeHeight(treeAreaRef);
-```
-
----
-
-### 错误 2：启用 filterable 但未配置 extraOffset
-
-```typescript
-// ❌ 错误
-const { treeHeight } = useTreeHeight(treeAreaRef);
-```
-
-**结果**：树底部内容被裁剪，或搜索框与树内容重叠
-
-**修复**：
-```typescript
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-
-const { treeHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,
-});
-```
-
----
-
-### 错误 3：使用 :max-height 而非 :height
-
-```vue
-<!-- ❌ 错误：YTree 不应使用 max-height -->
-<YTree :max-height="treeHeight" />
-```
-
-**修复**：
-```vue
-<YTree :height="treeHeight" />
-```
-
----
-
-### 错误 4：容器缺少 flex 样式
-
 ```less
-// ❌ 错误
-.tree-container {
+/* style.less */
+.tree-layout {
   height: 100%;
+  display: flex;
+  flex-direction: column;
 }
-```
 
-**修复**：
-```less
-.tree-container {
+.tree-area {
   flex: 1;
+  min-height: 0;
   overflow: hidden;
 }
 ```
 
----
+## 容器切换时机
+
+```typescript
+import { nextTick } from 'vue';
 
-## 🔗 关联 Skills
+/** 容器显示后补充一次高度计算。 */
+const handleVisibleChange = async (visible: boolean) => {
+  if (!visible) return;
+  await nextTick();
+  recalculateHeight();
+};
+```
 
-- **page-module-development**：页面模块整体开发规范
-- **ytree-usage**：YTree 组件使用规范
-- **use-table-height**：表格高度计算（类似逻辑，但 YTable 用 `:max-height`）
+## 交付检查清单
 
----
+- [ ] `treeAreaRef` 在 Hook 挂载时可用，父级高度可计算。
+- [ ] 内置搜索开关与 `YTREE_SEARCH_HEIGHT` 偏移一致，没有重复扣减。
+- [ ] Tab/抽屉切换后使用真实的 `recalculateHeight()` 重算。
+- [ ] 节点较少时未裁剪 DOM 被识别为正常虚拟滚动阈值行为。
+
+## 失败兜底策略
 
-**最后更新**: 2026-02-04
+- 树高度显示为 `minHeight` 且与容器不符时，检查是否在隐藏态完成首次计算，并在可见后重算。
+- `treeAreaRef` 由 `v-if` 延迟创建且尺寸不再自动更新时，保持外层容器挂载后重新初始化 Hook，或使用 `v-show + recalculateHeight()`。
+- 节点较少未触发 DOM 裁剪时，核对虚拟滚动阈值，不加 `virtual=true` 伪装修复。

package/template/.codex/skills/yss-web-controller/SKILL.md

@@ -10,7 +10,7 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 何时使用
 
 - 用户要批量生成 Controller。
-- 用户要根据 metadata 或已有 Domain Gateway 生成 `AddCmd / UpdateCmd / PageQuery / VO / Controller / WebConvertor`。
+- 用户要根据冻结 OpenAPI 字段合同、metadata 和稳定 Application 接口生成 Request / Response / Controller / WebConvertor。
 - 用户要求统一 Web Adapter 风格、返回值和接口路径。
 
 ## 不适用
@@ -20,7 +20,7 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 
 ## 优先流程
 
-1. 先确认冻结 OpenAPI/no-impact record、Application Service 接口、metadata、基础包、模块名、领域 segment、domain/web 落盘目录。
+1. 先确认冻结 OpenAPI、批准的 Web generation contract、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同中的 `base_package`、`module_name`、`domain_segment` 必须与 CLI 一致。
 2. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
 3. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
 4. 运行 `node scripts/generate_controller.mjs`。
@@ -32,34 +32,35 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ```bash
 node scripts/generate_controller.mjs \
   --metadata-file /path/metadata.json \
+  --contract-file /path/approved-web-generation-contract.json \
   --base-package com.yss.demo \
   --module-name demo \
   --domain-segment example \
-  --domain-project-dir /path/demo-domain \
   --web-project-dir /path/demo-adapter/demo-web \
   --application-service-package com.yss.demo.application.service \
-  --validation-namespace javax \
-  --force
+  --validation-namespace javax
 ```
 
 ## 输出预期
 
-- `client/dto/cmd/*AddCmd.java`
-- `client/dto/cmd/*UpdateCmd.java`
-- `client/dto/query/*PageQuery.java`
-- `client/vo/*VO.java`
+- `rest/dto/request/*CreateRequest.java`
+- `rest/dto/request/*UpdateRequest.java`
+- `rest/dto/request/*PageRequest.java`
+- `rest/dto/response/*Response.java`
 - `rest/*Controller.java`
 - `rest/convertor/*WebConvertor.java`
 
 ## 约束
 
-- 生成代码默认依赖既有 Application Service。只有批准合同明确标记的纯查询 CQRS 工作单元才允许直接读 Gateway；写操作禁止绕过 Application。
+- 生成代码只依赖既有 Application Service；读写操作都禁止绕过 Application。复杂查询经 Application Query Port 接入 Infrastructure。
 - 返回结构保持项目既有 `SingleResult`、`PageResult`、`MultiResult` 体系。
 - DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
-- `WebConvertor` 默认使用 MapStruct；禁止在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝，除非有受控例外和测试证据。
+- `WebConvertor` 使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝。
+- HTTP Request 不继承会暴露内部协作字段的 `PageQuery`；只生成冻结 OpenAPI allowlist 字段，禁止把 `offset`、`needTotalCount`、`tempTotalCount` 变成客户端输入。
 - 先跑脚本，再按项目规范做少量手调。
 - `javax` / `jakarta` validation namespace 必须来自工程基线，不得按记忆选择。
 - 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
+- 脚本是 initialize-only；写入前先规划全部目标，任一目标已存在或传入 `--force` 时整体返回 `unsupported` 且不得留下部分文件。旧项目迁移不属于该生成器。
 
 ## 按需读取
 

package/template/.codex/skills/yss-web-controller/assets/templates/Controller.java.template

@@ -2,14 +2,13 @@ package ${base_package}.rest;
 
 ${application_service_import}
 ${dto_imports}
-${domain_import}
 ${web_convertor_import}
 import com.yss.cloud.dto.result.PageResult;
 import com.yss.cloud.dto.result.SingleResult;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiOperation;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import ${validation_namespace}.validation.Valid;
 
 /**
@@ -20,36 +19,36 @@ import ${validation_namespace}.validation.Valid;
 @RestController
 @RequestMapping("/api/${module_name}/${domain_url_path}")
 @RequiredArgsConstructor
-@Api(tags = "${domain_desc}管理")
+@Tag(name = "${domain_desc}管理")
 public class ${domain_class}Controller {
 
     ${application_service_field}
-    private static final ${web_convertor_class} CONVERTOR = ${web_convertor_class}.INSTANCE;
+    private final ${web_convertor_class} webConvertor;
 
     /**
      * 分页查询 ${domain_desc}
      */
     @PostMapping("/page")
-    @ApiOperation("分页查询")
-    public PageResult<${vo_class}> page(@Valid @RequestBody ${query_class} query) {
-        return CONVERTOR.toVOPage(${query_call});
+    @Operation(summary = "分页查询")
+    public PageResult<${response_class}> page(@Valid @RequestBody ${page_request_class} request) {
+        return webConvertor.toResponsePage(${query_call});
     }
 
     /**
      * 根据ID查询 ${domain_desc}
      */
     @GetMapping("/{id}")
-    @ApiOperation("详情查询")
-    public SingleResult<${vo_class}> detail(@PathVariable Long id) {
-        return SingleResult.of(CONVERTOR.toVO(${detail_call}));
+    @Operation(summary = "详情查询")
+    public SingleResult<${response_class}> detail(@PathVariable Long id) {
+        return SingleResult.of(webConvertor.toResponse(${detail_call}));
     }
 
     /**
      * 新增 ${domain_desc}
      */
     @PostMapping
-    @ApiOperation("新增")
-    public SingleResult<Long> add(@Valid @RequestBody ${add_cmd_class} cmd) {
+    @Operation(summary = "新增")
+    public SingleResult<Long> add(@Valid @RequestBody ${create_request_class} request) {
         return SingleResult.of(${add_call});
     }
 
@@ -57,8 +56,8 @@ public class ${domain_class}Controller {
      * 更新 ${domain_desc}
      */
     @PutMapping
-    @ApiOperation("更新")
-    public SingleResult<Boolean> update(@Valid @RequestBody ${update_cmd_class} cmd) {
+    @Operation(summary = "更新")
+    public SingleResult<Boolean> update(@Valid @RequestBody ${update_request_class} request) {
         return SingleResult.of(${update_call});
     }
 
@@ -66,7 +65,7 @@ public class ${domain_class}Controller {
      * 删除 ${domain_desc}
      */
     @DeleteMapping("/{id}")
-    @ApiOperation("删除")
+    @Operation(summary = "删除")
     public SingleResult<Boolean> delete(@PathVariable Long id) {
         return SingleResult.of(${delete_call});
     }

package/template/.codex/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -1,23 +1,33 @@
 package ${base_package}.rest.convertor;
 
 import com.yss.cloud.dto.result.PageResult;
-import ${base_package}.client.dto.cmd.${domain_class}AddCmd;
-import ${base_package}.client.dto.cmd.${domain_class}UpdateCmd;
-import ${base_package}.client.vo.${domain_class}VO;
-import ${base_package}.domain.${domain_pkg_name}.model.${domain_class};
+${application_type_imports}
+import ${base_package}.rest.dto.request.${domain_class}CreateRequest;
+import ${base_package}.rest.dto.request.${domain_class}UpdateRequest;
+import ${base_package}.rest.dto.request.${domain_class}PageRequest;
+import ${base_package}.rest.dto.response.${domain_class}Response;
 import org.mapstruct.Mapper;
-import org.mapstruct.factory.Mappers;
+import java.util.List;
 
-@Mapper
+@Mapper(componentModel = "spring")
 public interface ${web_convertor_class} {
 
-    ${web_convertor_class} INSTANCE = Mappers.getMapper(${web_convertor_class}.class);
+    ${domain_class}CreateCommand toCreateCommand(${domain_class}CreateRequest source);
 
-    ${domain_class} toDomain(${domain_class}AddCmd source);
+    ${domain_class}UpdateCommand toUpdateCommand(${domain_class}UpdateRequest source);
 
-    ${domain_class} toDomain(${domain_class}UpdateCmd source);
+    ${domain_class}PageQuery toPageQuery(${domain_class}PageRequest source);
 
-    ${domain_class}VO toVO(${domain_class} source);
+    ${domain_class}Response toResponse(${domain_class}Result source);
 
-    PageResult<${domain_class}VO> toVOPage(PageResult<${domain_class}> source);
+    List<${domain_class}Response> toResponses(List<${domain_class}Result> source);
+
+    default PageResult<${domain_class}Response> toResponsePage(PageResult<${domain_class}Result> source) {
+        return PageResult.of(
+                toResponses(source.getData()),
+                source.getTotalCount(),
+                source.getPageSize(),
+                source.getPageIndex()
+        );
+    }
 }