jcgl-dev/docs/公寓端/10-人脸数据下发管理.md

10 人脸数据下发管理

文档编号：docs/公寓端/10。性质：设计稿（Design Only），不写业务代码、不建表改表、不执行 DDL / DML、不改任何配置。 上位依据：docs/10-架构优化方案-三端拆分.md §5.1 表 5-1（数据分层）、§5.3（同库边界）、§6.1 表 6-1、§6.2（上报信封）、§7.2 / §7.3（设备接入）、§7.5（媒体边界）；docs/公寓端/03 §3.3、表 3-4（设备域）、docs/公寓端/05 §3 / §5 / §6、docs/设计变更/03-三端功能设计修订（CR-02）.md（下称 CR-02）§2 / §3 / §4 / §6 / §10 / §11。 落地权威表述：本文件是"人员人脸主数据在平台 ↔ 公寓 ↔ 设备之间注册、同步、下发、隔离与清理"的唯一权威表述；口径改判与施工单登记见 CR-02 §12（CR-C24 媒体边界、CR-C25 注册链路）。跨端仍为 20 个接口编号、契约 v2-draft、平台不回调公寓（CR-C07）；本模块不新增跨端编号、不新增业务表，采用"复用既有表 + 补列 + 规则"实现。 CR-02 §15 关联（三端一致性）：本文件仍是人脸注册 / 下发 / 刷脸核验的唯一权威表述；应用端与平台端按 §15 表 3-65 同步业务规则、交互流程、权限控制与异常处理，三端状态映射与数据同步机制以 CR-02 §15 表 3-66 为唯一权威（reg_state / regVerdict / upload_state / dispatch_state / faceVerifyState 等枚举不变）。平台统计以 #9 PERSON_REG 同步回执与注册态作辅助数据源，统计结果不回写本模块任何状态；本端不新增上报接口与 bizType。变更点与影响范围见 CR-02 §15 表 3-63。 注册链路 v1.1（CR-C25）：人员注册由签到终端发起申请并上传人脸，值班员在值班台完成人员注册；注册成功后人脸进入公寓服务系统，再分别上传平台与下发公寓内设备。两条同步路径解耦并行、互不阻塞；平台回执不再是注册生效前置。 术语与编号：表名一律小写，字段类型取 apartment/db/mysql/*.sql 口径，枚举为大写下划线字符串（不用数字码、不用 MySQL ENUM）；图表编号 表 10-y / 图 10-y；功能项 AF-01AF-06、接口 N-25N-33（沿用 CR-02 的 N-* 序列）、决策点 Q-30~Q-34。

表 10-1 文档信息

项	内容
文档编号	docs/公寓端/10
文档名称	人脸数据下发管理（注册、平台同步、设备下发、权限隔离、离寓清理、长期驻留）
适用范围	铁路行车公寓叫乘与一卡通系统·公寓端人脸数据管理模块 apt-face
关联文档	docs/公寓端/0009、docs/平台端/0107、docs/设计变更/03 §12、docs/10、docs/11
约束条件	① 人员档案真源在平台，公寓端只持只读快照 + 本地登记流水；② 平台不回调公寓，下行一律"拉"；③ 设备侧一律"设备主动拉取"，服务端不回调设备；④ gyid 数据域锁定；⑤ 状态字段单写入口不变
交付对象	需求评审、三端详细设计、契约冻结、设备联调与验收

表 10-2 修订记录

版本	日期	说明
v1.0	2026-11-09	首次形成：定义 apt-face 模块，覆盖本地注册自动推送平台、平台新增人员下载入库、签到设备查询下发、消费/叫乘设备按设备维度隔离、离寓自动擦除、长期驻留人员长期保留六项功能；明确触发条件、数据范围、同步与清理机制、权限隔离与异常处理；改判人脸特征值跨端传输口径（CR-C24）
v1.1	2026-11-09	注册链路改判（CR-C25）：人员注册改为「签到终端发起注册申请并上传人脸 → 值班员在值班台完成人员注册 → 注册成功后人脸进入公寓服务系统 → 分别上传平台与下发公寓内设备」；新增 reg_state / apply_device_code / confirmed_by / dispatch_state 等状态与留痕列、注册状态机、双路解耦同步规则、N-34~N-37 接口与 Q-35；撤销"平台确认后注册才生效、确认前不得下发设备"的旧前置口径

---

1. 模块定位与对象定义

1.1 两类人脸对象的区分（本模块的关键前提）

表 10-3 人脸相关数据的分类与边界

类别	内容	是否跨端（平台 ↔ 公寓）	是否下发设备	说明
人员主数据人脸	注册照片、特征值、算法标识、特征版本、人员类别	允许（本模块管理对象）	允许（按设备权限范围）	用于身份识别的主数据，必须本地与平台一致；照片原本即由平台对象存储承载（docs/平台端/07 §2 第 2 条、docs/公寓端/09 表 9-1 第 2 行"人员增量（含照片版本）"）
业务过程抓拍	叫乘抓拍、离寓抓拍、签到现场图、平板刷脸比对帧	禁止	不留存于公寓服务端	仍按 docs/10 表 6-3 要点 5、docs/平台端/07 表 7-7：抓拍与录音不出公寓，平台只存索引与计数
识别结果	faceVerifyState、verifiedRyid、比对时间与分数	允许（业务结论）	—	结果上报不带图像（docs/公寓端/05 §9.3 表 5-17、CR-C22）

口径改判：CR-02 CR-C04 / 表 3-13 / 表 3-24 中"人脸特征引用与校验和可传，原图与特征大对象不出公寓"的表述，针对的是业务过程抓拍与识别结果，此前被扩大解释到人员主数据。本模块明确：人员主数据的照片与特征值必须双向同步（见 CR-02 §12 表 3-49 的 CR-C24）；抓拍、录音、签到现场图仍不出公寓，识别结果仍不带图像。不因本次改判放开媒体边界。

1.2 模块与三端职责

表 10-4 apt-face 子域、职责与唯一写入口

