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

> **依据**：[对外接口不变-远程调用与性能优化约定](对外接口不变-远程调用与性能优化约定.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](对外接口不变-远程调用与性能优化约定.md) 文末建议行（对接人 + 日期） |

---

## 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)` 仅取总数。

**修正实施后**：提交 **`251fc86`**（分支 `v0.11`）。

---

## 6. 迭代 2 起（占位）

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