胁迫报警

代表用户确认一个未处理的 Duress 事件：记录其正在响应，并可停止进一步升级。只有未处理的事件可以被确认。

务必先确认。 先不带 confirm 调用以获取事件，告知用户其正在确认的内容，只有在用户同意后才使用 confirm: true 再次调用。

在工作流中或由 Agent 调用时，仅当设施的响应计划允许工作流确认、解决和触发警报时才有效。如需关闭事件，请使用 duress_resolve_incident。

读取设施中的 Duress 按钮：其状态（电池、最后接收信号时间、最后测试时间）、完整资料（标签、房间、区域、安装位置、关联的摄像头、门和屏幕、已静音的警报、监控健康状况）、可关联的对象、转发按键信号的屏幕，以及新添加按钮的设置测试。

电池： low 表示 30% 或更低（尽快更换），critical 表示 20% 或更低（立即更换）。battery 和 lastSeenAt 为 null 表示尚无屏幕接收到该按钮的信号。时间采用 ISO 格式。

操作：

• status：按钮状态。每个按钮的区域、房间、电池、屏幕最后接收到其信号的时间以及最后测试时间。例如 "Duress 按钮是否正常工作？"、"哪些需要更换电池？"
• list：按钮资料。每个按钮的完整资料：duress_buttons_write update 可更改的内容，以及信号、过去一天内接收到其信号的屏幕、监控健康状况和待进行的设置测试。
• link_options：关联选项。设施中可与按钮关联的摄像头、门、屏幕和访问区域（供 duress_buttons_write update 使用的 ID）。
• receivers：按钮接收器。设施中接收按钮信号并转发按键的显示屏，以及每个是否在线。当没有任何设备能接收按钮信号时，ready 为 false。
• setup_test：设置测试。新添加按钮的设置测试：waiting（首次按下仅为测试）、received、expired、ended 或 none，以及自添加以来是否有屏幕接收到其信号。需要 deviceSerialNumber。

更改设施中的 Duress 按钮：添加新按钮，更改其资料（标签、房间、区域、安装位置、备注、关联的摄像头、门、屏幕和访问区域、已静音的设备警报），让按钮发出蜂鸣声以便员工找到它，结束新按钮的设置测试使其正式启用，以及移除按钮。

update 中未提供的字段保留原值；null 表示清除。可通过 duress_buttons_read list 读取当前资料。

操作：

• update：更新按钮。在按钮注册所在的设施保存其资料（需要该设施的 Duress Configuration）。zone 为 001 至 999，且在设施内唯一。alertsMutedUntil（ISO，最多提前 30 天）会将其电池和离线警报静音。需要 deviceSerialNumber。
• locate：让按钮发出蜂鸣声。让按钮蜂鸣并闪烁 30 秒，以便员工找到它，例如一直报告电量低的按钮。命令由附近的屏幕发送，因此按钮必须在某个屏幕的范围内。按钮有未处理的警报时不可用。需要 deviceSerialNumber。
• go_live：正式启用新按钮。立即结束新添加按钮的设置测试，使其下一次按下即为真实警报。请先查看 duress_buttons_read setup_test。需要设施的设备管理或 Duress Configuration 权限。需要 deviceSerialNumber。需要确认。
• remove：移除按钮。将按钮与设施解除配对并删除其资料，从而释放其区域。按钮有未处理的警报时不可用。需要设施的设备管理权限。需要 deviceSerialNumber。需要确认。
• add：添加按钮。通过按钮上印刷的序列号，在设施中注册新的 Duress 按钮。默认情况下，其在接下来 30 分钟内的首次按下仅为测试（setupTest）。设施需要一台开启了 Duress alarm monitoring 的屏幕或一台 IoT Gateway。需要设施的设备管理权限。需要 deviceSerialNumber。需要确认。

立即结束设施中正在进行的 Duress 测试，使下一次按下即为真实警报。与所有测试一样，结果会在大约 10 分钟后发出。

