create-yss-spec 2.1.15 → 2.2.1

package/template/.claude/skills/yss-page-module-development/references/hooks-map.md

@@ -0,0 +1,11 @@
+# YSS UI Hooks 速查
+
+业务页面生成时优先从 `@yss-ui/hooks` 复用 hooks。
+
+## 高度与异步
+
+- `useTableHeight` 和 `useTreeHeight` 必须绑定真实容器 `ref`，并按页面的分页、工具栏、搜索区选择扣除项。
+- `useLoading` 负责异步 loading 和错误边界；Orval mutator 已提示的错误不得在 `onError` 重复提示。
+- `usePollingTask` 只负责轮询调度，不接管页面的 `loading/data/error`。
+- `useUrlState` 用于把查询条件、分页和 Tab 状态同步到 URL。
+- `useFullscreen` 用于容器、图表或编辑器全屏。

package/template/.claude/skills/yss-page-module-development/references/utils-map.md

@@ -0,0 +1,14 @@
+# YSS UI Utils 速查
+
+业务页面生成时优先从 `@yss-ui/utils` 复用工具函数，避免重复实现。
+
+## 常用工具
+
+- 权限：`getAuthBtns`、`hasAuth`、`getBtnInfo`、`clearAuthInfo`。
+- 复制：`copyToClipboard(text)`。
+- 下载：`downloadFileStream`、`getFileNameFromContentDisposition`、`handleBlobResponse`、`downloadFileFromUrl`。
+- 格式化：`formatMoney`、`formatDate`、`formatFileSize`、`formatDateRelative`。
+- 主题：`applyYssTheme`、`lightenColor`、`darkenColor`。
+- URL：`getUrlData`。
+
+接口导出下载必须读取 `file-export-download` 专项技能，优先复用统一的 Blob 响应处理，不在页面 Hook 重复解析文件名和创建下载链接。

package/template/.claude/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -78,7 +78,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 
 YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空或摘要变化时返回 `blocked`，不能缩小审查范围或合并不同候选的结论。
 
-Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
+Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 
 “然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
 

package/template/.claude/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -9,6 +9,10 @@ implementation_path_policy:
   forbidden_roots: [app/backend/, app/frontend/]
   container_roots_are_projects: false
   external_repository_uses_native_root: true
+  policies: [harness-apps-multi-project, external-repository-native, git-submodule-harness-apps]
+  git_submodule:
+    repository_scope: git-submodule
+    layout_policy: git-submodule-harness-apps
 
 review_verification:
   low_medium_combined_independent_executor: true
@@ -84,6 +88,9 @@ workflow_execution_result:
       removal_target: schema_version_2
   result_values: [completed, blocked, needs-human, failed]
   required: [result_schema, work_unit, workflow_reference, result, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  unavailable_skill:
+    required: [skill, provider, fallback, resolution]
+    blocking_result: blocked
   blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
   completed_requires_empty: [new_impacts, stale_candidates]
   completed_requires_non_empty: [evidence_refs]
@@ -126,43 +133,101 @@ lifecycle_native_entries:
 work_unit_routes:
   work-unit.discovery-opportunity:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [competitive-intelligence, research]
     skills: [competitive-intelligence, research]
     route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: research, no_external_fact: yss-product-lifecycle}
+    applies_when: opportunity_or_external_fact_requires_validation
+    not_applicable_reason: no_external_fact
   work-unit.discovery-requirements:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [grilling, domain-modeling]
     skills: [grilling, domain-modeling]
+    applies_when: requirements_or_domain_boundary_unclear
+    not_applicable_reason: requirements_already_confirmed
   work-unit.spec-synthesis:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [domain-modeling]
     compatibility: {source: mattpocock/skills, skill: to-spec, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
     skills: [domain-modeling]
     human_gate: spec-baseline
+    applies_when: new_feature_or_behavior_change
+    not_applicable_reason: existing_frozen_spec_is_current
   work-unit.prototype-design:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
-    skills: [yss-design-system, yss-prototype-stage, yss-antd-design, product-design:index]
+    primary_skill: yss-prototype-stage
+    supporting_skills: [prototype-review, yss-design-system, yss-antd-design, product-design:index]
+    skills: [prototype-review, yss-design-system, yss-prototype-stage, yss-antd-design, product-design:index]
     human_gate: prototype-confirmation
+    applies_when: product_design_impact
+    not_applicable_reason: no_ui_or_product_design_impact
   work-unit.technical-analysis:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-router
+    supporting_skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding]
     skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding, yss-router]
     human_gate: openapi-freeze_if_api_impact
