starRiverProperty/docs/architecture/对外接口不变-远程调用与性能优化约定.md

对外接口不变前提下的远程调用与性能优化约定

适用范围：本仓库电梯应用（maven-cw-elevator-application）及与之集成的 intelligent / 图库等 Feign 调用路径。
订立日期：2026-04-24
状态：团队约定（实施前对「远端语义」类条目需与图库/通行服务二次确认）。
走查落地：对外接口不变-走查任务与状态（子任务计数、可修正 / 不可修正与下一步）。

---

1. 「对外接口不变」的可操作定义

层级	是否允许变更	说明
对客户端 HTTP	否	URL、Method、请求/响应 JSON 字段与语义、成功/失败码含义与现网一致。
本模块内部实现	是	ServiceImpl、DAO、私有方法、远程调用次数、并行策略等，只要最终 HTTP 行为与业务语义一致。
intelligent / 图库等 Feign 契约	默认否	不新增 batchDelete、多 zone 一次统计等接口时，仅允许在现有方法上组合、批处理逻辑或有界并行。若单独立项扩展 Feign，再按新版本评审。

下文默认 HTTP 与 Feign 契约均不扩展。

---

2. 总原则

1. 等价优先：任何减少 RPC 或改并行的地方，须保证与改造前同一业务语义（尤其 totalRows、删除范围、刷新范围）；不得用「近似」本地统计替代远端分页结果，除非完成对账验收并文档留痕。
2. 返回值必检：对 CloudwalkResult / Feign 封装结果须校验 isSuccess（或项目统一规范）；禁止依赖「失败静默」作为常态路径。
3. 合并优于 N 次：若远端操作对同一维度幂等重算（如按 label/org 刷新引用），优先在本地删库结束后去重并集单次调用，而非循环内重复调用。
4. 无法合并时的默认手段：在契约无批量 API 时，采用有界并行（固定线程池或 Semaphore，建议并发度 4～8，可按环境调参），并明确失败聚合策略与现网「遇错即停」等行为一致。
5. 事务边界：涉及多 RPC + 本地 DB 时，在约定中明确是否 @Transactional、失败是否需补偿；禁止在未定义产品语义时擅自「部分成功」。

---

3. 按场景的具体约定

3.1 ImageRuleRefServiceImpl.delete（循环内 updateGroupPersonRef）

• 目标：降低重复刷新带来的 RPC 与负载。
• 约定：在所有 deleteById（或等价删库步骤）完成后，对本轮涉及的 labelIds、organizationIds 去重并集，再调用一次 updateGroupPersonRef。
• 前置条件：与图库/通行侧确认「仅传 label/org 列表」为刷新引用语义，而非会把图库裁剪为仅含这些维度的破坏性语义。若不能确认，退化为保持循环调用 + 仍须做返回值校验。
• HTTP：不变。

3.2 AcsPersonServiceImpl.delete（循环内 imageStorePersonService.delete）

• 约束：ImageStorePersonDelParam 仅支持单 personId，无批量 delete 时不扩展契约。
• 约定：采用有界并行 delete；失败策略与现实现一致（例如任一失败则整体失败）；若需与现网「严格顺序失败」完全一致，须在实现中定义完成顺序与异常聚合方式。
• HTTP：不变。

3.3 AcsPassRuleServiceImpl.listFloor（每层 acsPersonService.page 仅取 totalRows）

• 约束：AcsPersonQueryParam 单 zone；图库侧无「多楼层一次返回人数」API 时，不能靠单次 RPC 消除 N。
• 禁止：用本地 countPersonIdByZoneId 等 SQL 人数直接替代 imageStorePersonService.page 的 totalRows（与 PersonRuleServiceImpl.page 路径下的 label/org/del 等过滤不等价），除非完成逐层对账并书面验收。
• 约定：在契约不扩展时，最优为按楼层有界并行 page（如 rowsOfPage=1 仅取总数），按树顺序合并结果，保证响应列表顺序与字段不变。
• HTTP：不变。

3.4 AcsPassRuleServiceImpl.addImageStore（循环 bindDeviceAndImageStore）

• 约定：无批量 bind 时，有界并行 bind；异常时的回滚（如删除已建图库）须与现逻辑一致，并注意并行下与顺序相关的竞态。
• HTTP：不变。

3.5 AcsDeviceTaskServiceImpl 等按楼层调用 personRuleService.delete / imageRuleRefService.delete

• 约定：优先受益于 3.1 的合并刷新；若仍为每层 delete，可叠加楼层级有界并行，前提是错误语义与资源侧限流可接受。

---

4. 实施优先级（契约不扩展时的 ROI）

优先级	项	说明
P0	3.1 合并 updateGroupPersonRef + 返回值校验	收益大、变更面相对集中；依赖远端语义确认。
P1	3.3 / 3.2 / 3.4 / 3.5 有界并行	不改 DTO/URL，主要降低墙钟时间；注意线程池生命周期与超时。
远期	Feign 批量/聚合接口	契约可扩展时，再评估批量 delete、多 zone 统计等结构性优化。

---

5. 变更与评审

• 任何偏离本约定（例如采用本地 count 替代 totalRows）须在 PR/变更说明中单列风险并附对账或测试证据。
• 与 intelligent 团队对齐「updateGroupPersonRef 语义」后，建议在本文 3.1 节追加结论日期与对接人一行，便于审计。

---

6. 相关代码锚点（便于检索）

场景	典型类/方法
人员分页与规则	AcsPersonServiceImpl#page、getRuleListByZoneId
楼层人数	AcsPassRuleServiceImpl#listFloor
规则与图库口径对照	PersonRuleServiceImpl#page
规则引用删除	ImageRuleRefServiceImpl#delete
人员删除与图库	AcsPersonServiceImpl#delete

---

7. 走查任务索引（子任务与状态）

见 对外接口不变-走查任务与状态.md：按 §3.1～§3.5 与当前代码对齐，列出 RPC 次数上界、下一可实施修正、在契约不扩展前提下不可做或须先确认 的项。