读取 Duress 警报事件（员工按下 Duress 按钮，或由工作流触发）：事件列表、单个事件的时间线和通知投递、事后复盘报告，以及警报前后的 CCTV 录像。

状态： open（尚无人确认）、acknowledged（有人正在响应）、resolved（已关闭，并带有处置结果：genuine、false_alarm、test 或 unknown）。active 表示 open 或 acknowledged。测试事件（isTest）来自按钮测试；testType 'unplanned' 表示以真实警报触发、但被响应人员解决为测试的警报。

投递状态：sent、acknowledged（接收方已确认）、failed（见 error）、shadow（试运行，未发送任何内容）。发往监控中心的投递还会在 monitoringCentre 下汇总。结果会列出人员姓名，但绝不包含电话号码或电子邮件地址。时间采用 ISO 格式。

操作：

• list：列出事件。最新的在前。scope：facility（默认；指定的或已连接的设施）或 organisation（你可查看的该组织中所有设施；默认为该设施所属的组织）。
• get：获取事件。状态、被按下的按钮、时间线（按下、升级、确认、备注），以及每次通知或监控中心投递尝试及其结果。需要 incidentId。
• report：事件报告。用于事后复盘：事件本身、确认和解决所用的秒数、到达的步骤、所有时间线条目、各渠道发送的内容及失败的内容，以及录像是否已保留。可配合 duress_incidents_write add_note 将复盘内容添加到事件中。需要 incidentId。
• footage_previews：警报录像。警报录像中的每个摄像头：其状态、帧数和片段数、已上传的片段，以及最接近按下时刻的帧（posterSeconds）。提供 cameraId 时，仅返回该摄像头以及每一帧的 Unix 秒数（frameSeconds）。需要设施拥有 CCTV。需要 incidentId。
• footage_frame：警报录像帧。警报录像中的一帧延时画面，以图片形式返回：录像保留后返回保留的副本，否则返回警报时间窗口内的实时帧。seconds 为 footage_previews 返回的 posterSeconds 或 frameSeconds 值。需要 incidentId、cameraId、seconds。

更改 Duress 事件，但不影响警报本身：为事件命名、添加员工备注，以及保留或释放事件前后的 CCTV 录像。不会通知任何人。如需确认、解决事件或通知响应人员，请使用 duress_acknowledge_incident、duress_resolve_incident 或 duress_post_update。

操作：

• rename：为事件命名。为事件命名以便日后查找，例如 "前台有访客情绪激动"。名称为空或 null 时会移除名称。名称会显示在 Duress 控制台和报告中。需要 incidentId。
• add_note：添加备注。向事件时间线添加备注，例如用户发现的情况或到场人员。适用于任何状态；只有员工能看到备注，且备注不会改变事件。请使用用户的原话，并先与用户确认措辞。需要 incidentId、note。
• keep_footage：保留警报录像。按照响应计划设定的分钟数和摄像头，保留已解决的真实警报前后的 CCTV 录像，使其不会随普通录像一起被删除。上传完成后，几分钟内生效。不适用于测试、未处理的警报或已保留/已释放的录像。需要 incidentId。
• release_footage：释放已保留的录像。放弃为某个警报保留的录像：片段恢复为普通保留期限，已保留的帧会被删除，因此普通录像过期后将无法再查看。需要设施的 Duress Configuration 权限。需要 incidentId。需要确认。

解除 Duress 警报的封锁：被封锁的门重新允许人员进入。无论警报处于何种状态均可使用。

先确认。 先不带 confirm 调用以查看封锁情况，告知用户，在用户同意后使用 confirm: true 再次调用。

向正在响应 Duress 警报的人员发布更新，例如 "警察正在赶来" 或 "警报解除，该人员已离开"。更新会显示在他们的警报页面和 Duress 应用中；对于真实警报，响应计划还可以通过短信将其发送给所有已收到该警报短信的人。在警报解决后 24 小时内均可发布更新。