+    applies_when: technical_or_contract_impact
+    not_applicable_reason: no_technical_or_contract_impact
   work-unit.ticket-decomposition:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [yss-router]
     compatibility: {source: mattpocock/skills, skill: to-tickets, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
     skills: [yss-router]
+    applies_when: frozen_scope_ready_for_slicing
+    not_applicable_reason: contract_or_scope_not_frozen
   work-unit.slice-implementation:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-router
+    supporting_skills: [tdd, yss-ui, yss-page-module-development]
     compatibility: {source: mattpocock/skills, skill: implement, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
     skills: [tdd, yss-router, yss-ui, yss-page-module-development]
+    frontend_route:
+      primary_skill: yss-ui
+      page_orchestration_skill: yss-page-module-development
+      conditional_skills:
+        api_impact: [yss-api-integration]
+        formily_impact: [yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow]
+        table_impact: [ytable-usage, yedit-table-usage]
+        tree_impact: [ytree-usage]
+        height_impact: [yss-use-table-height, yss-use-tree-height]
+        export_impact: [file-export-download]
+        theme_impact: [theme-token-usage]
+      not_applicable_reasons:
+        api_impact: no_api_impact
+        formily_impact: no_formily_impact
+        table_impact: no_table_impact
+        tree_impact: no_tree_impact
+        height_impact: no_height_impact
+        export_impact: no_export_impact
+        theme_impact: no_theme_impact
+    applies_when: ready_for_agent
+    not_applicable_reason: slice_contract_not_approved
   work-unit.frontend-implementation-verification:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-ui
+    supporting_skills: [yss-design-system, code-review]
     skills: [yss-ui, yss-design-system, code-review]
     applies_when: ui_impact
+    not_applicable_reason: no_ui_impact
   work-unit.code-review:
     native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
+    primary_skill: code-review
+    supporting_skills: []
     skills: [code-review]
+    applies_when: implementation_candidate_exists
+    not_applicable_reason: no_implementation_candidate
   work-unit.release-and-retrospective:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: []
     skills: [yss-product-lifecycle]
     human_gate: merge_or_release
+    applies_when: release_or_stage_completion
+    not_applicable_reason: work_not_ready_for_release
 
 compatibility_flow_preconditions:
   to-spec:
@@ -260,6 +325,26 @@ git_authorization:
     authorized_value: true
     non_empty: [push_scope, push_authorization_ref]
     unauthorized_action: checkpoint-only
+  git_submodule:
+    applies_when: repository_scope=git-submodule
+    forbid_commit_on_detached_head: true
+    commit_order: [submodule-repositories, superproject-gitlink]
+    push_order: [submodule-repositories, superproject-gitlink]
+    push_recurse_submodules: check
+    empty_gitlink_scaffold: blocked
+    treat_empty_gitlink_as_regular_dir: blocked
+    treat_detached_head_as_regular_dir: blocked
+    force_overlay_mount: blocked
+    write_inside_detached_head: blocked
+    require_git_entry_mode: "160000"
+    working_tree_declared_scope_must_match: true
+    copy_source_into_harness: forbidden
+    clone_requires_recurse_submodules: true
+    delivery_order_must_include: superproject-gitlink-update
+    nested_authorization: per-repository
+    inspect_working_tree_writable: explicit-boolean
+    empty_gitlink_writable: false
+    force_overlay_regular_dir_path: blocked
 
 seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan, target_version_or_release_date]
 

package/template/.claude/skills/yss-product-lifecycle/references/orchestration.md

@@ -69,6 +69,8 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 实现授权、`orchestrate`/`resume` 的有界写入、当前分支和 Git checkpoint 都不蕴含 commit 或 push 授权。执行 commit 前必须同时取得 `commit_authorized=true`、非空 `commit_scope` 和 `commit_authorization_ref`；执行 push 前必须同时取得 `push_authorized=true`、非空 `push_scope` 和 `push_authorization_ref`。任一缺失时只记录 checkpoint 判断并保持 Git 状态不变；负责人要求、时间压力、测试通过或“本地 commit 可逆”都不能补足用户授权。
 
+`repository_scope: git-submodule` 时授权按仓分别计算：禁止在 detached HEAD 提交；commit / push 顺序必须先子仓、再父仓 gitlink（`superproject-gitlink-update`）；父仓 push 使用 `git push --recurse-submodules=check`。空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录脚手架，也不得把实现源码复制进 Harness。登记字段必须能与 `harness-apps` / `external-repository` 区分，并对照工作树 gitlink。
+
 ## 必须暂停
 
 - Spec baseline、需求冻结、原型确认、OpenAPI Freeze 或 Architecture Review 等普通门禁等待人工裁决。

package/template/.claude/skills/yss-product-lifecycle/references/state-model.md

@@ -59,7 +59,7 @@ AND UI 影响切片的前端实现还原计划已通过 schema 校验、`templat
 
 进入代码审查时保存 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest` 及 Spec、Ticket、合同、Checklist、YSS Execution Result 引用。`worktree` 候选必须一次捕获 committed、staged、unstaged 和 untracked 文件；manifest 的按模式必填字段以及 `yss-worktree-candidate-v1`（raw path、uint64 big-endian 长度、tracked/untracked record、symlink 和不支持条目）以 `orchestration-contract.yaml.review_input` 为唯一执行定义。两个 Reviewer 消费同一不可变快照；返回后或完成 checkpoint 摘要变化则返回 `blocked` 并重新审查。不新增生命周期状态，只把该清单作为审查证据。
 
-Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。
+Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。`git-submodule` 另保存每仓授权、`checkout_state` 和先子后父顺序；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点时不得当成普通目录 commit / 脚手架。
 
 ## 状态块
 

package/template/.claude/skills/yss-router/SKILL.md

@@ -29,7 +29,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - Repository/数据模型影响缺少数据架构时，不得路由持久化实现。
 - API 变化必须回到生命周期 Draft/Review/Freeze；半成品 backend 不得冒充稳定 source of truth。
 - 后端端到端切片必须包含 Application；对象/POJO 影响按契约自动补 `mapstruct`、`lombok`、`alibaba-java-code-style`。
-- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。
+- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
 - 原型确认后若 backend `scaffold_status=required`，先由本 Router 按 `scaffold_contract_schema` 编译 `yss-ddd-scaffold-generator` 的 `controlled-generation` 工作单元合同 draft；合同必须带 `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据和验证命令。经生命周期编排器批准并持久化后才能运行生成器，再由受控工作单元实际执行固定的 `./mvnw validate`、`./mvnw test`、`./mvnw package` 并记录逐条结果，随后加载 `yss-backend-scaffold-parent` 并重新编译业务合同；脚手架不承载业务行为。

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

@@ -9,7 +9,7 @@ Use this reference when multiple YSS skills seem applicable.
 - `yss-page-module-development`: Page/module workflow. Use for creating or reorganizing a page folder, deciding structure, and assembling page, hooks, schemas, and blocks.
 - `yss-components`: Component layout and visual/page composition rules. Use for YTable/YTree/YssFormily/YSplitPane usage details.
 - `yss-hook`: Request, pagination, parameter, tree-selection, and response-mapping logic in `views/**/hooks/useXxx.ts`.
-- `api-integration`: Orval-generated API client imports, request/response mapping, `useRequest` calling patterns, submit/list/detail flows.
+- `yss-api-integration`: Orval-generated API client imports, request/response mapping, `useRequest` calling patterns, submit/list/detail flows.
 - `yss-formily`: Hand-written YssFormily schema implementation and form behavior.
 - `yss-formily-schema-generator`: Generate YssFormily schema from requirements, screenshots, mockups, Figma, or natural-language field descriptions.
 - `yss-use-table-height`: Only table available-height calculation and required container/pagination/toolbar wiring.

package/template/.claude/skills/yss-router/references/router-contract.yaml

@@ -4,6 +4,10 @@ forbidden_statuses: [approved, ready-for-agent, completed]
 skill_aliases:
   api-integration: yss-api-integration
   microapp-commit: yss-microapp-commit
+  page-module-development: yss-page-module-development
+  yss-ui-business-page-generation: yss-page-module-development
+  use-table-height: yss-use-table-height
+  use-tree-height: yss-use-tree-height
 implementation_path_policy:
   applies_to: harness-resident-runtime-code
   project_roots:
@@ -15,10 +19,30 @@ implementation_path_policy:
   forbidden_roots:
     - app/backend/
     - app/frontend/
+  policies:
+    - harness-apps-multi-project
+    - external-repository-native
+    - git-submodule-harness-apps
+  git_submodule:
+    repository_scope: git-submodule
+    layout_policy: git-submodule-harness-apps
+    git_entry_mode: "160000"
+    empty_gitlink_scaffold: blocked
+    treat_empty_gitlink_as_regular_dir: blocked
+    treat_detached_head_as_regular_dir: blocked
+    force_overlay_mount: blocked
+    write_inside_detached_head: blocked
+    copy_source_into_harness: forbidden
+    inspect_working_tree_writable: explicit-boolean
+    empty_gitlink_writable: false
+    force_overlay_regular_dir_path: blocked
   rules:
     - "Harness 内每个运行时工程必须位于具体 project 目录，不能直接写入 apps/backend/ 或 apps/frontend/。"
     - "app/backend/、app/frontend/ 及其子路径不是兼容别名，必须阻断。"
     - "外部实现仓库使用登记的真实项目根路径，不用 Harness 容器路径冒充。"
+    - "git-submodule 挂载路径使用 git-submodule-harness-apps，必须是 gitlink 且分别登记；不得登记为 harness-apps。"
+    - "空 gitlink、detached HEAD、--force 覆盖挂载点不得当成普通目录；也不得在 detached HEAD 工作树内当普通目录写入。"
+    - "inspectWorkingTreeScope 必须返回 { writable }；空 gitlink / detached HEAD 的 writable 必为 false；--force 覆盖 gitlink 不得走普通目录覆盖路径。"
 subcontract_statuses: [required, not-applicable]
 
 readiness:
@@ -149,8 +173,8 @@ dependency_closure:
     when_components: [yss-components]
     when_hooks: [yss-hook]
     when_form: [yss-formily]
-    when_api: [api-integration]
-  api-integration:
+    when_api: [yss-api-integration]
+  yss-api-integration:
     when_regeneration: [yss-openapi-governance]
 
 component_impact_values:

package/template/.claude/skills/yss-router/references/slice-implementation-contract.md

@@ -37,7 +37,7 @@ slice_contract:
         reason:
   common:
     impacted_areas: []
-    implementation_path_policy: harness-apps-multi-project # or external-repository-native
+    implementation_path_policy: harness-apps-multi-project # or external-repository-native | git-submodule-harness-apps
     project_roots: []
     required_skills: []
     optional_skills: []

package/template/.claude/skills/yss-ui/SKILL.md

@@ -59,7 +59,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 | Formily schema、联动、校验、详情态 | `yss-formily` |
 | 表格高度 | `yss-use-table-height` |
 | 树高度 | `yss-use-tree-height` |
-| Orval、API、useRequest 接入 | `api-integration` |
+| Orval、API、useRequest 接入 | `yss-api-integration` |
 | 视觉、token、响应式体验 | `yss-design-system` |
 
 不得引用不存在的复数 Hook skill 名称。

package/template/.claude/skills/yss-use-table-height/SKILL.md

@@ -5,6 +5,15 @@ description: Use when working with YTable that needs responsive height, paginati
 
 # useTableHeight 表格高度计算 Hook
 
+本目录是表格高度的 canonical 技能；历史名称 `use-table-height` 仅通过注册表和 Router alias 解析。
+
+## YSS canonical execution rules
+
+- 使用真实签名 `useTableHeight(containerRef, options)`，结果解构为 `tableHeight`、`isReady` 和 `recalculateHeight`。
+- `YTable` 必须绑定 `:height="tableHeight"`；不要只绑定 `max-height`，也不要用固定魔法高度替代 Hook。
+- `pageable`、工具栏和 `YEditTable` 添加按钮分别对应 `withPagination`、`withToolbar` 和 `withAddButton`。
+- 容器使用 `flex: 1; min-height: 0; overflow: hidden`，避免观察由表格内容反向撑开的直属容器。
+
 ## Authoritative Docs And Boundary
 
 - YSS UI hooks documentation: `http://192.168.164.27:3200/hooks`

package/template/.claude/skills/yss-use-tree-height/SKILL.md

@@ -5,6 +5,15 @@ description: Use when working with YTree that needs responsive height, virtual s
 
 # useTreeHeight 树组件高度计算 Hook
 
+本目录是树高度的 canonical 技能；历史名称 `use-tree-height` 仅通过注册表和 Router alias 解析。
+
+## YSS canonical execution rules
+
+- 使用真实签名 `useTreeHeight(containerRef, options)`，结果绑定到 `YTree` 的 `:height`。
+- `filterable` 时配置 `extraOffset: YTREE_SEARCH_HEIGHT`；不得重复扣减或添加无依据偏移。
+- 容器使用 `flex: 1; min-height: 0; overflow: hidden`，隐藏态切换后在可见的 `nextTick` 中调用 `recalculateHeight()`。
+- 不因节点数量少而强制开启虚拟滚动；按实际可见节点阈值决定是否裁剪 DOM。
+
 ## Authoritative Docs And Boundary
 
 - YSS UI hooks documentation: `http://192.168.164.27:3200/hooks`

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

@@ -0,0 +1,251 @@
+---
+name: ytable-usage
+description: 指导 YSS UI 业务列表页、CRUD 表格、远程分页、操作列、气泡确认、列筛选、字典翻译、行拖拽、工具栏和自定义插槽正确使用 @yss-ui/components 的 YTable；当需要配置 YTableColumn、YTableActionConfig、pagination、filter-change 或表格实例方法时使用。
+---
+
+# YTable 使用
+
+## 触发条件
+
+- 生成或修改业务列表、CRUD 表格、远程分页、操作列、列筛选、工具栏或行拖拽。
+- 需要配置 `YTableColumn`、`YTableActionConfig`、分页状态或表格实例方法。
+
+## 不适用场景
+
+- 可编辑表格是核心需求：使用 `../yedit-table-usage/SKILL.md`。
+- 页面只有短小静态数据且不需要表格交互。
+
+## 实施流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YTable` 的 Props、Events、Slots、Types 与实例方法；需要远程分页、筛选、操作列、拖拽或工具栏时，再用 `get_demo` 获取对应官方 Demo。
+2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+3. 把远程数据、`loading`、分页映射、API 调用和事件处理放入 Hook；把列定义和纯配置放入 `constant.ts`。
+4. 在模板中组合 `data/columns/loading/pagination`，并根据真实开启的工具栏和分页配置高度 Hook。
+5. 完成后核对删除确认、远程筛选、分页字段映射和 API 错误处理边界。
+
+## 硬约束（禁止/必须）
+
+- 必须从 `@yss-ui/components` 导入 `YTable`、`YTableColumn`、`YTableActionConfig` 等真实导出，不使用 `a-table` 实现业务主表格。
+- 远程分页状态使用 `current/pageSize/total/remote`，显式设置 `remote: true`；后端 `pageIndex/pageSize/totalCount` 只在 Hook 中映射。
+- 开启内置分页时传 `pageable`，受控更新使用 `v-model:pagination`，请求时机使用 `@page-change="handlePageChange"`。
+- `page-change` 事件参数固定为 `{ current: number, pageSize: number }`；回调必须读取 `current`，禁止写成组件不会派发的 `currentPage`。
+- YTable 没有 `request` 或 `searchParams` Props；远程查询由业务 Hook 管理。`refresh()` 是真实实例方法，内部调用 vxe-table `updateData()` 刷新当前表格数据，不等于重新调用后端接口。
+- 行键使用 `:row-config="{ keyField: 'id', useKey: true }"`，不臆造 `row-key` Prop。
+- 新增、导入、批量操作等主按钮直接放入 `#toolbar-right` 或 `#toolbar-left` 插槽即可自动渲染工具栏；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
+- 删除、启停、发布等危险操作使用 `actionConfig.buttons[].isConfirm = true`，不默认使用 `Modal.confirm`。
+- 列配置超过 10 行时放入 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。
+- 远程筛选必须提供稳定 `filters`，设置 `filterMethod: () => true` 禁用本地二次过滤，并监听 `filter-change`。
+- 自适应滚动列表绑定 `:height="tableHeight"`；`pageable`、工具栏分别对应 `withPagination: true`、`withToolbar: true`。纯短表不强制引入高度 Hook。
+- `mutator.ts` 已对网络错误和 `success === false` 统一 `message.error` 并 reject。API Hook 不再检查 `success === false`，不在 `else/catch` 重复 `message.error`；用 `finally` 恢复 loading，让异常继续中断流程。
+
+## 标准代码骨架
+
+```typescript
+import type { YTableActionConfig, YTableColumn } from '@yss-ui/components';
+
+/** 列表行数据。 */
+export interface ItemRow {
+  id: string;
+  name: string;
+  status: string;
+}
+
+/** 状态字典。 */
+export const STATUS_OPTIONS = [
+  { label: '启用', value: '1' },
+  { label: '停用', value: '0' },
+];
+
+/** 列表固定列配置。 */
+export const TABLE_COLUMNS: YTableColumn[] = [
+  { type: 'seq', title: '序号', width: 70 },
+  { field: 'name', title: '名称', minWidth: 180 },
+  { field: 'status', title: '状态', width: 120, isTransform: true },
+  { type: 'action', title: '操作', width: 180 },
+];
+
+/** 按组件 Hook 提供的回调创建操作列配置。 */
+export const createActionConfig = (handlers: {
+  onEdit: (row: ItemRow) => void;
+  onDelete: (row: ItemRow) => Promise<void>;
+}): YTableActionConfig => ({
+  width: 180,
+  fixed: 'right',
+  buttons: [
+    { value: 'edit', label: '编辑', type: 'link', click: ({ row }) => handlers.onEdit(row) },
+    {
+      value: 'delete',
+      label: '删除',
+      type: 'link',
+      isConfirm: true,
+      confirmProps: { title: '确认删除该数据吗？', okText: '确定', cancelText: '取消' },
+      click: ({ row }) => handlers.onDelete(row),
+    },
+  ],
+});
+```
+
+## 远程分页 Hook 关键模式
+
+```typescript
+import { ref } from 'vue';
+import type { YTablePagination } from '@yss-ui/components';
+import type { ItemRow } from '../constant';
+
+/** 列表 API 依赖，由当前项目的 Orval 函数适配。 */
+export interface ItemListApi {
+  queryPage: (params: { pageIndex: number; pageSize: number }) => Promise<{
+    list?: ItemRow[];
+    totalCount?: number;
+  }>;
+  deleteItem: (params: { id: string }) => Promise<unknown>;
+}
+
+/** 管理 YTable 远程分页和删除刷新。 */
+export const useItemList = (api: ItemListApi) => {
+  const dataList = ref<ItemRow[]>([]);
+  const loading = ref(false);
+  const pagination = ref<YTablePagination>({ current: 1, pageSize: 20, total: 0, remote: true });
+
+  /** 查询当前页；错误提示由 mutator 统一处理。 */
+  const loadList = async () => {
+    loading.value = true;
+    try {
+      const result = await api.queryPage({
+        pageIndex: pagination.value.current,
+        pageSize: pagination.value.pageSize,
+      });
+      dataList.value = result.list ?? [];
+      pagination.value = { ...pagination.value, total: result.totalCount ?? 0 };
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  /** 同步 YTable 分页状态并重新查询。 */
+  const handlePageChange = async ({ current, pageSize }: { current: number; pageSize: number }) => {
+    pagination.value = { ...pagination.value, current, pageSize };
+    await loadList();
+  };
+
+  /** 删除后刷新列表；不重复弹出 API 错误。 */
+  const handleDelete = async (row: ItemRow) => {
+    await api.deleteItem({ id: row.id });
+    await loadList();
+  };
+
+  return { dataList, loading, pagination, loadList, handlePageChange, handleDelete };
+};
+```
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { YButton, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { createActionConfig, STATUS_OPTIONS, TABLE_COLUMNS, type ItemRow } from './constant';
+import { useItemList, type ItemListApi } from './hooks/useItemList';
+
+/** 列表实例的 API 依赖。 */
+interface Props {
+  api: ItemListApi;
+}
+
+const props = defineProps<Props>();
+const emit = defineEmits<{
+  create: [];
+  edit: [row: ItemRow];
+}>();
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
+const { dataList, loading, pagination, loadList, handlePageChange, handleDelete } = useItemList(props.api);
+const actionConfig = createActionConfig({
+  onEdit: row => emit('edit', row),
+  onDelete: handleDelete,
+});
+
+onMounted(loadList);
+</script>
+
+<template>
+  <div ref="tableAreaRef" class="table-area">
+    <YTable
+      :data="dataList"
+      :columns="TABLE_COLUMNS"
+      :action-config="actionConfig"
+      :loading="loading"
+      :options-map="{ status: STATUS_OPTIONS }"
+      :row-config="{ keyField: 'id', useKey: true }"
+      :height="tableHeight"
+      pageable
+      v-model:pagination="pagination"
+      @page-change="handlePageChange"
+    >
+      <template #toolbar-right>
+        <YButton type="primary" @click="emit('create')">新增</YButton>
+      </template>
+    </YTable>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.table-area {
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+```
+
+## 表格多选与批量操作标准模式
+
+当业务需要 Checkbox 多选与批量操作（如批量删除、批量导出、批量启用）时，遵循以下规范：
+
+1. **列配置**：首列必须声明 `{ type: 'checkbox', width: 50, fixed: 'left', align: 'center' }`。
+2. **行唯一键**：必须显式指定 `:row-config="{ keyField: 'id', useKey: true }"`（`keyField` 与业务主键如 `userCode` 对齐）。
+3. **受控双向绑定**：推荐优先使用 `v-model:selected-row-keys="selectedRowKeys"` 或 `v-model:selected-rows="selectedRows"`，或者统一监听 `@selection-change`。
+4. **批量操作按钮**：放在 `#toolbar-right`，并配置 `:disabled="selectedRowKeys.length === 0"`。
+5. **清空选中态**：批量操作成功后，直接重置 `selectedRowKeys.value = []` 或调用 `tableRef.value.clearSelection()`。
+
+```vue
+<YTable
+  ref="tableRef"
+  v-model:selected-row-keys="selectedRowKeys"
+  :row-config="{ keyField: 'id', useKey: true }"
+  :data="dataList"
+  :columns="TABLE_COLUMNS"
+  pageable
+  v-model:pagination="pagination"
+  @page-change="handlePageChange"
+>
+  <template #toolbar-right>
+    <YButton :disabled="selectedRowKeys.length === 0" @click="handleBatchDelete">批量删除</YButton>
+  </template>
+</YTable>
+```
+
+## 插槽与实例边界
+
+- 优先使用 kebab-case：单元格 `#<field>`、表头 `#<field>-header`、筛选 `#<field>-filter`、工具栏 `#toolbar-left/#toolbar-right`、展开行 `#expand-row`、分组表头 `#group-header`、更多图标 `#action-more-icon`。
+- `getTableInstance()`、`refresh()`、`recalculate()`、`clearSelection()`、`getSelectedRows()`、`getSelectedRowKeys()`、`setSelection()`、`getPaginationInstance()` 是真实暴露方法；只在对应语义下使用。
+
+## 交付检查清单
+
+- [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
+- [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
+- [ ] 批量操作成功后已重置 `selectedRowKeys` 并调用 `tableRef.clearSelection()`。
+- [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
+- [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。
+- [ ] API Hook 没有 `success === false` 分支或重复 `message.error`。
+
+## 失败兜底策略
+
+- 分页字段混乱时，在 Hook 中分离 YTable 状态和后端参数，不直接把 `pageIndex/totalCount` 绑到组件。
+- 操作过多时使用 `displayLimit` 和更多菜单；远程刷新失效时回到业务 `loadList()`，不把实例 `refresh()` 当成接口请求。
+- API 失败后只在 `finally` 恢复本地 loading，让 mutator 的 reject 继续中断删除后刷新等后续流程。
+