zfjia/jcgl-dev
1
0 Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
main
jcgl-dev/docs/设计变更/03-三端功能设计修订（CR-02）.md
T
zfjia 51356c69a3
IT-0 verify / verify (push) Waiting to run
Details
第二次任务推进。
2026-11-10 16:44:01 +08:00

150 KiB
Raw Permalink Blame History

03 三端功能设计修订 CR-02（v1.0）

触发依据：docs/公寓端/00-公寓端主要功能设计.md 对公寓端功能重新规划；docs/backend/*（既有系统梳理）、docs/frontend/*（既有界面梳理）、docs/10-架构优化方案-三端拆分.md、docs/11-既有数据库结构分析.md 为现状基线。 上位依据：docs/10 §3（端职责）、§4（模块划分）、§5（数据架构）、§6（接口契约）、§9（迁移阶段）、附录 D（维护约定）；docs/设计变更/01-本地建单与本地调整.md（CR-01 v2）；docs/设计变更/02-文档修订清单（可执行）.md（R-01R-51、R-C1R-C11）。 性质：设计稿（Design Only）。本轮只产出设计文档，不写业务代码、不建表改表、不执行 DDL / DML、不改任何配置。文中所有新增表均为设计定义，DDL 须在阶段二契约冻结评审通过后方可执行。 权威声明：本文件是 CR-02 范围内"覆盖范围、交互协议、交互数据、模块数据设计、数据表设计、关键流程变更"的唯一权威表述。三端分册中与本文件冲突的旧口径一律以本文件为准，并已在 §8 施工单中逐处修订。跨端 20 接口编号、CR-01 的 jcid / jcsj 裁定、R-C1~R-C11 的裁定继续有效，本文件不推翻。

表 0-1 文档信息

项 内容
文档编号 docs/设计变更/03（CR-02）
文档名称 三端功能设计修订：覆盖范围、交互协议与数据、数据表与关键流程
适用范围 铁路行车公寓叫乘与一卡通系统三端（平台端 / 公寓端 / 应用端值班员界面）
关联文档 docs/公寓端/0009、docs/平台端/0109、docs/应用端/01~10、docs/10、docs/11、docs/backend/*、docs/frontend/*、CR-01、docs/设计变更/02
约束条件 ① 三端总体定位不变（平台真源与规则 / 公寓现场执行与事实 / 应用端人看与人工干预）；② 公寓端与应用端同 jar、同库、同进程，不构成第三套服务；③ 平台不回调公寓，跨端一律"公寓主动拉 + 推"；④ 跨端 20 个接口编号不新增、不重排，新增数据一律走 payload 与 bizType 扩展；⑤ 技术基线锁定 RuoYi-Vue + Vue + MySQL（公寓端 / 应用端），平台端选型按 D13 待决；⑥ 状态字段仍只有 apt.duty.state 一个写入口
交付对象 架构评审、三端详细设计、契约冻结、试点实施与验收

表 0-2 修订记录

版本 日期 说明
v1.0 2026-11-09 首次形成：把 docs/公寓端/00 的 14 项需求编号化为需求基线（§1）；裁决 14 项口径冲突并重划三端覆盖范围（§2）；定义四层交互协议与 v2 契约扩展（§3）；定义上行 bizType、payload 与枚举字典（§4）；新增模块数据设计（§5）与 16 张表的列级设计（§6）；定义 8 条关键流程变更（§7）；给出已执行的逐文件施工单（§8）与待决策项（§9）
v1.1 2026-11-09 补遗 §10：落实 docs/公寓端/00 v1.1 新增的「Asterisk 配置数据管理模块」（AC-01AC-05）与 SIP 分机离线告警规则；新增注册表 apt_sip_reg_status（T-17）、表数口径 58 → 59 张、裁决 CR-C15CR-C19、流程 F-I、接口 N-19N-24、决策点 Q-26Q-28；施工单追加 R-68~R-76
v1.2 2026-11-09 补遗 §11：明确叫乘功能的两类实现方式及其业务流程（SIP 语音叫乘 / 平板叫乘）的触发条件、交互流程、状态上报机制与结果反馈路径；流程权威表述为 docs/公寓端/05 §9（表 5-95-21、图 5-85-9）；新增裁决 CR-C20CR-C23、决策点 Q-29、验收 1214、施工单 R-77~R-84；未新增表、跨端编号、bizType 或 WS 消息名
v1.3 2026-11-09 补遗 §12：落实「公寓端人脸数据下发管理」完整模块（AF-01AF-06：注册与平台同步、平台下载入库、签到设备下发、消费/叫乘按设备维度隔离、离寓自动擦除、长期驻留保留）；权威表述为 docs/公寓端/10（表 10-110-30、图 10-1 / 10-2）。新增裁决 CR-C24（人员主数据照片与特征值允许跨端，业务过程抓拍 / 录音仍不出公寓）与 CR-C25（注册链路改判为「签到终端申请并上传人脸 → 值班员在值班台完成注册 → 注册成功后人脸进入公寓服务系统 → 分别上传平台与下发公寓内设备」，平台回执降级为主档同步回执、双路解耦并行）；新增流程 F-J、接口 N-25N-37、错误码 4091740924 / 50303、决策点 Q-30Q-35、验收 1517、施工单 R-85~R-93；不新增业务表、不新增跨端编号、不新增 bizType、不改 59 张表口径
v1.4 2026-11-10 补遗 §13：新增「人员入住作业流程」完整设计（docs/公寓端/11，CI-01CI-05：注册与签到、入住申请、值班员审核、数据提报与匹配、叫乘环节），含三条状态链、复用表补列结构、端内接口 N-38N-47（请求 / 响应字段）与跨端 #6 / #7 / #8 / #9 字段。新增裁决 CR-C26CR-C30、流程 F-K、决策点 Q-36Q-40、验收 1820、施工单 R-95R-103；不新增业务表（59 张不变）、不新增跨端编号、不新增 bizType、不新增 gy_jcxx 状态字段，"已入住"为流程态 + 业务事实双重表达
v1.5 2026-11-10 补遗 §14：新增「消费、充值与菜品管理」完整设计（docs/公寓端/12，CF-01CF-03：人员消费、人员线下充值、公寓菜品管理），含四条状态链、双额度扣减规则、复用表补列结构、端内接口 N-48N-58（请求 / 响应字段）与跨端 #1 / #4 / #10 / #16 的 payload 扩展。新增裁决 CR-C31CR-C35、流程 F-L / F-M / F-N、错误码 4093340940、决策点 Q-41Q-45、验收 2123、施工单 R-104~R-113；不新增业务表（59 张不变）、不新增跨端编号、不新增 bizType、不新增状态字段；仅线下充值不接线上支付，远程点菜仅预留入口
v1.6 2026-11-10 补遗 §15：把公寓端已完成的四项调整（平板叫乘、人脸签到、消费、菜品管理）在应用端 / 平台端同步落地，统一业务规则、交互流程、权限控制、异常处理，并给出三端状态映射与数据同步机制唯一权威表（表 3-66）；同时新增平台端「以公寓为单位的分类统计 / 月·季·年报表 / 公寓排名」能力（docs/平台端/10，PS-01PS-05）。新增裁决 CR-C36CR-C42、流程 F-O / F-P / F-Q、决策点 Q-46Q-50、验收 2426、施工单 R-114~R-125；变更点与影响范围见 §15 表 3-63。跨端仍 20 个编号、契约 v2-draft、平台零回调、公寓本地库 59 张、不新增 bizType；统计能力全部落平台管理端 /platform/v1/admin/stat/**，新增 2 张 pl_apt_stat_* 属平台库（另计），统计结果不回写任何业务状态
v1.7 2026-11-10 非设计变更登记（索引同步）：新增 docs/公寓端/13-公寓端小步迭代开发计划.md（v1.0，实施排期设计稿），以 dev/ 的 RuoYi-Vue / Vue2 / MySQL 实测上游为物理起点，把 §11~§15 的设计成果切成 IT-0IT-8 九个小步迭代（P1 入住 + 叫乘核心闭环优先）、里程碑 MS-0MS-5 与交付物 DV-0DV-8；P2 消费 / 充值 / 菜品整体延后为 IT-9IT-11（"设计已覆盖、实现延后"，非删需求）。登记 6 项 P0 排期前提与 3 项口径偏离（表 13-4 / 表 13-6），须评审签字后方可执行。变更点与影响范围：新建 公寓端/13 1 篇，同步 公寓端/00、公寓端/README.md、公寓端/07、公寓端/08、docs/README.md 与本文表 0-2 / 0-3 索引；不改动 §12~§15 任何权威表述，不新增裁决 CR-C* / 流程 F-* / 决策点 Q-* / 验收 / 施工单 R-* / M7 / 阶段六 / D-4 等既有编号；跨端仍 20 个编号、契约 v2-draft、平台零回调、公寓本地库 59 张表、平台库累计新增 5 张（含 2 张 pl_apt_stat_*）、apt.duty.state 单写入口、统计结果不回写全部不变；阶段与验收仍以 docs/10 §9、公寓端/07 表 7-1~7-8 为权威，13 篇内 IT-* / MS-* / DV-* / IR-* 编号不纳入本文体系
v1.8 2026-11-10 非设计变更登记（索引同步）：新增 docs/公寓端/15-第二轮开发（IT-1）交付说明.md（v1.0），登记 IT-1 运行时基座 M0 的实现与验收——四前缀治理与 /apt/** 鉴权、gyid 隔离、统一错误码与表 4-4 HTTP 状态映射、401/403 处理器、审计切面落 duty_operation_log、分页上限 100、springdoc 分组、权限点种子与只读列表骨架；41 个单测全绿，真实进程端到端 M0 5/5 通过（dev/scripts/verify-it1-m0.ps1）。变更点与影响范围：新建 公寓端/15 1 篇与 dev/scripts/verify-it1-m0.ps1 1 个脚本，同步 公寓端/README.md、公寓端/14 表 14-23、docs/README.md 与本文表 0-2 索引；不改动 §12~§15 任何权威表述，不新增裁决 CR-C* / 流程 F-* / 决策点 Q-* / 验收 / 施工单 R-* 等既有编号；跨端仍 20 个编号、契约 v2-draft、平台零回调、公寓本地库 59 张表、apt.duty.state 单写入口、统计结果不回写全部不变；IT-* / DV-* 仍为 13 篇内编号，不纳入本文体系；契约冻结签字与 D5 签字仍为 P0 待办

表 0-3 本文件图表编号规则

项 规则
图表编号 统一用 表 3-y（x = 文件序号 3，y 篇内连续递增）；引用其他文档一律带文档名前缀，如 docs/公寓端/03 表 3-7
表名 一律小写（apartment/db/mysql/*.sql 实际写法）；平台库新增表沿用 pl_ 前缀（分册原文大写，本文用小写）
排期编号 IT-* / MS-* / DV-* / IR-* 仅用于 docs/公寓端/13 篇内（v1.7），不纳入本文编号体系；本文仍只有 A / CR-C / F / Q / R / PS / S 系列
需求 / 裁决 / 流程编号 需求 A-01A-14（细化项 AC-01AC-05 见 docs/公寓端/00 §3）、裁决 CR-C01CR-C42、流程 F-AF-Q、决策点 Q-20Q-50；统计专册功能项 PS-01PS-05 与管理端接口 S-01~S-07 见 docs/平台端/10；不与 CR-01 的 D/F/G、docs/设计变更/02 的 R-*、R-C* 冲突

1. 需求基线（公寓端 14 项重新规划）

表 3-1 docs/公寓端/00 14 项需求的编号化与三端归属

编号 需求要点 主责端 协同端 本期 主要承载（模块 / 表 / 协议）
A-01 从平台获取叫乘任务、上报叫乘结果 公寓端 平台端 是（已具备） #6 / #7 / #8 / #9；gy_jcxx、apt_report_outbox
A-02 获取机务人员数据、注册新增人员（新增人脸数据） 公寓端（签到终端申请 + 值班员确认注册 + 本地入档 + 平台 / 设备分别同步） 平台端（跨公寓主档真源、接收同步回执） 是（新增） #1 / #2 / #9 payload 扩展；apt_person_face_reg、apt_master_person、apt_device_command、pl_person_reg_request；流程以 docs/公寓端/10 §4 与 CR-C25 为准
A-03 提交入住请求与离寓请求 公寓端 应用端（操作入口）、平台端（归集） 是（分期冲突已裁决，CR-C02） POST /duty/checkin、apt-stay；#9 / #10 payload 扩展
A-04 获取补贴、刷卡消费、扣本地补贴、上报消费台账、本地充值、充值上报；断网期间充值只能本地使用 公寓端（离线受理） 平台端（主账与规则）、应用端（登记界面） 是（由 P2 提升，最小闭环） apt.ledger.local、apt_ledger_offline、pl_offline_quota；#10 payload 扩展
A-05 设备状态上报：在线、离线、报警 公寓端 平台端（汇总） 是（补设备报警） apt_device_alarm、gy_sb；#11 / #12 payload 扩展
A-06 公寓侧叫乘设备任务下发：SIP 呼叫（Asterisk）、平板叫乘 公寓端 — 是（新增双模式） apt-dispatch、apt-device；AMI、/open/v1/tablet/**
A-07 任务按叫乘时间顺序派发；SIP 由 Asterisk 组织，平板形成任务数据由平板拉取 公寓端 — 是（新增派发队列） apt_tablet_task.dispatch_seq；gy_jcxx.call_mode / dispatch_seq
A-08 状态判定：SIP 由 AMI 事件推断，平板由平板上报结果（人员 / 刷脸 / 未刷脸） 公寓端 应用端（展示） 是（新增事件源） apt_tablet_call_result、apt.duty.state；/ws/duty tablet.result
A-09 换乘：值班员对交路指定换乘开车时间、叫乘时间，可能换房 公寓端（重算与联动） 应用端（发起）、平台端（接收变更） 是（新增） apt_transfer_order、TRANSFER 命令；#8 / #9 payload 扩展
A-10 叫乘报警、离寓报警 公寓端 应用端（处置） 是（已具备） gy_bjxx；#12
A-11 房间基础台账、房间状态更新、在寓人员查看 公寓端 平台端（基线） 是（补台账归属口径，CR-C05） gy_rooms、apt_master_room；G-01 building 补列（Q-20）
A-12 保洁人员管理、保洁记录管理 公寓端 应用端（现场登记） 是（新增） apt_clean_staff、apt_clean_record；POST /duty/clean/**
A-13 值班员排班、盯控质量考核 应用端（排班与考核界面） 公寓端（事实来源）、平台端（跨公寓汇总） 是（新增） duty_roster、duty_performance、pl_staff_performance_daily；#13 payload 扩展
A-14 数据上报管理：上报历史、断网提交失败后续报；范围含入住、消费、充值（并补齐叫乘结果、设备状态、报警、归档） 公寓端 平台端（接收与对账） 是（新增） apt_report_history、apt_report_retry_batch；apt_report_outbox.retry_batch_id

docs/公寓端/00 原第 14 条以逗号截断，本表按上下文补全上报范围；原文件已同步编号化，见 §8。

2. 三端覆盖范围

2.1 总纲（沿用，不改写）

表 3-2 三端一句话边界与本次补充

端 一句话边界（沿用 docs/10 §3.4） CR-02 补充
平台端 管主数据真源、规则与策略、账务主账、跨公寓统计 新增"本地登记确认、离线额度与冲正、跨公寓考核汇总"三类接收与确认职责；仍不执行现场动作
公寓端 管现场资源、现场事实、事件与媒体 新增"离线受理、平板设备与任务派发、换乘重算、上报历史与续报、现场台账"五类执行职责；主数据仍只读，本地登记为"待确认事实"
应用端 管人看与人工干预，任何干预经公寓端领域服务落地 新增"换乘发起、平板结果查看、本地充值登记、排班与考核查看"入口；仍无业务状态直写权限

2.2 功能域矩阵（v2）

表 3-3 新增 / 调整功能域的三端归属（● 主责　○ 参与　— 不做）

# 功能域 对应需求 平台端 公寓端 应用端 唯一写入口 / 真源
1 入住 / 离寓 / 换房 A-03、A-11 ○ 归集 ● 执行与事实 ○ 发起 apt-stay → gy_jcxx / gy_rooms / gygl_ly_event
2 补贴 / 消费 / 充值（含断网） A-04 ● 主账、规则、额度 ● 本地受理、离线流水 ○ 登记 / 查询 平台 platform-ledger；本地 apt.ledger.local（offline_scope 隔离）
3 人员与人脸注册 A-02 ● 跨公寓主档真源 / 接收同步回执 ● 签到终端申请、值班员确认注册、本地入档、按范围下发设备 ○ 值班台审核与确认 签到终端 REG_APPLY → apt_person_face_reg(APPLIED) → 值班员 CONFIRM → apt_master_person 入档 → 分别 #9 上行平台 / FACE_ISSUE 下发设备（CR-C25、§12 表 3-48）
4 SIP 叫乘（Asterisk） A-06、A-08 — ● ○ 人工触发 AMI / apt.duty.state
5 平板叫乘与顺序派发 A-06、A-07、A-08 — ● ○ 查看 apt_tablet_task / apt_tablet_call_result
6 换乘（时刻 + 换房联动） A-09 ○ 接收变更 ● 重算与联动 ● 发起 apt_transfer_order → apt.duty.state + apt-stay + apt.voice.endpoint
7 设备报警（区别于叫乘 / 离寓报警） A-05、A-10 ○ 汇总 ● 判定 ○ 处置 apt_device_alarm / gy_bjxx
8 保洁人员与保洁记录 A-12 ○ 跨公寓统计 ● 台账与记录 ○ 现场登记 apt_clean_staff / apt_clean_record / gy_clean_task
9 值班员排班与盯控质量考核 A-13 ○ 跨公寓汇总 ○ 事实来源 ● 排班与考核 duty_roster / duty_performance / pl_staff_performance_daily
10 上报历史与续报 A-14 ○ 接收、对账 ● 历史、续报 ○ 查看积压 apt_report_history / apt_report_retry_batch

原有功能域（交路与计划、叫乘执行、设备网关、语音与录音、主数据快照、运维自检、RBAC 与审计、跨公寓报表、外部集成）归属不变，见各端 01。

2.3 冲突裁决

表 3-4 CR-C01~CR-C14 口径裁决（冲突时以本表为准）

编号 冲突（旧口径） 裁定（唯一口径） 被撤销 / 修订的旧表述
CR-C01 端定位在三份 01 中措辞不一 沿用 docs/10 §3.4 总纲，本文件表 3-2 为补充解释；不改动上位结论 —
CR-C02 公寓端判"入住 / 换房 / 离寓属后续"、接口"本期不提供"；应用端 /duty/checkin 却列本期 本期实现；公寓 apt-stay 唯一写入口，应用端只发命令，平台只收归集 docs/公寓端/01 表 1-4 #2、docs/公寓端/04 §接口清单末段
CR-C03 公寓端账务标 P2、应用端"不做任何账务动作"、平台端"消费受理归公寓" 账务由 P2 提升为本期最小闭环：平台主账权威、公寓离线受理（额度内本地可用）、恢复后按 serverReceivedAt 归集冲正；应用端只做"本地充值登记 / 本地余额查询"，不改主账 docs/公寓端/01 表 1-4 #6 / §4；docs/应用端/01 §5 表 1-9 首行
CR-C04（v1.3 由 CR-C25 覆盖） 公寓端人员快照"一律只读"，但 A-02 要求本地注册新增人脸 平台仍是跨公寓人员主数据真源；下行快照只读，本地登记表独立可写。注册生效点按 §12 CR-C25 改判为值班员确认（不再等平台确认）：确认后即入 apt_master_person 并分别同步平台与公寓内设备；确认前不得参与运安匹配、不得下发设备 docs/公寓端/04 "平台下发字段一律只读"的绝对表述（改为"下行快照只读，本地登记表独立可写"）；本行旧流程以 §12 表 3-48 为准
CR-C05 房间台账：平台 GY_ROOMS 基线 vs 公寓 apt_master_room 只读 vs 本地新增房间 平台存基线（gyid + roomNo + 床位数）；公寓维护现场台账（楼栋 / 楼层 / 朝向 / SIP / 房态 / 在寓人员）并上报差异；building 补列登记为 Q-20，未决前沿用 room_floor + room_no 前缀筛选 三处"房间归属"表述统一到本条；不改写 D3
CR-C06 jcsj 以平台为准 / 不取平台值 / 平台存计算值三种口径 沿用 docs/设计变更/02 R-C9、R-C10：jcsj 及其派生恒由公寓按规则快照复算，平台只存"按要素派生的基线"不作为权威值；要素（kcsj / jcfs）不一致时以平台为准并告警 docs/公寓端/05 表 5-1 第 4 行、docs/平台端/03 PL_TASK.jcsj（平台计算值）、docs/平台端/06 图 6-2 要点
CR-C07 跨端契约"20 个不新增、确需新增走 v2 不在本期"与 A-02~A-14 的新数据冲突 不新增跨端编号：全部新数据以既有 #1#14、#23#25 的 payload 与新 bizType 扩展；平板 / 消费机 / 抓拍机属设备侧协议 /open/v1/**，应用端属端内协议，均不计入 20 个跨端接口；契约版本升 v2-draft docs/平台端/05 §1 第 2 条"确需新增则走 v2 契约，不在本期"改为按本条执行
CR-C08 平板叫乘是"任务下发"还是"拉取" 平板拉取（与 00 第 7 条"由平板拉取叫乘任务"一致，且符合"平台不回调公寓"纪律）：公寓按 jcsj 排序生成任务，平板按 cursor 拉取并回传结果 docs/公寓端/05 §3 设备协议"未确认"口径
CR-C09 换乘无落点（ASSIGN_ELEMENT / ADJUST_TIME 不含换房联动） 新增 TRANSFER 受控命令 + apt_transfer_order；由公寓重算时刻、联动 apt_sip_binding 与房间，再经 #8 / #9 上报；CR-01 两条命令保持不变 三端"换乘零命中"状态
CR-C10 "上报历史"被 outbox 队列语义覆盖，续报只有单条 replay outbox 保持队列语义；新增 apt_report_history（终态流水）与 apt_report_retry_batch（续报批次），续报复用既有上行接口重发，不新增编号 docs/公寓端/04 §上报接口清单、docs/公寓端/05 §6
CR-C11 值班员排班 / 考核无表无接口，交接班标"后续" 本期新增 duty_roster / duty_performance；duty_shift_handover 仍按原口径后续，不借本次顺带启用 docs/应用端/01 表 1-5 #6 不变；新增 #10、#11 两个域
CR-C12 设备报警与叫乘 / 离寓报警混在 gy_bjxx 新增 apt_device_alarm 独立表，alarm_source 区分 CALL / LEAVE / DEVICE；#12 摘要按来源分组，不改 gy_bjxx 列 docs/公寓端/09 #12 用途列
CR-C13 同码不同常量：40903、50101 两端命名不一致 统一：40903 = APT_SNAPSHOT_EXPIRED、50101 = APT_PROTOCOL_NOT_CONFIRMED；别名不保留 docs/公寓端/04 表 4-4、docs/应用端/04 表 4-4 对应行
CR-C14 契约版本 v1-draft、表数口径 44 / 45 并存 契约统一升 v2-draft（字段级仍在阶段二冻结）；公寓本地库业务表口径 v1.0 为 58 张、v1.1 补遗后为 59 张（44 存量 + apt_local_task 1 + CR-02 新增 13 + 补遗 apt_sip_reg_status 1，见 §10），平台库新增 3 张 pl_* 另计，框架 sys_* 30 张口径不变（表 3-25、3-26） docs/公寓端/09、docs/平台端/05 版本行；docs/公寓端/03 §1 标题、docs/平台端/README 表数量行

2.4 分期

表 3-5 本期 / 后续范围

阶段 做 不做
本期（CR-02） 表 3-3 十个域中 110 的最小闭环；A-01A-14 全部有落点（含设计定义、接口契约、流程与验收） 不改运安接入归属、不新增跨端编号、不启用 duty_shift_handover、不引入 kcgl、不开放录音外链、不做平台回调公寓
后续 P2-1 补助规则引擎化、餐饮结算规则、跨公寓考核报表重建 本期不实现规则引擎
后续 P2-2 多公寓推广与注册版本管理、P-01 平台前端形态、D13 平台库选型 本期按选项 A（平台保持现库）设计，不改写语义

3. 交互协议

3.1 四层协议栈

表 3-6 协议分层、方向与可靠性（平台不回调公寓为全栈硬约束）

层 参与方 协议 / 前缀 方向 鉴权 可靠性 对应需求
L1 跨端 公寓端 ↔ 平台端 HTTPS /platform/v1/**、/open/v1/**；20 个编号不新增 公寓主动 GET 拉（#1~#7、#23）/ POST 推（#8~#14、#24）；#15 / #25 平台自答；#16 / #17 方向待定（P-02 / F-03） X-Apt-GyId + 路径 gyId 双携带；mTLS / 双向令牌 上行信封 + Idempotency-Key + outbox + 三时间戳 + 水位 / 对账 A-01~A-05、A-14
L2 端内 应用端 ↔ 公寓端 同 JVM 进程内 Java 接口；浏览器门面 /duty/**；推送 /ws/duty 应用端 → 公寓领域服务（命令）；公寓 → 应用端（事件推送） 复用公寓端 RuoYi 账号 + gyid 数据域 commandId / action_id 幂等；seq 单调；60 s 兜底轮询 A-03、A-08、A-09、A-13
L3 设备侧 平板 / 消费机 / 抓拍机 ↔ 公寓端 HTTPS /open/v1/tablet/**、/open/v1/device/**；设备主动注册、心跳、拉取、上报 设备拉取（平板任务、消费凭证）；指令 ACK 回传 deviceCode + 激活码，HMAC(secret, body) + ±5 min 时间窗 + nonce commandId 幂等、本地队列、断网续传 A-04、A-06~A-08
L4 语音 公寓端 ↔ Asterisk AMI（本地）、SIP、会议桥、串口广播 本机出站 本地配置（不出现凭据） apt_ast_ami_session 自愈、事件兜底比对 A-06、A-08、A-10

L3 的"设备拉取"不是跨端接口，也不违反"平台不回调公寓"：它是公寓端与自有设备之间的本地网关协议。

3.2 跨端 20 接口的 v2 扩展点

表 3-7 既有编号上的 payload 扩展（编号、方向、路径一律不变）

# 接口 v2 扩展内容 方向 承载需求
1 GET /platform/v1/master/apartments/{gyId} 响应增 offlineQuota（离线充值单笔 / 累计上限）、features.tabletCall 开关 下行 A-04、A-06
2 GET /platform/v1/master/persons 响应增 personRegVerdicts[]（平台对已注册人员的同步回执：ACCEPTED / REJECTED 与 platformVersion，不再是注册批准）与人员增量 mediaUrls[] 下行 A-02、CR-C25
3 GET /platform/v1/master/routes routes[] 增 transferPolicy（是否允许换乘、最晚可改时刻） 下行 A-09
5 GET /platform/v1/master/rooms rooms[] 增 building / orientation / sipExtension（现场台账差异核对） 下行 A-11
7 GET /platform/v1/tasks/changes changes[] 增 transferOrders[]、callMode 下行 A-06、A-09
8 POST /platform/v1/ack/tasks items[] 增 computedCallTime 的 transferRef、dispatchSeq 上行 A-07、A-09
9 POST /platform/v1/report/duty-results bizType 扩 CHECKIN / CHECKOUT / TABLET_RESULT / TRANSFER / STAFF_PERFORMANCE_DAILY 上行 A-03、A-08、A-09、A-13
10 POST /platform/v1/report/ledger bizType 扩 LEDGER_OFFLINE；offlineScope / localBalanceVersion / quotaRef 上行 A-04
11 POST /platform/v1/report/device-status 摘要增 tabletCount、alarmSource=DEVICE 分组 上行 A-05、A-06
12 POST /platform/v1/report/alarms 摘要按 alarmSource 分组；增 deviceCode 上行 A-05、A-10
13 POST /platform/v1/report/archive 摘要增 cleanRecords[]、staffPerformance[]、reportHistory 计数 上行 A-12、A-13、A-14
14 POST /platform/v1/heartbeat 增 pendingRetryBatches、lastReportHistoryAt 上行 A-14
23 GET /open/v1/voice/config configType 增 TABLET（平板提示音 / 模板） 下行 A-06
24 POST /open/v1/voice/summary 摘要增 callMode=SIP / TABLET 分组 上行 A-06、A-08
2 / 9 / 10 的接收侧 POST /platform/v1/master/person-regs（不新增编号：作为 #2 的配套同步回执返回，仍由公寓拉取） 值班员注册成功后的人脸主档同步上行走 #9 的 PERSON_REG bizType；平台回执不决定本地注册生效（CR-C25） 上行 A-02

新增 bizType 不新增接口编号，仍复用 §6.2 上报信封；平台侧 PL_RECEIVE_LOG 按 biz_type 分流，见 docs/平台端/05 §9。

3.3 端内与设备侧新增接口

表 3-8 新增接口清单（N-01~N-18；均不计入跨端 20 接口）

编号 方法 + 路径 层 端 / 模块 权限点 幂等 落表 需求
N-01 POST /open/v1/tablet/register L3 apt.device.gateway 设备凭据 deviceCode apt_tablet_device A-06
N-02 POST /open/v1/tablet/heartbeat L3 apt.device.gateway 设备凭据 L0 apt_tablet_device.last_seen_at A-05
N-03 GET /open/v1/tablet/tasks?deviceCode&cursor&limit L3 apt-dispatch 设备凭据 L0（游标） apt_tablet_task A-07
N-04 POST /open/v1/tablet/results L3 apt.duty.state 设备凭据 resultId apt_tablet_call_result A-08
N-05 POST /open/v1/tablet/tasks/{taskId}/ack L3 apt-dispatch 设备凭据 taskId + deviceCode apt_tablet_task.pulled_* A-07
N-06 POST /duty/jcxx/{jcid}/commands（TRANSFER） L2 apt.duty.command duty:jcxx:transfer L2 commandId apt_transfer_order、duty_manual_action A-09
N-07 GET /duty/transfer / GET /duty/transfer/{transferId} L2 apt.duty.view duty:jcxx:query L0 apt_transfer_order A-09
N-08 POST /duty/person/face-reg / GET /duty/person/face-reg L2 apt-stay（经领域服务） duty:person:reg L2 regId apt_person_face_reg A-02
N-09 POST /duty/ledger/local-recharge L2 apt.ledger.local duty:ledger:local L2 flowId apt_ledger_offline、gy_ykt_xjczjl A-04
N-10 GET /duty/ledger/local-balance?ryid L2 apt.ledger.local duty:ledger:local L0 apt_ledger_offline（本地口径） A-04
N-11 POST /duty/clean/staff / GET /duty/clean/staff L2 apt-stay duty:clean:staff L1 apt_clean_staff A-12
N-12 POST /duty/clean/records / GET /duty/clean/records L2 apt-stay duty:clean:record L2 recordId apt_clean_record、gy_clean_task A-12
N-13 POST /duty/roster / GET /duty/roster L2 apt-duty duty:roster:* L1 shiftId duty_roster A-13
N-14 GET /duty/performance / POST /duty/performance/recalc L2 apt-duty duty:performance:* L1 (gyid, date) duty_performance A-13
N-15 GET /apt/report/history L2（管理端） apt.report.outbox apt:report:list L0 apt_report_history A-14
N-16 POST /apt/report/retry / GET /apt/report/retry/{batchId} L2（管理端） apt.report.outbox apt:report:retry L2 batchId apt_report_retry_batch、apt_report_outbox A-14
N-17 GET /apt/device/alarms / POST /apt/device/alarms/{id}/handle L2（管理端） apt.device.gateway apt:device:alarm L1 apt_device_alarm A-05
N-18 GET /apt/tablet/devices / GET /apt/tablet/tasks L2（管理端） apt-device apt:tablet:list L0 apt_tablet_device、apt_tablet_task A-06、A-07

表 3-9 /ws/duty 消息扩展（现有 12 类不变，新增 5 类）

消息名 方向 主要字段 触发 需求
tablet.result 公寓 → 应用端 jcid、taskId、faceVerifyState、verifiedRyid、occurredAt、seq 平板结果回传 A-08
transfer.changed 公寓 → 应用端 transferId、jcid、newJcsj、newRoomId、state、seq 换乘生效 / 驳回 A-09
device.alarm 公寓 → 应用端 alarmId、deviceCode、alarmSource、alarmEventKey、seq 设备报警 A-05
ledger.offline 公寓 → 应用端 flowId、offlineScope、localBalanceVersion、quotaRemain、seq 断网本地受理 A-04
report.backlog 公寓 → 应用端 pending、failed、retryBatchId、lastReportHistoryAt、seq 上报积压 / 续报完成 A-14

表 3-10 错误码统一与新增（沿用两端 04 表 4-4 分段，不自造新段）

code 常量 含义 裁定说明
40903 APT_SNAPSHOT_EXPIRED 快照过期 / 主数据版本过期 CR-C13：两端统一此名，废止 APT_MASTER_VERSION_STALE 别名
50101 APT_PROTOCOL_NOT_CONFIRMED 设备协议未确认 CR-C13：废止 APT_PROTOCOL_UNCONFIRMED
40913 APT_OFFLINE_QUOTA_EXCEEDED 断网本地充值 / 扣补贴超过离线额度 新增；offlineQuota 由 #1 下发
40914 APT_FACE_REG_PENDING 注册申请未获值班员确认，不能参与运安匹配与设备下发（v1.3 由 CR-C25 改判；平台同步回执未返回不再触发本码） CR-C25 改判
40915 APT_TRANSFER_TIME_ILLEGAL 换乘时刻晚于开车时刻或超出 transferPolicy 新增
40916 APT_TABLET_TASK_EXPIRED 平板任务已被派发 / 已过期，重复 ACK 新增
50302 APT_REPORT_RETRY_BUSY 同一批次续报进行中 新增

4. 交互数据

4.1 上行信封与 bizType

表 3-11 信封（沿用 docs/10 §6.2，仅扩展取值）

字段 类型 说明 v2 变更
gyId / appVersion / batchId / sentAt / watermark string / string / string / datetime / long 沿用 不变
items[].idempotencyKey string hash(gyid + bizType + bizId + bizVersion) 新增 bizType 取值沿用同一公式
items[].bizType string 业务类型 见 表 3-12
items[].bizId / bizVersion / occurredAt / receivedAt / payload string / long / datetime / datetime / object 沿用 payload 结构见 表 3-13~3-21
serverReceivedAt datetime 平台接收时间，回执带回 不变；账务归日仍以它为准

表 3-12 新增 bizType 与承载接口（不新增接口编号）

bizType 承载接口 bizId 幂等补充 需求
PERSON_REG #9 regId 值班员注册成功后上报；平台按 regId 去重，重复返回原同步回执 verdict（ACCEPTED / REJECTED），不做注册准入 A-02、CR-C25
CHECKIN / CHECKOUT #9 jcid + 事件序号 沿用 #9 幂等键 A-03
TABLET_RESULT #9 resultId 平板重传同 resultId 视为成功 A-08
TRANSFER #8 / #9 transferId bizVersion+1 表示换乘单更正 A-09
LEDGER_OFFLINE #10 flowId UK (gyid, type, flow_id)；与幂等重放语义区分 A-04
DEVICE_ALARM #12 alarmId handled_result 变更时 bizVersion+1 A-05
CLEAN_RECORD #13 recordId 按日汇总 A-12
STAFF_PERFORMANCE_DAILY #13 (gyid, date, ryid) 重发覆盖同日结果 A-13
REPORT_RETRY #14 batchId 心跳携带，不进 items 批量 A-14

4.2 payload 字典

表 3-13 PERSON_REG（A-02）

字段 类型 必填 说明
regId string(ULID) 是 本地登记 ID，幂等键
gyid / workNo / name / unitCode string 是 人员要素；workNo 与平台 ryid 对齐前的本地键
photoRef / featureRef / photoChecksum / featureChecksum string 是 人员主数据照片与特征值的引用及校验和；媒体本体走短期签名直传，不上行抓拍/录音（CR-C24、§12 表 3-48）
featureAlgo / featureVersion / personCategory / mediaUrls[] string / long / enum / string[] 是 算法标识、特征版本、人员类别（含 LONG_TERM）、媒体签名地址；版本单调、平台按 checksum 去重
regId / ryid / regState string / string / enum 是 值班员确认注册成功后才上报；ryid 由确认时生成、regState=CONFIRMED；申请阶段（APPLIED）不上报（CR-C25、docs/公寓端/10 §4）
registeredBy / occurredAt / deviceCode string / datetime / string 是 现场来源；deviceCode 为登记设备

表 3-14 CHECKIN / CHECKOUT（A-03）

字段 类型 必填 说明
jcid / ryid / roomId string 是 入住记录业务键、人员、房间
eventType enum 是 CHECKIN / CHECKOUT / ROOM_SWAP
eventAt / source datetime / enum 是 source = DEVICE / DUTY / SELF
transferId string 否 换乘联动产生的入住 / 离寓
faceVerifyState enum 否 与 表 3-16 同字典

表 3-15 LEDGER_OFFLINE（A-04）

字段 类型 必填 说明
flowId / type string / enum 是 type = CONSUME / RECHARGE / ALLOWANCE_DEDUCT
amount string(2) 是 字符串十进制两位小数；扣减用负数，禁止浮点
ryid / cardNo / deviceCode string 是 账户与受理设备
offlineScope enum 是 LOCAL_ONLY / SYNCED / RECONCILED；断网期间恒 LOCAL_ONLY
localBalanceVersion / quotaRef long / string 是 本地余额 CAS 版本；离线额度批次（#1 下发）
occurredAt / syncedAt datetime / datetime 是 / 否 归日仍以 serverReceivedAt 为准

表 3-16 TABLET_RESULT（A-08）

字段 类型 必填 说明
resultId / taskId / jcid string 是 结果、平板任务、叫乘任务三层键
deviceCode / callMode string / enum 是 callMode = TABLET
faceVerifyState enum 是 VERIFIED / UNVERIFIED / SKIPPED
verifiedRyid / personCount string / int 否 刷脸识别到的人员与应答人数
resultType enum 是 ANSWERED / NO_ANSWER / FAILED / CANCELLED
occurredAt / receivedAt datetime 是 现场发生 / 公寓入库

表 3-17 TRANSFER（A-09）

字段 类型 必填 说明
transferId / jcid / jlid string 是 换乘单、叫乘任务、原交路
newDepTime / newCallTime datetime 是 值班员指定的换乘开车 / 叫乘时间
recomputedCallTime datetime 是 公寓按规则快照复算结果（CR-C06），不是平台值
newRoomId / oldRoomId string / string 否 / 是 换房联动；为空表示不换房
commandId / reason string 是 与 duty_manual_action 对齐

表 3-18 DEVICE_ALARM（A-05）

字段 类型 必填 说明
alarmId / deviceCode / alarmSource string / string / enum 是 alarmSource = DEVICE（CALL / LEAVE 仍走 gy_bjxx）
alarmType / severity enum 是 OFFLINE / HEARTBEAT_TIMEOUT / CARD_JAM / POWER；P0~P2
alarmEventKey string 是 与 /ws/duty 去重键一致
occurredAt / handledAt / handledBy datetime / datetime / string 是 / 否 / 否 处置回写触发 bizVersion+1

表 3-19 CLEAN_RECORD / STAFF_PERFORMANCE_DAILY（A-12、A-13）

字段 类型 必填 说明
recordId / staffId / roomId string 是 保洁记录与人员
cleanType / state / finishedAt enum / enum / datetime 是 ROUTINE / CHECKOUT / DEEP；DONE / REDO
date / ryid / shiftId date / string / string 是（考核） 按 (gyid, date, ryid) 覆盖重发
responseSecAvg / alarmHandledRate / callSuccessRate / manualActionCount decimal / decimal / decimal / int 是（考核） 盯控质量指标，口径见 Q-23
source enum 是 LOCAL_CALC（本地算，平台只汇总）

表 3-20 下行扩展字段（#1 / #2 / #3 / #5 / #7）

接口 字段 类型 说明
#1 offlineQuota.{singleLimit, dailyLimit, maxOutstanding} string(2) ×3 离线充值 / 扣补贴额度；超限返回 40913
#1 features.tabletCall boolean 平板叫乘总开关，缺省 false
#2 personRegVerdicts[].{regId, verdict, ryid, rejectReason, version, platformVersion} array 平台同步回执：verdict = ACCEPTED / REJECTED / PENDING（CONFIRMED 为 v1.0 历史别名，按 ACCEPTED 理解）；不决定本地注册是否生效（CR-C25）
#3 transferPolicy.{allowed, latestChangeMinutes, requireRoomRecalc} object 换乘策略；不额外下发"应叫时刻"
#5 rooms[].{building, orientation, sipExtension} object 现场台账差异核对（CR-C05）
#7 changes[].{callMode, dispatchSeq, transferOrders[]} object 任务变更增量

表 3-21 枚举字典（跨端统一，大写下划线字符串；不用数字码、不用 MySQL ENUM）

枚举 取值 说明
callMode SIP / TABLET 叫乘执行模式；gy_jcxx.call_mode
faceVerifyState VERIFIED / UNVERIFIED / SKIPPED 平板上报刷脸状态；UNVERIFIED 触发复叫判定
alarmSource CALL / LEAVE / DEVICE 报警来源；#12 分组依据
offlineScope LOCAL_ONLY / SYNCED / RECONCILED 离线流水生命周期
reportState PENDING / SENT / FAILED / DEAD / RETRIED outbox 与 history 共用
transferState DRAFT / APPLIED / REJECTED / ROLLED_BACK 换乘单状态
regVerdict PENDING / ACCEPTED / REJECTED（平台同步回执）；本地注册态另见 regState = APPLIED / CONFIRMED / REJECTED / ARCHIVED 平台回执与本地注册态分离，注册生效点为值班员确认（CR-C25、docs/公寓端/10 §4.4）
callResultType ANSWERED / NO_ANSWER / FAILED / CANCELLED 平板结果

表 3-22 定序、幂等与重试（新增 bizType 沿用 docs/10 表 6-2）

项 口径
顺序 同一 bizId 按 bizVersion 单调；更正上报 bizVersion+1 并生成新 idempotencyKey；count 一律按 biz_id 去重（R-C3）
重试 1s / 5s / 30s / 2min / 10min + 抖动，上限 1 小时；PL-VERSION-STALE → DEAD；PL-5xx / 超时 → FAILED
断网 本地先落业务表 + outbox；恢复后先派 outbox，再拉 #7（CR-01 §2.9 顺序不变）
续报 失败批次由 apt_report_retry_batch 生成，复用原 idempotencyKey 重发；不产生新业务事实
平板 任务按 dispatch_seq 单调拉取；结果以 resultId 幂等；40916 表示任务已过期

5. 各模块的数据设计

表 3-23 新增 / 调整的模块职责与唯一写入口（依赖方向仍为单向，apt-duty 不被其他模块依赖）

模块 端 新增职责 唯一写入的表 依赖 需求
apt.dispatch（扩展） 公寓端 双模式派发、按 jcsj 排序、call_mode 分流、平板任务生成 gy_jcxx.call_mode / dispatch_seq、apt_tablet_task apt-master-client、apt.duty.state A-06、A-07
apt.device.gateway（扩展） 公寓端 平板注册 / 心跳 / 任务拉取 / 结果受理 / 设备报警 apt_tablet_device、apt_tablet_call_result、apt_device_alarm apt.duty.state（只提交命令） A-05、A-06、A-08
apt.stay（扩展） 公寓端 入住 / 离寓 / 换房 / 换乘联动、保洁人员与记录、本地人员登记 gy_jcxx、gy_rooms、gygl_ly_event、apt_transfer_order、apt_clean_staff、apt_clean_record、apt_person_face_reg apt-master-client（只读快照） A-02、A-03、A-09、A-11、A-12
apt.ledger.local（本期启用） 公寓端 离线扣补贴 / 本地充值 / 本地余额版本 / 额度校验 / 冲正 apt_ledger_offline、gy_ykt_*（5 张预留表启用） apt-master-client（额度与规则） A-04
apt.report.outbox（扩展） 公寓端 上报历史归档、失败批次续报、积压观测 apt_report_history、apt_report_retry_batch、apt_report_outbox 全部上行生产者 A-14
apt-duty（扩展） 应用端 换乘发起、排班、盯控质量考核、本地充值登记界面 duty_roster、duty_performance、duty_manual_action 进程内调 apt.duty.command / apt-stay / apt.ledger.local A-09、A-13、A-04
platform.ingest（扩展） 平台端 新 bizType 分流、登记确认回执、离线流水接收 PL_RECEIVE_LOG、pl_person_reg_request platform-master / platform-ledger A-02、A-04
platform.ledger（扩展） 平台端 离线额度下发、冲正与日对账 pl_offline_quota、PL_LEDGER_FLOW、GY_YKT_REMAINDER platform-ingest A-04
platform.report（扩展） 平台端 跨公寓考核汇总、保洁与上报历史统计 pl_staff_performance_daily、PL_REPORT_DAILY platform-ingest A-13、A-14

表 3-24 三端数据归属纪律（新增表必须满足）

纪律 要求
owner 标注 每张表在表 3-27 标 apartment / duty / platform / platform-down；写入模块唯一
gyid 隔离 所有新增业务表带 gyid 且业务 SQL 必带 gyid（sys_* 除外）；唯一键一律以 gyid 打头
状态单入口 ryzt / finish_jc / finish_ly / stoped 仍只有 apt.duty.state 可写；平板结果、换乘、报警都只提交命令
跨端媒体边界 人员主数据人脸（照片 / 特征值 / 算法标识 / 特征版本）按 CR-C24 允许平台 ↔ 公寓双向同步，本体走短期签名直传、库内只存引用与校验和；业务过程抓拍、录音、签到现场图仍不出公寓，平台只存索引与计数；识别结果上报不带图像（docs/公寓端/10 §1.1 表 10-3、§12 表 3-48）
主数据只读 下行快照表（apt_master_*）保持只读；本地登记表是独立表，不算"改主数据"
同库边界 应用端新增 duty_* 表与公寓端同库，禁止第二数据源 / 跨库 JOIN

6. 数据表设计

6.1 表数口径

表 3-25 表数统一口径（CR-C14）

库 v1.2 口径 CR-01 CR-02 新增 合计 说明
公寓本地库（含 duty_* 操作域） 44 张（docs/公寓端/03 §1） apt_local_task 1 张（已在 CR-01 定义、未在表 3-2 登记） 13 张（公寓 owner 11 + duty owner 2） + §10 补遗 1 张 59 张 不含若依框架 sys_* / qrtz_* 30 张；v1.0 的 58 张口径按本行理解
平台库 沿用 docs/平台端/03 §3 表 3-4~3-9 — 3 张 pl_* 原口径 + 3 平台库表数原本不引用 44
既有库结构缺陷 docs/11：40 表 / 0 主键 / 0 索引 / gy_jcxx 70 列 — — — CR-02 新增表必须全部带主键与索引，不复制既有缺陷

本轮为设计稿：以上建表、补列均为设计定义，须在阶段二契约冻结评审通过后按迁移脚本执行；不得直接对生产库执行 DDL / DML。

6.2 新增表总览

表 3-26 17 张新增表（编号 T-01~T-17；T-17 为 §10 补遗）

编号 表名 库 / owner 唯一写入模块 上报源 本期 需求
T-01 apt_tablet_device 公寓 / apartment apt.device.gateway 是（#11 摘要） 是 A-05、A-06
T-02 apt_tablet_task 公寓 / apartment apt-dispatch 否（明细不上报） 是 A-07
T-03 apt_tablet_call_result 公寓 / apartment apt.device.gateway → 命令 是（TABLET_RESULT / #9） 是 A-08
T-04 apt_person_face_reg 公寓 / apartment apt.face.registry（v1.3 由 apt-stay 改判，见 §12 表 3-49） 是（PERSON_REG / #9） 是 A-02、CR-C25
T-05 apt_transfer_order 公寓 / apartment apt-stay（经 apt.duty.state） 是（TRANSFER / #8、#9） 是 A-09
T-06 apt_clean_staff 公寓 / apartment apt-stay 否 是 A-12
T-07 apt_clean_record 公寓 / apartment apt-stay 是（#13 摘要） 是 A-12
T-08 apt_device_alarm 公寓 / apartment apt.device.gateway 是（DEVICE_ALARM / #12） 是 A-05
T-09 apt_report_history 公寓 / apartment apt.report.outbox 本身即上报历史 是 A-14
T-10 apt_report_retry_batch 公寓 / apartment apt.report.outbox 是（#14 心跳） 是 A-14
T-11 apt_ledger_offline 公寓 / apartment apt.ledger.local 是（LEDGER_OFFLINE / #10） 是 A-04
T-12 duty_roster 公寓 / duty apt-duty 否 是 A-13
T-13 duty_performance 公寓 / duty apt-duty 是（#13 日汇总） 是 A-13
T-14 pl_person_reg_request 平台 / platform platform-ingest 接收侧 是 A-02
T-15 pl_offline_quota 平台 / platform platform-ledger 下行侧（#1） 是 A-04
T-16 pl_staff_performance_daily 平台 / platform platform-report 接收侧（#13） 是 A-13
T-17 apt_sip_reg_status 公寓 / apartment apt.voice.event（只追加） 是（#11 / #24 摘要，明细不上报） 是 A-05、A-06；§10 补遗

6.3 列级设计

表 3-27 平板叫乘域（T-01~T-03）

表 列 类型 约束 / 默认 说明
apt_tablet_device id bigint PK 代理键；业务键为 device_code
gyid / device_code varchar(32) / varchar(64) UK (gyid, device_code)，NOT NULL 平板设备编码，入库大写
room_id / activation_code_ref varchar(64) / varchar(128) 可空 绑定房间；激活码只存引用，不存明文
register_status / app_version varchar(20) / varchar(32) 默认 PENDING ACTIVE / DISABLED / PENDING
last_seen_at / last_cursor datetime(3) / varchar(128) 可空 心跳与拉取游标
created_at / updated_at datetime(3) NOT NULL 三时间戳口径
apt_tablet_task id bigint PK 代理键
gyid / task_id / jcid varchar(32) / varchar(64) / varchar(64) UK (gyid, task_id)，NOT NULL 与 gy_jcxx.jcid 对齐（R-C1）
dispatch_seq bigint NOT NULL，IDX (gyid, dispatch_seq) 按 jcsj 排序的派发序号，单调递增
call_mode / jcsj varchar(20) / datetime(3) 默认 TABLET 叫乘基准时刻（本地复算值）
device_code / pull_state varchar(64) / varchar(20) 默认 WAITING WAITING / PULLED / EXPIRED / DONE
pulled_at / pulled_by / expire_at datetime(3) / varchar(64) / datetime(3) 可空 拉取回执
created_at / updated_at datetime(3) NOT NULL —
apt_tablet_call_result id bigint PK 代理键
gyid / result_id / task_id / jcid varchar(32) / varchar(64) ×3 UK (gyid, result_id)，NOT NULL 幂等键 = result_id
face_verify_state / verified_ryid varchar(20) / varchar(64) NOT NULL / 可空 VERIFIED / UNVERIFIED / SKIPPED
result_type / person_count varchar(20) / int NOT NULL 见 表 3-21
device_code / occurred_at / received_at varchar(64) / datetime(3) ×2 NOT NULL 现场 / 入库时间
applied_state varchar(20) 默认 PENDING PENDING / APPLIED / IGNORED；由 apt.duty.state 回写

表 3-28 人员登记、换乘与报警（T-04、T-05、T-08）

表 列 类型 约束 / 默认 说明
apt_person_face_reg id bigint PK 代理键
gyid / reg_id / work_no / name varchar(32) / varchar(64) ×3 UK (gyid, reg_id)，NOT NULL 本地登记要素
face_feature_ref / photo_checksum varchar(256) / varchar(128) NOT NULL 不存特征大对象 / 原图
reg_state / local_only / verdict varchar(20) / tinyint(1) / varchar(20) 默认 APPLIED / 1 / PENDING APPLIED → 值班员 CONFIRMED → local_only=0 并写入正式 ryid；verdict 只记平台同步回执（§12 表 3-49）
confirmed_ryid / reject_reason / verdict_version varchar(64) / varchar(256) / bigint 可空 confirmed_ryid 由值班员确认时生成；verdict_version 来自 #2 personRegVerdicts[] 同步回执
apply_device_code / applied_at / confirmed_by / confirmed_at varchar(64) / datetime(3) / varchar(64) / datetime(3) 可空 签到终端申请来源与值班员确认留痕
upload_state / dispatch_state varchar(20) ×2 默认 PENDING 上传平台与下发设备两条独立状态链，互不阻塞（CR-C25）
registered_by / device_code / occurred_at varchar(64) / varchar(64) / datetime(3) NOT NULL 现场来源
report_state / created_at varchar(20) / datetime(3) 默认 PENDING 上报状态
apt_transfer_order id bigint PK 代理键
gyid / transfer_id / jcid / jlid varchar(32) / varchar(64) ×3 UK (gyid, transfer_id)，NOT NULL 换乘业务键
old_room_id / new_room_id varchar(64) 可空 换房联动
new_dep_time / new_call_time / recomputed_call_time datetime(3) ×3 NOT NULL 后两者不得相等时静默覆盖，须告警（CR-C06）
state / command_id / reason varchar(20) / varchar(64) / varchar(256) 默认 DRAFT 与 duty_manual_action.action_id 对齐
biz_version / applied_at / created_at bigint / datetime(3) ×2 默认 1 更正上报时 +1
apt_device_alarm id bigint PK 代理键
gyid / alarm_id / device_code varchar(32) / varchar(64) ×2 UK (gyid, alarm_id)，NOT NULL 设备报警独立表
alarm_source / alarm_type / severity varchar(20) ×3 默认 DEVICE 见 表 3-18 / 3-21
alarm_event_key varchar(128) UK (gyid, alarm_event_key) 与 /ws/duty 去重键一致
occurred_at / handled_at / handled_by / handled_result datetime(3) ×2 / varchar(64) / varchar(256) 可空 处置触发 bizVersion+1
biz_version / report_state bigint / varchar(20) 默认 1 / PENDING —

表 3-29 保洁与值班域（T-06、T-07、T-12、T-13）

表 列 类型 约束 / 默认 说明
apt_clean_staff id / gyid / staff_id / name bigint / varchar(32) / varchar(64) ×2 PK / UK (gyid, staff_id) 保洁人员档案
state / phone_ref / created_at varchar(20) / varchar(128) / datetime(3) 默认 ACTIVE 联系方式只存引用
apt_clean_record id / gyid / record_id / staff_id / room_id bigint / varchar(32) / varchar(64) ×3 PK / UK (gyid, record_id) 保洁记录幂等键
clean_type / state / task_id varchar(20) ×2 / varchar(64) NOT NULL 关联 gy_clean_task
started_at / finished_at / remark datetime(3) ×2 / varchar(256) 可空 —
report_state / created_at varchar(20) / datetime(3) 默认 PENDING 日汇总进 #13
duty_roster id / gyid / shift_id / ryid bigint / varchar(32) / varchar(64) ×2 PK / UK (gyid, shift_id, ryid) 排班；shift_id = 日期 + 班次
shift_date / shift_type / start_at / end_at date / varchar(20) / datetime(3) ×2 NOT NULL DAY / NIGHT
state / created_by / created_at varchar(20) / varchar(64) / datetime(3) 默认 PLANNED PLANNED / CONFIRMED / CANCELLED
duty_performance id / gyid / ryid / shift_id / stat_date bigint / varchar(32) / varchar(64) ×2 / date PK / UK (gyid, stat_date, ryid) 盯控质量考核（本地算、平台汇总）
response_sec_avg / alarm_handled_rate / call_success_rate decimal(10,2) ×3 默认 0.00 指标口径 Q-23 待决
manual_action_count / alarm_missed_count int ×2 默认 0 —
calc_version / report_state / calculated_at bigint / varchar(20) / datetime(3) 默认 1 / PENDING 重算覆盖同日结果

表 3-30 上报与账务域（T-09~T-11）

表 列 类型 约束 / 默认 说明
apt_report_history id / gyid / idempotency_key / biz_type / biz_id bigint / varchar(32) / varchar(128) ×3 PK / UK (gyid, idempotency_key) 上报终态流水，不是队列
biz_version / batch_id / retry_batch_id bigint / varchar(64) ×2 NOT NULL / 可空 关联续报批次
state / result_code / last_error varchar(20) / varchar(64) / varchar(512) NOT NULL SENT / FAILED / DEAD / RETRIED
occurred_at / sent_at / platform_recv_at / created_at datetime(3) ×4 可空 三时间戳 + 建档
apt_report_retry_batch id / gyid / batch_id bigint / varchar(32) / varchar(64) PK / UK (gyid, batch_id) 续报批次，POST /apt/report/retry 生成
state / trigger_type / item_count / success_count varchar(20) / varchar(20) / int ×2 默认 RUNNING MANUAL / AUTO
from_watermark / to_watermark bigint ×2 NOT NULL 续报区间，复用原 idempotencyKey
started_at / finished_at / created_by datetime(3) ×2 / varchar(64) 可空 —
apt_ledger_offline id / gyid / flow_id / type bigint / varchar(32) / varchar(64) / varchar(30) PK / UK (gyid, type, flow_id) 断网本地流水；type 见 表 3-15
amount / ryid / card_no / device_code decimal(12,2) / varchar(64) ×3 NOT NULL 金额定点数，禁止浮点
offline_scope / local_balance_version / quota_ref varchar(20) / bigint / varchar(64) 默认 LOCAL_ONLY 额度批次来自 #1
balance_before / balance_after decimal(12,2) ×2 NOT NULL 本地余额 CAS 前后值
occurred_at / synced_at / reconcile_state / created_at datetime(3) ×2 / varchar(20) / datetime(3) 默认 PENDING 恢复后冲正 / 对账

表 3-31 平台端新增表（T-14~T-16；逻辑类型族，docs/平台端/03 表 3-16 方言映射）

表 列 类型族 约束 / 默认 说明
pl_person_reg_request id / gyid / reg_id / work_no id_ulid / string(32) ×2 / string(64) PK / UK (gyid, reg_id) 接收侧主档同步回执（注册成功后由 #9 送达）
verdict / confirmed_ryid / reject_reason enum_s / string(64) / string(256) 默认 PENDING 同步回执 ACCEPTED / REJECTED；platform-master 校验工号唯一性与 checksum 后回填，不做注册准入审批（CR-C25）
photo_ref / feature_ref / photo_checksum / feature_checksum string(512) ×2 / string(128) ×2 可空 接收人员主数据人脸媒体引用与校验和；不接收业务抓拍、不入库媒体二进制（CR-C24、docs/公寓端/10 表 10-6）
feature_algo / feature_version / person_category string(32) / long / enum_s 默认 1 / TRANSIENT 算法兼容判定与长期驻留标识
verdict_version / decided_at / received_at long / ts_ms ×2 NOT NULL 审定版本与三时间戳
pl_offline_quota id / gyid / quota_ref id_ulid / string(32) / string(64) PK / UK (gyid, quota_ref) 离线额度批次
single_limit / daily_limit / max_outstanding decimal(12,2) ×3 NOT NULL #1 下行
version / effective_from / state long / ts_ms / enum_s 默认 1 / ACTIVE 版本单调（P-06 依赖）
pl_staff_performance_daily id / gyid / stat_date / ryid id_ulid / string(32) / date / string(64) PK / UK (gyid, stat_date, ryid) 跨公寓考核汇总，只接收不算明细
response_sec_avg / alarm_handled_rate / call_success_rate decimal(10,2) ×3 默认 0.00 —
source_version / received_at long / ts_ms NOT NULL 覆盖同日结果

6.4 补列、索引与迁移

表 3-32 既有表补列（设计定义，待阶段二评审）

表 补列 类型 默认 用途 需求
gy_jcxx call_mode varchar(20) SIP 区分 AMI 推断 / 平板上报两种状态来源 A-06、A-08
gy_jcxx dispatch_seq bigint NULL 顺序派发序号，平板模式必填 A-07
apt_report_outbox retry_batch_id varchar(64) NULL 关联续报批次 A-14
apt_master_room building varchar(64) NULL 楼栋（G-01 的正式落点）；Q-20 未决前仍用 room_floor + room_no 前缀筛选 A-11

表 3-33 索引与约束（新增表全部满足，不复制 docs/11 的 0 主键 / 0 索引缺陷）

类别 要求
主键 16 张表全部有代理主键 id；跨端业务 ID 用 ULID / UUID 字符串，不用自增作幂等键
唯一键 全部以 gyid 打头（UK 见表 3-27~3-31）；alarm_event_key / result_id / flow_id 保证幂等
查询索引 按 (gyid, jcsj)、(gyid, dispatch_seq)、(gyid, state, occurred_at)、(gyid, stat_date) 建复合索引
逻辑删除与审计 沿用三端分册口径；新增表使用 state / report_state 表达生命周期，不做物理删除
迁移顺序 先平台 3 张 → 再公寓 13 张 → 再 §10 补遗 apt_sip_reg_status 1 张（共 14 张）→ 最后 3 处补列；DDL 与数据回填分离，回填需可重放
方言 平台表按 docs/平台端/03 表 3-16 逻辑类型族，迁 MySQL 时只换物理类型、不改语义

7. 关键流程变更

表 3-34 流程变更总表（v1.0 的 F-A~F-H；原流程章节不变，本节为增量；F-I 见 §10、F-J 见 §12）

编号 流程 变更性质 涉及的原流程 需求
F-A 叫乘双模式与顺序派发 分支新增 docs/公寓端/05 §1 / §2；docs/应用端/05 §1 A-06、A-07
F-B 平板结果回写与刷脸判定 事件源新增 docs/公寓端/05 §2 状态机；docs/应用端/04 §5 A-08
F-C 换乘（时刻 + 换房联动） 新流程 docs/应用端/05 §3；docs/平台端/06 §3 A-09
F-D 断网本地充值 / 扣补贴与恢复冲正 新流程 docs/平台端/06 §6 F5；docs/应用端/05 §6 A-04
F-E 上报历史与失败批次续报 新流程 docs/公寓端/05 §6；docs/平台端/06 §5 F4 A-14
F-F 人员注册（签到终端申请 → 值班员确认入档 → 平台 / 设备分别同步） 新流程（v1.3 由 §12 F-J / CR-C25 改判） docs/公寓端/05 §5 主数据下行、docs/公寓端/10 §4 A-02
F-G 保洁、排班与盯控质量考核 新流程 docs/应用端/05 §1 / §7；docs/平台端/06 §7 A-12、A-13
F-H 设备报警分流 分叉新增 docs/公寓端/05 §3；#11 / #12 A-05

7.1 F-A 叫乘双模式与顺序派发

步 主体 动作 落表 失败 / 补偿
1 apt-dispatch 计划下行后按规则快照复算 jcsj（CR-C06），按 jcsj 升序生成 dispatch_seq gy_jcxx、apt_tablet_task 规则快照过期 → 40903，保留最后版本并告警
2 apt-dispatch 读 gy_jcxx.call_mode 分流：SIP 走原 Quartz + AMI 链路；TABLET 只置任务 WAITING apt_tablet_task features.tabletCall=false 时强制回落 SIP
3 平板 GET /open/v1/tablet/tasks（cursor），按 dispatch_seq 顺序拉取；单公寓同一时刻只派发一条 apt_tablet_task.pull_state 重复 ACK → 40916；超时未拉取置 EXPIRED 并转人工
4 apt-dispatch 派发后回执 #8（含 dispatchSeq、复算时刻） apt_report_outbox 回执失败不影响执行（沿用原口径）
5 apt.voice.event SIP 分支仍以 ConfbridgeJoin 判接通、30 s 无入会 ryzt=2、35 s 复叫 apt_call_session、gy_jcxx 事件丢失兜底比对不变

7.2 F-B 平板结果回写

步 主体 动作 落表 失败 / 补偿
1 平板 POST /open/v1/tablet/results（resultId + faceVerifyState + resultType） apt_tablet_call_result 同 resultId 重传返回首次结果
2 apt.device.gateway HMAC / 时间窗 / nonce 校验；只提交命令给 apt.duty.state，不直改 gy_jcxx duty_manual_action 校验失败丢弃并告警
3 apt.duty.state ANSWERED + VERIFIED → ryzt=3 / finish_jc='1'；UNVERIFIED / SKIPPED → 保留待确认并触发复叫与告警；NO_ANSWER → ryzt=2 + gy_bjxx(TIMEOUT) gy_jcxx、gy_bjxx 条件更新带期望态；迟到结果记 IGNORED
4 duty.ws 推 tablet.result（seq 单调） — 断连走 60 s 兜底轮询
5 apt-report 以 TABLET_RESULT 经 #9 上报 apt_report_outbox 断网进 outbox

7.3 F-C 换乘

步 主体 动作 落表 失败 / 补偿
1 值班员（duty 入口） 选交路，指定换乘开车时间 / 叫乘时间，可选新房间 → TRANSFER 命令（commandId + 原因） duty_manual_action 同 commandId 只生效一次；时刻非法 40915
2 apt.duty.command → apt.duty.state 校验 transferPolicy、任务未结束、人员在寓；建换乘单 DRAFT apt_transfer_order 策略不允许 / 已离寓 → 拒绝并留痕
3 apt-dispatch 本地复算 recomputedCallTime；与原 jcsj 不一致时以复算值执行并告警（CR-C06） gy_jcxx、apt_tablet_task 不取平台值
4 apt-stay + apt.voice.endpoint 若 newRoomId 非空：换房、gy_rooms 房态重算、apt_sip_binding 联动（沿用现有换房链路） gy_rooms、apt_sip_binding 目标房满 → 40901，整单 ROLLED_BACK
5 apt-report 经 #8 / #9 上报 TRANSFER（bizVersion 单调） apt_report_history 平台驳回由 #7 下行，公寓自己置 REJECTED，不是平台回调
6 duty.ws 推 transfer.changed — —

7.4 F-D 断网本地充值 / 扣补贴

步 主体 动作 落表 失败 / 补偿
1 值班员 / 消费机 本地充值登记或刷卡消费请求 apt_ledger_offline、gy_ykt_* 超 offlineQuota → 40913；断网时仍允许额度内受理
2 apt.ledger.local 校验 singleLimit / dailyLimit / maxOutstanding；按 localBalanceVersion 做 CAS 扣减，记 balance_before/after apt_ledger_offline CAS 冲突重读重试一次，再失败转人工
3 写入 offline_scope=LOCAL_ONLY，本地余额立即可用；不写平台主账 gy_ykt_remainder（本地缓存） 平台主账权威不变（docs/平台端/06 §6）
4 恢复 先派 outbox（CR-01 §2.9）→ #10 LEDGER_OFFLINE 逐条上报 → 平台按 serverReceivedAt 归日、UK (gyid,type,flow_id) 去重 PL_RECEIVE_LOG、PL_LEDGER_FLOW 余额不足 PF-5001 进人工；重复流水 PF-5002
5 冲正 平台日对账通过后，公寓把 offline_scope 置 RECONCILED 并更新 localBalanceVersion apt_ledger_offline 对账未结清禁止调账（PF-5003）
6 duty.ws 推 ledger.offline（含 quotaRemain） — —

7.5 F-E 上报历史与续报

步 主体 动作 落表 失败 / 补偿
1 apt.report.outbox 每次派发结束把终态写入 apt_report_history（成功 / 失败 / 死信 / 已续报） apt_report_history outbox 仍是队列，两者不互相替代（CR-C10）
2 运维 / 自动 POST /apt/report/retry 指定水位区间，生成 apt_report_retry_batch apt_report_retry_batch 同批次运行中 → 50302
3 apt.report.outbox 按区间取失败项，复用原 idempotencyKey 重发既有 #9~#14 接口，不产生新业务事实 apt_report_outbox.retry_batch_id 仍按原退避；不新增跨端编号
4 平台 幂等判重返回 PL-IDEMPOTENT-REPLAY，视为成功 PL_RECEIVE_LOG PL-VERSION-STALE → DEAD
5 duty.ws / #14 推 report.backlog；心跳带 pendingRetryBatches apt_report_watermark 积压超阈值触发横幅告警

7.6 F-F 人员注册链路（v1.3 由 §12 F-J / CR-C25 改判）

步 主体 动作 落表 失败 / 补偿
1 签到终端 发起 REG_APPLY，上传人员要素 + 照片 / 特征值 apt_person_face_reg(APPLIED) 媒体异常 40919 / 40920；已注册 40918；未决重复申请返回原 regId；不进主档、不下发、不上报
2 duty.ws / 值班台 生成待办，值班员核对要素与照片并"确认注册"（duty:person:reg + 二次确认） duty_operation_log、duty_manual_action 驳回写 reject_reason，媒体按 Q-32 清理；未确认不进主档
3 apt.face.registry 确认时生成 ryid、reg_state=CONFIRMED、local_only=0；apt-master-client 事务写 apt_master_person（人脸进入公寓服务系统） apt_person_face_reg、apt_master_person、apt_master_version 事务失败整体回滚、保持 APPLIED；确认前参与匹配 → 40914
4a apt.face.sync → apt-report 注册成功后上传平台：媒体签名直传 + #9 PERSON_REG（表 3-13） apt_report_outbox、pl_person_reg_request 断网进 outbox，恢复后复用原幂等键续报；不阻塞 4b
4b apt.face.scope / apt.face.dispatch 注册成功后下发公寓内设备：按 gy_sb.face_scope_* 计算目标集合并生成 FACE_ISSUE apt_device_command、gy_sb_xt 设备离线排队；范围为空记审计；不依赖平台回执
5 平台 / apt-master-client 平台回同步回执 ACCEPTED / REJECTED + platform_version，由 #2 拉取对齐；不做注册准入审批 apt_master_version、apt_person_face_reg.verdict 回执 REJECTED 只告警 + 待办，不回滚本地注册与已下发设备（Q-35）
6 展示 值班台可查注册态、平台同步态与设备缓存台账 — 抓拍 / 录音 / 签到现场图不出公寓；人员主数据人脸按 CR-C24 允许跨端

4a / 4b 为并行双路，各自幂等、各自重试；注册生效点是步 3 的值班员确认，不是平台回执（CR-C25）。完整时序、状态机与异常见 docs/公寓端/10 §4。

7.7 F-G 保洁、排班与考核

步 主体 动作 落表 失败 / 补偿
1 公寓管理员 维护保洁人员；值班员登记保洁记录，联动 gy_clean_task.state apt_clean_staff、apt_clean_record、gy_clean_task 同 recordId 幂等
2 值班长 排班（日期 + 班次 + 人员），duty_shift_handover 仍不启用 duty_roster 同 (shift_id, ryid) 唯一
3 apt-duty 日终按班次从事实表本地计算盯控质量指标（响应时长、报警处置率、叫乘成功率、人工干预次数） duty_performance 口径 Q-23 待决；重算覆盖同日结果
4 apt-report → platform-report #13 摘要 CLEAN_RECORD / STAFF_PERFORMANCE_DAILY 日汇总 pl_staff_performance_daily、PL_REPORT_DAILY 平台只汇总，不重算公寓明细
5 duty 入口 只读查看本人 / 本公寓排班与考核 — 跨公寓对比归平台

7.8 F-H 设备报警分流

步 主体 动作 落表 失败 / 补偿
1 apt.device.gateway 心跳超时 / 离线 / 故障码判定为设备报警，与叫乘、离寓报警分离 apt_device_alarm alarm_event_key 去重，同 key 不重复响
2 duty.ws 推 device.alarm；值班台处置后回写 handled_* apt_device_alarm 处置变更触发 bizVersion+1
3 apt-report #12 按 alarmSource 分组上报 DEVICE_ALARM；#11 摘要增 tabletCount apt_report_outbox gy_bjxx 原逻辑不变

8. 已执行的施工单

表 3-35 三端文档逐处修订（本轮已直接修改，非"只登记"）

各分册的新增章节统一置于 ## 0. v2 修订（CR-02）（放在追溯段之后、原 §1 之前），图表用独立编号 表 C-y，不占用各文件原有 表 x-y 序号；冲突行的旧表述则就地改判。

编号 文件 章节 修订内容
R-52 docs/公寓端/00-公寓端主要功能设计.md 全文重写 补全截断条目、编号化 A-01~A-14、补文档信息与修订记录、指向本文件
R-53 docs/公寓端/01-功能边界.md 表 1-4 #2/#3/#4/#6、表 1-5、§4 说明、新增 §0 入住 / 换房 / 离寓与账务改判本期；追加 6 个功能域与三条不变式
R-54 docs/公寓端/03-数据设计.md §1 标题、新增 §0 44 → 58 张口径；追加 13 张新增表归属、命名分区同步、3 处补列
R-55 docs/公寓端/04-接口设计.md 表 4-4、§7 房间域第 3 条、新增 §0 统一 40903 常量名、补 5 个新码；撤销"本期不提供入住 / 换房 / 退房接口"；追加 N-01N-05 设备侧与 N-15N-18 管理端接口
R-56 docs/公寓端/05-关键流程.md 表 5-1 第 4 行、新增 §0 按 R-C9 修正 jcsj 口径；追加 F-A~F-H 本端流程落点
R-57 docs/公寓端/09-平台接口约定.md 契约版本行、新增 §0 v1-draft → v2-draft；"20 不新增"改判为 payload 扩展；追加 bizType / 下行扩展字段 / 枚举与错误码指针
R-58 docs/平台端/01-功能边界.md 新增 §0 追加 v2 覆盖范围裁决（主账 vs 离线受理、登记确认、考核汇总、三条不变边界）
R-59 docs/平台端/03-数据设计.md 新增 §0 追加 T-14~T-16 三张表设计、PL_TASK.jcsj 与 44 张引用口径修正
R-60 docs/平台端/05-跨端接口对齐.md 契约版本行、§1 第 2 条、新增 §0 撤销"确需新增走 v2 不在本期"；追加既有编号的 payload 扩展与 bizType 分流
R-61 docs/平台端/06-关键流程.md 新增 §0 追加 F-C / F-D / F-E / F-G 的平台侧流程变更
R-62 docs/应用端/01-功能边界.md 表 1-9、表 1-6 第 14 项说明、新增 §0 撤销"不做任何账务动作"；追加换乘、平板结果、充值登记、排班考核四个域
R-63 docs/应用端/03-数据设计.md 新增 §0 追加 duty_roster / duty_performance 表归属与可写 / 只读边界
R-64 docs/应用端/04-接口设计.md 表 4-4 50101 行、新增 §0 统一错误码；追加 N-06~N-14 接口、5 类 WS 消息、5 个新码
R-65 docs/应用端/05-关键流程.md 新增 §0 追加 F-B / F-C / F-D / F-G 的本端流程变更与断网能力清单
R-66 docs/10-架构优化方案-三端拆分.md 表 0-2 修订记录、§3 章指针 追加 v1.3 / v1.4 修订记录与覆盖第 3、4、6 章的 CR-02 指针
R-67 三端 README.md + docs/README.md 文档清单 / 一页结论 / 索引 收录 00 与本文件、同步依据版本、20 接口与 58 张表口径

按 docs/10 附录 D，新增 / 调整端职责、模块划分、跨端接口时须同步第 3、4、6 章与附录 B 图表清单；CR-02 未新增跨端编号，附录 B 图表索引不变，已在 docs/10 第 3 章开头追加覆盖第 3、4、6 章的 CR-02 指针。

9. 待决策点与验收

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

编号 待决事项 未决默认口径 拍板时点 影响
Q-20 apt_master_room.building 补列是否本期执行 不补列，沿用 room_floor + room_no 前缀筛选（G-01 兜底） 阶段二建表清单定稿前 A-11、表 3-32
Q-21 断网离线额度数值与累计口径 #1 下发 singleLimit / dailyLimit / maxOutstanding，缺省全 0（即断网不开放） 契约冻结签字时 A-04、F-D
Q-22 平板刷脸 UNVERIFIED 是否直接判复叫 触发复叫 + 告警，但保留人工确认入口 阶段三试点前 A-08、F-B
Q-23 盯控质量考核指标口径与权重 四指标等权、本地计算、平台只汇总 阶段三 D 批开工前 A-13、F-G
Q-24（v1.3 由 CR-C25 改判） 注册申请人员的运安匹配准入 值班员确认注册前一律 40914，不参与匹配、不下发设备；确认后即可匹配，平台上报属异步同步不阻塞 契约冻结签字时 A-02、F-F、F-J
Q-25 换乘是否允许改开车时间（newDepTime） 允许，但必须同时重算叫乘时刻并留痕 阶段三试点前 A-09、F-C

表 3-37 验收要点（写入各端 07 时按此表展开）

# 验收项 判据
1 覆盖范围 三端 01 不再出现"入住 / 离寓属后续"、"不做任何账务动作"等与本文件冲突的表述
2 协议 跨端仍为 20 个编号、平台零回调；平板 / 消费机 / 值班台协议分层清晰，设备侧一律拉取
3 数据 新增 16 张表 + §10 补遗 1 张（共 17 张）全部有主键、gyid 打头的唯一键与查询索引；§12 人脸模块不新增业务表（复用既有表 + 补列，59 张口径不变）；抓拍 / 录音不出公寓、人员主数据人脸按 CR-C24 允许跨端；验收 911 见 §10 表 3-43、验收 1517 见 §12 表 3-52
4 叫乘 SIP 与 TABLET 双模式均可闭环；dispatch_seq 严格单调；UNVERIFIED 触发复叫与告警
5 换乘 时刻重算、换房联动、分机绑定、bizVersion 单调、平台驳回落库五项全通
6 账务 断网额度内本地可用、恢复后先派 outbox 再拉 #7、serverReceivedAt 归日、对账未结清禁止调账
7 上报 outbox / history / retry batch 三者语义分离；续报复用原 idempotencyKey，不产生重复业务事实
8 状态机 所有新增事件源都只提交命令给 apt.duty.state，无任何直改 ryzt / finish_* / stoped 的写入

10. 补遗：Asterisk 配置数据管理与 SIP 分机离线告警（v1.1）

触发依据：docs/公寓端/00 v1.1 §3（A-05 / A-06 / A-08 的细化，细化项 AC-01AC-05，不新增 A-15 以后编号）。现状依据：docs/backend/10 表 1-1「分机没有独立台账」；上位依据：docs/10 §5.4 表 5-3、§7.8 表 7-4、docs/公寓端/03 §3.3 表 3-11、docs/公寓端/08「注册状态不可靠」。 权威关系：四类数据表的字段定义、增删改查、权限控制与离线告警规则以 docs/公寓端/00 §3（表 0-40-18）为准；本节只登记口径裁决、流程增量、施工单与决策点。跨端 20 个接口编号、契约版本 v2-draft、平台不回调、附录 B 图表索引全部不变。

表 3-38 补遗范围

项 内容 权威位置
模块功能 AC-01 分机表、AC-02 呼叫记录表、AC-03 录音文件表、AC-04 注册在线状态表、AC-05 分机状态离线告警 docs/公寓端/00 §3.1 表 0-4、0-5
字段定义 apt_sip_endpoint（表 0-6）、apt_call_session（表 0-7）、apt_recording（表 0-8）、apt_sip_reg_status（表 0-9，新增 T-17） docs/公寓端/00 §3.2
CRUD 与接口 四类表 CRUD 矩阵（表 0-10）、N-19~N-24 端内接口（表 0-11） docs/公寓端/00 §3.3、docs/公寓端/04 §0 表 C-4
权限控制 权限点矩阵（表 0-12）、六条硬要求（表 0-13） docs/公寓端/00 §3.4
离线告警 触发条件（表 0-14）、级别（表 0-15）、通知（表 0-16）、留存（表 0-17）、Q-26~Q-28（表 0-18） docs/公寓端/00 §3.5

表 3-39 新增裁决 CR-C15~CR-C19（冲突时以本表为准）

编号 事项 裁定
CR-C15 注册在线状态是"字段"还是"表" 主从，不产生第二真源：apt_sip_endpoint.register_status 为当前态唯一权威字段（apt.voice.endpoint 写）；新增 apt_sip_reg_status 为只追加的状态变迁流水（apt.voice.event 写），用于离线持续时长、告警去重与对账回溯。禁止把流水当当前态读，禁止两写入口互写
CR-C16 事实类表能否人工增删改 不能：apt_call_session、apt_recording、apt_sip_reg_status、apt_device_alarm 不开放人工 CUD 接口；只允许对应领域模块写入或带 commandId 的受控命令（归档 / 清理 / 重探 / 处置）；更正以新记录 + biz_version+1 体现
CR-C17 分机离线是否单独建告警体系 不单独建：复用 apt_device_alarm（alarmSource=DEVICE、alarmType=OFFLINE）、/ws/duty device.alarm 与 alarm.cleared、#12 DEVICE_ALARM；不新增 WS 消息名、不新增 bizType、不新增跨端编号。告警不阻断叫乘，失败原因记 apt_call_session.hangup_cause
CR-C18 register_status 与分机资源状态机的关系 补充枚举 ONLINE / OFFLINE / UNREACHABLE / UNKNOWN；不改 sync_state 的 PENDING / SYNCED / FAILED / DRIFT 四值状态机（docs/10 表 7-4、docs/公寓端/03 表 3-11），DISABLED / DELETED 仍由 enabled / deleted 表达
CR-C19 表数口径 公寓本地库业务表 58 → 59 张（+ T-17）；表 3-25、3-26、3-33 与 docs/公寓端/03 §0、三端 README、docs/10 v1.5 已同步。§8 施工单 R-54 / R-67 中的「58 张」「16 张」属 v1.0 历史口径，按本节理解；平台库仍为新增 3 张 pl_*

表 3-40 T-17 关键约束（列级定义见 docs/公寓端/00 表 0-9）

项 要求
键与索引 id PK；UK (gyid, endpoint_id, event_seq)；IDX (gyid, state, occurred_at)、(gyid, endpoint_id, occurred_at)；event_seq 同分机单调
写入语义 只追加、无 update_time；source ∈ AMI_EVENT / QUALIFY / PROBE / MANUAL / RECONCILE；双源判定（注册事件 + qualify / 定时探测）
告警关联 alarm_id 关联 apt_device_alarm；alarm_event_key = hash(gyid, endpoint_id, 'SIP_OFFLINE', offline_since)；恢复只追加不清空
留存 在线 90 天、按月归档；同一离线周期的起止必须成对可查

表 3-41 新增流程 F-I：SIP 分机注册离线告警

步 主体 动作 落表 失败 / 补偿
1 apt-dispatch 判 gy_jcxx.call_mode='SIP'；按 jcid → fjh → apt_sip_binding(ROOM, is_primary=1, 生效区间) → apt_sip_endpoint 解析房间主分机 apt_sip_binding、apt_sip_endpoint 绑定缺失 → apt_ast_drift 告警，不误报"注册离线"
2 apt.voice.endpoint / apt.voice.event 双源判定注册态：非 ONLINE 或 last_reg_at 超阈值，且 offline_since 持续超阈值；校验 enabled=1 / deleted=0 / sync_state='SYNCED' apt_sip_reg_status PENDING/FAILED/DRIFT → 40905 或对账告警；AMI 断连标 UNKNOWN + P2
3 apt.device.gateway 按 alarm_event_key 去重，写 apt_device_alarm（DEVICE / OFFLINE / P0~P2） apt_device_alarm 同 key 不重复响、不重复推；不提交状态机命令、不改 gy_jcxx
4 duty.ws / apt-report 推 device.alarm；P0 入两级提醒 + TTS；#12 DEVICE_ALARM、#11 摘要、#13 计数、#24 regRate apt_report_outbox 断网先落本地 + outbox，恢复后复用原幂等键续报（F-E）
5 恢复闭环 写新流水 ONLINE → 置 register_status='ONLINE' → 置 cleared_at → 推 alarm.cleared apt_sip_reg_status、apt_sip_endpoint、apt_device_alarm 只追加不清零；处置回写 handled_* 触发 bizVersion+1

阈值默认：注册探测 120 s、离线持续 60 s（Q-26）；告警级别：有待叫乘任务 P0、无任务但分机离线 P1、UNKNOWN / 中继 P2；留存：告警在线 180 天 + 归档、注册流水 90 天、录音 90 天且 PURGED 不删索引（表 0-15~0-17）。

表 3-42 施工单追加（R-68~R-76，本轮已直接修改）

编号 文件 章节 修订内容
R-68 docs/公寓端/00-公寓端主要功能设计.md 新增 §3、§3→§4、表 0-2 Asterisk 配置数据管理模块全量补充（v1.1）
R-69 docs/设计变更/03（本文） 表 0-2 / 0-3、CR-C14、表 3-25 / 3-26 / 3-33、新增 §10 补遗登记与 58 → 59 张口径同步
R-70 docs/公寓端/01-功能边界.md §0、表 1-5 语音域补遗说明、启动前置与表数口径
R-71 docs/公寓端/03-数据设计.md §0 表 C-1 / C-2、命名分区、§1 标题 14 张 / 59 张、apt_* 35 张、注册态主从口径
R-72 docs/公寓端/04-接口设计.md §0 表 C-4 N-19~N-24 接口与六条权限硬要求
R-73 docs/公寓端/05-关键流程.md §0 表 C-1 追加 F-I 流程落点
R-74 docs/公寓端/09-平台接口约定.md §0 表 C-4 #11 / #12 / #13 / #24 的告警 payload 扩展
R-75 三端 README.md + docs/README.md 索引 / 结论 / 口径 收录 00 §3 与补遗，同步 59 张与 17 张表口径
R-76 docs/10-架构优化方案-三端拆分.md、docs/应用端/02、03、docs/平台端/03 表 0-2、§3 指针、表 2-1、§0、表 C-2 追加 v1.5 修订记录，同步 59 张口径与 register_status 枚举说明

表 3-43 决策点与验收追加

项 内容
Q-26 注册探测阈值 / 离线持续阈值：默认 120 s / 60 s，阶段二契约冻结前拍板
Q-27 分机离线是否自动降级为平板 / 广播：默认不自动切换，仍发起 SIP 并记失败原因，阶段三试点前拍板
Q-28 告警记录在线留存 180 天是否合规：默认在线 180 天 + 按月归档、索引长期保留，阶段三 D 批开工前拍板
验收 9 四类数据表字段、CRUD 与权限点矩阵齐全；事实类表无人工 CUD 接口；gyid 数据域锁定；写操作两级审计
验收 10 call_mode='SIP' 且房间主分机离线时能按条件触发 P0/P1/P2 告警、同一离线周期只一条、通知与 #12 上报闭环、恢复只追加不清零
验收 11 告警不阻断叫乘；录音回放短期签名 ≤ 5 分钟且仅内网；录音、业务抓拍与注册流水明细不出公寓（人员主数据人脸按 CR-C24 允许跨端，见 §12）；平台零回调

11. 补遗：两类叫乘实现方式的端到端流程（v1.2）

触发依据：明确 A-06 / A-07 / A-08 的两类实现方式——SIP 语音叫乘（Asterisk 主动发起呼叫，房间 SIP 终端接听入会后播放提示语音完成叫乘，叫乘状态由业务系统依据 AMI 事件上报）与平板叫乘（平板拉取叫乘任务，到达 jcsj 后本地播放语音，人员刷脸确认签到结束叫乘，随后把结果上报公寓服务）。 流程权威表述：docs/公寓端/05 §9（表 5-95-21、图 5-85-9）。本节只登记裁决、落点、施工单与决策点；§7.1 F-A / §7.2 F-B、docs/10 §7.7 / §7.9 表 7-5 的骨架不变，本节补齐"平板本地定时播放"与"结果反馈路径"两个此前未展开的环节。未新增数据表、跨端接口编号、bizType、WS 消息名或状态字段。

表 3-44 新增裁决 CR-C20~CR-C23（冲突时以本表为准）

编号 事项 裁定
CR-C20 "接听后播放提示语音完成叫乘"的判据 接通判据是 AMI ConfbridgeJoin（房间侧入会），不是 SIP Answer（docs/10 §7.7 第 2 条）。入会即提交 ANSWERED → ryzt=3 / finish_jc='1' 完成叫乘；Playback(tts) 在入会后播放，apt_tts_utterance 的 DONE / FAILED 与 apt_recording.state 不回退、不改写叫乘终态（沿用 docs/公寓端/05 §4 第 3 条）
CR-C21 "状态由业务系统依据 AMI 事件上报"的路径 统一为三段：apt.voice.ami 收事件 → apt.voice.event 判业务状态 → 提交状态机命令（apt.duty.state 唯一写入口）→ 条件更新 gy_jcxx → apt-report 经 #8 / #9 / #24 上行。AMI 事件既不直接写业务表，也不单独构成对外上报；平板链路同构，事实源换成 N-04 的 TABLET_RESULT
CR-C22 平板"拉取任务"与"到点播放"的关系 拉取 ≠ 执行：服务端只生成 apt_tablet_task(WAITING) + dispatch_seq，不向平板推送呼叫指令（CR-C08）；平板提前按 cursor 拉取并以 serverTime 校准时钟，到 jcsj 由平板本地定时器播放语音、开启刷脸签到窗口。断网时缓存任务仍可播放，结果入本地队列恢复后按 resultId 重传；只传 faceVerifyState / verifiedRyid，抓拍帧、人脸原图与比对帧不出终端；比对所需特征值按 docs/公寓端/10 的设备权限范围下发（CR-C24）
CR-C23 两类方式的终态与上报 共用 gy_jcxx.ryzt / finish_jc 一套终态语义（表 5-20），跨端 payload 一律带 callMode；#24 语音质量摘要只由 SIP 链路发送，平板链路走 #9 TABLET_RESULT + #13 归档。一条 jcid 只有一种事实来源，执行中不切换方式；TABLET 在 features.tabletCall=false 或平板离线时回落 SIP

表 3-45 流程落点索引（均以 docs/公寓端/05 §9 为准）

维度 SIP 语音叫乘 平板叫乘 表 / 图
方式对照与模式选择 call_mode、回落、顺序派发、共用状态机 同左 表 5-9、5-10
触发条件 Quartz 到 jcsj / 人工发起、分机与会议桥前置、F-I 离线告警不阻断 任务生成、平板在册与心跳、平板本地到 jcsj、签到窗口 表 5-11、5-14
交互流程 8 步：CALL_START → Originate → 终端接听入会 → ANSWERED → Playback(tts) → 归档上报 10 步：生成任务 → 拉取 / ACK → 时钟校准 → 本地播放 → 刷脸签到 → N-04 上报 → 状态机命令 图 5-8 / 5-9；表 5-12、5-15、5-16、5-17
状态上报机制 AMI 事件 → 状态机命令 → gy_jcxx → outbox 平板结果 → 状态机命令 → gy_jcxx → outbox 表 5-13、5-18
结果反馈路径 值班台 /ws/duty、平台 #8 / #9 / #24 / #13、本地留痕、异常兜底 值班台 tablet.result + state.changed、平台 #9 / #8 / #13、本地留痕、异常兜底 表 5-19、5-20

表 3-46 施工单追加（R-77~R-84，本轮已直接修改）

编号 文件 章节 修订内容
R-77 docs/公寓端/05-关键流程.md 新增 §9（表 5-95-21、图 5-85-9） 两类叫乘方式的端到端流程全量补充（流程权威表述）
R-78 docs/设计变更/03（本文） 表 0-2 / 0-3、新增 §11 补遗登记、编号范围扩至 CR-C23 / Q-29
R-79 docs/公寓端/04-接口设计.md §0 表 C-5 N-03 任务负载（含 jcsj / serverTime）、N-04 结果契约与不直改 gy_jcxx 口径
R-80 docs/公寓端/03-数据设计.md §0 SIP / 平板两类落表与共用终态语义
R-81 docs/公寓端/09-平台接口约定.md §0 表 C-5 #8 / #9 / #12 / #13 / #14 / #24 按 callMode 分流的每日径
R-82 docs/公寓端/01-功能边界.md、docs/公寓端/00 §4 §0 / 关系第 4 条 两类方式指针，需求基线编号不变
R-83 docs/公寓端/README.md、docs/README.md 文档清单 / 索引 收录 05 §9 与 CR-02 §11
R-84 docs/10-架构优化方案-三端拆分.md 表 0-2 修订记录 追加 v1.6，声明 §7.7 / §7.9 表 7-5、表 7-6 与附录 B 不变

表 3-47 决策点与验收追加

项 内容
Q-29 平板签到窗口 signTimeoutSec、语音重播次数与 clockSkewMs 阈值：默认 60s / 1 次 / 1s，阶段二契约冻结前拍板
验收 12 SIP 链路以 ConfbridgeJoin 判接通、30s 无入会转 ryzt=2 + 复叫；TTS / 录音失败不改叫乘终态；状态只经 apt.duty.state 条件更新落库
验收 13 平板提前拉取任务并按 jcsj 本地定时播放；断网仍可播放、结果按 resultId 幂等续传；VERIFIED → ryzt=3 / finish_jc='1'，UNVERIFIED / NO_ANSWER → 复叫 + 告警；抓拍帧与人脸原图不上报，比对所需特征值按 docs/公寓端/10 的设备范围下发
验收 14 两类方式共用终态矩阵与 outbox 上行；值班台 / 平台 / 本地留痕 / 异常兜底四条反馈路径齐全；payload 带 callMode；#24 只由 SIP 发送；跨端 20 接口编号与 v2-draft 契约形态不变

12. 补遗：人脸数据下发管理与注册链路改判（v1.3）

触发依据：新建 docs/公寓端/10-人脸数据下发管理.md（完整数据管理模块），并澄清人员注册口径——注册由签到终端发起申请并上传人脸，在值班员处完成人员注册；注册成功后人脸进入公寓服务系统，再分别上传平台与下发公寓内设备。 权威关系：docs/公寓端/10 是"人员人脸主数据注册、平台 ↔ 公寓同步、设备下发、权限隔离与离寓清理"的唯一权威表述（AF-01AF-06、表 10-110-30、图 10-1 / 10-2、N-25~N-37）；本节只登记口径裁决、流程增量、施工单与决策点。跨端 20 个编号、契约 v2-draft、平台不回调公寓、公寓本地库 59 张口径、附录 B 图表索引全部不变；本补遗不新增业务表（复用既有表 + 补列 + 规则，DDL 待阶段二冻结评审）。

表 3-48 补遗范围与权威位置

项 内容 权威位置
模块功能 AF-01 注册与双路同步、AF-02 平台下载入库、AF-03 签到设备下发、AF-04 消费 / 叫乘设备隔离、AF-05 离寓擦除、AF-06 长期驻留保留 docs/公寓端/10 §3 表 10-8
注册链路 签到终端 REG_APPLY → 值班台待办 → 值班员 CONFIRM → apt_master_person 入档 → 分别 #9 上传平台 / FACE_ISSUE 下发设备 §4、图 10-2、表 10-9~10-11
数据模型 复用 8 张表 + 补列（表 10-5 / 10-6）、枚举字典（表 10-7） §2
接口与错误码 N-25N-37、40914 / 4091740924 / 50303 §13 表 10-26~10-28
权限与异常 九类动作留痕、签到终端 / 值班台职责分离（表 10-24）、异常场景（表 10-25） §11、§12
决策与验收 Q-30Q-35、验收 110 §14 表 10-29、10-30

表 3-49 新增裁决 CR-C24、CR-C25（冲突时以本表为准）

编号 事项 裁定
CR-C24 "原图与特征大对象不出公寓"是否覆盖人员主数据 不覆盖。该表述只针对业务过程抓拍、录音与识别结果；人员主数据的照片与特征值允许且必须在平台 ↔ 公寓间双向同步并按设备范围下发，库内只存引用与校验和、媒体本体走短期签名直传。抓拍、录音、签到现场图仍不出公寓，识别结果上报不带图像。表 3-13、表 3-24、表 3-31 及 docs/公寓端/09、docs/平台端/07 已就地改判；不因本裁决放开媒体边界
CR-C25 人员注册的发起方、生效点与同步顺序 签到终端发起注册申请并上传人脸 → 值班员在值班台完成人员注册 → 注册成功后人脸进入公寓服务系统（apt_master_person）→ 分别上传平台与下发公寓内设备。注册生效点为值班员 CONFIRM；平台 personRegVerdicts[] / verdict 降级为主档同步回执（ACCEPTED / REJECTED），不再是注册准入审批也不是生效前置。两条同步路径解耦并行、各自幂等、互不阻塞：平台不可达不阻塞设备下发，设备离线不阻塞平台上报
CR-C25-a 覆盖清单 表 3-1 A-02、表 3-2 第 3 行、CR-C04、表 3-7 #2 / #9、表 3-10 40914、表 3-13 PERSON_REG、表 3-19 regVerdict、表 3-27 T-04、表 3-31 T-14、§7.6 F-F、Q-24、docs/公寓端/04 表 4-4 / 表 C-3、docs/公寓端/05 表 C-1、docs/应用端/04 N-08 均按本表理解或已就地改判
CR-C25-b 不变项 平台仍是跨公寓人员主档真源；gyid 数据域锁定；下行一律"拉"、设备主动拉取；状态字段仍只有 apt.duty.state 一个写入口；apt_master_person 对业务模块只读，唯一写入口为注册确认时 apt-master-client 的事务写

表 3-50 新增流程 F-J：人员注册与双路同步（完整时序见 docs/公寓端/10 §4.2 图 10-2）

步 主体 动作 落表 失败 / 补偿
1 签到终端 REG_APPLY 上传人员要素 + 人脸，落 APPLIED apt_person_face_reg 媒体异常 40919 / 40920、已注册 40918；不进主档
2 值班台 值班员核对并确认 / 驳回（duty:person:reg + 二次确认） duty_manual_action、duty_operation_log 驳回留 reject_reason，按 Q-32 清理媒体
3 apt.face.registry 生成 ryid、CONFIRMED、local_only=0，事务写 apt_master_person apt_person_face_reg、apt_master_person、apt_master_version 事务失败整体回滚、保持 APPLIED；确认前匹配 → 40914
4a apt.face.sync #9 PERSON_REG + 媒体签名直传，平台回同步回执 apt_report_outbox、pl_person_reg_request 断网 outbox 续报；REJECTED 告警 + 待办，不回滚注册（Q-35）
4b apt.face.dispatch 按 gy_sb.face_scope_* 生成 FACE_ISSUE，设备主动拉取并 ACK apt_device_command、gy_sb_xt 设备离线排队；摘要不一致 → FACE_FULL_SYNC
5 apt.face.scope / 离寓清理 TRANSIENT 离寓自动 FACE_ERASE；LONG_TERM 独立分区长期保留 apt_device_command、apt_master_person.person_category 擦除超时 → P1 告警 + 全量同步（Q-30）

4a / 4b 并行双路；注册生效点是步 3，不是平台回执。docs/公寓端/10 §4.4 的 reg_state 状态机、upload_state / dispatch_state 双状态链是本节的实现口径。

表 3-51 施工单追加（R-85~R-93，本轮已直接修改）

编号 文件 章节 修订内容
R-85 docs/公寓端/10-人脸数据下发管理.md 全文 新建人脸数据下发管理模块（v1.0 六项功能 + v1.1 注册链路改判）
R-86 docs/设计变更/03（本文） 表 0-2 / 0-3、CR-C04、表 3-1 / 3-2 / 3-7 / 3-13 / 3-17 / 3-19 / 3-24 / 3-27 / 3-31、§7.6、Q-24、新增 §12 补遗登记；媒体边界与注册链路就地改判
R-87 docs/公寓端/00-公寓端主要功能设计.md 表 0-2 / 0-3、§4 需求基线 v1.2、A-02 三端归属改判与 §12 指针
R-88 docs/公寓端/01、03 §0 功能域指针、补列与 owner 口径同步
R-89 docs/公寓端/04-接口设计.md §0 表 C-6、表 C-3 / 表 4-4 N-25~N-37、40914 改判与新增错误码
R-90 docs/公寓端/05-关键流程.md §0 表 C-1、§9 F-J 流程索引与媒体口径改判
R-91 docs/公寓端/09-平台接口约定.md §0 表 C-6、表 C-2 / C-3 #2 / #9 / #11 / #14 人脸扩展与同步回执语义
R-92 三端 README.md + docs/README.md 清单 / 索引 / 一页结论 收录 10 与 CR-02 §12，同步 59 张 / 20 接口 / v2-draft
R-93 docs/10-架构优化方案-三端拆分.md、docs/平台端/*、docs/应用端/* 表 0-2、§3 指针、§0 追加 v1.7；平台侧对象存储与人员照片口径、应用端 N-08 审核入口
R-94 docs/公寓端/02、06、07、08、docs/平台端/03、05、06、docs/应用端/01、03、05、07 顶部追溯 / §0 / 表 C-1 / 表 C-2 分册同步补全：apt-face 子域归属与技术基线不变、媒体配置项、Q-30~Q-35 与验收入口；平台侧登记表补列 / 同步回执语义 / #9 上报时点；应用端注册审核职责、只读边界、F-F 流程与验收入口

表 3-52 决策点与验收追加

项 内容
Q-30~Q-35 见 docs/公寓端/10 表 10-29：擦除时限与告警级别、设备离线期间禁用本地人脸放行、保留期与删除留痕、媒体签名有效期与大小上限、LONG_TERM 标注来源；Q-35 为平台驳回注册结果（如 DUPLICATE_WORK_NO）时是否自动擦除已下发设备缓存，默认不自动擦除（保留本地注册与设备缓存，告警 + 值班台待办 + 暂停后续下发，由值班员人工归并）
验收 15 注册链路四段闭环：申请只落 APPLIED 且不进主档 / 不下发 / 不上报；值班员确认生成 ryid 并入 apt_master_person；确认后 #9 上传平台与 FACE_ISSUE 下发设备双路自动触发且互不阻塞；平台驳回不回滚本地注册（CR-C25）
验收 16 六项功能齐备：#2 增量下载入库、签到设备全字段下发、CONSUME / CALL 按设备范围隔离且不含照片、TRANSIENT 离寓擦除有 ACK、LONG_TERM 独立分区不误删、三级版本与 hash 对账及 FACE_FULL_SYNC 兜底
验收 17 边界不破：抓拍 / 录音 / 签到现场图不出公寓；人员主数据人脸按 CR-C24 允许跨端；跨端 20 编号、v2-draft、59 张表、附录 B 图表索引不变；九类动作全部留痕

13. 补遗：人员入住作业流程（v1.4）

触发依据：新增 docs/公寓端/11-人员入住作业流程.md，要求覆盖「注册与签到、入住申请、值班员审核、数据提报与匹配、叫乘环节」五环节，以及各环节状态流转、关键数据表结构与接口清单（含请求 / 响应字段）。 权威关系：docs/公寓端/11 是入住作业流程端到端的唯一权威表述（CI-01CI-05、表 11-111-35、图 11-1~11-3）；本节只登记口径裁决、流程增量、施工单与决策点。跨端 20 个编号、契约 v2-draft、平台不回调公寓、jcsj 恒由公寓复算、apt.duty.state 单写入口、公寓本地库 59 张表、附录 B 图表索引全部不变；本补遗不新增业务表、不新增跨端编号、不新增 bizType、不新增 gy_jcxx 状态字段，采用"复用 apt_local_task + 补列 + 规则"实现（补列均为设计定义，DDL 待阶段二契约冻结评审，Q-40）。

表 3-53 补遗范围与权威位置

项 内容 权威位置
五环节 CI-01 注册与签到、CI-02 入住申请、CI-03 值班员审核、CI-04 数据提报与匹配、CI-05 叫乘环节 docs/公寓端/11 §4~§8
状态流转 三条状态链（申请审核态 / 同步匹配态 / 业务事实态）、10 步全流程状态表、审核状态机 §2 表 11-4 / 11-5、图 11-2
数据模型 复用表清单、apt_local_task 列级结构、关键事实表相关列、枚举字典 §3 表 11-6~11-9
接口清单 端内 N-38~N-47、跨端 #2 / #6 / #7 / #8 / #9 请求 / 响应字段 §9 表 11-30 / 11-31，§4~§8 各字段表
异常与权限 12 类异常处理、七条权限与审计要求 §10 表 11-32 / 11-33
决策与验收 Q-36~Q-40、8 项验收要点 §11 表 11-34 / 11-35

表 3-54 新增裁决 CR-C26~CR-C30（冲突时以本表为准）

编号 事项 裁定
CR-C26 "入住人员状态更新为已入住"如何表达，是否新增 gy_jcxx 状态字段 不新增状态字段。已入住 = apt_local_task.checkin_state=CHECKED_IN（流程态）+ 业务事实 gy_jcxx.finish_ly='0' AND sjlysj IS NULL + 已写 gygl_ly_event(CHECKIN)。checkin_state / sync_state 是申请单流程态，不是 gy_jcxx 状态字段；ryzt / finish_jc / finish_ly / stoped 仍只经 apt.duty.state 条件更新，已结束不回写、已离寓不回写、stoped 不可逆（表 3-9 / 3-10、docs/backend/05 §2.1）
CR-C27 入住申请单落在哪张表 不新增业务表（59 张不变）：申请单作为 apt_local_task 的申请阶段记录（docs/设计变更/01 表 1-17「本地建单」表，已带 origin=CHECKIN_ROUTE / CHECKIN_PENDING 与 match_state 五值），补 apply_id / checkin_state / sync_state / fjh_final / review_* / face_* 等列。apply_id ↔ 预分配 jcid 一对一；申请阶段不建 gy_jcxx 行，审核通过办理入住时由 apt-stay 沿用同一 jcid 建行（docs/backend/05 §2.1、docs/设计变更/01 表 1-12）
CR-C28 五环节接口边界 端内新增 N-38~N-47（承接 §12 的 N-37，不计入跨端 20 个编号）；入住事实上报固定 #9 + CHECKIN / CHECKOUT / ROOM_SWAP（bizId = jcid + 事件序号，表 3-12 / 3-14 已有），运安乘务计划 #6、任务变更与匹配结论 #7、任务回执 #8。平台零回调，匹配结论只能放 #7 响应体 matchVerdict[]（与 replayHint 同级，docs/设计变更/02 R-05），不得新开推送通道或新增 bizType
CR-C29 平台匹配与 jcsj 权威 #8 是平台匹配的输入（联网时下一上报周期必发，否则长期 UNMATCHED）；平台按 gyid + cardNo/workNo + 日期 + 车次 + 交路 查 GY_SYN_JCXX 快照，命中补 kcsj / jcfs 并写 PL_TASK_CHANGE(op=UPSERT)。match_state 沿用正式五值 PENDING / MATCHED / UNMATCHED / LOCKED / REJECTED（LOCAL_ONLY 属 offlineScope，不是匹配状态）；UNMATCHED / LOCKED 保留公寓上报要素不清空、不删既有任务（D8' 例外①②）。jcsj 及派生恒由公寓按 apt_master_rule 复算，PL_TASK.jcsj 只是基线、禁止逐项覆写（CR-C06）
CR-C30 房间调整与交路可选 房间调整（N-45）仅审核期（未建 gy_jcxx）允许，复用 F-C 换房联动（gy_rooms 房态重算 + apt_sip_binding + ROOM_SWAP 事件），但不产生换乘单、不改 jcid、不重算 jcsj；已办理入住后的换房走 F-C TRANSFER。交路可确定时 origin=CHECKIN_ROUTE，否则 CHECKIN_PENDING 由平台匹配补齐，两种情况均不阻塞入住（Q-36）
CR-C28-a 覆盖清单 表 3-1 A-03、表 3-3 功能域 1、表 3-12 / 3-14 CHECKIN payload、表 3-8 端内接口清单（历史 N-01~N-18）、表 3-34 流程总表、docs/公寓端/04 §7 房间域第 3 条、docs/公寓端/05 §0 表 C-1、docs/公寓端/09 表 9-1、docs/平台端/05 表 5-1 / 表 C-2 均按本节理解或已就地补指针；不改动 20 个编号、方向与路径

表 3-55 新增流程 F-K：人员入住作业（完整时序见 docs/公寓端/11 图 11-1 / 11-3）

步 环节 主体 动作 落表 / 编号 失败 / 补偿
1 CI-01 注册与签到 签到终端 → apt.face.registry N-38 扫脸核验；未注册走 docs/公寓端/10 §4 的 N-34 → N-36，确认后重新核验 apt_master_person（只读）、apt_person_face_reg 未确认 40914；缓存过期 40927；核验结论不带图像
2 CI-02 入住申请 签到终端 → apt-stay N-39 拉房间 / 交路，N-40 提交申请；8 项校验后建申请单 + 预分配 jcid apt_local_task(SUBMITTED) 重复 deviceEventId 返回原 applyId；房间不可住 40928；不建 gy_jcxx
3 CI-03 值班员审核 值班台 → apt-stay N-42 / N-43 接单查看；N-44 审核、N-45 换房（可多次）；通过后单事务办理入住 apt_local_task(CHECKED_IN)、gy_jcxx、gygl_ly_event(CHECKIN)、gy_rooms、apt_sip_binding 并发 40926；事务失败整体回滚至 APPROVED；驳回 / 取消为终态
4 CI-04 提报 apt-report #9 CHECKIN（表 11-21）入 outbox 并上报 apt_report_outbox、PL_RECEIVE_LOG 断网 outbox 续报，不阻塞本地入住与叫乘准备
5 CI-04 匹配 平台 / apt-dispatch #6 拉计划、#8 回执作匹配输入、平台查运安快照、#7 响应体带 matchVerdict[] GY_SYN_JCXX、PL_TASK / PL_TASK_CHANGE、apt_local_task.match_state UNMATCHED 保留本地要素；LOCKED 不覆盖本地锁定；REJECTED 转待办
6 CI-05 叫乘 apt-dispatch → apt.duty.state #7 拉任务 → 按 apt_master_rule 复算 jcsj → 回 #8 → 按 jcsj + dispatch_seq 派发 gy_jcxx、gy_syn_jcxx_status、N-47 关联查询 已离寓迟到任务 IGNORED；两类叫乘执行见 docs/公寓端/05 §9

表 3-56 施工单追加（R-95~R-103，本轮已直接修改）

编号 文件 章节 修订内容
R-95 docs/公寓端/11-人员入住作业流程.md 全文 新建入住作业流程专册（v1.0）：五环节、三条状态链、复用表补列、N-38N-47 请求 / 响应字段、跨端 #6 / #7 / #8 / #9 字段、异常与权限、Q-36Q-40、验收 8 项
R-96 docs/设计变更/03（本文） 表 0-2 / 0-3、新增 §13 v1.4 补遗登记、CR-C26CR-C30、F-K、R-95R-103、Q-36Q-40、验收 1820
R-97 docs/公寓端/00-公寓端主要功能设计.md 表 0-1 / 0-2 / 0-3 A-03、§4 需求基线 v1.3、A-03 指针与 §13 权威表述
R-98 docs/公寓端/01、03、04 §0 / 表 C-1 / 表 C-6 功能域指针、apt_local_task 补列、N-38N-47 与错误码 4092640932
R-99 docs/公寓端/05-关键流程.md §0 表 C-1、新增 §10 F-K 流程索引与入住作业流程章节指针
R-100 docs/公寓端/09-平台接口约定.md §0 表 C-6、表 C-2 #9 CHECKIN 扩展、#6 / #7 / #8 字段与匹配结论载体
R-101 三端 README.md + docs/README.md 清单 / 索引 / 一页结论 收录 公寓端/11 与 CR-02 §13，同步 59 张 / 20 接口 / v2-draft
R-102 docs/10-架构优化方案-三端拆分.md 表 0-2、§3 指针 追加 v1.8；明确入住流程不新增编号、不新增表、jcsj 复算不变
R-103 docs/平台端/05、06、docs/应用端/01、04、05、docs/公寓端/07、08 §0 / 表 C-1 / 表 C-2 平台侧匹配结论与 #9 接收口径、值班台审核入口、F-K 流程与 Q-36~Q-40 / 验收追加

表 3-57 决策点与验收追加

项 内容
Q-36~Q-40 见 docs/公寓端/11 表 11-34：交路是否必填 / CHECKIN_PENDING 可否直接入住、UNMATCHED 超时阈值、入住后是否允许房间调整、签到终端离线能否先办后补、apt_local_task 补列 DDL 冻结时点
验收 18 五环节闭环：未注册先注册并重新核验 → 申请单 8 项校验且申请阶段不建 gy_jcxx → 值班员可换房且 7 项变更清单齐全 → #9 CHECKIN 提报与 #7 matchVerdict[] 匹配 → #7 拉到叫乘任务并复算 jcsj 进入派发
验收 19 "已入住"判据：同时满足 checkin_state=CHECKED_IN、finish_ly='0' AND sjlysj IS NULL、gygl_ly_event(CHECKIN) 已写；事务失败整体回滚；gy_jcxx 状态字段无新增、仍只经 apt.duty.state 条件更新；applyId ↔ jcid 一对一
验收 20 边界不破：跨端 20 编号、v2-draft、平台零回调、59 张表、附录 B 图表索引、jcsj 公寓复算、抓拍 / 录音不出公寓均不变；UNMATCHED / LOCKED 不清空本地要素；九类动作全部留痕，签到终端 / 值班台无业务表直写权限

14. 补遗：消费、充值与菜品管理（v1.5）

触发依据：新增 docs/公寓端/12-消费充值与菜品管理.md，要求覆盖「人员消费（食堂选餐 → 消费终端加菜显示金额 → 查补贴 / 现金额度 → 补贴优先扣款、不足现金补足 → 费用上报公寓端 → 流水同步平台并落入人员账户）、人员线下充值（扫公寓线下二维码 → 签到终端输入现金充值金额 → 管理员核对 → 计入本人现金充值额度 → 保存公寓端并同步平台）、公寓菜品管理（公寓管理员发布阶段性菜品食谱 → 消费人员在消费终端查看菜品并加入选择菜单 → 预留未来远程点菜入口）」三项流程，含数据结构、接口定义（请求 / 响应字段）、状态流转与异常场景。 权威关系：docs/公寓端/12 是三项流程端到端的唯一权威表述（CF-01CF-03、表 12-112-34、图 12-1~12-4）；本节只登记口径裁决、流程增量、施工单与决策点。跨端 20 个编号、契约 v2-draft、平台不回调公寓、apt.ledger.local / platform-ledger 各自单写入口、公寓本地库 59 张表、附录 B 图表索引全部不变；本补遗不新增业务表、不新增跨端编号、不新增 bizType、不新增 gy_jcxx 状态字段，采用"复用 gy_ykt_* 五张预留表 + apt_ledger_offline + 平台库 YKT_MEALS 补列 + 规则"实现（补列均为设计定义，DDL 待阶段二契约冻结评审，Q-43）。

表 3-58 补遗范围与权威位置

项 内容 权威位置
三项流程 CF-01 人员消费、CF-02 人员线下充值、CF-03 公寓菜品管理 docs/公寓端/12 §4~§6
状态流转 四条状态链（消费流水态 / 充值申请态 / 同步生命周期 / 食谱发布态）、11 步全流程状态表、双额度扣减决策图 §2 表 12-4 / 12-5、图 12-1 / 12-2
数据模型 复用表清单、gy_ykt_* / apt_ledger_offline / YKT_MEALS 列级结构与补列、枚举字典 §3 表 12-6~12-11
接口清单 端内 N-48~N-58、跨端 #1 / #4 / #10 / #16 扩展与 LEDGER_OFFLINE payload 字段 §8 表 12-29 / 12-30、§7 表 12-26
异常与权限 12 类异常总表、七条权限与审计要求 §9 表 12-31 / 12-32
决策与验收 Q-41~Q-45、8 项验收要点 §10 表 12-33 / 12-34

表 3-59 新增裁决 CR-C31~CR-C35（冲突时以本表为准）

编号 事项 裁定
CR-C31 补贴与现金双额度扣减如何落流水，是否分别记两条 一笔消费只产生一条 flowId / type=CONSUME 流水（CR-02 表 3-15 既有 flowType，不新增）。按"补贴优先、现金补足"拆出 allowanceAmount / cashAmount 随 #10 LEDGER_OFFLINE payload 扩展上报，两者之和等于 abs(amount)；不额外生成 ALLOWANCE_DEDUCT 流水，避免平台 sum(amount) 双计。ALLOWANCE_DEDUCT 保留给独立退补助 / 补助调整场景。两者合计仍不足则全额拒绝、不部分扣款、不透支（PF-5001 / 40933）
CR-C32 "扫公寓线下二维码充值"是否构成线上支付 不构成。充值仅支持线下现金、系统只记账：二维码只携带 gyid + qrCodeId 用于识别公寓并引导到签到终端，不含支付链接；不接微信 / 支付宝 / 网银、不建支付订单、不监听支付回调、不产生支付流水。现金由管理员线下收取并二次确认后，经 apt.ledger.local 只增 gy_ykt_remainder.xjye（不改 knye 补贴额度），再走 #10 同步平台。rechargeChannel 恒为 OFFLINE_CASH
CR-C33 阶段性菜品食谱主数据归属，以及"选择菜单"是否落库 食谱主数据归平台库 YKT_MEALS 补列（recipe_id / recipe_version / meal_period / 生效区间 / publish_state / published_*），由公寓管理员经 platform.catering 发布；公寓 apt.catering 只经 #4 下行 recipes[] 拉增量与水位，食谱缓存落在消费终端本地，不落公寓本地业务表。YKT_MEALS_ORDERING / YKT_MEALS_ORDERS_MX 本期不写入：终端"选择菜单"是设备本地状态，确认前不落库，确认后只按 CF-01 生成一条消费流水。远程点菜仅保留 #1 features.remoteOrdering=false 与 N-58 入口骨架，本期恒返回 40940 FEATURE_DISABLED，不下单、不扣款
CR-C34 knye / xjye 语义与金额口径 knye = 补贴可用额度（allowanceQuota）、xjye = 现金可用额度（cashQuota）为设计映射，须按 docs/11 与 docs/backend/11 存量数据复核（Q-43），不新造同义余额字段；GY_YKT_REMAINDER 仍是唯一余额表，gy_card 全库不存在、卡号沿用 GY_YKT_RY.card_id。金额一律 decimal(12,2) / 字符串两位小数、扣减用负数、充值用正数、禁止浮点；服务端按 recipeId + recipeVersion 重算金额，不信任终端合计
CR-C35 状态表达式与边界不变项 四条状态链互不替代：apt_ledger_offline.ledger_state（补列，流程态 SUBMITTED / DEDUCTED / REPORTED / RECONCILED / REJECTED / REVERSED）、gy_ykt_cash_request.request_state（沿用三值 PENDING / COMPLETED / CANCELLED）、offline_scope + outbox state + reconcile_state（沿用表 3-15 / 3-21 / 3-30）、YKT_MEALS.publish_state（补列四值）。ledger_state 不是余额状态字段，也不是 gy_jcxx 状态字段；状态字段仍只有 apt.duty.state 一个业务终态写入口。幂等 idempotencyKey = hash(gyid + bizType + bizId + bizVersion)、bizId = flowId、业务 UK (gyid, type, flow_id)、归日以平台 serverReceivedAt 为准、count 按 biz_id 去重（R-C3）全部沿用
CR-C31-a 覆盖清单 表 3-1 A-04 / A-14、表 3-3 功能域 6、表 3-12 / 3-15 LEDGER_OFFLINE、表 3-20 offlineQuota、表 3-30 apt_ledger_offline、§7.3 F-D、docs/公寓端/01 表 1-4 #6、docs/公寓端/03 表 C-2 / C-3、docs/公寓端/04 §0 表 C-3、docs/公寓端/09 表 9-1、docs/平台端/01 表 C-1、docs/平台端/03 表 3-7、docs/平台端/04 表 4-9 均按本节理解或已就地补指针；不改动 20 个编号、方向与路径，不新增 bizType

表 3-60 新增流程 F-L / F-M / F-N（完整时序见 docs/公寓端/12 图 12-3 / 12-4、图 12-1）

步 流程 主体 动作 落表 / 编号 失败 / 补偿
1 F-N 菜品管理 公寓管理员 → platform.catering N-57 新建 / 发布阶段性食谱（recipe_id + 单调 recipe_version + 餐次 + 生效区间），DRAFT → PUBLISHED YKT_MEALS 补列、#4 recipes[] 区间重叠拒绝发布；改价 / 下架生成新版本，不改已发布版；到期 EXPIRED、撤回 REVOKED
2 F-N 下发 apt.catering → 消费终端 公寓 GET #4 拉增量与水位，终端 N-48 按 version 主动拉食谱、本地缓存并展示 终端本地缓存（不落库） 缓存落后按 version 刷新；食谱失效 40936 / PF-6001
3 F-L 消费受理 消费终端 → apt.ledger.local 点击加入选择菜单、实时显示金额；N-49 查询两条额度，N-50 提交 items[] + amount apt_ledger_offline(SUBMITTED) 校验失败 REJECTED 不扣款；重复 deviceEventId 返回原 flowId
4 F-L 双额度扣减 apt.ledger.local 补贴优先 → 现金补足 → CAS 条件更新两条额度 + 记一条 CONSUME 流水（负数），balance_before/after 留痕 gy_ykt_remainder、gy_ykt_consume、apt_ledger_offline(DEDUCTED) 合计不足全额拒绝；CAS 冲突重读重试一次，再失败 40935 转人工
5 F-L 提报与对账 apt-report → platform-ingest → platform-ledger #10 LEDGER_OFFLINE 入 outbox 并上报；平台按 serverReceivedAt 归日、唯一写入口更新 GY_YKT_REMAINDER / PL_LEDGER_FLOW；#16 日对账通过置 RECONCILED apt_report_outbox / history、PL_RECEIVE_LOG、PL_LEDGER_FLOW、GY_YKT_REMAINDER 断网 LOCAL_ONLY + outbox PENDING，恢复复用原幂等键续报；差异 DIFF + PF-5003 阻断调账，只走 POST /adjustments 冲正
6 F-M 充值申请 签到终端 → apt.ledger.local 扫公寓线下二维码 → N-52 输入金额提交申请（申请表不存金额，金额落 apt_ledger_offline.amount） gy_ykt_cash_request(PENDING) 金额非法 40938；二维码跨 gyid 40301 / 40939；不建支付订单
7 F-M 管理员核对 值班台 → apt.ledger.local N-53 待核对列表 → N-54 二次确认（或 N-55 作废）→ COMPLETED、只增 xjye、写 gy_ykt_xjczjl(channel=OFFLINE_CASH) gy_ykt_remainder、gy_ykt_xjczjl、apt_ledger_offline、duty_manual_action 实收不符走 N-55 CANCELLED；并发冲突 40939 不重复入账；终态不可回写
8 F-M 同步 apt-report → platform-ledger 与步 5 共用 #10 LEDGER_OFFLINE（RECHARGE 正数）与 F-D 六步 同步 5 同步 5

三条流程共用 F-D 账务闭环（离线受理 → 本地余额立即可用 → 先派 outbox → #10 逐条上报 → 平台归日 → 日对账置 RECONCILED）与 #1 offlineQuota 约束；平台零回调、platform.ledger 是余额主账唯一写者，消费终端 / 签到终端 / 值班台对余额表零写权限。

表 3-61 施工单追加（R-104~R-113，本轮已直接修改）

编号 文件 章节 修订内容
R-104 docs/公寓端/12-消费充值与菜品管理.md 全文 新建三项流程专册（v1.0）：三条流程、四条状态链、复用表补列、N-48N-58 请求 / 响应字段、#10 LEDGER_OFFLINE payload 扩展、异常与权限、Q-41Q-45、验收 8 项
R-105 docs/设计变更/03（本文） 表 0-2 / 0-3、新增 §14 v1.5 补遗登记、CR-C31CR-C35、F-L / F-M / F-N、R-104R-113、Q-41Q-45、验收 2123
R-106 docs/公寓端/00-公寓端主要功能设计.md 表 0-2 / 0-3 A-04、§4 需求基线 v1.4、A-04 三端归属与 §14 权威表述
R-107 docs/公寓端/01、02、03 §0 / 表 C-1 / 表 C-3 功能域 6 补遗、子域归属与技术基线不变、gy_ykt_* / apt_ledger_offline / YKT_MEALS 补列与 owner 口径
R-108 docs/公寓端/04-接口设计.md §0 表 C-3 / 表 C-8 N-48N-58 端内接口与错误码 4093340940
R-109 docs/公寓端/05-关键流程.md §0 表 C-1、新增 §11 F-L / F-M / F-N 流程索引与三项流程章节指针
R-110 docs/公寓端/09-平台接口约定.md §0 表 C-8、表 C-2 #1 features.remoteOrdering、#4 recipes[]、#10 LEDGER_OFFLINE 扩展字段、#16 对账结论
R-111 docs/公寓端/06、07、08、README.md 配置项 / 验收入口 / Q 清单 / 索引 金额与离线额度配置项、验收 2123 入口、Q-41Q-45、收录 公寓端/12 与 v1.9
R-112 docs/平台端/01、03、04、05、06、07、09、README.md §0 / 表 C-1 / C-2 / 表 4-9 / §4.1 / 表 9-1 YKT_MEALS 补列与 publish_state、platform.catering recipes 资源、#10 payload 扩展与平台归集链路、余额主账单写入口声明；对象存储仍只有两个桶（image_ref 只作引用占位）、P-07 与 Q-44 远程点菜关联
R-113 docs/应用端/01、03、04、05、07、README.md、docs/10-架构优化方案-三端拆分.md、docs/README.md §0 / 表 C-1 / C-2 / 表 0-2 / §3 指针 管理员充值核对与食谱发布职责、只读边界、N-53~N-55 入口、F-M 流程与验收入口；追加 v1.9 修订记录与 CR-02 §14 索引

表 3-62 决策点与验收追加

项 内容
Q-41~Q-45 见 docs/公寓端/12 表 12-33：补贴不足是否允许现金补足（默认允许）、线下充值断网是否受 offlineQuota 约束（默认是，沿用 Q-21）、食谱主数据归属与 knye / xjye 语义复核（默认平台库 YKT_MEALS 补列 + 公寓只读下发，须按存量数据复核）、远程点菜启用条件（本期 features.remoteOrdering=false）、充值单笔上限 / 是否双人复核 / 内部人员透支（默认 > 0 且 < 100、二次确认即可、不透支）
验收 21 三项流程闭环：终端按 PUBLISHED 食谱选菜并显示金额 → N-49 返回两条额度 → 严格"补贴优先、现金补足"且一笔消费只一条 flowId → #10 落 PL_LEDGER_FLOW 并更新人员账户；扫码只识别公寓、无支付订单与回调、申请表不存金额、管理员二次确认后只增 xjye；阶段性食谱按 recipe_id + version + period + 区间 发布、选单确认前不落库、N-58 恒 40940
验收 22 状态一致性：四条状态链（表 12-4）互不替代；ledger_state / request_state / offline_scope / publish_state 与 docs/公寓端/12 §4~§6 状态机、§9 异常表逐项对应；终态不回写；amount 一律字符串两位小数、扣减负数、服务端按 recipeVersion 重算；CAS 前后值留痕
验收 23 边界不破：跨端 20 编号、v2-draft、平台零回调、59 张表、附录 B 图表索引、不新增 bizType、apt.ledger.local / platform-ledger 单写入口、抓拍 / 录音不出公寓均不变；十类动作全部留痕，新增权限点前后端同码并登记 sys_menu.perms，设备与前端零余额表写权限

15. 补遗：三端一致性同步与平台统计分析（v1.6）

触发依据：把公寓端已完成的四项调整（平板叫乘（§11 F-A / F-B、docs/公寓端/05 §9）、人脸签到与注册（§12 F-F / F-J、docs/公寓端/10）、消费（§14 F-L、docs/公寓端/12 §4）、菜品管理（§14 F-N、docs/公寓端/12 §6））在应用端与平台端同步落地，统一业务规则、交互流程、权限控制与异常处理，并明确三端数据同步机制与状态映射关系；同时强化平台端「以公寓为单位的分类统计、月 / 季 / 年报表与公寓排名」能力。 权威关系：docs/平台端/10 是统计 / 报表 / 排名能力的唯一权威表述（PS-01PS-05、表 10-110-22、图 10-110-3）；表 3-66 是三端状态映射与数据同步机制的唯一权威表述，各端分册的本端视角映射表均指向本节，不得另立第二真源。本节只登记变更点、影响范围、口径裁决、流程增量、施工单与决策点。 性质与边界：设计稿（Design Only），DDL 待阶段二契约冻结评审（Q-48）。跨端仍为 **20 个编号（117 + 23~25）、契约 v2-draft、平台零回调、公寓本地库 59 张表、附录 B 图表索引不变；不新增跨端编号、不新增 bizType、不新增公寓本地业务表、不新增业务状态字段。统计能力全部落在平台管理端 /platform/v1/admin/stat/**，新增 2 张 pl_apt_stat_* 属平台库**（按 §0 表 C-1 / C-2「平台库新增表另计」执行，不纳入 59 张校验）；统计结果不回写公寓端 / 应用端任何业务状态。

表 3-63 变更点与影响范围（本轮修订的交付清单，冲突时以本表为准）

# 变更点 类型 影响文件 影响端 冻结契约影响 施工单
1 新建「公寓统计分析与排名报表」专册：五类指标、月 / 季 / 年周期、分类与综合排名、报表生成导出 新增能力 docs/平台端/10（新建） 平台端（主责）、应用端（只读消费）、公寓端（不改上报义务） 无：不新增跨端编号 / bizType / 公寓业务表；平台库新增 2 张另计 R-114
2 三端状态映射与数据同步机制收口为唯一权威表 新增 / 收口 本文表 3-66；应用端/03、平台端/05 本端视角表；公寓端/09 指针 三端 无：全部沿用既有编号与枚举 R-115、R-117、R-123
3 应用端补齐平板叫乘的业务规则、交互流程、权限与异常（F-A / F-B 展开） 同步落地 应用端/01、02、03、04、05、06、07、08、09、README 应用端 无：只提交命令、不直写业务表 R-116~R-120
4 应用端补齐人脸签到 / 注册审核、消费、菜品管理的规则、权限、异常与错误码登记 同步落地 同上（04 补 4091740924 / 50303 / 4092640940 登记） 应用端 无：错误码沿用公寓端已定义值，本端只消费不自造 R-118、R-119
5 平台端补齐四项能力的业务规则、流程正式行、权限与异常（F-L / F-M / F-N 升入表 C-1） 同步落地 平台端/01、02、03、04、05、06、07、08、09、README 平台端 无：platform-ledger / platform-report 单写入口不变 R-121~R-124
6 平台端 worker 任务清单挂接四能力上报与统计生成 同步落地 平台端/02 §2、平台端/08 §1 / §4 平台端 无：单活 + 库级协调锁不变，不引入消息中间件 R-121
7 PL_REPORT_DAILY / PL_LEDGER_FLOW 补列与 2 张 pl_apt_stat_* 新表 数据结构（设计定义） 平台端/03、平台端/10 表 10-7 / 10-8 / 10-10 平台端 平台库新增表另计；DDL 待阶段二冻结（Q-48） R-122
8 新增管理端接口 S-01S-07 与错误码 PF-7003PF-7005 接口（管理端） 平台端/04 §9、平台端/10 表 10-14 平台端 不计入跨端 20 编号；管理接口不产生跨端副作用 R-123
9 评价情况 / 房间周转数据接入：#13 ARCHIVE 摘要 payload 扩展 口径裁决 公寓端/09、平台端/05、平台端/10 表 10-9 公寓端（分组计数）、平台端（只接计数） 不新增 bizType、不接明细、不新增上报接口 R-125
10 顶层架构与三端 README / 总索引版本同步 索引同步 docs/10 v2.0、三端 README.md、docs/README.md、公寓端/00、05 三端 无 R-125

影响范围总述：功能描述影响三端全部 01 分册（公寓端/01、应用端/01、平台端/01）；数据流程影响 公寓端/03/05/09、应用端/03/05、平台端/03/05/06/10；接口定义影响 公寓端/04/09、应用端/04、平台端/04/05；权限控制影响 公寓端/02/06、应用端/02/04、平台端/01/04/10；异常处理影响 公寓端/07/08、应用端/04/05/07、平台端/06/09/10；实施与验收影响 公寓端/07/08、应用端/07/08、平台端/08/09、docs/10 与三端 README.md / docs/README.md。不改变公寓端四项能力的既有权威表述（公寓端/05 §9、公寓端/10、公寓端/11、公寓端/12），只在四册头部补 §15 关联指针并补齐另两端。

表 3-64 新增裁决 CR-C36~CR-C42（冲突时以本表为准）

编号 事项 裁定
CR-C36 统计周期、封账与日切口径 月 YYYY-MM / 季 YYYY-Qn / 年 YYYY 一律由 PL_REPORT_DAILY rollup，不直接扫明细表、不重算公寓明细（表 4-10 边界、F6 要点 1、PR-10）。日切以平台 serverReceivedAt 为准，occurredAt 不参与。封账前置为「期内日报 DONE + 账务日对账无 DIFF」，否则 PF-7003、账务类指标 BLOCKED 且不参与排名。PL_REPORT_DAILY 一旦生成不可改，修正走次日重算 + revision_no+1，旧行标 REVISED（F6 要点 6）
CR-C37 现金充值是否"计为收入"及与余额的关系 计为期间收入：CASH_RECHARGE_INCOME = sum(amount) where type=RECHARGE（正数），不与消费净额抵销、不冲减补贴发放、不记入余额负债；与 GY_YKT_REMAINDER 余额快照是两个口径，禁止互相校验。rechargeChannel=OFFLINE_CASH（CR-C32）仅线下现金、不接线上支付
CR-C38 补贴消费额如何取数，是否与 sum(amount) 冲突 取 PL_LEDGER_FLOW.allowance_amount（补列，承接 §14 #10 allowanceAmount），不取 sum(amount)；一笔消费只一条 flow_id（CR-C31），补贴部分与现金部分分列，避免 sum(amount) 双计。补贴使用率 = ALLOWANCE_CONSUME_AMOUNT / ALLOWANCE_ISSUE_AMOUNT，分母 0 记 NO_DATA
CR-C39 "评价情况 / 房间利用周转"的数据来源，是否新增表或 bizType 不新增表、不新增 bizType、不新增上报接口：由公寓端在既有 #13 ARCHIVE 日归档摘要中按 payload 扩展分组计数 satisfaction{}（好 / 中 / 差 / 参评）与 roomOccupancy{}（可用房间夜 / 占用房间夜），平台只接计数不接明细、按批覆盖（表 3-13 摘要语义）。PL_REPORT_DAILY 补列承载。未上报则 data_status=NO_DATA 并在报表注明"数据未接入"，不推断、不补零、不以 pl_staff_performance_daily 代填（Q-46）；该表只作交叉校验，不替代评价计数
CR-C40 公寓排名的名次规则、范围与快照 以 gyid 为单位，对五类 + COMPOSITE 分别排名；RANK() 跳号、同分同名次、tie_count 记并列；gyIds[] 由会话数据范围解析且必须在 SQL 层带范围（F6 要点 4、平台端/03 §5），空 / 越权 PF-7004；排名按 revision_no 存快照，查询不实时重算；NO_DATA 公寓不参与该指标排名并标注；报警 / 投诉类为逆向指标（越小越优，Q-49）
CR-C41 三端状态映射的唯一真源，以及统计能否回写业务状态 表 3-66 为唯一权威，各端分册只给本端视角投影并指向本节；禁止另立第二套映射或改写既有枚举（ryzt / finish_jc / reg_state / match_state / ledger_state / publish_state 等）。统计与排名结果不回写 gy_jcxx、apt_local_task、apt_person_face_reg、GY_YKT_REMAINDER、YKT_MEALS 等任何业务表；apt.duty.state 仍是业务终态唯一写入口，platform-ledger 仍是余额主账唯一写者，platform-report 是 pl_apt_stat_* 唯一写者
CR-C42 边界不变项与新增表归属 跨端 20 个编号（117 + 2325）、契约 v2-draft、平台零回调、公寓本地库 59 张表、附录 B 图表索引、gyid 四级隔离、金额 decimal(12,2) / 比率 decimal(6,4) / 禁止浮点全部不变；统计接口 /platform/v1/admin/stat/** 属平台管理端，不计入跨端编号、不产生跨端副作用（表 4-10 §12 纪律①）；新增 pl_apt_stat_period / pl_apt_stat_rank 2 张属平台库，按 §0 表 C-1 / C-2「平台库新增表另计」执行，平台库累计新增 3 + 2 = 5 张；导出复用 report-export 桶，不新增桶（平台端/07 §4.1）
CR-C36-a 覆盖清单 表 3-1 A-01 / A-04 / A-13 / A-14、表 3-7 #9 / #10 / #11 / #12 / #13 / #24、表 3-12 bizType、表 3-21 枚举、docs/平台端/01 表 1-4 / 1-5、平台端/03 表 3-8 / 3-10 / 3-16、平台端/04 表 4-10、平台端/06 §7 / §8、平台端/09 PR-10 / P-07 均按本节理解或已就地补指针；不改动 20 个编号、方向与路径

表 3-65 四能力的三端业务规则 / 交互流程 / 权限控制 / 异常处理对照（权威表述仍以各专册为准）

能力 公寓端（执行与事实） 应用端（人看与人工干预） 平台端（真源与归集） 共同权限控制 共同异常处理
平板叫乘 到 jcsj 生成 apt_tablet_task(WAITING) + 单调 dispatch_seq；平板 N-03 主动拉取、serverTime 校准、本地定时播放 → 刷脸签到 → N-04 TABLET_RESULT（resultId 幂等）→ apt.device.gateway 提交状态机命令 → apt.duty.state 条件更新 gy_jcxx → #9 / #8 / #13 上行 → /ws/duty tablet.result。平板链路不发 #24（#24 仅 SIP）。权威见 公寓端/05 §9 只读 tablet.result / state.changed；UNVERIFIED 标"未刷脸"并按 Q-22 触发复叫提示；值班员只发命令（duty:call:*），不直写 gy_jcxx / apt_tablet_*；断网结果本地缓存、恢复按 resultId 续传 platform-ingest 按 idempotencyKey 去重收 #9 TABLET_RESULT → PL_TASK_ACK / PL_RECEIVE_LOG；#8 回执作匹配输入；#13 归档；报表只从 PL_REPORT_DAILY 出数，不重算明细；PL_TASK.jcsj 只是基线、权威 jcsj 恒由公寓复算（CR-C06） 设备凭据 + HMAC + ±5 min + nonce（/open/v1/**）；duty:call:*（/duty/**）；platform:report:list（平台只读）；gyid 只从凭据 / 会话解析 重复 ACK 40916；UNVERIFIED / SKIPPED → 保持待确认 + 复叫；NO_ANSWER / FAILED → ryzt=2 + 复叫；迟到 / 重复 → applied_state=IGNORED；PL-VERSION-STALE / PL-IDEMPOTENT-REPLAY；抓拍帧 / 人脸原图 / 比对帧不出终端
人脸签到与注册 N-34 REG_APPLY（APPLIED）→ N-36 值班员 CONFIRM（生效点）→ apt_master_person 入档 → 并行双路 4a #9 PERSON_REG 上传平台 / 4b FACE_ISSUE 下发设备；设备 N-30 拉增量；刷脸核验产出 faceVerifyState。权威见 公寓端/10 §4 N-35 待审列表、N-36 确认、N-37 驳回（duty:person:reg + 二次确认）；人脸相关表一律只读，只写 duty_*；值班台无 apt_master_person 写权限 pl_person_reg_request 回同步回执 ACCEPTED / REJECTED（regVerdict），不做注册准入审批、不决定公寓侧生效；媒体本体落 person-photo 桶、平台库只存引用与校验和；人员主数据人脸按 CR-C24 允许跨端，业务抓拍 / 签到现场图 / 录音不出公寓 apt:face:*（公寓管理端）；duty:person:reg（值班台）；设备按 gy_sb.face_scope_* 隔离；平台对象存储短期签名 ≤ 10 min 40914 未确认禁止匹配 / 下发；40917~40924、50303 媒体与注册态；40927 缓存过期、40930 核验不符；平台 REJECTED(DUPLICATE_WORK_NO) 不回滚本地注册与已下发设备（Q-35），只告警 + 待办
消费 N-48 拉食谱 → N-49 查双额度 → N-50 提交 → "补贴优先、现金补足"双额度 CAS 扣减且一条 CONSUME 流水 → #10 LEDGER_OFFLINE（allowanceAmount / cashAmount 拆分）→ 平台归日落人员账户 → #16 日对账置 RECONCILED。权威见 公寓端/12 §4 / §7 值班台只读账户额度（N-56）与流水（N-51），无消费提交权限；消费受理在设备侧；gy_ykt_* / apt_ledger_offline 一律只读；充值核对另见 §14 F-M platform-ingest 去重 → platform-ledger 唯一写入口更新 GY_YKT_REMAINDER / PL_LEDGER_FLOW；按 serverReceivedAt 归日、UK (gyid,type,flow_id) 去重；统计只读 PL_LEDGER_FLOW 取三类金额（CR-C37 / C38） apt:ledger:list；duty:ledger:*（仅核对 / 查询）；platform:ledger:* / platform:stat:*（平台只读统计）；设备与前端零余额表写权限 合计不足全额拒绝 40933 / PF-5001、不部分扣款；CAS 冲突 40935 重试一次后转人工；断网超 offlineQuota 40913；重复 deviceEventId 返回原 flowId；PF-5002 业务重复 vs PL-IDEMPOTENT-REPLAY 幂等重放；日 sum(amount) 不等 PF-5003 阻断调账，只走 POST /adjustments 冲正
菜品管理 #4 recipes[] 增量下行 → N-48 终端按 version 拉取并本地缓存 → 点击查看菜品、加入选择菜单（确认前不落库）→ 确认后按 CF-01 生成一条消费流水；N-58 远程点菜仅预留。权威见 公寓端/12 §6 公寓管理员经 N-57 发布 / 撤回（apt:catering:recipe:* + 二次确认）；值班台只读食谱与选单；只提交代理命令，不写 YKT_MEALS / 本地业务表 platform.catering 承载 YKT_MEALS 补列（§14）与 /recipes 资源；publish_state DRAFT→PUBLISHED→EXPIRED/REVOKED；#4 下行由公寓主动拉；image_ref 只作引用占位、不传图片本体、不新增对象存储桶 apt:catering:recipe:*（公寓管理员）；平台餐饮管理端权限；消费终端设备凭据；前后端 v-hasPermi / @PreAuthorize 同码并登记 sys_menu.perms 食谱失效 / 改价 40936 + 终端重拉；菜品下架 PF-6001；区间重叠拒绝发布；改价生成新 recipe_version 不改已发布版；远程点菜误调用 40940 FEATURE_DISABLED（features.remoteOrdering=false）；YKT_MEALS_ORDERING / ORDERS_MX 本期不写入

表 3-66 三端状态映射与数据同步机制（唯一权威表）

能力 / 环节 公寓端状态与字段 同步载体（既有编号） 平台端状态与落表 应用端可见 / 可写 终态与回退
平板叫乘·派发 apt_tablet_task.pull_state WAITING→PULLED→DONE/EXPIRED；dispatch_seq 单调 设备 N-03 主动拉（端内，不计跨端） 不感知（平台不生成任务行） 只读任务视图 EXPIRED 不重派；平板离线回落 SIP（CR-C23）
平板叫乘·结果 faceVerifyState VERIFIED/UNVERIFIED/SKIPPED；callResultType ANSWERED/NO_ANSWER/FAILED/CANCELLED；applied_state PENDING/APPLIED/IGNORED；gy_jcxx.ryzt / finish_jc 经 apt.duty.state 条件更新 #9 TABLET_RESULT（resultId）、#8 TASK_ACK、#13 ARCHIVE；/ws/duty tablet.result（端内 WS） PL_RECEIVE_LOG、PL_TASK_ACK、PL_REPORT_DAILY.call_count；PL_TASK.status PLANNED→DISPATCHED→ACKED→EXECUTING→FINISHED/CANCELLED 只读 tablet.result / state.changed；只提交复叫命令 VERIFIED→ANSWERED→ryzt=3 / finish_jc='1'（终态不回写）；UNVERIFIED/SKIPPED 保持待确认 + 复叫；NO_ANSWER/FAILED→ryzt=2；迟到/重复 IGNORED；存量 ryzt 数字码不跨端
人脸注册·本地生效 reg_state APPLIED→CONFIRMED/REJECTED/ARCHIVED；person_category TRANSIENT/LONG_TERM 端内 N-34 / N-36 / N-37 不感知（注册生效点在公寓） N-35 待审、N-36 确认、N-37 驳回（只提交命令） CONFIRMED 为生效点；REJECTED/ARCHIVED 终态；平台回执不决定本地生效
人脸注册·双路同步 upload_state / dispatch_state 各自 PENDING→SENT/ISSUED→ACKED，失败 FAILED→DEAD；face_sync_state PENDING/SYNCED/FAILED/STALE 4a #9 PERSON_REG（+ person-photo 短期签名直传）；4b 端内 FACE_ISSUE / FACE_ERASE / FACE_FULL_SYNC pl_person_reg_request、regVerdict PENDING→ACCEPTED/REJECTED（同步回执）、platform_version（经 #2 下拉取回） 只读注册态 / 同步态 / 设备缓存台账 两路解耦并行、各自幂等、互不阻塞；REJECTED 只告警 + 待办，不回滚本地注册与已下发设备（Q-35）；擦除超时 50303 升级 FACE_FULL_SYNC
入住匹配（衔接项） match_state PENDING/MATCHED/UNMATCHED/LOCKED/REJECTED；checkin_state SUBMITTED→…→CHECKED_IN；sync_state 五值 #9 CHECKIN、#6 计划、#8 回执（匹配输入）、#7 响应体 matchVerdict[]（结论唯一载体） GY_SYN_JCXX、PL_TASK / PL_TASK_CHANGE(op=UPSERT)、PL_REPORT_DAILY.stay_count 只读审核状态与匹配结论；N-44 / N-45 只提交命令 UNMATCHED / LOCKED 保留上报要素不清空；LOCAL_ONLY 属 offlineScope 不是匹配状态；jcsj 恒由公寓复算
账务·消费流水 ledger_state SUBMITTED→DEDUCTED→REPORTED→RECONCILED/REJECTED/REVERSED；offline_scope LOCAL_ONLY→SYNCED→RECONCILED；reportState PENDING/SENT/FAILED/DEAD/RETRIED #10 LEDGER_OFFLINE（bizId=flowId、idempotencyKey）、#16 日对账（公寓主动调用，P-02） PL_LEDGER_FLOW.reconcile_state RECEIVED→RECONCILED/DIFF；PL_RECONCILE_BATCH.state RUNNING→MATCHED/DIFF_FOUND/CLOSED；GY_YKT_REMAINDER（platform-ledger 唯一写） 只读额度 / 流水 / 对账状态 DIFF + PF-5003 阻断调账；冲正只走 POST /adjustments；断网 outbox PENDING，恢复复用原幂等键；RECONCILED 后不得直接改余额
账务·充值申请 request_state PENDING→COMPLETED/CANCELLED（申请表不存金额）；rechargeChannel=OFFLINE_CASH 端内 N-52 / N-54 / N-55；上行同 #10 RECHARGE PL_LEDGER_FLOW(type=RECHARGE) → 统计 CASH_RECHARGE_INCOME N-53 列表、N-54 确认、N-55 作废（duty:ledger:confirm + 二次确认） 终态不可回写（40939）；金额不符走 CANCELLED 重新申请；无支付订单与回调
食谱 publish_state DRAFT→PUBLISHED→EXPIRED/REVOKED（平台库 YKT_MEALS 补列）；终端选单为本地态、确认前不落库 #4 recipes[] + recipeWatermark（公寓 GET 拉取）；N-48 端内 YKT_MEALS（platform.catering 唯一写）、#4 只维护当前有效版本 只读食谱 / 选单；N-57 只提交代理命令 改价 / 下架生成新 recipe_version，不改已发布版；远程点菜 features.remoteOrdering=false 恒 40940
统计·日报与周期 不感知统计（业务状态一律不变） 无跨端交互（统计不反向下发） PL_REPORT_DAILY（冻结不可改）→ pl_apt_stat_period.state DRAFT→FINAL→REVISED + revision_no；pl_apt_stat_rank 快照；data_status OK/NO_DATA/BLOCKED 只读 FINAL / REVISED 快照与榜单（Q-50） 未封账 PF-7003；DIFF → BLOCKED 不参与排名；缺报 NO_DATA 不推断不补零；修正走次日重算 + 新 revision_no，不原地改 FINAL

同步机制总口径（沿用 §3 / §4，不新造）：下行一律"公寓主动 GET 拉"（#1~#7 / #23），上行一律"公寓 POST 推"（#8~#14 / #24），平台零回调；idempotencyKey = hash(gyId + bizType + bizId + bizVersion)，UK (gyid, idempotency_key)；三时间戳 occurredAt（业务时间轴）/ receivedAt / serverReceivedAt（归日与账务日切以此为准）；outbox 是队列、apt_report_history 是终态流水，两者不互换（CR-C10）；续报复用原幂等键（F-E）；对账三维 count（按 biz_id 去重，R-C3）/ sum(amount) / max(watermark)；摘要类 #11~#13 / #24 按批覆盖、无版本语义（表 3-13）。统计链路不产生任何新的跨端调用。

表 3-67 新增流程 F-O / F-P / F-Q

步 流程 主体 动作 落表 / 编号 失败 / 补偿
1 F-O 三端状态对齐 三端领域服务 四能力事件只提交命令：平板结果 → apt.duty.state；注册确认 → apt.face.registry + apt-master-client 事务；消费 → apt.ledger.local；食谱 → platform.catering。应用端 / 平台端只读 + 归集，不回写公寓业务状态 表 3-66 全量映射 越权 40301 / PF-7004；映射冲突以表 3-66 为准，不另立第二真源（CR-C41）
2 F-O 上行归集 apt-report → platform-ingest #9 / #10 / #12 / #13 按既有 bizType 上行；#13 摘要补 satisfaction{} / roomOccupancy{} 分组计数（CR-C39） PL_RECEIVE_LOG、PL_REPORT_DAILY 断网 outbox 续报；PL-IDEMPOTENT-REPLAY 视为成功；缺报标 NO_DATA
3 F-P 日报与封账 platform-worker（单活）→ platform-report 每日日切生成 PL_REPORT_DAILY；platform-ledger 跑日对账三维比对 PL_JOB_*、PL_RECONCILE_BATCH DIFF + PF-5003 阻断调账；日报冻结不可改；超时 > 10 min 拆批
4 F-P 周期汇总 platform-report 月 / 季 / 年由日报 + PL_LEDGER_FLOW + PL_RECEIVE_LOG rollup 五类指标 → DRAFT → FINAL pl_apt_stat_period 未封账 PF-7003；缺报 NO_DATA；账务 DIFF → BLOCKED
5 F-P 修订 platform-report 次日重算 / 人工修订生成 revision_no+1，旧行标 REVISED 两张 pl_apt_stat_* 版本冲突 PF-7005；不原地改 FINAL、不删历史
6 F-Q 排名与输出 platform-report → 管理端 / 应用端 RANK() 生成五类 + 综合排名快照 → S-01 / S-02 查询 → S-06 异步导出 XLSX / PDF pl_apt_stat_rank、report-export 桶 PF-7001 不输出半成品、PF-7002 导出失败；gyIds[] 越权 PF-7004

表 3-68 施工单追加（R-114~R-125，本轮已直接修改）

编号 文件 章节 修订内容
R-114 docs/平台端/10-公寓统计分析与排名报表.md 全文 新建统计专册（v1.0）：五类指标、月/季/年周期、分类与综合排名、S-01S-07 接口、2 张新表与补列、权限与异常、三端数据源映射、Q-46Q-50、验收 8 项
R-115 docs/设计变更/03（本文） 表 0-2 / 0-3、新增 §15 v1.6 补遗登记；表 3-63 变更点与影响范围、CR-C36CR-C42、表 3-66 三端状态映射唯一权威表、F-O / F-P / F-Q、R-114R-125、Q-46Q-50、验收 2426
R-116 docs/应用端/01、02、06、09、README.md §0 / 权限点 / 部署 / 契约 / 索引 四项能力的业务规则与边界、平板结果与异常展示落点、零命中文件补边界指针、§11 补遗
R-117 docs/应用端/03-数据设计.md §0 表 C-3 本端视角三端状态映射表（字段 → 对端状态 → 可写性），指向 CR-02 §15 表 3-66
R-118 docs/应用端/04-接口设计.md §0 表 C-3 / C-4 四能力接口字段与 faceVerifyState 全枚举；登记 4091740924 / 50303 / 4092640940（只消费不自造）；权限点矩阵
R-119 docs/应用端/05-关键流程.md §0 表 C-1、新增 §10 F-A / F-J / F-L 流程行与 F-B 展开；§10 三端一致性作业视图（交互时序、权限、异常、状态映射指针）
R-120 docs/应用端/07、08 表 7-6 / §0 验收 1523 编入本端验收表；承接 Q-26Q-45 与新增 Q-46~Q-50
R-121 docs/平台端/01、02、08、README.md §0 / §2 / §1 / §4 / 索引 四能力职责与统计能力归属；worker 定时任务清单（四能力上行 + 统计生成）；单活与拆批约束；§11 补遗
R-122 docs/平台端/03-数据设计.md §0 补遗段 / 表 C-3 2 张 pl_apt_stat_* 新表、PL_REPORT_DAILY / PL_LEDGER_FLOW 补列，平台库新增表 3 → 5 张口径
R-123 docs/平台端/04、05 §9 表 4-13 / §0 表 C-3 S-01S-07 与 PF-7003PF-7005；平台端视角三端状态映射与 #13 摘要扩展字段
R-124 docs/平台端/06、07、09 §0 表 C-1 / §4.1 / 编号纪律段 F-A / F-B / F-J / F-L / F-M / F-N / F-O~F-Q 升为流程正式行 + 异常分支；对象存储不新增桶；PR-10 / P-07 承接统计口径风险
R-125 docs/公寓端/00~12、README.md、docs/10-架构优化方案-三端拆分.md、三端 README.md、docs/README.md 索引 / 指针 / 表 0-2 / §3 指针 / 文档清单 收录 平台端/10 与 CR-02 §15；四能力权威专册 10 / 11 / 12 补 §15 关联指针；01 / 02 / 03 / 06 补齐边界 / 模块 / 数据 / 部署口径；#13 摘要扩展字段（公寓端/09 表 C-9、平台端/05 表 C-3）；上位版本 v2.0；三端一致性指针、Q-46Q-50 与验收 2426 入口、流程范围 F-A~F-Q

表 3-69 决策点与验收追加

项 内容
Q-46~Q-50 见 docs/平台端/10 表 10-21：评价 / 房间周转数据接入方式（默认 #13 摘要 payload 扩展）、周期时区与季度划分、补列与 2 张新表 DDL 冻结时点、综合排名权重与逆向指标、统计报表向应用端开放的粒度（默认只读到公寓级）
验收 24 三端一致性：四能力在应用端 / 平台端均有业务规则、交互流程、权限控制与异常处理表述；表 3-65 / 3-66 与两端本端视角映射表逐项对应；无第二套状态枚举；统计结果不回写任何业务状态；apt.duty.state / platform-ledger / platform-report 三个单写入口不变
验收 25 统计能力：五类指标公式与数据源齐备（现金充值计收入、补贴消费取 allowance_amount）；月 / 季 / 年报表可生成且只由日报 rollup；按 gyid 分类排名 + 综合排名、RANK() 跳号、NO_DATA 不参与；封账 PF-7003 与 DIFF 阻断生效；修正走 revision_no+1
验收 26 边界不破：跨端 20 编号、v2-draft、平台零回调、公寓 59 张表、附录 B 图表索引、不新增 bizType、抓拍 / 录音不出公寓、gyid SQL 层隔离均不变；平台库新增 2 张另计（累计 5 张）；管理接口 /platform/v1/admin/stat/** 不产生跨端副作用；DDL 待阶段二契约冻结
Reference in new issue View Git Blame Copy Permalink