create-yss-spec 1.0.0

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

@@ -0,0 +1,91 @@
+# yss-mybatis Source Index
+
+Generated: 2026-06-29T16:11:14+00:00
+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.py`. 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/.codex/skills/yss-openapi/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: yss-openapi
+description: Generate OpenAPI JSON from implemented YSS Java controllers, request DTOs, and response DTOs, then refresh frontend Orval API clients. Use only for the smart-doc plus Orval implementation workflow where smart-doc-maven-plugin emits target/openapi/openapi.json and frontend scripts such as generate:api, orval, api-schema-cleanup.cjs, api-flatten-exports.cjs, or format:generated regenerate src/api client code. Do not use this as the unified OpenAPI style guide, design-time API governance, or docs/api/specs Draft review skill.
+---
+
+# YSS OpenAPI
+
+Use this skill to move an already implemented backend controller/DTO contract into the frontend generated API layer.
+
+This is an implementation/generation skill, not the product API design step and not the unified OpenAPI specification governance skill. It generates `openapi.json` from controller methods, request DTOs, response DTOs, annotations, and Java comments; it does not decide naming conventions, resource modeling, error taxonomy, pagination policy, permission semantics, or organization-wide OpenAPI style rules.
+
+For new or changed API contracts, first produce OpenAPI Draft in `docs/api/specs/`, pass engineering baseline, architecture / OpenSpec / Comet design, and Design Review, then Freeze the contract before using this skill to refresh generated clients. When the backend is already the implemented source of truth, use this skill to regenerate and inspect the emitted contract before updating call sites.
+
+## Scope Boundary
+
+Use this skill for:
+
+- Running `smart-doc-maven-plugin` to generate `target/openapi/openapi.json` from implemented backend code.
+- Copying generated `openapi.json` into the frontend OpenAPI input path expected by Orval.
+- Running frontend API client generation and inspecting generated TypeScript changes.
+- Verifying that implemented controllers/DTOs emit the expected OpenAPI shape before call-site updates.
+
+Do not use this skill for:
+
+- Designing a new API contract from PRD, prototype, or architecture inputs.
+- Defining the unified OpenAPI style guide or reusable API governance rules.
+- Reviewing `docs/api/specs/*.yaml` before OpenAPI Freeze.
+- Choosing REST resource boundaries, error models, permission behavior, pagination standards, or contract test policy.
+
+For design-time contract review, use `yss-openapi-draft-review`. For a stronger organization-wide OpenAPI governance baseline, prefer a separate OpenAPI lint/style skill backed by a maintained ruleset tool such as Stoplight Spectral or Redocly CLI, then layer YSS-specific response wrappers, permission, pagination, and security-red-line rules on top.
+
+## Core Flow
+
+1. Locate the backend module that owns smart-doc generation.
+   - In `yss-valuation-outsourced`, this is usually `valuation-outsourced-starter`.
+   - Confirm the module has `smart-doc-maven-plugin` and a config such as `src/main/resources/smart-doc.json`.
+   - The smart-doc config's `outPath` determines the generated directory; in this repo it is `target/openapi`.
+
+2. Generate the backend OpenAPI contract from the repository root.
+   - Use the exact project profile/options the repo expects.
+   - For this repo, run the root `mvnw`; do not add IntelliJ-specific listener or `-Didea.*` parameters:
+
+```bash
+sh mvnw -P SpringCloud.2021.0.9,aliyun-only -DskipTests=true -Dmaven.repo.local=/Users/zhudaoming/.m2/repository com.github.shalousun:smart-doc-maven-plugin:yss-4.0.0:openapi -f pom.xml
+```
+
+3. Find the generated `openapi.json`.
+   - Use `find . -path '*/target/openapi/openapi.json' -print`.
+   - For this repo, the expected source is `valuation-outsourced-starter/target/openapi/openapi.json`.
+   - If multiple files exist, choose the one from the module whose `smart-doc.json` and plugin includes cover the controllers/DTOs being changed.
+
+4. Copy the generated contract into the frontend OpenAPI input.
+   - In `yss-valuation-outsourced`, copy to `valuation-outsourced-frontend/openapi/openapi.json`.
+   - Preserve the frontend path expected by `orval.config.ts`; do not invent a new input path unless the config is updated too.
+
+```bash
+cp valuation-outsourced-starter/target/openapi/openapi.json valuation-outsourced-frontend/openapi/openapi.json
+```
+
+5. Regenerate the frontend API client from the frontend root.
+   - In this repo, run from `valuation-outsourced-frontend`:
+
+```bash
+pnpm generate:api
+```
+
+   - The script expands to:
+
+```bash
+orval && node scripts/api-schema-cleanup.cjs && node scripts/api-flatten-exports.cjs && pnpm format:generated
+```
+
+6. Inspect generated changes before touching call sites.
+   - Check `openapi/openapi.json`.
+   - Check `packages/src/api/generated/**`.
+   - Update handwritten call sites only after seeing the regenerated function names, request body shape, params type, and result type.
+
+## How It Works
+
+- `smart-doc-maven-plugin` scans Java controller methods, request/response DTOs, annotations, comments, and configured dependency source jars. It emits an OpenAPI contract under the configured `outPath`.
+- The backend module is the source of truth for routes, HTTP verbs, DTO field names, enum descriptions, binary responses, multipart inputs, and operation IDs.
+- The frontend `orval.config.ts` reads `openapi/openapi.json` and generates TypeScript schema types plus axios client functions under `packages/src/api/generated`.
+- `scripts/api-schema-cleanup.cjs` changes empty object-like generated schemas from `{ [key: string]: unknown }` to `Record<string, never>` so empty bodies/responses are stricter.
+- `scripts/api-flatten-exports.cjs` converts Orval single-mode `getApi()` factory internals into top-level named exports, then keeps `getApi()` as a compatibility wrapper.
+- `pnpm format:generated` formats generated TypeScript files.
+
+## Repo Checks
+
+Run these discovery commands when the layout is uncertain:
+
+```bash
+rg -n "smart-doc-maven-plugin|configFile|outPath|openapi" -S pom.xml '**/pom.xml' '**/smart-doc.json'
+find . -maxdepth 5 \( -name 'orval.config.*' -o -name 'package.json' -o -name 'api-schema-cleanup.cjs' -o -name 'api-flatten-exports.cjs' \) -print
+```
+
+For `yss-valuation-outsourced`, expect:
+
+- Backend smart-doc config: `valuation-outsourced-starter/src/main/resources/smart-doc.json`
+- Backend generated file: `valuation-outsourced-starter/target/openapi/openapi.json`
+- Frontend Orval input: `valuation-outsourced-frontend/openapi/openapi.json`
+- Frontend Orval config: `valuation-outsourced-frontend/orval.config.ts`
+- Frontend generated code: `valuation-outsourced-frontend/packages/src/api/generated`
+
+## Troubleshooting
+
+- If a controller or DTO is missing, check `smart-doc.json` `packageFilters`, the plugin `<includes>`, module dependencies, and whether source jars are available in the local Maven repository.
+- If schema names look unstable or invalid, check `componentType`; this repo uses `NORMAL` to keep class-like schema names.
+- If binary download or Excel upload contracts are wrong, inspect backend annotations and any OpenAPI normalizer/override code in the repo before manually editing generated JSON.
+- If Orval changes a client function signature, update frontend call sites to match the generated contract. Do not preserve old call shapes by hand-editing generated files.
+- If `api-flatten-exports.cjs` cannot parse `getApi`, inspect the generated `index.ts`; an Orval version or mode change may have changed the output shape.
+- If formatting or generation fails in nested workspaces, run from the frontend root that owns `orval.config.ts` and the `generate:api` script.
+
+## Verification
+
+Prefer targeted checks:
+
+```bash
+test -s valuation-outsourced-starter/target/openapi/openapi.json
+test -s valuation-outsourced-frontend/openapi/openapi.json
+cd valuation-outsourced-frontend && pnpm generate:api
+git diff -- valuation-outsourced-frontend/openapi/openapi.json valuation-outsourced-frontend/packages/src/api/generated
+```
+
+For frontend behavior after API signature changes, run the smallest build or type check that is reliable for the repo. In `yss-valuation-outsourced`, `pnpm exec vite build` from the frontend package workspace has historically been a better signal than broad repo-wide checks when toolchain noise exists.

