docs(architecture): API-stable RPC walkthrough + link index

- Add 走查任务与状态: per §3.1–3.5 subtask bounds, next fixes vs blocked items
- Link from 约定 doc; scope wording; docs/README architecture links
- listFloor: note missing page.isSuccess per §2.2

Made-with: Cursor

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

@@ -0,0 +1,96 @@
+# 对外接口不变前提下的远程调用与性能优化约定
+
+**适用范围**：本仓库电梯应用（`maven-cw-elevator-application`）及与之集成的 intelligent / 图库等 Feign 调用路径。  
+**订立日期**：2026-04-24  
+**状态**：团队约定（实施前对「远端语义」类条目需与图库/通行服务二次确认）。  
+**走查落地**：[对外接口不变-走查任务与状态](对外接口不变-走查任务与状态.md)（子任务计数、可修正 / 不可修正与下一步）。
+
+---
+
+## 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](对外接口不变-走查任务与状态.md)**：按 §3.1～§3.5 与当前代码对齐，列出 **RPC 次数上界**、**下一可实施修正**、**在契约不扩展前提下不可做或须先确认** 的项。