用途
Seam Access Codes（底层 API）用于在开发者已有的代码库中直接集成 Seam 的访问码能力，实现对智能锁访问码的手动、精细控制。它面向需要按时间窗口为特定设备创建、更新和删除访问码的场景，例如为预订的房间、会议室或短租单元自动下发限时门锁密码。
主要能力
- 在指定设备上创建带 starts_at 和 ends_at 时间窗口的访问码。
- 更新已有访问码的时间窗口。
- 删除访问码（例如预订取消时）。
- 通过 webhook 接收访问码设置成功、设置失败、设备离线等事件。
- 支持 Node.js、Python、Ruby 三种语言的 SDK 集成。
使用方式
- 安装 SDK：npm install seam（Node.js）、pip install seam（Python）、bundle add seam（Ruby）。不要固定到特定版本。
- 初始化 Seam 客户端。Next.js 中需使用惰性 getter，避免在模块作用域直接 new Seam() 导致 next build 失败；Express/标准 Node.js 可直接在模块作用域初始化。
- 获取设备 ID：访问码针对具体 device_id，每个房间/门必须映射到自己的设备 ID，可从环境变量（如 SEAM_DEVICE_ROOM_A1）或应用数据模型（如 room.seamDeviceId）中获取。若映射缺失，应让操作失败，不得回退到全局设备。
- 在预订创建时创建访问码：在 createBooking() 等创建函数中调用 seam.accessCodes.create，传入 device_id、name、starts_at、ends_at，并将返回的 access_code_id 和 code 保存到预订对象上。
- 在预订变更时更新访问码：若已保存 access_code_id，调用 seam.accessCodes.update 更新 starts_at 和 ends_at。
- 在预订取消时删除访问码：调用 seam.accessCodes.delete。
- 添加 webhook 端点：按代码库现有 webhook 模式处理 access_code.set_on_device、access_code.failed_to_set_on_device、device.disconnected 等事件。
- 将相关服务函数改为 async，并更新调用方使用 await。
适用场景
- 短租、酒店、共享办公等需要按预订时间自动下发和回收门锁密码的系统。
- 需要为不同房间/门独立管理访问码，而非使用统一全局设备的应用。
- 需要在预订创建、修改、取消时同步管理智能锁访问码的业务流程。
限制与注意事项
- 必须保存 access_code_id，否则无法更新或删除；若为 null/undefined 表示创建失败，需要重试。
- 禁止使用全局设备回退，每个房间必须映射到其特定设备。
- device_id 是单个字符串（每个访问码对应一个设备），不是数组。
- 默认由 Seam 生成随机访问码，除非需要特定 PIN，否则不要硬编码 code 值。
- name 为可选但建议填写，用于在 Seam Console 中识别。
- 部分锁具有最大访问码数量限制，可检查 device.properties.max_active_codes_supported。
- 需要根据业务决定失败模式：若房间预订必须依赖访问权限，Seam 调用失败时应抛出异常；若访问权限可选，则记录日志并继续。
- 遇到问题可参考 references/troubleshooting.md，生产环境准备可参考 references/production-checklist.md。