create-yss-spec 2.1.6 → 2.1.8

package/template/.codex/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/.codex/skills/yss-mybatis/SKILL.md

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

package/template/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.github/workflows/template-node-tooling.yml

@@ -15,6 +15,8 @@ jobs:
         node: [22, 24]
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: pnpm/action-setup@v4
         with:
           version: 10.15.0

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

@@ -18,7 +18,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 ## 不适用
 
 - 只补单个领域模型时，优先 `yss-domain`。
-- 只补持久层时，优先 `yss-db2mybatis` 或 `yss-repository`。
+- 只补持久层时，优先 `yss-repository`。
 - 只补 Web 层时，优先 `yss-web-controller`。
 
 ## 优先流程

package/template/.hermes/skills/yss-domain/SKILL.md

@@ -17,7 +17,7 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 不适用
 
-- 只生成持久层时，优先 `yss-repository` 或 `yss-db2mybatis`。
+- 只生成持久层时，优先 `yss-repository`。
 - 只生成 Controller 时，优先 `yss-web-controller`。
 - 只初始化项目骨架时，优先 `yss-ddd-scaffold-generator`。
 
@@ -51,7 +51,7 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 协同顺序
 
-- 需要持久层时，再接 `yss-repository` 或 `yss-db2mybatis`
+- 需要持久层时，再接 `yss-repository`
 - 需要 Web 层时，再接 `yss-web-controller`
 - 需要完整工程时，先 `yss-ddd-scaffold-generator`
 

package/template/.hermes/skills/yss-dto/SKILL.md

@@ -7,6 +7,8 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 用于处理 `yss-component-dto` 的使用规范和代码接入。
 
+本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
+
 ## 何时使用
 
 - 用户要定义新的分页查询对象。
@@ -18,13 +20,15 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
 2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先确认当前项目用的是哪一套结果封装，再给出改法。
-4. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
+3. 先确认当前项目用的是哪一套结果封装和实际 import；新契约的 canonical 包是 `com.yss.cloud.dto.result`，`com.yss.cloud.dto.response` 只能作为 legacy / compatibility 线索，不能在新契约中引入。
+4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
+5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
 
 ## 源码索引
 
 - 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
 - 当前技能索引：`references/source-index.md`
+- OpenAPI wire profile：`references/openapi-wire-profile.yaml`
 - 重点源码入口通常包括 `CommandDTO`、`QueryDTO`、`PageQuery`、`PageRequestFactory`、`Result`、`SingleResult`、`MultiResult`、`PageResult`。
 
 当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
@@ -37,8 +41,13 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
 - 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
-- `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`，不能只测试 data。
-- `needTotalCount` / `tempTotalCount` 是内部分页协作字段；当前源码中前者标注暂未实现，二者都不是客户端输入。
+- OpenAPI 响应以 `YssResultMeta` 表达公共字段，并用 `allOf` 叠加 endpoint-specific `data` / page 字段；每个响应声明 `x-yss-response-wrapper: SingleResult|MultiResult|PageResult`，不得把 `SingleResult<T>` 文字写成 schema。
+- wire shape 不是 Java 字段清单：`success` 为 boolean，`dataType` 为 `string|null`，`code` 只允许 `string|integer|null`；不得把全局 `code` 放宽为任意 object。
+- `MultiResult.data` 和 `PageResult.data` 对外是数组，空值按 `[]` 建模；`SingleResult.data` 按 endpoint schema 建模并显式处理 nullability。
+- `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
+- `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
+- `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
+- Java getter、Lombok、`@JsonIgnore` 或默认 Jackson 结果都不是目标 HTTP wire fact；冻结前必须记录 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
 - DTO 只表达接口契约，不承载 Repository PO 或领域对象的持久化细节。
 
 ## 检查清单
@@ -48,6 +57,9 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - Service / Repository 是否真的接收到了 `PageQuery`。
 - 新增 DTO 是否与现有序列化和校验方式兼容。
 - 返回结构是否和前端或上游调用方契约一致。
+- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
+- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
+- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
 - Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
 - 前端 Orval 或调用方是否依赖当前返回包装结构。
 
@@ -55,6 +67,8 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 - 不要在一个项目里混用多套返回包装类。
 - 不要新建与 `PageQuery` 含义重叠的分页基类。
+- 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
+- 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
 - 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
 
 ## 按需读取
@@ -63,6 +77,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - DTO 基类示例：`assets/CommandDTO.java`、`assets/QueryDTO.java`
 - 分页基类：`assets/PageQuery.java`
 - 返回结构：`assets/Result.java`
+- HTTP/JSON 映射：`references/openapi-wire-profile.yaml`
 
 ## 阶段 7 合同
 

package/template/.hermes/skills/yss-dto/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS DTO"
   short_description: "统一响应、分页查询、Command 与 DTO 设计规范"
-  default_prompt: "Use $yss-dto to define YSS-style DTOs, page queries, commands, and unified response models."
+  default_prompt: "Use $yss-dto to define YSS-style DTOs, page queries, commands, unified response models, and their OpenAPI HTTP/JSON wire shapes."

package/template/.hermes/skills/yss-dto/references/README.md

@@ -1,6 +1,6 @@
 # 参考资料
 
-本文档详细介绍了 `yss-component-dto` 组件的核心数据传输对象（DTO）。这些 DTO 类被广泛应用于各个服务项目，用于规范数据交互格式。
+本文档详细介绍了 `yss-component-dto` 组件的核心数据传输对象（DTO）。这些 DTO 类被广泛应用于各个服务项目，用于规范数据交互格式。公开 HTTP/JSON 的可复用映射以 `openapi-wire-profile.yaml` 为准；本文不把 Java 字段或 getter 自动等同于 wire shape。
 
 ## 核心类 (Core Classes)
 
@@ -13,7 +13,7 @@
 **核心字段**:
 
 - `success`: 操作是否成功 (boolean)
-- `code`: 状态码 (Object, 默认 "DM-A0001")
+- `code`: Java 内部类型为 `Object`；公开 wire contract 仅允许 `string | integer | null`
 - `message`: 消息描述 (String, 默认 "数据返回正常")
 - `dataType`: 返回数据格式
 - `tips`: 提示消息
@@ -44,6 +44,13 @@
 - 提供了链式调用的 Setter 方法 (`setPageIndex`, `setPageSize` 等)。
 - 自动计算偏移量 `getOffset()`。
 
+## HTTP/JSON 映射边界
+
+- 新契约使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 只作为 legacy / compatibility 线索。
+- 公共响应 schema 使用 `YssResultMeta`，具体 endpoint schema 使用 `allOf` 组合，并声明 `x-yss-response-wrapper`。
+- `MultiResult.data` 和 `PageResult.data` 为数组；`SingleResult.data` 绑定具体 endpoint schema。不要把 `SingleResult<T>`、`MultiResult<T>` 或 `PageResult<T>` 的 Java 泛型文字直接写成 OpenAPI schema。
+- `PageQuery` 的客户端字段是 `pageIndex/pageSize/orderBy/orderDirection/groupBy`；`offset`、`needTotalCount`、`tempTotalCount` 不属于客户端输入。`totalPages` 只有目标 mapper / contract evidence 证明后才进入响应契约。
+
 ### 3. CommandDTO.java & QueryDTO.java
 
 **位置**: `../assets/CommandDTO.java`, `../assets/QueryDTO.java`