create-yss-spec 3.0.0 → 3.0.1

package/template/.hermes/skills/mapstruct/SKILL.md

@@ -1,334 +0,0 @@
----
-name: mapstruct
-description: |
-  MapStruct Java mapping framework. Covers basic mappers, update mappings,
-  nested objects, collections, custom methods, and Lombok integration.
-  Based on castellino and gestionale-presenze production patterns.
-
-  USE WHEN: user mentions "mapstruct", "@Mapper", "@Mapping", asks about
-  "DTO mapping", "entity conversion", "@MappingTarget", "nested mapping"
-
-  DO NOT USE FOR: Java language - use `java` skill instead
-  DO NOT USE FOR: Lombok - use `lombok` skill instead
-  DO NOT USE FOR: JPA entities - use JPA-specific skills
-allowed-tools: Read, Grep, Glob, Write, Edit
----
-# MapStruct Object Mapping
-
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `mapstruct` for comprehensive documentation.
-
-## YSS 阶段 7 执行结果
-
-- 消费批准后的 Slice Contract/work unit，只为合同中的 DTO/VO/PO/Domain 转换生成 Mapper/Convertor。
-- 受控生成必须记录 source/target、忽略字段、更新语义、Lombok processor 配置和 mapper 行为测试。
-- 按 `yss-router` 的统一 Execution Result 返回生成/源文件、测试和实际验证；未映射字段、反射/BeanUtils 退化或越界路径返回 `violation`。
-
-## Basic Mapper
-
-```java
-@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
-public interface UserMapper {
-
-    UserResponse toResponse(User user);
-
-    List<UserResponse> toResponseList(List<User> users);
-
-    @Mapping(target = "id", ignore = true)
-    @Mapping(target = "createdAt", ignore = true)
-    @Mapping(target = "updatedAt", ignore = true)
-    @Mapping(target = "password", ignore = true)
-    User toEntity(CreateUserRequest dto);
-}
-```
-
-## Update Mapping
-
-```java
-@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
-public interface UserMapper {
-
-    // Partial update - ignores null values
-    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
-    void updateEntity(UpdateUserRequest dto, @MappingTarget User user);
-
-    // Full update - sets all fields including nulls
-    void updateEntityFull(UpdateUserRequest dto, @MappingTarget User user);
-}
-```
-
-## Field Mapping
-
-```java
-@Mapper(componentModel = "spring")
-public interface OrderMapper {
-
-    // Different field names
-    @Mapping(source = "customer.name", target = "customerName")
-    @Mapping(source = "customer.email", target = "customerEmail")
-    @Mapping(source = "items", target = "orderItems")
-    OrderResponse toResponse(Order order);
-
-    // Constant values
-    @Mapping(target = "status", constant = "PENDING")
-    @Mapping(target = "createdAt", expression = "java(java.time.LocalDateTime.now())")
-    Order toEntity(CreateOrderRequest dto);
-
-    // Expression
-    @Mapping(target = "fullName", expression = "java(user.getFirstName() + \" \" + user.getLastName())")
-    UserResponse toResponse(User user);
-
-    // Date formatting
-    @Mapping(source = "createdAt", target = "createdDate", dateFormat = "yyyy-MM-dd")
-    OrderResponse toResponse(Order order);
-}
-```
-
-## Nested Objects
-
-```java
-@Mapper(componentModel = "spring", uses = {AddressMapper.class, ItemMapper.class})
-public interface OrderMapper {
-
-    // Uses AddressMapper for address field
-    // Uses ItemMapper for items collection
-    OrderResponse toResponse(Order order);
-}
-
-@Mapper(componentModel = "spring")
-public interface AddressMapper {
-    AddressResponse toResponse(Address address);
-}
-
-@Mapper(componentModel = "spring")
-public interface ItemMapper {
-    ItemResponse toResponse(Item item);
-}
-```
-
-## Enum Mapping
-
-```java
-@Mapper(componentModel = "spring")
-public interface StatusMapper {
-
-    @ValueMappings({
-        @ValueMapping(source = "ACTIVE", target = "ENABLED"),
-        @ValueMapping(source = "INACTIVE", target = "DISABLED"),
-        @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "UNKNOWN")
-    })
-    ExternalStatus toExternalStatus(InternalStatus status);
-}
-```
-
-## Custom Methods
-
-```java
-@Mapper(componentModel = "spring")
-public abstract class UserMapper {
-
-    @Autowired
-    protected RoleRepository roleRepository;
-
-    public abstract UserResponse toResponse(User user);
-
-    @Mapping(target = "roles", source = "roleIds")
-    public abstract User toEntity(CreateUserRequest dto);
-
-    // Custom mapping method
-    protected Set<Role> mapRoles(Set<Long> roleIds) {
-        if (roleIds == null) return new HashSet<>();
-        return roleIds.stream()
-            .map(id -> roleRepository.findById(id)
-                .orElseThrow(() -> new ResourceNotFoundException("Role", "id", id)))
-            .collect(Collectors.toSet());
-    }
-}
-```
-
-## Collection Mapping
-
-```java
-@Mapper(componentModel = "spring")
-public interface ProductMapper {
-
-    ProductResponse toResponse(Product product);
-
-    List<ProductResponse> toResponseList(List<Product> products);
-
-    Set<ProductResponse> toResponseSet(Set<Product> products);
-
-    // Page mapping
-    default Page<ProductResponse> toResponsePage(Page<Product> products) {
-        return products.map(this::toResponse);
-    }
-}
-```
-
-## After/Before Mapping
-
-```java
-@Mapper(componentModel = "spring")
-public abstract class UserMapper {
-
-    @AfterMapping
-    protected void afterMapping(@MappingTarget UserResponse response, User user) {
-        response.setDisplayName(user.getFirstName() + " " + user.getLastName().charAt(0) + ".");
-    }
-
-    @BeforeMapping
-    protected void beforeMapping(CreateUserRequest dto) {
-        if (dto.getEmail() != null) {
-            dto.setEmail(dto.getEmail().toLowerCase().trim());
-        }
-    }
-}
-```
-
-## Conditional Mapping
-
-```java
-@Mapper(componentModel = "spring")
-public abstract class UserMapper {
-
-    @Condition
-    public boolean isNotEmpty(String value) {
-        return value != null && !value.trim().isEmpty();
-    }
-
-    // Only maps non-empty strings
-    UserResponse toResponse(User user);
-}
-```
-
-## Maven Configuration
-
-```xml
-<properties>
-    <mapstruct.version>1.6.2</mapstruct.version>
-    <lombok.version>1.18.30</lombok.version>
-</properties>
-
-<dependencies>
-    <dependency>
-        <groupId>org.mapstruct</groupId>
-        <artifactId>mapstruct</artifactId>
-        <version>${mapstruct.version}</version>
-    </dependency>
-
-    <dependency>
-        <groupId>org.projectlombok</groupId>
-        <artifactId>lombok</artifactId>
-        <version>${lombok.version}</version>
-        <optional>true</optional>
-    </dependency>
-</dependencies>
-
-<build>
-    <plugins>
-        <plugin>
-            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-compiler-plugin</artifactId>
-            <version>3.13.0</version>
-            <configuration>
-                <source>17</source>
-                <target>17</target>
-                <annotationProcessorPaths>
-                    <!-- Order matters: Lombok first -->
-                    <path>
-                        <groupId>org.projectlombok</groupId>
-                        <artifactId>lombok</artifactId>
-                        <version>${lombok.version}</version>
-                    </path>
-                    <path>
-                        <groupId>org.mapstruct</groupId>
-                        <artifactId>mapstruct-processor</artifactId>
-                        <version>${mapstruct.version}</version>
-                    </path>
-                    <path>
-                        <groupId>org.projectlombok</groupId>
-                        <artifactId>lombok-mapstruct-binding</artifactId>
-                        <version>0.2.0</version>
-                    </path>
-                </annotationProcessorPaths>
-                <compilerArgs>
-                    <arg>-Amapstruct.defaultComponentModel=spring</arg>
-                </compilerArgs>
-            </configuration>
-        </plugin>
-    </plugins>
-</build>
-```
-
-## Key Annotations
-
-| Annotation | Purpose |
-|------------|---------|
-| `@Mapper` | Define mapper interface/abstract class |
-| `@Mapping` | Field-level mapping configuration |
-| `@MappingTarget` | Update existing object |
-| `@BeanMapping` | Bean-level mapping settings |
-| `@AfterMapping` | Post-processing method |
-| `@BeforeMapping` | Pre-processing method |
-| `@Condition` | Conditional mapping |
-| `@ValueMapping` | Enum value mapping |
-
-## Best Practices
-
-1. Use `componentModel = "spring"` for Spring injection
-2. Use `unmappedTargetPolicy = ReportingPolicy.IGNORE` for DTOs with fewer fields
-3. Always exclude `id`, `createdAt`, `updatedAt` when mapping from DTOs
-4. Use `@MappingTarget` for partial updates
-5. Order annotation processors: Lombok → MapStruct → Binding
-6. Use abstract classes instead of interfaces for custom logic
-7. Use `@Condition` for conditional mapping logic
-
----
-
-## When NOT to Use This Skill
-
-| Scenario | Use Instead |
-|----------|-------------|
-| Java language features | `java` skill |
-| Lombok annotations | `lombok` skill |
-| Spring configuration | `backend-spring-boot` skill |
-| JPA entity operations | JPA-specific skills |
-| Simple copying outside YSS contracts | Explicit manual mapping; in YSS slices follow the contract and never fall back to `BeanUtils.copyProperties` |
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Bad | Correct Approach |
-|--------------|--------------|------------------|
-| Mapping entities to entities | Breaks change tracking | Map DTO to entity |
-| Not using @MappingTarget | Inefficient updates | Use for partial updates |
-| Complex logic in expressions | Hard to test | Use custom methods |
-| Ignoring all unmapped | Misses fields silently | Use WARN or ERROR policy |
-| Not excluding audit fields | Overwrites metadata | Exclude id, timestamps |
-| Circular references | StackOverflowError | Break cycles with custom mapping |
-| Using interfaces for custom logic | Can't inject dependencies | Use abstract classes |
-| Not testing mappers | Runtime mapping errors | Write mapper tests |
-
----
-
-## Quick Troubleshooting
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "Cannot find implementation" | Annotation processing failed | Check processor configuration |
-| Lombok fields not found | Wrong processor order | Lombok before MapStruct |
-| Mapper not autowired | Wrong componentModel | Use componentModel = "spring" |
-| Circular dependency | Mappers reference each other | Use @Lazy or refactor |
-| UnmappedTargetProperty warning | Missing mapping | Add @Mapping or ignore policy |
-| NullPointerException in mapping | Null source | Add null checks or NullValuePropertyMappingStrategy |
-| Custom method not called | Wrong signature | Match method parameters exactly |
-| Generated code not updated | IDE cache | Clean and rebuild project |
-
----
-
-## Reference Documentation
-- [MapStruct Reference](https://mapstruct.org/documentation/stable/reference/html/)
-- [Spring Integration](https://mapstruct.org/documentation/stable/reference/html/#spring)
-- [Lombok Integration](https://mapstruct.org/faq/#can-i-use-mapstruct-together-with-project-lombok)
-
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `mapstruct` for comprehensive documentation.

package/template/.hermes/skills/migrate-to-shoehorn/SKILL.md

@@ -1,118 +0,0 @@
----
-name: migrate-to-shoehorn
-description: Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
----
-
-# Migrate to Shoehorn
-
-## Why shoehorn?
-
-`shoehorn` lets you pass partial data in tests while keeping TypeScript happy. It replaces `as` assertions with type-safe alternatives.
-
-**Test code only.** Never use shoehorn in production code.
-
-Problems with `as` in tests:
-
-- Trained not to use it
-- Must manually specify target type
-- Double-as (`as unknown as Type`) for intentionally wrong data
-
-## Install
-
-```bash
-npm i @total-typescript/shoehorn
-```
-
-## Migration patterns
-
-### Large objects with few needed properties
-
-Before:
-
-```ts
-type Request = {
-  body: { id: string };
-  headers: Record<string, string>;
-  cookies: Record<string, string>;
-  // ...20 more properties
-};
-
-it("gets user by id", () => {
-  // Only care about body.id but must fake entire Request
-  getUser({
-    body: { id: "123" },
-    headers: {},
-    cookies: {},
-    // ...fake all 20 properties
-  });
-});
-```
-
-After:
-
-```ts
-import { fromPartial } from "@total-typescript/shoehorn";
-
-it("gets user by id", () => {
-  getUser(
-    fromPartial({
-      body: { id: "123" },
-    }),
-  );
-});
-```
-
-### `as Type` → `fromPartial()`
-
-Before:
-
-```ts
-getUser({ body: { id: "123" } } as Request);
-```
-
-After:
-
-```ts
-import { fromPartial } from "@total-typescript/shoehorn";
-
-getUser(fromPartial({ body: { id: "123" } }));
-```
-
-### `as unknown as Type` → `fromAny()`
-
-Before:
-
-```ts
-getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose
-```
-
-After:
-
-```ts
-import { fromAny } from "@total-typescript/shoehorn";
-
-getUser(fromAny({ body: { id: 123 } }));
-```
-
-## When to use each
-
-| Function        | Use case                                           |
-| --------------- | -------------------------------------------------- |
-| `fromPartial()` | Pass partial data that still type-checks           |
-| `fromAny()`     | Pass intentionally wrong data (keeps autocomplete) |
-| `fromExact()`   | Force full object (swap with fromPartial later)    |
-
-## Workflow
-
-1. **Gather requirements** - ask user:
-   - What test files have `as` assertions causing problems?
-   - Are they dealing with large objects where only some properties matter?
-   - Do they need to pass intentionally wrong data for error testing?
-
-2. **Install and migrate**:
-   - [ ] Install: `npm i @total-typescript/shoehorn`
-   - [ ] Find test files with `as` assertions: `grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"`
-   - [ ] Replace `as Type` with `fromPartial()`
-   - [ ] Replace `as unknown as Type` with `fromAny()`
-   - [ ] Add imports from `@total-typescript/shoehorn`
-   - [ ] Run type check to verify

package/template/.hermes/skills/migrate-to-shoehorn/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Migrate to Shoehorn"
-  short_description: "Replace test assertions with shoehorn"

package/template/.hermes/skills/page-form-module/SKILL.md

@@ -1,168 +0,0 @@
----
-name: page-form-module
-description: 指导实现 YSS UI 新增、编辑和查看表单模块，覆盖 YFormily Schema、mode 0/1/2、详情渲染、数据回显与回填、表单值被意外清空排查、校验、提交 loading、弹窗销毁和列表刷新；当页面包含表单页、Modal 或 Drawer 表单，或编辑时回显丢失、提交后表单未重置时使用。
----
-
-# Page Form Module Skill
-
-## 触发条件
-
-- 实现新增、编辑、查看表单页，或 Drawer/Modal 中的表单闭环。
-- 需要处理 Schema、mode 0/1/2、回填、校验、提交和成功后列表刷新。
-
-## 不适用场景
-
-- 页面只包含列表查询，不包含任何表单编辑。
-- 表单为分步流程：使用 `formily-step-flow`。
-- 仅修复单个联动表达式：使用 `formily-linkage-effects`。
-
-## 必读依赖
-
-- 表单基础：`../formily-foundation/SKILL.md`
-- 联动副作用：`../formily-linkage-effects/SKILL.md`
-- 模式与详情：`../formily-mode-slot-detail/SKILL.md`
-- 分步表单：`../formily-step-flow/SKILL.md`
-- 接口与错误处理：`../yss-api-integration/SKILL.md`
-
-## 文档检索
-
-1. MCP 可用时，先用 `get_component_docs` 查询 `YFormily` 的 `mode`、`detail-options`、实例提交与回填 API，再按场景用 `get_demo` 获取 `formily/modes`、`formily/group`、`formily/linkage` 或 `formily/steps` 示例。
-2. 精确查询无结果时，先用 `search_docs` 或 `list_components` 校正名称；仅在 MCP 不可用、调用失败或校正后仍无结果时，回退读取最新 `llms-full.txt`。文档版本与当前依赖不一致时，再核对当前源码、CodeGraph 和真实导出。
-3. 当前会话已经加载上述本地 Skill 时，不要再通过 MCP 重复查询同一 Skill；仅在依赖 Skill 缺失时使用 `list_skills`、`get_skill` 补齐规则。
-
-## 硬约束（禁止/必须）
-
-- 提交前必须调用 `formRef.submit()` 或 `Submit.onSubmit` 进入完整校验链路。
-- `open/mode/currentId/formModel/submitting` 和回填、提交、关闭方法收敛在同一 Hook。
-- **数据前置同步原则（必守）**：表单数据必须在 `openCreate`/`openEdit` 触发前**同步赋好 `formModel.value`**；**严禁**在弹窗/抽屉组件内部通过 `watch(visible) + await nextTick() + initForm()` 异步回填数据（会导致首次编辑正常，切换新增再编辑时因时序差读取到残留空对象导致回显变空白的经典 Bug）。
-- **单一信任源**：使用 `v-model="formModel"` + `ref="formRef"` 调用 `submit()` 驱动；**严禁**在组件顶层写 `const form = createForm()` 与 `v-model`、`form.setValues`、`form.reset` 混用。
-- **禁止滥用动态 `:key`**：**严禁**在 `YFormily`/`YssFormily` 上使用 `:key="isEdit ? 'edit' : 'create'"` 等强制 Remount，应直接通过 `:mode` 或响应式数据驱动。
-- **弹窗生命周期隔离**：Modal/Drawer 必须配置 `:destroy-on-close="true"`，且内部 `YFormily` 必须使用 `v-if="open"` 随容器打开挂载、关闭销毁，避免宽度为 0 导致栅格退化，并彻底回收脏状态。
-- 新增/编辑/查看使用 `YFormily :mode="mode"`，`mode=2` 不渲染保存按钮。
-- Drawer 默认使用响应式宽度；基础表单设置 `FormLayout { labelWidth: 140, labelAlign: 'right' }`。
-- Drawer/Modal 中的 `FormGrid` 默认使用 `maxColumns: 2`、`minColumns: 1`、`minWidth: 320~360`；禁止 `minColumns: 2` 锁死两列。
-- 备注、说明和长文本通过 `x-decorator-props.gridSpan` 跨满整行。
-- 下拉选择器异步数据源必须使用 `enum` 或 `x-reactions` / `field.dataSource` 注入，严禁写入 `x-component-props.options`；基础字典下拉优先在弹窗打开前 `await` 拉取完成或在页面初始化提前拉取。
-- **表单校验规则规范**：必填文本字段声明 `whitespace: true`（如 `{ required: true, whitespace: true, message: '请输入xxx' }`）；自定义长度与格式校验必须使用条件式函数，空值放行交由 `required` 报错，非空才校验具体规则，禁止多个自定义校验重复承担必填职责。YFormily 适配层虽会归一化反馈展示，但不能代替正确的 Schema 语义。
-- 长整型 ID 按字符串原样回填和提交，禁止 `Number()`/`parseInt()`；表单中的普通数值按生成 DTO 真实类型处理。
-- 禁止使用 `if (res?.success)` 包裹保存成功逻辑，也禁止在 `catch` 重复 `message.error`。
-
-## 标准代码骨架
-
-```typescript
-import { ref } from 'vue';
-
-/** 默认表单模型 */
-const createDefaultModel = () => ({
-  name: '',
-  code: '',
-  description: '',
-});
-
-/** YFormily 业务侧仅需的实例方法。 */
-interface FormilyFormRef {
-  submit: () => Promise<Record<string, unknown>>;
-}
-
-/** 管理表单的模式、可见性、数据模型与提交链路。 */
-export const useRuleForm = (onSuccess: () => void) => {
-  const open = ref(false);
-  const mode = ref<0 | 1 | 2>(0);
-  const currentId = ref<string>();
-  const formModel = ref(createDefaultModel());
-  const submitting = ref(false);
-  const formRef = ref<FormilyFormRef>();
-
-  /** 打开新增：同步赋空值 */
-  const openCreate = (): void => {
-    mode.value = 0;
-    currentId.value = undefined;
-    formModel.value = createDefaultModel();
-    open.value = true;
-  };
-
-  /** 打开编辑：同步赋目标行数据，前置完成回填 */
-  const openEdit = (record: Record<string, any>): void => {
-    mode.value = 1;
-    currentId.value = record.id;
-    formModel.value = {
-      name: record.name ?? '',
-      code: record.code ?? '',
-      description: record.description ?? '',
-    };
-    open.value = true;
-  };
-
-  /** 关闭并清理 */
-  const close = (): void => {
-    open.value = false;
-    formModel.value = createDefaultModel();
-  };
-
-  /** 校验并保存表单。 */
-  const submit = async (): Promise<void> => {
-    if (mode.value === 2 || submitting.value || !formRef.value) return;
-
-    submitting.value = true;
-    try {
-      const values = await formRef.value.submit();
-      await saveRule({ ...formModel.value, ...values, id: currentId.value });
-      close();
-      onSuccess();
-    } catch {
-      // Formily 校验反馈或 mutator 已展示错误，此处不重复 Toast。
-    } finally {
-      submitting.value = false;
-    }
-  };
-
-  return { open, mode, currentId, formModel, submitting, formRef, openCreate, openEdit, close, submit };
-};
-```
-
-`saveRule` 必须替换为当前 Orval 真实生成方法，不得照抄占位名。
-
-```vue
-<YFormily
-  v-if="open"
-  ref="formRef"
-  v-model="formModel"
-  :schema="schema"
-  :mode="mode"
-  :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
-/>
-```
-
-```typescript
-/** Drawer 表单的基础布局 Schema。 */
-export const drawerFormLayout = {
-  type: 'void',
-  'x-component': 'FormLayout',
-  'x-component-props': { layout: 'horizontal', labelWidth: 140, labelAlign: 'right' },
-  properties: {
-    grid: {
-      type: 'void',
-      'x-component': 'FormGrid',
-      'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 340, columnGap: 24, rowGap: 16 },
-      properties: {},
-    },
-  },
-};
-```
-
-## 交付检查清单
-
-- [ ] `mode=0/1/2` 语义、回填和查看态渲染正确。
-- [ ] 提交先校验，又防重入，loading 始终在 `finally` 恢复。
-- [ ] Drawer/Modal 内 `YFormily` 按可见性条件挂载与销毁。
-- [ ] label 宽度和右对齐一致，FormGrid 能从 2 列响应式收缩为 1 列。
-- [ ] 长字段已跨行，长整型 ID 未转 number。
-- [ ] 没有 `if (res?.success)` 和重复错误 Toast。
-- [ ] 成功后关闭表单并通知上层刷新。
-- [ ] 业务层未导入 `@formily/antdv` UI 组件。
-
-## 失败兜底策略
-
-- 提交无响应时，先确认 `submit()` 是否实际调用并查看 Formily 校验反馈。
-- 编辑回填异常时，核对真实 DTO、字段路径与 Schema path，不在模板散落转换。
-- 表单过大时，拆分 Schema 生成函数、字典 Hook 和提交 Hook，保持 `index.vue` 不超过 150 行。