jcgl-dev/docs/公寓端/13-公寓端小步迭代开发计划.md

13 公寓端小步迭代开发计划（入住·叫乘优先，消费充值延后）

文档编号：docs/公寓端/13。性质：实施排期设计稿，不是设计变更、不改写任何既有权威表述；本文件回答"按什么顺序写代码、每步怎么验、消费充值何时接"，不回答"业务规则是什么"。 权威关系：业务规则 / 状态 / 接口 / 验收口径一律以 docs/设计变更/03（CR-02 §11~§15）、docs/公寓端/05 §9~§11、docs/公寓端/10、11、12、docs/公寓端/09 为准；阶段与批次以 docs/10 §9 表 9-19-6、docs/公寓端/07 表 7-17-8 为准。本文件只做排序、切分、对齐、衔接，冲突时以上述文件为准。 上位依据：dev/RuoYi-Vue-master/（后端）、dev/RuoYi-Vue2-master/（前端）实测代码基础；docs/10 §9 / §11.2 表 11-1 / §10.2 表 10-2；docs/公寓端/02、03、04、06、07、08、09；docs/设计变更/01（CR-01）、03（CR-02）；docs/应用端/07、docs/平台端/08、09。 硬约束：不新增 M7 / 阶段六 / D-4 等既有编号体系；跨端仍 20 个接口编号、契约 v2-draft、平台零回调；公寓本地库业务表 59 张口径不变；apt.duty.state 仍是业务终态唯一写入口；冻结前不写 Controller（公寓端/08 R-02）；DDL 待阶段二契约冻结评审通过后执行（Q-40 / Q-43 / Q-48）；本轮不执行 git commit / git push。

表 13-1 文档信息

项	内容
范围	公寓端 IT-0IT-8 九个小步迭代 + 延后 IT-9IT-11（消费 / 充值 / 菜品）；含迭代划分、里程碑、交付物、对齐矩阵、风险台账、跨迭代联调与测试、衔接规划
优先级	P1 入住 + 叫乘核心闭环优先（IT-3IT-5）；P2 消费 / 充值 / 菜品整体延后（IT-9IT-11）
编号规则	迭代 IT-y、里程碑 MS-y、风险 IR-y、交付物 DV-y（均为本文件内编号，不占用 M0M6 / D-1D-3 / Q-* / P-* / PR-* / R-*）
术语	「核心闭环」= 人脸注册与核验 → 入住申请 / 审核 / 办理 → #9 提报与平台匹配 → 叫乘任务 → 状态机执行 → outbox 上报；「延后域」= 消费 CF-01、线下充值 CF-02、菜品管理 CF-03

表 13-2 修订记录

版本	日期	修订内容
v1.0	2026-11-10	首次形成：基于 dev/ 实测上游代码与既有阶段 / 批次口径，切分 9 个小步迭代；登记 6 项 P0 排期前提与技术基线偏离；给出里程碑、交付物、风险台账、跨迭代联调测试与消费充值衔接规划

---

1. 现状基线与排期前提

1.1 dev/ 代码基础实测

表 13-3 dev/ 现状（本计划的物理起点）

项	实测结果	相对路径 / 证据
后端	RuoYi 多模块 Maven，3.9.2，JDK 17，Spring Boot 4.1.0，MyBatis 4.1.0，druid 1.2.28，springdoc 3.1.0；6 模块 ruoyi-admin（唯一启动 jar，端口 8080）/ framework / system / common / quartz / generator	dev/RuoYi-Vue-master/pom.xml、ruoyi-admin/src/main/resources/application.yml
前端	Vue 2.6.12 + element-ui 2.15.14 + vue-router 3.4.9 + vuex 3.6.0 + vue-cli 4.4.6（无 vite）；单入口 src/main.js + src/permission.js 全量 sys_menu 动态路由；devServer 80，代理 8080	dev/RuoYi-Vue2-master/package.json、vue.config.js、src/router/index.js
DDL	仅 31 张：sql/ry_20260417.sql 20 张 sys_/gen_、sql/quartz.sql 11 张 QRTZ_，库名 ry-vue	dev/RuoYi-Vue-master/sql/、application-druid.yml
业务代码	全部为净新增：gy_jcxx / gy_rooms / gy_ykt_* / apt_* / duty_* 表 0 张；入住 / 叫乘 / 交路 / 房间 / 消费充值 / 菜品 Controller·Service·Mapper 全无；apt-* 模块目录 0 命中	265 个 package 全为 com.ruoyi.*；25 个 Controller 全为 Sys*/Gen*/监控类
外部能力	Asterisk / AMI、SIP、人脸、WebSocket、/open/v1/**、设备签名 / mTLS 全部 0 命中；pom 无对应依赖	dev/RuoYi-Vue-master/*/pom.xml、SecurityConfig.java
可直接复用	RBAC（sys_menu + @PreAuthorize("@ss.hasPermi") + v-hasPermi 47 处）、@Log + LogAspect 审计、代码生成 ruoyi-generator、Quartz 基座（ScheduleConfig 整类被注释 = 默认 RAMJobStore，qrtz 表已建未用）、文件上传、springdoc（packages-to-scan 仅 ...controller.tool）	ruoyi-framework、ruoyi-common、ruoyi-quartz、ruoyi-generator

结论：docs/公寓端/07 表 7-2 的 M0~M6 不是"改造已有骨架"，而是从零新增业务模块；设计文档引用的 apartment/README.md、apartment/db/mysql 44 张表骨架在工作区不存在。因此 IT-0 必须承担"基线决策 + 建库 + 脚手架 + CI/测试"的前置工作，否则 IT-1 无法开工。

1.2 设计与代码的差距（P0 排期前提）

表 13-4 六项 P0 前提与推荐处置（均须评审签字，本计划不擅自改设计）

