create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-mybatis/references/README.md

@@ -0,0 +1,57 @@
+# 参考资料
+
+本文档详细介绍了 `yss-component-mybatis-starter` 模块中的核心类和配置类，这些类构成了通用 MyBatis 模式的基础。
+
+## 核心类 (Core Classes)
+
+### 1. BaseRepository.java
+**位置**: `../assets/BaseRepository.java`
+
+`BaseRepository<T, D>` 是通用 MyBatis 模式下的核心 Mapper 接口，所有业务 Repository 都应继承它。
+
+**主要特性**:
+- **继承链**: 继承了 `io.mybatis.mapper.BaseMapper` (基础 CRUD), `io.mybatis.mapper.list.ListMapper` (批量操作), 和 `com.baomidou.mybatisplus.core.mapper.Mapper` (兼容性)。
+- **通用方法**:
+  - `insert`, `update`, `delete`: 标准的单表操作。
+  - `selectBatchIds`, `deleteBatchIds`: 批量操作。
+  - `selectByMap`, `selectMaps`, `selectObjs`: 基于 Map 和 Wrapper 的查询。
+- **扩展点**: 允许用户通过继承此接口，获得开箱即用的 CRUD 能力，无需编写 XML。
+
+### 2. EntityQueryAspect.java
+**位置**: `../assets/EntityQueryAspect.java`
+
+这是一个 AOP 切面，用于实现非侵入式的自动分页功能。
+
+**工作原理**:
+- **切点**: 拦截所有 Repository 层 (`@Repository`) 和 Gateway 实现层的方法。
+- **条件**: 方法参数中必须包含 `com.yss.cloud.dto.page.PageQuery` 对象。
+- **逻辑**:
+  1. 检查 `PageQuery` 参数是否非空。
+  2. 调用 `PageHelper.offsetPage(offset, pageSize)` 开启分页。
+  3. 执行目标方法。
+  4. 获取分页结果的总记录数 (`page.getTotal()`)。
+  5. 将总数回填到 `PageQuery.tempTotalCount` 字段中。
+
+### 3. MybatisBaseConfiguration.java
+**位置**: `../assets/MybatisBaseConfiguration.java`
+
+MyBatis 基础配置类，负责加载核心组件。
+
+**主要功能**:
+- **导入配置**: 导入了 `PageQueryEntityConfigration`，确保分页切面生效。
+- **启用属性**: 启用了 `PrimaryDataSourceProperties`, `MybatisPlusGlobalProperties`, `YssMybatisMapperProperties` 等配置属性类。
+
+### 4. PageQueryEntityConfigration.java
+**位置**: `../assets/PageQueryEntityConfigration.java`
+
+负责注册分页查询切面。
+
+**主要功能**:
+- 定义了 `entityQueryAspect` Bean，使其受 Spring 容器管理，从而激活自动分页拦截功能。
+
+## 使用建议
+
+当您在开发中使用通用 MyBatis 模式时：
+1. **定义 Repository**: 直接继承 `BaseRepository<Entity, ID>`。
+2. **分页查询**: 在方法参数中添加 `PageQuery`，框架会自动处理分页逻辑。
+3. **批量操作**: 使用 `insertList`, `updateList` 等方法进行高效的数据处理。

package/template/.cursor/skills/yss-mybatis/references/source-index.md

