create-yss-spec 3.4.7 → 3.4.9

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

@@ -11,7 +11,7 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 
 以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
-这是一个 Web 适配层生成型 skill。优先复用脚本 `scripts/generate_controller.mjs` 和模板，不手写重复 CRUD。
+本 Skill 同时支持只读审计、既有整改和新建 CRUD 生成。审计读取实际入口和现有契约，缺证据只记录缺口；整改消费批准 Slice、冻结 API/no-impact 与稳定用例 seam；仅新建 CRUD 才要求 Web generation contract、metadata 并调用 initialize-only 生成器。
 
 ## 何时使用
 
@@ -19,12 +19,13 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 - 用户要根据冻结 OpenAPI 字段合同、metadata 和稳定 Application 接口生成 Request / Response / Controller / WebConvertor。
 - 用户要求统一 Web Adapter 风格、返回值和接口路径。
 
-## 不适用
+手工认证、回调、Cookie、下载或流式接口适用本 Skill，但不强制使用 CRUD 脚本或 metadata。
 
-- 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 实现合同编译器 补 `yss-application` / `yss-domain` 和相应合同输入。
+## 实施前置与审计边界
 
-## 优先流程
+- 只读审计可以记录用例 seam 或契约缺失。既有整改缺少批准 Slice、稳定用例 seam 或接口契约时，回实现合同编译器补齐；仅新建 CRUD 生成要求 metadata，不因缺 metadata 拒绝既有代码审计或手工接口整改。
+
+## 新建 CRUD 生成流程
 
 1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
 2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
@@ -61,13 +62,19 @@ node scripts/generate_controller.mjs \
 
 ## 约束
 
+<a id="web.use-case"></a>
+<!-- yss-rule {"id":"web.use-case","when":"web","level":"mandatory","evidence":"code-and-verification"} -->
 - 生成代码只依赖既有 Application Service；读写操作都禁止绕过 Application。复杂查询经 Application Query Port 接入 Infrastructure。
