docs(v0.11): 同步 Maven 聚合说明与本地编译文档

Made-with: Cursor

docs/architecture/Maven聚合工程说明.md

@@ -1,7 +1,7 @@
 # Maven 聚合工程说明（starRiverProperty）
 
-> **适用范围**：本仓库根目录下五个以 `maven-` 为前缀的 **Maven Reactor（聚合父工程）**，用于本地编译、走查与增量修改。  
-> **不适用范围**：各工程依赖的大量 **NINCA / 云从内部 JAR** 仍须通过 Nexus 等私服解析，本文仅描述**本仓库内可见的模块边界与协作关系**。
+> **适用范围**：本仓库根目录下以 `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 解析；本文描述**本仓库内可见的模块边界与协作关系**，补充反应堆仅覆盖文档化缺口中的一段。
 
 ---
 
@@ -13,7 +13,9 @@
 
 ---
 
-## 2. 五工程一览
+## 2. 工程一览
+
+### 2.1 主业务五工程
 
 | 仓库目录 | 聚合 artifactId（父 POM） | `groupId` | 版本（父 POM） | 子模块（`modules`） |
 |----------|---------------------------|-----------|----------------|----------------------|
@@ -23,6 +25,18 @@
 | `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)。
 
 ---
@@ -131,17 +145,96 @@
 
 ---
 
+### 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]
@@ -154,6 +247,10 @@ flowchart LR
   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
@@ -165,6 +262,7 @@ flowchart LR
 
 **文字归纳**  
 
+- **`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 公共栈**。
@@ -195,5 +293,5 @@ flowchart LR
 
 ## 7. 文档维护
 
-- 若新增第六个聚合工程，请在本表与各节补充 **目录、artifactId、modules、与其它工程的依赖边**。  
+- 若新增其它 `maven-*` 反应堆，请在本表与各节补充 **目录、artifactId、modules、与其它工程的依赖边**，并更新 [Maven工作区子工程版本一览](Maven工作区子工程版本一览.md) 与 [本地编译说明.md](../build/本地编译说明.md) §3。  
 - 若 Spring Boot / Cloud 版本升级，请以各 **`maven-*/pom.xml`** 为准同步更新本文「技术栈摘要」小节。