@@ -0,0 +1,93 @@
+# yss-mybatis Source Index
+
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
+Source worktree: `dirty`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+
+Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-persistence` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-persistence/HELP.md`
+- `yss-microservice-components/yss-component-persistence/README.md`
+- `yss-microservice-components/yss-component-persistence/TECHNICAL_DESIGN.md`
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-persistence`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/defaults/UserConfig.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/spring/SpringEnvAutoConfiguration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/BaseMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/Mapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/base/EntityMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/config/MapperUserConfig.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/example/ExampleMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/fn/FnMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/list/ListMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalColumn.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalProvider.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityColumnFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityInfoMapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityTableFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlCache.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScript.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScriptWrapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlSourceCustomize.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlWrapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/config/ProviderUserConfig.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlScriptWrapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlWrapper.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/CachingEntityTableFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactoryChain.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactoryChain.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/GenericTypeResolver.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityColumnFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityTableFactory.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/SimpleTypeUtil.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenId.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdKeyGenerator.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdSqlSource.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlMsCustomize.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlSqlSourceCustomize.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusConfiguration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusGlobalProperties.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/PageInterceptorProperties.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MybatisPlusConfig.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/LogbackImpl.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/MybatisBaseConfiguration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceConfiguration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceProperties.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceConfiguration.java`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceProperties.java`
+
+## Recommended Next Reads
+
+- Start with the documentation files above when learning component usage.
+- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
+- Prefer existing component extension points over rewriting framework logic in business modules.

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

@@ -0,0 +1,82 @@
+---
+name: yss-openapi-draft-review
+description: Use when reviewing a `docs/.scratch/<feature>/api/` OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/Spec Delta design, OpenAPI Freeze, vertical slicing, frontend/backend implementation, or when checking P0 requirement coverage, page action to endpoint mapping, YSS response wrappers, errors, pagination, optimistic locking, and contract test seams.
+---
+
+# YSS OpenAPI Draft Review
+
+Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
+
+## Required Inputs
+
+- 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 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
+
+1. Consume fresh automated evidence for YAML parsing, single-document OAS 3.1 shape, `$ref`, path parameters, and lint. Generate it once with the Draft or when the Draft changes; do not manually repeat unchanged structural checks.
+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, `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.
+
+## Blocking Rules
+
+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 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.
+
+## Output Contract
+
+```markdown
+### Review Result
+<Approved / Blocked>
+
+### Blocking Findings
+- <file:line grounded finding>
+
+### Non-Blocking Suggestions
+- <can wait until architecture/design>
+
+### Contract Coverage
+- <P0 requirement -> endpoint/schema/error/test mapping summary>
+
+### YSS Baseline
+- <`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
+- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
+```
+
+Prefer `docs/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

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

@@ -0,0 +1,130 @@
+---
+name: yss-openapi-governance
+description: Use when creating, governing, linting, freezing, or exporting YSS OpenAPI 3.1 design-time contracts. The frozen YAML is the only authority; this skill produces the reviewed JSON derivative consumed by frontend client generation.
+---
+
+# YSS OpenAPI Governance
+
+本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
+
+```text
+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 派生记录。
+- Spec Delta 影响存在时，在 `docs/.scratch/<feature>/spec-delta/` 记录与冻结 YAML 的关系；没有影响时明确记录 `not-applicable`。
+
+不使用本 skill 来替代：
+
+- `yss-openapi-draft-review`：独立、fail-closed 的语义评审与 P0 追踪。
+- `api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
+- `to-tickets`：在 Freeze 后正式化垂直切片。
+
+## 受控工具链
+
+在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
+
+```bash
+pnpm exec redocly lint docs/.scratch/<feature>/api/<feature>.yaml
+
+pnpm exec redocly bundle \
+  docs/.scratch/<feature>/api/<feature>.yaml \
+  --output docs/.scratch/<feature>/api/<feature>.json \
+  --ext json \
+  --component-renaming-conflicts-severity=error \
+  --metafile docs/.scratch/<feature>/api/<feature>.bundle-metafile.json
+```
+
+默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
+
+`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。
+
+## 治理流程
+
+1. **建立或读取 YAML Draft**
+   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
+   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
+   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
+
+2. **运行结构与治理校验**
+   - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
+   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
+   - 先运行 `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，不得生成生产客户端。
+   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
+
+4. **从冻结 YAML 派生 JSON**
+   - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
+   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
+   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `docs/api/templates/openapi-json-export-record-template.md` 创建。
+   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
+
+5. **交给下游前端**
+   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `api-integration` 与目标前端实现仓库。
+   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
+   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
+   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。
+
+## 阻断规则
+
+阻断 OpenAPI Freeze 或 JSON 导出，若：
+
+- YAML 不是单一 OAS 3.1 document，或其根节点混入生命周期元数据。
+- 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 的权威来源。
+
+## 输出契约
+
+```markdown
+### Governance Result
+<Draft / Approved for Freeze / Blocked / JSON Exported>
+
+### YAML Authority
+- YAML: <docs/.scratch/<feature>/api/<feature>.yaml>
+- OAS: 3.1.0
+- YAML SHA-256: <sha256>
+- Freeze record: <path / ref>
+
+### 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>
+
+### JSON Derivative
+- JSON: <docs/.scratch/<feature>/api/<feature>.json>
+- JSON SHA-256: <sha256>
+- Redocly CLI / lockfile: <version and lock reference>
+- Bundle command and metafile: <command / path>
+- JSON validation result: <pass / blocked>
+
+### Downstream Handoff
+- Canonical JSON / frontend materialization SHA-256: <same sha / blocked>
+- Frontend materialization path: <frontend/openapi/openapi.json / blocked>
+- Existing frontend code generation: <manual command in target repository / blocked reason>
+- Template boundary: <no frontend configuration, code-generation execution, or CI change>
+```

