persagy-vant 0.0.39 → 0.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "persagy-vant",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Lightweight Mobile UI Components built on Vue",
   "main": "lib/vant.cjs.js",
   "module": "es/index.mjs",

package/skills/use-persagy-vant/SKILL.md

@@ -11,12 +11,13 @@ description: 使用 Persagy Vant 为 Vue 3 移动端业务页面规划、实现
 
 1. 阅读 `references/reuse-policy.md`，确认复用边界与禁止项。
 2. 阅读 `references/design-interaction-baseline.md` 与 `references/public-style-system.md`，将其中适用的设计、状态和反馈规则落实到页面；如与产品需求冲突，以明确的产品需求为准并说明差异。
-3. 阅读 `references/business-component-catalog.md`，按用户任务先确定业务组件；再从 `references/component-catalog.md` 补齐基础组件。
-4. 按 `references/component-documentation.md` 的查阅流程读取每个被选中组件的 README 和 demo：在组件库仓库中使用 `packages/persagy-mobile/src/<component>/README.zh-CN.md`，在业务项目中使用 `node_modules/persagy-vant/es/<component>/README.zh-CN.md`。涉及视觉、插槽或类型扩展时，同时查阅 `var.less`、类型定义和 demo；API、事件、插槽和导入方式均以这些资料为准。
-5. 阅读 `references/component-variant-selection.md`，针对每个可见或可交互 UI 单元，从该组件模拟器/README 的示例中选定最贴近当前页面的具体样式与变量组合；不得仅按组件名称套用基础示例。
-6. 按 `references/page-recipes.md` 组合页面，补齐加载、空数据、错误、禁用和提交中状态。用户要求“审查并优化当前页面”或语义等同的 UI 优化时，默认按 `references/reuse-policy.md` 的非侵入式优化规则执行：不得改变已有接口、请求/响应数据、字段映射、数据内容或业务事件。
-7. 无论是单个页面审查/优化，还是从 0 到 1 的页面规划与实现，页面组件覆盖率均必须不低于 `90%`。将组件复用清单中的组件职责视为页面覆盖基线：默认保持模拟器示例与组件原样，只使用其既有 Props、事件、插槽和样式变体完成搭建；未经产品经理明确提出具体样式调整，不得改动 Less/CSS 变量、覆盖组件视觉或自行定制组件样式。
-8. 输出或提交前，按 `references/reuse-policy.md`、`references/design-interaction-baseline.md` 和 `references/component-variant-selection.md` 完成自查，并附上“组件复用清单”“组件变体选型”“规范落实项”“业务与数据兼容核查”和“组件覆盖率”。组件复用清单必须按 `references/component-documentation.md` 使用官网中文名称和可点击的组件展示链接；未达到 `90%` 时，必须记录覆盖率缺口并反馈给产品经理，说明需要优化的组件变量或建议新增的组件，供其反馈组件库维护方；未经产品经理明确确认例外，不得作为合规页面交付。
+3. 阅读 `references/element-component-matching.md`，先完整盘点当前页面或需求中的可见元素、字段、状态、交互和层级，再建立元素到组件的匹配；不得先编码或只凭单个关键词选组件。
+4. 阅读 `references/business-component-catalog.md`，按元素盘点结果先确定业务组件；再从 `references/component-catalog.md` 补齐基础组件。
+5. 按 `references/component-documentation.md` 的查阅流程读取每个被选中组件的 README 和 demo：在组件库仓库中使用 `packages/persagy-mobile/src/<component>/README.zh-CN.md`，在业务项目中使用 `node_modules/persagy-vant/es/<component>/README.zh-CN.md`。涉及视觉、插槽或类型扩展时，同时查阅 `var.less`、类型定义和 demo；API、事件、插槽和导入方式均以这些资料为准。
+6. 阅读 `references/component-variant-selection.md`，针对每个可见或可交互 UI 单元，从该组件模拟器/README 的示例中选定最贴近当前页面的具体样式与变量组合；不得仅按组件名称套用基础示例。
+7. 按 `references/page-recipes.md` 组合页面，补齐加载、空数据、错误、禁用和提交中状态。用户要求“审查并优化当前页面”或语义等同的 UI 优化时，默认按 `references/reuse-policy.md` 的非侵入式优化规则执行：不得改变已有接口、请求/响应数据、字段映射、数据内容或业务事件。
+8. 无论是单个页面审查/优化，还是从 0 到 1 的页面规划与实现，页面组件覆盖率均必须不低于 `90%`。将组件复用清单中的组件职责视为页面覆盖基线：默认保持模拟器示例与组件原样，只使用其既有 Props、事件、插槽和样式变体完成搭建；未经产品经理明确提出具体样式调整，不得改动 Less/CSS 变量、覆盖组件视觉或自行定制组件样式。
+9. 输出或提交前，按 `references/reuse-policy.md`、`references/design-interaction-baseline.md`、`references/element-component-matching.md` 和 `references/component-variant-selection.md` 完成自查，并附上“元素-组件匹配”“组件复用清单”“组件变体选型”“规范落实项”“业务与数据兼容核查”和“组件覆盖率”。组件复用清单必须按 `references/component-documentation.md` 使用官网中文名称和可点击的组件展示链接；未达到 `90%` 时，必须记录覆盖率缺口并反馈给产品经理，说明需要优化的组件变量或建议新增的组件，供其反馈组件库维护方；未经产品经理明确确认例外，不得作为合规页面交付。
 
 ## 组件缺口
 

package/skills/use-persagy-vant/references/component-catalog.md

@@ -6,7 +6,7 @@
 
 - `background`：含白色卡片的页面优先使用此容器；一级页面使用 `theme="default"`，其他层级页面使用 `theme="gray"`。仅在没有白色卡片且无明确背景设计时使用 `--van-gray-1`。
 - `nav-bar`、`tabbar`、`tab`、`tabs`、`sidebar`：页面与分区导航。标签较多时优先使用 `tabs` 的滚动或更多面板能力；筛选型分区选择 `type="filter"`。
-- `cell`、`cell-group`、`row`、`col`、`space`、`divider`：信息布局与分组；动态面板的页面触发器优先使用 `cell` 的【单元格】右图标样式（`right-icon="arrow"` + `click`），当前结果使用 `value` 或 `note` 回显。白色卡片内的最后一个可见 `cell` 或 `field` 设置 `border="false"`，不保留末尾分割线。
+- `cell`、`cell-group`、`row`、`col`、`space`、`divider`：信息布局与分组；动态面板的页面触发器优先使用 `cell` 的【单元格】右图标样式（`right-icon="arrow"` + `click`），当前结果使用 `value` 或 `note` 回显。白色卡片内有多个独立信息模块时，模块优先使用 `cell` 公开 `background` 能力承接 `--van-gradient-gray` 或 `--van-gradient-blue` 二次卡片背景；其他容器只使用 `gradient-gray` / `gradient-blue` 公共工具类。白色卡片内的最后一个可见 `cell` 或 `field` 设置 `border="false"`，不保留末尾分割线。
 - `empty`、`loading`、`skeleton`、`overlay`、`pull-refresh`、`list`、`pagination`：加载、空态、刷新与列表分页；页面首次进入使用 `loading` 的 `type="illustration"`，并以纯色背景承载过渡。
 - `collapse-toggle`：卡片内容区的展开/收起触发器；需要两侧分割线时使用其公开 `divider` 能力，不要自绘“查看更多/收起”控件。
 - `bottom-action-bar`、`action-bar`、`submit-bar`：固定操作区；不要自行实现 fixed footer。
@@ -23,11 +23,11 @@
 ## 内容与反馈
 
 - `label`：字段名称与回显值的首选组件，覆盖默认、加粗、链接、标签、图片视频及纵向布局；需要字段展示时优先使用，除录入、选择入口等应使用 `field` 或 `cell` 的场景外，不要为同类字段自行拼接样式。左侧标签文本尽量自带冒号，保证名称和值之间的统一阅读间距；按字段内容选择其公开展示类型。
-- `info-card`：多种类型字段的白色信息卡片，可接收字段数组或插槽，并提供更多字段、固定分割线与展开收起能力；字段类型较多时优先使用，内部字段使用 `label` 呈现。固定分割线只用于字段分组，不作为卡片末尾分割线。
+- `info-card`：多种类型字段的白色信息卡片，可接收字段数组或插槽，并提供更多字段、固定分割线与展开收起能力；字段类型较多时优先使用，内部字段使用 `label` 呈现。任务/作业摘要中主标题、状态、设备/位置与标签属于同一对象时，可用 `title`、字段数组和下方 `#default` 插槽组合 `label` 与 `cell` 的「换行标签栏」；不手写同类卡片。固定分割线只用于字段分组，不作为卡片末尾分割线。
 - `blue-mark`、`blue-mark-header`：一级标题和业务标识；页面一级标题统一使用放在白色卡片外层的 `blue-mark-header`，需要必填标识、右侧操作或展开收起时使用其公开能力，不手写同类标题栏。
 - `title-bar`：白色卡片内的二级标题统一使用默认样式（不使用 `mini`）；用 `show-description`、`show-icon`、`show-arrow` 和 `expandable`/`v-model` 组合备注、图标、箭头和展开内容。视觉调整只使用其 `--van-title-bar-*` 公开变量。
 - `card`、`tag`、`badge`、`notice-bar`、`image`、`icon`：内容展示与状态标识。
-- `popup`、`action-sheet`、`share-sheet`、`popover`：动作选择与自定义容器；动态面板必须先检查 `content-panel`、`form-panel`、`radio-panel`、`checkbox-panel`。四者不适用且自定义内容较多时，使用 `action-sheet` 的【动作面板】自定义面板样式，以 `title` 和默认插槽承载内容；仅少量轻量内容才使用 `popup`。
+- `popup`、`action-sheet`、`share-sheet`、`popover`：动作选择与自定义容器；动态面板必须先检查 `content-panel`、`form-panel`、`radio-panel`、`checkbox-panel`。仅单选直接使用 `radio-panel`，仅复选直接使用 `checkbox-panel`；它们无法覆盖且当前上下文需要组合标题、复杂选择项、字段、筛选或批量操作时，使用 `action-sheet` 的【动作面板】模拟器「自定义面板」（`v-model:show` + 标题/关闭公开能力 + 默认插槽）。插槽内只在该示例已有的白色卡片内容结构中组合现有组件；仅少量轻量内容才使用 `popup`。
 - `content-panel`：承载需阅读确认的分组内容，使用 `v-model:show`、`title`、`confirm-text`、`show-footer` 和 `confirm`/`close` 事件完成打开、确认与关闭；用 `footer` 插槽替换默认确认区。内部优先组合 `cell`、`blue-mark-header`、`title-bar`、`material-display-bar`；视觉调整只使用 `--van-content-panel-background`、`--van-content-panel-radius`、`--van-content-panel-footer-padding`。
 - `dialog`、`toast`、`notify`：确认、短反馈与顶部通知；不得重复封装确认弹窗或全局提示。
 - `friendly-tip`、`popover`：基于触发元素的引导说明和轻量操作菜单。一次性友好引导使用 `friendly-tip`，点击空白处关闭；不要手写定位气泡。
@@ -35,7 +35,7 @@
 
 ## 选型规则
 
-- 动态面板选型顺序：阅读/确认内容使用 `content-panel`；表单编辑/提交使用 `form-panel`；单选使用 `radio-panel`；多选使用 `checkbox-panel`；四者均不适用且自定义内容较多时使用 `action-sheet` 的【动作面板】自定义面板样式；仅少量轻量内容才使用 `popup`。仅确认操作使用 `dialog`；短暂提示使用 `toast` 或 `notify`。
+- 动态面板选型顺序：阅读/确认内容使用 `content-panel`；表单编辑/提交使用 `form-panel`；只需单选使用 `radio-panel`；只需复选使用 `checkbox-panel`；专用面板均无法覆盖且当前上下文需要组合标题、复杂选择项、字段、筛选或批量操作时，使用 `action-sheet` 的【动作面板】模拟器「自定义面板」（`v-model:show` + 标题/关闭公开能力 + 默认插槽）。插槽内只在该示例已有的白色卡片内容结构中组合现有组件；仅少量轻量内容才使用 `popup`。仅确认操作使用 `dialog`；短暂提示使用 `toast` 或 `notify`。
 - 可分页的业务列表：组合 `list`、`pull-refresh`、`empty`、`loading`，不要手写重复加载状态。
 - 页面首次进入：纯色页面背景叠加 `loading type="illustration"`，数据就绪后再展示内容；局部加载按实际范围使用 `loading` 或 `skeleton`。
 - 需要展示字段名称与回显值时优先使用 `label`，并让左侧标签文本尽量自带冒号；字段成组或类型较多时选择 `info-card` + `label`。只有简单、不需要统一字段样式或展开逻辑的内容才组合 `cell-group` 或 `card`。

package/skills/use-persagy-vant/references/component-variant-selection.md

@@ -20,6 +20,36 @@
 - 页面层级优先通过已有容器变体表达：例如卡片内容、分组标题、灰色承载区、圆角卡片，先检查容器组件的示例和变量，再考虑页面级布局。
 - 多个示例都可用时，选择无需改动组件视觉、公开能力最少且后续维护最清晰的一种；在清单中说明取舍。
 
+## 输入框与文件上传的示例匹配
+
+| 页面意图 | 优先模拟器示例 | 典型公开能力 | 不适用时机 |
+| --- | --- | --- | --- |
+| 标题仅说明其下一块自由文本录入（执行反馈、处理说明、备注） | 【输入框】「换行文本域」 | 原标题作为 `label`，`v-model`、`type="textarea"`、`label-position="top"`、`input-align="left"`、`rows`/`autosize`、`maxlength="200"`、`show-word-limit`；按原规则传入 `required`、`rules`、`readonly` 或 `disabled` | 标题是独立信息分组，或字段只是只读回显时 |
+| 图片与视频采集、回显或补充材料 | 【文件上传】「图片/视频表单」 | 原标题作为 `label`，原列表作为 `v-model`，`accept="image/*,video/*"`、`multiple`、`max-count="9"`、`preview-size="70"`；必填使用 `required`，保留 `after-read`、删除与 `click-preview` 事件 | 仅上传非媒体文件，或场景没有上传行为时 |
+
+当“执行反馈”标题只描述其下方的输入区域时，标题必须合并进 `field` 的 `label`，而不是同时使用标题栏、普通文本和自绘文本框。文本域保持左对齐、使用组件内置字数统计和原校验数据；不得因视觉对齐覆盖组件样式。
+
+当“照片/视频”标题只描述其下方上传区域时，标题必须合并进 `uploader` 的 `label`，使用「图片/视频表单」的既有卡片、上传和预览布局。视频通过 `accept="image/*,video/*"` 和既有预览事件处理；不得另绘拍照/上传入口、缩略图或必填星号。
+
+## 动作面板的示例匹配
+
+| 页面意图 | 优先模拟器示例 | 典型公开能力 | 不适用时机 |
+| --- | --- | --- | --- |
+| 面板内只需要单选 | 【单选面板】 | `radio-panel` 的原选中值与 `select` 事件 | 同时存在非同构字段、复杂条目或批量操作时 |
+| 面板内只需要复选 | 【多选面板】 | `checkbox-panel` 的原选中数组与 `confirm` 事件 | 同时存在非同构字段、复杂条目或批量操作时 |
+| 当前上下文下的复杂选择、筛选或批量处理面板；内部同时有标题、关闭、多个非同构条目和确认操作 | 【动作面板】「自定义面板」 | `v-model:show`、`title`、`closeable`、`close-on-click-overlay`、`lock-scroll` 与默认插槽；在示例既有白色卡片内容区组合已有组件 | 仅阅读/确认、标准表单、纯单选或纯多选可完整由 `content-panel`、`form-panel`、`radio-panel`、`checkbox-panel` 承接时 |
+
+自定义面板的默认插槽用于组合【标题栏】、【单元格】、【字段展示】、单选/多选和既有操作组件；例如空间选择可保留原选中数组、可选数量、位置字段、标签、全选与下一步事件。保持该模拟器已有的灰色面板背景、标题区与白色卡片内容结构，不复制其 DOM 或覆盖动作面板样式；不得改用 `popup` 或手写遮罩、弹层和固定底栏。
+
+## 信息卡片的插槽组合
+
+当一张任务/作业摘要卡中的主标题、状态、设备或位置、详情字段和标签都属于同一业务对象时，选择【信息卡片】承载整张卡，而非将它拆成普通白色容器、文本和标签。
+
+- 优先用 `title`、`fields`、`extra-fields` 承接能直接映射的标题与字段；字段数组通过 `visible` 保持原空值隐藏规则。
+- 需要在主字段之后补充组合内容时，选择模拟器示例「下方插槽样式」的 `#default` 插槽：字段回显插入【字段展示】`label`，任务标题加多标签、右侧状态和下钻入口插入【单元格】「换行标签栏」。
+- 标签必须继续使用 `wrap-tags` 与 `show-wrap-tags`，右侧状态继续使用 `value`；只有原卡片存在跳转或触发行为时才使用 `right-icon="arrow"` 和原 `click`。
+- 该插槽仅用于组合现有组件。不得在插槽内手写白色卡片、标签流、字段排版或覆盖信息卡片、字段展示、单元格的样式。
+
 ## 单元格的示例匹配
 
 【单元格】的模拟器拥有大量变体。按下列业务意图选用对应 README 示例，而不是固定使用基础单元格：
@@ -29,9 +59,12 @@
 | 普通标题与回显值 | 基础用法 | `title`、`value`、`label` | 有明确选择状态或三层稳定信息时 |
 | 点击进入详情、选择面板或下一层 | 展示箭头 / 扩展元素「右图标」 | `is-link` 或 `right-icon="arrow"`、`click`、`value`/`note` | 仅展示不可操作信息时 |
 | 多选、单选列表项 | 扩展元素「前置选择」或「后置选择」 | `left-select` / `right-select`，并连接真实选择状态 | 点击仅为路由跳转或字段录入时 |
+| 单选对象/空间列表：左侧单选圆点、名称与一条位置/说明 | 单选单元格-双行样式 | `v-model:left-select`、`select-type="radio"`、`show-left-select`、`title`、`label`；位置有图标时使用 `show-label-icon`、`label-icon="location-o"` | 实际需要复选、稳定三层文本或跳转入口时 |
 | 人员、设备等有识别图片的对象 | 扩展元素「头像」 | `avatar` 或 `right-avatar` | 图片不承担对象识别、仅为装饰时 |
 | 强调关键条目或分组内重点字段 | 标题加粗 / 前置小蓝标 | `title-bold` / `blue-mark` | 普通内容项；不能替代页面一级标题组件 |
 | 标题旁呈现多个分类/状态 | 扩展元素「标签组」 | `tags` | 单一状态可用右侧值或状态组件时 |
+| 任务/检查项的单行标题，下方标签可换行，右侧有状态和下钻箭头 | 扩展元素「换行标签栏」+「右图标」 | `title`、`wrap-tags`、`show-wrap-tags`、`value`、`right-icon="arrow"`、`click`；标题仅在原页面强调时使用 `title-bold` | 标签属于详情字段时应使用 `label type="tag"`；仅有稳定三层纯文本信息时使用三行样式 |
+| 分组标题 + 多条同级说明、动作项、执行要求或检查内容 | 多行备注 | `title`、原说明数组 `multi-line-notes`、`show-multi-line-notes`；一个分组对应一个单元格 | 将多条说明拼成一个长段落或手写列表；无交互却增加箭头/折叠 |
 | 标题 + 一条辅助信息 | 双行图标单元格 / 基础用法带 `label` | `label`、`icon`/`right-icon`、`center` | 需要固定三层业务信息时 |
 | 标题、编号/位置、描述三层信息 | 三行样式 | `three-line`、`title`、`label`、`description`、可选 `value`/`right-icon` | 内容只有一到两层时 |
 | 辅助信息在右侧且可独立操作 | 加粗与可点击备注 | `note`、`note-bold`、`note-clickable`、`click-note` | 整行都应作为唯一触发器时 |
@@ -39,6 +72,12 @@
 
 “前置选择”与“后置选择”由选择动作的视觉归属决定：选择控件与标题同属一项、需要先看到状态时使用前置；文本信息为主、选择控件作为结果或批量操作时使用后置。若现有页面无法明确判断，先保留原有交互位置并在选型记录中说明。
 
+空间、对象等单选列表在“左侧圆点 + 名称 + 一条位置/说明”的结构下，固定使用【单元格】「单选单元格-双行样式」：将原单选状态绑定为 `v-model:left-select`，设置 `select-type="radio"` 与 `show-left-select`，名称传入 `title`，位置或说明传入 `label`；位置有图标时使用 `show-label-icon` 和 `label-icon="location-o"`。保留原点击、禁用、最多可选数量与提交逻辑；不得手写 radio、列表行或位置图标。
+
+任务/检查项中的 EHS、要求拍照等标签属于该任务行的附属状态，应作为 `wrap-tags` 原数组传入，允许组件按宽度自然换行；右侧“待完成”等状态使用 `value`，下钻使用 `right-icon="arrow"` 和既有 `click`。不要将标题、标签、状态和箭头拆为手写 flex 行，也不要因标签换行改用三行样式。
+
+“动作项 / 执行顺序 / 执行要求 / 检查内容”这类分组说明，每一个分组使用一个【单元格】的「多行备注」能力：分组名放入 `title`，每条原始说明分别放入 `multi-line-notes`，并开启 `show-multi-line-notes`。仅当原页面已有展开收起交互，才增加 `show-title-collapse-icon`、`default-multi-line-notes-collapsed` 和对应状态事件；静态展示不增加交互。位于同一卡片的一组单元格沿用组件分隔线，最后一个实际单元格设为 `border=false`。
+
 ## 交付格式
 
 在“组件复用清单”后增加以下内容；同一变体可合并为一项，不必按每一行重复：

package/skills/use-persagy-vant/references/design-interaction-baseline.md

@@ -17,6 +17,7 @@
 - 卡片内容与页面左右边缘保持 `16px` 间距；卡片之间间距 `8px`。
 - 页面含白色卡片时，在滚动内容的最后一张卡片之后必须保留**唯一且恰好 `24px` 高**的页面级空白容器，避免卡片视觉贴近页面底部；该容器不承载业务内容、不计入卡片间距，也不使用自定义组件实现。滚动到末尾时，该 `24px` 即为滚动内容的终点；不得再叠加 `padding-bottom`、安全区占位、空白节点或额外卡片间距，避免出现超过 `24px` 的可滚动空白。存在固定底部操作栏时，空白容器仍位于可滚动内容末尾、操作栏之前；操作栏自身的安全区只作用于操作栏，不得计入或叠加到滚动内容末尾。
 - 模块之间、控件之间使用 `8px` 或 `12px` 间距；仅左右排布的两组字段，纵向间距不得小于 `8px`。
+- 白色卡片内容中存在两个及以上语义独立的信息模块时，每个模块必须以二次卡片封装：普通、中性模块使用 `--van-gradient-gray`，当前重点、选中或待处理模块使用 `--van-gradient-blue`。优先通过组件公开 `background` 能力或 `gradient-gray` / `gradient-blue` 公共工具类实现；不得自行调整渐变、圆角、边框或组件样式。单字段、同一模块内连续字段，以及已由 `info-card`、`work-order-card` 等提供层级的内容不重复封装。
 - 白色卡片内有分割线的控件列表，最后一个可见控件必须隐藏末尾分割线；使用组件公开能力实现，例如 `cell`/`field` 设置 `border="false"`、`material-display-bar` 设置 `divider="false"`。根据条件渲染或 `visible` 判定最后一个实际可见项，不使用 CSS 强行隐藏分割线。
 - 需要展示字段名称与回显值时，优先使用 `label`，不要手写同类标签和值的排版；左侧标签文本尽量自带冒号，保证名称和值之间的统一阅读间距。录入或选择入口仍使用 `field`、`cell` 等对应组件。多字段成组或存在多种字段展示类型（文字、强调文字、链接、标签、图片/视频或纵向字段）时，优先使用 `info-card` + `label`；按字段内容选择 `label` 的公开展示类型和纵向布局。字段无数据时整项隐藏，使用 `info-card` 时通过字段的 `visible: false` 实现。
 - 触发器没有内置按压态时，叠加 `5%` 黑色透明遮罩作为按压反馈；有内置按压态的组件不重复添加。

package/skills/use-persagy-vant/references/element-component-matching.md

@@ -0,0 +1,89 @@
+# 元素识别与组件匹配
+
+界面优化的第一步不是写代码，而是完整识别页面元素，再为每个元素选择最贴近业务语义的 Persagy Vant 组件、模拟器示例和公开变量。目标是在不处理既有字段、数据和事件的前提下，用组件库原生能力替换页面结构。
+
+## 四段式工作流
+
+### 1. 整页元素扫描
+
+先从上到下遍历页面；从 0 到 1 的需求则从需求中的页面区块开始。每个元素记录以下信息：
+
+- **内容与字段**：标题、字段名称、回显值、标签、媒体、数量、时间、空值规则；保留字段名称、含义与数据来源。
+- **层级与容器**：页面级、卡片外标题、卡片内标题、分组、列表项、字段行、固定底栏或动态面板。
+- **交互与状态**：展示、跳转、打开选择、单选、多选、录入、上传、展开、删除、禁用、加载与提交。
+- **呈现特征**：单/双/三行、左/右信息、前后图标、头像、标签组、媒体、是否需要换行或省略。
+
+不得因为元素文案相似就直接选组件。例如“分类”可能是详情字段的标签型回显、工单卡片的状态标签，或可编辑的筛选条件，三者组件和变量不同。
+
+### 2. 按语义快速匹配组件
+
+以下表用于建立首轮候选，最终选择仍须阅读对应 README 与模拟器。
+
+| 识别到的元素 | 首选组件 | 匹配边界 |
+| --- | --- | --- |
+| 白色卡片页面承载 | 【背景】`background` | 首页默认主题，其他层级灰色主题 |
+| 页面一级大标题 | 【小蓝标】标题栏 `blue-mark-header` | 位于白色卡片外；不是普通卡片内分组标题 |
+| 卡片内二级标题 | 【标题栏】`title-bar` 默认样式 | 备注、操作、箭头、必填或展开收起使用其公开 Props |
+| 名称 + 回显值的详情字段 | 【字段展示】`label` | 依字段选择默认、加粗、链接、标签、媒体、换行、居右或 mini |
+| 单一字段为录入或选择入口 | `field` 或 `cell` | 录入用 `field`；打开面板/下钻优先 `cell` 右图标样式 |
+| 分组标题仅用于说明其下方的一块自由文本录入（如执行反馈、处理说明、备注） | 【输入框】`field` | 使用「换行文本域」：标题直接使用 `label`，不再额外拆出标题组件和自定义文本框 |
+| 简单同构列表行 | 【单元格】`cell` / `cell-group` | 导航、选择、头像、标签组、双/三行等按模拟器变体匹配 |
+| 单选对象/空间列表：左侧单选圆点，名称与一条位置/说明 | 【单元格】`cell` | 使用模拟器示例「单选单元格-双行样式」：前置单选 + `title` + `label`，不手写单选列表行 |
+| 任务/检查项标题，标签可换行，右侧有状态和下钻箭头 | 【单元格】`cell` | 使用模拟器示例「换行标签栏」+ 右图标；不自绘任务行 |
+| 分组标题下有多条同级说明、动作项、执行要求或检查内容 | 【单元格】`cell` / `cell-group` | 使用模拟器示例「多行备注」：一个分组对应一个单元格，标题和说明数组保持原样 |
+| 工单的标题、标签、位置、展开信息与行内操作 | 【工单卡片】`work-order-card` | 不退化为自行拼接的 cell 列表 |
+| 复杂多字段详情卡片 | 【信息卡片】`info-card` + `label` | 用字段类型与 `visible` 表达内容；不手写详情字段布局 |
+| 任务/作业摘要卡：主标题、状态、设备/位置及多项标签属于同一对象 | 【信息卡片】`info-card` | 使用下方 `#default` 插槽组合【字段展示】与【单元格】换行标签栏，不拆成自定义白色卡片 |
+| 独立状态、分类或关键词 | 【标签】`tag` | 先识别状态语义和是否可关闭/带数字/图标，再选 type、size 与示例 |
+| 多个标签构成一个详情字段 | `label type="tag"` | 保留字段名与标签数组；不改为裸 `tag` 流 |
+| 搜索 | 【搜索】`search variant="pure"` | 保留既有搜索绑定与事件 |
+| 图片、视频、文件上传 | 【文件上传】`uploader` | 图片/视频选择模拟器示例「图片/视频表单」：以组件 `label` 呈现标题，`accept="image/*,video/*"`、`multiple`、`max-count="9"`、`preview-size="70"`；不自绘上传网格 |
+| 阅读确认、表单、单选、多选动态面板 | `content-panel` / `form-panel` / `radio-panel` / `checkbox-panel` | 按任务类型选择；再考虑 `action-sheet` 或轻量 `popup` |
+| 当前上下文的复杂动态面板：标题/关闭、多类型选择条目、筛选或批量操作共同出现 | 【动作面板】`action-sheet` | 使用模拟器示例「自定义面板」：默认插槽在既有白色卡片内容结构中组合组件，不手写弹层骨架 |
+| 页面级主次操作 | 【动作栏】`bottom-action-bar` | 固定操作栏，不自行实现 footer |
+
+### 3. 变量与模拟器变体匹配
+
+组件确定后，再根据元素盘点的字段、状态与视觉结构选择 README/demo 中的具体示例。优先使用已有 Props、事件和插槽；不得将 CSS 变量或页面样式作为第一选择。
+
+- **标题**：一级标题固定选 `blue-mark-header`；二级标题固定选默认 `title-bar`。仅在存在真实必填、操作、备注、箭头或展开状态时开启相应 Props。
+- **白色卡片内模块**：先按字段归属划分语义独立模块；出现两个及以上模块时，每个模块使用二次卡片承载。普通、中性模块使用 `--van-gradient-gray`，当前重点、选中或待处理模块使用 `--van-gradient-blue`；优先给支持该能力的组件传入公开 `background`，其他模块容器仅使用 `gradient-gray` / `gradient-blue` 工具类。单字段、同一模块的连续字段及已经由业务卡片承载的内容不再叠加二次卡片，不手写渐变或覆盖组件样式。
+- **单元格**：跳转/打开面板选箭头变体；真实单选/多选选前置或后置选择变体；对象识别选头像；稳定三层信息选三行；多个分类/状态选标签组。单选对象/空间列表为左侧圆点、对象名称和一条位置/说明时，使用「单选单元格-双行样式」：原单选状态绑定 `v-model:left-select`，设置 `select-type="radio"`、`show-left-select`，名称传入 `title`，位置或说明传入 `label`；有位置图标时使用 `show-label-icon` 与 `label-icon="location-o"`。仅原标题已强调时才使用 `title-bold`，并保留原 `click`、可选数量与禁用逻辑，不通过原生 radio 或手写列表行替代。任务或检查项为单行标题、下方标签可因数量换行、右侧同时有状态与下钻入口时，使用「换行标签栏」示例的 `title`、`wrap-tags`、`show-wrap-tags`、`value`、`right-icon="arrow"` 与原有 `click`；只有任务标题在原页面需强调时才加 `title-bold`。分组标题下有多条同级说明（如动作项、执行顺序、执行要求、检查内容）时，使用「多行备注」示例：`title` 保持分组标题，`multi-line-notes` 保持原始说明数组，并开启 `show-multi-line-notes`；一个分组对应一个单元格，保留说明顺序，不合并成自定义段落或手写列表。只有原界面确实支持分组展开/收起时，才启用 `show-title-collapse-icon`、`default-multi-line-notes-collapsed` 及 `update:multi-line-notes-collapsed`；静态说明不要增加折叠或右图标。多个此类单元格位于同一白色卡片时沿用 `cell-group` 分割逻辑，卡片最后一个实际单元格隐藏分割线（`border=false`）。详见 `component-variant-selection.md`。
+- **输入框**：分组标题只服务于一块自由文本录入时（如执行反馈、处理说明、备注），合并为【输入框】「换行文本域」而不是“标题 + 自定义文本框”：用原标题作为 `label`，`type="textarea"`、`label-position="top"`、`input-align="left"`，按既有内容高度使用 `rows` 与 `autosize`，并保留原 `v-model`、`name`、`rules`、`required`、禁用/只读状态和提交校验。文本最大 `200` 字时使用 `maxlength="200"` 与 `show-word-limit`；不为同一字段额外添加 `title-bar`。
+- **文件上传**：图片/视频采集使用【文件上传】模拟器示例「图片/视频表单」；用组件 `label` 承接原标题、`required` 承接必填，`v-model` 保留原文件列表映射，`accept="image/*,video/*"`、`multiple`、`max-count="9"` 和 `preview-size="70"` 承接类型、数量和布局。保留既有 `after-read` 上传处理、上传状态、删除、回显和视频预览事件；不得拆成独立标题、手写“拍照/上传”按钮或自定义预览网格。
+- **信息卡片**：任务/作业摘要中主标题、状态、设备/位置、字段和多个标签共同描述同一对象时，优先使用【信息卡片】而不是自定义白色卡片。主标题与可直接映射的详情使用 `title`、`fields` 或 `extra-fields`；需要组合字段展示和任务标签栏时，使用下方 `#default` 插槽：字段使用【字段展示】`label`，任务标题、多个标签可自然换行、右侧状态和下钻入口使用【单元格】「换行标签栏」的 `title`、`wrap-tags`、`show-wrap-tags`、`value`、`right-icon="arrow"` 与原有 `click`。插槽只组合已有组件，不手写文本、标签或卡片样式；没有实际下钻行为时不设置箭头。
+- **动态面板**：面板只提供单选时直接使用【单选面板】`radio-panel`，只提供复选时直接使用【多选面板】`checkbox-panel`；不要因为它从底部弹出就改用动作面板。只有同时包含标题/关闭、多个复杂选择项、筛选信息、数量提示或批量操作，且专用面板无法完整承接时，选择【动作面板】模拟器示例「自定义面板」。使用 `v-model:show` 保留显示状态，按原行为配置 `title`、`closeable`、`close-on-click-overlay`、`lock-scroll` 与关闭事件；默认插槽只在该示例已有的白色卡片内容区组合【标题栏】、【单元格】、【字段展示】、单选/多选组件及已有操作组件。选项仍绑定原选中状态、数量上限、禁用原因和确认事件；不得改用 `popup`、手写遮罩/底部弹层、手写白色卡片或自行实现 fixed 底栏。
+- **字段展示**：普通回显用 `label` 默认；需要强调用 `type="bold"`，真实可操作链接用 `type="link"`，标签数组用 `type="tag"`，图片/视频用 `type="media"`；内容结构而不是视觉偏好决定 `vertical`、`content-align`、`size`、`ellipsis` 等变量。
+- **标签**：先判断字段语义。业务状态使用 README 中与状态语义相符的 `type`；中性分类优先默认灰色类型；需要轮廓、圆角、标记、关闭、数字前缀或右图标时，分别匹配 `plain`、`round`、`mark`、`closeable`、`show-number`/`number`、`right-icon` 的模拟器示例。没有明确产品语义时，不使用 `color` 或 `text-color` 自定义颜色。
+- **列表/卡片**：先选择业务卡片或 `cell` 的对应示例，再以公开字段 Props/数组/插槽承载原始数据；不通过手写间距、字体或色彩伪造另一种列表样式。
+
+### 4. 字段不变实现核验
+
+落地前和交付前逐项检查：
+
+1. 每个原有可见字段仍被展示，或仅因原规则的空值隐藏而未展示；字段名、值、格式、顺序和含义未被处理。
+2. 原有 `v-model`、接口字段映射、条件显隐、事件、路由和权限判断仍连接到对应组件公开 API。
+3. 每个状态值都映射到组件已有变量/示例；不能确认映射时保留原有状态并记录待确认，不能因展示方便而合并、删除或改写状态。
+4. 先使用模拟器原始样式与变量组合；未有产品经理明确的具体调整，不使用 `color`、`text-color`、Less/CSS 变量或页面 CSS 修改组件视觉。
+
+## 元素-组件匹配记录
+
+优化、审查和从 0 到 1 实现均需在工作中建立此记录；交付时按页面复杂度展示主要项。组件中文名称与链接必须符合 `component-documentation.md`。
+
+```md
+## 元素-组件匹配
+- 页面一级标题「工单详情」→ [小蓝标](<官网链接>)：卡片外标题，使用 `blue-mark-header` 默认标题栏。
+- 分组标题「基础信息」→ [标题栏](<官网链接>)：卡片内二级标题，使用默认样式；无备注、操作或展开状态，不开启额外变量。
+- 字段「分类」及标签数组 → [字段展示](<官网链接>)：`type="tag"` + 原有标签数组，保持字段名称与数据不变。
+- 工单条目 → [工单卡片](<官网链接>)：保留标题、标签、位置、收起/展开字段和原事件；不改为通用单元格。
+- 筛选入口「处理状态」→ [单元格](<官网链接>)：模拟器示例「右图标 + 备注」，使用 `right-icon="arrow"`、原有 `click` 和 `note` 回显选择结果。
+- 任务项「确认冷却塔已停机」及 EHS/要求拍照标签 → [单元格](<官网链接>)：模拟器示例「换行标签栏」，使用原任务标题作为 `title`、原标签数组作为 `wrap-tags`、`show-wrap-tags`、原状态作为 `value` 及 `right-icon="arrow"`；保留原跳转事件。
+- 执行依据「动作项」及多条说明 → [单元格](<官网链接>)：模拟器示例「多行备注」，使用原分组名作为 `title`、原说明数组作为 `multi-line-notes` 和 `show-multi-line-notes`；原界面无展开或跳转时，不配置展开图标和右图标。
+- 作业准备摘要（任务标题、状态、设备/位置与 EHS/要求拍照标签）→ [信息卡片](<官网链接>)：使用 `title`、原字段数组，并在下方 `#default` 插槽组合 [字段展示](<官网链接>) 与 [单元格](<官网链接>)「换行标签栏」；保留原标签数组、状态和跳转事件，不自绘白色卡片。
+- 选择无法执行对象（多条空间、选择数量、全选与下一步）→ [动作面板](<官网链接>)：模拟器示例「自定义面板」，用 `v-model:show`、原面板标题和关闭状态，在既有白色卡片内容区组合标题栏、原选择控件与【单元格】；保留原选中数组、最多可选数量、全选和下一步事件。
+- 可反馈空间「2F 空调机房」及位置「B 栋 - F2」→ [单元格](<官网链接>)：模拟器示例「单选单元格-双行样式」，使用原选中值 `v-model:left-select`、`select-type="radio"`、`show-left-select`、`title`、`label` 及位置 `label-icon`；保留单选事件和禁用/数量判断。
+- 执行反馈 → [输入框](<官网链接>)：模拟器示例「换行文本域」，使用原标题作为 `label`、原反馈字段作为 `v-model`，并使用 `type="textarea"`、`label-position="top"`、`maxlength="200"`、`show-word-limit`；保留原必填和校验规则。
+- 照片/视频 → [文件上传](<官网链接>)：模拟器示例「图片/视频表单」，使用原标题作为 `label`、原文件列表作为 `v-model`，并使用 `required`、`accept="image/*,video/*"`、`multiple`、`max-count="9"` 和 `preview-size="70"`；保留原上传、删除、回显与预览事件。
+```
+
+当候选组件都不能同时满足元素语义、字段完整性和既有交互时，停止实现相似自定义结构，按组件缺口流程记录已评估的组件、示例和缺失能力。

package/skills/use-persagy-vant/references/page-recipes.md

@@ -35,6 +35,7 @@
 2. 一级标题使用白色卡片外层的 `blue-mark-header`；卡片内部的二级标题使用默认样式的 `title-bar`，不要手写文本标题。
 3. 需要展示字段名称与回显值时优先使用 `label`，左侧标签文本尽量自带冒号；录入或选择入口仍使用 `field`、`cell` 等对应组件。
 4. 多字段成组或字段类型较多时用 `info-card` 承载 `label`；简单内容再用 `cell-group`、`card`、`divider` 组织分组。
+4.1 白色卡片内有多个语义独立模块时，为每个模块增加二次卡片：普通模块使用 `--van-gradient-gray`，重点、选中或待处理模块使用 `--van-gradient-blue`。优先使用组件公开 `background` 能力，其他容器使用 `gradient-gray` / `gradient-blue` 工具类；不要自定义渐变或重复包裹已有业务卡片。
 5. 按字段内容选择 `label` 的默认、加粗、链接、标签、图片视频或纵向布局；媒体点击接入 `image-preview` 或 `video-preview`。
 6. `info-card` 的接口字段使用 `visible: false` 隐藏无数据项。需要更多字段时优先使用其固定分割线或展开收起能力；其他卡片内容的展开收起使用 `collapse-toggle` 或 `blue-mark-header`，不自行绘制触发器。白色卡片内最后一个实际可见控件如有分割线，使用公开属性隐藏：`cell`/`field` 设 `border="false"`，`material-display-bar` 设 `divider="false"`。
 7. 主要处理动作使用 `bottom-action-bar`；可能造成数据变更的操作先经 `dialog`。

package/skills/use-persagy-vant/references/public-style-system.md

@@ -82,6 +82,12 @@
 | 卡片内容末尾 | 最后一个可见项隐藏分割线 |
 | 卡片页面滚动终点 | 最后卡片后唯一 `24px` 空白容器；不得叠加额外可滚动留白 |
 
+### 白色卡片内的二次信息卡片
+
+白色卡片内容中出现两个及以上语义独立的信息模块时，每个模块需要采用二次卡片承载。二次卡片背景只可使用公共渐变变量：普通、中性的信息模块使用 `--van-gradient-gray`；需要蓝色弱强调的当前重点、选中或待处理模块使用 `--van-gradient-blue`。优先使用目标组件已提供的 `background` 等公开能力（例如【单元格】），或使用 `gradient-gray` / `gradient-blue` 公共工具类承载模块容器；不得自行重配渐变色、透明度、圆角、边框或创建近似卡片样式。
+
+单个字段、同一信息模块内的连续字段或已经由【信息卡片】、【工单卡片】等业务组件提供卡片层级的内容，不额外叠加二次卡片。二次卡片之间仍遵循 `8px` 或 `12px` 的组件/模块间距，内部最后一个实际可见控件照常隐藏末尾分割线。
+
 完整页面规则以 `design-interaction-baseline.md` 为准。
 
 ## 组件级样式索引