先确认。 先不带 confirm 调用以查看事件，向用户展示确切措辞，在用户同意后使用 confirm: true 再次调用。如果内容仅应让员工看到，请改用 duress_incidents_write add_note。

在设施触发真实的 Duress 警报，效果如同按下按钮：响应计划开始执行（通知相关人员，随后进行升级和提醒，并执行响应操作），警报会注明由此工作流触发及其原因。

• reason：发生了什么，例如 "后门出口被强行打开"（最多 200 个字符）。
• deviceSerialNumber：可选。使用其位置的按钮；只有提供此项时才会同时通知监控中心，并附带该按钮的区域。

仅可作为工作流步骤使用，且仅限响应计划允许工作流确认、解决和触发警报的设施。在此工作流的警报未处理期间，不会再触发新警报，而是返回该警报。

设施、品牌或组织的 Duress 合规报告：响应时间（P50/P95）、按处置结果分类的事件和误报率、测试覆盖率和逾期未测试的设施、按钮在线率、监控中心投递成功率，以及逐个事件的导出。另外还包括单个设施最近一次警报中未送达的通知。

天数按设施当地时间计算；超过 400 天的时间段会被缩短（range.capped）。真实事件和测试事件分别计数。时长单位为毫秒（p50Ms、p95Ms）。除非你拥有组织范围的访问权限，否则品牌报告只涵盖你可访问的设施（scope.restrictedToAccessibleFacilities）。

操作：

• overview：Duress 报告概览。总计、月度趋势，以及按组织、品牌和设施划分的指标（incidents、testCoverage、deviceUptime、deliveries）。设施分页返回。
• compliance_summary：Duress 合规摘要。合规 PDF 所显示的内容：测试覆盖率及逾期未测试的设施、按钮在线率、投递成功率、近期测试（testHistory），以及每个设施的最近一次测试、演练和真实警报，并附每个按钮的在线率。设施分页返回。
• incident_export：Duress 事件导出。每个事件一行，最早的在前，列与 CSV 导出相同：设施、测试或真实、状态、处置结果、当地时间、确认和解决所用的秒数、确认人和解决人、按钮和投递数量。
• delivery_problems：未送达的警报通知。设施最近一次警报或测试（包括整个测试时间窗口），以及按渠道列出的未送达通知。全部送达时 problems 为 null。需要该设施的 Duress 或 Duress Configuration 权限。

解决 Duress 事件：关闭警报、停止升级并记录结果。未处理和已确认的事件均可解决。

• disposition：genuine（真实紧急情况）、false_alarm、test 或 unknown。
• note：发生了什么。真实警报必填。

务必先确认。 先不带 confirm 调用以获取事件，告知用户其将关闭哪个警报及其结果，只有在用户同意后才使用 confirm: true 再次调用。

在工作流中或由 Agent 调用时，仅当设施的响应计划允许工作流确认、解决和触发警报时才有效。

读取 Duress 设置：响应计划（在设施或品牌模板中，通知哪些人、按什么顺序以及以何种方式通知）、警报引擎实际使用的解析后计划、可添加的人员和角色、设备警报（电池、离线、覆盖和投递问题）、品牌联系人规则和计划状态、品牌或组织的按钮概览，以及警报如何发送到监控中心。

设施可以沿用其品牌（否则为其组织）的模板，以额外联系人扩展模板（mode extend），或以自己的计划替换模板（mode replace）。可通过 duress_settings_write 更改设置。时间采用 ISO 格式。

操作：