package/template/.cursor/skills/yss-openapi-governance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS OpenAPI Governance"
+  short_description: "Govern YAML-first OpenAPI and export frozen JSON"
+  default_prompt: "Use $yss-openapi-governance to govern an OpenAPI YAML Draft, freeze it, and export its reviewed JSON derivative."

package/template/.cursor/skills/yss-page-module-development/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: yss-page-module-development
+description: Guide AI to create standardized Vue 3 business page modules for YSS micro-applications, including directory layout, hook extraction, table/tree height hooks, YssFormily query areas, YTable pages, and left-tree-right-content shells.
+---
+
+# YSS Page Module Development
+
+Use this skill when the user asks for a business page, CRUD module, tree-table page, detail page, or any standard YSS Vue 3 page module.
+
+## Authoritative Docs And Skill Boundaries
+
+- YSS UI components: `http://192.168.164.27:3200/components`
+- YSS UI hooks: `http://192.168.164.27:3200/hooks`
+- YSS UI skills: `http://192.168.164.27:3200/skills`
+- Local reference index: `references/frontend-docs.md`
+
+This skill orchestrates page/module creation. Load narrower skills only when their details are needed:
+
+中文说明：这个技能负责“建页面模块的流程编排”。遇到具体组件、接口、Hook、高度、Formily 细节时，再补充加载更窄的专项技能。
+
+- `yss-components` for layout, YTable/YTree/YssFormily/YSplitPane component specifics.
+- `yss-hook` for request, pagination, parameter, and mapping logic.
+- `api-integration` for Orval-generated APIs and submit/list/detail flows.
+- `yss-use-table-height` and `yss-use-tree-height` for height calculation.
+- `yss-formily` for detailed schema behavior.
+
+## What this skill produces
+
+- a page folder with predictable structure
+- a clear split between page composition and hook logic
+- YSS-aligned query, table, tree, and layout wiring
+- code that follows the existing app conventions instead of ad hoc UI assembly
+
+## Recommended workflow
+
+1. Identify the page type: list, tree-table, detail, or mixed.
+2. Decide whether the page needs `YssFormily`, `YTable`, `YTree`, `YSplitPane`, or custom blocks.
+3. Create the page folder structure.
+4. Move request and parameter logic into hooks.
+5. Assemble the page with minimal logic in `index.vue`.
+6. Verify loading, empty, and error states.
+
+## Standard structure
+
+```text
+views/PageName/
+  components/
+    XxxBlock/
+      index.vue
+      style.less
+      type.ts
+  hooks/
+    usePageTable.ts
+    usePageTree.ts
+  schemas/
+    searchSchema.ts
+  index.vue
+  style.less
+```
+
+Rules:
+
+- `index.vue` is for composition only.
+- `hooks/` holds request, parameter, selection, and mapping logic.
+- `components/` holds reusable blocks and view fragments.
+- `schemas/` holds YssFormily schema definitions.
+
+## Component priority
+
+1. Prefer `@yss-ui/components`.
+2. Use `ant-design-vue` only when YSS does not provide the needed control.
+3. Reuse existing page patterns before inventing a new layout.
+
+## Layout rules
+
+For left-tree-right-content pages:
+
+- use `YSplitPane` or an equivalent flexible split layout
+- keep the right side ordered as Header -> Query -> Data
+- make the content area flexible, not fixed height
+- provide a clear empty state when nothing is selected
+
+For non-split pages:
+
+- keep the main region responsive
+- avoid nested fixed-height containers that fight scrolling
+
+## Height hooks
+
+Use `useTableHeight` and `useTreeHeight` when the page needs available-height calculation.
+
+- bind the ref to the container, not to the table/tree itself
+- include pagination or toolbar offsets when they exist
+- keep the container `flex: 1; overflow: hidden`
+
+## Query and data regions
+
+### YssFormily
+
+- use schema-driven queries
+- keep action buttons in the schema
+- keep local helper logic in `scope`
+
+### YTable
+
+- use `field/type` column definitions
+- prefer named slots for custom cells
+- keep pagination and loading state driven by hook state
+
+### YTree
+
+- keep tree data and selection logic in hooks
+- use search offsets and height helpers when search is present
+
+## Page coding rules
+
+- use `<script setup lang="ts">`
+- keep `index.vue` thin
+- move data transformation out of templates
+- keep action handlers small and explicit
+- preserve existing route, menu, and permission conventions in the repo
+
+## Deliverables
+
+When implementing a page module, the result should usually include:
+
+- page shell
+- hook file(s)
+- schema file(s)
+- block components if needed
+- styles
+
+## Checklist
+
+- the page structure matches the chosen pattern
+- request logic is isolated in hooks
+- query, pagination, and selection state have one source of truth
+- empty, loading, and error states are covered
+- custom blocks are extracted only when they improve clarity or reuse
+
+## Do not
+
+- do not put large request flows in `index.vue`
+- do not duplicate parameter handling across page and hook
+- do not bypass YSS components when a project-standard control exists
+- do not over-split a simple page into unnecessary files
+
+## Stage 7 Contract
+
+- Require an approved `Slice Implementation Contract`, requirement freeze, low-fidelity review, Ant Design v6 high-fidelity HTML prototype, AntD CLI evidence, user confirmation, and state matrix for UI-impact work.
+- Bind page, hooks, schema, blocks, generated API client, component tests, and E2E paths to contract fields and `allowed_write_paths`.
+- User-visible loading, empty, error, permission, selection, pagination, and action behavior use `behavior-tdd`; purely mechanical page scaffolding may use documented `controlled-generation`.
+- Return the shared `YSS Skill Execution Result`. A prototype mismatch, new API, new permission state, path overrun, or missing evidence must produce `drift`, `violation`, or `new_impacts`, not `implemented`.

