jcgl-dev/docs/公寓端/11-人员入住作业流程.md

11 人员入住作业流程

文档编号：docs/公寓端/11。性质：设计稿（Design Only），不是接口契约冻结稿；阶段二契约冻结评审通过后才落 DDL。 落地权威表述：本文件是"人员入住 → 值班员审核 → 提报平台匹配 → 生成叫乘任务 → 进入叫乘"端到端作业流程的唯一权威表述（CI-01CI-05、表 11-111-35、图 11-111-3）；口径裁决、施工单与验收登记见 CR-02 §13。 上位依据：docs/10-架构优化方案-三端拆分.md、docs/设计变更/01-本地建单与本地调整.md、docs/设计变更/03-三端功能设计修订（CR-02）.md（表 3-1 A-03、表 3-3 功能域 1、表 3-14 CHECKIN payload、CR-C06 / CR-C07 / CR-C25）、docs/公寓端/10-人脸数据下发管理.md §4。 硬约束：跨端仍为 **20 个接口编号（117 + 23~25）**、契约 v2-draft、平台不回调公寓、下行一律"拉"；不新增业务表（公寓本地库仍 59 张）、不新增跨端编号、gy_jcxx 状态字段仍只有 apt.duty.state 一个写入口、jcsj 恒由公寓按规则快照复算。 CR-02 §15 关联（三端一致性）：本文件仍是入住作业流程的唯一权威表述；应用端与平台端按 §15 表 3-65 同步业务规则、交互流程、权限控制与异常处理，三端状态映射与数据同步机制以 CR-02 §15 表 3-66 为唯一权威（match_state 五值、checkin_state、sync_state 不变）。平台统计的入住人数取 #9 CHECKIN 归集后的 PL_REPORT_DAILY.stay_count，统计结果不回写 gy_jcxx / apt_local_task 任何状态；本端不新增上报接口与 bizType。变更点与影响范围见 CR-02 §15 表 3-63。

表 11-1 文档信息

