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,46 @@
+# 对外接口不变：走查任务与状态
+
+> **依据**：[对外接口不变-远程调用与性能优化约定](对外接口不变-远程调用与性能优化约定.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`（约 109～121 行） | **`F = passRuleResults.size()`** 次 `acsPersonService.page`（仅取 `totalRows`） | **P1**：按楼层 **有界并行** `page`（如 `rowsOfPage=1`）；**合并结果顺序**与树遍历一致；**立即修正**：循环内对 **`page.isSuccess()`** 校验（当前缺失，违反 §2.2） | **禁止**用本地 `countPersonIdByZoneId` 等替代 `page.totalRows`（与 `PersonRuleServiceImpl#page` 路径过滤**不等价**，见约定 §3.3）；**无多 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` 增加 **`zoneTree` / `page` 的 `isSuccess` 与空数据防护**（满足 §2.2，避免失败当 0）。  
+2. **P0 阻塞项**：与图库团队确认 **`updateGroupPersonRef`** 在「多 label/org 一次传入」下的语义 → 通过后实施 **§3.1 合并**。  
+3. **P1 工程项**：为 §3.2 / §3.3 / §3.4 引入**统一有界线程池**（或复用现有异步池策略），并在 PR 中写明失败策略与超时。
+
+---
+
+## 4. 文档维护
+
+| 项目 | 内容 |
+|------|------|
+| 更新触发 | `ImageRuleRefServiceImpl#delete`、`AcsPersonServiceImpl#delete`、`AcsPassRuleServiceImpl#listFloor` / `#addImageStore`、`AcsDeviceTaskServiceImpl#updateFloors` 任一处重构或签契约变更 |
+| 结论回填 | 图库对 §3.1 的确认结论请写回 [约定文档 §3.1](对外接口不变-远程调用与性能优化约定.md) 文末建议行（对接人 + 日期） |