create-yss-spec 2.1.6 → 2.1.8

package/template/.trae/skills/yss-dto/references/openapi-wire-profile.yaml

@@ -0,0 +1,181 @@
+schema_version: 1
+kind: yss-dto-openapi-wire-profile
+
+# This profile is the reusable mapping source consumed by the OpenAPI skills.
+# It describes the public HTTP/JSON shape, not every Java field or getter.
+canonical:
+  java_package: com.yss.cloud.dto.result
+  type_parameter:
+    name: T
+    java_bound: java.io.Serializable
+  openapi:
+    response_meta_schema: YssResultMeta
+    concrete_schema_composition: allOf
+    response_wrapper_extension: x-yss-response-wrapper
+    literal_java_generic_schema: false
+
+compatibility_packages:
+  - java_package: com.yss.cloud.dto.response
+    status: legacy-or-compatibility
+    use_for_new_contracts: false
+    policy: do-not-introduce-in-new-contracts
+
+common_response:
+  schema_name: YssResultMeta
+  fields:
+    success:
+      direction: response
+      wire_types: [boolean]
+      nullable: false
+      required: true
+    dataType:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+    code:
+      direction: response
+      wire_types: [string, integer, "null"]
+      nullable: true
+      required: true
+      policy: do-not-widen-global-wrapper
+    message:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+    tips:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+
+wrappers:
+  SingleResult:
+    java_type: com.yss.cloud.dto.result.SingleResult<T>
+    response_kind: single
+    data:
+      direction: response
+      wire_shape: endpoint-schema-or-null
+      nullable: true
+      required: true
+  MultiResult:
+    java_type: com.yss.cloud.dto.result.MultiResult<T>
+    response_kind: non-page-list
+    data:
+      direction: response
+      wire_types: [array]
+      items: endpoint-schema
+      nullable: false
+      required: true
+      empty_value: []
+  PageResult:
+    java_type: com.yss.cloud.dto.result.PageResult<T>
+    response_kind: page
+    fields:
+      totalCount:
+        direction: response
+        wire_types: [integer]
+        format: int64
+        minimum: 0
+        nullable: false
+        required: true
+      pageSize:
+        direction: response
+        wire_types: [integer]
+        format: int32
+        minimum: 1
+        nullable: false
+        required: true
+      pageIndex:
+        direction: response
+        wire_types: [integer]
+        format: int32
+        minimum: 1
+        nullable: false
+        required: true
+      data:
+        direction: response
+        wire_types: [array]
+        items: endpoint-schema
+        nullable: false
+        required: true
+        empty_value: []
+    computed_fields:
+      totalPages:
+        java_getter: getTotalPages
+        status: mapper-dependent
+        policy: include-only-with-target-wire-evidence
+
+page_query:
+  java_type: com.yss.cloud.dto.page.PageQuery
+  request_direction: query
+  fields:
+    pageIndex:
+      direction: request
+      wire_types: [integer]
+      format: int32
+      minimum: 1
+      default: 1
+      nullable: false
+      required: false
+    pageSize:
+      direction: request
+      wire_types: [integer]
+      format: int32
+      minimum: 1
+      default: 10
+      nullable: false
+      required: false
+    orderBy:
+      direction: request
+      wire_types: [string, "null"]
+      nullable: true
+      required: false
+      policy: endpoint-whitelist-required
+    orderDirection:
+      direction: request
+      wire_types: [string]
+      enum: [ASC, DESC]
+      default: DESC
+      nullable: false
+      required: false
+    groupBy:
+      direction: request
+      wire_types: [string, "null"]
+      nullable: true
+      required: false
+      policy: endpoint-whitelist-required
+  forbidden_client_fields:
+    - offset
+    - needTotalCount
+    - tempTotalCount
+  computed_fields:
+    offset:
+      java_getter: getOffset
+      status: computed
+      policy: exclude-from-client-input
+    needTotalCount:
+      java_getter: isNeedTotalCount
+      status: internal-or-ignored
+      policy: exclude-from-client-input
+    tempTotalCount:
+      java_getter: getTempTotalCount
+      status: internal-or-ignored
+      policy: exclude-from-client-input
+
+request_bases:
+  command:
+    java_type: com.yss.cloud.dto.CommandDTO
+    direction: request
+  query:
+    java_type: com.yss.cloud.dto.QueryDTO
+    direction: request
+    extends: command
+
+wire_evidence:
+  required_before_freeze:
+    - target-http-mapper-identity
+    - representative-serialization-fixtures
+    - contract-test-or-equivalent-http-evidence
+  rule: Java fields and computed getters are not public wire facts until target-boundary evidence confirms them.