项	内容
范围	人员入住作业五环节：注册与签到（CI-01）、入住申请（CI-02）、值班员审核（CI-03）、数据提报与匹配（CI-04）、叫乘环节（CI-05）
本端职责	签到终端核验与申请受理、值班台审核与房间调整、apt-stay 落库、apt-report 提报、apt-dispatch 拉任务与复算
协同端	平台端（运安计划接入、匹配结论、主档归集）、应用端（值班台审核入口）
编号规则	功能项 CI-01CI-05；表 表 11-y、图 图 11-y 篇内连续；端内接口 N-38N-47（承接 docs/公寓端/10 N-37）；决策点 Q-36Q-40；裁决 CR-C26CR-C30、流程 F-K（见 CR-02 §13）
术语	表名一律小写（apartment/db/mysql/*.sql 实际写法）；平台库表沿用 pl_ 前缀；枚举全大写下划线；时间统一 ts_ms / ISO-8601 带时区

表 11-2 修订记录

版本	日期	修订内容
v1.0	2026-11-10	首次形成：五环节端到端作业流程、三条状态链、复用表与补列结构、端内接口清单（含请求/响应字段）、跨端 #6 / #7 / #8 / #9 字段、异常与权限、Q-36~Q-40 与验收要点；明确"已入住"为流程态 + 业务事实双重表达，不新增 gy_jcxx 状态字段

---

1. 定位与边界

1.1 五个环节与三端职责

表 11-3 环节、主体与落点

环节	用户动作	主责端 / 模块	协同端	主要落表	跨端编号
CI-01 注册与签到	签到终端扫脸核验身份；未注册人员先完成注册	设备侧签到终端 → apt.face.registry / 值班台（N-35~N-37）	平台端（主档同步）	apt_person_face_reg、apt_master_person	#2 / #9（PERSON_REG）
CI-02 入住申请	选择房间、交路（可确定时）并提交申请	签到终端 → apt-stay（受控命令）	—	apt_local_task（申请阶段记录）	—（端内）
CI-03 值班员审核	值班台查看申请、判断是否换房、执行房间调整并置"已入住"	应用端值班台 → apt-stay（唯一执行域）	—	apt_local_task、gy_jcxx、gygl_ly_event、gy_rooms、apt_sip_binding、duty_manual_action	—（端内）
CI-04 数据提报与匹配	公寓提报入住数据；平台取运安数据匹配并确定叫乘任务	apt-report → platform-ingest / platform.plan	平台端	apt_report_outbox、PL_TASK / PL_TASK_CHANGE、GY_SYN_JCXX	#9（CHECKIN）、#6、#8、#7
CI-05 叫乘环节	公寓查询叫乘任务并进入叫乘	apt-dispatch → apt.duty.state	平台端	gy_syn_jcxx、gy_jcxx、apt_local_task	#7 / #8

1.2 与既有流程的关系

• 注册链路不重写：CI-01 直接复用 docs/公寓端/10 §4（签到终端 REG_APPLY → 值班台待办 → 值班员 CONFIRM → 入 apt_master_person → 分别上传平台 / 下发设备），注册生效点是值班员确认（CR-C25）。
• 入住落库不重写：apt-stay 仍是 gy_jcxx / gy_rooms / gygl_ly_event 的唯一写入模块（CR-02 表 3-3 功能域 1）；POST /duty/checkin 是既有端内入口，本文件新增的 N-38~N-47 只承担"设备侧受理 / 值班台审核 / 关联查询"，不绕过执行域直改状态字段。
• 匹配流程不重写：平台按 docs/设计变更/01 §2.5~2.7 收 #8 回执作为匹配输入 → 查 GY_SYN_JCXX 运安快照 → 命中补 kcsj / jcfs 并写 PL_TASK_CHANGE(op=UPSERT) → 结论只能放 #7 响应体 matchVerdict[]；match_state 沿用正式五值 PENDING / MATCHED / UNMATCHED / LOCKED / REJECTED。
• 叫乘执行不重写：CI-05 只负责"任务生成与进入叫乘"的衔接，两类叫乘（SIP / 平板）的端到端流程权威表述仍是 docs/公寓端/05 §9。
• 房间调整复用 CR-02 F-C 的换房联动（gy_rooms 房态重算 + apt_sip_binding 联动 + ROOM_SWAP 事件），但审核期换房不产生换乘单、不重算 jcsj。

1.3 不变式

1. 跨端 20 个编号、方向、路径不变；新增数据只走 payload 与既有 bizType（CHECKIN / CHECKOUT / ROOM_SWAP），契约 v2-draft（CR-C07）。
2. 平台零回调：#6 / #7 由公寓 GET 拉取，#8 / #9 由公寓 POST 上行；平台匹配结论不得另开推送通道（R-05）。
3. gy_jcxx 的 ryzt / finish_jc / finish_ly / stoped 只经 apt.duty.state 条件更新（where id=? and ryzt=?）；已结束不回写、已离寓不回写、stoped 不可逆。
4. gy_jcxx 行在审核通过办理入住时由 apt-stay 当场创建，申请阶段不建行；taskId 恒由公寓按 jcid 业务编码分配，plan_key 只作 matchedPlanKey。
5. jcsj 及派生（fjsj = jcsj + 10 min、jcbjsj = jcsj + 15 min、ylysj = jcsj + lysjgz）恒由公寓按本地规则快照复算；平台 PL_TASK.jcsj 只是基线值，不作为权威、禁止逐项覆写（CR-C06 / D8'）。
6. 主数据快照 apt_master_person / apt_master_room / apt_master_route / gy_syn_jcxx 只读，唯一写入 apt-master-client；本地指定要素不写快照，锁定位复用 gy_jcxx.jllx。
7. 设备侧一律主动拉取；结果按 resultId / applyId / commandId 幂等；抓拍帧、人脸原图、签到现场图与录音不出公寓，人员主数据照片与特征值按 CR-C24 允许跨端。
8. gyid 只从会话 / 设备凭据解析，不接受请求参数；所有 SQL 必带 gyid，唯一键以 gyid 打头。

---

2. 状态流转总览

图 11-1 五环节数据流向

flowchart LR
    subgraph DEV["签到终端 / 值班台"]
        CK["签到终端 CHECKIN<br/>扫脸核验 · 选房 · 提交申请"]
        DUTY["值班台 /duty<br/>审核 · 房间调整"]
    end
    subgraph AP["公寓服务系统"]
        FACE["apt.face.registry<br/>注册申请 / 确认（10 §4）"]
        STAY["apt-stay<br/>唯一执行域"]
        TASK["apt_local_task<br/>申请单 / 本地要素 / 匹配态"]
        JC["gy_jcxx<br/>叫乘任务行"]
        ROOM["gy_rooms / gygl_ly_event<br/>房态与入住事件"]
        REP["apt-report / outbox"]
        DISP["apt-dispatch"]
    end
    subgraph PL["平台端"]
        ING["platform-ingest<br/>#9 CHECKIN 接收"]
        PLAN["platform.plan<br/>#6 运安计划"]
        PT["PL_TASK / PL_TASK_CHANGE<br/>#7 匹配结论"]
    end
    CK -->|CI-01 N-38 扫脸核验| FACE
    FACE -->|未注册：N-34 申请 → N-36 确认| FACE
    CK -->|CI-02 N-39 房间/交路选项 · N-40 提交申请| TASK
    TASK -->|待审推送| DUTY
    DUTY -->|CI-03 N-44 审核 / N-45 换房| STAY
    STAY -->|CHECKED_IN：建 gy_jcxx + CHECKIN 事件 + 房态| JC
    STAY --> ROOM
    STAY -->|CI-04 #9 CHECKIN| REP
    REP --> ING
    PLAN -->|#6 计划下行（拉）| DISP
    ING --> PT
    PT -->|#7 响应体 matchVerdict[]（拉）| DISP
    DISP -->|#8 回执 + 复算 jcsj| ING
    DISP -->|CI-05 任务生成，进入叫乘| JC

表 11-4 三条状态链（互不替代）

链	字段 / 载体	取值	唯一写入口	说明
申请审核态	apt_local_task.checkin_state	SUBMITTED / REVIEWING / APPROVED / ROOM_ADJUSTED / REJECTED / CHECKED_IN / CLOSED	apt-stay（受控命令）	本流程新增的流程态，描述申请单生命周期；不是 gy_jcxx 状态字段（CR-C26）
同步匹配态	apt_local_task.sync_state + match_state	PENDING / REPORTED / MATCHED / UNMATCHED / TASK_READY；match_state 五值见 §1.2	apt-report / apt-dispatch	描述 #9 提报、平台匹配与任务就绪；match_state 沿用 docs/设计变更/01 表 1-17 正式五值
业务事实态	gy_jcxx.finish_ly + sjlysj + gygl_ly_event + ryzt	finish_ly='0' AND sjlysj IS NULL 为有效在寓；ryzt 0~5	apt.duty.state（状态字段）/ apt-stay（事实列）	没有独立"已入住"状态字段；"已入住"= checkin_state=CHECKED_IN 且有效在寓且已写 gygl_ly_event(CHECKIN)

表 11-5 全流程状态流转

序	阶段	checkin_state	sync_state / match_state	触发	写入口与落表	后继 / 异常回退
1	扫脸核验	—（未建单）	—	N-38 返回 personFound=true 且 regState=CONFIRMED	只读 apt_master_person / apt_person_face_reg	未注册 → 转 docs/公寓端/10 §4 注册流程，完成后回本步
2	提交申请	SUBMITTED	PENDING / PENDING	N-40 提交成功，分配 apply_id + 预分配 jcid	apt_local_task 建单（不建 gy_jcxx）	校验失败拒收；重复 deviceEventId 返回原 apply_id
3	值班台接单	REVIEWING	不变	N-43 读取详情（条件更新带期望态）	apt_local_task、duty_operation_log	并发接单按 biz_version 抢锁，失败返回 40926
4	审核通过 / 换房	APPROVED 或 ROOM_ADJUSTED	不变	N-44 APPROVE / APPROVE_WITH_ROOM_CHANGE、N-45 房间调整	apt_local_task、gy_rooms、apt_sip_binding、gygl_ly_event(ROOM_SWAP)、duty_manual_action	房间不可住 → 40928；驳回 → REJECTED（终态）
5	办理入住	CHECKED_IN	PENDING	N-44 审核命令提交后由 apt-stay 事务完成	建 gy_jcxx 行（finish_ly='0'、sjlysj IS NULL、ryzt=0）、gygl_ly_event(CHECKIN)、gy_rooms 房态、apt_local_task	事务失败整体回滚至 APPROVED，不产生半条入住记录
6	提报平台	CHECKED_IN	REPORTED	#9 CHECKIN 入 outbox 并发送成功	apt_report_outbox / apt_report_history	断网 → outbox PENDING，恢复后复用原 idempotencyKey 续报；不阻塞本地叫乘准备
7	平台匹配	CHECKED_IN	MATCHED / UNMATCHED	#7 响应体带回 matchVerdict[]	apt_local_task.match_state / matched_plan_key、gy_syn_jcxx	UNMATCHED 保留公寓上报要素不清空；jllx='1' → LOCKED；REJECTED 转值班台待办
8	任务就绪	CHECKED_IN	TASK_READY	#7 带回 op=UPSERT 且公寓按 apt_master_rule 复算 jcsj 完成并回 #8	gy_jcxx（jcsj / call_mode / dispatch_seq）、apt_local_task、gy_syn_jcxx_status	规则版本升级不回溯，留 derived_rule_version
9	进入叫乘	CHECKED_IN	TASK_READY	apt-dispatch 按 jcsj + dispatch_seq 派发	apt.duty.state（ryzt 条件更新）	两类方式按 docs/公寓端/05 §9 执行，本流程不重复
10	离寓 / 取消	CLOSED	终态	apt-stay 离寓事实或值班台取消（仅 SUBMITTED / REVIEWING 可取消）	gy_jcxx.finish_ly='1'、gygl_ly_event(CHECKOUT)	CHECKED_IN 后取消必须走离寓流程，不得直接改状态

图 11-2 申请审核状态机

flowchart LR
    S["SUBMITTED"] --> R["REVIEWING"]
    R --> A["APPROVED"]
    R --> X["REJECTED"]
    R --> C["CANCELLED"]
    A --> RA["ROOM_ADJUSTED"]
    RA --> A
    A --> CI["CHECKED_IN"]
    RA --> CI
    CI --> CL["CLOSED"]
    X --> CL
    C --> CL

ROOM_ADJUSTED 可多次往返 APPROVED（每次 room_adjust_seq + 1，只追加 ROOM_SWAP 事件、不覆盖历史）；REJECTED / CANCELLED / CLOSED 为终态，不回写 SUBMITTED。

---

3. 数据模型

不新增业务表：公寓本地库仍 59 张。入住申请单作为 apt_local_task 的申请阶段记录（docs/设计变更/01 表 1-17 的"本地建单"表，天然带 origin=CHECKIN_ROUTE / CHECKIN_PENDING 与 match_state），本流程只补列（设计定义，DDL 待阶段二冻结）。

表 11-6 复用表清单

表	库	唯一写入模块	本流程用途	上报
apt_local_task	apartment	apt-stay（受控命令）/ apt-report / apt-dispatch（同步态列）	入住申请单、房间与交路选择、审核状态机、匹配状态	否（经 #9 / #8）
gy_jcxx	apartment	apt-stay（建行/事实列）、apt.duty.state（状态字段）	审核通过后创建的叫乘任务行	是（#9 摘要）
gygl_ly_event	apartment	apt-stay	CHECKIN / CHECKOUT / ROOM_SWAP 事件证据	是（#9）
gy_rooms	apartment	apt-stay（房态重算）	在住人数与房态	否（#11 摘要）
apt_sip_binding	apartment	apt-stay	房间分机绑定联动	否
apt_master_room / apt_master_route / apt_master_person	apartment	apt-master-client	房间基线 / 交路模板 / 人员主档（只读）	—
apt_person_face_reg	apartment	apt.face.registry	未注册人员的注册申请与确认（docs/公寓端/10 §4）	是（#9 PERSON_REG）
apt_report_outbox / apt_report_history	apartment	apt-report	#9 CHECKIN 上行与续报留痕	是
gy_syn_jcxx / gy_syn_jcxx_status	apartment	apt-master-client / apt-dispatch	#6 计划快照与 #7 变更水位	否
duty_manual_action / duty_operation_log	duty	应用端	审核 / 换房留痕（操作人、commandId、前后值）	否
PL_TASK / PL_TASK_CHANGE	platform	platform.plan / platform-ingest	平台匹配结论与任务增量	—

表 11-7 apt_local_task 列级结构（既有列 + 本流程补列）

列	类型	约束	来源	说明
id / gyid / task_id	id_ulid / string(32) / string(64)	PK / UK (gyid, task_id)	既有	task_id = 预分配的 jcid；审核通过后 gy_jcxx 沿用同一值，不重新分配
origin	enum_s	NOT NULL	既有	CHECKIN_ROUTE（交路已确定）/ CHECKIN_PENDING（交路待平台匹配）/ LOCAL_ASSIGN / LOCAL_ADJUST / LOCAL_TEMP_EXTRA
local_version / biz_version	bigint	默认 1	既有 / 补列	local_version 本地要素版本；biz_version 申请单乐观锁与幂等版本，单调
matched_plan_key / match_state	string(128) / enum_s	可空 / 默认 PENDING	既有	match_state 五值 PENDING / MATCHED / UNMATCHED / LOCKED / REJECTED；平台只补 kcsj / jcfs
base_kcsj / base_jcfs / origin_jcsj	ts_ms / string / ts_ms	可空	既有	本地指定要素，jllx_at_override / override_reason / derived_rule_version 同源保留
apply_id	id_ulid	UK (gyid, apply_id)	补列	入住申请单业务键，N-40 幂等键
device_code / device_event_id	string(64) ×2	UK (gyid, device_code, device_event_id)	补列	签到终端来源与设备侧幂等
ryid / work_no / name_snapshot	string(64) / string(64) / string(128)	NOT NULL	补列	核验通过的人员身份快照（不替代 apt_master_person）
face_verify_state / verified_ryid / verified_at / feature_version	enum_s / string(64) / datetime(3) / bigint	可空	补列	扫脸核验结论与所用特征版本；不存抓拍帧与人脸原图
reg_id / reg_state_at_apply	string(64) / enum_s	可空	补列	关联 apt_person_face_reg；申请时必须是 CONFIRMED（CR-C25）
fjh / fjh_final / room_adjust_seq	string(32) ×2 / int	NOT NULL / 默认 0	补列	申请房间与调整后房间；每次调整 +1，不覆盖历史
jlid / cc / jch / kcsj_snapshot	string(64) / string(32) / string(32) / ts_ms	可空	补列	交路（可确定时）与快照要素；不确定时 origin=CHECKIN_PENDING
checkin_state / sync_state	enum_s ×2	默认 SUBMITTED / PENDING	补列	表 11-4 两条状态链
source	enum_s	默认 DEVICE	补列	DEVICE / DUTY / SELF（与 CR-02 表 3-14 同字典）
submitted_at / reviewed_by / reviewed_at / review_note	datetime(3) / string(64) / datetime(3) / string(256)	可空	补列	提交与审核留痕
adjusted_by / adjusted_at / adjust_reason	string(64) / datetime(3) / string(256)	可空	补列	房间调整留痕
checked_in_at / reported_at / matched_at / task_ready_at	datetime(3) ×4	可空	补列	四个关键时间戳，供对账与超时告警
created_at / updated_at	datetime(3) ×2	NOT NULL	既有	只追加，不物理删除

表 11-8 关键事实表本流程相关列

表	列	写入时点	口径
gy_jcxx	jcid / gyid / ryid / fjh	CI-03 办理入住建行	jcid 沿用申请单预分配值；fjh 取 fjh_final
gy_jcxx	finish_ly / sjlysj / ryzt	建行 / 派发时	finish_ly='0'、sjlysj IS NULL、ryzt=0；状态变更只经 apt.duty.state 条件更新
gy_jcxx	jcsj / call_mode / dispatch_seq	CI-05 任务就绪	jcsj 恒由公寓按 apt_master_rule 复算；call_mode = SIP / TABLET；dispatch_seq 单调
gygl_ly_event	jcid / event_type / event_at / device_code / device_event_id	CHECKIN / ROOM_SWAP / CHECKOUT	event_type 与 CR-02 表 3-14 同字典；(device_code, device_event_id) 幂等
gy_rooms	room_status / live_person / sip_account	入住 / 换房后房态重算	room_status 六值 1~6；换房时原房 -1、新房 +1
apt_report_outbox	biz_type / biz_id / idempotency_key / payload	CI-04	biz_type=CHECKIN；biz_id = jcid + 事件序号；idempotencyKey = hash(gyid + CHECKIN + jcid + eventSeq + bizVersion)

表 11-9 枚举字典

枚举	取值	说明
checkinState	SUBMITTED / REVIEWING / APPROVED / ROOM_ADJUSTED / REJECTED / CHECKED_IN / CANCELLED / CLOSED	申请审核态（表 11-4）
syncState	PENDING / REPORTED / MATCHED / UNMATCHED / TASK_READY	同步匹配态
matchState	PENDING / MATCHED / UNMATCHED / LOCKED / REJECTED	沿用 docs/设计变更/01 表 1-17 正式五值；LOCAL_ONLY 属 offlineScope，不是匹配状态
origin	CHECKIN_ROUTE / CHECKIN_PENDING / LOCAL_ASSIGN / LOCAL_TEMP_EXTRA / LOCAL_ADJUST	交路可确定时取 CHECKIN_ROUTE，否则 CHECKIN_PENDING
reviewVerdict	APPROVE / APPROVE_WITH_ROOM_CHANGE / REJECT	N-44 审核命令
faceVerifyState	VERIFIED / UNVERIFIED / NOT_FOUND	与 CR-02 表 3-16 同字典
eventType	CHECKIN / CHECKOUT / ROOM_SWAP	CR-02 表 3-14
source	DEVICE / DUTY / SELF	CR-02 表 3-14

---

4. CI-01 注册与签到

4.1 触发条件与数据范围

表 11-10 触发与前置

项	口径
触发	人员在签到终端发起"扫脸办理入住"；终端按设备凭据 + HMAC + ±5 min 时间窗 + nonce 调用 N-38
数据范围	设备凭据解析出的 gyid / deviceCode、deviceEventId、现场比对结论（faceVerifyState / verifiedRyid / featureVersion）、occurredAt；不上传抓拍帧、人脸原图、比对帧
前置	设备已注册且人脸缓存为 SYNCED（docs/公寓端/10 §6）；同一 (deviceCode, deviceEventId) 未处理过
不触发	仅查询、心跳、缓存摘要上报；faceVerifyState=NOT_FOUND 且人员明确拒绝注册

表 11-11 身份核验步骤

步	主体	动作	落表	异常 / 补偿
1	签到终端	本地 1:1 / 1:N 比对，得到 verifiedRyid 与 faceVerifyState	设备本地缓存	缓存 hash 落后 → 先按 docs/公寓端/10 §6 拉 FACE_FULL_SYNC 再比对
2	apt.checkin.verify	校验设备凭据、gyid 锁定、nonce；按 verifiedRyid 查 apt_master_person	apt_master_person（只读）	越权 40301；凭据失效 40101；重放 40901
3	apt.checkin.verify	判定注册态：CONFIRMED → PROCEED；APPLIED → REG_PENDING；无记录 → REGISTER_REQUIRED	apt_person_face_reg（只读）	APPLIED 不得办理入住（40914，CR-C25）
4	未注册分支	终端展示注册引导 → N-34 REG_APPLY → 值班台 N-35 / N-36 完成注册 → 人脸进入公寓服务系统并按范围下发设备	apt_person_face_reg、apt_master_person、apt_device_command	注册完成后回到步 1 重新核验，不自动沿用本次比对结论（docs/公寓端/10 §4）
5	响应	返回人员摘要、regState、nextAction、roomOptionsVersion、serverTime	duty_operation_log	LONG_TERM 人员同样走本流程，不跳过房态校验

表 11-12 注册数据字段（复用 docs/公寓端/10 表 10-9 ①）

字段	类型	必填	说明
gyid	string(32)	是	只从设备凭据解析，不接受请求参数
work_no / name / unit_code	string	是	人员要素；值班员确认时可修正
photo / photoChecksum	binary / string(128)	是	人脸照片本体与校验和；本体走短期签名直传
feature / featureChecksum / featureAlgo / featureVersion	binary / string(128) / string(32) / long	是	特征值与算法版本；仅传照片时由公寓端按 featureAlgo 提取
apply_device_code / occurred_at	string(64) / datetime(3)	是	签到终端来源与采集时间
reg_id	string(64)	响应	幂等键；同一 work_no 未决申请返回原值

4.2 接口：N-38 扫脸身份核验

表 11-13 N-38 POST /open/v1/checkin/verify 请求 / 响应字段

方向	字段	类型	必填	说明
请求	deviceCode / deviceEventId	string(64) ×2	是	设备凭据解析 + 设备侧幂等键
请求	faceVerifyState / verifiedRyid / featureVersion	enum / string(64) / long	是	只传识别结论与版本，不带图像
请求	occurredAt / nonce / signature	datetime / string / string	是	HMAC + 时间窗 + 防重放
响应	personFound / ryid / workNo / name / personCategory	boolean / string ×4	是	人员摘要（personCategory 决定是否长期驻留）
响应	regState / regId	enum / string(64)	是	CONFIRMED / APPLIED / NOT_FOUND；APPLIED 时带 regId 供查询进度
响应	nextAction	enum	是	PROCEED / REG_PENDING / REGISTER_REQUIRED / REJECTED
响应	roomOptionsVersion / serverTime	long / datetime	是	供 N-39 带版本拉取房间 / 交路选项，避免缓存错配

表 11-14 CI-01 异常与错误码

场景	处理	不做什么
比对未命中 NOT_FOUND	返回 REGISTER_REQUIRED 并引导 N-34 注册	不自动建人员、不建申请单
注册申请未确认 APPLIED	40914（CR-C25），返回 REG_PENDING + regId	不参与入住、不参与运安匹配
设备人脸缓存过期	40927 要求 FACE_FULL_SYNC 后重试	不用过期缓存放行
抓拍上传 / 凭据越 gyid	40919 / 40301 拒收并记审计	不落库、不生成待办
注册后回到核验	重新调用 N-38，服务端重新校验注册态与缓存版本	不复用注册前的比对结论

---

5. CI-02 入住申请

5.1 申请单数据结构

表 11-15 入住申请单字段（落 apt_local_task 补列，对应表 11-7）

字段	类型	必填	校验规则
applyId	id_ulid	响应生成	服务端生成；客户端可用 deviceEventId 作幂等键
deviceEventId / deviceCode	string(64) ×2	必填	UK (gyid, device_code, device_event_id)；重复提交返回原 applyId 与快照，不新建单
ryid / workNo	string(64) ×2	必填	必须来自 N-38 核验通过的人员；与 apt_master_person 一致；regState=CONFIRMED
faceVerifyState / featureVersion	enum / long	必填	必须为 VERIFIED；服务端按 N-38 会话留痕复核，不接受客户端自造新值
fjh	string(32)	必填	必须存在于 apt_master_room，且 gy_rooms.room_status 允许入住（1 空闲 / 5 未满），live_person < 床位数
jlid	string(64)	可选	交路可确定时填，须存在于 apt_master_route；填写后 origin=CHECKIN_ROUTE
cc / jch / kcsjSnapshot	string(32) ×2 / datetime	可选	与 jlid 同组；只作快照，不写 apt_master_route
source	enum	必填	DEVICE / DUTY / SELF；设备侧提交恒 DEVICE，服务端可覆盖
occurredAt	datetime(3)	必填	与 N-38 occurredAt 间隔超 5 min 需重新核验（40929）
remark	string(256)	可选	备注；不参与匹配与校验
bizVersion	long	响应生成	乐观锁，审核 / 调整命令必须带期望值

未填 jlid 时 origin=CHECKIN_PENDING：入住照常办理，交路要素留待 CI-04 由平台按运安快照匹配补齐（kcsj / jcfs），不阻塞入住、不预置 jcsj。

5.2 接口与校验

表 11-16 N-39 / N-40 / N-41 请求 / 响应字段

编号	方法 + 路径	权限 / 凭据	幂等	请求字段	响应字段
N-39	GET /open/v1/checkin/options?deviceCode&version	设备凭据	L0（版本）	version（可选，来自 N-38 roomOptionsVersion）	rooms[]{fjh, bedCount, roomStatus, livePerson, sipBound}、routes[]{jlid, cc, jch, kcsj}、version、serverTime；版本未变返回 304 语义的 notModified=true
N-40	POST /open/v1/checkin/applications	设备凭据 + HMAC	L2 (gyid, deviceCode, deviceEventId)	表 11-15 全部必填 + 可选字段	applyId、jcid（预分配）、checkinState=SUBMITTED、origin、bizVersion、serverTime；重复提交返回原单快照
N-41	GET /open/v1/checkin/applications/{applyId}	设备凭据	L0	applyId	checkinState、syncState、fjh / fjhFinal、reviewNote、estimatedRoomStatus、serverTime；不返回人脸数据

表 11-17 提交校验规则（服务端按序执行）

序	校验	失败码	说明
1	设备凭据 / gyid 锁定 / 时间窗 / nonce	40101 / 40301 / 40901	gyid 不接受请求参数
2	deviceEventId 幂等	返回原 applyId	不新建单，不重复推送待办
3	人员已 CONFIRMED 且 faceVerifyState=VERIFIED	40914 / 40930	注册未确认 / 核验结论不符
4	N-38 会话未过期（≤ 5 min）	40929	要求重新扫脸核验
5	房间可入住且 live_person < 床位数	40928	room_status 为 2 / 3 / 4 / 6 时拒收
6	jlid 存在且与 cc / jch 自洽	40931	不写主数据快照
7	同一 ryid 无有效在寓记录（finish_ly='0' AND sjlysj IS NULL）	40932	防重复入住；确需换房走 CI-03 房间调整
8	写申请单 + 预分配 jcid + 推值班台待办	—	事务内完成；不建 gy_jcxx 行

断网时签到终端本地排队，恢复后续传（复用原 deviceEventId）；服务端不因重复上报生成第二个 applyId 或第二次待办。

---

6. CI-03 值班员审核

6.1 审核状态机与房间调整

表 11-18 审核状态机（唯一写入口 apt-stay，条件更新带 bizVersion 期望值）

当前态	命令	目标态	前置	落表变更
SUBMITTED	N-43 读取详情	REVIEWING	值班员 duty:checkin:review	reviewed_by / 接单时间、duty_operation_log
REVIEWING	N-44 APPROVE	APPROVED → CHECKED_IN	房间仍可住、人员仍有效	见下方"办理入住事务"
REVIEWING	N-44 APPROVE_WITH_ROOM_CHANGE	ROOM_ADJUSTED	目标房间可住	见"房间调整变更清单"；可多次往返 APPROVED
APPROVED / ROOM_ADJUSTED	N-45 房间调整	ROOM_ADJUSTED	未办理入住（gy_jcxx 尚未建行）	room_adjust_seq + 1、只追加事件
REVIEWING / APPROVED	N-44 REJECT	REJECTED（终态）	必须填 review_note	review_note、duty_manual_action；不建 gy_jcxx
SUBMITTED / REVIEWING	值班台取消	CANCELLED（终态）	未办理入住	不建 gy_jcxx；终端 N-41 可见
任意终态	任何审核命令	拒绝 40926	—	返回原态快照，不回写

办理入住事务（apt-stay 单事务，失败整体回滚至 APPROVED）： checkin_state=CHECKED_IN → 建 gy_jcxx 行（沿用预分配 jcid，finish_ly='0'、sjlysj IS NULL、ryzt=0、fjh=fjh_final）→ 写 gygl_ly_event(CHECKIN) → gy_rooms 房态重算 → apt_sip_binding 联动 → 写 checked_in_at → 生成 #9 CHECKIN 上报项入 apt_report_outbox。

表 11-19 房间调整数据变更清单

#	对象	变更	约束
1	apt_local_task	fjh_final 更新、room_adjust_seq + 1、adjusted_by / adjusted_at / adjust_reason	保留 fjh 原值；只追加不覆盖历史
2	gy_rooms（原房 / 新房）	原房 live_person - 1、新房 + 1，两房 room_status 重算	由 apt-stay 房态重算执行，值班台不直改
3	apt_sip_binding	房间主分机绑定按新 fjh 联动	复用 CR-02 F-C 换房联动；离线分机按 §10 告警，不阻断入住
4	gygl_ly_event	追加 ROOM_SWAP 事件（jcid 沿用预分配值）	(device_code, device_event_id) 幂等，只追加
5	duty_manual_action / duty_operation_log	记操作人、commandId、前后房间、理由	二次确认留痕
6	#9 CHECKIN payload	若已上报，追加 eventType=ROOM_SWAP 事件（bizId = jcid + 新事件序号）	沿用 CR-02 表 3-14；不新增跨端编号
7	jcsj	不因房间调整重算	jcsj 由 apt_master_rule 按要素派生；要素未变则不动（CR-C06）

6.2 接口

表 11-20 N-42~N-46 请求 / 响应字段

编号	方法 + 路径	权限	幂等	请求字段	响应字段
N-42	GET /duty/checkin/applications?state&cursor&limit	duty:checkin:list	L0	state（SUBMITTED / REVIEWING）、cursor、limit	items[]{applyId, ryid, workNo, name, fjh, jlid, origin, checkinState, submittedAt, faceVerifyState}、cursor、total、serverTime
N-43	GET /duty/checkin/applications/{applyId}	duty:checkin:review	L0	applyId	申请单全字段 + roomStatus / bedCount / livePerson、routeSnapshot、注册态、bizVersion、可选房间列表 roomCandidates[]；不含人脸媒体本体
N-44	POST /duty/checkin/applications/{applyId}/review	duty:checkin:review + 二次确认	L2 commandId	verdict（APPROVE / APPROVE_WITH_ROOM_CHANGE / REJECT）、expectedBizVersion、reviewNote、targetFjh（换房时）、commandId	applyId、jcid、checkinState、fjhFinal、bizVersion、reviewedAt；APPROVE 成功即含"已入住"标记
N-45	POST /duty/checkin/applications/{applyId}/room-adjust	duty:checkin:adjust	L2 commandId	targetFjh、reason、expectedBizVersion、commandId	applyId、fjh、fjhFinal、roomAdjustSeq、roomStatusBefore/After、sipBound
N-46	GET /duty/checkin/applications/{applyId}/timeline	duty:checkin:list	L0	applyId	events[]{state, fromState, at, actor, commandId, note}、currentState、currentSyncState、matchState

图 11-3 审核与办理入住时序

sequenceDiagram
    autonumber
    participant CK as 签到终端
    participant S as apt-stay（受控命令）
    participant T as apt_local_task
    participant D as 值班台 /duty
    participant J as gy_jcxx / gy_rooms / gygl_ly_event
    participant R as apt-report / outbox

    CK->>S: N-40 提交申请（deviceEventId）
    S->>T: 建申请单 SUBMITTED + 预分配 jcid
    S->>D: 推待办 checkin.apply
    D->>S: N-43 读取详情（REVIEWING）
    alt 需要换房
        D->>S: N-45 房间调整（targetFjh + 二次确认）
        S->>T: ROOM_ADJUSTED（room_adjust_seq+1）
        S->>J: 房态重算 + apt_sip_binding 联动 + ROOM_SWAP 事件
    end
    D->>S: N-44 APPROVE（expectedBizVersion）
    S->>J: 单事务：建 gy_jcxx（finish_ly=0, ryzt=0）+ CHECKIN 事件 + 房态
    S->>T: CHECKED_IN + checked_in_at
    S->>R: 生成 #9 CHECKIN 上报项
    S-->>D: 已入住（applyId / jcid / checkinState）
    S-->>CK: N-41 可查状态

职责分离：签到终端只能提交申请、值班台只能提交审核命令，二者均不直写 gy_jcxx / gy_rooms / gygl_ly_event；apt.duty.state 仍由业务状态机单独调用。

---

7. CI-04 数据提报与匹配

7.1 提报数据格式

表 11-21 #9 POST /platform/v1/report/duty-results（bizType=CHECKIN）payload 字段

字段	类型	必填	说明
envelope	object	是	contractVersion=v2-draft、gyId（凭据解析）、bizType=CHECKIN、bizId = jcid + 事件序号、idempotencyKey = hash(gyid + CHECKIN + jcid + eventSeq + bizVersion)、occurredAt、serverReceivedAt
jcid / ryid / roomId	string	是	与 CR-02 表 3-14 同名字段；roomId 取 fjh_final
eventType / eventAt / source	enum / datetime / enum	是	CHECKIN / CHECKOUT / ROOM_SWAP；source=DEVICE / DUTY / SELF
applyId / origin	string / enum	是	本流程扩展：关联申请单；CHECKIN_ROUTE / CHECKIN_PENDING
jlid / cc / jch / kcsj	string ×3 / datetime	否	交路可确定时带上；不可确定时省略，由平台按运安快照补齐
cardNo / workNo	string	是	平台匹配输入；与 #8 回执共同构成匹配键
faceVerifyState	enum	否	VERIFIED；不携带任何图像
ruleVersion / bizVersion	long ×2	是	本地规则版本与申请单版本，供对账与幂等
transferId	string	否	换乘联动时沿用 CR-02 表 3-14

断网时先落 apt_report_outbox(PENDING)，恢复后按原 idempotencyKey 续报（CR-02 F-E）；平台不可达不阻塞本地入住事实与叫乘准备。

7.2 平台匹配规则

表 11-22 平台侧处理链路与匹配规则

步	主体	动作	跨端编号	落表
1	platform-ingest	收 #9 CHECKIN，按 bizId / idempotencyKey 去重，落接收日志与主档归集	#9	PL_RECEIVE_LOG、平台人员入住归集
2	platform-worker	定时接运安 SOAP 乘务计划，落快照并生成 / 更新任务	内部	GY_SYN_JCXX、PL_TASK、PL_TASK_CHANGE
3	公寓 apt-master-client	主动拉乘务计划	#6 GET /platform/v1/plans/duty?gyId&from&to	gy_syn_jcxx、gy_syn_jcxx_status
4	公寓 apt-dispatch	回任务接收回执（含本地要素登记）；#8 是平台匹配的输入，联网时下一上报周期必发	#8 POST /platform/v1/ack/tasks	apt_report_outbox（biz_type=TASK_ACK）
5	platform.plan	按 gyid + cardNo/workNo + 日期 + 车次(cc/jch) + 交路(jlid) 查 GY_SYN_JCXX 快照；命中则补 kcsj / jcfs，写 PL_TASK_CHANGE(op=UPSERT)	内部	PL_TASK、PL_TASK_CHANGE
6	公寓 apt-dispatch	主动拉任务变更增量，匹配结论随 #7 响应体 matchVerdict[] 下行（与 replayHint 同级）	#7 GET /platform/v1/tasks/changes?gyId&cursor	gy_syn_jcxx_status、apt_local_task
7	公寓 apt-dispatch	按 apt_master_rule 复算 jcsj 与派生时刻，回 #8 computedCallTime；规则升级不回溯，留 derived_rule_version	#8	gy_jcxx、apt_local_task

匹配判定：

• 命中 → matchVerdict.verdict=MATCHED，match_state=MATCHED，补 matchedPlanKey / kcsj / jcfs；PL_TASK_CHANGE(op=UPSERT)。
• 未命中 → UNMATCHED：保留公寓上报的要素不清空、不删除既有叫乘任务（D8' 例外①）；下一 #8 周期可重试。
• 本地锁定 gy_jcxx.jllx='1' → LOCKED，不覆盖本地指定要素（D8' 例外②）。
• 冲突/驳回 → REJECTED + rejectReason，转值班台待办，不自动改本地入住事实。
• 禁止：平台生成任务行、平台产出权威 jcsj、平台回调公寓、为匹配结论新开推送通道。

表 11-23 #7 响应体匹配结果字段

字段	类型	说明
changes[]	array	op=UPSERT / CANCEL、taskId（= jcid）、jlid / cc / jch、kcsj / jcfs、baseCallTime（仅基线）、ruleVersion、bizVersion
matchVerdict[]	array	taskId / applyId、verdict = MATCHED / UNMATCHED / REJECTED、matchedPlanKey、kcsj / jcfs、matchState、rejectReason、matchedAt
cursor / serverTime / replayHint	long / datetime / object	水位、服务端时间与重放提示；与 docs/设计变更/02 R-05 同级
dryRun / replay	boolean	沿用 docs/公寓端/09 表 9-4 约定

表 11-24 平台侧接口字段（既有编号，不新增）

#	接口	方向	请求 / 响应要点
#9	POST /platform/v1/report/duty-results	上行	表 11-21 全量 payload；响应 received / bizId / serverReceivedAt / duplicate
#6	GET /platform/v1/plans/duty?gyId&from&to	下行（拉）	响应 plans[]{jlid, cc, jch, kcsj, ruleVersion, bizVersion}、cursor、serverTime
#8	POST /platform/v1/ack/tasks	上行	taskId / applyId / cardNo / workNo / cc / jch / date / computedCallTime / derivedRuleVersion；响应 ack / nextRetryHint
#7	GET /platform/v1/tasks/changes?gyId&cursor	下行（拉）	表 11-23；响应 changes[] / matchVerdict[] / cursor / replayHint

表 11-25 匹配状态与落表映射

matchVerdict.verdict	apt_local_task.match_state	sync_state	公寓侧后续动作
MATCHED	MATCHED	MATCHED → TASK_READY	复算 jcsj、写 gy_jcxx、回 #8、进入 CI-05
UNMATCHED	UNMATCHED	REPORTED	保留本地要素，等下一 #8 周期；超时告警（Q-37）
—（jllx='1'）	LOCKED	REPORTED	不覆盖本地锁定要素，仍可进入本地叫乘
REJECTED	REJECTED	REPORTED	值班台待办 + 告警，不改入住事实

---

8. CI-05 叫乘环节

8.1 任务查询接口与返回结构

表 11-26 #7 GET /platform/v1/tasks/changes?gyId&cursor 查询契约

项	口径
触发	apt-dispatch 周期拉取；入住单 sync_state ∈ {REPORTED, MATCHED} 时提高拉取频率；心跳 / 水位变更可触发；管理端可手工 FULL_SYNC
方向	公寓 GET 拉取，平台零回调；断网保留 cursor 本地水位，恢复后从上次水位续拉
幂等	cursor 单调 + bizVersion 去重；重复 UPSERT 不产生第二条任务；CANCEL 按 taskId 幂等
前置	checkin_state=CHECKED_IN、gy_jcxx.finish_ly='0' 且 sjlysj IS NULL；已离寓不回写

表 11-27 叫乘任务返回数据结构

字段	类型	必填	说明
taskId / applyId / jcid	string(64) ×3	是	三键一致：taskId = jcid，与申请单 applyId 一对一
ryid / workNo / fjh	string ×3	是	人员与（调整后）房间；SIP 模式据此解析 apt_sip_binding
jlid / cc / jch / kcsj / jcfs	string ×3 / datetime / string	是（MATCHED 时）	平台补齐要素；kcsj 是要素不是叫乘时刻
baseCallTime	datetime	否	PL_TASK.jcsj 基线值，不作为权威（CR-C06）
jcsj	datetime	服务端复算后	恒由公寓按 apt_master_rule 复算；fjsj / jcbjsj / ylysj 同规则派生
callMode / dispatchSeq	enum / long	是	SIP / TABLET；dispatchSeq 按 jcsj 单调
ruleVersion / derivedRuleVersion / bizVersion	long ×3	是	规则版本与派发版本；版本升级不回溯
matchState / matchedPlanKey	enum / string	是	表 11-25
op	enum	是	UPSERT / CANCEL

表 11-28 与入住状态的关联关系

关联	判据	不允许
申请单 → 任务行	apply_id ↔ jcid 一对一；gy_jcxx 沿用预分配 jcid	一单多任务行、审核前建 gy_jcxx
入住 → 任务生成	仅 checkin_state=CHECKED_IN 且有效在寓（finish_ly='0' AND sjlysj IS NULL）才生成叫乘任务	REJECTED / CANCELLED / CLOSED 后仍派发
匹配 → 派发	MATCHED 走完整任务；UNMATCHED / LOCKED 保留本地要素仍可按本地规则派发（D8' 例外）	因 UNMATCHED 清空本地要素或删除既有任务
离寓 → 终态	apt-stay 写 finish_ly='1' 后 checkin_state=CLOSED，apt.duty.state 不再回写	已离寓回写叫乘状态
换房 → 任务	fjh_final 决定房间与 SIP 分机；房间调整不改 jcid、不重算 jcsj	换房生成新 jcid

表 11-29 N-47 GET /apt/checkin/{jcid}/call-task 请求 / 响应字段

方向	字段	类型	说明
请求	jcid / gyid（凭据）/ includeTimeline	string / string / boolean	管理端与值班台共用，apt:checkin:query；gyid 不接受请求参数
响应	applyId / checkinState / syncState / matchState	string / enum ×3	申请单与匹配态
响应	task	object	表 11-27 全量字段（taskId / jcsj / callMode / dispatchSeq / ruleVersion 等）
响应	roomAdjustSeq / fjh / fjhFinal	int / string ×2	换房历史摘要
响应	timeline[] / serverTime	array / datetime	仅 includeTimeline=true 时返回

N-47 是只读端内查询，不改变状态；两类叫乘的执行流程（SIP 的 AMI 事件上报、平板的 jcsj 本地播放与刷脸签到）仍以 docs/公寓端/05 §9 为权威表述。

---

9. 接口清单汇总

表 11-30 端内接口 N-38~N-47（均不计入跨端 20 个编号）

编号	方法 + 路径	权限 / 凭据	幂等	环节	用途
N-38	POST /open/v1/checkin/verify	设备凭据 + HMAC	deviceEventId	CI-01	扫脸身份核验与注册态判定
N-39	GET /open/v1/checkin/options	设备凭据	L0（版本）	CI-02	拉取可选房间与交路
N-40	POST /open/v1/checkin/applications	设备凭据 + HMAC	L2 (gyid, deviceCode, deviceEventId)	CI-02	提交入住申请
N-41	GET /open/v1/checkin/applications/{applyId}	设备凭据	L0	CI-02 / CI-03	终端查询申请状态
N-42	GET /duty/checkin/applications	duty:checkin:list	L0（游标）	CI-03	值班台待审列表
N-43	GET /duty/checkin/applications/{applyId}	duty:checkin:review	L0	CI-03	审核详情（含房态与候选房间）
N-44	POST /duty/checkin/applications/{applyId}/review	duty:checkin:review + 二次确认	L2 commandId	CI-03	审核通过 / 换房通过 / 驳回，办理入住
N-45	POST /duty/checkin/applications/{applyId}/room-adjust	duty:checkin:adjust	L2 commandId	CI-03	房间调整
N-46	GET /duty/checkin/applications/{applyId}/timeline	duty:checkin:list	L0	CI-03	状态流转时间线
N-47	GET /apt/checkin/{jcid}/call-task	apt:checkin:query	L0	CI-05	入住单 ↔ 叫乘任务关联查询（只读）

注册相关接口 N-34~N-37 见 docs/公寓端/10 表 10-26；通用约定（前缀、错误码、data.reason / data.traceId、gyid 锁定）见 docs/公寓端/04 §1。

表 11-31 跨端接口（沿用既有编号，不新增、不重排）

#	接口	方向	本流程用途	字段表
2	GET /platform/v1/master/persons	下行	主档人员增量（CI-01 核验依据）	docs/公寓端/10 表 10-27
6	GET /platform/v1/plans/duty?gyId&from&to	下行（拉）	运安乘务计划（CI-04）	表 11-24
7	GET /platform/v1/tasks/changes?gyId&cursor	下行（拉）	任务变更 + 匹配结论 + 叫乘任务查询（CI-04 / CI-05）	表 11-23、表 11-27
8	POST /platform/v1/ack/tasks	上行	匹配输入与复算回执（CI-04 / CI-05）	表 11-24
9	POST /platform/v1/report/duty-results	上行	CHECKIN / ROOM_SWAP 入住事实（CI-04）	表 11-21
9	同上，bizType=PERSON_REG	上行	注册结果同步（CI-01）	docs/公寓端/10 表 10-27

---

10. 异常处理、一致性与权限

表 11-32 异常处理

场景	处理	不做什么
签到终端断网	本地排队 deviceEventId，恢复后续传；N-39 用本地 version 兜底	不伪造"已提交"、不生成第二个 applyId
值班台推送失败	duty.ws 60s 兜底轮询 N-42	不重复待办
并发审核 / 换房	expectedBizVersion 条件更新，冲突 40926 返回原快照	不用后写覆盖前写
房间在审核期间被占	40928 要求重新选房（N-45）	不超床位办理入住
办理入住事务失败	整体回滚至 APPROVED，不写 gy_jcxx / 事件 / 房态	不产生半条入住记录
平台不可达	#9 进 outbox PENDING，恢复后复用原 idempotencyKey	不阻塞入住事实与本地叫乘准备
UNMATCHED 超时	告警 + 值班台待办，继续按本地要素派发	不清空本地要素、不删既有任务（D8'）
#7 重复 / 乱序	cursor 单调 + bizVersion 去重；CANCEL 按 taskId 幂等	不生成第二条任务、不回写已离寓记录
规则版本升级	不回溯已派生 jcsj，留 derived_rule_version	不逐项覆写派生时刻
离寓后迟到任务	finish_ly='1' 拒收，记 IGNORED	不回写 ryzt / finish_jc

表 11-33 权限与审计

#	要求
1	双校验：管理端 /apt/checkin/** 走 RuoYi 会话 + @PreAuthorize，前端 v-hasPermi 同码（apt:checkin:query）；值班台 /duty/checkin/** 走 duty:checkin:list / duty:checkin:review / duty:checkin:adjust；设备侧 /open/v1/checkin/** 走设备凭据 + HMAC + 时间窗 + nonce
2	职责分离：签到终端只能核验、拉选项、提交申请、查状态；值班台只能接单、审核、换房、查时间线；二者均不直写 gy_jcxx / gy_rooms / gygl_ly_event，唯一执行域是 apt-stay
3	gyid 锁定：只从会话 / 设备凭据解析；所有 SQL 必带 gyid，唯一键以 gyid 打头
4	二次确认：N-44 APPROVE / REJECT 与 N-45 房间调整必须二次确认并写 duty_manual_action
5	审计：核验、提交、接单、审核、换房、办理入住、提报、匹配、任务就绪九类动作全部记 duty_operation_log（操作人 / 设备、commandId、前后值、结果）
6	最小必要：N-41 / N-42 / N-43 / N-47 均不返回人脸照片或特征值本体；抓拍帧、签到现场图与录音不出公寓（CR-C24）
7	状态保护：checkin_state / sync_state 是流程态，不允许写入 gy_jcxx.ryzt / finish_jc / finish_ly / stoped；状态字段仍只经 apt.duty.state（CR-C26）

---

11. 决策点与验收

表 11-34 待决口径（Q-36~Q-40，承接 docs/公寓端/10 Q-35）

编号	事项	默认口径（未决前执行）	拍板时点
Q-36	交路是否必填 / CHECKIN_PENDING 是否允许直接办理入住	允许：交路可确定时填 jlid，否则 CHECKIN_PENDING 照常入住，由平台匹配补齐	阶段三试点前
Q-37	UNMATCHED 超时阈值与告警级别	超过 2 个 #8 周期仍未命中转值班台待办 + P2 告警，本地要素保留	阶段三试点前
Q-38	房间调整是否允许在"已办理入住"后进行	不允许：审核期（未建 gy_jcxx）才可 N-45；入住后换房走 CR-02 F-C TRANSFER	契约冻结签字时
Q-39	签到终端离线期间是否允许先办入住后补申请	不允许：必须先有服务端 applyId；离线只排队不本地放行	阶段三试点前
Q-40	apt_local_task 补列的 DDL 与 apply_id 索引是否随阶段二一次性冻结	是；补列均为设计定义，冻结前用 duty_operation_log JSON 兜底留痕	阶段二契约冻结

表 11-35 验收要点

#	验收项	判据
1	注册与签到	未注册人员先经 N-34 → N-36 完成注册并重新核验；APPLIED 一律 40914；N-38 只传识别结论不带图像
2	入住申请	必填 / 可选字段与表 11-15 一致；8 项校验按序生效；重复 deviceEventId 返回原 applyId；申请阶段不建 gy_jcxx
3	值班员审核	状态机按表 11-18 迁移；并发冲突 40926；换房变更清单 7 项齐全且不改 jcid / jcsj
4	已入住	checkin_state=CHECKED_IN 且 finish_ly='0' AND sjlysj IS NULL 且已写 gygl_ly_event(CHECKIN)；事务失败整体回滚；未新增 gy_jcxx 状态字段
5	提报与匹配	#9 CHECKIN 字段与表 11-21 一致；#8 为匹配输入；匹配结论只经 #7 响应体 matchVerdict[]；UNMATCHED 不清空本地要素
6	叫乘环节	#7 返回结构符合表 11-27；jcsj 由公寓复算且不由平台基线覆写；applyId ↔ jcid 一对一；已离寓迟到任务 IGNORED
7	边界不破	跨端 20 编号、v2-draft、平台零回调、59 张表、apt.duty.state 单写入口、抓拍 / 录音不出公寓均不变
8	安全与审计	九类动作全部留痕；gyid 不可由请求参数指定；签到终端 / 值班台无业务表直写权限