+<a id="web.wire"></a>
+<!-- yss-rule {"id":"web.wire","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
 - 返回包装类、分页默认值、允许字段与 `PageResult.of(...)` 参数语义必须消费合同绑定的 `yss-dto/references/openapi-wire-profile.yaml`；Web skill 不复制或自行维护第二套协议。
 - DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
 - `WebConvertor` 使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝。
+<a id="web.pagination"></a>
+<!-- yss-rule {"id":"web.pagination","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - HTTP Request 不继承会暴露内部协作字段的 `PageQuery`；只生成冻结 OpenAPI allowlist 字段，禁止把 `offset`、`needTotalCount`、`tempTotalCount` 变成客户端输入。
 - `fields.<table>.pagination` 必须显式列出 `yss-dto` wire profile 允许暴露的字段子集；模板不得无条件生成字段或自行定义默认值。
-- 先跑脚本，再按项目规范做少量手调。
+- 仅新建 CRUD 先跑脚本；既有整改和手工协议适配不重跑初始化生成器。
 - Validation namespace 参数必须来自批准的精确平台配置和当前工程基线，不得按记忆或 Boot 大版本自行选择。
 - 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
 - 脚本是 initialize-only；写入前先规划全部目标并校验 `allowed_write_paths`，任一目标已存在或传入 `--force` 时整体返回 `unsupported`。落盘使用排他创建和失败回滚，不得留下部分文件；旧项目迁移不属于该生成器。
@@ -85,8 +92,10 @@ node scripts/generate_controller.mjs \
 
 ## 阶段 7 合同
 
-- 只消费已批准且当前的 schema v2 Web generation contract 和冻结 OpenAPI/no-impact record；schema v1 为 `unsupported`，不得自动升级，也不得用 Controller 或半成品 backend 反向定义产品契约。
+- 所有写入消费批准且当前的 Slice 与冻结 OpenAPI/no-impact record；只有新建 CRUD 生成还要求 schema v2 Web generation contract。生成合同 v1 为 `unsupported`，不得自动升级；不得用 Controller 反向定义产品契约。
 - DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
+<a id="web.write-scope"></a>
+<!-- yss-rule {"id":"web.write-scope","when":"change","level":"mandatory","evidence":"code-and-verification"} -->
 - 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
 - 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 实现合同编译器/生命周期。
 

package/template/.pi/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -84,3 +84,11 @@ public interface QualityRuleWebConvertor {
 - Wire forbidden fields 无法绑定。
 - OpenAPI 3 注解、YSS Result wrapper、Validation namespace 与平台 Profile 一致。
 - 执行项目根 `./mvnw test/package`，并保留 HTTP/serialization/exception 证据。
+
+## 非 CRUD 适配
+
+认证、OAuth 回调、Cookie、流式响应及协议端点可以手工实现，不强行套 CRUD metadata；仍消费批准的 wire 合同、Application seam 和平台配置。Controller 不直连 Domain Gateway，也不自行编排登录、撤销或持久化。
+
+协议转换、Cookie/Header 处理归 Web；业务决策归 Application/Domain。异常翻译器可以依赖领域错误类型，不能据此允许 Controller 调用领域端口。MapStruct 处理机械字段映射，协议编码及显式领域工厂适配使用有测试的自定义方法。
+
+生成器推荐 rest 布局；已登记的 adapter.web 等布局通过合同绑定识别。审查按模块、实际 Controller 类型和依赖方向进行，包名偏离不能让检查空匹配通过。

package/template/.pi/skills/ytable-usage/SKILL.md

@@ -216,7 +216,7 @@ onMounted(loadList);
 2. **行唯一键**：必须显式指定 `:row-config="{ keyField: 'id', useKey: true }"`（`keyField` 与业务主键如 `userCode` 对齐）。
 3. **受控双向绑定**：推荐优先使用 `v-model:selected-row-keys="selectedRowKeys"` 或 `v-model:selected-rows="selectedRows"`，或者统一监听 `@selection-change`。
 4. **批量操作按钮**：放在 `#toolbar-right`，并配置 `:disabled="selectedRowKeys.length === 0"`。
-5. **清空选中态**：批量操作成功后，直接重置 `selectedRowKeys.value = []` 或调用 `tableRef.value.clearSelection()`。
+5. **清空选中态**：批量操作成功后，清空实际受控的 `selectedRowKeys` / `selectedRows`，并在存在表格内部选择缓存时调用已核验的 `tableRef.value.clearSelection()`。受控状态与组件可见勾选必须一致；不能只清其中一层。
 
 ```vue
 <YTable
@@ -244,7 +244,7 @@ onMounted(loadList);
 
 - [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
 - [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
-- [ ] 批量操作成功后已重置 `selectedRowKeys` 并调用 `tableRef.clearSelection()`。
+- [ ] 批量成功后，所有实际受控选择字段与表格可见勾选均已清空；内部缓存存在时已通过 `clearSelection()` 清除。
 - [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
 - [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。
 - [ ] 查询、重置、翻页、刷新和导出复用同一份 `currentParams`；查询/重置回到第一页，批量成功后清空选中态。

package/template/docs/agents/yss-skill-registry.yaml

@@ -33,6 +33,7 @@ backend_skill_domains:
     yss-implementation-contract-compiler: platform-governance-migration
     yss-skill-source-index-refresh: platform-governance-migration
     yss-up-springboot3: platform-governance-migration
+    yss-backend-spec-review: platform-governance-migration
   deprecated_skills: []
 backend_source_index_contract:
   schema_version: 1
@@ -126,6 +127,7 @@ retirement_contract:
     deprecated: skill-deprecated
     retired: skill-retired
 capabilities:
+  - { id: governance.backend-spec-conformance, primary_skill: yss-backend-spec-review, provider: { kind: none }, task_modes: [guidance, troubleshooting, review-input] }
   - { id: writing.lifecycle-document, primary_skill: i-have-adhd, provider: { kind: none }, task_modes: [guidance] }
   - { id: architecture.technical-design, primary_skill: yss-technical-design, provider: { kind: none }, task_modes: [guidance, integration, review-input] }
   - { id: architecture.mvc-design, primary_skill: yss-technical-design, provider: { kind: none }, architecture_family: layered-mvc, task_modes: [guidance, integration, review-input] }
@@ -159,6 +161,7 @@ capabilities:
   - { id: project-init.mvc-data-analysis, primary_skill: yss-layered-mvc-scaffold-generator, provider: { kind: none }, task_modes: [component-maintenance] }
   - { id: migration.springboot3, primary_skill: yss-up-springboot3, provider: { kind: none }, task_modes: [guidance, integration, troubleshooting, component-maintenance, review-input] }
 recipes:
+  - { id: backend.spec-conformance, capabilities: [governance.backend-spec-conformance, quality.java-code-style] }
   - { id: backend.ddd-domain-behavior, architecture_family: domain-driven, capabilities: [layer.domain, layer.application, quality.java-code-style] }
   - { id: backend.ddd-persistence-mybatis, architecture_family: domain-driven, capabilities: [layer.persistence, framework.mybatis, codegen.mapstruct, codegen.lombok, quality.java-code-style] }
   - { id: backend.ddd-http-api, architecture_family: domain-driven, capabilities: [layer.web-adapter, contract.dto-wire, contract.request-validation, contract.error-mapping, codegen.mapstruct, codegen.lombok, quality.java-code-style] }
@@ -180,6 +183,10 @@ recipes:
   - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  yss-backend-spec-review:
+    - { skill: alibaba-java-code-style, type: context-required }
+    - { skill: yss-implementation-contract-compiler, type: coordination-only }
+    - { skill: code-review, type: review-only }
   prototype-review:
     - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
   yss-implementation-contract-compiler:
@@ -689,6 +696,12 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [backend]
+  - id: yss-backend-spec-review
+    layer: specialist
+    maturity: verified
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [backend, quality]
   - id: yss-userinfo
     layer: specialist
     maturity: supported

package/template/docs/engineering/backend-platforms.md

@@ -101,3 +101,17 @@ Boot 4 使用对应 MVC / MVC 测试 starter、Jackson 3 默认栈与新的模
 通用运行时依赖仍由真实依赖树和 Boot BOM 核验。YSS 组件能力的精确构件绑定只读取同一兼容条目内的 `component_capabilities`，不得再从 catalog 顶层列表或平行 `components` 目录推断。
 
 Jar 核验拒绝未登记或版本不符的额外库；仅允许 Boot 对应版本的 jarmode 工具以及已选配方中的 provided Lombok 随包出现。原因是 [Boot repackage 默认包含 provided 依赖](https://docs.spring.io/spring-boot/maven-plugin/packaging.html)；这些打包例外不能补足必须存在于 compile/runtime 树的 Web、Servlet、JSON 等能力。
+
+
+## 双平台专项认证
+
+本轮必选范围为 `spring-boot-2.7-jdk8:2.7.18` 与 `spring-boot-3.5-jdk17:3.5.16`，各覆盖
+`domain-driven`、`layered-mvc`。矩阵输入可指定 `required_combinations`，或重复传
+`--require-combination <profile_id>:<spring_boot_version>:<architecture_family>`。不指定时仍执行完整矩阵。
+未选择的组合记录 `not-executed`，不计为通过，也不影响专项总状态。专项通过不自动修改清单可选性。
+
+每个组合使用合同选择的平台和显式 `java_homes`，本机默认 Java 不决定项目版本。生成的测试夹具覆盖
+HTTP JSON/Validation 错误响应、MapStruct 编译与字段映射、MyBatis 持久化往返/分页、事务失败回滚。
+夹具在 test scope 使用 H2、标准 MyBatis RowBounds 和 TransactionTemplate；它不证明生产方言、YSS 自动分页切面、业务 Service 代理事务或特定
+组件能力。对应能力仍须读取所选平台的源码索引、验证实际组件并绑定独立证据。新增用例必须出现在本次
+Surefire XML 中，空测试、跳过或旧报告不可通过。没有凭据、构件、真实批准合同或组件兼容证据时保持阻断。