package/template/.trae/skills/yss-mybatis/SKILL.md

@@ -61,7 +61,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 
 - 不要同时引入两套分页机制而不说明谁生效。
 - 不要在已有 Repository 基类体系之外再造一套 Mapper 抽象。
-- 若用户只是要生成持久层骨架，优先衔接 `yss-db2mybatis`。
+- 若用户只是要生成持久层骨架，优先衔接 `yss-repository`。
 
 ## 按需读取
 

package/template/.trae/skills/yss-openapi-draft-review/SKILL.md

@@ -12,7 +12,8 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 - OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`，作为唯一权威的单一 OAS 3.1 YAML document；生命周期元数据和 Freeze 决策位于相邻 Markdown 记录。
 - Calibrated Spec.
 - Interaction spec / prototype review when UI exists.
-- YSS engineering baseline rules, especially `SingleResult<T>`, `MultiResult<T>`, and `PageResult<T>`.
+- YSS engineering baseline rules and `.agents/skills/yss-dto/references/openapi-wire-profile.yaml`；先运行 `scripts/verify-yss-dto-openapi-profile`。
+- 若 Draft 包含 computed getter（例如 `totalPages`），必须提供目标 HTTP mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP evidence。
 
 ## Review Flow
 
@@ -20,13 +21,16 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry.
 3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
 4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
-5. Check YSS API baseline: REST shape, `SingleResult<T>` for single objects, `MultiResult<T>` for non-page lists, `PageResult<T>` for pagination, and stable DTO/schema names.
-6. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
-7. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
+5. Check YSS API baseline: REST shape, `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult`, `YssResultMeta` plus `allOf` concrete schemas, and stable DTO/schema names. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
+6. Check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately.
+7. Check pagination input: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
+8. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
+9. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
 
 ## Automation Boundary
 
 - Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
+- `scripts/verify-yss-dto-openapi-profile` owns the reusable DTO mapping invariants; the review still checks each endpoint's concrete schema, wrapper extension and evidence.
 - Human or independent semantic review owns P0 traceability, page-action coverage, error behavior, concurrency/idempotency, scope downgrades, contract-test seams, and any explicitly specified authentication or authorization behavior.
 - Fresh passing automation evidence may be referenced by the semantic review; copying the same findings into a second checklist is unnecessary.
 - Re-run structural automation only when the Draft, ruleset, or referenced schema changes.
@@ -38,7 +42,9 @@ Block if any of these are true:
 - A P0 requirement has no endpoint, schema, error contract, or explicit non-goal.
 - A UI action has no endpoint/non-goal mapping.
 - A configurable rule or gate lacks a source, owner, fixed/default decision, or API representation.
-- Pagination does not align with YSS `PageResult<T>` or documented exception.
+- Pagination does not align with the `PageResult` profile or documented exception, or exposes `offset` / `needTotalCount` / `tempTotalCount` as client input.
+- A response omits `x-yss-response-wrapper`, uses the compatibility `com.yss.cloud.dto.response` package for a new contract, writes Java generic notation as an OAS schema, or fails `YssResultMeta` + `allOf` + concrete `data` mapping.
+- `code` is modeled as arbitrary object, `dataType` loses explicit nullability, or computed fields such as `totalPages` lack target wire evidence.
 - Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, and optimistic locking.
 - YAML contains lifecycle frontmatter / root metadata, or the proposed JSON client input is not explicitly deferred until Freeze and governance export.
 
@@ -58,9 +64,15 @@ Block if any of these are true:
 - <P0 requirement -> endpoint/schema/error/test mapping summary>
 
 ### YSS Baseline
-- <response wrappers, DDD boundary implications, implementation feasibility>
+- <`x-yss-response-wrapper` map and `YssResultMeta` / `allOf` conformance>
+- <profile version, concrete `data` schemas, nullability, request/response direction and computed-field evidence>
+- <DDD boundary implications, implementation feasibility>
 
 ### Contract Test Checklist
+- <wrapper meta fields: success/code/message/tips/dataType, including code string/integer/null cases>
+- <single object, non-page list empty array, page empty array and page boundary cases>
+- <PageQuery allowed fields, ASC/DESC and endpoint whitelist; negative assertions for offset/needTotalCount/tempTotalCount>
+- <target HTTP mapper identity and computed-field fixture, if totalPages or another getter is included>
 - <minimum contract tests before OpenAPI Freeze>
 
 ### Next Action

package/template/.trae/skills/yss-openapi-governance/SKILL.md

@@ -13,12 +13,15 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 `docs/.scratch/<feature>/api/<feature>.yaml` 是唯一权威的 OpenAPI 3.1 契约。JSON 只能由冻结后的 YAML 可复现地产生，用于前端代码生成或分发；不得手写、不得反向覆盖 YAML、不得把运行时代码当成设计契约来源。
 
+YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/openapi-wire-profile.yaml` 单一维护。它描述公开 wire shape，不是 Java 字段或 getter 清单；本 skill 必须消费 profile，不能在治理文档、feature YAML 和 JSON 中各自发明 `SingleResult`、`PageResult` 或 `PageQuery` 字段表。
+
 ## 边界与职责
 
 使用 `yss-openapi-governance`：
 
 - 基于冻结前的 Spec、产品设计、架构约束创建或更新 `docs/.scratch/<feature>/api/<feature>.yaml`。
 - 保证 YAML 是单一 YAML document、根节点为 `openapi: 3.1.0`，且不把 `pipeline`、`stage`、`status`、`owner` 等生命周期元数据写入 OpenAPI 根节点。
