mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 08:20:31 +08:00
hpd840321
7b2bd307f1
- backend/: 13 Maven modules (cw-elevator-application, cloudwalk-cloud, intelligent-cwoscomponent, ninca-crk, etc.) - frontend/: 4 Vue projects (elevator-front, cwos-portal, alarm-front, front_acs) + decompiled + scripts - scripts/: build, test-env, tools (Docker Compose, service templates, API parity) - docs/: AGENTS.md, superpowers specs, architecture docs - .gitignore: standard Java/Maven exclusions Moved from legacy maven-*/ root layout to backend/ organized structure.
97 lines
6.2 KiB
Markdown
97 lines
6.2 KiB
Markdown
# 对外接口不变前提下的远程调用与性能优化约定
|
||
|
||
**适用范围**：本仓库电梯应用（`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 次数上界**、**下一可实施修正**、**在契约不扩展前提下不可做或须先确认** 的项。
|