create-yss-spec 2.2.9 → 2.2.10

package/template/.claude/skills/yss-repository/references/infrastructure-layer-guide.md

@@ -1,192 +1,107 @@
-本 Skill 提供了 YSS **Infrastructure (基础设施层)** 的通用开发规范。Infrastructure 层负责实现 Domain 层定义的网关接口，处理数据持久化、外部服务调用和配置管理。
+# YSS Infrastructure Target Profile 指南
 
-## 1. 核心职责 (Core Responsibilities)
+本指南只定义 `target-domain-model + mybatis-plus`。历史 `Entity + DTO/VO Gateway` 为 `unsupported`，不存在旧架构 Profile。
 
-- **实现网关接口 (Gateway Implementation)**: 实现 Domain 层定义的 `Gateway` 接口。
-- **数据持久化 (Persistence)**: 定义 `Repository` 接口和 `PO` (Persistent Object) 实体，操作数据库。
-- **对象转换 (Conversion)**: 使用 MapStruct 实现 PO 与 Domain Model/DTO 之间的转换。
-- **外部适配 (External Adapters)**: 集成外部服务 (如文件存储、消息队列)。
+## 1. 职责
 
-## 2. 代码结构 (Code Structure)
+- 实现 Domain Gateway，负责 Aggregate 持久化。
+- 实现 Application Query Port，负责分页、列表和读模型。
+- 定义 PO、MyBatis-Plus Repository/Mapper、XML 和数据源适配。
+- 通过 Spring MapStruct Bean 完成 `PO <-> Domain Model`、`PO -> Application Result`。
 
-```
-com.yss.{module}.repository
-├── entity                  # 持久化对象 (PO)
-├── gateway.impl            # Domain Gateway 接口实现
-├── convertor               # MapStruct 转换器
-├── util                    # 工具类
-└── {Domain}Repository.java # MyBatis Plus Repository 接口
-```
-
-## 3. 开发规范 (Development Guidelines)
-
-### 3.1 持久化对象 (PO)
-
-- **命名**: `DomainName` + `PO` (e.g., `QualityTemplatePO`)。
-- **继承**: 推荐继承 `AuditableEntity` 以自动处理审计字段 (`created_by`, `created_date` 等)，但非强制要求。
-- **注解**:
-  - `@TableName("t_table_name")`: 指定数据库表名。
-  - `@TableId(value = "id", type = IdType.ASSIGN_ID)`: 指定主键策略 (雪花算法)。
-  - `@TableField("column_name")`: 指定字段映射。
-  - 按 `lombok` skill 选择最小注解；PO 默认使用 `@Getter` / `@Setter`，不得无条件使用 `@Data`。继承基类时再审查 `equals/hashCode/toString` 风险。
-
-### 3.2 Repository 接口
-
-- **继承**: `com.yss.cloud.mybatis.support.BasePlusRepository<PO>`。
-- **位置**: 直接位于 `com.yss.{module}.repository` 包下。
-- **Mapper XML**: 对应的 XML 文件位于 `src/main/resources/mappers`。
-
-### 3.3 Gateway 实现
-
-- **位置**: `com.yss.{module}.repository.gateway.impl`。
-- **注解**: `@Repository` 或 `@Service`。
-- **依赖注入**: 使用 `@RequiredArgsConstructor` (Lombok) 或 `@Autowired` 注入 Repository。
-- **查询逻辑**: 使用 `Wrappers.lambdaQuery()` 构建类型安全的查询条件。
-- **分页处理**: 使用 `PageUtil.page(query)` 构建分页对象，返回 `PageResult.of(...)`。
+Infrastructure 不拥有业务事务边界，不向 Application/Web 暴露 PO，也不直接生成 HTTP VO。
 
-### 3.4 对象转换 (Convertor)
+## 2. 包结构
 
-- **工具**: MapStruct。
-- **位置**: `com.yss.{module}.repository.convertor`。
-- **命名**: `DomainName` + `Convertor` (e.g., `QualityTemplateConvertor`)。
-- **规范**: 定义 `INSTANCE` 常量，使用 `Mappers.getMapper(...)` 获取实例。
+```text
+{base_package}.infrastructure
+├── persistence
+│   ├── po
+│   ├── repository
+│   ├── convertor
+│   └── gateway
+└── query
+    ├── adapter
+    └── convertor
+```
 
-## 4. 详细案例 (Detailed Examples)
+新脚手架固定使用 `{base_package}.infrastructure`。已有 `{base_package}.repository` 工程不由 scaffold 改写；需要现代化时单独立项。
 
