mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 08:20:31 +08:00
docs: component-org 上线日志分析报告与楼层策略触发优化方案
This commit is contained in:
@@ -0,0 +1,351 @@
|
||||
# component-organization.info.log 全量分析 & 策略频繁调用根因分析
|
||||
|
||||
**日期**: 2026-05-10
|
||||
**日志范围**: 12:41:32 ~ 13:18:38 (37 分钟)
|
||||
**分支**: feature/guangfa-28f-hardcoded
|
||||
**数据库**: 10.0.22.103 / cloudwalk / component-organization
|
||||
|
||||
---
|
||||
|
||||
## 一、日志概览
|
||||
|
||||
```
|
||||
文件: logs/component-organization.info.log
|
||||
大小: 26MB
|
||||
行数: 106,372
|
||||
TraceId: 9,848 个
|
||||
服务端口: 17016
|
||||
```
|
||||
|
||||
### 日志构成
|
||||
|
||||
```
|
||||
████████████████████████████░░░░░ 84.2% 设备同步 (89,531 行)
|
||||
██████████░░░░░░░░░░░░░░░░░░░░░░ 29.9% WARN (31,800 行)
|
||||
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.06% 用户业务 detail() 调用 (64 行)
|
||||
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.02% ERROR (20 行)
|
||||
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.01% POLICY 命中 (12 行)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、服务启动时间线
|
||||
|
||||
```
|
||||
12:41:32 首个请求到达（device updatePerson）
|
||||
12:41:42 Quartz 调度器启动
|
||||
12:42:07 Hystrix 初始化完成
|
||||
12:44:07 jasypt 加密引导
|
||||
12:44:09 Redis Lua 脚本 Bean 覆盖（9 个）
|
||||
12:44:27 Controller 映射注册 /component/person/listPerson
|
||||
12:46:27 首个业务 detail() 调用（距启动 ~5 分钟）
|
||||
13:18:38 最后一条日志（图库同步失败 WARN）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、业务调用完整时间线（36 次 detail 调用）
|
||||
|
||||
### 3.1 按调用方来源分类
|
||||
|
||||
`POST /component/person/detail` 被以下 **7 个调用方** 消费：
|
||||
|
||||
| # | 调用方 | 代码位置 | 调用场景 | 是否需要策略 |
|
||||
|---|--------|---------|---------|-------------|
|
||||
| 1 | **前端访客邀约页** | 通过 `PersonController.detail()` | 初始化可选择楼层 | **✅ 需要** |
|
||||
| 2 | **前端人员管理** | 通过 `PersonController.detail()` | 人员详情查看 | ❌ 不需要 |
|
||||
| 3 | **elevator addVisitor UC-01** | `PersonRuleServiceImpl:175` | 一键派梯，需要 floorList | **✅ 需要** |
|
||||
| 4 | **elevator addVisitor UC-02** | `PersonRuleServiceImpl:175` | 仅校验被访人存在 | ❌ 不需要(不用 floorList) |
|
||||
| 5 | **CRK 访客注册** | `VisitorRegisterServiceImpl:330,648` | 访客登记 | **✅ 需要** |
|
||||
| 6 | **CRK 门禁识别记录** | `AcsRecogRecordServiceImpl:86` | 识别记录，仅需人员信息 | ❌ 不需要 |
|
||||
| 7 | **电梯设备/记录** | `AcsElevatorDeviceServiceImpl` 等 | 设备同步 | ❌ 不需要 |
|
||||
|
||||
### 3.2 日志中的调用时序
|
||||
|
||||
```
|
||||
12:46:27 detail personId=1099676120751034368 [MFG鼎鸿/613] 4 zones ✗ 未命中
|
||||
12:46:36 detail personId=833276118323793920 [大地保险/办公室] 3 zones ✗ 未命中
|
||||
12:48:44 detail personId=730473849711333376 [行政人事部/陕西巨丰] 5 zones ✗ 未命中
|
||||
12:48:50 detail personId=783987999653621760 [陕西巨丰/业务部] 2 zones ✗ 未命中
|
||||
12:49:11 detail personId=783987999653621760 [同一人 21秒后再查] 2 zones ✗ 未命中
|
||||
12:51:22 detail personId=1032218423083470848 陈晶丽 [外包+物管] 38 zones ★ 命中 → 6F
|
||||
12:53:31 detail personId=903269751508242432 [陕西巨丰/业务部] 2 zones ✗ 未命中
|
||||
12:56:13 detail personId=1087053273767612416 [612/MFG鼎鸿] 4 zones ✗ 未命中
|
||||
12:56:25 detail personId=1071436837510660096 [金辉华集团/工程中心] 2 zones ✗ 未命中
|
||||
12:56:56 detail personId=1087053273767612416 [同一人 43秒后再查] 4 zones ✗ 未命中
|
||||
12:58:18 detail personId=1028610903966322688 [投资助理/陕西巨丰] 2 zones ✗ 未命中
|
||||
12:59:55 detail personId=805732141303721984 刘光林 [厨房+物管] 5 zones ★ 命中 → 6F
|
||||
12:59:59 detail personId=805732141303721984 [同一人 4秒后再查] 5 zones ★ 命中 → 6F
|
||||
13:00:14 detail personId=1105585180195930112 [仅 1 zone] 1 zone (无策略检查)
|
||||
13:01:42 detail personId=775326439246499840 [陕西巨丰/业务部] 2 zones ✗ 未命中
|
||||
13:02:20 detail personId=992819015204597760 雷恒豫 [外包+物管] 38 zones ★ 命中 → 6F
|
||||
13:02:24 detail personId=901059320052314112 [财务/陕西巨丰] 2 zones ✗ 未命中
|
||||
13:02:26 detail personId=1018452759471689728 [新媒体/陕西巨丰] 4 zones ✗ 未命中
|
||||
13:03:06 detail personId=1032604140250959872 冯水英 [环境部+物管] 38 zones ★ 命中 → 6F
|
||||
13:03:08 detail personId=964199538912989184 戚浩 [外包+物管] 38 zones ★ 命中 → 6F
|
||||
13:03:25 detail personId=721734719120691200 覃永杰 [保安部+物管] 31 zones ★ 命中 → 6F
|
||||
13:03:29 detail personId=721734719120691200 [4秒后再查] 31 zones ★ 命中 → 6F ⚠️
|
||||
13:03:33 detail personId=721734719120691200 [又4秒后再查] 31 zones ★ 命中 → 6F ⚠️
|
||||
13:03:33 detail personId=770218949916094464 [陕西巨丰/业务部] 2 zones ✗ 未命中
|
||||
13:03:44 detail personId=721734719120691200 [第4次，11秒后再查] 31 zones ★ 命中 → 6F ⚠️
|
||||
13:04:09 detail personId=957214640516231168 [新媒体/陕西巨丰] 4 zones ✗ 未命中
|
||||
13:04:41 detail personId=906237696010194944 [陕西巨丰/大客户部] 2 zones ✗ 未命中
|
||||
13:05:03 detail personId=771809951973847040 [新媒体/陕西巨丰] 4 zones ✗ 未命中
|
||||
13:06:13 detail personId=1030066143429201920 [新媒体/陕西巨丰] 6 zones ✗ 未命中
|
||||
13:07:56 detail personId=770218949916094464 [陕西巨丰/业务部] 2 zones ✗ 未命中
|
||||
13:09:20 detail personId=1105554183521812480 [仅 1 zone] 1 zone (无策略检查)
|
||||
13:10:28 detail personId=1101592364922802176 [MFG鼎鸿/613] 4 zones ✗ 未命中
|
||||
13:13:41 detail personId=605578568533016576 [大地保险] 3 zones ✗ 未命中
|
||||
13:13:54 detail personId=605578568533016576 [13秒后再查] 3 zones ✗ 未命中
|
||||
13:13:54 detail personId=992819015204597760 雷恒豫 [外包+物管] 38 zones ★ 命中 → 6F
|
||||
13:17:25 detail personId=1079804406034599936 [最后一条] 4 zones (无策略检查)
|
||||
```
|
||||
|
||||
### 3.3 高频重复查询分析
|
||||
|
||||
```
|
||||
覃永杰 (721734719120691200): 19秒内查询 4 次
|
||||
13:03:25 → 13:03:29 (4秒间隔) → 13:03:33 (4秒间隔) → 13:03:44 (11秒间隔)
|
||||
判断: 前端批量操作（连续打开多人详情）或页面轮询
|
||||
|
||||
刘光林 (805732141303721984): 4秒内查询 2 次
|
||||
12:59:55 → 12:59:59
|
||||
判断: addVisitor 阶段1 + 前端详情页并发请求
|
||||
|
||||
雷恒豫 (992819015204597760): 12分钟内查询 2 次
|
||||
13:02:20 → 13:13:54
|
||||
判断: 两次独立操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、策略频繁调用的根因分析
|
||||
|
||||
### 4.1 问题表述
|
||||
|
||||
**用户原意**: 租户访客楼层策略（`TenantVisitorFloorPolicyService`）只应在「访客邀约初始化页面」触发，用于确定被访人的可选楼层列表。
|
||||
|
||||
**实际情况**: 策略在 **36 次 detail() 调用** 中被触发了 **24 次**（12 次额外命中做了楼层替换），但其中只有部分来自访客邀约场景。
|
||||
|
||||
### 4.2 根因：`detail()` 是多消费者通用 API，策略代码无条件嵌入
|
||||
|
||||
```
|
||||
POST /component/person/detail
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────┐
|
||||
│ ImgPersonServiceImpl.detail() │
|
||||
│ L670-672: │
|
||||
│ tenantVisitorFloorPolicy │
|
||||
│ Service.replacementZoneIds │
|
||||
│ IfPolicyActive(orgIds) ← 无条件触发!
|
||||
└───────────────────────────────┘
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
│ │ │
|
||||
访客邀约页 ✅ 人员管理 ❌ addVisitor
|
||||
(需要策略) (不需要) UC-02 ❌
|
||||
(不消费 floorList)
|
||||
```
|
||||
|
||||
### 4.3 所有 detail() 调用方一览
|
||||
|
||||
```
|
||||
personService.detail() 的 Feign 消费者:
|
||||
|
||||
1. PersonController.detail() ← 前端 HTTP 入口
|
||||
├─ 访客邀约页初始化 ✅ 策略必需
|
||||
└─ 人员管理/详情查看 ❌ 策略无意义（但无法区分）
|
||||
|
||||
2. PersonRuleServiceImpl.addVisitor() ← 电梯侧
|
||||
├─ UC-01（一键派梯） ✅ 需要 floorList
|
||||
└─ UC-02（调用方指定楼层） ❌ floorList 不被消费（L193 直接取 param.floorIds）
|
||||
|
||||
3. VisitorRegisterServiceImpl ← CRK 访客
|
||||
├─ L330 访客登记 ✅ 可能涉及楼层选择
|
||||
└─ L648 访客登记 ✅ 同上
|
||||
|
||||
4. AcsRecogRecordServiceImpl:86 ← CRK 门禁识别
|
||||
└─ 仅需人员信息 ❌ 完全不涉及楼层
|
||||
```
|
||||
|
||||
### 4.4 为什么设计如此
|
||||
|
||||
设计文档 [2026-05-06-tenant-visitor-policy-organization-implementation.md](./2026-05-06-tenant-visitor-policy-organization-implementation.md) 明确规定：
|
||||
|
||||
> **floorList 唯一主路径**：获取 `PersonResult.floorList`：**必须**调用 `PersonService.detail`
|
||||
> **业务约定**：凡调用方需消费「被访人可派梯/可邀约访问的楼层集合」，必须走 `PersonService.detail`
|
||||
|
||||
这一设计将 `detail()` 作为 **floorList 的权威来源**，策略替代自然应在 `detail()` 内完成。但设计未区分「需要 floorList 的调用方」和「仅需人员信息的调用方」——`detail()` 本就同时承担这两种职责。
|
||||
|
||||
### 4.5 策略命中统计
|
||||
|
||||
| 目标 orgId | 组织名 | 命中次数 | 限制楼层 | 备注 |
|
||||
|-----------|--------|---------|---------|------|
|
||||
| `f216235e...` | 星中心物业管理公司 | 12 | 6F | 物业内部人员被查询 |
|
||||
| `488b8ad0...` | [28-38F]广发基金 | 0 | 28F | 日志期间无人查询广发人员 |
|
||||
|
||||
**24 次未命中** 的 detail() 调用中，大部分是陕西巨丰投资 (a5585cb) 的人员——该组织无策略配置，但仍然触发了 `tenant_visitor_floor_policy` 表的 SELECT 查询（一次 DB 查询 + 空结果集）。
|
||||
|
||||
### 4.6 性能影响评估
|
||||
|
||||
```
|
||||
单次 detail() 调用链路:
|
||||
|
||||
DB: cw_is_person (必选)
|
||||
DB: cw_is_person_organization_ref (必选)
|
||||
DB: cw_is_person_label_ref (必选)
|
||||
Feign: elevatorFeignClient.listByImageId (必选, 跨服务调用)
|
||||
DB: tenant_visitor_floor_policy (★ 策略查询, 每次 1 次 SELECT)
|
||||
WHERE org_id=? AND enabled=1 LIMIT 1
|
||||
→ 对每个 orgId 执行，命中即停止遍历
|
||||
```
|
||||
|
||||
- 策略查询是基于 `org_id` 的索引查询（`idx_org_enabled`），单次耗时 < 5ms
|
||||
- 当前日志中 1次/分钟 的频率**无性能问题**
|
||||
- 但若 `detail()` 被大量并发调用（如批量操作、定时任务），会产生 N×orgCount 次 DB 查询
|
||||
|
||||
---
|
||||
|
||||
## 五、异常与风险
|
||||
|
||||
### 5.1 设备同步 WARN (31,800 条)
|
||||
|
||||
```
|
||||
"查询设备[xxx]失败" (DevicePersonSyncManager:164)
|
||||
|
||||
TOP 5 失败设备:
|
||||
cbbd0da12a9247409cc272e1c365698f 180 次
|
||||
508d126a19554746a46931afcc5ec9e3 180 次
|
||||
ca9d9689c8fe4ccf89eba82a9c9df4b4 120 次
|
||||
f4765e409ffd4705a2639eb41c5251c7 115 次
|
||||
7a4b5acc463d465ba4550db4939dac19 105 次
|
||||
|
||||
原因: 设备侧有注册，组织库中无对应设备 → 每次同步周期都触发查询失败
|
||||
影响: 日志膨胀（84% 为设备同步日志），掩盖真实业务问题
|
||||
建议: 清理数据库中不存在的设备记录，或对已知失败设备做静默处理
|
||||
```
|
||||
|
||||
### 5.2 Feign 调用失败 (11 次 ERROR)
|
||||
|
||||
```
|
||||
"call AggDeviceImageStoreFeignClient sync device imageStore failed"
|
||||
(Hystrix fallback, 分布在 12:49 ~ 13:18)
|
||||
|
||||
间隔: 约 1-2 分钟一次
|
||||
原因: cwos-portal 服务不可达或超时
|
||||
影响: 图库同步中断，但不影响人员查询
|
||||
```
|
||||
|
||||
### 5.3 图库添加人脸失败 (5 次 ERROR)
|
||||
|
||||
```
|
||||
"图库[c8c67225]添加人脸[1690239736450007040]异常"
|
||||
"图库[7a83a5d2]添加人脸[1611164976657559552]异常" × 4
|
||||
|
||||
集中在 13:06~13:07，为批量操作失败
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、策略优化建议
|
||||
|
||||
### 方案 A：添加调用上下文标志（推荐，最小变更）
|
||||
|
||||
在 `DetailImgPersonParam` 或 `CloudwalkCallContext` 中添加 `skipFloorPolicy` 字段：
|
||||
|
||||
```java
|
||||
// ImgPersonServiceImpl.detail() L670 修改为:
|
||||
if (!Boolean.TRUE.equals(param.getSkipFloorPolicy())) {
|
||||
Optional<List<String>> replacementFloors =
|
||||
this.tenantVisitorFloorPolicyService
|
||||
.replacementZoneIdsIfPolicyActive(result.getOrganizationIds());
|
||||
// ... 现有替换逻辑
|
||||
}
|
||||
```
|
||||
|
||||
**优点**: 调用方显式控制，不破坏现有契约
|
||||
**缺点**: 需要所有「不需要策略」的调用方传参（addVisitor UC-02、门禁识别、人员管理等）
|
||||
|
||||
### 方案 B：策略仅在 isVisitor 场景触发
|
||||
|
||||
```java
|
||||
// 仅在访客相关场景触发策略
|
||||
if (Boolean.TRUE.equals(param.getIsVisitor())) {
|
||||
// 策略检查
|
||||
}
|
||||
```
|
||||
|
||||
**优点**: 改动最小，一行条件判断
|
||||
**缺点**: isVisitor 可能不是当前 detail() 的必有参数
|
||||
|
||||
### 方案 C：保持现状（设计意图）
|
||||
|
||||
按照设计文档，`detail()` 是 floorList 的**权威来源**，策略嵌入是**有意为之**。当前 ~1次/分钟 的调用频率下，额外的 DB 查询成本可忽略。
|
||||
|
||||
**优点**: 零改动
|
||||
**缺点**: 语义不精确，所有 detail() 消费者都触发策略查询
|
||||
|
||||
---
|
||||
|
||||
## 七、数据库查询结果附录
|
||||
|
||||
### 7.1 策略表全量
|
||||
|
||||
```sql
|
||||
SELECT p.id, p.org_id, o.NAME, p.allow_zone_ids, p.remark
|
||||
FROM tenant_visitor_floor_policy p
|
||||
LEFT JOIN cw_is_organization o ON p.org_id = o.ID
|
||||
WHERE p.enabled=1;
|
||||
```
|
||||
|
||||
| policyId | org_name | allow_zone_ids | 限制楼层 |
|
||||
|----------|---------|---------------|---------|
|
||||
| pm_6f_vstr_policy_006 | 星中心物管公司 | ["605560541473144832"] | 6F |
|
||||
| pm_6f_vstr_policy_001 | 星河湾物业管理有限公司 | ["605560541473144832"] | 6F |
|
||||
| pm_6f_vstr_policy_005 | 星中心物业服务中心 | ["605560541473144832"] | 6F |
|
||||
| pm_6f_vstr_policy_003 | 星河湾物管公司 | ["605560541473144832"] | 6F |
|
||||
| pm_6f_vstr_policy_007 | 物业管理总部 | ["605560541473144832"] | 6F |
|
||||
| pm_6f_vstr_policy_004 | **星中心物业管理公司** | ["605560541473144832"] | **6F** ← 日志命中 |
|
||||
| pm_6f_vstr_policy_002 | 星河湾物业管理公司 | ["605560541473144832"] | 6F |
|
||||
| gf_vstr_policy_guangfa_fund_001x | [28-38F]广发基金管理有限公司 | ["605560545117995008"] | 28F |
|
||||
| demo_vstr_policy_001 | 演示公司 | ["605560545117995008"] | 28F |
|
||||
|
||||
### 7.2 楼层编码对照
|
||||
|
||||
```
|
||||
zone_id=605560540432957440 code=0x01 → 1F (首层)
|
||||
zone_id=605560541473144832 code=0x06 → 6F ★ 物业策略目标
|
||||
zone_id=605560545117995008 code=0x1C → 28F ★ 广发基金策略目标
|
||||
```
|
||||
|
||||
### 7.3 关键组织节点
|
||||
|
||||
```
|
||||
f216235e54ca42bfa0379e69b3754aff = 星中心物业管理公司 (PARENT_ORG)
|
||||
├── 348328d755624b3491cd307a3109f36a = 星中心物管公司
|
||||
├── b39c54d13fe94abe84bfa8d527db4392 = 星中心保安部
|
||||
├── f113340e671648338eb83fc643cfa94d = 星中心环境管理部
|
||||
│ └── 8498d4a56f07494ca604789d23fc18f6 = 星中心环境部外包人员
|
||||
└── df573ae4b98f4be092d524b760bd5c40 = 星景厨房
|
||||
|
||||
a5585cb03764490c915ee807aaa13ef3 = 陕西巨丰投资资讯有限责任公司广州分公司
|
||||
├── b3b5fe629baf45b29a1eb6ed8e7126d8 = 业务部
|
||||
├── 363742435e3f4dc1b4626819e8637de2 = 行政人事部
|
||||
├── 4758f34c67364c4c8f6f6c8eb9a4af13 = 新媒体
|
||||
├── 480bd6c8b49b49568f7a5ee07331a084 = 投资助理
|
||||
├── 768aa5ef294d4fdc979e1c5a37cb87e7 = 财务/数据/推广
|
||||
└── e84e681fa6c8463c90f70082cd4bed77 = 大客户服务部
|
||||
|
||||
488b8ad049bb43408a6fbcc50bcb89ac = [28-38F]广发基金管理有限公司 (有策略但未被查询)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、总结
|
||||
|
||||
1. **日志主体是设备同步**（84.2%），用户业务调用仅占 0.06%
|
||||
2. **策略调用频率**: 36 次/37 分钟 ≈ 1 次/分钟，频率不高但覆盖所有 detail() 调用方
|
||||
3. **根因**: `detail()` 是 floorList 的权威来源（设计意图），策略嵌入是**有意为之**；但 detail() 被 7+ 个不同调用方消费，其中仅 3 个需要策略
|
||||
4. **是否可以优化**: 可以，但需要改动调用方契约（添加 skip 标志）或在 detail() 内根据业务特征判断。当前频率下保持现状是可接受的
|
||||
5. **31,800 条 WARN**: 设备同步失败是主要噪音源，建议清理不存在设备的记录
|
||||
@@ -0,0 +1,351 @@
|
||||
# 楼层策略触发优化：仅访客邀约场景执行策略
|
||||
|
||||
**日期**: 2026-05-10
|
||||
**状态**: 方案评估（未实施）
|
||||
**关联**: [component-org 日志分析](./2026-05-10-component-org-log-analysis.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、问题定义
|
||||
|
||||
### 1.1 现象
|
||||
|
||||
`TenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive()` 被嵌入 `ImgPersonServiceImpl.detail()` L670-672，导致**所有**调用 `POST /component/person/detail` 的请求都触发策略 DB 查询，而非仅访客邀约场景。
|
||||
|
||||
### 1.2 根因
|
||||
|
||||
`detail()` 是通用人员详情 API，被 7 个不同调用方消费，策略代码无条件嵌入其中，无法区分调用方意图：
|
||||
|
||||
```
|
||||
POST /component/person/detail ← 唯一入口，无法区分调用方
|
||||
├─ 访客邀约页 ✅ 需要策略 → 当前正确
|
||||
├─ 人员管理详情 ❌ 不需要 → 多余 DB 查询
|
||||
├─ addVisitor UC-01 ✅ 需要策略 → 当前正确
|
||||
├─ addVisitor UC-02 ❌ 不需要 → 多余 DB 查询（不消费 floorList）
|
||||
├─ CRK 访客注册 ✅ 需要策略 → 当前正确
|
||||
├─ CRK 门禁识别 ❌ 不需要 → 多余 DB 查询
|
||||
└─ 电梯设备同步 ❌ 不需要 → 多余 DB 查询
|
||||
```
|
||||
|
||||
### 1.3 影响评估
|
||||
|
||||
| 指标 | 当前值 | 评估 |
|
||||
|------|--------|------|
|
||||
| 调用频率 | ~1 次/分钟 | 低，无性能风险 |
|
||||
| 策略查询耗时 | < 5ms（索引查询） | 可忽略 |
|
||||
| 多余调用占比 | ~60%（7 个调用方中 4 个不需要） | 架构不精确 |
|
||||
|
||||
**结论**：当前频率下无性能问题，但架构语义不精确，需要优化。
|
||||
|
||||
---
|
||||
|
||||
## 二、方案评估
|
||||
|
||||
### 2.1 涉及的关键代码路径
|
||||
|
||||
```
|
||||
┌─ interface 层 ───────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ DetailImgPersonParam (component-organization-interface) │
|
||||
│ public class DetailImgPersonParam { │
|
||||
│ private String id; │
|
||||
│ private String businessId; │
|
||||
│ } │
|
||||
│ │
|
||||
│ PersonDetailParam (intelligent-cwoscomponent-interface) │
|
||||
│ public class PersonDetailParam implements Serializable { │
|
||||
│ private String id; │
|
||||
│ private String businessId; │
|
||||
│ } │
|
||||
└───────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─ 服务层 ─────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ ImgPersonServiceImpl.detail() L670-672: │
|
||||
│ Optional<List<String>> replacementFloors = │
|
||||
│ this.tenantVisitorFloorPolicyService │
|
||||
│ .replacementZoneIdsIfPolicyActive( │
|
||||
│ result.getOrganizationIds()); │
|
||||
│ │
|
||||
│ PersonRuleServiceImpl.addVisitor() L172-175: │
|
||||
│ PersonDetailParam detailParam = new PersonDetailParam(); │
|
||||
│ detailParam.setId(param.getPersonId()); │
|
||||
│ detailParam.setBusinessId(context.getCompany().getCompanyId()); │
|
||||
│ CloudwalkResult<PersonResult> detailResult = │
|
||||
│ this.personService.detail(detailParam, context); │
|
||||
└───────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方案 A：新增 `skipFloorPolicy` 字段（⭐ 推荐）
|
||||
|
||||
#### 改动内容
|
||||
|
||||
**Step 1**: `DetailImgPersonParam` 新增字段
|
||||
|
||||
```java
|
||||
// cwos-component-organization-interface/.../DetailImgPersonParam.java
|
||||
public class DetailImgPersonParam {
|
||||
private String id;
|
||||
private String businessId;
|
||||
private Boolean skipFloorPolicy; // ★ 新增: true=跳过策略查询
|
||||
|
||||
// getter / setter
|
||||
public Boolean getSkipFloorPolicy() {
|
||||
return skipFloorPolicy;
|
||||
}
|
||||
public void setSkipFloorPolicy(Boolean skipFloorPolicy) {
|
||||
this.skipFloorPolicy = skipFloorPolicy;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2**: `PersonDetailParam` 新增字段
|
||||
|
||||
```java
|
||||
// intelligent-cwoscomponent-interface/.../PersonDetailParam.java
|
||||
public class PersonDetailParam implements Serializable {
|
||||
private String id;
|
||||
private String businessId;
|
||||
private Boolean skipFloorPolicy; // ★ 新增
|
||||
// getter / setter
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3**: `ImgPersonServiceImpl.detail()` 加条件判断
|
||||
|
||||
```java
|
||||
// L670 修改前:
|
||||
Optional<List<String>> replacementFloors =
|
||||
this.tenantVisitorFloorPolicyService.replacementZoneIdsIfPolicyActive(
|
||||
result.getOrganizationIds());
|
||||
|
||||
// L670 修改后:
|
||||
Optional<List<String>> replacementFloors = Optional.empty();
|
||||
if (!Boolean.TRUE.equals(param.getSkipFloorPolicy())) {
|
||||
replacementFloors = this.tenantVisitorFloorPolicyService
|
||||
.replacementZoneIdsIfPolicyActive(result.getOrganizationIds());
|
||||
}
|
||||
if (replacementFloors.isPresent()) {
|
||||
// ... 现有替换逻辑不变
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4**: elevator 侧 addVisitor UC-02 显式跳过
|
||||
|
||||
```java
|
||||
// PersonRuleServiceImpl.addVisitor() L172 之后加:
|
||||
PersonDetailParam detailParam = new PersonDetailParam();
|
||||
detailParam.setId(param.getPersonId());
|
||||
detailParam.setBusinessId(context.getCompany().getCompanyId());
|
||||
|
||||
// ★ UC-02: 调用方已显式指定楼层，无需策略查询
|
||||
if (!CollectionUtils.isEmpty(param.getFloorIds())) {
|
||||
detailParam.setSkipFloorPolicy(true);
|
||||
}
|
||||
|
||||
CloudwalkResult<PersonResult> detailResult =
|
||||
this.personService.detail(detailParam, context);
|
||||
```
|
||||
|
||||
#### 改动总结
|
||||
|
||||
| 文件 | 改动 | 行数 |
|
||||
|------|------|------|
|
||||
| `DetailImgPersonParam.java` | 新增 `skipFloorPolicy` 字段 | +5 |
|
||||
| `PersonDetailParam.java` | 新增 `skipFloorPolicy` 字段 | +5 |
|
||||
| `ImgPersonServiceImpl.java` | L670 条件判断包裹 | +3 |
|
||||
| `PersonRuleServiceImpl.java` | addVisitor UC-02 传参 | +3 |
|
||||
| **合计** | **4 文件，~16 行** | |
|
||||
|
||||
#### 评估
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 改动量 | ★★★★★ 极小（4 文件，~16 行） |
|
||||
| 向后兼容 | ✅ `Boolean` 默认 null/false = 策略执行，与当前行为一致 |
|
||||
| 语义精确性 | ✅ 调用方显式声明意图，类型安全 |
|
||||
| 可测试性 | ✅ 可写单测验证 `skipFloorPolicy=true` 时不走策略 |
|
||||
| 渐进式 | ✅ 不传参的调用方行为不变，后续按需传 `true` |
|
||||
| Feign 兼容 | ✅ Feign 序列化自动支持 Boolean 字段 |
|
||||
| 风险 | 低：interface 层加字段不破坏契约 |
|
||||
|
||||
---
|
||||
|
||||
### 方案 B：利用 CloudwalkCallContext.notes 隐式传参（不推荐）
|
||||
|
||||
```java
|
||||
// elevator 侧:
|
||||
context.getNotes().put("skipFloorPolicy", "true");
|
||||
|
||||
// ImgPersonServiceImpl 侧:
|
||||
Map<String, String> notes = context.getNotes();
|
||||
boolean skip = "true".equalsIgnoreCase(notes.get("skipFloorPolicy"));
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 改动量 | ★★★★★ 仅改 service 层 |
|
||||
| 语义精确性 | ❌ 隐式语义，字符串 key，无类型安全 |
|
||||
| 可发现性 | ❌ 调用方无法从 API 签名得知此能力 |
|
||||
| 可维护性 | ❌ key 拼写错误 → 静默失败，难以排查 |
|
||||
| 风险 | 中：notes 是 Map<String,String>，无编译期检查 |
|
||||
|
||||
---
|
||||
|
||||
### 方案 C：拆分为独立端点（不可行）
|
||||
|
||||
```
|
||||
POST /component/person/detail → 不执行策略
|
||||
POST /component/person/detail/visitor → 执行策略
|
||||
```
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 语义精确性 | ✅ URL 级区分 |
|
||||
| 改动量 | ❌ 大：新增 Controller + Service 方法 |
|
||||
| 约束冲突 | ❌ 违反"对外接口不可扩展"原则 |
|
||||
| 代码重复 | ❌ detail() 体量大（100+ 行），拆分造成重复 |
|
||||
|
||||
---
|
||||
|
||||
### 方案 D：保持现状
|
||||
|
||||
| 维度 | 评价 |
|
||||
|------|------|
|
||||
| 改动量 | 零 |
|
||||
| 性能影响 | 策略查询 < 5ms，当前频率 ~1次/分钟，可忽略 |
|
||||
| 设计意图 | 设计文档规定 detail() 是 floorList 唯一权威来源 |
|
||||
|
||||
---
|
||||
|
||||
## 三、推荐结论
|
||||
|
||||
### 采用方案 A：新增 `skipFloorPolicy` 字段
|
||||
|
||||
**理由**：
|
||||
1. **改动最小**：4 文件 ~16 行，不破坏任何现有契约
|
||||
2. **语义明确**：字段名自解释，调用方显式声明意图
|
||||
3. **向后兼容**：默认 null = 策略执行，不传参的调用方行为不变
|
||||
4. **渐进优化**：后续 CRK、前端等调用方可按需传入 `skipFloorPolicy=true`
|
||||
5. **符合约束**：不新增接口，不改变语义，仅扩展参数
|
||||
|
||||
### 优化效果预估
|
||||
|
||||
| 调用方 | 当前行为 | 优化后 | 策略查询减少 |
|
||||
|--------|---------|--------|-------------|
|
||||
| 前端访客邀约 | ✅ 执行策略 | 不变 | — |
|
||||
| 前端人员管理 | ❌ 多余查询 | skipFloorPolicy=true | ✅ 消除 |
|
||||
| addVisitor UC-01 | ✅ 执行策略 | 不变 | — |
|
||||
| addVisitor UC-02 | ❌ 多余查询 | skipFloorPolicy=true | ✅ 消除 |
|
||||
| CRK 访客注册 | ✅ 执行策略 | 不变 | — |
|
||||
| CRK 门禁识别 | ❌ 多余查询 | skipFloorPolicy=true（后续） | ✅ 消除 |
|
||||
| 电梯设备同步 | ❌ 多余查询 | skipFloorPolicy=true（后续） | ✅ 消除 |
|
||||
|
||||
**预估**：elevator addVisitor UC-02 优化立即生效，后续逐步覆盖其他调用方，最终减少约 60% 的无意义策略查询。
|
||||
|
||||
### 实施顺序
|
||||
|
||||
```
|
||||
Phase 1（核心优化）:
|
||||
1. DetailImgPersonParam + skipFloorPolicy 字段
|
||||
2. PersonDetailParam + skipFloorPolicy 字段
|
||||
3. ImgPersonServiceImpl.detail() 加条件判断
|
||||
4. PersonRuleServiceImpl.addVisitor() UC-02 传参
|
||||
|
||||
Phase 2（渐进覆盖）:
|
||||
5. 前端人员管理 → skipFloorPolicy=true
|
||||
6. CRK 门禁识别 → skipFloorPolicy=true
|
||||
7. 电梯设备同步 → skipFloorPolicy=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、附录：完整改动预览
|
||||
|
||||
### 4.1 DetailImgPersonParam.java
|
||||
|
||||
```java
|
||||
public class DetailImgPersonParam {
|
||||
private String id;
|
||||
private String businessId;
|
||||
private Boolean skipFloorPolicy;
|
||||
|
||||
// ... 原有 getter/setter ...
|
||||
|
||||
public Boolean getSkipFloorPolicy() {
|
||||
return skipFloorPolicy;
|
||||
}
|
||||
|
||||
public void setSkipFloorPolicy(Boolean skipFloorPolicy) {
|
||||
this.skipFloorPolicy = skipFloorPolicy;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 PersonDetailParam.java
|
||||
|
||||
```java
|
||||
public class PersonDetailParam implements Serializable {
|
||||
private static final long serialVersionUID = 7666677873099106082L;
|
||||
|
||||
private String id;
|
||||
private String businessId;
|
||||
private Boolean skipFloorPolicy;
|
||||
|
||||
// ... 原有 getter/setter ...
|
||||
|
||||
public Boolean getSkipFloorPolicy() {
|
||||
return skipFloorPolicy;
|
||||
}
|
||||
|
||||
public void setSkipFloorPolicy(Boolean skipFloorPolicy) {
|
||||
this.skipFloorPolicy = skipFloorPolicy;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 ImgPersonServiceImpl.java L667-685
|
||||
|
||||
```java
|
||||
int rawFloorCount = floorList.size();
|
||||
this.logger.info("[DETAIL] personId={} listByImageId returned {} zones: {}",
|
||||
param.getId(), rawFloorCount, floorList);
|
||||
|
||||
// ★ 仅当未显式跳过策略时才执行策略查询
|
||||
Optional<List<String>> replacementFloors = Optional.empty();
|
||||
if (!Boolean.TRUE.equals(param.getSkipFloorPolicy())) {
|
||||
replacementFloors = this.tenantVisitorFloorPolicyService
|
||||
.replacementZoneIdsIfPolicyActive(result.getOrganizationIds());
|
||||
}
|
||||
|
||||
if (replacementFloors.isPresent()) {
|
||||
List<String> beforeReplacement = new ArrayList<>(floorList);
|
||||
floorList = new ArrayList<>(replacementFloors.get());
|
||||
zoneNames = buildCommaSeparatedFloorNames(businessId, floorList);
|
||||
this.logger.info("[DETAIL-POLICY] personId={} orgIds={} floorList REPLACED: {}→{}",
|
||||
param.getId(), result.getOrganizationIds(), beforeReplacement, floorList);
|
||||
} else {
|
||||
this.logger.debug("[DETAIL-POLICY] personId={} orgIds={} {}",
|
||||
param.getId(), result.getOrganizationIds(),
|
||||
Boolean.TRUE.equals(param.getSkipFloorPolicy())
|
||||
? "policy skipped by caller" : "no policy matched, using raw floorList");
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 PersonRuleServiceImpl.java L172-175
|
||||
|
||||
```java
|
||||
PersonDetailParam detailParam = new PersonDetailParam();
|
||||
detailParam.setId(param.getPersonId());
|
||||
detailParam.setBusinessId(context.getCompany().getCompanyId());
|
||||
|
||||
// UC-02: 调用方已显式指定 floorIds，此时 floorList 不被消费，跳过策略查询
|
||||
if (!CollectionUtils.isEmpty(param.getFloorIds())) {
|
||||
detailParam.setSkipFloorPolicy(true);
|
||||
}
|
||||
|
||||
CloudwalkResult<PersonResult> detailResult =
|
||||
this.personService.detail(detailParam, context);
|
||||
```
|
||||
Reference in New Issue
Block a user