create-yss-spec 3.4.1 → 3.4.3

package/template/.codex/skills/mapstruct/references/annotation-examples.md

@@ -0,0 +1,300 @@
+# mapstruct 条件参考
+
+仅在需要具体注解或配置示例时定位对应章节。示例业务名与版本不是工程基线；按批准合同替换，禁止直接复制成业务实现。
+
+## Basic Mapper
+
+```java
+@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR)
+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.ERROR)
+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>${maven.compiler.source}</source>
+                <target>${maven.compiler.target}</target>
+                <annotationProcessorPaths>
+                    <!-- Use the approved processor configuration, including Lombok binding -->
+                    <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. Keep unmapped targets visible with `ReportingPolicy.ERROR`; explicitly ignore only fields excluded by the contract
+3. Map or explicitly exclude identity and audit fields according to ownership in the contract
+4. Use `@MappingTarget` for partial updates
+5. Configure Lombok, MapStruct and the required binding processor from the engineering baseline
+6. Use abstract classes instead of interfaces for custom logic
+7. Use `@Condition` for conditional mapping logic
+
+---
+
+
+## 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 ERROR and explicit field mappings |
+| 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 | Missing processor or binding | Check annotationProcessorPaths and Lombok binding |
+| Mapper not autowired | Wrong componentModel | Use componentModel = "spring" |
+| Circular dependency | Mappers reference each other | Review mapper dependencies and remove cycles |
+| UnmappedTargetProperty warning | Missing mapping | Add an explicit mapping or a contract-approved field ignore |
+| 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)

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

@@ -1,6 +1,6 @@
 ---
 name: page-form-module
-description: 指导实现 YSS UI 新增、编辑和查看表单模块，覆盖 YFormily Schema、mode 0/1/2、详情渲染、数据回显与回填、表单值被意外清空排查、校验、提交 loading、弹窗销毁和列表刷新；当页面包含表单页、Modal 或 Drawer 表单，或编辑时回显丢失、提交后表单未重置时使用。
+description: "实现 YSS UI 新增、编辑、查看表单模块及弹窗闭环；排查回显丢失、重置、提交与列表刷新。"
 ---
 
 # Page Form Module Skill

package/template/.codex/skills/page-skeleton/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: page-skeleton
-description: 指导搭建 Vue3 YSS UI 列表、表单、详情和弹窗页面模块骨架，统一 index.vue、constant.ts、style.less、hooks 与私有组件职责；当新建页面或需要拆分超过 150 行的业务组件时使用。
+description: "创建或拆分 Vue3 YSS UI 页面模块骨架，明确页面、配置、hooks 与私有组件职责。"
 ---
 
 # Page Skeleton Skill

package/template/.codex/skills/product-design/skills/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit
-description: "Audit or critique a product flow, journey, workflow, funnel, onboarding path, checkout path, settings path, screen, or multi-step product experience by capturing screenshots first, placing them in Figma or a local folder, then reporting UX, design, and accessibility findings from that evidence. Use when the user asks to audit, critique, review, inspect, assess, or evaluate a product experience."
+description: "Audit an existing product screen or flow using screenshots; report UX and accessibility findings."
 ---
 
 # Audit

package/template/.codex/skills/product-design/skills/design-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-qa
-description: "Internal prototype QA helper. Use only after a Product Design prototype, URL-to-code build, or image-to-code build has a source visual target and a rendered implementation to compare before handoff. Do not use for broad UX critique, design critique, product audits, or flow reviews; route those user-facing requests to audit."
+description: "Compare a rendered prototype with its source visual target before handoff. For broad UX audits use audit."
 ---
 
 # Design QA

package/template/.codex/skills/product-design/skills/get-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-context
-description: "Mandatory design-brief gate for Product Design build and design workflows. Use before ideation, prototyping, image-to-code builds, redesigns, or product UI work to clarify missing product, visual, and interactivity context or play back the supplied brief before proceeding."
+description: "Establish the Product Design brief before ideation or builds; reuse supplied context and clarify missing decisions."
 ---
 
 # Get Context

package/template/.codex/skills/product-design/skills/ideate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ideate
-description: "Generate image-based visual alternatives, remixes, or concept directions after Product Design get-context has confirmed the design brief. Use when the user asks for design variants, visual exploration, remixes, or image-generated approaches from provided context."
+description: "Generate visual alternatives or remixes after the Product Design brief is confirmed."
 ---
 
 # Ideate

package/template/.codex/skills/product-design/skills/image-to-code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: image-to-code
-description: "Implement a selected image, screenshot, mockup, or Image Gen reference as a faithful responsive frontend after Product Design get-context has confirmed the design brief."
+description: "Implement a selected image, screenshot or mockup as a responsive frontend after confirming the design brief."
 ---
 
 # Image to Code

package/template/.codex/skills/product-design/skills/index/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: index
-description: "Use to discover specific skills for the Product Design plugin, when it is at-mentioned directly, or for any mentions of potentially relevant work, including: UX research; product, screen, or flow audits; visual ideation; app or interface design, redesign, cloning, prototyping, or implementation from ideas, URLs, images, Figma, or code; design QA; and prototype sharing or deployment."
+description: "Route Product Design requests for UX research, product audits, visual ideation, prototypes and design QA."
 ---
 
 # Skill Purpose

package/template/.codex/skills/product-design/skills/prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prototype
-description: "Route coded prototype requests after Product Design get-context has confirmed the design brief. Use for building prototypes from URLs, images, mockups, Figma, existing code, or ideas that need visual exploration before build."
+description: "Route prototype builds from URLs, images, Figma, code or ideas after confirming the Product Design brief."
 ---
 
 # Design Prototypes

package/template/.codex/skills/product-design/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: "Run fast, source-grounded UX research on the highest-signal problems users are experiencing with a user-specified digital product. Use when the user asks to research user pain, UX friction, onboarding issues, docs/help problems, developer experience friction, support pain, product workflow issues, or current user complaints for a named product."
+description: "Research UX friction, user pain or current complaints about a named digital product using traceable sources."
 ---
 
 # Research

package/template/.codex/skills/product-design/skills/user-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: user-context
-description: Load or manage Product Design's saved user context. Use when the user asks to set up Product Design, get started, onboard, save product or design sources, see what Product Design remembers, update saved context, or remember Product Design preferences. Examples include product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, and general product/design notes.
+description: "Manage saved Product Design context when asked to onboard, remember sources or update design preferences."
 ---
 
 # User Context

package/template/.codex/skills/theme-token-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theme-token-usage
-description: 指导 Vue3 YSS UI 微应用业务页面、公共组件、原型还原和主题修复使用可动态换肤的 CSS/Ant Design Token，覆盖主色、hover/active/selected/focus、状态色、中性色、透明色派生和暗色模式；当新增或修改 .vue、style.less、内联样式、TS 渲染配置、SVG 色值，或审查硬编码 #hex/rgb/渐变时使用。
+description: "实现或修复 Vue3 YSS UI 主题、交互状态色与动态换肤；用于 token 映射和硬编码色值审查。"
 ---
 
 # YSS UI 主题 Token 使用 Skill

package/template/.codex/skills/to-tickets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: to-tickets
-description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in one file per ticket locally, or native blocking links on a real tracker.
+description: "显式调用时，将已确认的 Plan 或 Spec 拆成带依赖的垂直切片 Ticket，并按配置的 tracker 持久化。"
 disable-model-invocation: true
 ---
 

package/template/.codex/skills/using-git-worktrees/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-git-worktrees
-description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+description: "Set up Git worktree isolation when requested or when concurrent work needs a separate checkout."
 ---
 
 # Using Git Worktrees

package/template/.codex/skills/wayfinder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wayfinder
-description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
+description: "显式调用时，为跨多个会话的大型工作建立决策地图，逐项收敛后交回主流程。"
 disable-model-invocation: true
 ---
 

package/template/.codex/skills/yedit-table-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yedit-table-usage
-description: 指导 YSS UI 业务页面使用 @yss-ui/components 的 YEditTable 实现可编辑表格、行内编辑、添加/删除行、下拉多选与可创建 tags、行级候选联动、表头筛选、校验和查看态；当需求出现编辑表格、明细行、扩展属性、可编辑列或 YEditTableColumn 时使用。
+description: "配置或修复 YSS UI YEditTable 的行内编辑、候选联动、增删行、校验与查看态。"
 ---
 
 # YEditTable 使用

package/template/.codex/skills/yss-api-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-api-integration
-description: 指导在 Vue3 业务列表、表单、详情和操作 Hook 中集成 Orval API，覆盖真实生成产物选择、mutator 响应契约、错误提示、加载状态、请求选项和长整型精度；当页面对接查询、新增、编辑、删除、详情或文件流接口时使用。
+description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator、错误反馈、loading 与长整型精度。"
 ---
 
 # API 集成 Skill

package/template/.codex/skills/yss-audit-log/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-audit-log
-description: Use when YSS `AuditLog`, `EnableAuditLog`, audit SpEL summaries, async publication, subscriber registration, queue loss, or audit delivery failures are involved.
+description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订阅注册与审计投递。"
 ---
 
 # yss-audit-log

package/template/.codex/skills/yss-cache/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-cache
-description: 用于 YSS 缓存框架的接入、配置、代码修改和故障诊断。Use when tasks involve QueryCache、UpdateCache、ClearCache、TTL、SpEL key、事务提交后缓存操作、Redis/Caffeine/Hazelcast 后端切换、Redis Standalone/Sentinel/Cluster、Jedis 连接池、Redis fallback、JetCache、多级缓存、序列化兼容、缓存不命中或失效不一致。
+description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、缓存后端与一致性问题。"
 ---
 
 # yss-cache

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

@@ -21,6 +21,19 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - 只补持久层时，优先 `yss-repository`。
 - 只补 Web 层时，优先 `yss-web-controller`。
 
+## Spring Boot / Java 平台选择
+
+调用本技能时先展示 `scripts/backend-platforms` 的精确版本清单及兼容状态。由生命周期编排器把架构、Spring Boot、Java 和 YSS 父 POM/BOM 合并展示并取得真实用户确认；生成器不提问、不猜版本、不使用 `x` 或 `latest`。已有批准且当前的选择展示摘要后复用。
+
+- 候选平台：Boot 2.7.18 / Java 8，Boot 3.5.16 / Java 17 或 21，Boot 4.1.1 / Java 17 或 21。新 Boot 默认推荐 Java 17；候选不等于可生成。
+- 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 Maven Reactor 使用一个平台。
+- 只开放共享兼容清单中已有真实 YSS 构建、依赖和启动证据的组合。缺少兼容父 POM、BOM、starter 或相应能力证据即 `blocked`；不替换官方组件、不降级回退。
+- 新生成合同必须有 `platform_configuration` v2，与架构决策、Maven 坐标及兼容条目摘要一致。Boot、Java、YSS 坐标或依赖配方变化时回生命周期重新确认并编译合同；仅追加同配置验证记录不重复确认，仍核验证据有效性。
+- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Boot 3.5 / 4.1 拒绝 Java 8/11。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
+- 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
+
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+
 ## 优先流程
 
 1. 确认服务级 `scaffold_request_id`、已由用户确认且生命周期批准的 `domain-driven` 架构选择及 digest、项目名、基础包名、Maven 项目坐标、父 POM GAV、YSS Components BOM 版本、输出目录和批准 Profile。Java `base_package` 与 Maven `group_id` 是两个独立输入，不得相互推导；脚手架发生在 Ticket 正式化前，不使用 `slice_id` 伪造切片身份。
@@ -84,12 +97,12 @@ node scripts/run_first_slice_verification.mjs \
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成时的静态依赖由技能注册表与 实现合同编译器 共同约束为 `yss-backend-scaffold-parent`、`alibaba-java-code-style`。生成后必须回到 实现合同编译器，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
-- 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
+- 验证数据库固定 H2，生产数据库 `not-bound`；后续存储接入按批准的切片合同执行。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
 - 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。
-- 合同 `profiles` 只支持 `target-domain-model`、`mybatis-plus`、`mysql`、`spring-boot-2.7-jdk8`、`javax`、`web`、`yss-internal`。普通 MyBatis、Boot 3、独立 client module、client-in-domain 和其他旧架构均为 `unsupported`，不提供回退分支。
+- DDD 固定 `target-domain-model`、`mybatis-plus`、H2 验证、`web` DTO、`yss-internal`；平台与 Validation 命名空间由共享清单约束。普通 MyBatis、独立 client module、client-in-domain 和其他旧架构仍为 `unsupported`。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 skill tree digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。
 - `first-slice-verified` 只能由 `run_first_slice_verification.mjs` 写入。手工改 Manifest、只生成 Controller、只通过局部模块测试或仅有结构扫描都不能升级完成等级。

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/pom/application-pom.xml.template

@@ -27,7 +27,7 @@
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-aop</artifactId>
+            <artifactId>{{aop_starter}}</artifactId>
         </dependency>
         <dependency>
             <groupId>org.springframework</groupId>

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

@@ -20,16 +20,18 @@
 
     <properties>
         <yss-components.version>{{yss_components_version}}</yss-components.version>
-        <maven.compiler.source>1.8</maven.compiler.source>
-        <maven.compiler.target>1.8</maven.compiler.target>
+        <java.version>{{java_version}}</java.version>
+        <spring-boot.version>{{boot_version}}</spring-boot.version>
+        <maven.compiler.source>{{java_version}}</maven.compiler.source>
+        <maven.compiler.target>{{java_version}}</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <mapstruct.version>1.5.5.Final</mapstruct.version>
-        <lombok.version>1.18.30</lombok.version>
-        <lombok-mapstruct-binding.version>0.2.0</lombok-mapstruct-binding.version>
-        <swagger-annotations-v3.version>2.2.22</swagger-annotations-v3.version>
-        <archunit.version>1.2.1</archunit.version>
-        <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
-        <maven-enforcer-plugin.version>3.5.0</maven-enforcer-plugin.version>
+        <mapstruct.version>{{mapstruct_version}}</mapstruct.version>
+        <lombok.version>{{lombok_version}}</lombok.version>
+        <lombok-mapstruct-binding.version>{{lombok_mapstruct_binding_version}}</lombok-mapstruct-binding.version>
+        <swagger-annotations-v3.version>{{swagger_version}}</swagger-annotations-v3.version>
+        <archunit.version>{{archunit_version}}</archunit.version>
+        <maven-compiler-plugin.version>{{compiler_version}}</maven-compiler-plugin.version>
+        <maven-enforcer-plugin.version>{{enforcer_version}}</maven-enforcer-plugin.version>
     </properties>
 
     <modules>
@@ -42,6 +44,7 @@
 
     <dependencyManagement>
         <dependencies>
+            <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>{{boot_version}}</version><type>pom</type><scope>import</scope></dependency>
             <dependency>
                 <groupId>com.yss.cloud</groupId>
                 <artifactId>yss-components-bom</artifactId>
@@ -94,6 +97,8 @@
 
     <build>
         <plugins>
+            <plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>{{boot_version}}</version></plugin>
+            <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>{{surefire_version}}</version></plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
@@ -129,7 +134,7 @@
                         <goals><goal>enforce</goal></goals>
                         <configuration>
                             <rules>
-                                <requireJavaVersion><version>[1.8,1.9)</version></requireJavaVersion>
+                                <requireJavaVersion><version>{{java_range}}</version></requireJavaVersion>
                                 <requireMavenVersion><version>[3.6.3,)</version></requireMavenVersion>
                                 <reactorModuleConvergence/>
                                 <dependencyConvergence/>

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/pom/web-pom.xml.template

@@ -19,7 +19,7 @@
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-web</artifactId>
+            <artifactId>{{web_starter}}</artifactId>
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -45,13 +45,13 @@
         </dependency>
         <dependency>
             <groupId>io.swagger.core.v3</groupId>
-            <artifactId>swagger-annotations</artifactId>
+            <artifactId>{{swagger_artifact}}</artifactId>
             <version>${swagger-annotations-v3.version}</version>
             <scope>compile</scope>
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-test</artifactId>
+            <artifactId>{{web_test_starter}}</artifactId>
             <scope>test</scope>
         </dependency>
     </dependencies>

package/template/.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -11,9 +11,9 @@ description: YSS DDD scaffold Engineering Baseline entry for profile, module, de
 
 - Architecture: `target-domain-model`
 - Persistence: `mybatis-plus`
-- Database: `mysql`
-- Platform: `spring-boot-2.7-jdk8`
-- Validation namespace: `javax`
+- Verification database: `h2`; production database: `not-bound`
+- Platform: approved `platform_configuration` v2 from the shared backend platform catalog
+- Validation namespace: derived from that platform (`javax` for Boot 2.7; `jakarta` for Boot 3.5/4.1)
 - DTO placement: `web`
 - Repository: `yss-internal`