-### 4.1 Persistent Object (PO)
+## 3. Domain Gateway 实现
 
 ```java
-package com.yss.quality.repository.entity;
-
-import com.baomidou.mybatisplus.annotation.IdType;
-import com.baomidou.mybatisplus.annotation.TableField;
-import com.baomidou.mybatisplus.annotation.TableId;
-import com.baomidou.mybatisplus.annotation.TableName;
-import lombok.Getter;
-import lombok.Setter;
-import lombok.EqualsAndHashCode;
-
-@Getter
-@Setter
-@EqualsAndHashCode(callSuper = true)
-@TableName("t_quality_template")
-public class QualityTemplatePO extends AuditableEntity {
-
-    @TableId(value = "id", type = IdType.ASSIGN_ID)
-    private Long id;
-
-    @TableField("template_name")
-    private String templateName;
+@Repository
+@RequiredArgsConstructor
+public class QualityTemplateGatewayImpl implements QualityTemplateGateway {
+    private final QualityTemplateRepository repository;
+    private final QualityTemplatePersistenceConvertor convertor;
 
-    @TableField("template_code")
-    private String templateCode;
+    @Override
+    public Optional<QualityTemplate> findById(QualityTemplateId id) {
+        return Optional.ofNullable(repository.selectById(id.value()))
+                .map(convertor::toDomain);
+    }
 
-    @TableField("status")
-    private Integer status;
+    @Override
+    public void save(QualityTemplate aggregate) {
+        repository.insertOrUpdate(convertor.toPO(aggregate));
+    }
 }
 ```
 
-### 4.2 Repository Interface
+GatewayImpl 不接收 Web Cmd/Query，不返回 VO/PageResult，不声明新的业务事务。
 
-```java
-package com.yss.quality.repository;
-
-import com.yss.cloud.mybatis.support.BasePlusRepository;
-import com.yss.quality.repository.entity.QualityTemplatePO;
-
-public interface QualityTemplateRepository extends BasePlusRepository<QualityTemplatePO> {
-}
-```
+## 4. Query Port 实现
 
-### 4.3 Gateway Implementation
+分页/列表属于 Application Query Port：
 
 ```java
-package com.yss.quality.repository.gateway.impl;
-
-import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
-import com.baomidou.mybatisplus.core.metadata.IPage;
-import com.baomidou.mybatisplus.core.toolkit.Wrappers;
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.quality.client.dto.query.QualityTemplatePage;
-import com.yss.quality.client.vo.QualityTemplateVO;
-import com.yss.quality.domain.template.gateway.QualityTemplateGateway;
-import com.yss.quality.repository.QualityTemplateRepository;
-import com.yss.quality.repository.convertor.QualityTemplateConvertor;
-import com.yss.quality.repository.entity.QualityTemplatePO;
-import com.yss.quality.repository.util.PageUtil;
-import lombok.RequiredArgsConstructor;
-import org.springframework.stereotype.Repository;
-import org.springframework.util.StringUtils;
-
-import java.util.List;
-
 @Repository
 @RequiredArgsConstructor
-public class QualityTemplateGatewayImpl implements QualityTemplateGateway {
-
-    private final QualityTemplateRepository qualityTemplateRepository;
+public class QualityTemplateQueryAdapter implements QualityTemplateQueryPort {
+    private final QualityTemplateRepository repository;
+    private final QualityTemplateQueryConvertor convertor;
 
     @Override
-    public PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query) {
-        LambdaQueryWrapper<QualityTemplatePO> wrapper = Wrappers.lambdaQuery(QualityTemplatePO.class);
-
-        // 构建查询条件
-        if (StringUtils.hasText(query.getTemplateName())) {
-            wrapper.like(QualityTemplatePO::getTemplateName, query.getTemplateName());
-        }
-        if (query.getStatus() != null) {
-            wrapper.eq(QualityTemplatePO::getStatus, query.getStatus());
-        }
-
-        wrapper.orderByDesc(QualityTemplatePO::getCreatedDate);
-
-        // 执行分页查询
-        IPage<QualityTemplatePO> result = qualityTemplateRepository.selectPage(PageUtil.page(query), wrapper);
-
-        // 转换结果
-        List<QualityTemplateVO> records = QualityTemplateConvertor.INSTANCE.toQualityTemplateVOList(result.getRecords());
-
-        return PageResult.of(
-                records,
-                result.getTotal(),
-                result.getSize(),
-                result.getCurrent()
-        );
+    public PageResult<QualityTemplateResult> page(QualityTemplatePageQuery query) {
+        // orderBy/groupBy 必须先映射到批准列白名单，再构造 MyBatis 条件。
+        return convertor.toResultPage(repository.selectPage(...));
     }
 }
 ```
 