• response_plan：响应计划。设施当前生效的计划（effective）以及每个层级的内容（sources：facility、brand、organisation），或仅提供 brandId 时返回品牌模板。联系人按已保存的形式返回，可直接编辑并保存回去。
• resolved_plan：解析后计划。警报引擎在该设施逐级联系的对象：展开为具体人员的角色、每人可联系的渠道、延迟，以及需要在警报发生前修复的警告。仅包含姓名，不包含电话号码或电子邮件。
• contact_options：联系人选项。可添加到设施计划中的人员和角色（需要该设施的 Duress Configuration 权限），或仅提供 brandId 时可添加到品牌模板中的人员和角色，已按品牌联系人规则筛选。
• device_alerts：设备警报。电池电量低、按钮离线、覆盖丢失和投递失败时通知谁：每个层级的规则和设施解析后的接收人，或仅提供 brandId 时返回品牌的规则。
• contact_rules：品牌联系人规则。品牌下的设施可以将哪些角色添加到计划中：allowAllExcept 隐藏列出的角色，manual 仅提供列出的角色。所需权限与编辑品牌计划相同。需要 brandId。
• plan_status：品牌计划状态。品牌下的每个设施：是沿用模板、扩展模板还是拥有自己的计划，添加了多少联系人，以及其计划的警告。需要 brandId。
• buttons_summary：按钮概览。品牌或组织中的每个设施：按钮数量、电池电量低和离线的数量、下一次和上一次测试。即 Brands & Customisation 和组织概览中的数据。
• monitoring：监控中心路由。警报如何从设施发出：eaAlarmType none、cid（通过 eaAlarmProvider 呼叫监控中心）或 relay（通过 eaRelayModel 连接有线面板），以及可使用的服务商。

更改 Duress 设置：响应计划（设施的计划，或品牌、组织的模板）、设备警报、品牌联系人规则，以及警报如何发送到监控中心。每次更改都需要确认，因为它会改变通知的对象。

传入 facilityId（默认：已连接的设施）、brandId 或 organisationId 中的一项。设施计划需要该设施的 Duress Configuration 权限；模板需要拥有 Duress Configuration 权限的组织管理员，品牌模板则需要该品牌下每个设施的 Duress Configuration 权限。请先通过 duress_settings_read 读取。

操作：

• save_response_plan：保存响应计划。在按下后 afterSeconds 秒通知的联系人层级（升序，第一级通常为 0）、ackRequired、reminders 和 responseActions。设施也可以改为以新增内容扩展其模板（mode extend）。未提供的字段保留已保存的值；responseActions 按操作合并。需要确认。
• remove_response_plan：移除响应计划。删除此层级已保存的计划，使设施重新沿用其模板，品牌则回退到组织的模板。需要确认。
• save_device_alerts：保存设备警报。替换此层级的设备警报规则：最多 10 条规则，每条规则包含一组事件和联系人（push、sms 或 email）。请保留从 duress_settings_read device_alerts 读取的规则 ID。需要 rules。需要确认。
• remove_device_alerts：移除设备警报。删除此层级的设备警报规则，使其重新沿用上一级的设置。需要确认。
• save_contact_rules：保存品牌联系人规则。品牌下的设施可以将哪些角色添加到计划中：allowAllExcept 隐藏 roleIds，manual 仅提供 roleIds。已保存的联系人保持不变；解析后的计划会刷新。需要 brandId、mode、roleIds。需要确认。
• save_monitoring：保存监控中心路由。警报的去向：eaAlarmType none、cid（需要 eaAlarmProvider，即 duress_settings_read monitoring 列出的服务商之一）或 relay（eaRelayModel）。需要设施的 Duress Configuration 权限。需要 eaAlarmType。需要确认。

因 Duress 警报封锁设施：在封锁解除之前（通过 duress_lift_lockdown 或控制台），所有门都将禁止人员进入。每个警报只能封锁一次。

绝不用于测试或已解决的警报。需要设施的 Door & Gate Access 权限。

先确认。 先不带 confirm 调用以查看事件，告知用户所有门都将上锁，在用户同意后使用 confirm: true 再次调用。

立即在设施开始 Duress 测试。在测试结束之前，每次按下都是测试，而非真实警报：

• walk：员工逐个按下按钮；仅通知响应计划的第一步，并标记为 TEST。
• drill：执行整个响应计划，并标记为 TEST。

