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

Initial commit: reorganized source tree

Browse Source 
- 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.
This commit is contained in:
hpd840321
2026-05-09 09:00:12 +08:00
commit 7b2bd307f1
7260 changed files with 612980 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/Maven工作区子工程版本一览.md
+279
View File
@@ -0,0 +1,279 @@
# Maven 工作区子工程版本一览
> **范围**：`/media/zebra/9e8fa357-7db6-4d70-88ed-d5de5a059a663/星河湾星中星/反编译` 下 `maven-*` 目录内全部 `pom.xml`（**主聚合工程 5 个 + 补充反应堆 7 个**，合计 **44** 个 `pom.xml` 文件）。
> **说明**：子模块未单独声明 `<version>` 时，与**反应堆（reactor）父 POM** 的 `<version>` 一致。
> **生成方式**：走查各 `pom.xml` 的 `parent`、`groupId`、`artifactId`、`version`、`properties` 关键项。
> **版本演进（主版本升级）**：相对历史反编译/私服线，本工作区多工程坐标抬升主版本号以便区分。**电梯运行口径**：依赖 **`intelligent-cwoscomponent` 2.9.2-xinghewan**（与 `cw_lib` 一致，**不使用** 3.0.0）；**`maven-intelligent-cwoscomponent` 源码反应堆** 仍为 **3.0.0-xinghewan**（与其它工程/历史 3.x 线兼容）。另：cloudwalk-cloud **4.0.0-Brussels-SRX**、ninca-crk **2.0.0**、ninca-qk-alarm **1.0.0-SNAPSHOT**。
---
## 1. 聚合工程总表
### 1.1 主链（业务五工程）
| 工程目录 | 反应堆 `groupId` | 反应堆 `artifactId` | **工程版本** | **Spring Boot parent** | Spring Cloud（属性） |
|----------|------------------|----------------------|--------------|------------------------|----------------------|
| `maven-cw-elevator-application/` | `cn.cloudwalk.elevator` | `cw-elevator-application-reactor` | **`2.0-SNAPSHOT`** | `2.1.18.RELEASE` | 见反应堆 `pom.xml`（与 Boot 2.1 栈配套） |
| `maven-intelligent-cwoscomponent/` | `cn.cloudwalk.intelligent` | `intelligent-cwoscomponent-reactor` | **`3.0.0-xinghewan`** | `2.1.18.RELEASE` | **`Greenwich.SR6`**（`${spring-cloud.version}`） |
| `maven-cloudwalk-cloud/` | `cn.cloudwalk.cloud` | `cloudwalk-cloud-reactor` | **`4.0.0-Brussels-SRX`** | `2.1.18.RELEASE` | **`Greenwich.SR6`** |
| `maven-ninca-crk/` | `cn.cloudwalk.ninca` | `ninca-crk-reactor` | **`2.0.0`** | **`1.5.22.RELEASE`** | **`Edgware.SR6`** |
| `maven-ninca-qk-alarm/` | `cn.cloudwalk.ninca` | `ninca-qk-alarm-reactor` | **`1.0.0-SNAPSHOT`** | `2.1.18.RELEASE` | （反应堆未统一声明 spring-cloud BOM，以依赖为准） |
### 1.2 补充反应堆（私服缺父 POM 时本地 install）
| 工程目录 | 反应堆 / 父 `artifactId` | 版本 | 说明 |
|----------|---------------------------|------|------|
| `maven-cloudwalk-device-sdk/` | `cloudwalk-device-sdk`（`cn.cloudwalk`） | **`2.2.0`** | 子模块 **`cloudwalk-device-sdk-protocol-entity`**；与 intelligent 中 **`cloudwalk.device.sdk.version`** 一致。 |
| `maven-cloudwalk-device-manager/` | `cloudwalk-device-manager`（`cn.cloudwalk.cloud`） | **`2.0.2`** | 子模块 **`cloudwalk-device-manager-common`**、**`cloudwalk-device-manager-interface`**；依赖 **`cloudwalk-common-result:3.7.2-Brussels-SRX`**（须先 **`maven-cloudwalk-legacy-public`**）。 |
| `maven-cloudwalk-legacy-public/` | `cloudwalk-legacy-public-reactor`（`cn.cloudwalk.cloud`） | **`1.0.0-SNAPSHOT`** | 安装 **`cloudwalk-cloud-common:3.7.2-Brussels-SRX`**、**`cloudwalk-common-result`/`web`/`serial`**、**`cwos-sdk-event:1.5.0-SNAPSHOT`**、**`cloudwalk-intelligent-component-lock:1.1.1-SNAPSHOT`**；源码来自 **`反1/*.jar.src.zip`**。 |
| `maven-cwos-resource/` | `cwos-resource-reactor`（`cn.cloudwalk.cloud`） | **`1.0.0-SNAPSHOT`** | 含 **`cwos-component-resource`**、**`cwos-portal`** 父 POM、**`cwos-java-sdk-resource`**、**`cwos-device-pkg-stub`** 等；与电梯 **`cwos.sdk.resource.version`** 对齐。 |
| `maven-cloudwalk-intelligent-davinci-manager/` | `cloudwalk-intelligent-davinci-manager`（`cn.cloudwalk.intelligent`） | **`1.1.7-SNAPSHOT`** | 子模块 **`davinci-manager-common`**、**`davinci-manager-storage`**；与电梯 **`davinci.manager.storage.version`** 一致。 |
| `maven-cwos-common-aks/` | **`cwos-common-aks`**（`cn.cloudwalk.cloud`） | **`1.0.0-SNAPSHOT`** | 子模块 **`cwos-common-aks-interface`**；与 **`cw_lib`** / **`反1`** 对齐；须先 **`maven-cloudwalk-legacy-public`**（**`cloudwalk-common-result`**）。 |
| `maven-cwos-device-authentication/` | **`cwos-device-authentication`**（`cn.cloudwalk.cloud`） | **`1.0.0-SNAPSHOT`** | 子模块 **`cwos-device-authentication-interface`**；依赖 **device-sdk**、**device-manager**、**`maven-cloudwalk-cloud`**（**`cloudwalk-common-service`**）、**`cwos-common-aks-interface`**；须在 **`maven-cwos-common-aks`** 与 **`maven-cloudwalk-cloud`** 之后 install。 |
---
## 2. 按工程展开：子模块坐标与版本
### 2.1 `maven-cw-elevator-application`（电梯应用）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cw-elevator-application-reactor` | **2.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cw-elevator-application-common/` | `cw-elevator-application-common` | **2.0-SNAPSHOT**（继承） | `cw-elevator-application-reactor` |
| `cw-elevator-application-data/` | `cw-elevator-application-data` | **2.0-SNAPSHOT**（继承） | 同上 |
| `cw-elevator-application-service/` | `cw-elevator-application-service` | **2.0-SNAPSHOT**（继承） | 同上 |
| `cw-elevator-application-web/` | `cw-elevator-application-web` | **2.0-SNAPSHOT**（继承） | 同上 |
**反应堆内常用属性（节选）**：`cloudwalk.internal.version` / `cloudwalk.legacy.public.version` **3.7.2-Brussels-SRX**；`intelligent.cwoscomponent.version` **2.9.2-xinghewan**（与 **`cw_lib`** / 上线口径一致）；`fastjson.version` **1.2.73**；`guava.version` **28.2-jre**；`poi.version` **4.1.2**；`java.version` **1.8**。
---
### 2.2 `maven-intelligent-cwoscomponent`（CWOS 智能组件）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `intelligent-cwoscomponent-reactor` | **3.0.0-xinghewan** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `intelligent-cwoscomponent-parent/` | `intelligent-cwoscomponent` | **3.0.0-xinghewan** | `spring-boot-starter-parent` **2.1.18.RELEASE**（**stub parent**，`packaging`=`pom`，与私服 JAR 声明的 parent 对齐） |
| `intelligent-cwoscomponent-interface/` | `intelligent-cwoscomponent-interface` | **3.0.0-xinghewan**（继承） | `intelligent-cwoscomponent-reactor` |
| `intelligent-cwoscomponent-rest/` | `intelligent-cwoscomponent-rest` | **3.0.0-xinghewan**（继承） | `intelligent-cwoscomponent-reactor` |
**反应堆内常用属性（节选）**：`spring-cloud.version` **Greenwich.SR6**；`cloudwalk.internal.version` **4.0.0-Brussels-SRX**；`cloudwalk.device.sdk.version` **2.2.0**；`fastjson.version` **1.2.83**。
---
### 2.3 `maven-cloudwalk-cloud`（云从 cloud 公共）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cloudwalk-cloud-reactor` | **4.0.0-Brussels-SRX** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cloudwalk-cloud-common/` | `cloudwalk-cloud-common` | **4.0.0-Brussels-SRX** | `spring-boot-starter-parent` **2.1.18.RELEASE**（**stub parent**，`packaging`=`pom`） |
| `cloudwalk-common-event/` | `cloudwalk-common-event` | **4.0.0-Brussels-SRX**（继承） | `cloudwalk-cloud-reactor` |
| `cloudwalk-common-service/` | `cloudwalk-common-service` | **4.0.0-Brussels-SRX**（继承） | `cloudwalk-cloud-reactor` |
**反应堆内常用属性（节选）**：`spring-cloud.version` **Greenwich.SR6**；`cwos.sdk.event.version` **1.5.0-SNAPSHOT**；`cloudwalk.internal.version` **4.0.0-Brussels-SRX**。
---
### 2.4 `maven-ninca-crk`（轻舟 CRK）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `ninca-crk-reactor` | **2.0.0** | `spring-boot-starter-parent` **1.5.22.RELEASE** |
| `ninca-crk-gpu-std/` | `ninca-crk-gpu-std` | **2.0.0**（继承） | `ninca-crk-reactor` |
**反应堆内常用属性（节选）**：`spring-cloud.version` **Edgware.SR6**；`cloudwalk.internal.version` **4.0.0-Brussels-SRX**；`intelligent.cwoscomponent.rest.version` **3.0.0-xinghewan**；`ninca-crk-*` 多模块 **2.9.1_210630-SNAPSHOT**；`mybatis-spring-boot.version` **1.3.5**。
---
### 2.5 `maven-ninca-qk-alarm`（区域告警应用）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `ninca-qk-alarm-reactor` | **1.0.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `ninca-qk-alarm-app-starter/` | `ninca-qk-alarm-app-starter` | **1.0.0-SNAPSHOT**（继承） | `ninca-qk-alarm-reactor` |
**反应堆内常用属性（节选）**：`cloudwalk.internal.version` **4.0.0-Brussels-SRX**；`curator.version` **4.2.0**；`zookeeper.version` **3.4.14**；`mybatis-spring-boot.version` **2.0.1**。
---
### 2.6 `maven-cloudwalk-device-sdk`（设备 SDK 父链）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cloudwalk-device-sdk` | **2.2.0** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cloudwalk-device-sdk-protocol-entity/` | `cloudwalk-device-sdk-protocol-entity` | **2.2.0**（继承） | `cloudwalk-device-sdk`（`../pom.xml`） |
---
### 2.6b `maven-cloudwalk-device-manager`（设备管理 common / interface）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cloudwalk-device-manager` | **2.0.2** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cloudwalk-device-manager-common/` | `cloudwalk-device-manager-common` | **2.0.2**（继承） | `cloudwalk-device-manager`（`../pom.xml`） |
| `cloudwalk-device-manager-interface/` | `cloudwalk-device-manager-interface` | **2.0.2**（继承） | `cloudwalk-device-manager`（`../pom.xml`） |
**反应堆内常用属性（节选）**：`cloudwalk.common.result.version` **3.7.2-Brussels-SRX**（与 **`maven-cloudwalk-legacy-public`** 中 **`cloudwalk-common-result`** 一致）。
---
### 2.7 `maven-cwos-resource`（CWOS 资源 / 门户 / SDK）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cwos-resource-reactor` | **1.0.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cwos-component-resource/` | `cwos-component-resource` | **1.0.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cwos-component-resource-data/` | `cwos-component-resource-data` | **1.0.0-SNAPSHOT**（继承） | `cwos-component-resource` |
| `cwos-component-resource-interface/` | `cwos-component-resource-interface` | **1.0.0-SNAPSHOT**（继承） | `cwos-component-resource` |
| `cwos-device-pkg-stub/` | `cwos-device-pkg-stub` | **1.0.0-SNAPSHOT**（继承） | `cwos-resource-reactor` |
| `cwos-portal/` | `cwos-portal` | **1.0.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cwos-portal-interface/` | `cwos-portal-interface` | **1.0.0-SNAPSHOT**（继承） | `cwos-portal` |
| `cwos-java-sdk-resource/` | `cwos-java-sdk-resource` | **1.0.0-SNAPSHOT**（继承） | `cwos-resource-reactor` |
**反应堆内常用属性（节选）**：`spring-cloud.version` **Greenwich.SR6**；`cloudwalk.legacy.public.version` **3.7.2-Brussels-SRX**；`mybatis.version` **3.5.6**。
---
### 2.8 `maven-cloudwalk-intelligent-davinci-manager`（Davinci 存储）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cloudwalk-intelligent-davinci-manager` | **1.1.7-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `davinci-manager-common/` | `davinci-manager-common` | **1.1.7-SNAPSHOT**（继承） | `cloudwalk-intelligent-davinci-manager`（`../pom.xml`） |
| `davinci-manager-storage/` | `davinci-manager-storage` | **1.1.7-SNAPSHOT**（继承） | `cloudwalk-intelligent-davinci-manager`（`../pom.xml`） |
**反应堆内常用属性（节选）**：`spring-cloud.version` **Greenwich.SR6**；`feign-form.version` **3.0.3**；`commons-io.version` **2.5**。
---
### 2.9 `maven-cloudwalk-legacy-public`（反1 公共线）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cloudwalk-legacy-public-reactor` | **1.0.0-SNAPSHOT** | （无 Spring parent，聚合 `pom`） |
| `cloudwalk-cloud-common/` | `cloudwalk-cloud-common` | **3.7.2-Brussels-SRX** | `spring-boot-starter-parent` **1.5.22.RELEASE** |
| `cloudwalk-common-result/` | `cloudwalk-common-result` | **3.7.2-Brussels-SRX**（继承） | `cloudwalk-cloud-common` |
| `cloudwalk-common-web/` | `cloudwalk-common-web` | **3.7.2-Brussels-SRX**（继承） | `cloudwalk-cloud-common` |
| `cloudwalk-common-serial/` | `cloudwalk-common-serial` | **3.7.2-Brussels-SRX**（继承） | `cloudwalk-cloud-common` |
| `cwos-sdk-event/` | `cwos-sdk-event` | **1.5.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cloudwalk-intelligent-component-lock/` | `cloudwalk-intelligent-component-lock` | **1.1.1-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
---
### 2.10 `maven-cwos-common-aks`（AKS 公共接口）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cwos-common-aks` | **1.0.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cwos-common-aks-interface/` | `cwos-common-aks-interface` | **1.0.0-SNAPSHOT**（继承） | `cwos-common-aks`（`../pom.xml`） |
**反应堆内常用属性（节选）**：`cloudwalk.legacy.public.version` **3.7.2-Brussels-SRX**；`fastjson.version` **1.2.83**。
---
### 2.11 `maven-cwos-device-authentication`（设备认证 interface）
| 模块路径 | `artifactId` | 版本 | 父 POM |
|----------|----------------|------|--------|
| 根 | `cwos-device-authentication` | **1.0.0-SNAPSHOT** | `spring-boot-starter-parent` **2.1.18.RELEASE** |
| `cwos-device-authentication-interface/` | `cwos-device-authentication-interface` | **1.0.0-SNAPSHOT**（继承） | `cwos-device-authentication`（`../pom.xml`） |
**反应堆内常用属性（节选）**：`cloudwalk-common.version` **3.7.2-Brussels-SRX**；`cloudwalk-device.version` **2.0.2**；`cloudwalk-aks.version` **1.0.0-SNAPSHOT**；`cloudwalk.device.sdk.version` **2.2.0**；`fastjson.version` **1.2.83**。
---
## 3. 跨工程对齐关系（便于联调）
| 概念 | 常见取值 | 出现在 |
|------|----------|--------|
| 云从内部线版本 | **3.7.2**（电梯常用） / **4.0.0**（部分工程） | 电梯、ninca-qk-alarm 等 `cloudwalk.internal.version` 多为 **3.7.2**；**cloudwalk-cloud / ninca-crk** 等仍可能 **4.0.0** |
| intelligent 组件线 | **2.9.2-xinghewan**（电梯） / **3.0.0-xinghewan**（反应堆源码、ninca-crk） | **电梯** `intelligent.cwoscomponent.version` **必须为 2.9.2**（与 `cw_lib` 一致）；**`maven-intelligent-cwoscomponent`** 反应堆仍为 **3.0.0**；**ninca-crk** `intelligent.cwoscomponent.rest.version` 多为 **3.0.0** |
| 设备 SDK 协议实体 | **2.2.0** | intelligent `cloudwalk.device.sdk.version`；**`maven-cloudwalk-device-sdk`** 反应堆版本 |
| 设备管理 common/interface | **2.0.2** | **`maven-cloudwalk-device-manager`**；依赖 **`cloudwalk-common-result` 3.7.2**（**`maven-cloudwalk-legacy-public`**） |
| AKS / 设备认证 interface | **1.0.0-SNAPSHOT** | **`maven-cwos-common-aks`**（**`cwos-common-aks-interface`**）、**`maven-cwos-device-authentication`**（**`cwos-device-authentication-interface`**）；与 **`cw_lib`** 同名 JAR 对齐；**device-authentication** 另依赖 **`cloudwalk-common-service`**（**`maven-cloudwalk-cloud`**）、**device-manager-interface**、**protocol-entity** |
| CWOS Java SDK 资源 | **1.0.0-SNAPSHOT** | 电梯 `cwos.sdk.resource.version`；**`maven-cwos-resource`** 中 **`cwos-java-sdk-resource`** 等 |
| Davinci 存储 | **1.1.7-SNAPSHOT** | 电梯 `davinci.manager.storage.version`；**`maven-cloudwalk-intelligent-davinci-manager`** 中 **`davinci-manager-storage`** |
| 反1 公共线（legacy） | **3.7.2 / 1.5.0-SNAPSHOT / 1.1.1-SNAPSHOT** | **`maven-cloudwalk-legacy-public`**：`common-result`/`web`/`serial`、`cwos-sdk-event`、`component-lock`；与 **`cloudwalk.legacy.public.version`**、**`cwos.sdk.event.version`**、**`intelligent.lock.version`** 对齐 |
| Spring Boot 主线 | **2.1.18.RELEASE** | 电梯、intelligent、cloudwalk-cloud、ninca-qk-alarm |
| Spring Boot 旧线 | **1.5.22.RELEASE** | **仅 ninca-crk** |
---
## 4. `pom.xml` 物理路径清单（44）
```
maven-cloudwalk-cloud/pom.xml
maven-cloudwalk-cloud/cloudwalk-cloud-common/pom.xml
maven-cloudwalk-cloud/cloudwalk-common-event/pom.xml
maven-cloudwalk-cloud/cloudwalk-common-service/pom.xml
maven-cloudwalk-device-sdk/pom.xml
maven-cloudwalk-device-sdk/cloudwalk-device-sdk-protocol-entity/pom.xml
maven-cloudwalk-device-manager/pom.xml
maven-cloudwalk-device-manager/cloudwalk-device-manager-common/pom.xml
maven-cloudwalk-device-manager/cloudwalk-device-manager-interface/pom.xml
maven-cloudwalk-legacy-public/pom.xml
maven-cloudwalk-legacy-public/cloudwalk-cloud-common/pom.xml
maven-cloudwalk-legacy-public/cloudwalk-common-result/pom.xml
maven-cloudwalk-legacy-public/cloudwalk-common-web/pom.xml
maven-cloudwalk-legacy-public/cloudwalk-common-serial/pom.xml
maven-cloudwalk-legacy-public/cwos-sdk-event/pom.xml
maven-cloudwalk-legacy-public/cloudwalk-intelligent-component-lock/pom.xml
maven-cloudwalk-intelligent-davinci-manager/pom.xml
maven-cloudwalk-intelligent-davinci-manager/davinci-manager-common/pom.xml
maven-cloudwalk-intelligent-davinci-manager/davinci-manager-storage/pom.xml
maven-cwos-resource/pom.xml
maven-cwos-resource/cwos-component-resource/pom.xml
maven-cwos-resource/cwos-component-resource-data/pom.xml
maven-cwos-resource/cwos-component-resource-interface/pom.xml
maven-cwos-resource/cwos-device-pkg-stub/pom.xml
maven-cwos-resource/cwos-portal/pom.xml
maven-cwos-resource/cwos-portal-interface/pom.xml
maven-cwos-resource/cwos-java-sdk-resource/pom.xml
maven-cwos-common-aks/pom.xml
maven-cwos-common-aks/cwos-common-aks-interface/pom.xml
maven-cwos-device-authentication/pom.xml
maven-cwos-device-authentication/cwos-device-authentication-interface/pom.xml
maven-cw-elevator-application/pom.xml
maven-cw-elevator-application/cw-elevator-application-common/pom.xml
maven-cw-elevator-application/cw-elevator-application-data/pom.xml
maven-cw-elevator-application/cw-elevator-application-service/pom.xml
maven-cw-elevator-application/cw-elevator-application-web/pom.xml
maven-intelligent-cwoscomponent/pom.xml
maven-intelligent-cwoscomponent/intelligent-cwoscomponent-parent/pom.xml
maven-intelligent-cwoscomponent/intelligent-cwoscomponent-interface/pom.xml
maven-intelligent-cwoscomponent/intelligent-cwoscomponent-rest/pom.xml
maven-ninca-crk/pom.xml
maven-ninca-crk/ninca-crk-gpu-std/pom.xml
maven-ninca-qk-alarm/pom.xml
maven-ninca-qk-alarm/ninca-qk-alarm-app-starter/pom.xml
```
---
## 5. 维护说明
- 若某子模块单独写了 `<version>`，以该模块 `pom.xml` 为准（当前走查结果：**子模块均未覆盖反应堆版本**）。
- 私服、Nexus 地址等多写在各反应堆 `pom.xml` 的 `properties` 中（如 `nexus.baseUrl`）。
- 本文不替代各工程 `dependencyManagement` 内**第三方库**的逐项版本；需要时可对各根 `pom.xml` 再跑 `mvn help:effective-pom` 导出。
---
## 6. 修订历史
| 日期 | 内容 |
|------|------|
| 2026-04-24 | 初稿：工作区 `pom` 走查 |
| 2026-04-24 | **主版本升级**（与历史反编译/私服坐标区分）：电梯 **2.0-SNAPSHOT**、intelligent **3.0.0-xinghewan**、cloudwalk-cloud **4.0.0-Brussels-SRX**、ninca-crk **2.0.0**、ninca-qk-alarm **1.0.0-SNAPSHOT**；`cloudwalk.internal.version`、电梯与 ninca-crk 中 intelligent 属性已对齐 |
| 2026-04-24 | **`cloudwalk.legacy.public.version`（3.7.2-Brussels-SRX）**：私服未发布新主版本的 `cloudwalk-common-result` / `web` / `serial` 时，与反应堆 **4.0.0** 解耦；本地编译说明见 [docs/build/本地编译说明.md](../build/本地编译说明.md) |
| 2026-04-24 | 补充反应堆 **`maven-cloudwalk-device-sdk`**（`cloudwalk-device-sdk` **2.2.0**）、**`maven-cwos-resource`**（CWOS 资源/门户/SDK）；`pom` 总数 **17 → 27**；编译顺序见 [本地编译说明.md](../build/本地编译说明.md) §3 |
| 2026-04-24 | 补充反应堆 **`maven-cloudwalk-intelligent-davinci-manager`**（**`cloudwalk-intelligent-davinci-manager` 1.1.7-SNAPSHOT**、`davinci-manager-common`、`davinci-manager-storage`）；`pom` 总数 **27 → 30**；编译顺序见 [本地编译说明.md](../build/本地编译说明.md) §3 |
| 2026-04-24 | 补充反应堆 **`maven-cloudwalk-legacy-public`**（**`反1`**：`cloudwalk-cloud-common` **3.7.2**、`common-result`/`web`/`serial`、**`cwos-sdk-event`**、**`component-lock`**）；`pom` 总数 **30 → 37**；须在 **`maven-cloudwalk-cloud`** 之前 install；见 [本地编译说明.md](../build/本地编译说明.md) §3 |
| 2026-04-24 | 补充反应堆 **`maven-cloudwalk-device-manager`**（**`cloudwalk-device-manager` 2.0.2**、**common**、**interface**；**`反1`** zip）；`pom` 总数 **37 → 40**；须在 **`maven-cloudwalk-legacy-public`** 之后 install；见 [本地编译说明.md](../build/本地编译说明.md) §3 |
| 2026-04-24 | 补充反应堆 **`maven-cwos-common-aks`**、**`maven-cwos-device-authentication`**（**`反1`**：`cwos-common-aks-interface`、`cwos-device-authentication-interface`）；`pom` 总数 **40 → 44**；**device-authentication** 须在 **`maven-cloudwalk-cloud`** 与 **`maven-cwos-common-aks`** 之后 install；见 [本地编译说明.md](../build/本地编译说明.md) §3 |
| 2026-04-24 | **`intelligent-cwoscomponent-rest`**：`FeignClient` 由 **`org.springframework.cloud.netflix.feign`** 改为 **`org.springframework.cloud.openfeign`**，与 **Greenwich + `spring-cloud-starter-openfeign`** 一致 |
| 2026-04-27 | **电梯** `intelligent.cwoscomponent.version` 定为 **2.9.2-xinghewan**（与 **`cw_lib`**、上线口径一致，**禁止 3.0.0**）；`build_nexus_only.sh` 改为从 **`cw_lib` + 父 POM 桩** install-file，不再默认编译 **`maven-intelligent-cwoscomponent` 3.0.0** |
---
*文档为工作区静态走查整理；若你本地有未提交的 `pom` 修改，请以工作区实际文件为准。*
docs/architecture/Maven聚合工程说明.md
+297
View File
@@ -0,0 +1,297 @@
# Maven 聚合工程说明（starRiverProperty）
> **适用范围**：本仓库根目录下以 `maven-` 为前缀的 **Maven Reactor**：其中 **五个** 为主业务聚合工程；另有 **七个** 补充反应堆（`maven-cloudwalk-device-sdk`、`maven-cloudwalk-device-manager`、`maven-cwos-resource`、`maven-cloudwalk-intelligent-davinci-manager`、**`maven-cloudwalk-legacy-public`**、**`maven-cwos-common-aks`**、**`maven-cwos-device-authentication`**）用于在私服缺父 POM 或缺历史公共 JAR 时 **本地 `install` 闭合** `cloudwalk-device-sdk`、`cloudwalk-device-manager`、`cwos-component-resource`、`cwos-portal`、`cwos-java-sdk-resource`、**`cloudwalk-intelligent-davinci-manager` / `davinci-manager-storage`**、**`cloudwalk-common-result` / `web` / `serial`（3.7.2）**、**`cwos-sdk-event`**、**`cloudwalk-intelligent-component-lock`**、**`cwos-common-aks` / `cwos-device-authentication`** 等坐标（**`反1/`** 下对应 `*.jar.src.zip` 已接入各反应堆）。
> **不适用范围**：各工程依赖的 **NINCA / 云从内部** 等大量 JAR 仍多须 Nexus 解析；本文描述**本仓库内可见的模块边界与协作关系**，补充反应堆仅覆盖文档化缺口中的一段。
---
## 1. 文档目的
- 说明五个聚合工程各自的 **业务定位、子模块划分、技术栈选型原因**。
- 说明工程之间的 **Maven 依赖与调用链上的协作**（与 `docs/business/` 中接口走查互补：本文偏「工程与构件」，走查文档偏「接口与数据流」）。
- 说明 **`maven-*`** 目录与 **`artifacts/decompiled/`**（源码归档，目录名 `decompiled` 为历史约定）、**运行包目录** `cw-elevator-application-V1.0.0.20211103/` 的分工，避免混淆「可改源码树」与「仅对照归档」。
---
## 2. 工程一览
### 2.1 主业务五工程
| 仓库目录 | 聚合 artifactId（父 POM） | `groupId` | 版本（父 POM） | 子模块（`modules`） |
|----------|---------------------------|-----------|----------------|----------------------|
| `maven-cloudwalk-cloud/` | `cloudwalk-cloud-reactor` | `cn.cloudwalk.cloud` | `4.0.0-Brussels-SRX` | `cloudwalk-cloud-common`、`cloudwalk-common-event`、`cloudwalk-common-service` |
| `maven-cw-elevator-application/` | `cw-elevator-application-reactor` | `cn.cloudwalk.elevator` | `2.0-SNAPSHOT` | `cw-elevator-application-common`、`data`、`service`、`web` |
| `maven-intelligent-cwoscomponent/` | `intelligent-cwoscomponent-reactor` | `cn.cloudwalk.intelligent` | `3.0.0-xinghewan` | `intelligent-cwoscomponent-parent`、`interface`、`rest` |
| `maven-ninca-crk/` | `ninca-crk-reactor` | `cn.cloudwalk.ninca` | `2.0.0` | `ninca-crk-gpu-std` |
| `maven-ninca-qk-alarm/` | `ninca-qk-alarm-reactor` | `cn.cloudwalk.ninca` | `1.0.0-SNAPSHOT` | `ninca-qk-alarm-app-starter`（其下再含 web / interface 等子模块） |
### 2.2 补充反应堆（编译链）
| 仓库目录 | 说明 |
|----------|------|
| `maven-cloudwalk-device-sdk/` | 安装 **`cn.cloudwalk:cloudwalk-device-sdk:2.2.0`**（`pom`）与 **`cloudwalk-device-sdk-protocol-entity`**，供 **`maven-intelligent-cwoscomponent`** 解析 `protocol-entity` 描述符。 |
| `maven-cloudwalk-device-manager/` | 安装 **`cn.cloudwalk.cloud:cloudwalk-device-manager:2.0.2`**（`pom`）及 **`cloudwalk-device-manager-common`**、**`cloudwalk-device-manager-interface`**；依赖 **`cloudwalk-common-result:3.7.2-Brussels-SRX`**（须先 **`maven-cloudwalk-legacy-public`** `install`）。 |
| `maven-cwos-resource/` | 安装 **`cwos-component-resource`**、**`cwos-portal`** 父 POM 及 **`cwos-java-sdk-resource`** 等，供 **`cw-elevator-application-service`** 解析 `cwos-java-sdk-resource` 的传递父链。`cwos-portal-interface` 为 **裁剪 + 占位** 以闭合 SDK，详见 [本地编译说明.md](../build/本地编译说明.md) §3。 |
| `maven-cloudwalk-intelligent-davinci-manager/` | 安装 **`cn.cloudwalk.intelligent:cloudwalk-intelligent-davinci-manager:1.1.7-SNAPSHOT`**（父 `pom`）及 **`davinci-manager-common`**、**`davinci-manager-storage`**，供电梯 **`cw-elevator-application-service`** 解析 **`davinci-manager-storage`**（`davinci.manager.storage.version`）。源码基底来自历史 **1.1.5** 反编译 zip，与 V1 运行包 **1.1.7-SNAPSHOT** 坐标一致；**`SpringMvcContract` / `FeignClientsConfiguration`** 与 **Greenwich + OpenFeign** 对齐。 |
| `maven-cloudwalk-legacy-public/` | 安装 **`cn.cloudwalk.cloud:cloudwalk-cloud-common:3.7.2-Brussels-SRX`**（与 **`cloudwalk-common-result` / `web` / `serial`** 反编译 POM 的 parent 一致）、**`cwos-sdk-event:1.5.0-SNAPSHOT`**、**`cloudwalk-intelligent-component-lock:1.1.1-SNAPSHOT`**。源码自 **`反1/*.jar.src.zip`** 解压；**`cwos-sdk-event`** 已替换 **`reflections-maven`** 为 **`org.reflections:reflections`**，并修正 **`KafkaConsumer#setListenerClass`** / **`EventClient`** 的编译问题。 |
| `maven-cwos-common-aks/` | 安装 **`cn.cloudwalk.cloud:cwos-common-aks:1.0.0-SNAPSHOT`** 与 **`cwos-common-aks-interface`**；源码自 **`反1/cwos-common-aks-interface-1.0.0-SNAPSHOT.jar.src.zip`**；须先 **`maven-cloudwalk-legacy-public`**（**`cloudwalk-common-result`**）。 |
| `maven-cwos-device-authentication/` | 安装 **`cn.cloudwalk.cloud:cwos-device-authentication:1.0.0-SNAPSHOT`** 与 **`cwos-device-authentication-interface`**；源码自 **`反1/cwos-device-authentication-interface-1.0.0-SNAPSHOT.jar.src.zip`**；依赖 **device-sdk**、**device-manager**、**`maven-cloudwalk-cloud`**（**`cloudwalk-common-service`**）、**`cwos-common-aks-interface`**，须在上述反应堆与 **`maven-cwos-common-aks`** 之后 **`install`**。 |
> **版本说明**：上表为当前源码树反应堆版本（相对历史反编译/私服线已做**主版本号升级**，便于区分）。与 `cw-elevator-application-V1.0.0.20211103` 等**历史运行包内 JAR 文件名**不必一致，详见 `docs/build/ORIGINAL_BUILD_JDK.txt` 文首说明及 [Maven工作区子工程版本一览](Maven工作区子工程版本一览.md)。
---
## 3. 各工程详细说明
### 3.1 `maven-cloudwalk-cloud` — 云从公共云底座（事件与服务）
**定位**
聚合 **CloudWalk 内部通用能力**：消息与事件封装（`cloudwalk-common-event`）、通用服务侧抽象与实现（`cloudwalk-common-service`）。电梯应用、智能组件等上层工程普遍依赖这里的 **`CloudwalkResult`、Feign 封装、事件注解** 等构件。
**为何存在「`cloudwalk-cloud-common`」子模块**
历史子 JAR 的 `parent` 曾指向 **`cloudwalk-cloud-common`**，而原始父 POM 在仓库中缺失。本聚合工程增加 **`cloudwalk-cloud-common`** 模块，使子模块能 **先 `install` 到本地 `~/.m2`**，满足其它构件对「父 POM 坐标」的解析，同时由本 reactor **继承 Spring Boot**，统一 **Spring Cloud Greenwich** 与内部版本属性（如 `cwos-sdk-event` 与 V1 运行包 `lib` 对齐的说明见父 `pom.xml` 注释）。
**技术栈摘要**
- Spring Boot **2.1.x**（与父 POM 声明一致）
- Spring Cloud **Greenwich**（`spring-cloud-dependencies` import）
- Java **1.8**
**与其它工程关系**
被 **`maven-cw-elevator-application`**、**`maven-intelligent-cwoscomponent`**、**`maven-ninca-crk`** 等通过 `dependencyManagement` 或直连依赖引用 `cloudwalk-common-event` / `cloudwalk-common-service` 等坐标。
---
### 3.2 `maven-cw-elevator-application` — 电梯 / ACS 通行应用
**定位**
**电梯与门禁派梯相关业务应用**：人员通行规则（含访客 `add/visitor`）、设备、区域/空间 Feign、乘梯记录、MQTT 等。对应运行环境中常部署的 **`elevator-app`** 一类服务；业务走查见 `docs/business/访客注册与派梯楼层业务流程走查.md`。
**子模块分层（推荐理解顺序）**
| 子模块 | 典型职责 |
|--------|----------|
| `cw-elevator-application-common` | 公共枚举、常量、工具、跨层 DTO/注解等 |
| `cw-elevator-application-data` | MyBatis 实体、Mapper、DAO 与数据源相关 |
| `cw-elevator-application-service` | 业务实现：`PersonRuleServiceImpl`、设备服务、记录服务等 |
| `cw-elevator-application-web` | Spring MVC 控制器，对外 HTTP API（如 `/elevator/person/add/visitor`） |
**技术栈摘要**
- Spring Boot **2.1.x**、Java **1.8**
- MyBatis、分库分表（ShardingSphere 等版本在父 POM 属性中集中管理）
- 依赖 **`cloudwalk-common-*`**、**`intelligent-cwoscomponent-rest`** 等（与智能侧、组织侧集成）
**与运行包、源码归档的关系**
- 父 POM 中属性 **`cw.elevator.v1.lib.dir`**（`${project.basedir}/../cw-elevator-application-V1.0.0.20211103/lib`）与 **V1 运行包 `lib` 目录** 对齐，便于 `install-file` 或私服核对。
- **`artifacts/decompiled/trees/cw-elevator-application-*-SNAPSHOT.jar.src`** 为历史解压对照；**日常改代码以 `maven-cw-elevator-application` 下各模块为准**。
---
### 3.3 `maven-intelligent-cwoscomponent` — 智能组件（接口 + REST）
**定位**
**智能操作系统组件（CWOS Component）**：对上提供 **REST / Feign Client** 入口，对下通过 **Feign** 调用组织人员、电梯、图库、空间等微服务。在业务文档中常作为「第三方或网关」与 **`cw-elevator-application`** 之间的中转层（例如 `ElevatorPersonService.addVisitor` → Feign → `POST /elevator/person/add/visitor`）。
**子模块说明**
| 子模块 | 职责 |
|--------|------|
| `intelligent-cwoscomponent-parent` | 占位/对齐原多模块父工程坐标（若子模块引用需要） |
| `intelligent-cwoscomponent-interface` | API、参数、结果 DTO、对外 Service 接口定义 |
| `intelligent-cwoscomponent-rest` | 接口实现、Feign 客户端声明、与 Spring Cloud 集成 |
**技术栈摘要**
- Spring Boot **2.1.x**、Spring Cloud **Greenwich**
- 管理 **`cloudwalk-device-sdk-protocol-entity`** 等与设备协议相关的版本（父 POM 注释与 V1 `lib` 对齐）
**与其它工程关系**
- **`maven-cw-elevator-application`** 依赖 **`intelligent-cwoscomponent-rest`**（或同版本构件），形成「智能组件编排 ↔ 电梯落地」的链路。
- **`maven-ninca-crk`** 的 `ninca-crk-gpu-std` 对 **`intelligent-cwoscomponent-rest`** 存在 **exclusion** 等精细依赖控制，说明 CRK 打包场景下需避免重复引入或版本冲突，以实际 **`ninca-crk-gpu-std/pom.xml`** 为准。
---
### 3.4 `maven-ninca-crk` — NINCA CRK 产品线（当前聚合 GPU 标准后端）
**定位**
**NINCA CRK**（门禁、考勤、访客、会议等组合能力）产品族中的 **标准 GPU 出入口后端** 工程 **`ninca-crk-gpu-std`**。子模块描述中体现为轻舟 1.4 体系下的 **标准 GPU 服务器-出入口版**；考勤、访客、门禁等大量 **web 模块以私服版本依赖** 引入，**不在本 reactor 的 `modules` 列表中展开**。
**为何使用 Boot 1.5 + Edgware**
父 POM 说明：为 **贴近原 `spring-boot-maven-plugin` 1.3.x 时代栈**，采用 Spring Boot **1.5.22** 与 Spring Cloud **Edgware**，减少与历史 fat jar 字节码、依赖树差异带来的构建问题。
**技术栈摘要**
- Spring Boot **1.5.x**、Cloud **Edgware**
- Java **1.8**
- 与 **`intelligent-cwoscomponent-rest`**、**`cloudwalk-common-event`** 等版本在父 POM `dependencyManagement` 中锁定
**与其它工程关系**
依赖本仓库整理的 **`intelligent-cwoscomponent-rest`**、**`cloudwalk-common-event`** 等；更多 `ninca-crk-*` 构件从 Nexus 拉取。
---
### 3.5 `maven-ninca-qk-alarm` — 轻舟告警应用（Starter 聚合）
**定位**
**区域告警 / 轻舟告警（qk-alarm）** 可执行应用的 Maven 化聚合：原 **`ninca-qk-alarm-app`** 父 POM 缺失，由本 **`ninca-qk-alarm-reactor`** 补齐 **`dependencyManagement`、插件版本、编码** 等，当前 reactor **直接列出的模块**为 **`ninca-qk-alarm-app-starter`**（可执行 JAR 形态业务的启动与组装入口）。
**子模块 `ninca-qk-alarm-app-starter` 说明**
- 依赖 **`ninca-qk-alarm-app-web`**、**`ninca-qk-alarm-app-interface`** 等同版本子构件，形成完整 Web + 接口层。
- 使用 **Curator + ZooKeeper**（版本在父 POM 统一管理），适用于注册发现或分布式协调类能力（以实际代码为准）。
**技术栈摘要**
- Spring Boot **2.1.x**、Java **1.8**
- MyBatis Spring Boot、Jacoco 等插件在父 POM `pluginManagement` 中声明
**与其它工程关系**
主要依赖 **`cloudwalk-common-web`** 等云从公共 Web 能力；与电梯、智能组件无强绑定，相对 **独立部署单元**。
---
### 3.6 `maven-cloudwalk-device-sdk` — 设备 SDK 父 POM（协议实体）
**定位**
私服常缺失 **`cn.cloudwalk:cloudwalk-device-sdk:2.2.0`** 父 `pom`，导致无法解析 **`cloudwalk-device-sdk-protocol-entity`**。本反应堆在本地 **`install`** 后，**`maven-intelligent-cwoscomponent`** 的 **`intelligent-cwoscomponent-interface`** 可正常解析该依赖。
**子模块**
- **`cloudwalk-device-sdk-protocol-entity`**：源码来自 `反1` 反编译 zip，与运行包 **2.2.0** 坐标一致。
---
### 3.7 `maven-cwos-resource` — CWOS 资源 / 门户 / Java SDK
**定位**
补齐 **`cwos-component-resource`**、**`cwos-portal`** 父 POM 及 **`cwos-java-sdk-resource`**，使 **`cw-elevator-application-service`** 不再因私服缺 **`cwos-component-resource:pom`**、**`cwos-portal:pom`** 而失败。
**子模块要点**
- **`cwos-component-resource-data`** / **`cwos-component-resource-interface`**：反编译源码。
- **`cwos-portal-interface`**：为闭合 **`cwos-java-sdk-resource`** 的编译 classpath，已 **裁剪** 非 SDK 所需包，并含 **`cwos-device-pkg-stub`**（`DeviceUpgradeResult` 占位）。
- **`cwos-java-sdk-resource`**：Feign 注解由 **`org.springframework.cloud.netflix.feign.FeignClient`** 迁移为 **`org.springframework.cloud.openfeign.FeignClient`**，与 **Greenwich + `spring-cloud-starter-openfeign`** 一致；**`ResourceBeanConfig`** 补全缺失的 `import`。
---
### 3.8 `maven-cloudwalk-intelligent-davinci-manager` — Davinci 存储父链
**定位**
私服常缺失 **`cn.cloudwalk.intelligent:cloudwalk-intelligent-davinci-manager:1.1.7-SNAPSHOT`** 父 `pom`，导致无法解析 **`davinci-manager-storage`**（电梯 **`cw-elevator-application-service`** 直接依赖）。本反应堆在本地 **`install`** 后，可闭合该父链。
**子模块**
- **`davinci-manager-common`**：`DavinciResult`、`DavinciServiceException` 等。
- **`davinci-manager-storage`**：文件/分片上传 Feign 与 **`FileStorageManager` / `FilePartManager`** 实现；**`io.github.openfeign:feign-okhttp`** 替代原 POM 中的 **`com.netflix.feign:feign-okhttp`**，与 **Spring Cloud Greenwich** 管理的 OpenFeign 一致。
---
### 3.9 `maven-cloudwalk-legacy-public` — 反1 私服公共线（3.7.2 + cwos-sdk-event + lock）
**定位**
将 **`反1/`** 内 **`cloudwalk-common-*-3.7.2-Brussels-SRX.jar.src.zip`**、**`cwos-sdk-event-1.5.0-SNAPSHOT.jar.src.zip`**、**`cloudwalk-intelligent-component-lock-1.1.1-SNAPSHOT.jar.src.zip`** 解压为 Maven 子模块并 **`install`**，闭合 **`cloudwalk.legacy.public.version`**、**`cwos.sdk.event.version`**、**`intelligent.lock.version`** 等横切依赖。
**子模块要点**
- **`cloudwalk-cloud-common`**：**`3.7.2-Brussels-SRX`** 父 `pom`（继承 **Boot 1.5.22**）；与 **`maven-cloudwalk-cloud`** 中 **4.0.0** 的 stub **`cloudwalk-cloud-common`** 为**不同版本**，勿混用。
- **`cloudwalk-common-result`**：在反编译依赖外补 **Spring / Jackson / Joda / SLF4J / validation-api**。
- **`cwos-sdk-event`**：**`reflections-maven`** → **`org.reflections:reflections`**；**`KafkaConsumer`** 实现 **`Consumer#setListenerClass(Class)`**；**`EventClient`** 使用 **`commons-lang3.StringUtils`**。
---
### 3.10 `maven-cloudwalk-device-manager` — 设备管理 common / interface（2.0.2）
**定位**
私服常缺失 **`cn.cloudwalk.cloud:cloudwalk-device-manager:2.0.2`** 父 `pom`，导致无法解析 **`cloudwalk-device-manager-common`**、**`cloudwalk-device-manager-interface`**。本反应堆在本地 **`install`** 后闭合该父链。
**子模块**
- **`cloudwalk-device-manager-common`**、**`cloudwalk-device-manager-interface`**：源码来自 **`反1/`** 下 **`cloudwalk-device-manager-*-2.0.2.jar.src.zip`**。父 POM 将 **`cloudwalk-common-result`** 锁定为 **`3.7.2-Brussels-SRX`**（与 **`maven-cloudwalk-legacy-public`** 一致）；**`hibernate-validator`** 与 **Boot 2.1.18** 栈对齐（**6.0.22.Final**）。
**与其它工程关系**
须在 **`maven-cloudwalk-legacy-public`** 成功 **`install`**（提供 **`cloudwalk-common-result:3.7.2`**）之后，再 **`install`** 本反应堆。
---
### 3.11 `maven-cwos-common-aks` / `maven-cwos-device-authentication` — AKS 与设备认证 interface（1.0.0-SNAPSHOT）
**定位**
与 **`cw-elevator-application-V1.0.0.20211103/cw_lib`** 中 **`cwos-common-aks-interface`**、**`cwos-device-authentication-interface`** 同名坐标对齐；私服若缺 **`cwos-common-aks`**、**`cwos-device-authentication`** 父 POM，可在本地 **`install`** 闭合。
**子模块**
- **`cwos-common-aks-interface`**、**`cwos-device-authentication-interface`**：源码来自 **`反1/`** 对应 **`*.jar.src.zip`**。
- **device-authentication** 的 **`pom`** 依赖 **`cloudwalk-common-service`**、**`cloudwalk-device-manager-interface`**、**`cwos-common-aks-interface`**、**`cloudwalk-device-sdk-protocol-entity`** 等，编译顺序见 [本地编译说明.md](../build/本地编译说明.md) §3。
---
## 4. 工程间依赖与协作（简图）
下列关系表示 **Maven 依赖 / 常见运行时调用方向**，非严格部署拓扑。
```mermaid
flowchart LR
subgraph devsdk [maven-cloudwalk-device-sdk]
PE[protocol-entity]
end
subgraph cwos [maven-cwos-resource]
SDK[cwos-java-sdk-resource]
end
subgraph davinci [maven-cloudwalk-intelligent-davinci-manager]
DMS[davinci-manager-storage]
end
subgraph cloud [maven-cloudwalk-cloud]
CE[cloudwalk-common-event]
CS[cloudwalk-common-service]
end
subgraph intel [maven-intelligent-cwoscomponent]
II[intelligent-cwoscomponent-interface]
IR[intelligent-cwoscomponent-rest]
end
subgraph elev [maven-cw-elevator-application]
EW[cw-elevator-application-web]
ES[cw-elevator-application-service]
end
subgraph crk [maven-ninca-crk]
GPU[ninca-crk-gpu-std]
end
subgraph alarm [maven-ninca-qk-alarm]
ST[ninca-qk-alarm-app-starter]
end
PE --> II
II --> IR
SDK --> ES
DMS --> ES
CE --> ES
CS --> ES
IR --> ES
ES --> EW
CE --> GPU
IR -.->|可能被 exclusion| GPU
CS --> ST
```
**文字归纳**
- **`maven-cloudwalk-device-sdk`** 为 **`intelligent-cwoscomponent-interface`** 提供 **`cloudwalk-device-sdk-protocol-entity`**；**`maven-cwos-resource`** 为 **`cw-elevator-application-service`** 提供 **`cwos-java-sdk-resource`**（及 portal/resource 父链）；**`maven-cloudwalk-intelligent-davinci-manager`** 为 **`cw-elevator-application-service`** 提供 **`davinci-manager-storage`** 父链；**`maven-cloudwalk-legacy-public`** 为 **`cloudwalk-common-event`**、电梯 **common**、**`cwos-resource`** 等提供 **`cloudwalk-common-result`/`web`/`serial`（3.7.2）**、**`cwos-sdk-event`**、**`component-lock`**；**`maven-cloudwalk-device-manager`** 提供 **`cloudwalk-device-manager:2.0.2`** 及 **common/interface**（依赖前述 **`cloudwalk-common-result:3.7.2`**）；**`maven-cwos-common-aks`**、**`maven-cwos-device-authentication`** 与 **`cw_lib`** 中 AKS / 设备认证 **interface** 坐标对齐（详见 §3.11）。前序 **`install`** 顺序见 [本地编译说明.md](../build/本地编译说明.md) §3。
- **电梯应用** 依赖 **公共云模块** + **智能组件 REST**，对外暴露电梯 HTTP API；智能组件再通过 Feign 回调电梯、组织等。
- **CRK GPU 标准后端** 依赖公共事件、智能组件等，与考勤/访客等 **NINCA 模块** 打成一个可部署单元（具体以 `ninca-crk-gpu-std/pom.xml` 为准）。
- **告警应用** 相对独立，主要挂 **CloudWalk Web 公共栈**。
---
## 5. 源码目录、`artifacts`、运行包三者的分工
| 位置 | 性质 | 建议使用方式 |
|------|------|----------------|
| **`maven-*/*/src/main/java`** | 已整理为 Maven 标准目录的 **主修改区** | 日常开发、编译、`mvn validate/package` |
| **`artifacts/decompiled/trees/*.jar.src`** | 由 JAR 还原的 **解压树归档**（对照用） | 查历史包内资源、与 `META-INF/maven` 对照版本 |
| **`artifacts/decompiled/archives/*.jar.src.zip`** | 未解压的 **zip 备份** | 备份、交付留档 |
| **`cw-elevator-application-V1.0.0.20211103/`** | **V1 运行包展开**（含 `lib/`） | 对齐线上依赖列表；`docs/operations/deploy_cw_elevator_v1_lib_to_nexus.py` 默认读取其 `lib` |
详见 [artifacts/decompiled/README.md](../../artifacts/decompiled/README.md)。
---
## 6. 构建与环境（延伸阅读）
- **JDK 版本依据**：[ORIGINAL_BUILD_JDK.txt](../build/ORIGINAL_BUILD_JDK.txt)
- **各父 POM** 中 **`maven-enforcer-plugin`** 要求使用 JDK 8 范围，与上述依据一致。
- **代码风格**：`docs/style/alibaba-eclipse-codestyle.xml`，各聚合工程通过属性 **`alibaba.eclipse.codestyle.path`** 引用。
- **私服与上传脚本**：`docs/operations/deploy_cw_elevator_v1_lib_to_nexus.py`；Nexus 地址见各父 POM 中 `nexus.baseUrl` 注释。
---
## 7. 文档维护
- 若新增其它 `maven-*` 反应堆，请在本表与各节补充 **目录、artifactId、modules、与其它工程的依赖边**，并更新 [Maven工作区子工程版本一览](Maven工作区子工程版本一览.md) 与 [本地编译说明.md](../build/本地编译说明.md) §3。
- 若 Spring Boot / Cloud 版本升级，请以各 **`maven-*/pom.xml`** 为准同步更新本文「技术栈摘要」小节。
docs/architecture/V1-V2-电梯API源码比对白名单.md
+51
View File
@@ -0,0 +1,51 @@
# V1 / V2 电梯应用 API 调用链源码比对白名单
本文约定：**每次发布或横向对拍异常排查**时，优先仅对下列文件做 V1 与 V2 的语义级 diff，避免整仓反编译树与 Maven 源码的「格式噪声」干扰判断。
## 用途
- 核对「HTTP 入口 → Service → Feign/DAO」是否与历史 V1 行为一致。
- 与 `maven-cw-elevator-application/tools/elevator_api_parity/` 对拍清单互补：白名单覆盖曾出现 **code_only 不一致** 的典型链路。
## 比对基线（仓库内路径）
| 侧 | 根路径 |
|----|--------|
| **V2（Maven 源码）** | `maven-cw-elevator-application/cw-elevator-application-web/src/main/java/cn/cloudwalk/elevator/`（web）<br>`maven-cw-elevator-application/cw-elevator-application-service/src/main/java/cn/cloudwalk/elevator/`（service） |
| **V1（反编译树，与 1.0-SNAPSHOT 模块 JAR 对齐）** | `artifacts/decompiled/trees/cw-elevator-application-web-1.0-SNAPSHOT.jar.src/cn/cloudwalk/elevator/`（web）<br>`artifacts/decompiled/trees/cw-elevator-application-service-1.0-SNAPSHOT.jar.src/cn/cloudwalk/elevator/`（service） |
若线网 V1 为 **另一 fat-jar**，应先确认其反编译树或 CFR 输出与上表 V1 根是否同源，再执行比对。
## 白名单（相对上述「根」的类路径）
| 优先级 | 相对路径 | 说明 |
|--------|----------|------|
| P0 | `person/controller/AcsPersonController.java` | `person/add`、`person/edit`、`person/pageByApp`、`timeDetail` 等 |
| P0 | `record/controller/AcsElevatorRecordController.java` | `record/page`、`analyse/cycle|count`、`page/request` |
| P0 | `passrule/controller/AcsPassRuleController.java` | `passRule/add` 等规则入口 |
| P0 | `person/impl/PersonRuleServiceImpl.java` | `person/add` 业务链、`76260527` 空设备等 |
| P0 | `person/impl/AcsPersonServiceImpl.java` | `edit`、`pageByApp`、`timeDetail`、图库/设备 Feign 组装 |
| P0 | `record/impl/AcsElevatorRecordServiceImpl.java` | `openRecord`、`analyseCycle`、`analyseCount`、`pageInfo` |
| P1 | `passrule/impl/AcsPassRuleServiceImpl.java` | 规则新增/编辑主流程 |
| P1 | `passrule/impl/ImageRuleRefServiceImpl.java` | `addOnlyRule` 等与 `76260527` 相关分支 |
| P1 | `common/AbstractCloudwalkController.java` | `getCloudwalkContext()` 等与请求头/会话相关 |
按需扩展时，应先在 `api_catalog.json` 或走查清单中标注接口 id，再增补对应 Controller/Service，**避免无界扫 diff**。
## 建议命令（忽略空白，便于看语义）
在仓库根目录执行，示例（web 单文件）：
```bash
diff -uw \
artifacts/decompiled/trees/cw-elevator-application-web-1.0-SNAPSHOT.jar.src/cn/cloudwalk/elevator/person/controller/AcsPersonController.java \
maven-cw-elevator-application/cw-elevator-application-web/src/main/java/cn/cloudwalk/elevator/person/controller/AcsPersonController.java
```
`service` 模块将两条根路径中的 `...-web-...` / `cw-elevator-application-web` 换成 `...-service-...` / `cw-elevator-application-service` 即可。
## 相关文档
- V1/V2 依赖比对（`lib`/`cw_lib` 与反应堆坐标）：`V1-V2-电梯依赖比对.md`
- 对拍约定与清单说明：`../../maven-cw-elevator-application/tools/elevator_api_parity/API-RECONCILIATION.md`
- 走查任务总览：`对外接口不变-走查任务与状态.md`
docs/architecture/V1-V2-电梯依赖比对.md
+169
View File
@@ -0,0 +1,169 @@
# V1 与 V2 电梯应用依赖：详细比对说明
本文说明 **V1 历史运行包** 与 **V2 Maven 反应堆** 在依赖上的对应关系、已核对的一致项、已知差异与后续可执行动作。比对以仓库内 `**cw-elevator-application-V1.0.0.20211103`** 为 V1 基线。
---
## 1. V1 运行包 classpath 结构（与 V2 可执行 JAR 的对应）
| 位置 | 路径 | 数量 | 含义 |
| -------------------- | ------------------------------------------------------ | ------- | --------------------------------------------------------------------------------- |
| **第三方与 Spring 栈** | `cw-elevator-application-V1.0.0.20211103/lib/*.jar` | **245** | 与 Boot 1.5、Spring Cloud、MyBatis、Netty、Feign 等一致；文件名即 **artifactId-version** 形态为主。 |
| **云从 + 电梯模块 + 智能组件** | `cw-elevator-application-V1.0.0.20211103/cw_lib/*.jar` | **24** | 与 V2 `pom.xml` 中 **显式声明版本** 的坐标对齐；电梯四模块以 **1.0-SNAPSHOT** JAR 形式落盘。 |
V2 可执行包由 `spring-boot-maven-plugin` repackage 后，上述两类依赖会进入 `**BOOT-INF/lib/`**；概念上 **V2 ≈ cw_lib ∪ lib 的传递闭包**，但 **具体 JAR 列表以 Maven 解析结果为准**。
**完整文件名清单（机器可读）**：
- `docs/architecture/data/v1-elevator-lib-jars.txt`（245 行）
- `docs/architecture/data/v1-elevator-cw-lib-jars.txt`（24 行）
---
## 2. `cw_lib`（24）与 V2 反应堆版本：逐项一致
下列 JAR 在 V1 `cw_lib` 中的 **文件名** 与 V2 `maven-cw-elevator-application/pom.xml` 的 `<properties>` / `dependencyManagement` **一致**（脚本已自动核对）：
| # | V1 `cw_lib` 文件名 | V2 约束来源 |
| --- | --------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 1 | `cloudwalk-common-event-3.7.2-Brussels-SRX.jar` | `cloudwalk.internal.version` |
| 2 | `cloudwalk-common-result-3.7.2-Brussels-SRX.jar` | `cloudwalk.legacy.public.version` |
| 3 | `cloudwalk-common-serial-3.7.2-Brussels-SRX.jar` | `cloudwalk.legacy.public.version` |
| 4 | `cloudwalk-common-service-3.7.2-Brussels-SRX.jar` | `cloudwalk.internal.version` |
| 5 | `cloudwalk-common-web-3.7.2-Brussels-SRX.jar` | `cloudwalk.legacy.public.version` |
| 6 | `cloudwalk-device-manager-common-2.0.2.jar` | V1 随包固定；V2 由 `**intelligent-cwoscomponent-rest`** 等传递引入（反应堆未单独 pin 版本，以解析树为准） |
| 7 | `cloudwalk-device-manager-interface-2.0.2.jar` | 同上 |
| 8 | `cloudwalk-device-sdk-protocol-entity-2.2.0.jar` | 同上 |
| 9 | `cloudwalk-intelligent-component-lock-1.1.1-SNAPSHOT.jar` | `intelligent.lock.version` |
| 10 | `cw-elevator-application-common-1.0-SNAPSHOT.jar` | V2：`cn.cloudwalk.elevator:cw-elevator-application-common:**2.0-SNAPSHOT`** |
| 11 | `cw-elevator-application-data-1.0-SNAPSHOT.jar` | V2：`…-data:**2.0-SNAPSHOT`** |
| 12 | `cw-elevator-application-service-1.0-SNAPSHOT.jar` | V2：`…-service:**2.0-SNAPSHOT**` |
| 13 | `cw-elevator-application-web-1.0-SNAPSHOT.jar` | V2：`…-web:**2.0-SNAPSHOT**` |
| 14 | `cwos-common-aks-interface-1.0.0-SNAPSHOT.jar` | V1 随包；V2 若未在反应堆显式声明则来自传递依赖 |
| 15 | `cwos-component-resource-data-1.0.0-SNAPSHOT.jar` | 同上 |
| 16 | `cwos-component-resource-interface-1.0.0-SNAPSHOT.jar` | 同上 |
| 17 | `cwos-device-authentication-interface-1.0.0-SNAPSHOT.jar` | 同上 |
| 18 | `cwos-java-sdk-resource-1.0.0-SNAPSHOT.jar` | `cwos.sdk.resource.version` |
| 19 | `cwos-portal-interface-1.0.0-SNAPSHOT.jar` | V1 随包；V2 传递 |
| 20 | `cwos-sdk-event-1.5.0-SNAPSHOT.jar` | `cwos.sdk.event.version` |
| 21 | `davinci-manager-common-1.1.7-SNAPSHOT.jar` | 与 `davinci-manager-storage` 同族 |
| 22 | `davinci-manager-storage-1.1.7-SNAPSHOT.jar` | `davinci.manager.storage.version` |
| 23 | `intelligent-cwoscomponent-interface-2.9.2-xinghewan.jar` | `intelligent.cwoscomponent.version` |
| 24 | `intelligent-cwoscomponent-rest-2.9.2-xinghewan.jar` | `intelligent.cwoscomponent.version` |
**结论（云从/智能主干）**：与对拍、校验切面相关的 `**cloudwalk-common-*` 3.7.2-Brussels-SRX** 与 `**intelligent-cwoscomponent-*` 2.9.2-xinghewan** 等，**V1 cw_lib 与 V2 POM 显式口径一致**；对拍行为差异 **不宜** 首先归因于「cloudwalk 主版本不一致」。
**电梯自研模块**：V1 为 **1.0-SNAPSHOT** 四 JAR，V2 反应堆为 **2.0-SNAPSHOT** —— 属 **预期版本升级**，需用源码白名单比对（见 `V1-V2-电梯API源码比对白名单.md`），而非依赖坐标「偷偷不一致」。
---
## 3. V1 `lib`（245）与 V2 `dependencyManagement`：显式对齐项
V2 反应堆在 `<properties>` 中 **主动钉死**、且与 V1 `lib` 中 **常见文件名** 对齐的第三方包括（节选）：
| 属性 | 值 | V1 `lib` 中典型 JAR |
| ------------------------------------------------------- | --------------- | --------------------------------------------- |
| `fastjson.version` | 1.2.73 | `fastjson-1.2.73.jar` |
| `guava.version` | 20.0 | `guava-20.0.jar` |
| `poi.version` | 3.15 | `poi-3.15.jar`、`poi-ooxml-3.15.jar` |
| `ant.version` | 1.9.6 | 见下节「多版本」 |
| `mybatis-spring-boot.version` | 1.3.1 | `mybatis-spring-boot-starter-1.3.1.jar` |
| `pagehelper.version` / `pagehelper-spring-boot.version` | 5.1.2 / 1.2.5 | `pagehelper-5.1.2.jar` 等 |
| `shardingsphere.version` | 4.0.0 | `sharding-jdbc-spring-boot-starter-4.0.0.jar` |
| `spring-cloud.version` | **Edgware.SR6** | 见下节 |
**Spring Boot**：V2 父 POM 为 `**spring-boot-starter-parent` 1.5.17.RELEASE**；V1 `lib` 中可见 `**spring-boot-*-1.5.17.RELEASE.jar`**，主版本一致。
---
## 4. V1 `lib` 中的「多版本并存」风险（V2 由 BOM 收敛）
对 `lib` 内文件名做 **artifact 前缀聚合** 后，典型 **多版本** 包括：
| 前缀 | 并存版本（示例） | 说明 |
| ------------ | --------------- | ------------------------------------------------------------------- |
| `feign-core` | 8.18.0 与 9.5.0 | 历史传递与 Netflix/OpenFeign 栈叠加；**实际生效顺序依赖 fat JAR Class-Path / 装载顺序**。 |
| `ant` | 1.6.5 与 1.9.6 等 | V2 反应堆仅钉 `**ant.version` = 1.9.6**；V1 物理目录仍含旧 ant。 |
| `rxjava` | 1.x 与 2.x | 常见于 Netflix + 其它客户端并存。 |
V2 由 `**spring-boot-dependencies` + `spring-cloud-dependencies`（Edgware.SR6）** 统一解析，**理论上** 比「手工铺 245 个 jar」更可重复；若需 **字节级** 证明与 V1 运行时一致，应在 **同一 JDK** 下导出 `**mvn dependency:tree`** 与 V1 进程 `**jcmd <pid> VM.classloader_hierarchy`** / 或解压 fat JAR 的 `BOOT-INF/lib` 做集合 diff。
---
## 5. V2 反应堆「直接依赖」模块一览（非传递闭包）
| 模块 | 直接引入的典型坐标（无版本处由 `dependencyManagement` 解析） |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cw-elevator-application-starter` | `spring-boot-starter-web`、MyBatis、Actuator、Cache、AOP、OpenFeign、`cw-elevator-application-web` |
| `cw-elevator-application-web` | `cloudwalk-common-web`、`cw-elevator-application-service` |
| `cw-elevator-application-service` | `cloudwalk-common-service`、`spring-tx`、`cloudwalk-common-serial`、`cwos-java-sdk-resource`、`jackson-datatype-jsr310`、`cloudwalk-intelligent-component-lock`、`cloudwalk-common-event`、`cwos-sdk-event`、`cw-elevator-application-data`、`davinci-manager-storage`、`intelligent-cwoscomponent-rest`、`spring-cloud-starter-openfeign`、`javax.annotation-api`、`jsr305` |
| `cw-elevator-application-common` | `cloudwalk-common-result`、Guava、POI、Ant、thumbnailator、`commons-io`、fastjson、`tomcat-embed-core`、`cloudwalk-common-web`、`spring-boot-autoconfigure`、`commons-lang3`、ZXing、zip4j、`spring-web`、`spring-data-redis`、lombok、`jackson-datatype-jsr310` |
| `cw-elevator-application-data` | `cw-elevator-application-common`、`cloudwalk-common-result`、`spring-beans`/`context`、MyBatis、mysql、`mybatis-spring-boot-starter`、HikariCP、pagehelper、shardingsphere |
**与 V1 的差异点**：V2 `**cw-elevator-application-common`** 显式增加 `**spring-boot-autoconfigure`**（见模块内注释：私服上 `cloudwalk-common-web` 传递不完整时的 **编译 classpath 补齐**）。V1 若完全依赖传递，**编译期/工具链** 与 V2 可能略有不同，但 **运行时** 通常仍由 Boot 引入同一类库。
---
## 5.1 反应堆子模块报「在 nexus-public 找不到 sibling SNAPSHOT」
**现象**：`data` 拉 `cw-elevator-application-common`、`web` 拉 `service` 等，日志只出现 `Downloading from nexus-public: .../elevator/...`。
**原因**：全局 `~/.m2/settings.xml` 中 `**mirrorOf=*`**（或等价过宽）时，Maven 易把 **本反应堆未发布到私服的 SNAPSHOT** 也导向 Nexus，导致失败。**不需要**为此逐个 `deploy` 电梯子模块到私服。
**本仓库已落盘**：`maven-cw-elevator-application/.mvn/maven.config` + `.mvn/settings.xml`：用 `-s` **绕过** `~/.m2`；profile 激活 `**nexus-public`（http）**；并含 一条 `id=maven-default-http-blocker`、`mirrorOf=dummy` 的占位 `<mirror>`，用于覆盖 Maven 3.8.1+ 安装目录里对 `**external:http:*`** 的默认拦截（否则会出现 `Blocked mirror for repositories: [nexus-public (...http...)]`）。**不是** `mirrorOf=*`，不会把反应堆 sibling 整体导向私服。私服若需账号，请在 `.mvn/settings.xml` 内补 `<servers>`（勿提交密钥）。若 Nexus 已支持 **HTTPS**，更推荐改仓库 URL 为 `https://` 并删除该占位 mirror。
**隔离构建**：`./scripts/build_nexus_only.sh` 会额外 `purge` `**cn/cloudwalk/elevator`** 下 `*.lastUpdated`，并在使用 `clean install` 时把 sibling 写入隔离库。
---
## 6. 生成「V2 全量传递依赖树」与与 V1 的集合 diff（推荐下一步）
当前环境若 **无法安装反应堆子模块** 或 **无法访问 Nexus**，则无法在 CI 外自动生成 **V2 完整 245+ 级传递树**。请在 **可解析依赖** 的环境、于 `**maven-cw-elevator-application` 根**执行（**自动使用 `.mvn/settings.xml`**；与 `build_nexus_only.sh` 对齐隔离库时可加 `-Dmaven.repo.local=$PWD/.m2-elevator-nexus-only`）：
```bash
cd maven-cw-elevator-application
mvn -pl cw-elevator-application-starter -am -DskipTests clean install
mvn -pl cw-elevator-application-starter -am -DskipTests dependency:tree \
-DoutputFile=cw-elevator-application-starter/target/v2-starter-dependency-tree.txt
```
然后将 `**target/v2-starter-dependency-tree.txt**` 中的 `groupId:artifactId:jar:version` 与 `**docs/architecture/data/v1-elevator-lib-jars.txt**` 做集合差集（仅 artifactId-version 对齐即可），即可得到 **「V2 有而 V1 lib 无」** 与 **「V1 lib 有而 V2 未解析到」** 的完整列表。
---
## 7. 自动化脚本（可重复输出摘要）
仓库根目录执行：
```bash
python3 scripts/compare_v1_v2_elevator_dependencies.py
```
将打印：`cw_lib` 与 V2 属性对齐核对、V1 `lib` 多版本示例、以及生成 `dependency:tree` 的 Maven 命令提示。
---
## 8. 总括结论（供评估「下一步计划」）
1. **云从公共件 + intelligent 2.9.2 + davinci/cwos 等与对拍强相关的坐标**：V1 `cw_lib` 与 V2 `pom.xml` **已对齐**。
2. **电梯四模块**：V1 **1.0-SNAPSHOT** JAR vs V2 **2.0-SNAPSHOT** 源码 —— **预期差异**，行为差应结合 **源码白名单 diff + 运行时** 看。
3. **245 个第三方 JAR**：V2 由 **Boot 1.5.17 + Cloud Edgware.SR6 BOM** 收敛；V1 物理目录存在 **Feign/Ant/RxJava 多版本**，**与「仅业务源码不同」假设不完全相容** —— 若要对齐到「与 V1 进程 classpath 完全一致」，需 **依赖树 diff**，不能只盯 `cw_lib`。
4. **下一步建议优先级**：① 在 CI 生成并归档 `**dependency:tree`**；② 与 `v1-elevator-lib-jars.txt` 做 **差集报告**；③ 对差集中 **多版本冲突** 项做 **运行时类加载验证**（仅静态比对不足以解释偶发 NPE/空响应）。
---
## 相关文档
- API 调用链源码比对白名单：`V1-V2-电梯API源码比对白名单.md`
- 对拍与根因说明：`../../maven-cw-elevator-application/tools/elevator_api_parity/API-RECONCILIATION.md`
docs/architecture/data/v1-elevator-cw-lib-jars.txt
+24
View File
@@ -0,0 +1,24 @@
cloudwalk-common-event-3.7.2-Brussels-SRX.jar
cloudwalk-common-result-3.7.2-Brussels-SRX.jar
cloudwalk-common-serial-3.7.2-Brussels-SRX.jar
cloudwalk-common-service-3.7.2-Brussels-SRX.jar
cloudwalk-common-web-3.7.2-Brussels-SRX.jar
cloudwalk-device-manager-common-2.0.2.jar
cloudwalk-device-manager-interface-2.0.2.jar
cloudwalk-device-sdk-protocol-entity-2.2.0.jar
cloudwalk-intelligent-component-lock-1.1.1-SNAPSHOT.jar
cw-elevator-application-common-1.0-SNAPSHOT.jar
cw-elevator-application-data-1.0-SNAPSHOT.jar
cw-elevator-application-service-1.0-SNAPSHOT.jar
cw-elevator-application-web-1.0-SNAPSHOT.jar
cwos-common-aks-interface-1.0.0-SNAPSHOT.jar
cwos-component-resource-data-1.0.0-SNAPSHOT.jar
cwos-component-resource-interface-1.0.0-SNAPSHOT.jar
cwos-device-authentication-interface-1.0.0-SNAPSHOT.jar
cwos-java-sdk-resource-1.0.0-SNAPSHOT.jar
cwos-portal-interface-1.0.0-SNAPSHOT.jar
cwos-sdk-event-1.5.0-SNAPSHOT.jar
davinci-manager-common-1.1.7-SNAPSHOT.jar
davinci-manager-storage-1.1.7-SNAPSHOT.jar
intelligent-cwoscomponent-interface-2.9.2-xinghewan.jar
intelligent-cwoscomponent-rest-2.9.2-xinghewan.jar
docs/architecture/data/v1-elevator-lib-jars.txt
+245
View File
@@ -0,0 +1,245 @@
activation-1.1.jar
aliyun-java-sdk-core-3.2.8.jar
aliyun-java-sdk-dysmsapi-1.1.0.jar
animal-sniffer-annotation-1.0.jar
annotations-2.0.0.jar
ant-1.6.5.jar
ant-1.9.6.jar
ant-apache-bsf-1.9.4.jar
ant-jakarta-oro-1.6.1.jar
ant-launcher-1.9.6.jar
antlr4-runtime-4.7.2.jar
ant-nodeps-1.8.1.jar
archaius-core-0.6.6.jar
asm-5.0.3.jar
asm-analysis-5.0.3.jar
asm-tree-5.0.3.jar
asm-util-5.0.3.jar
aspectjweaver-1.8.13.jar
bcpkix-jdk15on-1.55.jar
bcprov-jdk15on-1.55.jar
bsf-2.4.0.jar
byte-buddy-1.9.6.jar
cache-api-1.0.0.jar
classmate-1.3.4.jar
classworlds-1.1-alpha-2.jar
commons-codec-1.10.jar
commons-collections-3.2.2.jar
commons-collections4-4.1.jar
commons-compress-1.9.jar
commons-configuration-1.8.jar
commons-fileupload-1.3.1.jar
commons-io-2.5.jar
commons-lang-2.6.jar
commons-lang3-3.5.jar
commons-logging-1.2.jar
commons-pool2-2.4.3.jar
consul-api-1.3.0.jar
core-3.3.3.jar
curvesapi-1.04.jar
d3js-3.4.11.jar
dom4j-1.6.1.jar
ehcache-2.10.5.jar
encrypt-core-merge-4.0.0.jar
encrypt-core-rewrite-4.0.0.jar
fastjson-1.2.73.jar
feign-core-8.18.0.jar
feign-core-9.5.0.jar
feign-form-3.0.3.jar
feign-form-spring-3.0.3.jar
feign-hystrix-9.5.0.jar
feign-okhttp-8.18.0.jar
feign-slf4j-9.5.0.jar
freemarker-2.3.28.jar
fst-2.56.jar
groovy-2.4.5-indy.jar
gson-2.8.5.jar
guava-20.0.jar
hamcrest-core-1.3.jar
HdrHistogram-2.1.9.jar
hibernate-validator-5.3.6.Final.jar
HikariCP-2.5.1.jar
httpclient-4.5.6.jar
httpcore-4.4.10.jar
hystrix-core-1.5.12.jar
hystrix-javanica-1.5.12.jar
hystrix-metrics-event-stream-1.5.12.jar
hystrix-serialization-1.5.12.jar
jackson-annotations-2.11.2.jar
jackson-core-2.11.2.jar
jackson-databind-2.11.2.jar
jackson-dataformat-yaml-2.11.2.jar
jackson-datatype-jsr310-2.11.2.jar
jackson-module-afterburner-2.11.2.jar
jade-plugin-common-1.3.8.jar
javassist-3.21.0-GA.jar
javax.inject-1.jar
jboss-logging-3.3.2.Final.jar
jcl-over-slf4j-1.7.25.jar
jdom-1.1.2.jar
jedis-2.9.0.jar
jersey-apache-client4-1.19.1.jar
jersey-client-1.19.1.jar
jersey-core-1.19.1.jar
joda-time-2.9.9.jar
jodd-bean-3.7.1.jar
jodd-core-3.7.1.jar
jquery-2.1.1.jar
jsoup-1.9.2.jar
jsqlparser-1.2.jar
jsr311-api-1.1.1.jar
jul-to-slf4j-1.7.25.jar
junit-4.12.jar
kafka-clients-2.3.0.jar
log4j-over-slf4j-1.7.25.jar
logback-classic-1.1.11.jar
logback-core-1.1.11.jar
lombok-1.16.18.jar
lz4-java-1.6.0.jar
mail-1.4.4.jar
maven-artifact-2.0.5.jar
maven-artifact-manager-2.0.5.jar
maven-model-2.0.5.jar
maven-plugin-anno-1.4.1.jar
maven-plugin-api-2.0.5.jar
maven-profile-2.0.5.jar
maven-project-2.0.5.jar
maven-repository-metadata-2.0.5.jar
maven-settings-2.0.5.jar
mybatis-3.4.6.jar
mybatis-spring-1.3.2.jar
mybatis-spring-boot-autoconfigure-1.3.1.jar
mybatis-spring-boot-starter-1.3.1.jar
mysql-connector-java-5.1.47.jar
netflix-commons-util-0.1.1.jar
netflix-statistics-0.1.1.jar
netty-buffer-4.1.33.Final.jar
netty-codec-4.1.33.Final.jar
netty-codec-dns-4.1.33.Final.jar
netty-common-4.1.33.Final.jar
netty-handler-4.1.33.Final.jar
netty-resolver-4.1.33.Final.jar
netty-resolver-dns-4.1.33.Final.jar
netty-transport-4.1.33.Final.jar
objenesis-2.1.jar
okhttp-3.2.0.jar
okio-1.6.0.jar
opencsv-2.3.jar
pagehelper-5.1.2.jar
pagehelper-spring-boot-autoconfigure-1.2.5.jar
parboiled-core-1.1.7.jar
parboiled-java-1.1.7.jar
pegdown-1.6.0.jar
plexus-container-default-1.0-alpha-9.jar
plexus-utils-1.1.jar
poi-3.15.jar
poi-ooxml-3.15.jar
poi-ooxml-schemas-3.15.jar
reactive-streams-1.0.2.jar
reactor-core-2.0.8.RELEASE.jar
reactor-stream-2.0.8.RELEASE.jar
redisson-2.15.2.jar
redisson-spring-boot-starter-2.15.2.jar
redisson-spring-data-18-2.15.2.jar
reflections-0.9.9-RC2.jar
reflections-maven-0.9.9-RC2.jar
ribbon-2.2.5.jar
ribbon-core-2.2.5.jar
ribbon-httpclient-2.2.5.jar
ribbon-loadbalancer-2.2.5.jar
ribbon-transport-2.2.5.jar
rxjava-1.2.0.jar
rxjava-2.1.13.jar
rxnetty-0.4.9.jar
rxnetty-contexts-0.4.9.jar
rxnetty-servo-0.4.9.jar
servo-core-0.10.1.jar
servo-internal-0.10.1.jar
sharding-core-api-4.0.0.jar
sharding-core-common-4.0.0.jar
sharding-core-entry-4.0.0.jar
sharding-core-execute-4.0.0.jar
sharding-core-merge-4.0.0.jar
sharding-core-rewrite-4.0.0.jar
sharding-core-route-4.0.0.jar
sharding-jdbc-core-4.0.0.jar
sharding-jdbc-spring-boot-starter-4.0.0.jar
shardingsphere-execute-4.0.0.jar
shardingsphere-merge-4.0.0.jar
shardingsphere-rewrite-engine-4.0.0.jar
shardingsphere-spi-4.0.0.jar
shardingsphere-sql-parser-engine-4.0.0.jar
shardingsphere-sql-parser-mysql-4.0.0.jar
shardingsphere-sql-parser-oracle-4.0.0.jar
shardingsphere-sql-parser-postgresql-4.0.0.jar
shardingsphere-sql-parser-relation-4.0.0.jar
shardingsphere-sql-parser-spi-4.0.0.jar
shardingsphere-sql-parser-sql92-4.0.0.jar
shardingsphere-sql-parser-sqlserver-4.0.0.jar
sharding-spring-boot-util-4.0.0.jar
sharding-transaction-core-4.0.0.jar
slf4j-api-1.7.25.jar
snakeyaml-1.17.jar
snappy-java-1.1.7.3.jar
spring-aop-4.3.29.RELEASE.jar
spring-aspects-4.3.29.RELEASE.jar
spring-beans-4.3.29.RELEASE.jar
spring-boot-1.5.17.RELEASE.jar
spring-boot-actuator-1.5.17.RELEASE.jar
spring-boot-autoconfigure-1.5.17.RELEASE.jar
spring-boot-starter-1.5.17.RELEASE.jar
spring-boot-starter-actuator-1.5.17.RELEASE.jar
spring-boot-starter-aop-1.5.17.RELEASE.jar
spring-boot-starter-cache-1.5.17.RELEASE.jar
spring-boot-starter-data-redis-1.5.17.RELEASE.jar
spring-boot-starter-freemarker-1.5.17.RELEASE.jar
spring-boot-starter-jdbc-1.5.17.RELEASE.jar
spring-boot-starter-logging-1.5.17.RELEASE.jar
spring-boot-starter-tomcat-1.5.17.RELEASE.jar
spring-boot-starter-web-1.5.17.RELEASE.jar
spring-cloud-commons-1.3.5.RELEASE.jar
spring-cloud-consul-core-1.3.5.RELEASE.jar
spring-cloud-consul-discovery-1.3.5.RELEASE.jar
spring-cloud-context-1.3.5.RELEASE.jar
spring-cloud-netflix-core-1.4.6.RELEASE.jar
spring-cloud-netflix-hystrix-dashboard-1.4.6.RELEASE.jar
spring-cloud-starter-1.3.5.RELEASE.jar
spring-cloud-starter-consul-1.3.5.RELEASE.jar
spring-cloud-starter-consul-discovery-1.3.5.RELEASE.jar
spring-cloud-starter-netflix-archaius-1.4.6.RELEASE.jar
spring-cloud-starter-netflix-hystrix-1.4.6.RELEASE.jar
spring-cloud-starter-netflix-hystrix-dashboard-1.4.6.RELEASE.jar
spring-cloud-starter-netflix-ribbon-1.4.6.RELEASE.jar
spring-cloud-starter-openfeign-1.4.6.RELEASE.jar
spring-cloud-starter-ribbon-1.4.6.RELEASE.jar
spring-context-4.3.29.RELEASE.jar
spring-context-support-4.3.29.RELEASE.jar
spring-core-4.3.29.RELEASE.jar
spring-data-commons-1.13.16.RELEASE.jar
spring-data-keyvalue-1.2.16.RELEASE.jar
spring-data-redis-1.8.16.RELEASE.jar
spring-expression-4.3.29.RELEASE.jar
spring-jdbc-4.3.29.RELEASE.jar
spring-oxm-4.3.29.RELEASE.jar
spring-security-crypto-4.2.9.RELEASE.jar
spring-security-rsa-1.0.3.RELEASE.jar
springside-core-4.2.3-GA.jar
spring-tx-4.3.29.RELEASE.jar
spring-web-4.3.29.RELEASE.jar
spring-webmvc-4.3.29.RELEASE.jar
stax-api-1.0.1.jar
thumbnailator-0.4.8.jar
tomcat-annotations-api-8.5.34.jar
tomcat-embed-core-8.5.34.jar
tomcat-embed-el-8.5.34.jar
tomcat-embed-websocket-8.5.34.jar
tomcat-jdbc-8.5.34.jar
tomcat-juli-8.5.34.jar
validation-api-1.1.0.Final.jar
wagon-provider-api-1.0-beta-2.jar
xml-apis-1.4.01.jar
xmlbeans-2.6.0.jar
xpp3-1.1.3.4-RC8.jar
xstream-1.1.3.jar
zip4j-2.6.2.jar
zstd-jni-1.4.0-1.jar
docs/architecture/对外接口不变-走查任务与状态.md
+227
View File
@@ -0,0 +1,227 @@
# 对外接口不变：走查任务与状态
> **依据**：[对外接口不变-远程调用与性能优化约定](对外接口不变-远程调用与性能优化约定.md)（§2 总原则、§3 场景、§4 优先级）。
> **走查代码根**：`maven-cw-elevator-application/cw-elevator-application-service`（2026-04-24 静态走查）。
> **说明**：下表「子任务数」指**与约定相关的 RPC/可优化循环次数上界**（随运行时数据规模变化）；**状态**表示在**不扩展 Feign/HTTP 契约**前提下是否建议动代码。
> **排期（2026-04）**：`frontend/` 暂无可用前端工程；**凡需改前端、登记页、物业管理端 UI 的迭代，暂跳过**（详见 [docs/README 当前排期与范围](../README.md#当前排期与范围2026-04)）。本文档仅跟踪**电梯等服务端**在约定下的走查与修正。
---
## 1. 总览表（子任务量 + 可修正 / 不可修正）
| 约定 § | 代码锚点 | 子任务数（上界） | 下一可修正动作（建议顺序） | 不可修正或须前置确认 |
|--------|----------|------------------|----------------------------|------------------------|
| **§3.1** | `ImageRuleRefServiceImpl#delete`（约 575～598 行） | **`N = param.getIds().size()`** 次 `updateGroupPersonRef`（每规则删后各 1 次） | **P0**：全部 `deleteById` 完成后，对本轮涉及的 `labelIds`、`organizationIds` **去重并集**，调用 **1 次** `updateGroupPersonRef`；为每次 RPC 增加 **`isSuccess` 校验**（与 §2.2 一致） | **须图库/通行确认**：合并调用是否为「刷新引用」语义、是否等价于当前 N 次效果；若不能确认则**不得合并**，仅可补返回值校验与日志（**工作区走查与方案审核见 §6**） |
| **§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` | 增删楼层远程调用**墙钟**上界仍分别为 **A**、**D** 次；**有界并行**可缩短多楼层场景耗时（**迭代 5**，见 **§9**） | 内层 `imageRuleRefService.delete` 仍受 **§3.1 冻结** 时的 RPC 上界与语义约束；`@Async("updateFloorsExecutor")` 下背压与 `catch` 细粒度见 **§7.3** / **§9** |
---
## 2. 数量小结（便于排期）
| 类型 | 计数符号 | 含义 |
|------|----------|------|
| **§3.1 可合并 RPC** | 由 N 降为 **1**（在语义确认后） | 规则批量删除场景收益最大 |
| **§3.2 并行度** | P | 人员多 ID 删除 |
| **§3.3 并行度** | F | 楼层列表人数统计 |
| **§3.4 并行度** | D | 设备绑图库 |
| **§3.5** | A + D | 异步任务按层调用 |
---
## 3. 迭代规划与下一迭代范围（不改 HTTP/Feign 签名）
### 冻结范围（2026-04-25）
| 项 | 说明 |
|----|------|
| **约定 §3.1 全范围** | 未取得图库/通行对 `updateGroupPersonRef` 语义确认前，**不进行**与该约定相关的**任何**代码修正与优化（含 **合并 N→1** 及 §6.4 所述**仅 `isSuccess` 校验**小步），避免在无确认期分散实现与回滚成本。 |
| **恢复条件** | 图库书面或接口说明确认 + 在 [约定文档 §3.1](对外接口不变-远程调用与性能优化约定.md) 文末回填对接人、日期；再按 §1 表拆分 PR（合并与返回值校验可分步）。 |
| **前端相关** | 仓库**暂无可用前端**；所有需改**前端 / 登记页 / 物业端页面**的迭代**暂不排期、不执行**（与本文服务端走查无冲突；产品方案中 UI 类阶段见 [docs/README](../README.md#当前排期与范围2026-04)）。 |
### 迭代 3（**§3.5 `updateFloors`**）
| 字段 | 内容 |
|------|------|
| **状态** | **走查与首轮修正已完成**（见 **§7**）：`getById` 空防护、步骤级 `CloudwalkResult` 校验、`keepAliveSeconds` 绑定线程池。 |
| **约定锚点** | **§3.5** `AcsDeviceTaskServiceImpl#updateFloors` |
| **暂缓项** | 楼层有界并行**已**见 **§9**；`AbortPolicy` 与 `catch` 语义、其它见 **§7.3**。 |
### 迭代 4（**P1：§3.2 / §3.3 / §3.4 + 统一有界池**）
| 字段 | 内容 |
|------|------|
| **状态** | **已实施**（实现说明与语义边界见 **§8**）。 |
| **线程池 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（**§3.5 `updateFloors` 楼层有界并行**）
| 字段 | 内容 |
|------|------|
| **状态** | **已实施**（见 **§9**）：增楼列表、删楼列表在各自阶段内以最多 **6** 路**并发**执行 `add` / `addOnlyRule` / `delete` 等；**`BIND_DEVICES` 仍按原列表顺序**、每层成功**仍 +1** 重读任务行，与纯串行「进度语义」一致；子线程 Feign 经 `FeignThreadLocalUtil`；`ruleMap` 缺 `zoneId` 时用 **`getOrDefault(…, "")`** 防 NPE。 |
| **不变更** | **§3.1 全冻结** 期间未改 `ImageRuleRefServiceImpl#delete` 内 `updateGroupPersonRef` 次数。 |
### 迭代 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**。
---
## 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)` 仅取总数。
**修正实施后**：提交 **`e652eb3`**（分支 `v0.11`）。
---
## 6. 迭代 2：`ImageRuleRefServiceImpl#delete` 与 §3.1 方案走查（仅评估，未改代码）
**走查日期**：2026-04-25
**目标**：在全工作区定位**图库（intelligent 图库人员服务）**与**通行规则（电梯应用本地）**相关代码，审核「合并 `updateGroupPersonRef`」方案是否需图库侧语义确认后方可实施。
### 6.1 图库 / 通行相关代码位置（工作区）
| 层级 | 路径/符号 | 职责 |
|------|-----------|------|
| **Feign 契约** | `maven-intelligent-cwoscomponent/intelligent-cwoscomponent-rest/.../feign/ImageStorePersonFeignClient.java` | `POST .../updateGroupPersonRef`，请求体 `UpdateGroupPersonRefParam` |
| **DTO** | `maven-intelligent-cwoscomponent/intelligent-cwoscomponent-interface/.../param/UpdateGroupPersonRefParam.java` | `businessId`、`imageStoreId`、`personIds`、`labelIds`、`organizationIds`（可同时只填部分字段） |
| **客户端封装** | `.../service/RestImageStorePersonServiceImpl.java` | 透传 Feign |
| **电梯侧 §3.1 锚点** | `maven-cw-elevator-application/.../passrule/impl/ImageRuleRefServiceImpl.java` 方法 **`delete`**（约 571～605 行） | 按 `param.getIds()` 循环：`listByParentRule` → 收集子规则 `includeLabels` / `includeOrganizations` → **`deleteById`** → **`imageStorePersonService.updateGroupPersonRef`**（每删一条父规则 1 次 RPC） |
| **同文件其它 `updateGroupPersonRef`** | `addOnlyRule`（约 434～439）、`update` 内分支（约 556～562） | 新增/编辑规则后刷新；**同样未校验** `CloudwalkResult.isSuccess()` |
| **人员通行规则** | `maven-cw-elevator-application/.../person/impl/PersonRuleServiceImpl.java` | `add` / `addVisitor` / `delete` 末尾各 1 次 `updateGroupPersonRef`，入参以 **`personIds`** 为主（与 `delete` 以 **label/org** 为主不同） |
| **HTTP 入口** | `cw-elevator-application-web/.../AcsPassRuleController.java` | `imageRuleRefService.delete` |
| **异步任务调用** | `AcsDeviceTaskServiceImpl#updateFloors` | 删楼层时多构造 `deleteParam.setIds(Collections.singletonList(ruleId))` **逐层**调 `imageRuleRefService.delete`；单次 `delete` 内仍可能 1 次或多次 `updateGroupPersonRef`（视该层 `ids` 数量） |
**说明**：本仓库**无** intelligent 图库服务端的 `updateGroupPersonRef` 业务实现源码，仅能依据 DTO 与调用方推断语义；**与图库/通行团队确认**仍属 §3.1 前置条件。
### 6.2 当前 `delete` 行为摘要（与合并相关）
- `imageStoreId` 来自 **`deviceImageStoreDao.getByBuildingId(param.getParentId())`**，整次批量删除共用同一图库。
- 对每个待删父规则 `id`：先读**该父规则下子规则**的 label/org（子行若带 label 则 `continue`，**同一子行不会同时写入 org**，与数据模型一致），再删父规则，再带着**本轮** `includeLabels` / `includeOrganizations` 调图库刷新。
- **`updateGroupPersonRef` 的返回值未做 `isSuccess` 校验**（违反约定 §2.2；与 `getImageStorePerson` 等分支不一致）。
### 6.3 约定中的「合并」方案审核
| 维度 | 结论 |
|------|------|
| **与现网 N 次调用的等价性** | 若图库侧语义为：在**给定 `imageStoreId`** 下，对传入的 **labelIds / organizationIds 集合**做**增量刷新或按维度重算引用**（各维度独立、与顺序无关），则「删库前汇总所有待删父规则的子维度 → **去重并集** → 删库完成后 **1 次** `updateGroupPersonRef`」与「每删一条父规则刷新其维度子集」在**最终一致**上通常等价。 |
| **必须向图库确认的风险** | 若远端实现为「以本次入参**覆盖/裁剪**图库可见范围」或依赖**调用顺序**产生副作用，则合并后的**单次并集**与 N 次**子集递进**可能不等价。约定文档 §3.1 所述「非破坏性刷新」即针对此。 |
| **`personIds` 与 `labelIds`/`organizationIds` 混用** | `PersonRuleServiceImpl` 走 `personIds` 路径；`ImageRuleRefServiceImpl#delete` 走 label/org。合并方案**不改变** `delete` 仅设 label/org 的现状；但若图库服务在**未传 `personIds`** 时对空列表有特殊含义，仍须一并确认。 |
| **空列表仍 RPC** | 当前循环在子规则为空时仍调用 `updateGroupPersonRef`（两列表皆空）。合并后是否**跳过空并集**可减少无效 RPC，但属于**行为微调**，若图库依赖「空刷」触发全量重算，须图库确认后再定。 |
| **不合并时的安全增量** | 在未获图库书面确认前，**仅**可为每次 `updateGroupPersonRef` 增加 **`isSuccess` 校验 + 失败抛 `ServiceException`**（及可选日志），**不改变** RPC 次数；与约定「退化为循环调用 + 返回值校验」一致。 |
### 6.4 评估结论（是否允许进入 §3.1「合并」类代码修正）
- **合并 N→1**：**不允许在图库/通行确认前实施** — 与 §1 表及约定 §3.1 前置条件一致。
- **仅返回值校验（及可选空并集跳过，若产品同意）**：**允许作为独立小步** — 不依赖远端语义新假设，符合 §2.2。
**图库确认建议提问（可复制）**：「对同一 `imageStoreId`，`updateGroupPersonRef` 在仅设置 `labelIds`、`organizationIds`（`personIds` 为空）时，是否为**按这些维度刷新人员引用**且**不会**将图库维度裁剪为仅等于本次入参？多次调用子集与单次调用**并集**是否在业务上等价？」
**实施后回填**：确认结论、对接人、日期写入 [约定文档 §3.1 文末](对外接口不变-远程调用与性能优化约定.md)（见约定 §5）。
**排期决策（2026-04-25）**：在取得图库确认前，**冻结**约定 **§3.1** 相关全部代码变更；下一迭代转 **§3.5**（见上文 **「迭代 3」**）。
---
## 7. 迭代 3：`AcsDeviceTaskServiceImpl#updateFloors` 走查结论（§3.5）
**走查日期**：2026-04-25
**代码位置**：`cw-elevator-application-service/.../device/impl/AcsDeviceTaskServiceImpl.java` 方法 `updateFloors`；线程池 `.../common/UpdateFloorsTaskExecutor.java`；配置 `UpdateFloorsPoolProperties`（`ninca.update.floor.pool.*`，默认 core=3、max=5、queue=100、`AbortPolicy`）。
### 7.1 调用链与 RPC 上界（与 §1 表对齐）
| 分支 | 行为 | 上界 |
|------|------|------|
| 增楼层 | `personRuleService.add` **或** `imageRuleRefService.addOnlyRule`，成功后 `updateBingDevices` | `addFloors.size()` |
| 删楼层 | `personRuleService.delete` **或** `imageRuleRefService.delete`（单 id）**或** 仅 DAO `deleteByOrgAndLabel`，成功后 `updateBingDevices` | `delFloorIds.size()` |
| 内层放大 | `imageRuleRefService.delete` 仍受约定 **§3.1** 冻结影响（`updateGroupPersonRef` 多次）；本迭代**未**改该内层。 | 不变 |
**入口**：`AcsElevatorDeviceServiceImpl#bindingFloors` / `#bindingPerson` 在插入任务行后**同步**调用 `updateFloors`；方法带 `@Async`，实际在 **`updateFloorsExecutor`** 线程执行；HTTP 已返回 `taskId` 后，**异步内失败不会回写该 HTTP 响应**（现网行为保持；运维依赖任务进度与日志）。
### 7.2 检查项与结论
| 检查项 | 现状（走查时） | 结论 |
|--------|----------------|------|
| `acsDeviceTaskDao.getById` | 未判空即 `task.getIsStop()`，存在 **NPE** 风险（数据异常或竞态） | **不通过** → 已修正：空则记录并 `ServiceException` |
| `personRuleService.add/delete`、`imageRuleRefService.addOnlyRule/delete` 返回值 | 未校验 `CloudwalkResult.isSuccess()`，失败时仍 **`updateBingDevices`**，进度与真实绑定不一致 | **不通过**（违反 §2.2）→ 已修正：统一 `requireTaskStepSuccess`，失败抛错且**不**递增 |
| `catch` 仅 `ServiceException(e.getMessage())` | 丢失根因类型与栈信息到调用方；异步场景仅日志含 `{}` 与异常 | **记录**：是否改为 `ServiceException(code, msg)` 或 `initCause` 属产品/运维范围，**本轮不改** |
| 线程池 `keepAliveSeconds` | `UpdateFloorsPoolProperties` 有字段，**Bean 未 `setKeepAliveSeconds`**，配置项无效 | **缺陷** → 已在 `UpdateFloorsTaskExecutor` 绑定 |
| `RejectedExecutionHandler` | `AbortPolicy`，队列满时拒绝提交 | **记录**：与背压策略相关，**本轮不改**（须与运维对齐） |
| 删楼 `ruleMap.get(delFloorId)` | 若 `listZoneInfoByIds` 未覆盖某 `delFloorId` 可能 **null** 拼接 `ruleName` | **记录**：数据正常时风险低；**本轮未改**（可后续与 DAO 对齐） |
### 7.3 评估结论（是否允许进入代码修正）
- **允许并已实施（本轮）**：`task` 空指针防护；对 **`personRuleService.add` / `delete`**、**`imageRuleRefService.addOnlyRule` / `delete`** 的 **`CloudwalkResult` 成功校验**（约定 §2.2）；`updateFloorsExecutor` 绑定 **`keepAliveSeconds`**。
- **暂缓（须单独评审）**：拒绝策略、`catch` 异常语义增强；**楼层有界并行**与 `ruleMap` 缺键防护**已**见 **§9**。
**修正实施后**：提交 **`0ddeedc`**（分支 `v0.11`）。
---
## 8. 迭代 4：P1 有界并行（§3.2 / §3.3 / §3.4）
**实施日期**：2026-04-25
### 8.1 行为与约定对齐说明
| 项 | 说明 |
|----|------|
| **并发度** | 代码常量与默认池 **`corePoolSize=maxPoolSize=6`**（约定 4～8 区间内），可通过 **`ninca.elevator.remote-io.pool.core-pool-size` / `max-pool-size`** 覆盖。 |
| **§3.2 `delete`** | 多 `personId` 时按批 `ThreadPoolExecutor.invokeAll`；单 ID 仍走主线程（无 Feign 子线程问题）。失败时返回 **`76260407`** 风格 `CloudwalkResult.fail`，与改造前**一致**；**同批内**若某 RPC 失败，`invokeAll` 仍会等本批其它任务结束后再统一 `get()` 抛出/返回，与**严格单线程「第一条失败即不再发起后续」**在「已发起请求数」上略有差异，属典型有界并行取舍。 |
| **§3.3 `listFloor`** | 设备数仍顺序 DAO；`acsPersonService.page` 按批并行，结果写入 `personTotals[idx]` 后顺序 `setPersonNumber`，**响应楼层顺序不变**。 |
| **§3.4 `addImageStore`** | `bindAppImageStoreDevice` 仍顺序执行；仅 **`bindDeviceAndImageStore`** 按批并行；任一批次中失败则 **`rollbackImageStoreAfterBindFailure`**（抽方法）后抛 `ServiceException`，与原先 try/catch 回滚路径一致。 |
| **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`。
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 次数上界**、**下一可实施修正**、**在契约不扩展前提下不可做或须先确认** 的项。
docs/architecture/租户组织人员访客-数据模型与用例.md
+221
View File
@@ -0,0 +1,221 @@
# 租户 / 组织 / 人员 / 访客 — 数据模型、表关系与用例
**文档性质**：架构梳理（电梯仓 + 组织组件约定）。
**校验状态**：已使用 [`tools/visitor_floor_verification/.env.visitor_verify`](../../maven-cw-elevator-application/tools/visitor_floor_verification/.env.visitor_verify) 所列主机（本地开发库）执行 **`INFORMATION_SCHEMA` + 抽样查询**，纪要见 **§6.1**（日期 **2026-04-30**）。其它环境仍以现场库为准。
**关联精读**：[访客注册与派梯楼层 — 业务流程](../testing/visitor-registration-business-flow.md)、[租户访客默认楼层隔离边界](../testing/tenant-visitor-default-floor-isolation.md)。
---
## 1. 术语与请求上下文
| 术语 | 含义 | 典型落点 |
|------|------|----------|
| **租户 / 机构 ID** | 多租户数据隔离边界 | HTTP Header **`businessid`** → `FeignThreadLocalUtil` → `CloudwalkCallContext.company.companyId` |
| **`business_id`（库列）** | 与上下文 **`businessid`** 相同的字符串 | 组织库 `cw_is_organization.BUSINESS_ID`、`cw_is_person.BUSINESS_ID`；电梯库 `tenant_visitor_floor_policy.business_id`、`image_rule_ref.business_id` |
| **组织节点 ID** | 机构树上一节点（公司、部门等） | `cw_is_organization.ID`；父子关系 **`PARENT_ID` → `ID`** |
| **人员主键 `personId`** | API / 组件语境的人员 ID | 对应组织库 **`cw_is_person.ID`**（导出 CSV 列名为 **`ID`**） |
| **被访人** | 接待访客的员工 | `add/visitor` 请求体字段 **`personId`**（勿与访客混淆） |
| **访客** | 访客档案 | 请求体 **`visitorId`**；派梯写库时 **`image_rule_ref.person_id` = 访客 ID** |
**关键辨析**
- **`business_id` 不是 `cw_is_organization` 的主键**。组织节点主键为 **`ID`**；**`BUSINESS_ID`** 是在**同一租户下多行组织节点上重复出现**的作用域字段。
- 跨库之间**不存在**数据库级外键；一致性依赖 **`business_id`** 与 **`cw_is_person.ID`**（API 字段 `personId`）。关联表 **`cw_is_person_organization_ref.PERSON_ID`** 存储的也是该 **`ID`**。
---
## 2. 数据库边界（两库）
```mermaid
flowchart TB
subgraph orgLib [component_organization]
O[cw_is_organization]
P[cw_is_person]
R[cw_is_person_organization_ref]
L[cw_is_person_label_ref]
LB[cw_is_label]
end
subgraph elevLib [cw_elevator_application]
POL[tenant_visitor_floor_policy]
IRR[image_rule_ref]
end
O -->|"树 PARENT_ID"| O
R -->|"ORG_ID"| O
R -->|"PERSON_ID"| P
L -->|"PERSON_ID"| P
L -->|"LABEL_ID"| LB
POL -.->|"business_id 对齐 BUSINESS_ID"| P
IRR -.->|"business_id"| P
IRR -.->|"person_id 常为访客"| P
```
---
## 3. 逻辑 ER（组织库）
组织侧表无权威 DDL 收于本仓库；下列字段来自导出脚本、测试文档与 [`export_catalog.py`](../../maven-cw-elevator-application/tools/visitor_floor_verification/scripts/export_catalog.py) 中的 SQL 用法。
```mermaid
erDiagram
cw_is_organization {
string ID PK "组织节点"
string PARENT_ID FK "父节点 ID 可空"
string BUSINESS_ID "租户范围重复列"
string NAME "节点名称"
}
cw_is_person {
string ID PK "人员主键 API personId"
string BUSINESS_ID "租户"
string NAME "姓名"
int IS_DEL "是否删除"
}
cw_is_person_organization_ref {
string PERSON_ID FK "人员"
string ORG_ID FK "组织节点"
}
cw_is_organization ||--o{ cw_is_organization : "parent_child"
cw_is_person ||--o{ cw_is_person_organization_ref : "membership"
cw_is_organization ||--o{ cw_is_person_organization_ref : "org_node"
```
**`cw_is_person` 列名与访客判定**
- 仓库内导出示例 [docs/testing/_cw_is_person__202604302030.csv](../testing/_cw_is_person__202604302030.csv) 表头为 **`ID`**, **`BUSINESS_ID`**, **`IS_DEL`** 等，与 **2026-04-30 开发库**一致。
- 开发库 **`cw_is_person` 不存在**列：`person_id`、`deleted`、`labels`、`business_name`、`organization_name`。访客标签通过 **`cw_is_person_label_ref`**（`PERSON_ID`、`LABEL_ID`）关联 **`cw_is_label`**（含 `BUSINESS_ID`、`NAME`）；示例租户下 **`NAME='访客'`** 对应 **`LABEL_ID=ed2dbab6d6234a7287106b80857c819e`**。
---
## 4. 逻辑 ER（电梯库）
依据 [`tenant_visitor_floor_policy.sql`](../../maven-cw-elevator-application/releases/v2.0.0/ddl/tenant_visitor_floor_policy.sql) 与 [`ImageRuleRefMapper.xml`](../../maven-cw-elevator-application/cw-elevator-application-data/src/main/java/cn/cloudwalk/elevator/record/mapper/ImageRuleRefMapper.xml)。
```mermaid
erDiagram
tenant_visitor_floor_policy {
string id PK
string business_id "租户 UK 组成部分"
string policy_type "如 INTERSECT_ALLOWLIST"
text allow_zone_ids "JSON zoneId 数组"
string building_id "预留楼栋维度可空"
int enabled
bigint policy_version
}
image_rule_ref {
string id PK
string business_id
string zone_id "楼层区域"
string zone_name
string parent_rule "父规则"
string person_id "访客开通场景为访客"
int person_delete
string include_labels
string include_organizations
int is_default
}
```
**访客默认楼层策略语义（UC-01，未传 `floorIds`）**
- **规范**：启用租户访客策略且 **`allow_zone_ids` 非空**时，组织 **`PersonService.detail`** 应将 **`floorList` 替换为 `allow_zone_ids`（替代，非 ∩）**；电梯 **`addVisitor`** 仅使用 `personResult.getFloorList()`，**不再**在电梯侧与 allow 求交。
- 详见 [`PersonRuleServiceImpl#addVisitor`](../../maven-cw-elevator-application/cw-elevator-application-service/src/main/java/cn/cloudwalk/elevator/person/impl/PersonRuleServiceImpl.java)、[迁入组织组件规格](../superpowers/specs/2026-05-06-tenant-visitor-policy-organization-implementation.md) 与 [租户访客默认楼层-数据库配置阶段技术设计](../business/租户访客默认楼层-数据库配置阶段技术设计.md)。
---
## 5. 角色与派梯用例（电梯侧）
```mermaid
flowchart LR
actor Caller as Caller_BFF
participant API as AcsPersonController
participant PR as PersonRuleServiceImpl
participant Org as PersonService_detail
participant IRR as ImageRuleRefDao
participant Img as ImageStorePersonService
Caller -->|"POST_add_visitor"| API --> PR
PR --> Org
PR --> IRR
PR --> Img
```
```mermaid
flowchart TD
subgraph UC01 [UC01不传floorIds]
U1[add_visitor]
U2[detail_host_floorList已含策略替代]
U4[write_image_rule_ref_visitor]
U5[batchBind_visitor]
U1 --> U2 --> U4 --> U5
end
subgraph UC02 [UC02显式floorIds]
V1[add_visitor]
V2[detail校验被访人]
V2b[effective=请求floorIds]
V3[write_rules_bind]
V1 --> V2 --> V2b --> V3
end
subgraph UCRead [回读验收]
R1[passRule_image_personId_visitor]
end
```
---
## 6. 附录：现场核对 SQL 与纪要
### 6.1 开发库核对纪要（2026-04-30）
以下为使用 **`maven-cw-elevator-application/tools/visitor_floor_verification/.env.visitor_verify`**（主机、端口、账号由本地填写，**勿将密钥写入 Git**）连接所得摘要：
| 项目 | 结果 |
|------|------|
| 根机构 **`BUSINESS_ID=2524639890ba4f2cba9ba1a4eeaa4015`** | 节点 **`NAME=星河湾中心`**，`ID=d656e3ab3f61440bb7b9bc23b76834b9`，**与 `BUSINESS_ID` 字符串不相等** |
| `cw_is_person` | 主键列 **`ID`**；删除 **`IS_DEL`**；**无** `person_id`、`deleted`、`labels`、`business_name`、`organization_name` |
| `cw_is_organization` | 含 **`ID`、`PARENT_ID`、`BUSINESS_ID`、`NAME`、`IS_DEL`** 等（大量 `EXT*`） |
| `cw_is_person_organization_ref` | **`ID`、`PERSON_ID`、`ORG_ID`** 及审计列 |
| `cw_is_person_label_ref` / `cw_is_label` | 用于人员标签；访客标签 **`NAME='访客'`** 对应 **`LABEL_ID=ed2dbab6d6234a7287106b80857c819e`**（该租户） |
| `information_schema.TABLE_CONSTRAINTS` | 上述组织表 **仅有 `PRIMARY KEY` / `UNIQUE`**，**未声明 FOREIGN KEY** |
| `cw-elevator-application.tenant_visitor_floor_policy` | 列与仓库 DDL 一致；示例租户 **`enabled=1`**，`allow_zone_ids` 含 **`605560545117995008`** |
### 6.2 INFORMATION_SCHEMA 模板（任意环境）
```sql
-- 组织库：核心表列一览
SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'component-organization'
AND TABLE_NAME IN (
'cw_is_organization',
'cw_is_person',
'cw_is_person_organization_ref',
'cw_is_person_label_ref',
'cw_is_label'
)
ORDER BY TABLE_NAME, ORDINAL_POSITION;
-- 根节点与 BUSINESS_ID 是否相等（现场逐项核对）
SELECT ID, PARENT_ID, BUSINESS_ID, NAME
FROM cw_is_organization
WHERE BUSINESS_ID = '2524639890ba4f2cba9ba1a4eeaa4015'
ORDER BY ID
LIMIT 20;
-- 电梯库：策略表列
SELECT COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'cw-elevator-application'
AND TABLE_NAME IN ('tenant_visitor_floor_policy', 'image_rule_ref')
ORDER BY TABLE_NAME, ORDINAL_POSITION;
```
---
## 7. 文档索引（与本模型一致）
| 文档 | 用途 |
|------|------|
| [visitor-registration-business-flow.md](../testing/visitor-registration-business-flow.md) | 被访人 / 访客 / 楼层源码链路 |
| [visitor-registration-floor-validation.md](../testing/visitor-registration-floor-validation.md) | 测试矩阵与现场组织示例 |
| [tenant-visitor-default-floor-isolation.md](../testing/tenant-visitor-default-floor-isolation.md) | `business_id` 粒度与隔离边界 |
| [租户访客默认楼层-数据库配置阶段技术设计.md](../business/租户访客默认楼层-数据库配置阶段技术设计.md) | **替代**语义与迁移（历史文档含「求交」表述处以 2026-05-06 规格为准） |