子域	端	职责	唯一写入的表 / 列	依赖
apt.face.registry	公寓端	注册申请受理与值班员确认注册：接收签到终端申请（要素 + 人脸）、生成值班台待办、确认后生成正式 ryid 并写入人员主档本地副本	apt_person_face_reg、apt_master_person（经 apt-master-client 事务写）	签到终端 /open/v1/face/reg-requests、duty.ws 值班台
apt.face.sync	公寓端	注册成功后上传平台：#9 PERSON_REG 上行、媒体签名直传、平台回执与版本对齐；以及从平台下载新增人员入库	apt_report_outbox / apt_report_history、apt_master_person、apt_master_version	apt-report、apt-master-client
apt.face.scope	公寓端	设备可见范围规则、人员类别、下发目标集合计算	gy_sb.face_scope_*、apt_master_person.person_category	apt.device.catalog
apt.face.dispatch	公寓端	注册成功后下发公寓内设备：生成下发 / 擦除 / 全量同步指令、回执处理、缓存台账与对账	apt_device_command、gy_sb_xt.face_cache_*	apt.device.command、apt.device.gateway
platform.ingest / platform-master	平台端	接收注册结果并纳入跨公寓人员主档、回同步回执、维护主档增量与媒体签名地址；不做注册准入审批	pl_person_reg_request、平台人员主档	#2 / #9
签到终端 / 设备侧固件	设备	签到终端发起注册申请并上传人脸；其他设备按凭据与范围拉取人员与人脸、本地缓存、执行擦除、上报缓存摘要	设备本地缓存（不在公寓库）	/open/v1/face/**
duty.ws / 值班台	应用端	展示待审申请、由值班员核对并完成人员注册（确认 / 驳回），回写确认留痕	duty_operation_log、duty_manual_action	apt.face.registry（只提交注册命令）

依赖方向单向：apt.face.registry → apt.face.sync / apt.face.dispatch；apt.face.dispatch → apt.device.command；值班台只提交注册命令、不直接写业务表；apt-face 不被 apt.duty.* 反向依赖。所有业务模块对 apt_master_person 仍只读（docs/公寓端/03 表 3-1、docs/设计变更/01 不变式 A），唯一写入口是注册确认时 apt-master-client 的事务写。

1.3 与既有流程的关系

• 注册链路按 CR-C25 改判为「签到终端申请 → 值班员注册 → 入公寓服务系统 → 分别上传平台 / 下发设备」；CR-02 F-F 的旧"平台确认 → #2 下行生效"流程由 §12 F-J 覆盖，历史行按覆盖关系理解。
• 主数据下行仍沿用 docs/公寓端/05 §5（版本校验、事务写快照、apt_master_version(APPLIED)），本模块补充"媒体下载、校验和校验、增量变更触发下发 / 擦除"；平台 personRegVerdicts[] 语义改为同步回执，不决定本地注册是否生效。
• 设备接入仍沿用 docs/公寓端/05 §3（注册、心跳、取指令、ACK），本模块补充"人脸指令类型与缓存摘要"。
• 离寓仍以 apt-stay 为唯一写入口（gy_jcxx.finish_ly / gygl_ly_event），本模块只消费离寓事实生成擦除指令，不改叫乘状态字段。

---

2. 数据模型（复用既有表 + 补列，不新增业务表）

表 10-5 复用表清单

表	现有用途	本模块用途	唯一写入模块	owner
apt_master_person	平台下发人员只读快照	人员人脸主档的本地权威副本（照片、特征值引用、类别、版本）；设备下发唯一取数源	apt-master-client	platform-down
apt_person_face_reg	本地人员/人脸登记流水	注册申请流水（签到终端来源、值班员确认留痕、注册状态机）、上行同步状态、设备下发状态、平台同步回执	apt.face.registry	apartment
pl_person_reg_request	平台接收注册结果	平台侧人员人脸主档登记与同步回执（ACCEPTED / REJECTED），不做注册准入审批	platform-ingest	platform
gy_sb	设备档案	设备类别与人脸可见范围	apt.device.catalog	apartment
gy_sb_xt	设备心跳与版本状态	设备人脸缓存版本、数量、摘要与最后同步时间	apt.device.gateway	apartment
apt_device_command	设备指令队列（PENDING/SENT/ACKED/EXPIRED/FAILED）	下发 / 擦除 / 全量同步 / 范围重载指令与回执	apt.device.command	apartment
apt_report_outbox / apt_report_history	上行队列与终态流水	PERSON_REG 上行、续报与对账	apt.report.outbox	apartment
apt_master_version	快照版本	(gyid, PERSON, source, version) 人员增量水位	apt-master-client	apartment

为什么不加新表：docs/11 指出既有库 40 表 / 0 主键 / 0 索引、单表 70 列的上帝表问题；人脸主档已有 apt_master_person，指令已有 apt_device_command，设备状态已有 gy_sb_xt。新增独立表会形成第三份人员真源与第四份指令队列，反而破坏一致性。补列均为设计定义，DDL 待阶段二契约冻结评审通过后执行。

表 10-6 补列定义（按表分组；均为设计定义）

表	补列	类型	约束 / 默认	说明
apt_master_person	photo_ref	varchar(512)	可空	本地照片引用（平台对象键 / 本地缓存路径），不存图片二进制
	photo_checksum	varchar(128)	可空	照片 SHA-256，下载后校验
	feature_ref	varchar(512)	可空	特征值加密文件引用（不入库大对象）
	feature_checksum	varchar(128)	可空	特征值校验和
	feature_algo	varchar(32)	可空	算法标识（如厂商/版本），设备兼容性判定
	feature_version	bigint	默认 0	特征版本，单调递增，下发幂等键组成部分
	person_category	varchar(20)	默认 TRANSIENT	TRANSIENT（临时入住/乘务）/ LONG_TERM（保洁/巡检/管理长期驻留）
	face_sync_state	varchar(20)	默认 PENDING	PENDING / SYNCED / FAILED / STALE；媒体下载与校验结果
	face_platform_version	bigint	默认 0	平台侧版本，与本地对账
apt_person_face_reg	photo_ref / feature_ref	varchar(512) ×2	NOT NULL	签到终端上传的人脸媒体引用；补 photo_checksum / feature_checksum 校验和列
	feature_algo / feature_version	varchar(32) / bigint	默认 1	算法与版本
	person_category	varchar(20)	默认 TRANSIENT	值班员确认时可改判为 LONG_TERM
	reg_state	varchar(20)	默认 APPLIED	APPLIED / CONFIRMED / REJECTED / ARCHIVED；注册状态机（表 10-11）
	apply_device_code / applied_at	varchar(64) / datetime(3)	NOT NULL	发起申请的签到终端与申请时间
	confirmed_ryid / confirmed_by / confirmed_at	varchar(64) / varchar(64) / datetime(3)	可空	值班员确认时生成正式 ryid 并留痕
	reject_reason / verdict	varchar(256) / varchar(20)	可空 / 默认 PENDING	值班员驳回理由；verdict 只记平台同步回执
	upload_state / dispatch_state	varchar(20) ×2	默认 PENDING	上传平台与下发设备两条独立状态链，互不阻塞（CR-C25）
	platform_version	bigint	默认 0	平台同步回执后回填
gy_sb	device_class	varchar(20)	默认 OTHER	CHECKIN / CONSUME / CALL / TABLET / OTHER
	face_scope_type	varchar(24)	默认 NONE	ALL_ACTIVE / ROOM_BOUND / CATEGORY_WHITELIST / NONE
	face_scope_value	varchar(256)	可空	房间号 / 类别白名单 / 区域编码
	face_cache_enabled	tinyint(1)	默认 0	是否允许缓存人脸；TABLET 等按任务临时拉取的设备可为 0
gy_sb_xt	face_cache_version	bigint	默认 0	设备上报的缓存版本
	face_cache_count	int	默认 0	设备缓存人员数
	face_cache_hash	varchar(128)	可空	设备缓存集合摘要（ryid + feature_version 有序哈希）
	last_face_sync_at	datetime(3)	可空	最后一次成功同步 / 擦除回执时间
apt_device_command	biz_type	varchar(30)	默认 GENERIC	FACE_ISSUE / FACE_ERASE / FACE_FULL_SYNC / FACE_SCOPE_RELOAD
	biz_id	varchar(64)	可空	ryid（单人）或批次 ID（全量）
	biz_version	bigint	默认 1	与 feature_version 对齐；更正时 +1
	payload	json	可空	下发字段集、擦除原因、媒体签名地址等（若既有表无此列则补）
pl_person_reg_request	photo_ref / feature_ref	string(512) ×2	可空	平台侧媒体引用
	photo_checksum / feature_checksum	string(128) ×2	可空	校验和
	feature_algo / feature_version / person_category	string(32) / long / enum_s	默认 1 / TRANSIENT	与公寓端同字典

表 10-7 枚举字典

枚举	取值	说明
regState	APPLIED / CONFIRMED / REJECTED / ARCHIVED	注册状态机；只有 CONFIRMED 才使人员进入公寓服务系统
platformVerdict	PENDING / ACCEPTED / REJECTED	平台同步回执，不是注册批准；REJECTED 触发告警与值班台待办
uploadState / dispatchState	PENDING / SENT(ISSUED) / ACKED / FAILED / DEAD	上传平台与下发设备两条独立状态链，互不阻塞
personCategory	TRANSIENT / LONG_TERM	临时入住 / 长期驻留；决定是否参与离寓擦除
faceSyncState	PENDING / SYNCED / FAILED / STALE	媒体与版本同步结果
deviceClass	CHECKIN / CONSUME / CALL / TABLET / OTHER	设备类别，决定可见范围
faceScopeType	ALL_ACTIVE / ROOM_BOUND / CATEGORY_WHITELIST / NONE	设备可见范围规则
faceBizType	FACE_ISSUE / FACE_ERASE / FACE_FULL_SYNC / FACE_SCOPE_RELOAD	人脸指令类型
eraseReason	CHECKOUT / PLATFORM_DELETED / CATEGORY_REVOKED / MANUAL / RECONCILE	擦除原因，进审计

---

3. 数据流向总览

图 10-1 平台 ↔ 公寓 ↔ 设备的人脸数据流向

flowchart LR
    subgraph DUTYUI["应用端值班台"]
        DUTY["值班员审核并<br/>完成人员注册"]
    end
    subgraph DEV["公寓内设备（按类别隔离）"]
        CK["签到终端 CHECKIN<br/>发起注册申请 / 上传人脸"]
        CO["消费设备 CONSUME"]
        CL["叫乘设备 CALL"]
    end
    subgraph AP["公寓服务系统（apt-face）"]
        REG["apt.face.registry<br/>apt_person_face_reg（APPLIED → CONFIRMED）"]
        MASTER["apt_master_person<br/>本地权威副本（注册成功后入档）"]
        SYN["apt.face.sync<br/>outbox / 快照版本"]
        SCOPE["apt.face.scope<br/>gy_sb.face_scope_*"]
        DISP["apt.face.dispatch<br/>apt_device_command"]
    end
    subgraph PL["平台端"]
        PM["人员人脸主档<br/>pl_person_reg_request / 平台主档"]
        PO["对象存储<br/>照片 / 特征值（仅人员主数据）"]
    end
    CK -->|AF-01 ① REG_APPLY 申请 + 人脸| REG
    REG -->|② 生成值班台待办| DUTY
    DUTY -->|③ 值班员 CONFIRM 完成注册| REG
    REG -->|④ 注册成功，人脸进入公寓服务系统| MASTER
    MASTER -->|⑤a 上传平台| SYN
    SYN -->|#9 PERSON_REG + 媒体签名直传| PM
    SYN -->|媒体本体| PO
    PM -->|AF-02 #2 人员增量 + 同步回执（拉）| SYN
    PO -->|短期签名下载| SYN
    MASTER -->|⑤b 下发公寓内设备| SCOPE
    SCOPE -->|计算目标设备集合| DISP
    DISP -->|AF-03/04 FACE_ISSUE| CK
    DISP -->|AF-04 FACE_ISSUE（最小字段）| CO
    DISP -->|AF-04 FACE_ISSUE（最小字段）| CL
    CK -->|AF-05 缓存摘要 / ACK| DISP
    CO -->|AF-05 缓存摘要 / ACK| DISP
    CL -->|AF-05 缓存摘要 / ACK| DISP
    DISP -->|AF-05 FACE_ERASE（仅 TRANSIENT 离寓）| CO
    DISP -->|AF-05 FACE_ERASE（仅 TRANSIENT 离寓）| CL
    CK -.->|AF-06 LONG_TERM 长期保留，不擦除| CK

表 10-8 六条数据流与处理规则

编号	功能	源 → 目的	触发	数据范围	机制	落点
AF-01	签到终端申请 → 值班员注册 → 入公寓服务系统 → 分别同步	签到终端 → 值班台 → apt-face → 平台 / 公寓内设备	签到终端提交 REG_APPLY；注册生效点为值班员 CONFIRM	人员要素 + 照片 + 特征值 + 算法/版本 + 申请设备来源	申请落流水（APPLIED，不进主档）→ 值班台待办 → 值班员确认（生成 ryid、CONFIRMED）→ 事务写 apt_master_person → 两条解耦路径：#9 PERSON_REG 上传平台 / FACE_ISSUE 下发设备	apt_person_face_reg、apt_master_person、apt_report_outbox、apt_device_command、pl_person_reg_request
AF-02	平台新增人员下载入库	平台 → apt-face → 本地快照	定时/增量拉取 #2、version 递增	新增/变更人员 + 照片 + 特征值 + 类别	拉增量 → 下载媒体 → 校验 checksum → 事务写快照 + 版本	apt_master_person、apt_master_version
AF-03	签到设备查询与下发	apt_master_person → 签到设备	人员在册变更 / 设备上线 / 手工全量	全部有效人员（TRANSIENT 在寓 + LONG_TERM），含照片与特征值	按 feature_version 增量下发，媒体走设备侧签名 URL，回执后更新台账	apt_device_command、gy_sb_xt
AF-04	消费/叫乘设备按设备维度隔离	apt_master_person → 消费/叫乘设备	同 AF-03，但按范围过滤	仅本设备权限范围内的在寓 TRANSIENT + 授权 LONG_TERM，最小必要字段（不含照片）	服务端强制拼范围条件，设备不得按 ryid 任意查询	gy_sb.face_scope_*、N-30
AF-05	离寓自动擦除	离寓事实 → 消费/叫乘设备	finish_ly='1' / gygl_ly_event(CHECKOUT) / 平台 deleted=1	仅 TRANSIENT 且已下发过的设备；LONG_TERM 不擦除	生成 FACE_ERASE → ACK 回执 → 重投/全量同步兜底 → 缓存摘要对账	apt_device_command、gy_sb_xt
AF-06	长期驻留人员长期保留	平台/本地配置 → 设备独立分区	person_category=LONG_TERM 生效/撤销	保洁、巡检、管理等长期驻留人员	独立缓存分区、独立版本、不参与离寓擦除；撤销需二次确认	apt_master_person.person_category、apt_clean_staff

四条硬约束：① 平台不回调公寓，下行一律"拉"（CR-C07）；② 公寓不回调设备，设备一律主动拉取指令与媒体（docs/公寓端/05 §3 表 5-3）；③ 设备下发唯一取数源是 apt_master_person，注册申请未获值班员确认（reg_state=APPLIED）不得下发设备、不得参与运安匹配（40914）；④ 注册成功后"上传平台"与"下发设备"是两条独立状态链，平台回执不是下发前置、设备 ACK 也不是平台上报前置（CR-C25）。

---

4. AF-01 注册申请、值班员注册与平台 / 设备分别同步

本节是注册链路的唯一权威表述（CR-C25）。注册由签到终端发起申请并上传人脸，值班员在值班台完成人员注册；注册成功后人脸进入公寓服务系统，再分别上传平台与下发公寓内设备。CR-02 F-F 的旧"平台确认 → #2 下行生效"流程由本节与 §12 F-J 覆盖。

4.1 触发条件与数据范围

表 10-9 三段触发条件与数据范围

阶段	主体 / 触发	数据范围	前置与不触发
① 注册申请	签到终端（N-34）提交 REG_APPLY：现场采集人员要素 + 人脸并上传	gyid、work_no、name、unit_code、照片、特征值（或仅照片由公寓端按 feature_algo 提取）、apply_device_code、occurred_at	媒体缺失 / 格式不支持 / checksum 不符 → 40919 / 40920 拒收；同一 work_no 已有未决申请 → 返回原 regId（幂等）；已有 CONFIRMED 人员 → 40918；不进主档、不下发设备、不上报平台
② 值班员注册	值班台（N-35 / N-36）出现待办，值班员核对要素与照片、可修正 unit_code / person_category，点"确认注册"	regId、confirmed_ryid（确认时生成）、confirmed_by、confirmed_at、person_category、feature_algo 兼容性判定	需 duty:person:reg 权限 + 二次确认；驳回（N-37）须填 reject_reason；确认前参与运安匹配 / 下发设备 → 40914
③ 注册成功后分别同步	reg_state=CONFIRMED 且 apt_master_person 事务写成功即自动触发两条路径	人员主档全量要素 + 照片 / 特征值引用与校验和 + feature_version + ryid	无需人工点"同步"；平台不可达不阻塞设备下发，设备离线不阻塞平台上报

注册生效点：值班员 CONFIRM，不是平台回执。平台 personRegVerdicts[] / verdict 自此只作主档同步回执，不决定人员是否在公寓服务系统生效。

4.2 端到端时序

图 10-2 注册申请 → 值班员注册 → 入公寓服务系统 → 分别上传平台 / 下发设备

sequenceDiagram
    autonumber
    participant CK as 签到终端 CHECKIN
    participant R as apt.face.registry
    participant D as 值班台（应用端 /duty）
    participant M as apt_master_person
    participant S as apt.face.sync / outbox
    participant P as 平台端
    participant W as apt.face.dispatch
    participant DV as 公寓内设备（签到/消费/叫乘）

    CK->>R: ① REG_APPLY（要素 + 人脸照片 / 特征值，N-34）
    R->>R: 校验 checksum，加密落盘 → photo_ref / feature_ref
    R->>R: 写 apt_person_face_reg（reg_state=APPLIED, local_only=1）
    R->>D: ② 推待办 reg.apply（不写主档、不下发）
    D->>D: 值班员核对要素与照片、补全单位 / 类别
    D->>R: ③ CONFIRM（duty:person:reg + 二次确认，N-36）
    R->>R: 生成 confirmed_ryid、reg_state=CONFIRMED、local_only=0
    R->>M: ④ 事务写 apt_master_person + apt_master_version（人脸进入公寓服务系统）
    par ⑤a 上传平台
        R->>S: 提交同步命令（upload_state=PENDING）
        S->>P: 媒体签名直传 + #9 PERSON_REG（regId, ryid, 引用, checksum, algo, version）
        P->>P: 校验工号唯一性 / checksum → 纳入跨公寓主档
        P-->>S: 同步回执 ACCEPTED / REJECTED + platform_version
        S->>R: 回填 upload_state / verdict / platform_version
    and ⑤b 下发公寓内设备
        R->>W: 提交下发命令（dispatch_state=PENDING）
        W->>W: 按 gy_sb.face_scope_* 计算目标设备集合
        W->>DV: FACE_ISSUE（设备心跳主动拉取，N-30 / N-31）
        DV-->>W: ACK + face_cache_hash / count / version（N-32 / N-33）
        W->>R: 回填 dispatch_state=ACKED
    end
    Note over S,W: 两条路径独立幂等、互不阻塞；平台不可达 / 设备离线各自排队续报

4.3 处理步骤与规则

表 10-10 处理步骤与规则（A 申请 / B 值班员注册 / C 双路同步）

步	阶段	主体	动作	落表	异常 / 补偿
1	A	签到终端	采集人员要素与人脸，按设备凭据 + HMAC 提交 REG_APPLY	设备侧采集缓存	凭据失效 / 越 gyid → 40301
2	A	apt.face.registry	校验媒体完整性与 work_no 唯一性；加密落盘生成引用与校验和	apt_person_face_reg(APPLIED)	媒体缺失 40919、校验不符 40920、已注册 40918；未决重复申请返回原 regId
3	A	duty.ws	生成值班台待办 reg.apply，展示要素、照片、申请设备与时间	duty_operation_log	推送失败靠 60s 兜底轮询；待办不重复生成
4	B	值班员	核对并修正要素、person_category，确认或驳回注册	duty_manual_action、duty_operation_log	无权限 40301；驳回须填理由，媒体按 Q-32 保留期清理，不生成 ryid
5	B	apt.face.registry	确认时生成 confirmed_ryid、置 CONFIRMED / local_only=0；apt-master-client 事务写主档副本	apt_person_face_reg、apt_master_person、apt_master_version	事务失败整体回滚，注册态保持 APPLIED；算法不兼容 40921 可确认但标记不下发
6	C-a	apt.face.sync	媒体签名直传（≤ 10 min）+ #9 PERSON_REG 上行	apt_report_outbox / apt_report_history、pl_person_reg_request	断网 → outbox PENDING，恢复后复用原 idempotencyKey 续报；不阻塞 C-b
7	C-a	平台端	校验工号唯一性与 checksum，纳入跨公寓主档并回 ACCEPTED / REJECTED + platform_version	平台人员主档	回执由 #2 拉取；REJECTED 只告警 + 待办，不回滚本地注册与已下发设备（Q-35）
8	C-b	apt.face.scope / apt.face.dispatch	按设备类别与 face_scope_* 计算目标集合，生成 FACE_ISSUE	apt_device_command	设备离线 → 指令排队，上线心跳取走；范围为空则不下发并记审计
9	C-b	公寓内设备	按 cursor + version 拉取人员与人脸、校验 hash 后写本地缓存并 ACK	gy_sb_xt.face_cache_*	回执丢失按 commandId 幂等重投；摘要不一致 → FACE_FULL_SYNC
10	C	apt.face.registry	分别维护 upload_state / dispatch_state；两条链路各自终态，互不改写	apt_person_face_reg	任一条 FAILED 只告警并独立重试，不把另一条回退为 PENDING

4.4 注册状态机与一致性

注册状态机（reg_state，唯一写入口 apt.face.registry）：

• APPLIED → CONFIRMED（值班员确认，生成 ryid 并入档）或 REJECTED（值班员驳回，写 reject_reason）；
• CONFIRMED 之后 upload_state / dispatch_state 各自 PENDING → SENT / ISSUED → ACKED，失败转 FAILED 重试、最终 DEAD 转人工；verdict 由平台回执单独回填；
• REJECTED / ARCHIVED 为终态，不回写 APPLIED；媒体按 Q-32 保留期清理并留审计。

表 10-11 注册态与平台 / 设备一致性规则

规则	口径
真源	平台仍是跨公寓人员主档真源；公寓 apt_master_person 是注册成功后写入的本地权威副本，apt_person_face_reg 只是申请与同步流水，三者不互为真源
生效点	值班员 CONFIRM，平台确认不再是前置（CR-C25）；平台版本高于本地时按 platform_version 覆盖本地主档，不撤销注册事实
双路解耦	上传平台（outbox）与下发设备（apt_device_command）各自幂等、各自重试；两条状态链独立落 apt_person_face_reg，任一失败不影响另一条
版本	feature_version（本地）与 face_platform_version（平台）双向携带；平台版本高则以平台为准覆盖并触发重下发，本地版本高则触发补传
幂等	申请 regId + work_no；上行 idempotencyKey = hash(gyid + PERSON_REG + regId + bizVersion)；设备 commandId = hash(gyid + deviceCode + FACE_ISSUE + ryid + bizVersion)；媒体按 checksum 去重
确认前	reg_state=APPLIED 的人员不得下发设备、不得参与运安匹配（40914）、不参与叫乘
平台驳回	本地注册保留、verdict=REJECTED，告警 + 值班台待办 + 暂停后续下发；是否自动擦除已下发缓存由 Q-35 拍板，未决默认不自动擦除
冲突	同一 work_no 平台已有档案 → 平台回 REJECTED(DUPLICATE_WORK_NO)，本地保留注册事实与审计，不自动覆盖平台记录，由值班台人工归并
对账	每日按 (gyid, ryid, feature_version, checksum) 比对本地与平台 count/sum/max(version)；差异写告警并触发重拉 #2 或补传 #9

---

5. AF-02 从平台查询、下载新增人员并完成本地入库

表 10-12 触发条件与数据范围

项	口径
触发	① apt-master-client 定时拉取 #2 GET /platform/v1/master/persons?gyId&cursor&version；② 心跳/版本变更发现 version 递增；③ 管理端 POST /apt/face/persons/commands（FULL_SYNC）手工触发；④ 收到 personRegVerdicts[] 同步回执后对齐 platform_version；⑤ 值班员注册成功后的首次平台增量对齐（已由 AF-01 写入的 ryid 不重复入库）
数据范围	增量人员：ryid、work_no、姓名、unit_code、person_category、照片、特征值、feature_algo、feature_version、photo_checksum / feature_checksum、deleted 标记、platform_version
不下载	业务抓拍、录音、叫乘现场图；这些仍不出公寓

表 10-13 入库步骤与规则

步	动作	规则	异常
1	拉 #2 增量	比较 apt_master_version(PERSON) 的 version，仅处理 version > 本地；重复/旧版本丢弃并记日志	版本回退 → 告警并请求全量
2	校验响应	校验 gyid 一致、checksum 字段齐备、feature_algo 在设备兼容白名单	缺字段 → 不入库，整批重试
3	下载媒体	用 mediaUrls[] 短期签名地址下载照片与特征值；先下载到临时区、校验 checksum 通过后才入正式引用	超时/校验不符 → 丢弃临时文件、退避重试、face_sync_state=FAILED
4	事务写快照	一个事务内 upsert apt_master_person（按 ryid）+ 更新 apt_master_version(APPLIED) + 记 duty_operation_log	任一步失败整体回滚，保留旧快照
5	生效判定	face_sync_state=SYNCED 才允许下发设备；deleted=1 的人员触发 AF-05 擦除	半同步状态不得下发，避免设备拿到不完整数据
6	通知依赖	通知 apt.face.scope 重算目标设备集合、duty.ws 推人员变更（沿用 §5「通知依赖模块刷新缓存」）	通知失败不影响快照，靠 60s 兜底轮询

表 10-14 入库校验清单

校验	判据	失败处理
必要字段	ryid、姓名、person_category、feature_version、checksum 齐备	40920 APT_FACE_MEDIA_CHECKSUM_MISMATCH 或整批重试
媒体完整性	SHA-256(photo) == photo_checksum、SHA-256(feature) == feature_checksum	丢弃 + 重下，连续 3 次告警
算法兼容	feature_algo 在 apt.face.algo.whitelist 内	40921 APT_FACE_ALGO_UNSUPPORTED，人员入库但不下发设备
版本单调	feature_version >= 本地同 ryid 版本	旧版本丢弃；相同版本但内容不同 → 以 checksum 判冲突并告警
大小上限	单条特征值 ≤ face.feature.maxBytes、照片 ≤ face.photo.maxBytes	40922 APT_FACE_MEDIA_TOO_LARGE
gyid 隔离	所有记录 gyid 等于会话/设备所属公寓	越 gyid 直接 40301

---

6. AF-03 签到设备查询人员及人脸信息并由公寓端下发

表 10-15 触发条件、范围与下发规则

项	口径
触发	① AF-01 值班员注册成功且 apt_master_person 入档（reg_state=CONFIRMED、face_sync_state=SYNCED）或 AF-02 平台增量入库完成；② 签到设备注册/上线或心跳报 face_cache_version 落后；③ 管理端 RE_ISSUE / FULL_SYNC 命令；④ 对账发现缓存摘要不一致
目标设备	gy_sb.device_class='CHECKIN' 且 face_cache_enabled=1、enabled=1、deleted=0
数据范围	全部有效人员：在寓 TRANSIENT（finish_ly='0'）+ 全部 LONG_TERM；字段含 ryid、姓名、person_category、照片、特征值、feature_algo、feature_version、checksum
下发方式	设备按 cursor + version 调用 GET /open/v1/face/persons（N-30）主动拉取；公寓端同时生成 FACE_ISSUE 指令入 apt_device_command，由设备心跳取走；媒体走 GET /open/v1/face/media/{ref}（N-31，短期签名、设备凭据鉴权）
完整性保证	响应按 face_scope_type=ALL_ACTIVE 构造，服务端强制拼接 gyid + (在寓 OR LONG_TERM) + deleted=0；返回 total、cursor、featureVersion 与集合 hash；设备按 hash 校验完整性，不符则请求 FACE_FULL_SYNC
回执	设备逐条或批量 POST /open/v1/face/ack（N-32）上报 commandId + result；公寓端更新 apt_device_command.state=ACKED 与 gy_sb_xt.face_cache_*
异常	设备离线 → 指令排队（PENDING），上线心跳取走；回执丢失 → 按 commandId 幂等重投，设备重复执行无副作用；媒体下载失败 → 校验和不通过不写缓存，重试并告警

下发内容准确完整的判据：apt_master_person.face_sync_state=SYNCED + feature_version 单调 + checksum 校验通过 + 服务端范围过滤 + 设备 hash 回执一致，五项缺一即视为未完成，不标记 ACKED。

---

7. AF-04 消费设备、叫乘设备按设备维度的数据隔离

表 10-16 设备类别 → 可见范围矩阵（服务端强制，设备不可覆盖）

device_class	face_scope_type	可见人员范围	可见字段	缓存
CHECKIN 签到设备	ALL_ACTIVE	全部有效人员（在寓 TRANSIENT + LONG_TERM）	全字段（含照片、特征值）	允许（含 LONG_TERM 独立分区）
CONSUME 消费设备	ROOM_BOUND 或 CATEGORY_WHITELIST	本设备绑定房间/区域的在寓 TRANSIENT + 该设备白名单内的 LONG_TERM	最小必要字段：ryid、姓名、person_category、feature_ref / 特征值、feature_version；不含照片	允许；离寓即擦除 TRANSIENT
CALL 叫乘设备	ROOM_BOUND	本设备绑定房间的在寓 TRANSIENT + 授权 LONG_TERM	同 CONSUME	允许；离寓即擦除 TRANSIENT
TABLET 平板	NONE（按任务临时）	仅当前叫乘任务涉及人员（按 jcid / taskId）	识别所需特征值，不含照片	默认 face_cache_enabled=0，任务结束即弃用
OTHER	NONE	不可见	—	禁止

表 10-17 三重隔离校验（任一不通过即拒绝）

层	校验	失败返回
1 设备身份	deviceCode + 激活凭据 + HMAC(secret, body) + ±5 min 时间窗 + nonce 去重；停用/删除设备直接拒绝	40301 APT_FORBIDDEN
2 数据域	gyid 只从设备凭据解析，不接受请求参数；所有 SQL 必带 gyid	40301
3 范围过滤	服务端按 gy_sb.face_scope_type/value + device_class 拼接 WHERE；设备不得传 ryid、roomNo 作为任意查询条件，只能传 cursor / version；越范围人员自动排除，不返回"存在但无权"	40917 APT_FACE_SCOPE_DENIED

补充规则：

1. 最小必要字段：消费/叫乘设备不返回照片；特征值按 feature_algo 白名单过滤，不兼容的算法不下发并告警。
2. 范围变更：face_scope_type/value 变更时生成 FACE_SCOPE_RELOAD 指令；设备须先清空旧范围缓存再按新范围全量拉取，避免残留越权数据。
3. 审计：每次设备拉取记 deviceCode、gyid、cursor、返回条数、hash 与结果，写 duty_operation_log；越权尝试单独计数并进 #11 设备摘要。
4. 跨公寓：设备凭据绑定单一 gyid，跨公寓查询一律拒绝；平台不下发其他公寓人员。

---

8. AF-05 离寓后自动擦除设备缓存

表 10-18 触发条件与数据范围

项	口径
触发	① apt-stay 产生离寓事实：gy_jcxx.finish_ly='1' 或 gygl_ly_event(CHECKOUT) 落库；② 值班员 MARK_LEAVE 命令生效；③ #2 下行人员 deleted=1；④ 换乘/换房导致原房间不再在寓；⑤ 平台 person_category 由 LONG_TERM 改回 TRANSIENT 且已离寓
目标人员	仅 person_category=TRANSIENT 且已离寓的人员；LONG_TERM 不擦除
目标设备	该人员曾成功下发过的 CONSUME / CALL / TABLET 设备集合（由 apt_device_command 中 biz_type=FACE_ISSUE 且 state=ACKED 反查），以及其绑定房间对应的设备
不擦除	CHECKIN 签到设备的主档（签到需保留全部有效人员用于下次入住比对，按 deleted 标记自然失效）、LONG_TERM 分区、apt_master_person 快照本身（快照只标 deleted，不物理删）
时限	离寓事实落库后 ≤ 30s 生成擦除指令；≤ 5 min 完成 ACK；超时告警并升级为 FACE_FULL_SYNC（Q-30）

表 10-19 擦除步骤与处理规则

步	主体	动作	落表	异常 / 补偿
1	apt.face.scope	消费离寓事件，按 ryid 反查已下发设备集合	apt_device_command、gy_sb	查不到下发记录 → 仍按绑定房间生成兜底擦除，避免漏擦
2	apt.face.dispatch	生成 FACE_ERASE 指令（biz_id=ryid、erase_reason=CHECKOUT、biz_version+1）；commandId = hash(gyid, deviceCode, FACE_ERASE, ryid, biz_version)	apt_device_command(PENDING)	同键幂等，重复离寓事件不生成第二条
3	设备（心跳取指令 / N-30 erase[]）	删除本地缓存中该 ryid 的照片、特征值、比对索引	设备本地	设备离线 → 指令排队；上线后优先取 FACE_ERASE（P0 优先，重投 5 次不过期，沿用 docs/公寓端/05 表 5-3）
4	设备 → N-32	上送 ACK（erased=true + 缓存新 hash / count / version）	apt_device_command(ACKED)、gy_sb_xt	回执丢失 → 按 commandId 幂等重投，设备重复执行无副作用
5	apt.face.dispatch	更新设备缓存台账；比对期望集合与上报 hash	gy_sb_xt.face_cache_*	不一致 → 生成 FACE_FULL_SYNC 覆盖式全量同步（隐含擦除）
6	审计与告警	记 duty_operation_log（eraseReason、设备、时间、结果），失败项进 #11 摘要与盯控告警	duty_operation_log、apt_report_outbox	超时未完成 → P1 告警 + 值班台横幅，人工可发 ERASE 命令重试

表 10-20 兜底与对账

机制	口径
缓存摘要对账	设备每次心跳上送 face_cache_hash / count / version（N-33）；公寓端按"权限范围 × 在寓状态 × LONG_TERM 白名单"计算期望集合并比对，每 30 min 全量比对一次
全量同步	差异 → FACE_FULL_SYNC：设备先清空对应分区，再按最新范围全量拉取；比逐条擦除更可靠，作为最终兜底
断网	离寓事实与擦除指令先落本地库；设备离线期间保留缓存，但设备侧须在检测到离线时禁用本地人脸放行（Q-31），恢复后立即取擦除指令
误擦恢复	人员重新入住 → 生成新 FACE_ISSUE；不依赖"恢复缓存"，按最新快照重新下发
时效	擦除指令 EXPIRED 前一直重投；超过 Q-30 时限升级为 P1 告警，不自动放弃

---

9. AF-06 长期驻留人员数据的长期保留与区分管理

表 10-21 区分管理规则

维度	TRANSIENT（临时入住/乘务）	LONG_TERM（保洁、巡检、管理等长期驻留）
标识来源	#2 下发 person_category 默认 TRANSIENT	#2 下发或管理端按 apt_clean_staff / 巡检与管理人员名册标注，需 duty:face:category 权限 + 二次确认
设备缓存分区	TRANSIENT 分区	LONG_TERM 独立分区，与临时人员分区物理/逻辑隔离
离寓擦除	参与 AF-05，离寓即擦除	不参与；仅在资格撤销、人员 deleted=1、设备退役/范围变更时擦除
可见范围	按设备绑定房间/区域在寓状态	按 CATEGORY_WHITELIST 授权；未列入白名单的设备不可见，即使同为长期人员
版本与对账	随人员主档版本	独立 LONG_TERM 集合版本，对账时与 TRANSIENT 分开计算 hash
有效期	随入住/离寓周期	长期有效；每季度随平台主档全量核对一次，发现失联/离职由平台 deleted 触发擦除
撤销	—	平台 person_category 变更为 TRANSIENT 或 deleted=1 → 生成 FACE_ERASE（erase_reason=CATEGORY_REVOKED），需管理端二次确认后执行
审计	duty_operation_log	同左，且类别变更单独记一条（操作人、理由、前后值）

与其他人员区分的最小实现：apt_master_person.person_category + 设备侧 cache_partition + 独立的 face_cache_hash_long_term。三者共同保证"长期保留"不会被离寓清理误删，也不会被消费/叫乘设备越权看到。

---

10. 同步、清理与一致性机制

表 10-22 版本、幂等与顺序

项	口径
版本	feature_version（人员特征）、face_platform_version（平台）、face_cache_version（设备）三级单调；同 ryid 只接受 version >= 本地 的变更
幂等键	上行 idempotencyKey = hash(gyid + bizType + bizId + bizVersion)；设备指令 commandId = hash(gyid + deviceCode + bizType + bizId + bizVersion)；媒体按 checksum 去重
注册双路	值班员 CONFIRM 后，upload_state（#9 上行平台）与 dispatch_state（FACE_ISSUE 下发设备）各自 PENDING → SENT / ISSUED → ACKED；两条链独立幂等、独立重试、互不阻塞，平台回执不是下发前置（CR-C25、§4.4）
顺序	同一 ryid 按 bizVersion 单调；FACE_ISSUE 与 FACE_ERASE 并发时以离寓事件为准，擦除优先，迟到下发记 IGNORED
事务	快照写入与 apt_master_version 更新在同一事务；媒体下载失败不产生半条记录
断网	本地先落业务表 + outbox；恢复后"先派 outbox、再拉 #7"（CR-01 §2.9 顺序不变），随后补拉 #2 人员增量
归日	跨端上报以 serverReceivedAt 为准（沿用 docs/平台端/06 §6）

表 10-23 一致性对账

层级	对账对象	周期	差异处理
平台 ↔ 公寓	(gyid, ryid, feature_version, checksum) 的 count/sum/max(version)	每日 + 每次 #2 增量	平台版本高 → 重拉并重下发；本地版本高 → 补传 PERSON_REG
公寓 ↔ 设备	期望集合 hash vs gy_sb_xt.face_cache_hash	每次心跳 + 每 30 min 全量	差异 → FACE_FULL_SYNC；持续差异 → P1 告警
人员状态 ↔ 缓存	在寓状态 / person_category / deleted	每次离寓事件 + 每日	多余缓存 → FACE_ERASE；缺失 → FACE_ISSUE
媒体完整性	photo_checksum / feature_checksum	每次下载/下发	不符 → 丢弃重下，连续 3 次告警

---

11. 权限隔离与安全

表 10-24 权限与安全要求

#	要求
1	双校验：管理端 /apt/face/** 走 RuoYi 会话 + @PreAuthorize，前端 v-hasPermi 同码（apt:face:list / apt:face:dispatch / apt:face:scope / apt:face:category / apt:face:reconcile）；值班台 /duty/person/face-reg/** 走 duty:person:reg + 二次确认；设备侧 /open/v1/face/** 走设备凭据 + HMAC + 时间窗 + nonce
2	gyid 锁定：gyid 只从会话/设备凭据解析，不接受请求参数；所有查询/写入 SQL 必带 gyid，唯一键以 gyid 打头
3	服务端过滤：设备可见范围一律在服务端按 gy_sb.face_scope_* 拼接，设备不得指定 ryid / roomNo 越权查询；越权 40917
4	媒体保护：照片与特征值本地加密落盘，库内只存引用与校验和；跨端与设备侧媒体地址短期签名（≤ 10 min）、仅内网、一次一密；不进平台对象存储的是抓拍/录音，人员主数据媒体按本模块允许跨端
5	最小必要：消费/叫乘设备不返回照片；TABLET 不长期缓存；签到设备才拿全字段
6	审计：注册申请、值班员确认/驳回、平台同步、入库、下发、擦除、类别变更、范围变更、对账九类动作全部记 duty_operation_log（操作人/设备、commandId、前后值、结果）；失败与越权单独计数进 #11 摘要
7	职责分离：人员类别标注与设备范围配置仅公寓管理员可改；值班员只能查看、审核注册与发起 RE_ISSUE／ERASE 受控命令
8	合规边界：业务过程抓拍、录音、签到比对帧仍不出公寓（docs/平台端/07 表 7-7）；识别结果上报不带图像；人脸数据保留期与删除留痕按 Q-32 待决口径执行
9	注册链路职责分离：签到终端只有"发起申请 + 上传人脸"权限（N-34），无权直接写人员主档或触发下发；确认 / 驳回仅值班台 duty:person:reg 可用且必须二次确认（N-36 / N-37）；apt.face.registry 只受理 reg_state=APPLIED 的确认，重复确认幂等返回原 ryid

---

12. 异常处理策略

表 10-25 异常场景与处理

场景	处理	不做什么
注册申请阶段媒体异常	拒收 40919 / 40920，不落申请流水、不生成值班台待办	不把不完整申请推给值班员
重复注册申请	同一 work_no 未决申请返回原 regId；已 CONFIRMED 返回 40918	不生成第二个 ryid、不重复待办
值班员驳回	reg_state=REJECTED + reject_reason，媒体按 Q-32 保留期清理，不生成 ryid	不进主档、不触发双路同步、不下发设备
注册确认后事务失败	整体回滚，reg_state 保持 APPLIED，值班台待办保留可重试	不产生半条人员记录、不触发双路同步
平台不可达	upload_state=PENDING，outbox 排队、恢复后复用原 idempotencyKey 续报；dispatch_state 照常推进，设备下发不受影响（CR-C25）	不阻塞设备下发、不伪造已同步状态
平台驳回注册结果	verdict=REJECTED + reject_reason；本地注册与已下发设备保留，告警 + 值班台待办 + 暂停后续下发（Q-35）	不自动回滚注册、不自动擦除设备缓存、不覆盖平台已有档案
媒体下载失败 / checksum 不符	丢弃临时文件、退避重试（3 次）、face_sync_state=FAILED + 告警；整批不入库	不写入半条人员记录
特征值算法不兼容	人员入库但 FACE_ALGO_UNSUPPORTED 告警，不下发该设备；管理端可配置白名单	不静默截断特征值
设备离线	指令排队，上线心跳按优先级取走；FACE_ERASE 优先级高于 FACE_ISSUE	不向离线设备推送、不标记 ACKED
回执丢失 / 重复	按 commandId 幂等重投，设备重复执行无副作用	不产生第二份业务事实
设备缓存膨胀 / 摘要不一致	FACE_FULL_SYNC 覆盖式重建；连续不一致升级 P1 告警	不逐条猜测差异
擦除超时	≤ 5 min 未完成 → FACE_FULL_SYNC + 值班台告警；人工可发 ERASE 重试	不自动放弃、不自动改为"已擦除"
重复注册	同 work_no 返回 40918；平台已有时由平台驳回 DUPLICATE_WORK_NO	不生成第二个 ryid
类别误标 / 资格撤销	需管理端二次确认后生成 FACE_ERASE(CATEGORY_REVOKED)，写前后值审计	不由定时任务自动批量撤销 LONG_TERM
时钟偏差	设备按心跳 serverTime 校准；偏差 > 1s 拒绝增量拉取并要求 FACE_FULL_SYNC	不按设备本地时间判定版本新旧
版本回退 / 乱序	旧 feature_version 丢弃并记日志；异常回退请求全量重拉 #2	不用旧版本覆盖新版本
跨 gyid / 越权	40301 / 40917，记审计与越权计数	不返回脱敏后的他人人员数据

---

13. 接口清单

表 10-26 新增接口（N-25~N-37；/apt/** 为管理端、/duty/** 为值班台、/open/v1/face/** 为设备侧，均不计入跨端 20 接口）

编号	方法 + 路径	权限 / 凭据	幂等	用途	落点
N-25	GET /apt/face/persons	apt:face:list	L0	人员人脸主档查询（含注册态、同步状态、类别、版本）	apt_master_person、apt_person_face_reg
N-26	POST /apt/face/persons/{ryid}/commands（RE_ISSUE / ERASE / FULL_SYNC）	apt:face:dispatch	L2 commandId	手工重下发 / 擦除 / 全量同步	apt_device_command、duty_manual_action
N-27	GET /apt/face/devices/{deviceCode}/scope、PUT 同路径	apt:face:scope	L1	设备类别与可见范围配置	gy_sb.face_scope_*
N-28	GET /apt/face/devices/{deviceCode}/cache	apt:face:list	L0	设备缓存台账与对账差异	gy_sb_xt.face_cache_*
N-29	POST /apt/face/reconcile	apt:face:reconcile	L2 batchId	手动触发平台/设备对账与全量重建	apt_master_version、apt_device_command
N-30	GET /open/v1/face/persons?deviceCode&cursor&version	设备凭据	L0（游标）	设备按权限范围拉取人员与人脸增量，响应含 persons[]、erase[]、total、hash	apt_master_person、gy_sb
N-31	GET /open/v1/face/media/{ref}	设备凭据 + 短期签名	L0	下载照片 / 特征值（校验和随附）	本地媒体区
N-32	POST /open/v1/face/ack	设备凭据	commandId	下发 / 擦除回执	apt_device_command(ACKED)、gy_sb_xt
N-33	POST /open/v1/face/cache-report	设备凭据	(deviceCode, version)	上报缓存 hash / count / version	gy_sb_xt.face_cache_*
N-34	POST /open/v1/face/reg-requests（REG_APPLY）	签到终端设备凭据	L2 regId	签到终端发起注册申请并上传人员要素与人脸；只落 APPLIED，不进主档、不下发、不上报	apt_person_face_reg
N-35	GET /duty/person/face-reg/pending	duty:person:reg	L0	值班台待审申请列表（要素、照片、申请设备、时间）	apt_person_face_reg
N-36	POST /duty/person/face-reg/{regId}/confirm	duty:person:reg + 二次确认	L2 regId	值班员完成人员注册：生成 ryid、入 apt_master_person，自动触发平台上传与设备下发两条路径	apt_person_face_reg、apt_master_person、duty_manual_action
N-37	POST /duty/person/face-reg/{regId}/reject	duty:person:reg	L2 regId	值班员驳回申请（须填 reject_reason），媒体按 Q-32 保留期清理	apt_person_face_reg、duty_operation_log

N-34~N-37 是注册链路端内接口，不新增跨端编号；原 CR-02 N-08 POST /duty/person/face-reg 保留为"值班台直接登记"的历史入口，按 CR-C25（CR-02 §12 表 3-49）收敛为 N-35 / N-36 的列表 + 确认两步，不再承担"提交即生效"。

表 10-27 跨端接口扩展（沿用既有编号，不新增、不重排，CR-C07）

#	扩展	方向	用途
1	facePolicy（范围规则、缓存上限、擦除窗口、LONG_TERM 白名单、算法白名单）	下行	公寓端按策略执行下发与清理
2	人员增量 payload 增 photoRef、photoChecksum、featureRef、featureChecksum、featureAlgo、featureVersion、personCategory、mediaUrls[]；personRegVerdicts[] 改为平台同步回执（ACCEPTED / REJECTED + platformVersion），不再是注册批准	下行	AF-02 下载入库、AF-01 注册结果对齐
9	PERSON_REG payload 增 ryid、regState=CONFIRMED、照片与特征值引用、校验和、算法、版本、personCategory；媒体本体走签名直传	上行	AF-01 值班员注册成功后上报（APPLIED 阶段不上报），平台按 regId 去重回同步回执
11	设备摘要增 faceCacheMismatchCount、unauthorizedFaceQueryCount	上行	越权与不一致观测
14	心跳增 faceSyncWatermark	上行	版本与积压

表 10-28 新增错误码（沿用 docs/公寓端/04 表 4-4 分段）

code	常量	含义
40914	APT_FACE_REG_PENDING	沿用 CR-02 同码并改判：注册申请未获值班员确认，禁止参与运安匹配与设备下发（CR-C25）
40917	APT_FACE_SCOPE_DENIED	设备越出可见范围查询人员/人脸
40918	APT_FACE_PERSON_DUPLICATE	同 work_no 重复注册
40919	APT_FACE_MEDIA_MISSING	照片或特征值缺失 / 格式不支持
40920	APT_FACE_MEDIA_CHECKSUM_MISMATCH	媒体校验和不符
40921	APT_FACE_ALGO_UNSUPPORTED	特征值算法不在兼容白名单
40922	APT_FACE_MEDIA_TOO_LARGE	媒体超过大小上限
40923	APT_FACE_NOT_SYNCED	人员媒体未同步完成，禁止下发设备（区别于 40914 的"注册申请未获值班员确认"）
40924	APT_FACE_REG_STATE_INVALID	注册态不允许该操作（确认已驳回申请、对 CONFIRMED 再驳回等）
50303	APT_FACE_ERASE_TIMEOUT	离寓擦除超时未完成，已升级全量同步

---

14. 待决策与验收

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

编号	待决事项	未决默认口径	拍板时点
Q-30	离寓擦除时限与告警级别	≤ 30s 生成、≤ 5 min 完成，超时 P1 + FACE_FULL_SYNC	阶段二契约冻结前
Q-31	设备离线期间是否禁用本地人脸放行	禁用（离线只保留缓存、不放行），恢复后先取擦除指令	阶段三试点前
Q-32	人脸主数据保留期与删除留痕合规口径	跟随平台 deleted 标记；本地快照与审计长期保留，设备侧按 AF-05/AF-06 清理	阶段三 D 批开工前
Q-33	媒体签名有效期与大小上限	签名 ≤ 10 min；单条特征值/照片上限由 face.*.maxBytes 配置（默认 64 KB / 512 KB）	阶段二契约冻结前
Q-34	LONG_TERM 类别由平台统一下发还是公寓本地标注	平台下发为准，本地标注需二次确认并上报平台备案	阶段三试点前
Q-35	平台驳回注册结果（如 DUPLICATE_WORK_NO）时是否自动擦除已下发设备缓存	不自动擦除：保留本地注册与设备缓存，告警 + 值班台待办 + 暂停后续下发，由值班员人工归并或撤销；未决期间不影响已完成的叫乘 / 消费业务	阶段三试点前

表 10-30 验收要点

#	验收项	判据
1	注册链路	签到终端 REG_APPLY → 值班台待办 → 值班员 CONFIRM 后生成 ryid 并入 apt_master_person；申请阶段不进主档、不参与匹配、不下发设备（40914）；确认后 #9 上传平台与 FACE_ISSUE 下发设备两条路径均自动触发且互不阻塞；平台驳回不回滚本地注册（Q-35）
2	平台下载	#2 增量下载照片与特征值，校验和通过才入库；版本单调，失败不产生半条记录
3	签到下发	CHECKIN 设备拿到全部有效人员且 hash 与服务端一致；下发内容缺一即不标记 ACKED
4	权限隔离	CONSUME / CALL 设备只拿到本设备范围内人员且不含照片；越权查询返回 40917；gyid 不可由请求参数指定
5	离寓清理	TRANSIENT 离寓后消费/叫乘设备缓存被擦除并有 ACK；LONG_TERM 分区不受影响；超时升级全量同步
6	长期驻留	保洁/巡检/管理人员长期保留、独立分区与独立对账；撤销需二次确认
7	一致性	平台 ↔ 公寓 ↔ 设备三级版本与 hash 对账通过；断网恢复后自动补齐，不产生重复业务事实
8	边界	抓拍、录音、签到现场图仍不出公寓；识别结果不带图像；跨端 20 编号与 v2-draft 契约形态不变
9	安全与审计	九类动作（含注册申请、确认、驳回、双路同步）全部留痕；媒体地址短期签名、仅内网；越权与失败计入 #11 摘要
10	注册权限与幂等	签到终端只能申请、值班台 duty:person:reg 才能确认 / 驳回且须二次确认；重复申请返回原 regId、重复确认幂等返回原 ryid；平台不可达时设备下发仍成功，设备离线时平台上报仍成功