设施的测试联系人会收到测试开始的通知，并在测试结束约 10 分钟后收到结果。每个设施同一时间只能进行一项测试。可通过 duress_end_test 提前结束；可通过 duress_tests_write 预约测试。

先确认。 先不带 confirm 调用，告知用户在 durationMinutes 内按下按钮不会触发真实警报，在用户同意后使用 confirm: true 再次调用。在工作流中或由 Agent 调用时，仅当设施的响应计划允许工作流确认、解决和触发警报时才有效。

读取 Duress 按钮测试：预约测试的排程（walk、comms 或 drill，单次或重复，适用于组织、品牌或设施）、排程在每个设施生成的测试时间窗口（scheduled、active、completed、cancelled，以及临时测试），以及某个时间窗口的结果（哪些按钮被按下或遗漏、通知了谁、监控中心信号、确认时间）。

不包含预约、更改或取消测试的人员；投递接收方已隐去。时间采用 ISO 格式；localDate 和 localStartTime 使用设施时区。可通过 duress_tests_write 预约或更改测试；通过 duress_start_test 立即开始测试。

操作：

• schedules：测试排程。scope 为 facility（默认；涵盖该设施的所有排程，包括其跳过或替换的共享排程）、brand（brandId）或 organisation（默认：该设施所属的组织）。最新更改在前。
• windows：测试时间窗口。设施从 from 到 to 的测试时间窗口（默认约为过去一周到未来一个月），或仅提供 organisationId 时返回该组织所有设施即将到来的时间窗口。
• results：测试结果。某个时间窗口及其结果：发送后保存，测试进行中实时计算（walk 测试清单），已排程或已取消的时间窗口为 null。需要设施的 Duress 权限。需要 startsAtKey。

预订、更改和取消 Duress 测试计划，设置单个设施如何遵循共享计划，并取消单个即将进行的测试时段。每项更改都会预订或改写未来的时段并向相关人员发送电子邮件，因此每项操作都需要确认。

计划需要在其整个目标范围内拥有 Duress Configuration 权限（组织范围的计划需要组织管理员）。时间采用各设施的时区。先使用 duress_tests_read 读取计划和时段；使用 duress_start_test 立即开始测试。

操作：

• create_schedule：预订测试计划。在 target 中的每个设施预订最多约一年的时段，并发送预订确认电子邮件。需要 name、type、target、startDate、localStartTime 和 recurrence。需要 name、type、target、startDate、localStartTime、recurrence。需要确认。
• update_schedule：更改测试计划。未提供的字段保留原值。未来的时段会被改写（已开始的保持不变），相关人员会收到更改通知。之后使用结果中的 ownerScope。需要 ownerScope、scheduleId。需要确认。
• cancel_schedule：取消测试计划。取消该计划及其未来的时段，并发送取消通知电子邮件。拥有自己副本的设施会保留该副本。需要 ownerScope、scheduleId。需要确认。
• set_facility_override：为单个设施更改共享计划。mode 为 follow（在此重新执行共享计划）、skip（在此停止）或 own（在此用基于 schedule 构建的副本替换）。仅需该设施的 Duress Configuration 权限。需要 ownerScope、scheduleId、mode。需要确认。
• cancel_window：取消单个测试时段。取消某设施的一次计划测试（计划继续执行），并向其相关人员发送电子邮件。需要该设施的 Duress 权限；正在进行的测试改用 duress_end_test 结束。需要 startsAtKey。需要确认。

为 Duress 警报解锁门，例如让警察或急救人员进入：解锁与所按按钮关联的门，否则解锁响应计划中的门。省略 doorIds 表示全部解锁，也可以列出其中部分门。每次解锁都会记录在事件时间线和访问日志中。

切勿用于测试警报或已解除的警报。需要该设施的 Door/Gate Access 权限。

先确认。 先不带 confirm 调用以查看将解锁哪些门，告知用户，待用户同意后再带 confirm: true 调用。