starRiverProperty/docs/architecture/对外接口不变-走查任务与状态.md

对外接口不变：走查任务与状态

依据：对外接口不变-远程调用与性能优化约定（§2 总原则、§3 场景、§4 优先级）。
走查代码根：maven-cw-elevator-application/cw-elevator-application-service（2026-04-24 静态走查）。
说明：下表「子任务数」指与约定相关的 RPC/可优化循环次数上界（随运行时数据规模变化）；状态表示在不扩展 Feign/HTTP 契约前提下是否建议动代码。

---

1. 总览表（子任务量 + 可修正 / 不可修正）

约定 §	代码锚点	子任务数（上界）	下一可修正动作（建议顺序）	不可修正或须前置确认
§3.1	ImageRuleRefServiceImpl#delete（约 575～598 行）	N = param.getIds().size() 次 updateGroupPersonRef（每规则删后各 1 次）	P0：全部 deleteById 完成后，对本轮涉及的 labelIds、organizationIds 去重并集，调用 1 次 updateGroupPersonRef；为每次 RPC 增加 isSuccess 校验（与 §2.2 一致）	须图库/通行确认：合并调用是否为「刷新引用」语义、是否等价于当前 N 次效果；若不能确认则不得合并，仅可补返回值校验与日志
§3.2	AcsPersonServiceImpl#delete（约 165～175 行）	P = param.getPersonIds().size() 次 imageStorePersonService.delete	P1：有界并行（并发度 4～8）调用 delete，失败聚合与现网「遇错即停」一致；已具备 isSuccess 分支，保持语义	无批量 delete：无法改为单次 RPC，除非将来扩展契约（约定 §4 远期）
§3.3	AcsPassRuleServiceImpl#listFloor	F = passRuleResults.size() 次 acsPersonService.page（仅取 totalRows）	首轮已完成：page.isSuccess()、getData() 空防护、rowsOfPage=1。P1 后续：按楼层 有界并行 page（保持结果顺序）	禁止用本地 countPersonIdByZoneId 等替代 page.totalRows；无多 zone 一次统计 API 时无法单 RPC 消除 N
§3.4	AcsPassRuleServiceImpl#addImageStore（约 195～201 行）	D = deviceList.size() 次 bindDeviceAndImageStore	P1：有界并行 bind；并行失败时与现有 回滚删图库 逻辑一致（注意竞态与顺序）	无批量 bind：不能合并为 1 次 RPC（契约不扩展时）
§3.5	AcsDeviceTaskServiceImpl#updateFloors（约 46～119 行）	增：A = addFloors.size() 次 personRuleService.add 或 imageRuleRefService.addOnlyRule；删：D = delFloorIds.size() 次 personRuleService.delete / imageRuleRefService.delete / DAO	P1：删层在 §3.1 落地后可减少「内层 refresh」放大；可对楼层维度做有界并行（与限流/异步线程池策略一致）	@Async("updateFloorsExecutor") 下线程池与背压须单独评估；错误现为 throw new ServiceException(e.getMessage()) 信息较粗，是否属「接口不变」范畴由产品/运维定义

---

2. 数量小结（便于排期）

类型	计数符号	含义
§3.1 可合并 RPC	由 N 降为 1（在语义确认后）	规则批量删除场景收益最大
§3.2 并行度	P	人员多 ID 删除
§3.3 并行度	F	楼层列表人数统计
§3.4 并行度	D	设备绑图库
§3.5	A + D	异步任务按层调用

---

3. 建议下一迭代（不改 HTTP/Feign 签名）

1. 小改快赢：AcsPassRuleServiceImpl#listFloor 已增加 page 的 isSuccess 与空数据防护、rowsOfPage=1（见 §5）。
2. P0 阻塞项：与图库团队确认 updateGroupPersonRef 在「多 label/org 一次传入」下的语义 → 通过后实施 §3.1 合并。
3. P1 工程项：为 §3.2 / §3.3（并行 page）/ §3.4 引入统一有界线程池（或复用现有异步池策略），并在 PR 中写明失败策略与超时。

---

4. 文档维护

项目	内容
更新触发	ImageRuleRefServiceImpl#delete、AcsPersonServiceImpl#delete、AcsPassRuleServiceImpl#listFloor / #addImageStore、AcsDeviceTaskServiceImpl#updateFloors 任一处重构或签契约变更
结论回填	图库对 §3.1 的确认结论请写回 约定文档 §3.1 文末建议行（对接人 + 日期）

---

5. 迭代 1：AcsPassRuleServiceImpl#listFloor 走查结论（§3.3 / §2.2）

走查日期：2026-04-25
代码位置：maven-cw-elevator-application/.../passrule/impl/AcsPassRuleServiceImpl.java 方法 listFloor。

检查项	现状	结论
zoneService.tree 返回值	已校验 zoneTree.isSuccess()，失败抛 ServiceException	通过
acsPersonService.page 返回值	循环内未校验 page.isSuccess()，直接 page.getData() 取 totalRows	不通过：违反约定 §2.2；Feign 失败时 getData() 可能为 null，存在 NPE 风险，且可能把失败误当「0 人」
page.getData() 空指针	未防护	不通过：与上项合并修正
rowsOfPage	当前为 10，仅使用 totalRows	建议：改为 1（约定 §3.3：仅取总数，略减负载），不改变 HTTP 响应字段

评估结论（是否允许进入代码修正）：通过进入修正 — 仅补充与 zoneTree 分支一致的失败处理及空数据防护，不改变对外 JSON 字段语义；rowsOfPage=1 与现逻辑（只读 totalRows）等价。

代码修正（已应用，2026-04-25）：AcsPassRuleServiceImpl#listFloor — 增加 page.isSuccess() 失败抛错、page.getData() 为空时 personNumber=0、CloudwalkPageInfo(1,1) 仅取总数。

修正实施后：提交 e652eb3（分支 v0.11）。

---

6. 迭代 2 起（占位）

• §3.1 待图库确认后再改代码；确认前不在此文档标记为「已实施」。