+- 按 `yss-dto` wire profile 校验 `com.yss.cloud.dto.result` canonical 包、`YssResultMeta` 公共字段、具体 wrapper schema、请求 / 响应方向和分页负向字段。
 - 运行受项目 lockfile 约束的 lint / bundle，检查 `$ref`、operationId、响应包装、错误、分页、幂等和契约测试 seam；只有 Spec 明确改变认证或授权行为时才检查对应契约。
 - 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
 - 维护治理记录、Freeze 记录和 JSON 派生记录。
@@ -59,7 +62,9 @@ pnpm exec redocly bundle \
 2. **运行结构与治理校验**
    - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
    - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
-   - 检查 `/api/v1/` 版本策略（或记录例外）、`SingleResult<T>` / `MultiResult<T>` / `PageResult<T>`、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
+   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
+   - 每个响应都必须落成具体 endpoint schema：`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
+   - `code` 按 profile 只允许 `string | integer | null`，`dataType` 按 profile 为 `string | null`；`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入；`totalPages` 只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
 
 3. **独立 Draft Review 与 Freeze**
    - 将 fresh lint 证据交给 `yss-openapi-draft-review`；阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
@@ -85,6 +90,9 @@ pnpm exec redocly bundle \
 - YAML / `$ref` / lint 不通过，operationId 不稳定或不唯一，或路径参数、schema、examples 无法解析。
 - P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
 - `$ref` 超出允许范围，或转换器版本、lockfile、命令、输入 YAML 无法识别。
+- `scripts/verify-yss-dto-openapi-profile` 失败、profile 版本未记录，或 Draft 未按 profile 建模 `x-yss-response-wrapper`、`YssResultMeta` / `allOf` 和具体 `data` schema。
+- 新契约引入 `com.yss.cloud.dto.response`、把 Java 泛型文字当成 OAS schema、把全局 `code` 放宽为任意 object，或把 `offset` / `needTotalCount` / `tempTotalCount` 作为客户端字段。
+- `totalPages`、任何 computed getter 或 Lombok / `@JsonIgnore` 推导字段没有目标 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
 - Freeze 记录、YAML SHA-256、JSON SHA-256、JSON 解析 / lint 证据缺失。
 - JSON 被手工编辑，或生成结果试图反向成为 YAML 的权威来源。
 
@@ -102,6 +110,8 @@ pnpm exec redocly bundle \
 
 ### Validation
 - Lint command and result: <locked pnpm command / result>
+- YSS DTO wire profile: <`.agents/skills/yss-dto/references/openapi-wire-profile.yaml`, schema_version, verifier result>
+- Wrapper conformance: <`x-yss-response-wrapper`, `YssResultMeta`, `allOf`, concrete data schema, direction and forbidden-field result>
 - `$ref` policy / approved exceptions: <details>
 - Blocking findings: <file:line grounded finding>
 

package/template/.trae/skills/yss-repository/SKILL.md

@@ -23,7 +23,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 
 1. 先确认输入来源：领域模型、metadata、数据库表、DDL。
 2. 探测持久化 profile：新 DDD 默认 `PO <-> Domain Model`；legacy YSS 常见 `Entity + BaseRepository + GatewayImpl`。沿用现有工程命名，不混用两套模型。