package/template/.cursor/skills/yss-page-module-development/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Page Module"
+  short_description: "标准业务页面模块、分区布局与 Hook 开发实践规范"
+  default_prompt: "Use $yss-page-module-development to scaffold a YSS Vue 3 page module with hooks, schemas, and split layout."

package/template/.cursor/skills/yss-page-module-development/examples/AdvancedFormPage/constant.ts

@@ -0,0 +1,32 @@
+/**
+ * 复杂表单页面 - 常量配置
+ */
+
+/** 步骤枚举 */
+export enum RULE_STEPS {
+  BASE_INFO = 1,
+  RULE_CONFIG = 2,
+  RULE_RESULT = 3,
+}
+
+/** 步骤配置 */
+export const QUALITY_RULE_STEPS = [
+  { value: RULE_STEPS.BASE_INFO, title: '基本信息' },
+  { value: RULE_STEPS.RULE_CONFIG, title: '规则配置' },
+  { value: RULE_STEPS.RULE_RESULT, title: '规则结果' },
+];
+
+/** 条件组节点接口 */
+export interface ConditionGroup {
+  id: string;
+  type: 'GROUP' | 'LEAF';
+  logicalOp: 'AND' | 'OR';
+  children: any[];
+}
+
+/** 表单选项接口 */
+export interface FormOptions {
+  intensity: Array<{ label: string; value: any }>;
+  errorStorageType: Array<{ label: string; value: string }>;
+  [key: string]: any;
+}