package/template/.codex/skills/yss-openapi/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS OpenAPI"
+  short_description: "Generate YSS OpenAPI and Orval clients"
+  default_prompt: "Use $yss-openapi to regenerate backend OpenAPI and frontend API clients."

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

@@ -0,0 +1,67 @@
+---
+name: yss-openapi-draft-review
+description: "Use when reviewing a docs/api/specs OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/OpenSpec/Comet design, OpenAPI Freeze, vertical slicing, frontend/backend implementation, or when checking P0 requirement coverage, page action to endpoint mapping, YSS response wrappers, errors, permissions, pagination, optimistic locking, security red lines, 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/api/specs/`; it is not the smart-doc / Orval generation workflow.
+
+## Required Inputs
+
+- OpenAPI Draft under `docs/api/specs/*.yaml`.
+- Calibrated PRD.
+- Interaction spec / prototype review when UI exists.
+- YSS engineering baseline rules, especially `SingleResult<T>`, `MultiResult<T>`, and `PageResult<T>`.
+
+## Review Flow
+
+1. Parse the OpenAPI file and verify YAML, `$ref`, path parameters, and lint when tooling is available.
+2. Build a P0 traceability matrix from PRD functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests.
+3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, permission behavior, state transition, idempotency/concurrency rule, and error codes.
+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 and permission contracts: field-level errors, model-level errors, 403 no-data leakage, disabled reasons, gate failures, and conflict responses.
+7. Check security red lines: authentication/authorization, SQL/DDL draft boundaries, downloads, audit/logging, sensitive field handling, and human-review items.
+8. Output a persistent review artifact under `docs/architecture/` or update the existing one.
+
+## 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 YSS `PageResult<T>` or documented exception.
+- Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, permission, and optimistic locking.
+- Security red lines are unmarked or the Draft exposes execution endpoints for SQL/DDL migration.
+
+## 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
+- <response wrappers, DDD boundary implications, implementation feasibility>
+
+### Security Review
+- <red lines and human-review items>
+
+### Contract Test Checklist
+- <minimum contract tests before OpenAPI Freeze>
+
+### Next Action
+- <return to OpenAPI Draft / enter Engineering Baseline / architecture design>
+```
+
+Prefer `docs/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

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

