huangping/starRiverProperty
1
0
Fork 0
mirror of https://github.com/hpd840321/starRiverProperty.git synced 2026-06-09 08:20:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
反编译工作区
2026-04-25 08:10:29 +08:00
parent d3de42bd28
commit e1ab6efd23
3 changed files with 144 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+2
View File
@@ -19,6 +19,8 @@
### 工程说明（architecture）
- [Maven 聚合工程说明](architecture/Maven聚合工程说明.md) — 五个 `maven-*` 聚合工程的定位、子模块、技术栈、工程间依赖与 `artifacts`/运行包分工。
- [对外接口不变-远程调用与性能优化约定](architecture/对外接口不变-远程调用与性能优化约定.md) — HTTP/Feign 不扩展前提下，合并 RPC、有界并行与返回值校验等原则。
- [对外接口不变-走查任务与状态](architecture/对外接口不变-走查任务与状态.md) — 与约定对齐的代码走查：子任务量、可修正项与不可修正/须确认项。
### 业务（business）
docs/architecture/对外接口不变-走查任务与状态.md
+46
View File
@@ -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) 文末建议行（对接人 + 日期） |
docs/architecture/对外接口不变-远程调用与性能优化约定.md
+96
View File
@@ -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 次数上界**、**下一可实施修正**、**在契约不扩展前提下不可做或须先确认** 的项。