jcgl-dev/docs/公寓端/00-公寓端主要功能设计.md

00 公寓端主要功能设计（需求基线）

文档编号：docs/公寓端/00。性质：需求基线（Design Only），不写业务代码、不建表改表、不执行 DDL / DML。 上位依据：docs/10-架构优化方案-三端拆分.md §3.2 / §3.4、§5.4 表 5-3、§7.8 表 7-4；现状依据：docs/backend/*、docs/frontend/*、docs/11-既有数据库结构分析.md。 落地权威表述：docs/设计变更/03-三端功能设计修订（CR-02）.md（覆盖范围、交互协议、交互数据、模块与数据表设计、关键流程变更）；Asterisk 配置数据管理补遗见该文档 §10，两类叫乘流程见 §11，人脸数据下发管理与注册链路改判见 §12 及 docs/公寓端/10，人员入住作业流程见 §13 及 docs/公寓端/11，消费、充值与菜品管理见 §14 及 docs/公寓端/12，三端一致性同步与平台统计分析见 §15 及 docs/平台端/10。本文件定义"要做什么"及数据需求，不定义代码结构。实施排期见 docs/公寓端/13（非设计变更，只做排序、切分、对齐与衔接；阶段划分与验收口径仍以 docs/10 §9、docs/公寓端/07 为准）。

表 0-1 文档信息

项	内容
文档编号	docs/公寓端/00
文档名称	公寓端主要功能设计（重新规划后的需求基线）
适用范围	铁路行车公寓叫乘与一卡通系统·公寓端
关联文档	docs/公寓端/0113、docs/平台端/0110、docs/应用端/01~10、docs/10、docs/11、CR-02（§12 / §13 / §14 / §15）
约束条件	① 三端总体定位不变；② 平台不回调公寓；③ 公寓端与应用端同 jar、同库；④ 跨端 20 个接口编号不新增；⑤ 状态字段只有 apt.duty.state 一个写入口
交付对象	需求评审、三端详细设计、契约冻结与验收

表 0-2 修订记录

版本	日期	说明
v0.1	2026-11-07	首次形成：14 条公寓端职责的口语化罗列（末条截断）
v1.0	2026-11-09	补全末条上报范围；14 条编号化为 A-01~A-14、补主责端 / 协同端 / 本期判定；补文档信息与修订记录；指向 CR-02 作为落地权威
v1.1	2026-11-09	新增 §3「Asterisk 配置数据管理模块」：分机表 / 呼叫记录表 / 录音文件表 / 注册在线状态表四类数据表的字段定义、增删改查与权限控制；补充 SIP 呼叫场景下分机注册离线自动纳入设备报警的业务规则（触发条件、级别、通知、留存）。新增注册表 apt_sip_reg_status（CR-02 补遗 T-17），公寓本地库业务表口径 58 → 59 张
v1.2	2026-11-09	新增 docs/公寓端/10 人脸数据下发管理模块（AF-01~AF-06）并改判 A-02 注册链路（CR-C25）：签到终端发起注册申请并上传人脸 → 值班员在值班台完成人员注册 → 注册成功后人脸进入公寓服务系统 → 分别上传平台与下发公寓内设备；撤销"平台确认后注册才生效"的旧前置，明确人员主数据照片与特征值允许跨端（CR-C24），抓拍 / 录音仍不出公寓。不新增业务表、不新增跨端编号
v1.3	2026-11-10	新增 docs/公寓端/11「人员入住作业流程」（CI-01CI-05）并细化 A-03 作业链路：注册与签到 → 入住申请（房间 / 交路）→ 值班员审核（可换房）→ #9 CHECKIN 提报与平台运安匹配 → #7 拉取叫乘任务进入叫乘。明确"已入住"为流程态 + 业务事实双重表达（不新增 gy_jcxx 状态字段）、申请单落 apt_local_task 补列（不新增业务表，59 张不变）、端内接口 N-38N-47；权威登记见 CR-02 §13（CR-C26CR-C30、F-K、验收 1820）
v1.4	2026-11-10	新增 docs/公寓端/12「消费、充值与菜品管理」（CF-01CF-03）并细化 A-04 作业链路：食堂选餐与消费终端加菜显示金额 → 查补贴 / 现金额度 → 补贴优先扣款、不足现金补足 → 费用上报公寓端 → #10 流水同步平台并落入人员账户；线下充值仅"扫码识别 + 管理员核对记账"、不接线上支付；食谱按阶段性批次发布、终端选单确认前不落库、远程点菜仅预留入口。明确一笔消费只一条流水、四条状态链互不替代、knye / xjye 双额度设计映射（Q-43）、不新增业务表（59 张不变）、不新增跨端编号、不新增 bizType；端内接口 N-48N-58；权威登记见 CR-02 §14（CR-C31CR-C35、F-L / F-M / F-N、验收 2123）
v1.5	2026-11-10	三端一致性同步 + 平台统计分析（CR-02 §15）：本端已完成的平板叫乘 / 人脸签到 / 消费 / 菜品管理四项能力在应用端与平台端同步落地，三端状态映射与数据同步机制以 CR-02 §15 表 3-66 为唯一权威；#13 ARCHIVE 摘要 payload 扩展 satisfaction{} / roomOccupancy{} 分组计数，供平台以公寓为单位的分类统计（评价情况 / 房间利用周转），不新增 bizType、不新增上报接口、不接明细。平台新增 docs/平台端/10「公寓统计分析与排名报表」，统计结果不回写本端任何业务状态。本端四项能力权威表述不变，跨端 20 编号、59 张表、v2-draft、平台零回调不变；变更点与影响范围见 CR-02 §15 表 3-63

1. 定位

公寓端是执行叫乘任务和消费、充值的现场：管现场资源、现场事实、设备与媒体，负责具体任务的执行；主数据真源与账务主账在平台，值班员在界面上的人工干预必须经公寓端领域服务落地。

2. 功能需求（A-01~A-14）

表 0-3 需求清单（编号与三端归属以 CR-02 表 3-1 为准）

编号	需求	主责端	协同端	本期
A-01	从平台侧获取叫乘任务，上报叫乘结果	公寓端	平台端	是
A-02	获取机务人员数据，注册新增人员（新增人脸数据）	公寓端（签到终端申请 + 值班员确认注册 + 本地入档 + 平台 / 设备分别同步）	平台端（跨公寓主档真源、接收同步回执）、应用端（值班台审核）	是
A-03	提交入住请求与离寓请求；作业链路见 docs/公寓端/11（CI-01~CI-05）	公寓端（apt-stay 唯一执行域）	应用端（值班台审核 / 房间调整）、平台端（运安匹配与归集）	是
A-04	获取补贴，接收消费设备刷卡请求，扣除本地补贴，上报至平台消费台账、本地充值、充值上报；与平台断网期间，充值只能本地使用；完整作业链路见 docs/公寓端/12（CF-01~CF-03）	公寓端（离线受理、apt.ledger.local 唯一写入）	平台端（余额主账 platform-ledger）、应用端（管理员充值核对 / 食谱发布）	是
A-05	设备状态上报：在线、离线、报警	公寓端	平台端	是
A-06	公寓侧叫乘设备任务下发：SIP 呼叫（现有基于 Asterisk 执行）、平板叫乘	公寓端	—	是
A-07	叫乘任务派发：按叫乘任务叫乘时间顺序派发；SIP 呼叫模式由 Asterisk 组织派发并发起呼叫，平板叫乘形成叫乘任务数据、由平板拉取	公寓端	—	是
A-08	叫乘任务状态：SIP 呼叫模式由 AMI 事件执行情况推断状态变迁；平板叫乘方式由平板上报叫乘结果（人员、刷脸、未刷脸等）	公寓端	应用端	是
A-09	换乘：值班员对交路可指定其换乘的开车时间、叫乘时间，换乘可能涉及需要更换房间	公寓端（重算与联动）	应用端、平台端	是
A-10	报警功能：叫乘报警、离寓报警（设备报警按 A-05 单列）	公寓端	应用端	是
A-11	公寓房间管理：房间基础台账、房间状态更新、房间入住人员情况查看	公寓端	平台端	是
A-12	保洁管理：保洁人员管理、保洁记录管理	公寓端	应用端	是
A-13	值班员管理：值班员排班、值班员盯控质量考核	应用端	公寓端、平台端	是
A-14	数据上报管理：上报历史、续报（断网提交失败后再次报送）；上报范围包括入住情况、消费情况、充值情况，并补齐叫乘结果、设备状态、报警与归档摘要	公寓端	平台端	是

v0.1 末条原文止于"…充值情况，"，v1.0 按上下文补全；补全部分不改原意，只把范围列全。 §3 是 A-05 / A-06 / A-08 的细化，不新增 A-15 以后编号，14 项需求基线保持不变；细化项用 AC-01~AC-05 编号。

3. Asterisk 配置数据管理模块（A-05 / A-06 / A-08 细化）

现状依据：docs/backend/10 表 1-1「分机没有独立台账」（分机只以 GY_ROOMS.sip_account 单列存在，sip_status 从未被写入）；目标设计见 docs/10 §5.4 表 5-3（语音域 11 张表）、§7.8 表 7-4（分机资源状态机）。 术语沿用三端分册：表名一律小写；写入口用 apt.voice.endpoint / apt.voice.event / apt.voice.media / apt.voice.ami 模块名；权限点沿用 apt:voice:* 族；字段类型用 apartment/db/mysql/*.sql 的 MySQL 口径；枚举一律大写下划线字符串，不用数字码、不用 MySQL ENUM。

3.1 模块定位与数据表

表 0-4 模块功能项（AC-01~AC-05）

编号	功能项	主要数据表	唯一写入模块	需求来源
AC-01	分机表管理：分机台账的增删改停、房间/值班台/广播绑定、期望态收敛与对账	apt_sip_endpoint、apt_sip_binding、apt_trunk	apt.voice.endpoint	A-06
AC-02	呼叫记录表管理：呼叫会话、原始 AMI 事件流水、终态判定与归档	apt_call_session、apt_call_event、apt_call_event_his	apt.voice.event / apt.voice.ami	A-08
AC-03	录音文件表管理：录音索引、短期签名回放、留存与清理	apt_recording	apt.voice.media	A-08
AC-04	注册在线状态表管理：分机注册状态当前态与变迁流水、探测与恢复	apt_sip_endpoint.register_status、apt_sip_reg_status（新增）	apt.voice.endpoint（当前态）/ apt.voice.event（流水）	A-05、A-06
AC-05	分机状态离线告警：SIP 呼叫场景下自动判定并纳入设备报警	apt_device_alarm	apt.device.gateway（经 apt.duty.state 提交命令）	A-05、A-10

表 0-5 四类数据表与既有语音域表的关系

用户称谓	对应表	状态	说明
分机表	apt_sip_endpoint	既有	docs/10 表 5-3 已定义；配套 apt_sip_binding（绑定）、apt_trunk（中继）不单独成节
呼叫记录表	apt_call_session	既有	会话主表；明细 apt_call_event 只追加，归档 apt_call_event_his
录音文件表	apt_recording	既有	录音索引，与会话一对多；不存录音二进制，文件在本地目录
注册在线状态表	apt_sip_reg_status	新增（CR-02 补遗 T-17）	状态变迁流水；当前态权威仍是 apt_sip_endpoint.register_status，两表主从关系见 §3.2

主从不重复：apt_sip_endpoint.register_status 是当前态唯一权威字段（apt.voice.endpoint 写入）；apt_sip_reg_status 是只追加的状态变迁流水（apt.voice.event 写入），用于离线持续时间、告警去重与对账回溯。禁止把流水表当作当前态读取，也禁止两个写入口互写。

3.2 数据表字段定义

表 0-6 分机表 apt_sip_endpoint

列	类型	约束 / 默认	说明
endpoint_id	bigint	PK	代理键
gyid / extension	varchar(32) ×2	UK (gyid, extension)，NOT NULL	分机号是业务键；IDX (gyid, endpoint_type, enabled)、(gyid, room_no)
endpoint_type	varchar(20)	NOT NULL	ROOM / CONSOLE / BROADCAST / TRUNK_SIDE
room_no	varchar(32)	可空	房间号；与房间的正式关系是 apt_sip_binding，此列只作冗余检索
enabled	tinyint(1)	默认 1	停用不参与叫乘
register_status	varchar(20)	默认 UNKNOWN	本模块补充枚举：ONLINE / OFFLINE / UNREACHABLE / UNKNOWN；当前态权威字段
last_reg_at / last_seen_ip	datetime(3) / varchar(64)	可空	最近注册时间与来源 IP
sync_state	varchar(20)	默认 PENDING	PENDING / SYNCED / FAILED / DRIFT（表 7-4 四值）；DISABLED / DELETED 用 enabled / deleted 表达，不写进本列
applied_version / config_version	bigint ×2	默认 0	本地意图版本与平台下发版本
remark	varchar(256)	可空	备注
deleted	tinyint(1)	默认 0	逻辑删除；物理删除前二次对账
create_time / update_time	datetime(3) ×2	NOT NULL	三时间戳口径

表 0-7 呼叫记录表 apt_call_session（明细 apt_call_event / apt_call_event_his 同 docs/10 表 5-3 口径）

列	类型	约束 / 默认	说明
session_id	bigint	PK	代理键
gyid / linked_id	varchar(32) / varchar(128)	UK (gyid, linked_id)，NOT NULL	Asterisk linkedid；IDX (gyid, task_id)、(gyid, ryid, originate_at)、(gyid, state, originate_at)
unique_id / conf_no	varchar(128) / varchar(64)	可空	通道 ID、会议桥
task_id / ryid / room_no	varchar(64) ×3	可空	与 gy_jcxx.jcid、人员、房间对齐
peer_extension / console_extension	varchar(32) ×2	可空	房间分机 / 值班台分机
attempt_no	int	默认 1	复叫次数
state	varchar(20)	NOT NULL	CALLING / RINGING / ANSWERED / JOINED_CONF / LEFT / HANGUP / FAILED / TIMEOUT / UNKNOWN
originate_at / ring_at / answer_at / join_at / leave_at / hangup_at	datetime(3) ×6	可空	事件时间线
hangup_cause / duration_ms	varchar(128) / bigint	可空	挂断原因与时长
recording_id	bigint	可空	关联 apt_recording
source	varchar(20)	默认 AUTO	AUTO / MANUAL / TEST
create_time / update_time	datetime(3) ×2	NOT NULL	—

apt_call_event：event_seq PK、UK (gyid, session_id, event_type, channel, event_at_ms)、payload JSON 原始事件快照，只追加；apt_call_event_his 结构同口径并增 archived_at。

表 0-8 录音文件表 apt_recording

列	类型	约束 / 默认	说明
recording_id	bigint	PK	代理键
gyid / file_key	varchar(32) / varchar(256)	UK (gyid, file_key)，NOT NULL	Asterisk recordfile；IDX (gyid, task_id)、(gyid, ryid, started_at)、(gyid, state, started_at)
session_id / task_id / ryid	bigint / varchar(64) ×2	可空	与会话一对多
storage_kind / storage_path	varchar(20) / varchar(512)	默认 LOCAL	LOCAL / NFS / HTTP；路径只存索引，不存文件本体
url	varchar(512)	可空	回放地址；对外一律短期签名
bytes / duration_ms / codec	bigint ×2 / varchar(20)	可空	文件大小、时长、编码
started_at	datetime(3)	NOT NULL	录音开始时间
state	varchar(20)	默认 RECORDING	RECORDING / AVAILABLE / MISSING / PURGED
retention_days	int	默认 90	D15：90 天 + 仅内网 + 导出必审计
purged_at / checksum	datetime(3) / varchar(128)	可空	PURGED 只删文件、不删索引
create_time / update_time	datetime(3) ×2	NOT NULL	—

表 0-9 注册在线状态表 apt_sip_reg_status（新增 T-17；owner = apartment；上报源 = #11 摘要 / #24 质量摘要，明细不上报）

列	类型	约束 / 默认	说明
id	bigint	PK	代理键；业务键为 (gyid, endpoint_id, event_seq)
gyid / endpoint_id / extension / room_no	varchar(32) / bigint / varchar(32) / varchar(32)	UK (gyid, endpoint_id, event_seq)，NOT NULL	IDX (gyid, state, occurred_at)、(gyid, endpoint_id, occurred_at)
state / prev_state	varchar(20) ×2	NOT NULL	与 apt_sip_endpoint.register_status 同字典：ONLINE / OFFLINE / UNREACHABLE / UNKNOWN
source	varchar(20)	NOT NULL	AMI_EVENT / QUALIFY / PROBE / MANUAL / RECONCILE；双源判定见 docs/公寓端/08「注册状态不可靠」
event_seq	bigint	NOT NULL，单调	同一分机单调递增；更正以新一条 + biz_version+1 体现，不改历史行
occurred_at / received_at	datetime(3) ×2	NOT NULL	现场发生 / 公寓入库
last_reg_at / offline_since / duration_ms	datetime(3) ×2 / bigint	可空	离线持续时间与周期起点；告警去重键依赖 offline_since
peer_ip / peer_port	varchar(64) / int	可空	注册来源
ami_session_id	bigint	可空	关联 apt_ast_ami_session，用于 AMI 断连归因
alarm_id	varchar(64)	可空	关联 apt_device_alarm.alarm_id；恢复时不清空
biz_version	bigint	默认 1	同周期更正 +1
create_time	datetime(3)	NOT NULL	只追加，无 update_time

新增表全部带代理主键、gyid 打头的唯一键与查询索引，不复制 docs/11 记录的 0 主键 / 0 索引缺陷；本表为设计定义，DDL 待阶段二契约冻结评审通过后执行。

3.3 增删改查操作

表 0-10 四类表的 CRUD 主体、入口与约束

表	增（C）	改（U）	删（D）	查（R）
apt_sip_endpoint	管理员 POST /apt/voice/endpoints，只落库 + 异步下发，返回"已受理 + 当前 syncState"；apt:voice:endpoint:add	PUT /apt/voice/endpoints/{id} 改属性；启停走 /status；收敛走 /resync。分机号不可原地改（40906，停旧建新，旧号留 7 天）	DELETE 为 deleted=1 逻辑删除，物理删除前二次对账；保留 apt_ast_config_version 版本记录	GET /apt/voice/endpoints（列表 + 详情）；gyid 数据域过滤，默认按 register_status / sync_state 可筛
apt_call_session	无人工新增接口：由 apt.voice.event 依 AMI OriginateResponse 等事件自动写入	无人工编辑接口：只允许状态机事件推进与 5 分钟巡检判定 UNKNOWN 终态；不得改 state 外的业务事实	禁止单条删除；只允许按留存期由归档任务 apt:voice:call:archive 受控迁 apt_call_event → apt_call_event_his（commandId 幂等）	GET /apt/voice/calls、/{sessionId}、/{sessionId}/events；导出必审计
apt_recording	无人工新增接口：由 apt.voice.media 依事件 recordfile 或目录反查写入；缺文件置 MISSING 并告警	只允许 state 由清理任务置 PURGED、由回查置 AVAILABLE，不改 file_key / checksum	禁止物理删索引；清理顺序为「先置 PURGED → 再删文件」，失败重试 + 告警（docs/公寓端/05 表 5-4）	GET /apt/voice/recordings、/{id}/url 短期签名地址；state=PURGED 返回 41001
apt_sip_reg_status	只追加：apt.voice.event 依注册事件 / qualify / 定时探测写一条状态变迁	禁止改：更正以新一条 + biz_version+1 体现；当前态由 apt.voice.endpoint 同步到 apt_sip_endpoint.register_status	禁止删单条；按月归档（在线 90 天）	GET /apt/voice/reg-status（当前态）、/{endpointId}/history（变迁流水）；POST /apt/voice/reg-status/{endpointId}/commands 手工重探
apt_device_alarm	AC-05 自动判定写入	仅处置回写 handled_at/by/result（bizVersion+1）	禁止删除，按留存期归档	GET /apt/device/alarms（CR-02 N-17）

表 0-11 新增 / 沿用接口（端内 /apt/**，不计入跨端 20 接口；编号沿用 CR-02 的 N-* 序列）

编号	方法 + 路径	权限点	幂等	落表	状态
docs/公寓端/04 表 4-15 #1~#6	GET/POST/PUT/DELETE /apt/voice/endpoints*	apt:voice:endpoint:*	L0~L2	apt_sip_endpoint	沿用
docs/公寓端/04 表 4-15 #7~#9	GET /apt/voice/calls*	apt:voice:call:list	L0	apt_call_session、apt_call_event	沿用
docs/公寓端/04 表 4-15 #10~#11	GET /apt/voice/recordings*	apt:voice:recording:list/replay	L0	apt_recording	沿用
N-19	GET /apt/voice/reg-status	apt:voice:reg:list	L0	apt_sip_endpoint、apt_sip_reg_status	新增
N-20	GET /apt/voice/reg-status/{endpointId}/history	apt:voice:reg:query	L0	apt_sip_reg_status	新增
N-21	POST /apt/voice/reg-status/{endpointId}/commands（PROBE）	apt:voice:reg:probe	L2 commandId	apt_sip_reg_status	新增
N-22	POST /apt/voice/calls/archive	apt:voice:call:archive	L2 commandId	apt_call_event_his	新增
N-23	POST /apt/voice/recordings/commands（PURGE）	apt:voice:recording:purge	L2 commandId	apt_recording	新增
N-24	GET /apt/voice/endpoints/{id}	apt:voice:endpoint:list	L0	apt_sip_endpoint	新增（补详情）

路径遵循 docs/公寓端/04 表 4-1：不出现动词化路径；archive / commands 属非 CRUD 动作；受控命令一律带 commandId，状态变更不直接 PUT 业务状态字段。

3.4 权限控制要求

表 0-12 权限点矩阵（前端 v-hasPermi 与后端 @PreAuthorize 同码，登记 sys_menu.perms，见 docs/公寓端/02 §4.1 / §4.2）

权限点	分机表	呼叫记录表	录音文件表	注册在线状态表	告警记录	可授角色
apt:voice:endpoint:list	R	—	—	R	—	公寓管理员、值班长、值班员
apt:voice:endpoint:add/edit/changeStatus/remove	C / U / D	—	—	���	—	仅公寓管理员 / 系统管理员
apt:voice:call:list	—	R	—	—	—	值班长、值班员（只读）
apt:voice:call:archive	—	归档	—	—	—	仅公寓管理员
apt:voice:recording:list/replay	—	—	R	—	—	值班长、值班员（回放必审计）
apt:voice:recording:purge	—	—	清理	—	—	仅公寓管理员
apt:voice:reg:list/query	R	—	—	R	—	值班长、值班员
apt:voice:reg:probe	—	—	—	受控命令	—	值班长、公寓管理员
apt:device:alarm	—	—	—	—	R + 处置	值班员（处置）、值班长

表 0-13 六条权限硬要求

#	要求
1	双校验：/apt/** 走 RuoYi 会话 + @PreAuthorize，前端 v-hasPermi 同码；越权或跨 gyid 一律 40301 APT_FORBIDDEN，不返回脱敏后的他人数据
2	gyid 数据域锁定：gyid 只从会话取，不接受前端参数；四类表所有查询 / 写入 SQL 必带 gyid，唯一键一律以 gyid 打头
3	事实类表只读：呼叫记录、录音索引、注册状态流水、设备告警不开放人工新增 / 编辑 / 删除接口，只能由对应领域模块或带 commandId 的受控命令写入；任何"直接改 state"的接口视为设计错误
4	两级审计：所有写操作、导出、回放、清理、处置同时记 sys_oper_log 与 duty_operation_log（操作人、权限点、commandId、前后值、结果）；审计事实可查询、可导出、保留期独立（docs/公寓端/05 §8）
5	敏感数据：录音回放短期签名地址 ≤ 5 分钟（D15 保守值，严于 04 §8 的 ≤ 10 分钟）、仅内网可播；state=PURGED 返回 41001；last_seen_ip / storage_path 仅管理端可见、值班台脱敏；录音文件与人脸、抓拍一样不上传平台
6	职责分离：改动 Asterisk 资源（分机增删改停、对账）与查阅业务结果（呼叫 / 录音 / 注册 / 告警）分开授权；值班员可查看与处置告警，但不得改分机台账、不得清理录音

3.5 SIP 呼叫场景：分机注册离线自动纳入设备报警

适用范围：gy_jcxx.call_mode='SIP'（A-06 / A-08）。TABLET 模式不触发分机离线告警，其设备离线仍按 CR-02 F-H 走 apt_device_alarm，两者共用一张告警表与同一 alarmSource=DEVICE 口径。

表 0-14 告警触发条件（四条同时满足才判定）

#	条件	判定依据	不成立时
1	呼叫方式为 SIP 且任务进入派发	gy_jcxx.call_mode='SIP'；Quartz 触发或人工 POST /duty/call/{jcid}/voice	平板模式跳过
2	能解析出对应房间的主分机	jcid → fjh → apt_sip_binding(bind_type='ROOM', is_primary=1, 生效区间有效) → apt_sip_endpoint	绑定缺失记 apt_ast_drift 并告警，不误报"注册离线"
3	分机配置已就绪	enabled=1、deleted=0、sync_state='SYNCED'	PENDING / FAILED / DRIFT 属配置未收敛，按 40905 / 对账告警处理
4	注册状态非在线或已失联	apt_sip_endpoint.register_status ∈ {OFFLINE, UNREACHABLE, UNKNOWN}，或 ONLINE 但 last_reg_at 早于 now - 探测阈值；且 apt_sip_reg_status 最新态非 ONLINE、offline_since 持续超过阈值	状态 UNKNOWN 且 AMI 断连时按 P2 记，不阻断叫乘

阈值默认：注册探测 120 s、离线持续 60 s（Q-26 待决）。双源判定：注册事件 + qualify / 定时探测，与 docs/公寓端/08「注册状态不可靠」的处置一致；apt_ast_ami_session 断连期间的 UNKNOWN 单列归因。 去重：同一离线周期只产生 1 条告警，alarm_event_key = hash(gyid, endpoint_id, 'SIP_OFFLINE', offline_since)；分机恢复后再次离线生成新 key；同 key 不重复响、不重复推送（CR-02 F-H 第 1 步）。

表 0-15 告警级别（severity，沿用 apt_device_alarm 的 P0~P2）

级别	触发情形	值班台表现
P0	有待叫乘任务（含 30 s 内即将触发）且对应房间主分机离线	该行置红 + 顶部横幅 + 业务优先 TTS 提醒
P1	无待叫乘任务，但房间 / 值班台 / 广播分机离线	D6 设备行标红，纳入盯控列表
P2	状态 UNKNOWN（AMI 断连、qualify 未回）或中继侧离线	仅记入告警列表与健康摘要，不触发 TTS

表 0-16 通知方式（不新增 WS 消息名、不新增跨端接口编号）

#	通道	内容	约束
1	落库	apt_device_alarm 一行：alarm_source=DEVICE、alarm_type=OFFLINE、severity 按表 0-15，附 endpointId、extension、roomNo、jcid、offlineSince	alarm_event_key 去重；deviceCode 填 apt_sip_binding 的 DEVICE 关联值，无则填分机号
2	/ws/duty	复用 CR-02 表 3-9 device.alarm（alarmSource、alarmEventKey、severity）；恢复时复用 docs/应用端/04 表 4-8 alarm.cleared	seq 单调；60 s 兜底轮询；推送只是加速
3	值班台	D6 行标红 + 横幅；P0 经 notice.sync 入两级提醒队列与 TTS（业务优先）	不新增消息名 / 枚举；apt_tts_utterance 只记播报结果
4	跨端上报	#12 DEVICE_ALARM（按 alarmSource 分组，含 deviceCode）、#11 摘要 offlineList[]、offlineCount；#13 归档摘要计数、#24 质量摘要 regRate	走 CR-02 payload 扩展；平台只汇总，不回调、不下发处置指令
5	人工处置	POST /apt/device/alarms/{id}/handle（CR-02 N-17，权限点 apt:device:alarm）	回写 handled_at/by/result，bizVersion+1

不阻断原则：离线告警只提示与留痕，仍按原流程发起 SIP 呼叫，失败原因记入 apt_call_session.hangup_cause；是否自动降级为平板 / 广播由 Q-27 决定，未决前不自动切换。告警与叫乘结论互不覆盖（docs/公寓端/05 §4 第 3 条"录音不阻断叫乘"同口径）。

表 0-17 告警记录留存要求

#	对象	留存口径
1	apt_device_alarm	在线 180 天（Q-28 待决），之后按月归档；索引长期保留。必须完整保留 alarm_event_key、occurred_at、cleared_at、handled_at/by/result、biz_version、severity 与关联 jcid / endpointId
2	apt_sip_reg_status	状态变迁流水在线 90 天，按月归档；同一离线周期的 OFFLINE 起与 ONLINE 恢复必须成对可查，禁止物理删单条
3	apt_call_session / apt_call_event	会话索引长期保留；原始事件在线 90 天后归档到 apt_call_event_his（docs/10 表 5-3 处理关系第 5 条）
4	apt_recording	D15：录音文件 90 天（retention_days），PURGED 只删文件不删索引；告警记录不随录音清理删除
5	审计与上报	sys_oper_log + duty_operation_log 保留期独立；#12 / #13 摘要与 PL_RECEIVE_LOG 按平台口径留存；断网期间告警先落本地库 + outbox，恢复后按 serverReceivedAt 归日并复用原 idempotencyKey 续报（CR-02 F-E）
6	恢复闭环	注册恢复后：写 apt_sip_reg_status 新流水 → apt.voice.endpoint 置 register_status='ONLINE' → 置 apt_device_alarm.cleared_at → 推 alarm.cleared。只追加、不清零，恢复后告警记录仍可查

表 0-18 本次新增决策点（沿用 docs/应用端/10 的决议记录格式：结论 + 决议人 + 日期三者缺一视为未决议）

编号	待决事项	未决默认口径	拍板时点
Q-26	注册探测阈值与离线持续阈值	120 s / 60 s	阶段二契约冻结前
Q-27	分机离线时是否自动降级为平板 / 广播	不自动切换，仍发起 SIP 并记失败原因	阶段三试点前
Q-28	告警记录在线留存 180 天是否合规	在线 180 天 + 按月归档，索引长期保留	阶段三 D 批开工前

4. 与三端设计的关系

1. 覆盖范围：A-01A-14 的三端归属、冲突裁决与分期见 CR-02 §2（表 3-23-5）；三端 01-功能边界.md 已同步改判。§3 属公寓端语音与录音域（原功能域），不新增功能域编号。
2. 交互协议与数据：跨端仍为 20 个编号（不新增），新数据走 payload + bizType 扩展；平板 / 消费机走设备侧 /open/v1/** 拉取；值班台走端内 /duty/** 与 /ws/duty。见 CR-02 §3、§4；本次告警通知不新增消息名与接口编号。
3. 数据表：CR-02 新增公寓本地库 13 张表 + 本次补遗 1 张（共 14 张）、平台库 3 张表，另 3 处补列；公寓本地库业务表口径统一为 59 张（44 存量 + apt_local_task 1 + 14）。见 CR-02 §6、§10。
4. 关键流程：双模式顺序派发、换乘、断网充值与冲正、上报历史与续报等 8 条流程变更见 CR-02 §7；本次新增分机离线告警流程 F-I 见 CR-02 §10。A-06 / A-07 / A-08 两类叫乘实现方式的端到端流程（触发条件、交互流程、状态上报机制、结果反馈路径）以 docs/公寓端/05 §9 为流程权威表述，表 0-3 的需求口径不变。
5. 人脸数据下发与注册链路：docs/公寓端/10 为唯一权威表述，登记见 CR-02 §12（CR-C24 / CR-C25、F-J、R-85R-93、验收 1517）。注册链路为「签到终端发起注册申请并上传人脸 → 值班员在值班台完成人员注册 → 注册成功后人脸进入公寓服务系统 → 分别上传平台与下发公寓内设备」；平台 personRegVerdicts[] 降级为主档同步回执，不再是注册生效前置；两条同步路径解耦并行、互不阻塞。人员主数据照片与特征值按 CR-C24 允许跨端，业务抓拍 / 录音仍不出公寓；本模块不新增业务表，59 张口径不变。
6. 人员入住作业流程：docs/公寓端/11 为唯一权威表述，登记见 CR-02 §13（CR-C26CR-C30、F-K、R-95R-103、验收 18~20）。五环节为「注册与签到 → 入住申请（房间 / 交路）→ 值班员审核与房间调整 → #9 CHECKIN 提报与平台运安匹配 → #7 任务查询进入叫乘」；"已入住"为流程态 + 业务事实双重表达，申请单落 apt_local_task 补列，本流程不新增业务表、不新增 gy_jcxx 状态字段、不新增跨端编号。
7. 消费、充值与菜品管理：docs/公寓端/12 为唯一权威表述，登记见 CR-02 §14（CR-C31CR-C35、F-L / F-M / F-N、R-104R-113、验收 21~23）。三流程为「人员消费：食堂选餐 → 消费终端加菜显示金额 → 查询补贴 / 现金额度 → 补贴优先扣款、不足现金补足 → 费用上报公寓端 → #10 流水同步平台并落入人员账户」「人员线下充值：扫公寓线下二维码 → 签到终端点击现金充值并输入金额 → 管理员核对 → 计入本人现金充值额度 → 保存至公寓端并同步平台」「公寓菜品管理：发布阶段性菜品食谱 → 消费终端查看菜品并加入选择菜单 → 预留远程点菜入口」；仅线下充值、扫码非支付、不建支付订单与回调，一笔消费只一条流水、四条状态链互不替代，食谱主数据归平台库 YKT_MEALS 补列，本流程不新增业务表、不新增跨端编号、不新增 bizType、不新增状态字段。
8. 三端一致性同步与平台统计分析：docs/平台端/10 为统计 / 报表 / 排名唯一权威表述，CR-02 §15（表 3-63 变更点与影响范围、表 3-65 四能力三端对照、表 3-66 三端状态映射与数据同步机制）为登记权威。本端四项能力权威表述不变；#13 ARCHIVE 摘要按 payload 扩展 satisfaction{} / roomOccupancy{} 分组计数，供平台以公寓为单位统计评价情况与房间利用周转，不新增 bizType、不新增上报接口、不接明细、不改公寓业务状态。平台按 gyid 分类统计接待能力（入住 / 叫乘 / 评价 / 报警）、补贴发放、补贴消费、现金充值（计为收入）、房间利用周转，按月 / 季 / 年出报表并做分类 + 综合排名；统计结果不回写本端业务状态。跨端 20 编号、59 张表、v2-draft、平台零回调不变，平台库新增 2 张另计。
9. 待决策：Q-20Q-25 见 CR-02 §9，Q-26Q-28 见本文件表 0-18，Q-29 见 CR-02 §11，Q-30Q-35 见 docs/公寓端/10 表 10-29，Q-36Q-40 见 docs/公寓端/11 表 11-34，Q-41Q-45 见 docs/公寓端/12 表 12-33，Q-46Q-50 见 docs/平台端/10 表 10-21；未决前按默认口径执行。