-3. 如果 metadata 不完整，优先转到 `yss-db2mybatis` 提取。
+3. 如果 metadata 不完整，先补齐 metadata、数据库表结构或 DDL 输入。
 4. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
 5. 涉及持久化模型与 Domain/VO/CMD 转换时，必须加载并遵守 `mapstruct`。
 6. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
@@ -57,7 +57,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 
 ## 协同顺序
 
-- metadata 提取：`yss-db2mybatis`
+- metadata / DDL 输入准备：确认输入完整
 - 领域建模：`yss-domain`
 - POJO 样板代码：`lombok`
 - 对象转换：`mapstruct`

package/template/.trae/skills/yss-router/references/boundaries.md

@@ -26,7 +26,6 @@ Default for a new page: first verify the approved product design, state matrix,
 - `yss-backend-scaffold-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
 - `yss-repository`: Persistence implementation, PO, Repository, Convertor, GatewayImpl.
 - `yss-web-controller`: REST adapter layer, request/response DTOs, VO, web convertor.
-- `yss-db2mybatis`: Generate persistence artifacts from database metadata or DDL.
 - `yss-mybatis`: Framework behavior for MyBatis/MyBatis-Plus, BaseRepository, pagination, mapper scanning, batch, datasource issues.
 - `yss-dto`: Result/PageQuery/CommandDTO/QueryDTO and unified API contract objects.
 
@@ -48,9 +47,7 @@ Default for end-to-end backend CRUD: include Domain, Application, Infrastructure
 - `yss-validation`: Validation engine and JSR-303 integration.
 - `yss-security-algorithm`: RSA/AES/SM/JWT/JWK/password-encoding compatibility and production key-management safety gates.
 - `yss-userinfo`: Current-user info propagation and starter integration.
-- `yss-variable`: Variable component APIs and variable resolution.
 - `yss-exception`: Exception component and unified exception handling.
-- `yss-valuation`: Valuation component behavior.
 
 Component skills should inspect generated `references/source-index.md` before changing code when the task depends on exact class or config names.
 

package/template/.trae/skills/yss-source-index/references/source-map-config.md

@@ -20,9 +20,7 @@ The refresh script maps component source path hints to skill references. These p
 | `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
 | `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
 | `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |
-| `yss-variable` | `yss-microservice-components/yss-component-variable` |
 | `yss-exception` | `yss-microservice-components/yss-component-exception` |
-| `yss-valuation` | `yss-microservice-components/yss-component-valuation` |
 
 Frontend docs are written to these skills:
 