#	差距	设计锁定值	dev 实测	推荐处置	阻塞迭代
IR-01	技术基线冲突	JDK 1.8 / Boot 2.5.15 / RuoYi 3.8.9 / springfox 3.0.0 / 后端 8086 / 前端 8082	JDK 17 / Boot 4.1.0 / 3.9.2 / springdoc 3.1.0 / 8080 / 80	推荐方案 B：修订 docs/公寓端/02 §1 基线锁定值以匹配上游，走设计变更评审登记；理由：上游未改动、"框架不魔改"，降级 pom 回退官方版本风险更高。方案 A（降级 dev）列为备选。Swagger 注解由 @Api 改 @Tag/@Operation	IT-0
IR-02	表数口径冲突	44 存量 / 74 apt_apartment / CR 后 59 张	31 张纯 sys_/gen_/QRTZ_	以 59 张为设计口径，产出分域增量 DDL（DDL 与回填分离、回填可重放，CR-02 表 3-33）；07 表 7-5 第 5 条"44 张已实测通过"在当前 dev 不成立，改为 IT-0 的验收项；改 application-druid.yml 库名与凭据	IT-0、IT-1
IR-03	前端入口冲突	src/entries/{apt,duty} 双入口 + src/shared/** + apt 固定路由	单 main.js + 全量动态路由	IT-0 只建 apt 单入口脚手架，duty 入口随 应用端 D-1~D-3 再开；sys_menu 只作权限点载体、apt 业务路由走 constantRoutes 固定注册	IT-0、IT-6
IR-04	无 CI / 测试工程	07 §6 表 7-6 的 8 类用例 + 3 类专项	无 workflows、无 src/test、无 spring-boot-starter-test / surefire	IT-0 补 spring-boot-starter-test、JUnit5 + MockMvc、CI 工作流（编译 / 单测 / 明文凭据正则扫描 / 架构测试）；每迭代把表 7-6 用例沉淀为回归基线	IT-0
IR-05	明文凭据	07 表 7-5 第 8 条「仓库无明文口令」	application-druid.yml root/password、druid 控制台 ruoyi/123456；application.yml token.secret	IT-0 全部外置到环境变量 / 配置中心，CI 加正则扫描卡口；阶段零"已完成"结论在 dev 上重新验收	IT-0
IR-06	契约与 DDL 未冻结	阶段二退出前不写 Controller（R-02）；Q-40/Q-43/Q-48 待决	无	IT-0 组织冻结会：F-01~F-14 冻结清单、D5/D8'/D3/D17、P-02/P-03/P-06/P-08、Q-15/Q-22/Q-25；未决前用 duty_operation_log JSON 兜底留痕（Q-40），平台侧 Q-48 用 PL_JOB_* JSON 兜底	IT-0~IT-4

1.3 优先级依据与口径偏离登记

表 13-5 「消费充值延后」的权威依据

依据	原文口径	对本计划的作用
docs/10 §11.2 表 11-1 P2-1	「账务：平台主账 + 公寓流水 + 日对账；餐饮改走账务接口」，理由「数据一致性风险最高的一环」	消费 / 充值排 P2，不进 IT-0~IT-8
docs/10 §11.2 表 11-1 P1-3	「叫乘状态机单一入口 + 盯控台」	叫乘进 P1 核心闭环
docs/10 §9 表 9-4 阶段三	「断网 2 小时完成『入住→叫乘→复叫→报警→应答→离寓→归档』」	核心闭环的业务边界
公寓端/07 表 7-4 第 6 行	账务本地流水三处标 P2：/apt/ledger/**、ledger/ConsumeList.vue、apt:ledger:*	本期不开账务接口 / 页面 / 权限点
公寓端/07 表 7-2 + §2	M0→M1→M2→M3 叫乘→M4→M5→M6，「顺序即依赖顺序，不允许跳批」	迭代依赖链不得跳批
CR-02 §2.4 表 3-5	后续 P2-1：补助规则引擎化、餐饮结算规则、跨公寓考核报表	延后域挂 P2-1
公寓端/09 表 9-17 第 5 步	「打开 #10 ledger（P2）」	联调顺序天然把账务放后，延后不改既有 8 步
平台端/09 P-07 / Q-44	餐饮域归属「阶段五」；features.remoteOrdering=false、N-58 恒 40940	菜品与远程点菜一并延后

表 13-6 口径偏离登记（须评审确认，不改写既有文档）

#	偏离	说明	建议处置
1	CR-02 R-53 / R-62 已撤销「本期不提供入住 / 换房 / 退房接口」「不做任何账务动作」，即消费充值在设计范围内；但 07 表 7-4 仍标 P2、§14 抬头明确「不改变本文件阶段划分与批次顺序」	本计划把消费充值实现排 IT-9~IT-11，属"设计已覆盖、实现延后"，不是删需求	在 CR-02 修订记录登记 v1.7 指向本文件；不改 §12~§15 任何权威表述
2	07 表 7-1 称阶段零「已完成」、表 7-5 第 5 条称「44 张表已实测通过」	该结论基于工作区不存在的 apartment/ 骨架，在 dev/ 上不成立	阶段零在 dev 上重新验收（IT-0），44 张表改由 IT-0 增量 DDL 交付；不删除既有结论，只登记适用前提
3	设计按 apartment/ 12 模块命名；dev 只有 6 个 ruoyi-* 模块	模块名与包根不同	采用「若依模块承载 + 业务包分层」映射（表 13-21），不新建 12 个 Maven 模块，避免破坏上游构建

---

2. 迭代划分

2.1 总览

表 13-7 迭代总览（IT-0IT-8 为本期，IT-9IT-11 为延后衔接）

迭代	名称	目标	范围（含 / 不含）	前置依赖	建议周期	对应既有批次 / 阶段
IT-0	基线对齐与契约冻结	把 dev 上游变成可开工的工程底座，冻结契约	含：基线决策、分域增量 DDL、apt 单入口脚手架、CI/测试骨架、凭据外置、F-01~F-14 与 D5/D8'/D3 签字；不含：任何业务 Controller	无（起点）	3 周	阶段零重验 + 阶段二（表 9-3）主体
IT-1	运行时基座	gyid 隔离、错误码、审计、/apt/** 鉴权成型	含 AptContext、拦截器、AptErrorCode、审计切面、分页、springdoc 分组；不含业务表 CRUD	IT-0	2 周	M0
IT-2	主数据与房间	交路 / 房间 / 主数据快照可读可管	含交路 CRUD + 复算校验、房间档案 + 房态、Mock 主数据下行；不含人员关联 Tab、叫乘	IT-1；D8'/D3 已签	3 周	M1 + M2
IT-3	人脸注册与签到核验（最小闭环）	支撑入住 CI-01 的刷脸核验前置	含 N-34 REG_APPLY → N-36 值班员确认 → apt_master_person 入档 → #9 PERSON_REG 同步回执 → 刷脸核验会话；不含设备批量下发 / 离寓擦除 / 媒体签名（挪至 IT-7）	IT-1、IT-2（房间 / 人员主档）；CR-C25 链路	2 周	§12 F-F / F-J 最小集
IT-4	入住作业核心	跑通 CI-01~CI-05 五环节	含入住申请（apt_local_task 补列）、值班员审核与换房、apt-stay 办理入住建 gy_jcxx、#9 CHECKIN 提报、#7 matchVerdict[] 拉取、任务生成与 jcsj 复算；N-38~N-47；不含消费、账务	IT-2、IT-3；Q-40 DDL 或 JSON 兜底	3 周	§13 F-K + M3 前置
IT-5	叫乘执行与状态机	apt.duty.state 单一入口 + 平板 / SIP 双模式最小集	含 STOP/RE_CALL 命令、状态时间线、jcsj 复算、平板 TABLET_RESULT（#9）/UNVERIFIED 复叫、SIP 降级回落；不含录音索引 / 12 项自检	IT-4；M3 状态机、D8'	3 周	M3 + §11 F-A / F-B
IT-6	上报续传 + 值班台 / 人员 / 设备	断网可跑、恢复可追平；值班台"看 + 干预"	含 outbox + 水位 + #9/#8/#13 续报、人员关联 Tab（M4）、设备网关指令入队（M5）、应用端 D-1~D-3 最小集；不含 #10 LEDGER_OFFLINE	IT-5；Q-21/Q-22/Q-23	3 周	M4 / M5 / D-1~D-3
IT-7	语音运维 + 人脸补齐	可叫乘探针、降级路径、人脸设备侧补齐	含分机台账 / 会话 / 录音索引、apt-ops 12 项自检、call-ready、Asterisk 降级；人脸设备下发 / 擦除 / 媒体边界	IT-5；D11/D12/D15/D16 已定稿、Asterisk 可达	3 周	M6 + §12 补齐
IT-8	单公寓试点与灰度	阶段三退出	含断网 2h 演练、恢复 10min 追平、灰度与回滚演练、阶段三 10 项验收；不含多公寓推广	IT-0~IT-7 全通过	2 周	阶段三（表 9-4）退出
IT-9~IT-11	消费 / 充值 / 菜品（延后）	见 §8 衔接规划	CF-01 / CF-02 / CF-03	见 §8 表 13-28	待排	后续 P2-1

图 13-1 依赖链（顺序即依赖顺序，不允许跳批）

flowchart LR
    I0["IT-0 基线/契约冻结"] --> I1["IT-1 基座 M0"]
    I1 --> I2["IT-2 主数据 M1+M2"]
    I2 --> I3["IT-3 人脸注册最小闭环"]
    I3 --> I4["IT-4 入住核心 CI-01~05"]
    I4 --> I5["IT-5 叫乘状态机 M3"]
    I5 --> I6["IT-6 上报/值班台/设备"]
    I5 --> I7["IT-7 语音运维 M6"]
    I6 --> I8["IT-8 试点与灰度"]
    I7 --> I8
    I8 -. "P2 进入条件满足后" .-> I9["IT-9~11 消费/充值/菜品"]

2.2 拆分逻辑

表 13-8 业务优先级与依赖顺序（为什么这样排）

序	判断	依据
1	先 IT-0 再任何编码	阶段二冻结前不写 Controller（公寓端/08 R-02）；dev 无表 / 无 CI / 有明文口令，阶段零需重验
2	基座 M0 → 主数据 M1+M2	07 表 7-2 明确 M2 依赖 M1、M3 依赖 M1+M2；D5→M0、D8'→M1、D3→M2 为强阻塞（公寓端/08 表 8-11）
3	人脸注册最小闭环先于入住	CI-01 要求"未注册先按 §12 完成注册"（CR-C25）；把 §12 切成"最小闭环（IT-3）+ 设备侧补齐（IT-7）"是本期最重要的小步切分，避免人脸媒体 / 擦除阻塞入住
4	入住 IT-4 → 叫乘 IT-5	叫乘任务只在 CHECKED_IN 且有效在寓时生成（公寓端/05 §10 衔接约束②）；applyId ↔ 预分配 jcid 一对一由入住侧产生
5	叫乘先于人员关联 M4	07 §2「为什么 M3 在 M4 之前」：先做 M3 让 M4 关联 Tab 直接可验证，避免两次返工
6	上报 IT-6 紧随叫乘	断网 2h / 恢复 10min 追平是阶段三退出条件；outbox 不能等语音做完才补
7	语音 IT-7 并行于 IT-6	D11/D12/D15/D16 可并行定稿（公寓端/08 结论「语音三项并行启动、不等开发进度」）
8	消费 / 充值 / 菜品整体延后	表 13-5 的 P2-1「数据一致性风险最高」；且 #10 在 公寓端/09 表 9-17 联调第 5 步本就标 P2

表 13-9 与既有编号体系的映射（不新增 M7 / 阶段六 / D-4）

本计划迭代	既有批次 / 阶段	应用端子批次	全局验收项
IT-0	阶段零重验 + 阶段二（表 9-3）	—	表 3-37、F-01~F-14 冻结清单
IT-1	M0	—（D-1 不得早于 M3）	表 7-3 M0 项
IT-2	M1 + M2	—	表 7-3 M1/M2 项
IT-3	§12 F-F / F-J 最小集	—	CR-02 §12 验收 15~17（最小集）
IT-4	§13 F-K	—	§13 表 3-57 验收 18~20
IT-5	M3 + §11 F-A / F-B	D-1 起（不得早于 M3）	表 7-3 M3 项、§11 验收
IT-6	M4 / M5 + outbox	D-1~D-3	表 7-5 第 1/2 项、表 7-7 步骤 1~8
IT-7	M6	D-2 / D-3 收口	表 7-3 M6 项、§12 验收 15~17（补齐）
IT-8	阶段三退出（表 9-4）	—	表 7-5 全 10 项
IT-9~IT-11	后续 P2-1	—	§14 表 3-62 验收 21~23、§15 表 3-69 验收 25

---

3. 各迭代明细

每个迭代的验收标准均须可复现；"对齐文档"列给出该迭代必须逐条核对的权威位置，"对齐代码模块"列给出 dev 实际承载路径。跨迭代回归基线见 §7。

表 13-10 IT-0 基线对齐与契约冻结（3 周）

项	内容
目标	把 dev 上游变成可开工底座，完成阶段二契约冻结
范围	表 13-4 六项 P0 处置；IR-01 基线决策评审、59 张分域增量 DDL（DDL 与回填分离、可重放）、apt 单入口脚手架 + 固定路由、CI/测试骨架、凭据外置、F-01~F-14 与 D5/D8'/D3/D17/P-02/P-03/P-06/P-08 签字
依赖	无；但需产品 / 架构 / 平台 / 应用端四方评审
对齐文档	docs/10 §9 表 9-1/9-3、表 10-2、§11.3；公寓端/02 §1/§2.4；公寓端/08 表 8-1/8-11；公寓端/09 表 9-18；CR-01 §5/§6、CR-02 表 3-33/表 3-36
对齐代码模块	dev/RuoYi-Vue-master/pom.xml、ruoyi-admin/src/main/resources/{application.yml,application-druid.yml}、ruoyi-framework/.../SecurityConfig.java、SwaggerConfig.java、ruoyi-quartz/.../ScheduleConfig.java、dev/RuoYi-Vue2-master/{vue.config.js,src/router,src/permission.js}
交付物 DV-0	基线偏离评审纪要、分域增量 DDL 脚本 + 回填脚本、脚手架、CI 工作流与测试骨架、冻结清单签字版、明文凭据扫描报告
验收标准	① 主干可稳定编译、单测可重复执行；② 仓库 CI 正则扫描无口令 / 内网地址 / AMI 凭据；③ 59 张表脚本二次执行幂等；④ sys_config 可读、ruoyi-admin（设计名 apt-admin）以 local profile 启动无异常；⑤ F-01~F-14 逐条签认（含 CR-01 建议的 F-14）；⑥ IR-01 基线方案 A/B 二选一形成书面结论
退出 / Go-NoGo	契约冻结签字完成；未冻结不进入 IT-1（R-02）

表 13-11 IT-1 运行时基座 M0（2 周）

项	内容
目标	gyid 隔离 / 统一错误码 / 审计 / 鉴权成型，让后续每域"只写业务"
范围	AptContext（gyid 只从会话 / 设备凭据解析）、四前缀拦截器、AptErrorCode 与 {code,msg,data.traceId}、@Log 扩展审计切面、分页上限 100、springdoc 分组扫 com.ruoyi.apt.**、/apt/** 鉴权；业务表只读查询骨架
依赖	IT-0；D5（一进程一 gyid）已签
对齐文档	公寓端/04 §1/§2、公寓端/03 §5 四级隔离、公寓端/07 表 7-3 M0 项、表 7-6 8 类用例
对齐代码模块	ruoyi-framework（SecurityConfig、WebMvcConfig）、ruoyi-common（AjaxResult/异常体系）、ruoyi-admin（启动类 + Swagger 分组）、ruoyi-system（sys_menu 权限点种子）
交付物 DV-1	拦截器 + 错误码 + 审计切面 + AptContext + 分页封装 + Swagger 分组 + 权限点种子 SQL + M0 用例脚本
验收标准	表 7-3 M0 四项全过：无令牌 /apt/route/list → 401；有令牌缺权限点 → 40301；gyid=A 查 gyid=B → 40302 且无数据泄露；异常统一返回无堆栈外泄；pageSize=1000 截为 100；架构测试断言所有业务 Mapper SQL 带 gyid

表 13-12 IT-2 主数据与房间 M1+M2（3 周）

项	内容
目标	交路、房间、主数据快照可读可管，为入住提供房间与交路要素
范围	交路 CRUD + 复算校验 + 启停原因；房间档案 + 房态 + 停用/恢复 + state_version；#1~#4 主数据下行 Mock（source='LOCAL'、页面标"非平台下发"）
依赖	IT-1；D8'（叫乘时刻口径）、D3（房间主数据）、D7 已签
对齐文档	公寓端/07 表 7-3 M1/M2 项、表 7-4 第 1/2/8 域；公寓端/09 §7 表 9-16 Mock 策略；CR-01 §2.8 Q8（交路批量预置）
对齐代码模块	新建 com.ruoyi.apt.master.*（ruoyi-system 内业务包）、com.ruoyi.apt.stay.*；ruoyi-generator 生成 CRUD 骨架；RuoYi-Vue2-master/src/entries/apt/views/{route,room}
交付物 DV-2	Controller/Service/Mapper/DTO/VO/页面/路由/权限点；Mock 灌数脚本（3 交路 / 5 房间 / 5 人员 / 2 天计划）；表 7-6 的 M1/M2 用例记录
验收标准	缺 cc/kcsj/reason → 40001 且指出字段；同 jlid 重复 → 40901；停用审计 duty_operation_log 含原因；房态筛选只返回 room_status=4；停用后恢复触发重算且 state_version 递增；快照字段改 xm → 40904；Mock 数据标记 source=LOCAL / source_version=0

表 13-13 IT-3 人脸注册与签到核验最小闭环（2 周）

项	内容
目标	支撑入住 CI-01 的刷脸核验，且不被人脸媒体/擦除复杂度阻塞
范围	含 N-34 REG_APPLY → N-35 待审 → N-36 值班员 CONFIRM（生效点）→ apt_master_person 入档 → #9 PERSON_REG 同步 + #2 personRegVerdicts[] 回执 → 签到终端刷脸核验会话（faceVerifyState）；不含设备批量下发 FACE_ISSUE、离寓擦除、媒体签名与对象存储、长期驻留保留（挪 IT-7）
依赖	IT-1、IT-2（人员 / 房间主档）；CR-C25 注册链路、CR-C24 媒体边界
对齐文档	公寓端/10 §4 注册链路与状态机、表 10-26/10-27；CR-02 §12（CR-C24/CR-C25、验收 15）；公寓端/11 §4 CI-01；Q-30/Q-35
对齐代码模块	com.ruoyi.apt.face.*（ruoyi-system 内）、com.ruoyi.apt.stay.* 核验会话；设备侧 /open/v1/face/** 匿名分区 + 设备凭据校验（SecurityConfig 扩展，不放行全量）
交付物 DV-3	注册申请 / 审核 / 主档 / 同步回执最小链路、核验会话接口、注册态与回执态字段、40914/40917~40924 错误码落地
验收标准	① 签到终端只能申请，值班台 duty:person:reg + 二次确认才可确认 / 驳回；② APPLIED 阶段不上传平台、不参与匹配 / 下发（40914）；③ 重复确认按 commandId 幂等返回原 ryid；④ 平台 REJECTED 不回滚本地注册（Q-35），只告警 + 待办；⑤ faceVerifyState 三值 VERIFIED/UNVERIFIED/SKIPPED 与 公寓端/05 §9 一致；⑥ 抓拍帧 / 人脸原图 / 比对帧不出终端

表 13-14 IT-4 入住作业核心 CI-01~CI-05（3 周）

项	内容
目标	跑通"注册签到 → 入住申请 → 值班员审核 → 提报匹配 → 叫乘任务"五环节
范围	含 apt_local_task 申请阶段补列（Q-40 冻结前用 duty_operation_log JSON 兜底）、N-38~N-47、值班员审核 / 换房 / 驳回、apt-stay 单事务建 gy_jcxx 行、#9 CHECKIN 提报、#8 回执作匹配输入、#7 matchVerdict[] 拉取、jcsj 公寓复算、gygl_ly_event(CHECKIN)；不含账务 / 消费 / 充值
依赖	IT-2、IT-3；D8'/D17/Q-15 已定；PL_TASK/PL_TASK_ACK 字段对齐（CR-01 §5 阶段二挂载点）
对齐文档	公寓端/11 全文（表 11-111-35、图 11-111-3）；CR-02 §13 表 3-57 验收 18~20；公寓端/05 §10；公寓端/09 §0 表 C-7；docs/设计变更/01 §2.4 / §5
对齐代码模块	com.ruoyi.apt.stay.*（apt-stay 子域）、com.ruoyi.apt.dispatch.* 任务生成、com.ruoyi.apt.report.* #9 上行、com.ruoyi.apt.master.* #7 拉取；前端 entries/apt/views/checkin/**、entries/duty/views/checkin/**
交付物 DV-4	申请单 / 审核 / 办理 / 提报 / 匹配全链路代码与页面、增量 DDL（或 JSON 兜底）、applyId↔jcid 映射与唯一约束、Q-36~Q-40 默认口径配置
验收标准	§13 验收 18~20 全过：① 五环节闭环，CHECKIN 提报 → #7 matchVerdict → 拉任务并复算 jcsj；② "已入住" = checkin_state=CHECKED_IN 流程态 + finish_ly='0' AND sjlysj IS NULL 业务事实 + gygl_ly_event(CHECKIN)，不新增 gy_jcxx 状态字段；③ applyId ↔ 预分配 jcid 一对一，申请阶段不建 gy_jcxx 行，审核通过由 apt-stay 单事务建行；④ match_state 五值、UNMATCHED/LOCKED 不清空本地要素；⑤ PL_TASK.jcsj 仅作基线，权威值恒由公寓复算（CR-C06）；⑥ 边界不破：59 张表、20 编号、v2-draft、平台零回调

表 13-15 IT-5 叫乘执行与状态机 M3（3 周）

项	内容
目标	apt.duty.state 成为业务终态唯一写入口，平板 / SIP 双模式最小闭环
范围	含 STOP/RE_CALL 受控命令 + commandId 幂等、状态时间线（状态迁移 + AMI 事件 + 人工命令按时间升序）、jcsj 复算、平板 TABLET_RESULT（#9）与 UNVERIFIED 复叫（Q-22）、SIP 降级回落（CR-C23）、只读字段不可改；不含录音索引、apt-ops 12 项自检
依赖	IT-4；M3 状态机、D8'、Asterisk 或 Mock 可达；应用端 D-1 不得早于本迭代
对齐文档	公寓端/07 表 7-3 M3 项 / 表 7-4 第 3 域 / 表 7-5 第 7 项；公寓端/05 §9（F-A/F-B）、§11；CR-02 §11；应用端/07 §1/§2（D-1）
对齐代码模块	com.ruoyi.apt.dispatch.*（状态机唯一入口）、ruoyi-quartz（定时触发；须启用 ScheduleConfig 或显式登记仍用 RAMJobStore）、com.ruoyi.apt.device.* 平板结果接入、com.ruoyi.apt.voice.* 最小 SIP 适配
交付物 DV-5	状态机 + 命令层 + 时间线 + 平板/SIP 结果接入 + 页面（列表/详情/时间线/命令）+ 架构测试（全仓 grep 状态字段 UPDATE 只出现在 apt.duty.state）
验收标准	表 7-3 M3 四项：PUT /apt/jcxx/{id} 不存在、correct 改 ryzt → 40001；同 commandId 重复 STOP 只生效一次；对 finish_ly='1' 的 STOP → 40902；时间线三类事件齐全；平板 UNVERIFIED 保持待确认 + 复叫、不判完成；迟到 / 重复结果 IGNORED；平板链路不发 #24；平台不可达时按最后快照继续执行

表 13-16 IT-6 上报续传 + 值班台 / 人员 / 设备（3 周）

项	内容
目标	断网可跑、恢复可追平；值班台"看 + 干预"上线
范围	含 outbox（队列）+ 终态流水不互换、水位与 #14 心跳、#9/#8/#13 续报复用原 idempotencyKey、人员关联 Tab（M4）、设备网关指令入队（M5）、应用端 D-1~D-3 最小集；不含 #10 LEDGER_OFFLINE（P2）
依赖	IT-5；Q-21（离线额度缺省全 0）/Q-22/Q-23/Q-25
对齐文档	公寓端/07 表 7-5 第 1/2 项、表 7-7 步骤 1~8；公寓端/09 §7 表 9-16 Mock 策略、表 9-17 联调 8 步；平台端/05 表 5-2；CR-02 表 3-21 / 表 3-30；应用端/07 表 7-6 / 7-7 / 7-8
对齐代码模块	com.ruoyi.apt.report.*（outbox / watermark / 续报）、com.ruoyi.apt.master.* 人员关联、com.ruoyi.apt.device.* 指令队列、RuoYi-Vue2-master/src/entries/duty/**（duty 入口本期开出）
交付物 DV-6	outbox + 水位 + 续报链路、M4/M5 代码与页面、duty 入口脚手架、断网演练记录、20 接口各 1 条"请求样例 → 落库断言"回归基线
验收标准	断网 2h 主链路不中断；恢复 ≤10min outbox 清空、acked_watermark = current_watermark、count 零差异、max(watermark) 追平（CR-01 表 1-23 含离线指定要素 / 离线调整时刻用例）；PL-IDEMPOTENT-REPLAY 视为成功且不产生新业务事实；M5 指令只入队 PENDING、无心跳不伪造 ACKED；M4 关联 Tab 正确且快照只读 40904；值班台命令幂等 duplicated=true、越界不可写、时钟偏差 ≤5s

表 13-17 IT-7 语音运维 + 人脸设备侧补齐（3 周）

项	内容
目标	可叫乘探针、降级路径、人脸设备侧能力补齐（与 IT-6 并行）
范围	分机台账 / 会话 / 录音索引、apt-ops 12 项自检、call-ready、Asterisk 不可用走"串口广播 + 值班台人工"；§12 剩余部分：FACE_ISSUE 设备下发、离寓擦除、媒体签名、LONG_TERM 保留
依赖	IT-5；D11/D12/D15/D16 定稿、Asterisk 可达；Q-30~Q-35
对齐文档	公寓端/07 表 7-3 M6 项 / 表 7-5 第 9/10 项；公寓端/10 §5~§12、CR-02 §12 验收 15~17；公寓端/06 §5/§8 表 6-8；docs/10 表 10-2 D16
对齐代码模块	com.ruoyi.apt.voice.*（新增 asterisk-java 依赖）、com.ruoyi.apt.ops.*、RuoYi-Vue2-master/src/entries/apt/views/{voice,ops}、ruoyi-common 文件上传能力（录音索引只存引用）
交付物 DV-7	语音 / 自检 / 人脸下发擦除代码与页面、12 项自检落库、降级演练记录、依赖变更清单
验收标准	改号被拒 40906；录音签名地址有效、PURGED 返回 41001；自检 12 项落库且 AMI 不可达时 call-ready=false 且原因准确；Asterisk 不可用走串口广播 + 人工、不静默失败；人脸"上传平台 / 下发设备"双路解耦并行互不阻塞；擦除超时 50303 升级全量同步；业务抓拍 / 录音不出公寓

表 13-18 IT-8 单公寓试点与灰度（2 周）

项	内容
目标	阶段三退出，形成可推广基线
范围	断网 2h 全链路演练、恢复 10min 追平、准点率对比、值班操作步骤 ≤10%、灰度与回滚演练、#9 影子模式转正式、关闭 Mock 切真实平台
依赖	IT-0~IT-7 全通过；PR-09 本期只开 1 个公寓；P-08 白名单就绪
对齐文档	公寓端/07 表 7-5（10 项）、表 7-6（8 类 + 3 专项）、表 7-7（9 步）；docs/10 表 9-4；平台端/08 表 8-5 灰度回滚；公寓端/09 表 9-17 第 4/8 步；平台端/09 PR-02/PR-09/PR-10
对齐代码模块	全部 com.ruoyi.apt.*；CI 回归流水线；application-{local,prod}.yml 配置外置
交付物 DV-8	阶段三验收报告、演练取证（gy_jcxx/apt_call_session/gy_jcxx_his）、灰度 / 回滚记录、回归基线全绿报告、遗留问题清单
验收标准	表 7-5 全 10 项通过；#9 影子模式"只写不生效"→ 对账零差异连续 3 天后转正式；关闭 Mock 后 24h 无 P0/P1；gyid 跨公寓用例 100% 拦截；状态单写入口架构测试通过；仓库无明文凭据；回滚演练通过（回滚是回退业务形态，不是回滚数据）；旧页 JcXx.vue 保留至阶段五、不得先删

---

4. 里程碑与节奏建议

表 13-19 里程碑与 Go/No-Go

里程碑	时点	可验证结果	Go/No-Go 判据	关联迭代
MS-0 工程底座就绪	第 3 周末	apt-admin 可启动、59 张表脚本幂等、CI 全绿、无明文口令	契约冻结签字；未签字不进 IT-1	IT-0
MS-1 基座与主数据可管	第 8 周末	交路 / 房间 CRUD、Mock 下行、gyid 隔离 100%	表 7-3 M0~M2 项全过	IT-1~IT-2
MS-2 入住 + 叫乘核心闭环可演示	第 16 周末	单公寓、Mock 平台下跑通"刷脸核验 → 入住 → 审核 → 提报匹配 → 叫乘 → 状态机"	§13 验收 18~20 + 表 7-3 M3 项全过；这是本期最重要的可演示节点	IT-3~IT-5
MS-3 断网闭环与值班台	第 19 周末	断网 2h 主链路、恢复 10min 追平、值班台看 + 干预	表 7-5 第 1/2 项、CR-01 表 1-23 全过	IT-6
MS-4 语音与运维补齐	第 22 周末	call-ready 探针、降级路径、人脸设备侧	表 7-3 M6 项、§12 验收 15~17 全过	IT-7
MS-5 阶段三试点退出	第 24 周末	全部 10 项验收、灰度与回滚演练、回归基线全绿	docs/10 表 9-4 退出条件；此后才评估 P2 进入条件	IT-8
MS-6 账务域（延后）	待排	消费 / 充值 / 菜品闭环	见 §8 表 13-28 进入条件	IT-9~IT-11

表 13-20 节奏建议

项	建议	理由
单迭代节奏	按迭代分档：IT-1 / IT-3 / IT-8 为 2 周（开发与回归同窗），IT-0 / IT-2 / IT-4~IT-7 为 3 周（2 周开发 + 1 周联调 / 回归 / 决策会，含评审窗口）；与表 13-7「建议周期」逐行一致	小步快跑且每步留回归窗口；与 07 表 7-7「逐模块联调」一致
总周期	IT-0~IT-8 串行保守基线约 24 周（6 个月），表 13-19 的里程碑时点按此排；核心闭环 MS-2 在第 16 周	让"入住 + 叫乘"在半年周期内尽早可演示
并行度	IT-6 与 IT-7 可在 IT-5 后并行（两组人）；若并行，MS-4 可提前至第 19 周、MS-5 不早于第 21 周，Go/No-Go 判据与灰度观察窗不变；语音三项决策 D11 / D12 / D15 / D16 并行定稿、不等开发	公寓端/08 表 8-11 结论「语音三项并行启动」；表 13-19 的 24 周为不并行时的保守口径
决策会	每迭代末 30 分钟口径会；IT-0 末尾契约冻结会（半天）；MS-2 后一次 P2 进入条件评估	应用端/08 表 8-7「D-2 阻塞最密集，须在 D-1 验收前开 30 分钟决策会」
缓冲	每 3 个迭代留 1 周缓冲，用于 DDL 冻结、Asterisk 环境、平台 Mock 对齐	IR-01/IR-02/IR-06 均为外部依赖
反模式	不跳批、不先写 Controller、不在 IT-0~IT-8 开 /apt/ledger/**、不为赶进度关闭 Mock 校验	公寓端/09 抬头 R-02、表 9-16 「生产强制 false 启动校验」

---

5. 对齐矩阵：设计文档 × 代码模块 × 迭代

表 13-21 设计模块 → dev 承载位置 → 落地迭代（不新建 12 个 Maven 模块）

设计模块 / 子域	dev 承载路径（业务包分层）	复用若依能力	主要表	落地迭代
apt-framework / apt-common	ruoyi-framework（com.ruoyi.framework.*）、ruoyi-common（com.ruoyi.common.*）	SecurityConfig、@PreAuthorize、AjaxResult、LogAspect、分页	sys_*	IT-0、IT-1
apt-admin	ruoyi-admin（RuoYiApplication，唯一 jar）	启动 / Swagger / profile	—	IT-0
apt-system	ruoyi-system（com.ruoyi.system.*）	sys_menu / sys_user / RBAC	sys_*	IT-0、IT-1
apt-master-client	ruoyi-system 新增 com.ruoyi.apt.master.*	ruoyi-generator 生成 CRUD	apt_master_route / rule / room / person / version、gy_syn_jcxx	IT-2、IT-6
apt-stay（含 apt.checkin.*）	ruoyi-system 新增 com.ruoyi.apt.stay.*	事务、@Log	apt_local_task（补列）、gy_jcxx、gy_rooms、gygl_ly_event	IT-2、IT-4
apt.face.registry / apt-face	ruoyi-system 新增 com.ruoyi.apt.face.*	文件上传（仅引用）、Anonymous 注解	apt_master_person、apt_person_face_reg	IT-3、IT-7
apt-dispatch（apt.duty.state）	ruoyi-system 新增 com.ruoyi.apt.dispatch.* + ruoyi-quartz	Quartz 定时（须处理 ScheduleConfig 被注释）	gy_jcxx、gy_jcxx_his、duty_manual_action	IT-4、IT-5
apt-device	ruoyi-system 新增 com.ruoyi.apt.device.*	无（净新增）	gy_sb、apt_device_command	IT-5、IT-6
apt-voice	ruoyi-system 新增 com.ruoyi.apt.voice.*（新增 asterisk-java 依赖）	文件上传（录音索引）	apt_sip_endpoint、apt_call_session、apt_recording	IT-5、IT-7
apt-report（outbox）	ruoyi-system 新增 com.ruoyi.apt.report.*	无（净新增）	apt_report_outbox / history / watermark	IT-4、IT-6
apt-ops	ruoyi-admin 现有 monitor/{Cache,Server}Controller 扩展	oshi 监控	apt_ops_selfcheck	IT-7
apt.ledger.local（延后）	ruoyi-system 预留 com.ruoyi.apt.ledger.*（本期不建包）	无	gy_ykt_*、apt_ledger_offline	IT-9~IT-11
前端 apt 入口	RuoYi-Vue2-master/src/entries/apt/**（IT-0 建）	v-hasPermi、src/utils/request.js、动态路由权限点	—	IT-0~IT-8
前端 duty 入口	RuoYi-Vue2-master/src/entries/duty/**	同上	—	IT-6

表 13-22 各迭代必须逐条核对的权威文档（验收引用以此为准）

迭代	主键文档	验收表 / 条款
IT-0	docs/10 §9/§11.3、公寓端/02、08、09、CR-01 §5/§6、CR-02 表 3-33/3-36	表 9-1/9-3、表 8-11、表 9-18、F-01~F-14
IT-1~IT-2	公寓端/04 §1/§2、03 §5、07 表 7-2~7-4、09 表 9-16	表 7-3 M0~M2、表 7-6 8 类用例
IT-3	公寓端/10 §4、11 §4、CR-02 §12	表 10-26/10-27、验收 15、Q-30/Q-35
IT-4	公寓端/11 全文、05 §10、09 表 C-7、CR-02 §13	表 3-57 验收 18~20、表 11-35
IT-5	公寓端/05 §9/§11、07 表 7-3/7-5、应用端/07 §1/§2	表 7-3 M3、表 7-5 第 7 项
IT-6	公寓端/07 表 7-5/7-7、09 表 9-16/9-17、平台端/05 表 5-2、应用端/07 表 7-6~7-8	表 7-5 第 1/2 项、CR-01 表 1-23
IT-7	公寓端/07 表 7-3/7-5、10 §5~§12、06 §5/§8	表 7-3 M6、表 7-5 第 9/10 项、§12 验收 15~17
IT-8	docs/10 表 9-4、公寓端/07 表 7-5~7-8、平台端/08 表 8-5、平台端/09 PR-02/09/10	表 7-5 全 10 项
IT-9~IT-11	公寓端/12 全文、09 表 C-8/C-9、平台端/10、CR-02 §14/§15	表 12-34、表 3-62 验收 21~23、表 3-69 验收 25

---

6. 风险台账与应对

表 13-23 风险台账（IR-y 为本文件内编号，不占用既有 R-* / PR-* / Q-*）

编号	风险	等级	触发时点	应对方式	兜底 / 不做什么
IR-01	技术基线冲突（JDK17/Boot4.1 vs 设计 JDK8/Boot2.5）	P0	IT-0	推荐方案 B 修订设计基线锁定值并走变更评审；方案 A（降级 dev）备选；Swagger 注解改 springdoc	不擅自改 docs/公寓端/02；未签字不写业务代码
IR-02	表数口径冲突 / 无业务表	P0	IT-0~IT-1	分域增量 DDL，DDL 与回填分离、回填可重放；二次执行幂等验收；改库名与凭据	不改 59 张设计口径；不在业务代码里直接 CREATE TABLE
IR-03	前端双入口 / 动态路由与固定路由冲突	P1	IT-0、IT-6	apt 单入口先行、duty 随 D-1 开出；sys_menu 仅作权限点载体	不魔改 permission.js 全局动态路由
IR-04	无 CI / 测试工程，8 类用例无承载	P1	IT-0	补 starter-test + MockMvc + CI 工作流 + 架构测试；每迭代沉淀回归基线	不以"手工点点"替代自动化回归
IR-05	明文口令 / token.secret	P1	IT-0	全部外置 + CI 正则扫描卡口	阶段零"已完成"在 dev 重新验收，不沿用旧结论
IR-06	契约 / DDL 未冻结（F-01~F-14、D5/D8'/D3、Q-40）	P0	IT-0~IT-4	冻结会签字；冻结前不写 Controller（R-02）	Q-40 用 duty_operation_log JSON 兜底；平台 Q-48 用 PL_JOB_* JSON 兜底
IR-07	dev Quartz ScheduleConfig 被注释 = RAMJobStore	P1	IT-5	叫乘定时前显式决策：启用 JDBC JobStore 或登记单实例 RAM 的风险	多实例部署前必须解决；本期单公寓单实例
IR-08	Asterisk / AMI 依赖缺失且 D11/D12/D15/D16 未决	P1	IT-5~IT-7	三项决策并行定稿；IT-5 用 Mock 结果接入、IT-7 才接真实 AMI	不静默失败；Asterisk 不可用走串口广播 + 人工
IR-09	人脸媒体 / 设备擦除复杂度阻塞入住	P1	IT-3	§12 切分为「最小闭环（IT-3）+ 设备侧补齐（IT-7）」	IT-3 不接对象存储、不做批量下发；抓拍帧不出终端
IR-10	平台 / 运安不可用导致 M0~M4 被阻塞	P1	IT-1~IT-6	公寓端/09 表 9-16 Mock 策略：APT_REPORT_DISPATCH_ENABLED=false + apt.master-client.mock=true 仅 local profile	Mock 数据标 source=LOCAL、outbox 只累积不派发、不允许假成功置 SENT；生产强制 false 启动校验
IR-11	断网 / 时钟偏差 / 乱序导致状态错乱	P1	IT-6、IT-8	三时间戳 + serverReceivedAt 归日 + 幂等键 + 条件更新；表 7-6 三类专项	occurredAt 不判日切；任务类不套 LEDGER 的「差值 ≤10 分钟」门槛
IR-12	旧页 / 旧接口双跑期间数据分叉	P2	IT-8 后	平台端/09 PR-02：「一侧只读」或按 gyId 白名单互斥；PR-09 本期只开 1 个公寓	旧页 JcXx.vue、旧 /jcgl/** 保留至阶段五才下线，不得先删
IR-13	消费充值延后导致 #10 / 账务统计无数据	P2	IT-8 后	平台端/10 账务三类指标标 data_status=NO_DATA / BLOCKED，报表注明"数据未接入"	不推断、不补零、不以其他表代填（CR-C39、表 10-9）
IR-14	范围蔓延：把 P2 账务提前塞进核心迭代	P1	全周期	表 13-28 进入条件 + IT-8 前的范围卡口评审	本期不开 /apt/ledger/**、不建 com.ruoyi.apt.ledger 包、不建支付订单

表 13-24 P0 决策清单与阻塞关系（沿用既有编号，不新增 D/Q/P）

决策	内容	阻塞	拍板时点
D5	一进程一 gyid	IT-1（M0）	IT-0 冻结会
D8' / D17	jcsj 恒由公寓复算、主键与匹配键分离	IT-2（M1）、IT-4	IT-0 冻结会
D3	房间主数据	IT-2（M2）	IT-0 冻结会
D7	交路应急新增	IT-2	IT-0 冻结会
F-01~F-14	20 接口冻结清单（F-14 为 CR-01 建议追加）	全部 Controller	IT-0 冻结会
P-02/P-03/P-06/P-08	平台侧方向 / 过渡 / 白名单	IT-6、IT-8	阶段二之前（平台端/09 表 9-4）
Q-15/Q-22/Q-25	阈值、权限点、准点率三档；平板复叫	IT-5、IT-6	阶段三试点前
D11/D12/D15/D16	语音与 Asterisk HA	IT-7	阶段二冻结前 / M6 前
D1/D2	餐饮归属、余额主账位置	不阻塞本期，但阻塞 IT-9	P2 进入条件评估时

---

7. 跨迭代联调与测试安排

表 13-25 联调顺序（承接 公寓端/07 表 7-7 九步 / 公寓端/09 表 9-17 八步，#10 保持 P2 位置不变）

步	联调内容	前置	通过标志	所在迭代
1	20 接口路径 / 字段对齐 → 差异清单签字（冻结 v1）	IT-0	F-01~F-14 签字	IT-0
2	启动 apt-admin（local）→ 登录链路 captchaImage→login→getInfo	IT-1	启动无异常、拿到 token 与 permissions	IT-1
3	Mock 灌 3 交路 / 5 房间 / 5 人员 / 2 天计划	IT-2	apt_master_version 有 APPLIED、标 LOCAL	IT-2
4	交路 → 房间 → 人脸注册 → 入住申请 / 审核 / 办理	IT-3、IT-4	表 7-3 M1/M2、§13 验收 18~20 全过	IT-3~IT-4
5	#14 心跳 → outboxWatermark / clockSkewMs	IT-6	水位与时钟偏差可读	IT-6
6	#9 duty-results 影子模式「只写不生效」→ 对账零差异连续 3 天	IT-6 / IT-8	零差异	IT-6 起、IT-8 收口
7	打开 #10 LEDGER_OFFLINE（P2）	P2 进入条件	账务日对账零差异	延后 IT-9，本期跳过
8	#11/#12/#13 摘要（含 §15 的 satisfaction{} / roomOccupancy{} 分组计数）	IT-6	摘要不阻塞主链路；缺报标 NO_DATA	IT-6~IT-8
9	#23/#24 语音域；关闭 Mock 切真实平台	IT-7、IT-8	24h 无 P0/P1	IT-7~IT-8

表 13-26 测试分层与跨迭代回归基线

层	内容	承载	每迭代动作	来源
L1 单元	Service / 状态机 / 复算 / 双额度（延后）	JUnit5 + Mockito（新增 starter-test）	新增用例，覆盖率门槛按域设定	IR-04
L2 接口	Controller / 错误码 / 鉴权 / 分页 / gyid	MockMvc	表 7-6 的 8 类用例逐域执行：正常查询、分页边界、必填、重复冲突、无权限、gyid 隔离、状态非法、只读快照	公寓端/07 表 7-6
L3 专项	幂等（同 commandId 连发 3 次只 1 条）、时间戳（事件毫秒 / 列表秒）、空数据（200 + total=0 不返回 null）	集成测试	每迭代固定执行	表 7-6 补充三类专项
L4 架构	状态字段 UPDATE 只出现在 apt.duty.state；所有业务 SQL 带 gyid；无明文口令	CI 静态扫描 + ArchUnit	每迭代必跑，失败即阻断合入	表 7-5 第 6/7/8 项
L5 契约	20 接口各 1 条「请求样例 → 落库断言」	契约测试	冻结后作回归基线，跨迭代不删只增	公寓端/09 §7 表 9-16 / 表 9-18
L6 端到端	断网 2h + 恢复 10min + 灰度回滚	现场演练	MS-3 / MS-5 各一次，取证归档	表 7-5、CR-01 表 1-23
L7 应用端	命令幂等 duplicated=true、越界不可写、告警不误报、时钟 ≤5s	应用端/07 表 7-6/7-7	IT-6 起纳入回归	应用端/07

表 13-27 跨迭代回归与 Mock 切换纪律

项	规则
回归范围	累积式：IT-n 必须回归 IT-0~IT-(n-1) 的全部 L2/L3/L4/L5 基线，不允许"只测本迭代"
基线冻结	IT-0 产出 20 接口请求样例 → 落库断言；每迭代新增只追加、不修改既有断言
Mock 开关	APT_REPORT_DISPATCH_ENABLED=false + apt.master-client.mock=true 仅 local profile；生产启动强制校验 false，否则拒绝启动
Mock 数据标注	apt_master_version.source='LOCAL' / source_version=0，页面标"非平台下发"；outbox 只累积不派发、禁止假成功置 SENT
影子模式	#9 duty-results 先"只写不生效"，对账零差异连续 3 天才转正式（公寓端/09 表 9-17 第 4 步）
切换顺序	先切本地库与状态机（M3 / IT-5）→ 再切值班台（D-2 / IT-6）→ 最后摘旧页 JcXx.vue（阶段五）；旧页不得先删
灰度与回滚	平台端/08 表 8-5：域级 master→person→route→plan→ledger→report（本期不到 ledger）；公寓级 gyId 白名单先 1 个公寓跑满 1 个结算周期；回滚是回退业务形态，不是回滚数据
联调环境	单公寓单实例（PR-09）；platform-worker 单活；Asterisk 用 Mock 至 IT-7

---

8. 后续消费 / 充值 / 菜品模块衔接规划

8.1 延后范围与进入条件

表 13-28 延后域与 P2 进入条件（全部满足才启动 IT-9）

项	内容
延后范围	CF-01 人员消费（N-49N-51、双额度 CAS、一条 CONSUME 流水）、CF-02 人员线下充值（N-52N-55、管理员二次确认、只增 xjye）、CF-03 公寓菜品管理（N-48 / N-57 / #4 recipes[]）；对应 公寓端/12 §4~§6、四条状态链、4093340940、S-01S-07 报表消费端
进入条件 1	MS-5 阶段三验收 10 项全过，单公寓试点稳定 ≥1 个结算周期（平台端/08 §8）
进入条件 2	D1（餐饮归属）/ D2（余额主账位置）归属先签字（不阻塞本期，但阻塞账务实现）；P-07 餐饮域定稿
进入条件 3	Q-41~Q-45 拍板（补贴不足现金补足、离线充值受 offlineQuota 约束、knye/xjye 语义与 YKT_MEALS 补列复核、远程点菜启用条件、单笔上限 / 双人复核 / 内部人员透支）
进入条件 4	Q-43 / Q-48 DDL 契约冻结：gy_ykt_* 五张预留表、apt_ledger_offline、YKT_MEALS、PL_REPORT_DAILY / PL_LEDGER_FLOW 补列、2 张 pl_apt_stat_*
进入条件 5	平台 #10 LEDGER_OFFLINE 影子模式"只写不生效"→ 对账零差异连续 3 天；platform-ledger 余额主账就绪
进入条件 6	#1 offlineQuota 下发链路与 features.remoteOrdering=false 开关可用；日对账 #16 与 POST /adjustments 冲正通道验收通过

8.2 本期「预埋但不上线」清单

表 13-29 为避免 IT-9 返工，本期必须预埋 / 必须避免

类别	本期预埋（不做实现）	本期不做（防止范围蔓延）
数据	59 张表 DDL 中保留 gy_ykt_* / apt_ledger_offline 的表结构与补列定义（建表不开放读写）；报表统计账务三类指标按 NO_DATA / BLOCKED 输出	不写账务业务数据、不以其他表代填、不推断不补零
接口	#1 响应保留 offlineQuota（缺省全 0）、features.remoteOrdering=false；#13 摘要 payload 预留 satisfaction{} / roomOccupancy{} 分组计数	不开 /apt/ledger/**、不开 /open/v1/ledger/**（N-49~N-55）、不建支付订单 / 回调
代码	包结构预留 com.ruoyi.apt.ledger（不建包）；错误码段 40933~40940 登记在 公寓端/04 表 C-3 但不启用	不建 apt.ledger.local 服务、不引支付 SDK、不写 YKT_MEALS_ORDERING / ORDERS_MX
权限	apt:ledger:* / duty:ledger:* / platform:stat:* 权限点在 sys_menu 登记但置灰（公寓端/07 表 7-4 第 6 行 P2）	不授予任何角色、不出现在值班台菜单
报表	平台端/10 五类指标中账务三类按 data_status=NO_DATA / BLOCKED 输出，报表注明"数据未接入"；CASH_RECHARGE_INCOME 口径（计收入、不与消费抵销）先冻结	不参与排名、不对 NO_DATA 公寓补零、不以 pl_staff_performance_daily 代填
边界	统计结果不回写任何业务状态；三个单写入口不变；平台库 2 张 pl_apt_stat_* 在本期（IT-0~IT-8）不建（Q-48 冻结后再建，见 平台端/03、平台端/10）	不新增 bizType、不新增跨端编号、不新增对象存储桶

8.3 衔接迭代建议

表 13-30 IT-9~IT-11（待排，仅给顺序与验收，不占本期周期）

迭代	目标	范围	依赖	验收要点
IT-9 账务底座	apt.ledger.local 与 platform-ledger 对齐	gy_ykt_* / apt_ledger_offline 补列落库、#1 offlineQuota、#10 影子转正式、#16 日对账、POST /adjustments 冲正	表 13-28 全部进入条件	日对账 count/sum(amount)/max(watermark) 三维零差异；PF-5003 阻断调账；PL-VERSION-STALE 置 DEAD
IT-10 消费 + 线下充值	CF-01 / CF-02 闭环	N-49~N-55、补贴优先 / 现金补足双额度 CAS、一笔消费只一条 CONSUME 流水、管理员二次确认、只增 xjye、值班台核对 / 作废	IT-9；Q-41/Q-42/Q-45	§14 表 3-62 验收 21~23：三项流程闭环、四条状态链互不替代、十类动作留痕、设备与前端零余额表写权限；CASH_RECHARGE_INCOME 计收入不与消费抵销（CR-C37）
IT-11 菜品 + 统计收敛	CF-03 与平台报表打通	N-48 / N-57、#4 recipes[]、YKT_MEALS 补列、publish_state、N-58 远程点菜仅预留（40940）；平台端/10 五类指标与月/季/年排名正式启用	IT-10；P-07 / Q-44 / Q-46~Q-50	§14 验收 21~23 + §15 表 3-69 验收 25/26；食谱缓存只在终端本地、确认前不落库；缺报 NO_DATA 不补零；不新增桶 / bizType / 跨端编号

表 13-31 衔接期的三个不变式（防止 P2 上线破坏核心闭环）

#	不变式
1	账务域上线不得改变 apt.duty.state 单写入口、gy_jcxx 状态字段数、20 个跨端编号与 v2-draft 契约
2	统计与排名结果不回写 gy_jcxx / apt_local_task / GY_YKT_REMAINDER / YKT_MEALS 等任何业务表；apt.duty.state / platform-ledger / platform-report 三个单写入口不变
3	核心闭环的 L2L5 回归基线在 IT-9IT-11 期间持续全绿；任一账务变更导致入住 / 叫乘回归失败，先回滚账务域开关（回退业务形态，不回滚数据）

---

9. 交付物与提交纪律

表 13-32 交付物清单（承接 公寓端/07 表 7-8，按本计划迭代重排）

迭代	代码	文档 / 配置	验证记录
IT-0	脚手架、CI/测试骨架、凭据外置、apt 入口	基线偏离评审纪要、分域增量 DDL + 回填脚本、冻结清单签字版、CI 配置	编译 / 单测 / 明文扫描 / DDL 二次执行幂等报告
IT-1~IT-2	拦截器、错误码、审计、交路 / 房间 CRUD 与页面	接口约定落地说明、字段说明与待确认项、权限点种子	表 7-3 M0~M2 + 表 7-6 8 类用例记录、curl / 页面截图
IT-3~IT-5	人脸最小闭环、入住五环节、状态机与平板 / SIP 结果接入	applyId↔jcid 映射说明、状态机与命令说明、Q-36~Q-40 默认口径配置	§13 验收 18~20、表 7-3 M3、架构测试报告
IT-6~IT-7	outbox / 水位 / 续报、人员 / 设备、duty 入口、语音 / 自检 / 人脸设备侧	Mock 策略说明、20 接口请求样例 → 落库断言基线、依赖变更清单	断网演练取证、表 7-7 联调 9 步记录、表 7-6/7-7 应用端用例
IT-8	全量回归修复	阶段三验收报告、灰度 / 回滚记录、遗留问题清单、P2 进入条件评估纪要	表 7-5 全 10 项、L2~L5 全绿报告
IT-9~IT-11	账务 / 充值 / 菜品 / 统计（延后）	公寓端/12 与 平台端/10 的落地说明	§14 表 3-62、§15 表 3-69 验收记录

提交纪律：本轮只产出设计与排期文档，不写业务代码、不建表改表、不执行 DDL / DML、不执行 git commit / git push；dev/ 两套上游保持未改动，所有新增落在后续迭代的独立分支并由评审合并。本文件不改变 docs/公寓端/07 的 M0M6 批次顺序、docs/10 的阶段零五划分与 D1~D16 待决状态；表 13-6 的三项口径偏离须经评审确认后方可执行。