-### 4.4 Convertor (MapStruct)
-
-```java
-package com.yss.quality.repository.convertor;
-
-import com.yss.quality.client.vo.QualityTemplateVO;
-import com.yss.quality.repository.entity.QualityTemplatePO;
-import org.mapstruct.Mapper;
-import org.mapstruct.factory.Mappers;
+`PageQuery` 可以在 Web/Application/Infrastructure 协作链使用，但不得进入 Domain。`orderBy` / `groupBy` 禁止直接拼接 SQL。
 
-import java.util.List;
+## 5. PO 与 Repository
 
-@Mapper
-public interface QualityTemplateConvertor {
-    QualityTemplateConvertor INSTANCE = Mappers.getMapper(QualityTemplateConvertor.class);
+- Target Profile 使用 `*PO`；旧式 `*Entity` 布局为 `unsupported`。
+- PO 默认使用最小 Lombok 注解，不无条件使用 `@Data`。
+- 当前实现继承项目既有 `BasePlusRepository<PO>`；普通 MyBatis 为 `unsupported`。
+- Mapper XML 位于项目既有扫描路径；扫描包和 XML 路径必须由集成测试证明。
 
-    QualityTemplateVO toQualityTemplateVO(QualityTemplatePO po);
+## 6. MapStruct
 
-    List<QualityTemplateVO> toQualityTemplateVOList(List<QualityTemplatePO> pos);
+```java
+@Mapper(componentModel = "spring")
+public interface QualityTemplatePersistenceConvertor {
+    QualityTemplate toDomain(QualityTemplatePO source);
+    QualityTemplatePO toPO(QualityTemplate source);
 }
 ```
 
-## 5. 注意事项 (Notes)
+- 禁止 `INSTANCE = Mappers.getMapper(...)`。
+- Convertor 使用构造器注入。
+- 父 POM 必须配置 `mapstruct-processor`、Lombok 和 `lombok-mapstruct-binding`。
+- 验证必须编译生成实现，不能只检查接口文本。
+
+## 7. 验证
 
-1.  **AuditableEntity**: 推荐业务 PO 继承此基类，以便自动维护审计信息。
-2.  **Lombok 使用**: 使用 `@RequiredArgsConstructor` 进行构造器注入是推荐的最佳实践。
-3.  **Wrapper 使用**: 优先使用 `Wrappers.lambdaQuery()` 而不是字符串列名，以提高重构安全性。
-4.  **分页工具**: 使用 `PageUtil` 统一处理分页参数，避免手动计算 offset。
+- Domain Gateway：保存后可通过 Gateway seam 重新加载等价 Aggregate。
+- Query Port：分页、total、排序白名单和空结果。
+- Mapper/Repository：实际 MyBatis-Plus/H2 或批准数据库 fixture。
+- Architecture：Infrastructure 可以依赖 Application/Domain；反向依赖必须失败。
+- 使用项目根 `./mvnw test/package` 留证。
 
-## 6. 阶段 7 合同
+## 8. 旧架构边界
 
-- 前置条件是批准的数据架构、Repository 策略和 Slice Contract。
-- PO/Repository/Convertor 骨架可受控生成；复杂查询、分页语义、数据源、事务、迁移和并发使用 `behavior-tdd`。
-- 返回统一 `YSS Skill Execution Result`，证据包含实际文件、集成测试、MapStruct/Lombok 配置和 `./mvnw ...` 结果。
+检测到 Repository 直接接收 client Query、返回 VO、Convertor 做 `PO -> VO` 或使用旧式 Entity 布局时，返回 `unsupported`，不得由新 scaffold 自动改写。旧项目继续按原工程维护；现代化改造必须单独立项。

package/template/.claude/skills/yss-router/references/router-contract.yaml

@@ -5,7 +5,6 @@ skill_aliases:
   api-integration: yss-api-integration
   microapp-commit: yss-microapp-commit
   page-module-development: yss-page-module-development
-  yss-ui-business-page-generation: yss-page-module-development
   use-table-height: yss-use-table-height
   use-tree-height: yss-use-tree-height
 implementation_path_policy:
@@ -108,17 +107,41 @@ context_plan:
   missing_context_action: [blocked, reroute]
 
 scaffold_contract_schema:
-  schema_version: 1
+  schema_version: 2
+  identity: service-engineering-baseline
   compiled_by: yss-router
   approved_by: yss-product-lifecycle
   status_by_owner:
     router: [draft, ready-for-lifecycle-review, blocked]
     lifecycle: [approved, stale, blocked]
-  required: [contract_id, contract_version, slice_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, target_git_url_or_output_dir, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, overwrite_policy]
+  required: [contract_id, contract_version, scaffold_request_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, project_name, target_output_dir, base_package, maven_coordinates, profiles, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, generation_policy]
   approval:
     required: [approval_ref, approver, persisted_ref, current_version]
-  overwrite_policy:
-    required: [force_allowed, overwrite_scope, rollback_ref]
+  generation_policy:
+    required: [mode, existing_target, old_project_migration, template_upgrade]
+    mode: initialize-only
+    existing_target: unsupported
+    old_project_migration: unsupported
+    template_upgrade: unsupported
+  maven_coordinates:
+    required: [group_id, project_version, parent, yss_components_version]
+    parent_required: [group_id, artifact_id, version]
+    yss_components_version: 2.0.0-SNAPSHOT
+  profiles:
+    required: [architecture, persistence, database, platform, validation_namespace, dto_placement, repository]
+    supported_initial:
+      architecture: target-domain-model
+      persistence: mybatis-plus
+      database: mysql
+      platform: spring-boot-2.7-jdk8
+      validation_namespace: javax
+      dto_placement: web
+      repository: yss-internal
+    unsupported: [old-architecture-profile, client-in-domain, mybatis, spring-boot-3, jakarta, separate-client-module]
+  unsupported_inputs:
+    schema_v1: reject-no-auto-upgrade
+    slice_id: forbidden-as-scaffold-identity
+    existing_project: reject-no-scaffold-migration
   lifecycle_boundary:
     router_emits: [draft, ready-for-lifecycle-review, blocked]
     lifecycle_approves: [approved]
@@ -127,12 +150,18 @@ scaffold_contract_schema:
   work_unit:
     required: [id, behavior, primary_skill, supporting_skills, tdd_mode, allowed_write_paths, expected_evidence, verification_commands, controlled_generation]
   generation_boundary:
-    allowed_for: [project_scaffold, pom, mechanical_config, wrapper]
+    allowed_for: [project_scaffold, pom, mechanical_config, wrapper, bootstrap_entrypoint, manifest_v2, architecture_rules, test_infrastructure]
     forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+    initialization: initialize-only
+    regeneration: unsupported
+    template_upgrade: unsupported
+    old_project_migration: unsupported-separate-architecture-modernization-initiative
   verification:
     commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
     requires_execution: true
-    evidence: [command, exit_code, duration_ms, stdout_ref, stderr_ref, executed_at]
+    completion_levels: [generated, empty-scaffold-verified, first-slice-verified]
+    downstream_readiness_claim_requires: first-slice-verified
+    evidence: [preflight, command, exit_code, failure_category, duration_ms, stdout_ref, stderr_ref, executed_at]
 
 applicable_subcontract_nonempty:
   frontend:
@@ -183,6 +212,11 @@ dependency_closure:
     always: [yss-exception]
   yss-exception:
     always: [yss-dto]
+  yss-ui-business-page-generation:
+    when_components: [yss-components]
+    when_hooks: [yss-hook]
+    when_form: [yss-formily]
+    when_api: [yss-api-integration]
   yss-page-module-development:
     when_components: [yss-components]
     when_hooks: [yss-hook]

package/template/.claude/skills/yss-ui/SKILL.md

@@ -46,14 +46,15 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 - `YTable` 替代 AntDV `Table`，列使用 `field/type` 和字段同名插槽。
 - `YTree` 替代 AntDV `Tree`。
-- `YssFormily` 是新代码 canonical name；`YFormily` 仅作为已确认导出的 deprecated alias。
+- `YFormily` 是新代码 canonical name；`YssFormily` 仅作为已确认导出的历史兼容 alias。
 - `YSplitPane`、`YButton`、`YCard` 等已有封装优先使用 YSS。
 
 ## 4. 最小专项 skill 路由
 
 | 任务 | 必须路由 |
 |---|---|
-| 完整页面模块 | `yss-page-module-development` |
+| 新建或改造完整业务页面 | `yss-ui-business-page-generation` |
+| 生命周期页面编排与旧触发词兼容 | `yss-page-module-development` |
 | 页面布局、组件和交互 | `yss-components` |
 | 请求、分页、参数、树数据映射 | `yss-hook` |
 | Formily schema、联动、校验、详情态 | `yss-formily` |
@@ -78,7 +79,7 @@ views/PageName/
 - `index.vue` 只做页面编排和事件转发。
 - `components/` 承载区块展示和局部交互。
 - `hooks/` 承载请求、分页、参数单一来源、映射和错误兜底。
-- `schemas/` 承载 `YssFormily` schema。
+- `schemas/` 承载 `YFormily` schema。
 - 页面内禁止复制请求流程、分页状态和复杂字段转换。
 
 ## 6. 跨组件强制约束
@@ -129,7 +130,7 @@ verification: pnpm type-check
 1. 读取批准合同、项目版本和组件映射。
 2. 选择最小专项 skills。
 3. 搭页面目录和布局。
-4. 接 `YssFormily`、`YTable`、`YTree` 等 YSS 主体组件。
+4. 接 `YFormily`、`YTable`、`YTree` 等 YSS 主体组件。
 5. 下沉请求、分页和映射到 `yss-hook`。
 6. 接高度、主题、locale、浮层和无障碍约束。
 7. 联调冻结 API、Mock、路由和权限。
@@ -139,7 +140,7 @@ verification: pnpm type-check
 
 - [ ] 已记录 Vue、YSS UI、AntDV、VXE 实际版本。
 - [ ] 组件选型符合 `component-routing.md`，回退有证据。
-- [ ] 新代码使用 `YssFormily` 和真实存在的 `yss-hook`。
+- [ ] 新代码使用 `YFormily` 和真实存在的 `yss-hook`。
 - [ ] YTable/YTree/Formily/高度 Hook 遵循专项 skill。
 - [ ] 主题、locale、浮层容器和微应用隔离已检查。
 - [ ] loading/empty/error/no-access/selected 状态按影响面覆盖。

package/template/.claude/skills/yss-ui/references/component-routing.md

@@ -9,7 +9,7 @@
 | 数据表格 | `YTable` | VXE Table + AntDV Pagination | specialized | 使用 `yss-components`、`field/type`、字段插槽 |
 | 编辑表格 | `YEditTable` | VXE Table | specialized | 对照 edit-table docs/demo |
 | 树 | `YTree` | AntDV Tree | specialized | 搜索、Tooltip、动作和高度路由 |
-| Schema 表单 | `YssFormily` | Formily + AntDV | specialized | `YssFormily` 为 canonical；加载 `yss-formily` |
+| Schema 表单 | `YFormily` | Formily + AntDV | specialized | `YFormily` 为 canonical；`YssFormily` 仅为历史兼容名；加载 `yss-formily` |
 | 分栏布局 | `YSplitPane` | YSS layout | required | 统一主从页面与容器高度 |
 | 文件导入 | `YFileImport` | Upload/业务适配 | required | 使用 YSS 上传结果和表单适配 |
 | 条件构建 | `YConditionBuilder` | YSS domain component | required | 使用对应 docs/demo |

package/template/.claude/skills/yss-ui-business-page-generation/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: yss-ui-business-page-generation
+description: 指导生成或改造 Vue3 YSS UI CRUD、列表、表单、详情、左树右表和弹窗抽屉页面，覆盖组件选型、模块拆分、Orval API、响应式高度、主题和原型验收；当用户要求生成 YSS UI 业务页或 CRUD 模块时使用。
+---
+
+# YSS UI 业务页面生成 Skill
+
+## 触发条件
+
+- 用户要求生成或改造业务页面、CRUD 模块、列表页、表单页、详情页、左树右表、树表联动页面。
+- 页面涉及 `YTable`、`YTree`、`YFormily`、`YButton`、`YCard`、`YSplitPane`、`YConditionBuilder` 等 YSS UI 组件。
+- 需要让 AI 优先复用 YSS UI 组件、hooks、utils，而不是直接使用 Ant Design Vue 或重复造工具函数。
+- 用户提供旧项目路径、原型截图、目标截图或要求“照旧项目/照原型还原”。
+
+## 不适用场景
+
+- 只修改 yss-ui 组件库内部实现：回到 yss-ui 源仓库，使用其 `categories.library` 维护流程；该类 skill 不随业务模板分发。
+- 只写文档、提交信息或发版流程，不生成业务页面代码。
+- 用户明确要求不用 YSS UI 组件库。
+
+## 必读参考
+
+- 组件来源速查：`./references/component-map.md`
+- Hooks 速查：`./references/hooks-map.md`
+- Utils 速查：`./references/utils-map.md`
+- 表格细节：`../ytable-usage/SKILL.md`
+- 编辑表格细节：`../yedit-table-usage/SKILL.md`
+- 树形细节：`../ytree-usage/SKILL.md`
+- 表单细节：`../yss-formily/SKILL.md`
+- 原型还原验收：`../prototype-page-acceptance/SKILL.md`
+- 主题 Token 与换肤：`../theme-token-usage/SKILL.md`
+- 文件导出下载：`../file-export-download/SKILL.md`
+- Orval 接口与错误处理：`../yss-api-integration/SKILL.md`
+
+## 文档检索顺序
+
+1. 当前会话可用 yss-ui MCP 时，生成业务代码前先调用一次 `get_codegen_rules`；不确定导出时用 `list_components`，配置组件/Hook/Utils 前用 `get_component_docs`，复杂场景用 `get_demo`，不确定归属时用 `search_docs`。
+2. MCP 查询未命中时，先用 `list_components` 或 `search_docs` 校正名称；只有 MCP 工具不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。
+3. MCP/`llms-full.txt` 与当前项目的依赖版本或导出不一致时，使用当前项目源码、CodeGraph 和可编译导出交叉核验，明确记录差异，不猜测 API。
+4. 当前 Skill 已被本地加载时不得再用 `get_skill` 查询自身；仅在所需子 Skill 未同步到本地时才用 `list_skills/get_skill` 兜底。
+
+## 硬约束（禁止/必须）
+
+- 生成页面前必须先判定组件来源：YSS UI 已封装的组件从 `@yss-ui/components` 导入。
+- 表单默认使用 `YFormily + JSON Schema`，业务代码禁止导入 `@formily/antdv` UI 组件。
+- 所有 `YFormily` 横向业务表单必须显式设置固定 `labelWidth` 与 `labelAlign: 'right'`，并使用 `FormLayout -> FormGrid -> 字段` 响应式结构；禁止用 `minColumns: maxColumns` 固定列数破坏响应式。
+- 标准列表/CRUD 查询区必须采用 `YCard -> search-content -> search-form(YFormily) + search-actions(YButton 查询/重置)` 的纵向布局；按钮行独占下一行并右对齐，缩放或窄屏字段换行后仍位于搜索卡片右下角。
+- 查询区禁止横向放“表单 + 按钮”并用大 `gap`、`align-items: flex-start`、`padding-top` 硬调按钮位置。
+- 抽屉/弹窗编辑表单默认 `labelWidth: 140`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`，备注/长文本字段用 `gridSpan` 占满整行。
+- 下拉选择器（`Select`/`TreeSelect`/`Radio.Group`）异步数据源必须通过 `enum` 或 `x-reactions` / `field.dataSource` 注入，严禁写入 `x-component-props.options`（会导致首次打开弹窗显示“暂无数据”、关闭再打开才展示的经典时序 Bug）；弹窗基础下拉字典优先在打开前 `await` 或页面初始化提前拉取。
+- 表格默认使用 `YTable`；远程分页使用 `pageable + pagination.remote + @page-change`，事件参数固定读取 `{ current, pageSize }`，禁止使用 `currentPage`。
+- 编辑表格默认使用 `YEditTable`；需求出现“编辑表格/添加行/删除行/行内下拉”时禁止直接用 `a-table` 手搓。
+- 左树右表优先使用 `YSplitPane + YCard + YTree + YTable`，高度使用 `useTreeHeight/useTableHeight`。
+- 标准列表必须使用 `YTable` 真实 API：`:data`、`:columns`、`:loading`、`pageable`、`v-model:pagination`、`@page-change`；禁止臆造 `request/search-params` 等 Prop。实例 `refresh()` 只刷新当前 vxe 表格数据，远程重新查询必须调用业务 Hook。
+- 新增/导入/批量操作等主操作直接放入 `#toolbar-right` 插槽；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
+- 删除确认默认使用 `YTable actionConfig.buttons[].isConfirm` 按钮项或 AntDV `Popconfirm` 气泡确认，禁止默认使用居中 `Modal.confirm`。
+- 样式抽离到 `style.less`，在 SFC 中使用 `<style scoped lang="less">@import './style.less';</style>`。
+- `index.vue` 原则上不超过 150 行；状态、API、副作用和处理方法进入 `hooks/`，列定义和静态配置进入 `constant.ts`。
+- 所有导出函数、hooks、类型和静态配置必须使用中文 JSDoc。
+- Orval 请求必须使用真实生成导出和 DTO；禁止 `if (res?.success)` 冗余包裹，也禁止在 `else`/`catch` 重复 `message.error`。
+- 页面、公共组件、内联样式、TS 渲染配置和 SVG 必须遵循 `theme-token-usage`；禁止硬编码品牌色及 hover/active/selected/focus 色阶，主色透明态必须由真实动态 Token 派生。
+- 页面包含导出、报表、模板或附件下载时必须遵循 `file-export-download`，使用 `handleBlobResponse(res.data, res.headers)`，并检查生成方法是否已包含 `responseType: 'blob'`。
+- 若用户给出旧项目路径或截图，开发前必须先提取 UI/交互验收清单；交付前逐项对照，不允许只实现字段和接口。
+
+## 标准代码骨架
+
+```text
+src/views/{module-name}/
+├── index.vue
+├── constant.ts
+├── style.less
+├── hooks/
+│   ├── use{Module}List.ts
+│   └── use{Module}Form.ts
+├── type.ts              # 独立类型较多时增加
+└── components/          # 多个私有视图时增加
+    ├── {Module}Table.vue
+    └── {Module}Modal.vue
+```
+
+## 生成流程
+
+1. 读取本 skill 的三个 reference，并按上述文档检索顺序核对真实 API 与导出，禁止根据旧示例猜测。
+2. 读取 `theme-token-usage`，检查项目真实主题变量与运行时同步链路。
+3. 若有截图或旧项目路径，先按 `prototype-page-acceptance` 提取布局、按钮位置、表格高度、抽屉宽度、字段控件类型等验收项。
+4. 按需求类型加载细分 skill：列表读 `page-list-module` 和 `ytable-usage`；表单读 `yss-formily`；编辑表格读 `yedit-table-usage`；树读 `ytree-usage`；导出下载读 `file-export-download`。
+5. 先设计 `constant.ts`、`style.less` 和 hooks；独立类型或私有视图确有需要时再增加 `type.ts`/`components/`，最后写 `index.vue` 组合视图。
+6. 对 API 请求使用 Orval 真实生成类型和导出，在 hooks 内封装 loading、分页映射和失败后状态；错误 Toast 由 mutator 统一处理。
+7. 交付前检查导入来源、真实组件 API、分页字段、Formily schema 层级、主题 Token、查询按钮右下角布局、表格工具栏、样式作用域、删除确认和原型对照清单。
+
+## 最小组合示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YButton, YCard, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { TABLE_COLUMNS } from './constant';
+import { useRuleList } from './hooks/useRuleList';
+
+const emit = defineEmits<{ create: [] }>();
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight, isReady } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
+const { loading, dataList, pagination, handlePageChange } = useRuleList();
+
+/** 打开新增表单，实际项目中由表单 Hook 实现。 */
+const openCreate = (): void => {
+  emit('create');
+};
+</script>
+
+<template>
+  <YCard class="page-card">
+    <div ref="tableAreaRef" class="table-area">
+      <YTable
+        v-if="isReady"
+        :height="tableHeight"
+        :data="dataList"
+        :columns="TABLE_COLUMNS"
+        :loading="loading"
+        pageable
+        v-model:pagination="pagination"
+        @page-change="handlePageChange"
+      >
+        <template #toolbar-right>
+          <YButton type="primary" @click="openCreate">新增</YButton>
+        </template>
+      </YTable>
+    </div>
+  </YCard>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+## 交付检查清单
+
+- [ ] 已优先复用 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils`。
+- [ ] `index.vue` 不超过 150 行，业务逻辑、常量、列配置和样式已按职责拆分。
+- [ ] 未出现未导出的 Y 前缀组件。
+- [ ] 未导入 `@formily/antd-v3`、`@formily/antd` 或业务层 `@formily/antdv` UI 组件。
+- [ ] `YTable` 分页字段为 `current/pageSize/total`。
+- [ ] `YTable` 未臆造 `request/search-params` Prop，也未把实例 `refresh()` 当作远程请求。
+- [ ] 主表格主操作放在 `#toolbar-right`，仅在业务需要列设置时才配置了 `toolbar-config.custom`。
+- [ ] 编辑表格场景使用 `YEditTable`，下拉可输入/多选等能力通过列 `props` 配置。
+- [ ] `YFormily` 未使用不存在的详情开关 prop，表单 label 固定宽度右对齐，`FormGrid` 保持响应式。
+- [ ] 查询区按钮在外部 `.xxx__search-actions` 右对齐独占一行，缩窄后仍处于搜索卡片右下角。
+- [ ] 主题色、状态色、中性色及交互态使用动态 Token；未依赖未同步变量的固定色 fallback。
+- [ ] 导出下载使用 `handleBlobResponse`，且 Blob 配置、响应头、loading 与错误链路已验证。
+- [ ] 已核对 Orval 真实导出，未使用 `if (res?.success)` 或重复错误 Toast。
+- [ ] 若有截图或旧项目参考，已逐项对照布局、按钮、表格高度、抽屉响应式和字段控件类型。
+
+## 失败兜底策略
+
+- 组件来源不确定时，先用 MCP `list_components/get_component_docs/search_docs` 交叉确认；MCP 不可用时才查 `component-map.md` 和 `llms-full.txt`，仍无法确认时报告待确认项，不得将猜测的导入直接落地。
+- 页面复杂度过高时，先落地最小列表/表单闭环，再拆分私有组件和 hooks。
+- API 契约不稳定时，先在 hook 内做最小字段映射，不把兼容逻辑散落到模板。

