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

chore: 工作区反编译与 Maven/文档/脚本同步到发布分支

Browse Source 
- artifacts/decompiled 树与相关源码变更
- maven-cw-elevator-application 业务 docs 与 package-info
- scripts 下 formatter 校验与辅助脚本
- 其他子工程/接口与发布线一并纳入版本控制

Made-with: Cursor

Former-commit-id: e102e8cab64e575bcd23c9a66a598aa1892bb492
This commit is contained in:
反编译工作区
2026-04-25 09:35:35 +08:00
parent 1c28fcedfc
commit dee355b4a7
2000 changed files with 133077 additions and 169300 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/对外接口不变-走查任务与状态.md
+41 -8
View File
@@ -2,7 +2,8 @@
> **依据**：[对外接口不变-远程调用与性能优化约定](对外接口不变-远程调用与性能优化约定.md)（§2 总原则、§3 场景、§4 优先级）。
> **走查代码根**：`maven-cw-elevator-application/cw-elevator-application-service`（2026-04-24 静态走查）。
> **说明**：下表「子任务数」指**与约定相关的 RPC/可优化循环次数上界**（随运行时数据规模变化）；**状态**表示在**不扩展 Feign/HTTP 契约**前提下是否建议动代码。
> **说明**：下表「子任务数」指**与约定相关的 RPC/可优化循环次数上界**（随运行时数据规模变化）；**状态**表示在**不扩展 Feign/HTTP 契约**前提下是否建议动代码。
> **排期（2026-04）**：`frontend/` 暂无可用前端工程；**凡需改前端、登记页、物业管理端 UI 的迭代，暂跳过**（详见 [docs/README 当前排期与范围](../README.md#当前排期与范围2026-04)）。本文档仅跟踪**电梯等服务端**在约定下的走查与修正。
---
@@ -14,7 +15,7 @@
| **§3.2** | `AcsPersonServiceImpl#delete` | **`P = param.getPersonIds().size()`** 次 `imageStorePersonService.delete` | **P1 首轮已实施**（**§8**）：`elevatorRemoteBoundedExecutor` 按批 `invokeAll`（默认并发 **6**），子线程 **`FeignThreadLocalUtil.callWithContext`**；遇失败**整批后**即返回 `CloudwalkResult.fail`（与原先顺序循环遇错即停一致，**非**单条失败即取消同批其它在途 RPC） | **无批量 delete**；同批内并行语义见 **§8.1** |
| **§3.3** | `AcsPassRuleServiceImpl#listFloor` | **`F = passRuleResults.size()`** 次 `acsPersonService.page` | **P1 首轮已实施**（**§8**）：楼层 `page` 有界并行（默认 **6**），`personTotals[]` 按下标写回，**列表顺序不变** | **禁止**本地 count 替代 `totalRows`；RPC 上界仍为 **F** |
| **§3.4** | `AcsPassRuleServiceImpl#addImageStore` 内设备绑图库 | **`D = deviceList.size()`** 次 `bindDeviceAndImageStore` | **P1 首轮已实施**（**§8**）：`bind` 有界并行；失败仍 **`rollbackImageStoreAfterBindFailure`** 后抛 `ServiceException`（与同批已绑设备竞态与顺序循环**同类**） | **无批量 bind** |
| **§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())` 信息较粗，是否属「接口不变」范畴由产品/运维定义 |
| **§3.5** | `AcsDeviceTaskServiceImpl#updateFloors` | 增删楼层远程调用**墙钟**上界仍分别为 **A**、**D** 次；**有界并行**可缩短多楼层场景耗时（**迭代 5**，见 **§9**） | 内层 `imageRuleRefService.delete` 仍受 **§3.1 冻结** 时的 RPC 上界与语义约束；`@Async("updateFloorsExecutor")` 下背压与 `catch` 细粒度见 **§7.3** / **§9** |
---
@@ -38,6 +39,7 @@
|----|------|
| **约定 §3.1 全范围** | 未取得图库/通行对 `updateGroupPersonRef` 语义确认前，**不进行**与该约定相关的**任何**代码修正与优化（含 **合并 N→1** 及 §6.4 所述**仅 `isSuccess` 校验**小步），避免在无确认期分散实现与回滚成本。 |
| **恢复条件** | 图库书面或接口说明确认 + 在 [约定文档 §3.1](对外接口不变-远程调用与性能优化约定.md) 文末回填对接人、日期；再按 §1 表拆分 PR（合并与返回值校验可分步）。 |
| **前端相关** | 仓库**暂无可用前端**；所有需改**前端 / 登记页 / 物业端页面**的迭代**暂不排期、不执行**（与本文服务端走查无冲突；产品方案中 UI 类阶段见 [docs/README](../README.md#当前排期与范围2026-04)）。 |
### 迭代 3（**§3.5 `updateFloors`**）
@@ -45,7 +47,7 @@
|------|------|
| **状态** | **走查与首轮修正已完成**（见 **§7**）：`getById` 空防护、步骤级 `CloudwalkResult` 校验、`keepAliveSeconds` 绑定线程池。 |
| **约定锚点** | **§3.5** `AcsDeviceTaskServiceImpl#updateFloors` |
| **暂缓项** | 楼层有界并行、`AbortPolicy` 与 `catch` 语义、删楼 `ruleMap` 缺键等见 **§7.3**。 |
| **暂缓项** | 楼层有界并行**已**见 **§9**；`AbortPolicy` 与 `catch` 语义、其它见 **§7.3**。 |
### 迭代 4（**P1：§3.2 / §3.3 / §3.4 + 统一有界池**）
@@ -55,12 +57,19 @@
| **线程池 Bean** | `elevatorRemoteBoundedExecutor`（`ElevatorRemoteIoExecutorConfig`），配置前缀 **`ninca.elevator.remote-io.pool`**（默认 core=max=**6**，queue=512，`CallerRunsPolicy`）。**未**与 `updateFloorsExecutor` 合并，避免异步任务与同步 RPC 抢同池。 |
| **公共能力** | `FeignThreadLocalUtil.callWithContext`（`cw-elevator-application-common`）：子线程执行 Feign 前绑定/恢复 ThreadLocal 请求头。 |
### 迭代 5 及以后（可选深化）
### 迭代 5（**§3.5 `updateFloors` 楼层有界并行**）
- **§3.5**：`updateFloors` 内楼层循环有界并行（仍受 §3.1 内层放大约束）。
- **调参 / 观测**：`ninca.elevator.remote-io.pool` 按环境压测调整；必要时为并行批增加指标日志。
| 字段 | 内容 |
|------|------|
| **状态** | **已实施**（见 **§9**）：增楼列表、删楼列表在各自阶段内以最多 **6** 路**并发**执行 `add` / `addOnlyRule` / `delete` 等；**`BIND_DEVICES` 仍按原列表顺序**、每层成功**仍 +1** 重读任务行，与纯串行「进度语义」一致；子线程 Feign 经 `FeignThreadLocalUtil`；`ruleMap` 缺 `zoneId` 时用 **`getOrDefault(…, "")`** 防 NPE。 |
| **不变更** | **§3.1 全冻结** 期间未改 `ImageRuleRefServiceImpl#delete` 内 `updateGroupPersonRef` 次数。 |
**已完成回顾**：迭代 1 — **§5**；迭代 2 — **§6**（§3.1 冻结）；迭代 3 — **§7**；迭代 4 — **§8**。
### 迭代 6 及以后（可选）
- **调参 / 观测**：`ninca.elevator.remote-io.pool` 按环境压测；必要时为 `updateFloors` 批处理增加**指标/耗时日志**（不扩展 HTTP 响应）。
- **§3.1**：图库确认后再评估合并 N→1 与（若允许）`updateGroupPersonRef` 的 `isSuccess` 小步。
**已完成回顾**：迭代 1 — **§5**；迭代 2 — **§6**（§3.1 冻结）；迭代 3 — **§7**；迭代 4 — **§8**；迭代 5 — **§9**。
---
@@ -171,7 +180,7 @@
### 7.3 评估结论（是否允许进入代码修正）
- **允许并已实施（本轮）**：`task` 空指针防护；对 **`personRuleService.add` / `delete`**、**`imageRuleRefService.addOnlyRule` / `delete`** 的 **`CloudwalkResult` 成功校验**（约定 §2.2）；`updateFloorsExecutor` 绑定 **`keepAliveSeconds`**。
- **暂缓（须单独评审）**：按楼层 **有界并行**、拒绝策略、`catch` 异常语义增强、`ruleMap` 缺键防护。
- **暂缓（须单独评审）**：拒绝策略、`catch` 异常语义增强；**楼层有界并行**与 `ruleMap` 缺键防护**已**见 **§9**。
**修正实施后**：提交 **`0ddeedc`**（分支 `v0.11`）。
@@ -192,3 +201,27 @@
| **Feign ThreadLocal** | 所有子线程 RPC 经 **`FeignThreadLocalUtil.callWithContext`**，避免池化线程串请求头。 |
**实施后提交**：**`fe571aa`**（分支 `v0.11`）。
---
## 9. 迭代 5：`updateFloors` 楼层有界并行（§3.5）
**实施日期**：2026-04-24（工作区）
### 9.1 设计要点
| 项 | 说明 |
|----|------|
| **并发度** | 与 §8 一致使用 **`elevatorRemoteBoundedExecutor`** 的 **`ThreadPoolExecutor#invokeAll`**，批大小 **`UPDATE_FLOORS_FLOOR_PARALLEL = 6`**（与 `AcsPassRuleServiceImpl` 等处一致）。 |
| **bind 推进** | 同批内各楼层 RPC **可并发**；`Future#get()` **按列表下标顺序** 等待；每遇返回值 **1** 则主线程**再** `getById` 后 **`BIND_DEVICES`+1**，与旧实现「每层成功后立即 +1」的**终态**一致。 |
| **停任务** | 每层子步骤开头仍 `getById`；`isStop != 0` 时该层贡献 **0**、不推进 bind。 |
| **DAO 异常** | 删楼分支中 `getByRuleName` / `deleteByOrgAndLabel` 的 **`DataAccessException`** 在子步内转 **`ServiceException`**，以配合 `Callable` 与 `invokeAll` 的异常链。 |
| **§3.1** | 未改 `imageRuleRefService.delete` 实现，内层 `updateGroupPersonRef` 行为与冻结前一致。 |
### 9.2 同批多楼层与「遇错即停」
与 **§8.1** 类似：同批中若一 Floor 的 RPC 失败，同批**其它在途** Floor 的 RPC 可能已执行完毕；`get()` 按顺序在**首败**时抛出。与严格串行「前一层失败则后层不再发起」在**已发出请求**上可存在差异，属有界并行常见取舍。
### 9.3 代码位置
- `AcsDeviceTaskServiceImpl#updateFloors`、`#runAddFloorsInBoundedParallel` / `#runDelFloorsInBoundedParallel`、`#addOneFloorStep` / `#delOneFloorStep`、`#advanceBindProgressOne`。