@@ -0,0 +1,145 @@
+---
+name: yss-openapi-governance
+description: Govern and lint YSS OpenAPI design-time contracts with Spectral or Redocly CLI before OpenAPI Freeze. Use when creating or maintaining organization-level OpenAPI style rules, validating docs/api/specs/*.yaml, defining API naming/error/pagination/permission conventions, adding contract-test checklist rules, or checking generated smart-doc output against YSS API governance. Do not use for smart-doc or Orval generation; use yss-openapi for that implementation workflow.
+---
+
+# YSS OpenAPI Governance
+
+Use this skill to make OpenAPI contracts consistent, lintable, and reviewable before implementation. This is the ruleset and governance layer for `docs/api/specs/*.yaml`; it is not the smart-doc / Orval generation workflow.
+
+## Boundary
+
+Use `yss-openapi-governance` for:
+
+- Defining or applying reusable OpenAPI style rules.
+- Running Spectral or Redocly CLI against `docs/api/specs/*.yaml`.
+- Checking YSS response wrappers, error contracts, pagination, permissions, security red lines, and contract-test seams.
+- Comparing generated `openapi.json` against frozen design rules when backend code is already implemented.
+- Writing or updating governance notes under `docs/api/`, `docs/architecture/`, or the active OpenSpec / Comet design.
+
+Use other skills for:
+
+- `yss-openapi`: generate `target/openapi/openapi.json` from implemented controllers/DTOs and refresh Orval clients.
+- `yss-openapi-draft-review`: perform fail-closed semantic review against PRD, prototype, page actions, P0 coverage, and architecture readiness.
+- `openspec-*` or `comet-*`: formalize behavior changes and implementation tasks after the contract is frozen.
+
+## Preferred Tooling
+
+Prefer Spectral when the repo needs a portable, custom OpenAPI ruleset:
+
+```bash
+npx --yes @stoplight/spectral-cli lint -r .spectral.yaml docs/api/specs/*.yaml
+```
+
+Prefer Redocly CLI when the repo already uses Redocly for lint, bundle, docs, or CI:
+
+```bash
+npx --yes @redocly/cli lint docs/api/specs/*.yaml
+```
+
+If neither tool is configured, do not invent project policy silently. Create or propose a minimal config and mark it as draft until reviewed. Use Spectral as the default baseline for custom YSS rules because its YAML rulesets are easy to version and extend.
+
+## Governance Flow
+
+1. Locate contract inputs.
+   - Check `docs/api/specs/*.yaml` first.
+   - If only generated contracts exist, inspect `*/target/openapi/openapi.json` or frontend `openapi/openapi.json` as implemented evidence, not as design authority.
+   - Confirm whether the task is pre-freeze design governance or post-implementation conformance checking.
+
+2. Detect existing lint configuration.
+   - Look for `.spectral.yaml`, `.spectral.yml`, `redocly.yaml`, `redocly.yml`, `package.json` scripts, or CI jobs.
+   - Reuse the existing toolchain and scripts when present.
+   - If both Spectral and Redocly exist, run the repo's documented CI path first, then targeted local lint.
+
+3. Validate baseline OpenAPI correctness.
+   - Parse YAML/JSON successfully.
+   - Check OpenAPI version, `$ref` resolution, duplicate `operationId`, path parameter coverage, unused schemas, and invalid examples.
+   - Bundle or dereference only when needed for tooling; keep source files maintainable.
+
+4. Apply YSS API governance rules.
+   - Paths are versioned under `/api/v1/` unless a documented exception exists.
+   - Operations use stable `operationId` values suitable for Orval/client generation.
+   - Single-object responses use `SingleResult<T>`.
+   - Non-page list responses use `MultiResult<T>`.
+   - Page responses use `PageResult<T>` and expose the project's standard page request/response fields.
+   - Error responses include a consistent envelope, machine-readable code, human-readable message, and field/model-level validation shape where applicable.
+   - Permission failures avoid data leakage; 403/disabled-action behavior is explicit.
+   - Mutating operations define idempotency, optimistic locking, or conflict semantics when repeated submission or concurrent edits are possible.
+   - Download, upload, export, import, audit, sensitive data, SQL, DDL, authentication, authorization, and encryption surfaces are marked for human/security review when they touch AGENTS.md safety red lines.
+   - Contract-test seams are named for each P0 workflow and critical error path.
+
+5. Produce governance output.
+   - For quick checks, report lint command, pass/fail result, and blocking findings with file paths.
+   - For durable decisions, write or update a Chinese governance artifact under `docs/api/` or `docs/architecture/`.
+   - For active OpenSpec / Comet work, reference the active change and keep rules aligned with `proposal.md`, `design.md`, `tasks.md`, and specs.
+
+## Minimal Spectral Baseline
+
+When the repo lacks a ruleset and the user asks to add one, start with a small `.spectral.yaml` that extends the OpenAPI baseline and encodes only stable YSS rules. Keep controversial product semantics in review checklists until the team agrees.
+
+```yaml
+extends:
+  - spectral:oas
+
+rules:
+  yss-paths-versioned:
+    description: YSS API paths should be versioned under /api/v1.
+    message: "Path '{{property}}' should start with /api/v1/ or document an exception."
+    severity: warn
+    given: "$.paths[*]~"
+    then:
+      function: pattern
+      functionOptions:
+        match: "^/api/v1/"
+
+  yss-operation-id-required:
+    description: Operation IDs must be stable for generated clients and contract tests.
+    severity: error
+    given: "$.paths[*][*]"
+    then:
+      field: operationId
+      function: truthy
+
+  yss-tags-required:
+    description: Operations should be grouped by bounded context or module.
+    severity: warn
+    given: "$.paths[*][*]"
+    then:
+      field: tags
+      function: truthy
+```
+
+Do not overfit Spectral rules when human review is better. For example, "uses `SingleResult<T>` correctly" may require schema convention inspection and YSS context; encode it only if the repo has stable wrapper schema names.
+
+## Blocking Rules
+
+Block OpenAPI Freeze if any of these are true:
+
+- The contract cannot be parsed or linted with the repo's configured tool.
+- A public operation lacks `operationId`, response schema, or error contract.
+- Pagination, list, or single-object response wrappers contradict YSS baseline without a documented exception.
+- Permission, validation, conflict, import/export, upload/download, or sensitive-data behavior is ambiguous.
+- A safety-red-line area is implemented as final contract without `TODO-HUMAN-REVIEW` or equivalent review record.
+- Contract tests cannot be identified for P0 flows and critical error paths.
+
+## Output Contract
+
+```markdown
+### Governance Result
+<Pass / Blocked / Draft Rules Proposed>
+
+### Tooling
+- <Spectral/Redocly command used or proposed>
+
+### Blocking Findings
+- <file:line grounded finding>
+
+### Rule Changes
+- <ruleset/config changes made or proposed>
+
+### YSS Contract Checks
+- <response wrappers, errors, pagination, permissions, security red lines, contract tests>
+
+### Next Action
+- <fix draft / run yss-openapi-draft-review / enter OpenAPI Freeze / compare generated contract>
+```

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS OpenAPI Governance"
+  short_description: "Lint and govern YSS OpenAPI drafts"
+  default_prompt: "Use $yss-openapi-governance to lint and govern a YSS OpenAPI draft before freeze."

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

@@ -0,0 +1,146 @@
+---
+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