package/template/.claude/skills/yss-ui-business-page-generation/references/component-map.md

@@ -0,0 +1,39 @@
+# YSS UI 组件来源速查
+
+此文件用于业务页面生成前的组件选型。优先使用 YSS UI 已封装组件；未封装能力再从 `ant-design-vue` 导入。
+
+## 从 `@yss-ui/components` 导入
+
+| 组件 | 适用场景 | 备注 |
+| --- | --- | --- |
+| `YButton` | 操作按钮、权限按钮 | 支持 `permissionCode`、`fallback`、`modifiers`；优先替代 `a-button`。 |
+| `YCard` | 页面容器、区域容器 | 支持 `title`、`extra`、`padding`、Meta 插槽。 |
+| `YTable` | 标准列表、分页、操作列、筛选、字典翻译 | 继承 vxe-table 能力，分页用 AntDV Pagination。 |
+| `YEditTable` | 可编辑表格 | 需要底部添加按钮高度时配合 `useTableHeight(tableAreaRef, { withAddButton: true })`。 |
+| `YTree` | 左侧分类树、组织树、搜索过滤树 | 节点操作用 `getNodeActions`。 |
+| `YSplitPane` | 左树右表、可拖拽分割布局 | 左右或上下区域分割。 |
+| `YFormily` | JSON Schema 表单、新增/编辑/查看 | 默认表单方案。 |
+| `YssFormily` | 表单兼容导出 | 仅用于维护历史代码；新代码统一使用 `YFormily`。 |
+| `YConditionBuilder` | 条件构建器、规则配置 | 常用于数据质量、筛选条件配置。 |
+| `YFileImport` | 文件导入 | Formily schema 内也可用 `YFileImport`。 |
+| `YMonaco` | 代码编辑器 | SQL、JSON、脚本编辑。 |
+| `YMonacoDiff` | 代码 Diff | 变更对比场景。 |
+| `YCron` | Cron 表达式编辑 | 定时任务配置。 |
+| `YMonthCalendar` | 月度日历、节假日和连续区间 | 支持单元格、右键菜单和头部插槽。 |
+| `YEcharts` | 图表展示 | 业务图表封装。 |
+| `YSheet` | 协同/类 Excel 表格 | 复杂表格编辑。 |
+| `AuthorityDropdown` | 权限相关下拉 | 可从 `@yss-ui/components` 导入；全局安装后也注册了 `YDropdown` 组件名别名。 |
+
+## 回退到 `ant-design-vue`
+
+`@yss-ui/components` 未导出的组件不要臆造 Y 前缀，应直接从 `ant-design-vue` 导入：
+
+- `Modal`、`Drawer`、`Popconfirm`
+- `Input`、`Select`、`Switch`、`DatePicker`、`Tag`
+- `Steps`、`Tabs`、`Space`、`Tooltip`
+- `message`、`notification`
+
+## 禁止规则
+
+- 不要编造未导出的 Y 前缀组件；弹窗、抽屉、输入框等未封装能力直接从 `ant-design-vue` 导入。
+- 业务层不要从 `@formily/antdv` 导入 `FormItem`、`Input` 等 UI 适配组件。