package/template/.trae/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-jdbc":["yss-microservice-components/yss-component-jdbc"],"yss-dictionary":["yss-microservice-components/yss-component-dictionary-parent"],"yss-log":["yss-microservice-components/yss-component-log-starter"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-taskflow":["yss-microservice-components/yss-component-taskflow"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-variable":["yss-microservice-components/yss-component-variable"],"yss-exception":["yss-microservice-components/yss-component-exception"],"yss-valuation":["yss-microservice-components/yss-component-valuation"]};
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-jdbc":["yss-microservice-components/yss-component-jdbc"],"yss-dictionary":["yss-microservice-components/yss-component-dictionary-parent"],"yss-log":["yss-microservice-components/yss-component-log-starter"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-taskflow":["yss-microservice-components/yss-component-taskflow"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
 const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
 const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
 const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];

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

@@ -16,7 +16,7 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 不适用
 
 - 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 或 `yss-db2mybatis`。
+- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 并准备完整的 metadata 输入。
 
 ## 优先流程
 

package/template/CONTEXT.md

@@ -21,6 +21,8 @@
 | `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |
 | OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | Freeze 前不得作为前后端稳定实现契约。 |
 | OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | Freeze 后变更必须回到 API 影响分析和设计审查。 |
+| YSS 响应包装 | 对外 API 使用 `Result` 基础字段及 `SingleResult`、`MultiResult`、`PageResult` 表达单对象、非分页列表和分页查询结果的统一返回结构。 | Java 泛型记法是语义简称；公开 schema 必须落成具体 endpoint wire shape。 |
+| DTO wire shape | DTO 在 HTTP/JSON 边界实际暴露的字段、类型、可空性和方向性；与 Java 字段、getter 或内部协作字段区分。 | 以目标 mapper / contract evidence 为准，不从 getter、Lombok 或 `@JsonIgnore` 机械推断。 |
 | UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
 | 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
 | 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
@@ -57,6 +59,8 @@
 | 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | 不作为通用流程模板的权威来源。 |
 | 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | 不包含模板源审查、研究、发布路线或源仓库专属 ADR。 |
 | 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线和源仓库治理决策的归档区域。 | 不随 CLI 分发；不等于产品实例的研发管理资产。 |
+| 目标平台单文件二进制 | 随模板快照分发、只适用于一个受支持 OS/架构组合的可执行文件。 | 不等同于跨平台通用文件，也不等同于运行时下载或 `cargo install`。 |
+| 原生模板实例运行时 | 在模板实例中执行原有治理和验证公共操作、且不依赖 Node.js 的目标平台原生运行时。 | 不等同于模板维护侧的构建工具，也不等同于仅创建模板的安装器。 |
 | 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。

package/template/docs/api/templates/openapi-draft-review-checklist.md

@@ -20,6 +20,7 @@
 | AntD CLI 校验证据 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` 或评审记录 | 有 UI 时必需；记录 design.md / info / demo / token / semantic 查询 |
 | 用户确认记录 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` | 有 UI 时必需；未确认前不得进入 OpenAPI Draft 评审 |
 | YSS 工程基线 | `.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md` |  |
+| YSS DTO wire profile | `.agents/skills/yss-dto/references/openapi-wire-profile.yaml`；`scripts/verify-yss-dto-openapi-profile` |  |
 
 ## P0 追踪矩阵
 
@@ -41,6 +42,11 @@
 | 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey` 和错误码；Spec 明确认认证 / 授权变化时同时映射该行为 |  |  |
 | 对象生命周期 | manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft 语义闭环 |  |  |
 | YSS 响应包装 | 单对象 `SingleResult<T>`；列表 `MultiResult<T>`；分页 `PageResult<T>` |  |  |
+| DTO wire shape | `com.yss.cloud.dto.result` 为新契约 canonical；`data` 落成 endpoint-specific schema，Java 泛型文字不得成为 OAS type / `$ref`；响应使用 `x-yss-response-wrapper`、`YssResultMeta` 和 `allOf` |  |  |
+| 公共响应字段 | `success:boolean`；`dataType:string|null`；`code:string|integer|null`；`message/tips` 显式 nullable；不得把全局 `code` 放宽为 arbitrary object |  |  |
+| 分页输入 | 只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`；`orderDirection` 为 `ASC|DESC`；`orderBy/groupBy` 有 endpoint whitelist |  |  |
+| 分页负向字段 | `offset`、`needTotalCount`、`tempTotalCount` 不得成为客户端输入；`totalPages` 仅在目标 mapper / fixture 证据存在时纳入 |  |  |
+| Wire 证据 | mapper identity、代表性序列化 fixture、contract-test / 等价 HTTP 证据已记录；不能从 getter、Lombok 或 `@JsonIgnore` 直接推断 |  |  |
 | 显式认证 / 授权行为 | 仅当 Spec 明确改变相关行为时，`401` / `403`、资源过滤和错误语义有契约表示 |  | 未明确改变时不适用且无需额外记录 |
 | 错误结构 | 模型级、字段级、行级错误可定位；关键 422 有 examples |  |  |
 | 乐观锁 / 幂等 | 草稿写入有 draftVersion；关键命令有幂等键 |  |  |

package/template/scripts/lib/scenario-checks.mjs

@@ -38,6 +38,23 @@ const profiles = {
     message: "OpenAPI YAML-first JSON handoff scenarios passed",
     files: ["docs/api/templates/openapi-json-export-record-template.md", ".agents/skills/yss-api-integration/SKILL.md"],
     markers: [[".agents/skills/yss-api-integration/SKILL.md", "SHA-256"]]
+  },
+  yssDtoWire: {
+    message: "YSS DTO OpenAPI wire-shape scenarios passed",
+    files: [
+      ".agents/skills/yss-dto/references/openapi-wire-profile.yaml",
+      ".agents/skills/yss-dto/SKILL.md",
+      ".agents/skills/yss-openapi-governance/SKILL.md",
+      ".agents/skills/yss-openapi-draft-review/SKILL.md",
+      "docs/api/templates/openapi-draft-review-checklist.md",
+      "scripts/verify-yss-dto-openapi-profile"
+    ],
+    markers: [
+      [".agents/skills/yss-dto/SKILL.md", "x-yss-response-wrapper"],
+      [".agents/skills/yss-openapi-governance/SKILL.md", "verify-yss-dto-openapi-profile"],
+      [".agents/skills/yss-openapi-draft-review/SKILL.md", "offset`, `needTotalCount`, and `tempTotalCount"],
+      ["docs/api/templates/openapi-draft-review-checklist.md", "DTO wire shape"]
+    ]
   }
 };
 
@@ -50,5 +67,9 @@ export function runScenario(name) {
     const result = spawnSync("scripts/verify-lifecycle-registry", [], { cwd: root, encoding: "utf8" });
     ensure(result.status === 0, result.stderr || result.stdout);
   }
+  if (name === "yssDtoWire") {
+    const result = spawnSync("scripts/verify-yss-dto-openapi-profile", [], { cwd: root, encoding: "utf8" });
+    ensure(result.status === 0, result.stderr || result.stdout);
+  }
   process.stdout.write(`${profile.message}\n`);
 }

package/template/scripts/lib/skill-supply-chain.mjs

@@ -8,7 +8,7 @@ export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "
 const SOURCE_ROOT = path.join(ROOT, ".agents/skills");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
-const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-openapi"]);
+const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi"]);
 
 function relative(target) { return path.relative(ROOT, target).replaceAll(path.sep, "/"); }
 function entries(directory) { return existsSync(directory) ? readdirSync(directory, { withFileTypes: true }) : []; }

package/template/scripts/verify-template

@@ -5,7 +5,7 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT_DIR"
 node -e 'const [major]=process.versions.node.split(".").map(Number); if (major < 22 || major >= 27) { console.error("模板工具需要 Node >=22 <27"); process.exit(1); }'
 
-required_files=(yss-project.yaml AGENTS.md CONTEXT.md skills-lock.json docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json scripts/repository-mode scripts/implementation-path-policy scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/export-yss-skills)
+required_files=(yss-project.yaml AGENTS.md CONTEXT.md skills-lock.json docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json scripts/repository-mode scripts/implementation-path-policy scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/export-yss-skills)
 for required in "${required_files[@]}"; do test -f "$required" || { echo "缺少模板必需文件: $required" >&2; exit 1; }; done
 
 repository_mode="$(scripts/repository-mode)"
@@ -18,6 +18,8 @@ fi
 
 scripts/sync-skills --check
 scripts/update-skill-lock --check
+scripts/verify-yss-dto-openapi-profile
+scripts/verify-yss-dto-openapi-scenarios
 scripts/verify-lifecycle-registry
 scripts/verify-lifecycle-scenarios
 scripts/verify-governance-release
@@ -30,7 +32,7 @@ scripts/verify-yss-ui-scenarios
 scripts/verify-openapi-yaml-first-scenarios
 scripts/verify-openapi-json-handoff-scenarios
 
-for entry in scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-scenarios scripts/verify-matt-yss-integration-scenarios scripts/verify-prototype-backend-scaffold-scenarios scripts/verify-yss-router-scenarios scripts/verify-openapi-yaml-first-scenarios scripts/verify-openapi-json-handoff-scenarios scripts/export-yss-skills; do node --check "$entry"; done
+for entry in scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/verify-lifecycle-scenarios scripts/verify-matt-yss-integration-scenarios scripts/verify-prototype-backend-scaffold-scenarios scripts/verify-yss-router-scenarios scripts/verify-openapi-yaml-first-scenarios scripts/verify-openapi-json-handoff-scenarios scripts/export-yss-skills; do node --check "$entry"; done
 
 legacy_runtime="ru""by"
 script_roots=(scripts)

package/template/scripts/verify-yss-dto-openapi-profile

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const profilePath = path.join(root, ".agents/skills/yss-dto/references/openapi-wire-profile.yaml");
+
+function ensure(condition, message) {
+  if (!condition) throw new TypeError(message);
+}
+
+function sameMembers(actual, expected, label) {
+  ensure(Array.isArray(actual), `${label} 必须是数组`);
+  const left = [...actual].sort().join(",");
+  const right = [...expected].sort().join(",");
+  ensure(left === right, `${label} 必须为 [${expected.join(", ")}]，实际为 [${actual.join(", ")}]`);
+}
+
+function includesAll(actual, expected, label) {
+  ensure(Array.isArray(actual), `${label} 必须是数组`);
+  for (const value of expected) ensure(actual.includes(value), `${label} 缺少 ${value}`);
+}
+
+function checkField(field, label, { wireTypes, nullable, required, direction }) {
+  ensure(field && typeof field === "object", `${label} 必须是对象`);
+  if (direction) ensure(field.direction === direction, `${label}.direction 必须为 ${direction}`);
+  sameMembers(field.wire_types, wireTypes, `${label}.wire_types`);
+  ensure(field.nullable === nullable, `${label}.nullable 必须为 ${nullable}`);
+  ensure(field.required === required, `${label}.required 必须为 ${required}`);
+}
+
+function checkArrayData(field, label, direction) {
+  checkField(field, label, { wireTypes: ["array"], nullable: false, required: true, direction });
+  ensure(field.items === "endpoint-schema", `${label}.items 必须为 endpoint-schema`);
+  ensure(Array.isArray(field.empty_value) && field.empty_value.length === 0, `${label}.empty_value 必须为 []`);
+}
+
+try {
+  const document = parseDocument(readFileSync(profilePath, "utf8"), { maxAliasCount: 0 });
+  ensure(document && document.errors.length === 0, `wire profile YAML 无法解析: ${document?.errors?.map((error) => error.message).join("; ")}`);
+  const profile = document.toJSON();
+
+  ensure(profile.schema_version === 1, "wire profile schema_version 必须为 1");
+  ensure(profile.kind === "yss-dto-openapi-wire-profile", "wire profile kind 不正确");
+  ensure(profile.canonical?.java_package === "com.yss.cloud.dto.result", "canonical package 必须为 com.yss.cloud.dto.result");
+  ensure(profile.canonical?.type_parameter?.java_bound === "java.io.Serializable", "结果泛型必须声明 Serializable bound");
+  ensure(profile.canonical?.openapi?.response_meta_schema === "YssResultMeta", "OpenAPI 基础响应 schema 必须为 YssResultMeta");
+  ensure(profile.canonical?.openapi?.concrete_schema_composition === "allOf", "具体响应 schema 必须使用 allOf 组合");
+  ensure(profile.canonical?.openapi?.response_wrapper_extension === "x-yss-response-wrapper", "响应包装扩展字段不正确");
+  ensure(profile.canonical?.openapi?.literal_java_generic_schema === false, "不得把 Java 泛型文字作为 OpenAPI schema");
+
+  const compatibility = profile.compatibility_packages?.find((item) => item.java_package === "com.yss.cloud.dto.response");
+  ensure(compatibility?.use_for_new_contracts === false, "dto.response 必须标记为非新契约 canonical");
+
+  const commonFields = profile.common_response?.fields ?? {};
+  sameMembers(Object.keys(commonFields), ["success", "dataType", "code", "message", "tips"], "common response fields");
+  checkField(commonFields.success, "success", { wireTypes: ["boolean"], nullable: false, required: true, direction: "response" });
+  checkField(commonFields.dataType, "dataType", { wireTypes: ["string", "null"], nullable: true, required: true, direction: "response" });
+  checkField(commonFields.code, "code", { wireTypes: ["string", "integer", "null"], nullable: true, required: true, direction: "response" });
+  checkField(commonFields.message, "message", { wireTypes: ["string", "null"], nullable: true, required: true, direction: "response" });
+  checkField(commonFields.tips, "tips", { wireTypes: ["string", "null"], nullable: true, required: true, direction: "response" });
+  ensure(commonFields.code.policy === "do-not-widen-global-wrapper", "code 不得退化为全局 arbitrary object");
+
+  sameMembers(Object.keys(profile.wrappers ?? {}), ["SingleResult", "MultiResult", "PageResult"], "wrappers");
+  for (const name of ["SingleResult", "MultiResult", "PageResult"]) {
+    ensure(profile.wrappers[name].java_type.startsWith(`com.yss.cloud.dto.result.${name}<T>`), `${name} 必须来自 canonical result package`);
+  }
+  const singleData = profile.wrappers.SingleResult?.data;
+  ensure(singleData?.direction === "response", "SingleResult.data 必须为 response");
+  ensure(singleData?.wire_shape === "endpoint-schema-or-null", "SingleResult.data 必须绑定 endpoint schema 或 null");
+  ensure(singleData?.nullable === true && singleData?.required === true, "SingleResult.data 必须显式 required 且 nullable");
+  checkArrayData(profile.wrappers.MultiResult?.data, "MultiResult.data", "response");
+  const pageFields = profile.wrappers.PageResult?.fields ?? {};
+  sameMembers(Object.keys(pageFields), ["totalCount", "pageSize", "pageIndex", "data"], "PageResult.fields");
+  checkField(pageFields.totalCount, "PageResult.totalCount", { wireTypes: ["integer"], nullable: false, required: true, direction: "response" });
+  ensure(pageFields.totalCount.format === "int64" && pageFields.totalCount.minimum === 0, "PageResult.totalCount 必须为非负 int64");
+  checkField(pageFields.pageSize, "PageResult.pageSize", { wireTypes: ["integer"], nullable: false, required: true, direction: "response" });
+  ensure(pageFields.pageSize.format === "int32" && pageFields.pageSize.minimum === 1, "PageResult.pageSize 必须为正 int32");
+  checkField(pageFields.pageIndex, "PageResult.pageIndex", { wireTypes: ["integer"], nullable: false, required: true, direction: "response" });
+  ensure(pageFields.pageIndex.format === "int32" && pageFields.pageIndex.minimum === 1, "PageResult.pageIndex 必须为正 int32");
+  checkArrayData(pageFields.data, "PageResult.data", "response");
+  sameMembers(profile.page_query?.forbidden_client_fields, ["offset", "needTotalCount", "tempTotalCount"], "forbidden_client_fields");
+  ensure(profile.page_query?.request_direction === "query", "PageQuery 必须声明 query request direction");
+  const pageQueryFields = profile.page_query?.fields ?? {};
+  sameMembers(Object.keys(pageQueryFields), ["pageIndex", "pageSize", "orderBy", "orderDirection", "groupBy"], "PageQuery.fields");
+  checkField(pageQueryFields.pageIndex, "PageQuery.pageIndex", { wireTypes: ["integer"], nullable: false, required: false, direction: "request" });
+  ensure(pageQueryFields.pageIndex.format === "int32" && pageQueryFields.pageIndex.minimum === 1 && pageQueryFields.pageIndex.default === 1, "PageQuery.pageIndex 必须为正 int32，默认 1");
+  checkField(pageQueryFields.pageSize, "PageQuery.pageSize", { wireTypes: ["integer"], nullable: false, required: false, direction: "request" });
+  ensure(pageQueryFields.pageSize.format === "int32" && pageQueryFields.pageSize.minimum === 1 && pageQueryFields.pageSize.default === 10, "PageQuery.pageSize 必须为正 int32，默认 10");
+  checkField(pageQueryFields.orderBy, "PageQuery.orderBy", { wireTypes: ["string", "null"], nullable: true, required: false, direction: "request" });
+  ensure(pageQueryFields.orderBy.policy === "endpoint-whitelist-required", "PageQuery.orderBy 必须要求 endpoint whitelist");
+  sameMembers(profile.page_query?.fields?.orderDirection?.enum, ["ASC", "DESC"], "orderDirection.enum");
+  checkField(pageQueryFields.orderDirection, "PageQuery.orderDirection", { wireTypes: ["string"], nullable: false, required: false, direction: "request" });
+  ensure(pageQueryFields.orderDirection.default === "DESC", "PageQuery.orderDirection 默认值必须为 DESC");
+  checkField(pageQueryFields.groupBy, "PageQuery.groupBy", { wireTypes: ["string", "null"], nullable: true, required: false, direction: "request" });
+  ensure(pageQueryFields.groupBy.policy === "endpoint-whitelist-required", "PageQuery.groupBy 必须要求 endpoint whitelist");
+  ensure(profile.wrappers.PageResult.computed_fields.totalPages.policy === "include-only-with-target-wire-evidence", "totalPages 必须要求目标 wire evidence");
+  ensure(profile.wrappers.PageResult.computed_fields.totalPages.status === "mapper-dependent", "totalPages 必须标记为 mapper-dependent");
+  ensure(profile.page_query.computed_fields.offset.policy === "exclude-from-client-input", "offset 不得成为客户端输入");
+  ensure(profile.page_query.computed_fields.needTotalCount.policy === "exclude-from-client-input", "needTotalCount 不得成为客户端输入");
+  ensure(profile.page_query.computed_fields.tempTotalCount.policy === "exclude-from-client-input", "tempTotalCount 不得成为客户端输入");
+  includesAll(profile.wire_evidence?.required_before_freeze, ["target-http-mapper-identity", "representative-serialization-fixtures", "contract-test-or-equivalent-http-evidence"], "wire_evidence.required_before_freeze");
+  process.stdout.write("YSS DTO OpenAPI wire profile 验证通过\n");
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-yss-dto-openapi-scenarios

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runScenario } from "./lib/scenario-checks.mjs";
+
+try { runScenario("yssDtoWire"); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }