扫描住客权益
大多数扫描会在 1 分钟内完成。 每个营业日的首次刷新会建立轻量级预订列表。 只有选择预订后，才会加载权益详情。
当你需要扫描住客卡、刷新预订数据或使用手动查找时，请使用本指南。 正常刷新会复用未变更的预订。 这样可以让大多数更新更快，并减少对 PMS 的读取。
| 区域 | 功能 | 你应看到的结果 |
|---|---|---|
| Scan | 根据今天的快照读取住客房卡 | 匹配的预订会在屏幕上打开 |
| Refresh | 重建今天的预订快照 | 横幅会显示进度、计数和就绪状态 |
| Manual lookup | 按房号或确认号查找预订 | 即使房卡无法读取，你仍可继续操作 |
| Benefits | 管理权益定义和房价计划分配 | 只显示 PMS 支持的操作 |
| Activity | 显示今天的消耗和同步状态 | 你可以撤销或重试失败的同步 |
打开页面
-
打开 Entitlements。
-
从 Scan 标签页开始。
-
如果需要扫描房卡，请选择一个已连接的编码器。
✓ 快照就绪后，Start scanning 按钮会变为可用。
当连接声明支持房卡读取时，AVA 可以通过 PMS 支持的读卡器进行扫描。 该读卡器会与其他符合条件的编码器一起显示。 物业还必须启用 Enable physical keycard reading 设置。
Opera 房卡扫描会提供房间和有效期详情，但不会提供住客姓名。 在管理权益前，请使用匹配的预订详情确认住客身份。
刷新预订数据
页面会保留酒店当前营业日期的本地快照。 正常刷新采用增量方式。 如果 PMS 预订修订版本没有变化，刷新会复用成功读取的详情。 刷新只读取在住预订列表。 它不会为每个预订加载权益详情。 今天离店的住客只要仍在房间内，就仍然符合条件。 某些 PMS 会将这些住宿标记为 DUE_OUT 或 Due Out，而不是 CHECKED_IN。
-
点击 Refresh 执行普通更新。
-
当详情看起来过时，或你需要完整重建时，点击 Refresh + clear cache。
-
等待状态横幅变为就绪状态。
✓ 页面现在可以再次扫描房卡。
如果不存在活动快照，AVA 会自动开始首次刷新。 如果刷新只返回当天的部分数据，AVA 会保留屏幕上仍可用的行。 刷新运行期间，现有的仅依赖快照的扫描仍然可用。 如果 PMS 开始限制刷新频率，AVA 会停止本次运行。 它会继续显示上一次可用的快照。
读取刷新计数
状态横幅现在会显示刷新进度计数。
| 计数 | 含义 | 重要性 |
|---|---|---|
| Fetched | 从 PMS 新鲜读取的预订 | 计数越高，表示新增或变更的行越多 |
| Reused | 从上一份快照延续的预订 | 复用越多，通常表示刷新越快 |
| Deferred | 等待唯一选择的预订详情 | 这些详情暂时不需要读取 PMS |
| Hydrated | 已加载权益详情的预订 | 该计数表示 AVA 已检查的详情数量 |
| Pages | 刷新期间读取的 PMS 预订列表页数 | 帮助你发现缓慢或异常深入的列表扫描 |
在 PMS 将住宿标记为已退房之前，AVA 会将住客保留在权益名单中。 在提供早餐或其他离店日权益前，请刷新快照。
快照会将已加载详情的预订与延后加载的预订分别跟踪。 当详情仍处于延后状态时，权益总数可能只是下限。 每个预订都完成加载或返回无权益后，总数才会完整。
加载预订详情
-
扫描住客卡，或使用手动查找。
-
当出现多个房间匹配项时，选择房间结果。
-
等待 AVA 加载该预订的权益详情。
✓ 成功结果（包括无权益结果）会在该营业日内保持缓存。
重复扫描和查找会复用缓存结果。 详情读取失败只会影响所选预订。 AVA 会等待后再重试，限流响应可能会延长等待时间。
Opera 可以将次日套餐存储在前一晚的住宿记录中。 AVA 使用 Opera 的计划标志，在实际兑换日期显示该权益。 酒店营业日期控制兑换日期，而匹配的 PMS 日期控制额度行。 例如，8 月 28 日的早餐可以使用 Opera 中 8 月 27 日的计划行。 没有明确住宿夜晚依据的计划会继续使用酒店营业日期。
Mews 通常会将权益记入实际入住的住宿夜晚。 因此，8 月 27 日的入账可能会显示为 8 月 28 日的早餐。 当 Mews 产品目录不可用时，AVA 会保留这一默认行为。 包括 PostingTimeUnit 在内的明确当天计划，会使用其提供的兑换日期。
当 PMS 日期与今天日期不同时
某些 PMS 权益会使用实际入住夜晚作为计划日期。 这在次日早餐套餐中很常见。
- AVA 会检查住客是否可以在今天的酒店营业日期兑换。
- AVA 会读取并更新匹配的 PMS 计划日期。
- 每次住宿权益的有效日期如果来自该依据，也会使用匹配的计划日期。
你不需要手动修改酒店营业日期。
处理家庭预订
AVA 会将同一房间的关联预订分组为一个房间级结果。 这包括团队预订、多房间预订以及带有同行住客的预订。
AVA 使用连接提供的 PMS 预订系列信息。 你不需要根据供应商特有的共享住客代码来识别关联住客。 Opera 家庭预订使用标准化的 Primary、Sharer 或 Member 角色。 Mews 同行记录使用标准化的 Main 或 Accompany 角色。
结果可能显示：
- Booked occupancy；如果 PMS 提供，还会显示成人和儿童人数。
- 标记为 Primary、Sharer、Accompany 或 Guest 的住客名单。
- 为该房间预订组选择的额度。
AVA 不会将关联预订的额度相加。 它会使用最高额度；额度相同时选择 Primary。 消耗会归属于提供该额度的预订。
在记录权益前，请使用住客名单确认你正在服务的住客。
如果 PMS 未提供预订入住人数，AVA 会将该值留空。 它不会显示虚假的零值。
处理受限流影响的刷新
当刷新在你预期完成前停止时，请使用此流程。 你也可能看到比平常更少的已获取预订。
-
等待一分钟后再试。
-
再次点击 Refresh。
-
如果当前快照仍覆盖今天的住客，请继续使用它。
-
如果问题持续，请让管理员检查 PMS 限流设置。
✓ PMS 限流时，AVA 不会假装刷新已完成。
扫描房卡
- 打开 Entitlements。
- 停留在 Scan。
- 选择一个在线编码器。
- 点击 Start scanning。
- 刷住客房卡。
- 查看匹配的预订。
- 住客使用权益时，点击 Consume 1。
- 只有在管理人员批准例外时，才点击 Manager override。
- 完成接待该住客后，点击 Done。
✓ 横幅会短暂显示 Card scanned — ready for the next card in a moment。 ✓ 随后扫描会回到 Ready — tap the next card at any time。
使用手动查找
当房卡无法读取，或你需要按房间搜索时，请使用手动查找。 AVA 会在触发付费权益读取前检查住宿日期。 如果日期缺失或无效，请先修正预订。
- 已知房号时，使用 Look up by room。
- 已知预订参考号时，使用 Look up by confirmation number。
- 等待预订卡片出现。
- 以与扫描结果相同的方式使用权益卡片。
开始手动查找后，活动中的房卡读取会在搜索开始前停止。 查找期间，Start scanning、编码器和候选项控件会保持锁定。 如果匹配到多个房间结果，选择其中一个即可继续无卡查找。
当手动查找未命中缓存时，AVA 可能会实时查询 PMS。 该结果会带有备注显示，直到下一次刷新将其纳入快照。
读取快照状态
| 横幅文本 | 含义 | 你要做什么 |
|---|---|---|
| in-house reservations ready | 快照已就绪，可用于扫描 | 开始扫描 |
| Refreshing PMS reservations… | AVA 正在重建快照 | 等待刷新完成 |
| using earlier same-day data | 当天刷新失败，但仍保留可用数据 | 方便时再次刷新 |
| unavailable until the next refresh | 该预订暂时不可用 | 刷新或使用手动查找 |
| Reservation data must be refreshed before scanning | 还没有可用快照 | 点击 Refresh |
当 PMS 访问缺失、不受支持、受到限流或不可用时，页面也会发出警告。 在这些情况下，现有快照可能仍然可见。
权益和活动
其他标签页的工作方式保持不变。
- 当 PMS 提供权益目录时，Benefits 会显示该目录。
- Activity 会显示今天的消耗、撤销操作和重试操作。
- 当 PMS 允许时，Rate plan assignments 仍保留在 Benefits 中。
撤销会直接更新可见的权益计数。 它不需要后续刷新，因此不会中断正在进行的房卡扫描。
故障排查
你看到：Reservation data must be refreshed before scanning
解决方法：
- 点击 Refresh。
- 等待就绪状态。
- 如有需要，点击 Refresh + clear cache。
- 如果横幅没有更新，重新打开 Entitlements。
你看到：页面显示 PMS 警告
解决方法：
- 如果当前快照仍可用，请继续使用。
- 请管理员重新连接 PMS 或恢复功能访问权限。
- PMS 问题修复后再次刷新。
你看到：刷新提前停止或显示限流警告
解决方法：
- 等待重试窗口结束。
- 再次选择该预订。
- 对其他住客使用当前快照。
- 如果问题持续，请让管理员检查 PMS 限流设置。
你看到：权益详情仍在加载
原因： AVA 只有在唯一选择预订后才会加载详情。 预订列表可能已经就绪，但其中的权益详情仍可能处于延后状态。
解决方法：
- 确认已唯一选择该预订。
- 等待详情读取完成。
- 如果 PMS 修正时间较新，点击 Refresh + clear cache。
- 如果详情仍不可用，请检查 PMS 连接。
你看到：手动查找没有返回可用结果
解决方法：
- 确认预订具有有效的住宿日期。
- 核对房号或确认号是否正确。
- 在 PMS 中刷新该预订后再试一次。
- 如果快照看起来仍然过时，请使用 Refresh + clear cache。
你看到：手动查找重新打开扫描或替换了较新的结果
原因： 较早的扫描或查找响应可能仍在完成。
解决方法：
-
等待当前查找完成。
-
运行期间不要更换编码器或选择其他候选项。
-
使用正确的房号或确认号重新开始查找。
✓ AVA 会保留最新结果，不会因为手动查找而重新开始扫描。
你看到：扫描显示多个预订或没有匹配
解决方法：
- 有多个关联预订匹配时，打开房间级结果。
- 检查所选编码器是否在线。
- 使用 Look up by room 或 Look up by confirmation number。
- 使用名单上的角色标签确认正在服务的住客。
- 如果结果仍不正确，请让支持团队检查预订映射。
你看到：房间额度似乎过高
你看到的情况： 一个分组房间结果为多个关联预订显示一个额度。
原因： AVA 会选择预订中的最高额度。 它绝不会将关联预订的额度相加。
解决方法： 检查 Primary、Sharer 和 Accompany 标签。 如果所选额度与 PMS 不同，请联系支持团队。
你看到：今天离店的住客缺失
你看到的情况： 住客仍在房间内，但按房间查找显示没有匹配的活动预订。
原因： PMS 可能会将离店日住宿标记为 DUE_OUT 或 Due Out。
解决方法：
-
在 PMS 中确认住客尚未退房。
-
在 Entitlements 中点击 Refresh。
-
再次按房号或确认号搜索。
-
如果住客仍未出现，请使用 Refresh + clear cache。
✓ 在退房完成前，AVA 会让已入住和即将离店的住宿保持符合条件。
你看到：家庭预订显示了错误的额度
你看到的情况： 团队、多房间或同行住客预订没有显示预期权益。
解决方法：
- 在 PMS 中刷新该预订。
- 在 Entitlements 中点击 Refresh + clear cache。
- 再次按房号或确认号搜索。
- 出现多个候选项时，选择正确的预订。
- 如果额度仍与 PMS 不同，请联系支持团队。
你看到：未启用实体房卡读取
解决方法：
- 使用 Look up by room 或 Look up by confirmation number。
- 前往 Settings → Room Access → Keycard Encoding。
- 选择 PMS Integration。
- 确认 PMS 供应商和编码器设备正确。
- 只有在 PMS 读取 API 验证通过后，才启用 Enable physical keycard reading。
- 点击 Save，然后重新加载 Entitlements。
- 如果保存后警告仍存在，请联系支持团队。
当连接无法读取房卡时，AVA 会停用房卡扫描。 房号和确认号查找仍然可用。 该警告可能表示读取功能已关闭、不受支持或暂时不可用。
你看到：结果显示已在 PMS 中实时检查
解决方法：
- 将该结果用于当前住客。
- 点击 Refresh，让后续扫描使用更新后的快照。
- 如果实时结果仍然不正确，请重新检查该预订。
仍然卡住？
如果出现以下情况，请联系 success@vouch-technologies.com：
- ❌ 快照始终无法就绪。
- ❌ 房卡扫描持续漏掉有效预订。
- ❌ 多次刷新后仍反复出现实时回退。
建议附上：
- 预订 ID 或确认号
- 房号
- 状态横幅截图
- 问题开始的时间