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

Made-with: Cursor

docs/build/本地编译说明.md

@@ -18,21 +18,79 @@ java -version   # 应显示 1.8.x
 
 ## 3. 推荐编译顺序（依赖链）
 
-在仓库根下按顺序 **install**（或至少 **compile** 前序模块并 install 到本地 `~/.m2`）：
+在仓库根下按顺序 **install**（或至少 **compile** 前序模块并 install 到本地仓库；若使用自定义 `settings.xml` 的 `localRepository`，构件会写入该路径）：
 
-1. **`maven-cloudwalk-cloud`**：`mvn -DskipTests clean install`  
-2. **`maven-intelligent-cwoscomponent`**：`mvn -DskipTests clean install`（依赖 cloudwalk 与私服 `cloudwalk-device-sdk` 等）  
-3. **`maven-cw-elevator-application`**：`mvn -DskipTests clean install`  
-4. 其余：`maven-ninca-crk`、`maven-ninca-qk-alarm` 按需单独编译。
+1. **`maven-cloudwalk-device-sdk`**：`mvn -DskipTests clean install` — 提供 **`cn.cloudwalk:cloudwalk-device-sdk:2.2.0`** 父 POM 与 **`cloudwalk-device-sdk-protocol-entity`**（替代私服缺失父工程）。  
+2. **`maven-cloudwalk-legacy-public`**：`mvn -DskipTests clean install` — 自 **`反1/*.jar.src.zip`** 提供 **`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`**（闭合 **`cloudwalk.legacy.public.version`**、**`cwos.sdk.event`**、电梯 **lock** 等；**须在 `maven-cloudwalk-cloud` 之前**安装，以便 **`cloudwalk-common-event`** 解析 **`cwos-sdk-event`**）。  
+3. **`maven-cloudwalk-device-manager`**：`mvn -DskipTests clean install` — 自 **`反1/cloudwalk-device-manager-*-2.0.2.jar.src.zip`** 提供 **`cn.cloudwalk.cloud:cloudwalk-device-manager:2.0.2`** 父 POM 与 **`cloudwalk-device-manager-common`**、**`cloudwalk-device-manager-interface`**（依赖第 2 步的 **`cloudwalk-common-result`**；**须在依赖其 interface 的其它工程之前**安装）。  
+4. **`maven-cwos-resource`**：`mvn -DskipTests clean install` — 提供 **`cwos-component-resource`**、**`cwos-portal`** 父 POM 及 **`cwos-java-sdk-resource`** 等（替代私服缺失的 CWOS 资源/门户父链）。  
+5. **`maven-cloudwalk-intelligent-davinci-manager`**：`mvn -DskipTests clean install` — 提供 **`cn.cloudwalk.intelligent:cloudwalk-intelligent-davinci-manager:1.1.7-SNAPSHOT`** 父 POM 与 **`davinci-manager-common`**、**`davinci-manager-storage`**（替代私服缺失的 Davinci 父链；与电梯 **`davinci.manager.storage.version`** 对齐）。  
+6. **`maven-cloudwalk-cloud`**：`mvn -DskipTests clean install` — 提供 **`cloudwalk-common-event`**、**`cloudwalk-common-service`** 等（**`maven-cwos-device-authentication`** 依赖 **`cloudwalk-common-service`**，故 **aks / device-authentication 须排在本步之后**）。  
+7. **`maven-cwos-common-aks`**：`mvn -DskipTests clean install` — 自 **`反1/cwos-common-aks-interface-1.0.0-SNAPSHOT.jar.src.zip`** 提供 **`cn.cloudwalk.cloud:cwos-common-aks:1.0.0-SNAPSHOT`** 与 **`cwos-common-aks-interface`**（依赖第 2 步 **`cloudwalk-common-result`**）。  
+8. **`maven-cwos-device-authentication`**：`mvn -DskipTests clean install` — 自 **`反1/cwos-device-authentication-interface-1.0.0-SNAPSHOT.jar.src.zip`** 提供 **`cn.cloudwalk.cloud:cwos-device-authentication:1.0.0-SNAPSHOT`** 与 **`cwos-device-authentication-interface`**（依赖第 1、3、6、7 步及 **`cwos-common-aks-interface`**）。  
+9. **`maven-intelligent-cwoscomponent`**：`mvn -DskipTests clean install`（依赖第 1 步的 **protocol-entity** 与 cloudwalk 模块）  
+10. **`maven-cw-elevator-application`**：`mvn -DskipTests clean install`（`service` 若仍失败，多为其它私服构件或业务源码问题，见下文）  
+11. 其余：`maven-ninca-crk`、`maven-ninca-qk-alarm` 按需单独编译。
 
 单工程示例：
 
 ```bash
-cd maven-cloudwalk-cloud && mvn -DskipTests clean install
+cd maven-cloudwalk-device-sdk && mvn -DskipTests clean install
+cd ../maven-cloudwalk-legacy-public && mvn -DskipTests clean install
+cd ../maven-cloudwalk-device-manager && mvn -DskipTests clean install
+cd ../maven-cwos-resource && mvn -DskipTests clean install
+cd ../maven-cloudwalk-intelligent-davinci-manager && mvn -DskipTests clean install
+cd ../maven-cloudwalk-cloud && mvn -DskipTests clean install
+cd ../maven-cwos-common-aks && mvn -DskipTests clean install
+cd ../maven-cwos-device-authentication && mvn -DskipTests clean install
 cd ../maven-intelligent-cwoscomponent && mvn -DskipTests clean install
 cd ../maven-cw-elevator-application && mvn -DskipTests clean compile
 ```
 
+**说明**：`maven-cwos-resource` 内 **`cwos-portal-interface`** 已按 **`cwos-java-sdk-resource`** 实际引用面裁剪（仅保留 `common`/`enterprise`/`user` 等与 SDK 相关的包），并含 **`cwos-device-pkg-stub`** 占位 **`DeviceUpgradeResult`**；与线上一致「全量 portal 接口」不等价，仅用于 **本地编译闭合**。
+
+**与 `cw_lib` 的 outer 类对照**：可用仓库根目录下 **`scripts/compare_jar_to_sources.py`**（参数为 **`cw-elevator-application-V1.0.0.20211103/cw_lib` 中某 `.jar` 的绝对路径** + **对应 `maven-*` 子模块目录**），快速检查 JAR 内每个 outer 类是否在源码树中有同名 `.java`；**`cwos-portal-interface`** 因裁剪会出现大量「缺失」，属预期。**`package-info.java`** 可能报告为「多出的源码」，一般可忽略。
+
+### `cw_lib` 审核结论摘要（outer 类级，相对 `cw-elevator-application-V1.0.0.20211103/cw_lib`）
+
+| 类型 | 模块 / 构件 | 结论 | 原因说明 |
+|------|----------------|------|----------|
+| **JAR 有类、本地缺 outer `.java`** | 除 **`cwos-portal-interface`** 外，与 `cw_lib` 成对映射的 **`maven-*` 子模块** | **未发现** | 已用脚本对 `cw_lib` 内各业务/公共 JAR 全量扫描；**仅** portal 因裁剪出现大量「缺失」。 |
+| **JAR 有类、本地缺 outer `.java`** | **`maven-cwos-resource/cwos-portal-interface`** | **约 438 个 outer 类无对应 `.java`** | **有意裁剪**：仅保留 **`cwos-java-sdk-resource`** 实际引用到的包，与 **`cw_lib` 全量 `cwos-portal-interface`** 不对等；非反编译丢文件。 |
+| **本地有业务类型、对应 JAR 无 outer 类** | **`cw-elevator-application-data`**：`TenantVisitorFloorPolicyDao` / `Dto` / `DaoImpl` / `Mapper` | **4 个类型仅存在于本地** | **`cw_lib` 中 `cw-elevator-application-data` / `service` JAR 均无 `TenantVisitor` 相关 `.class`**；与运行包相比，当前 Maven 源码含 **租户访客默认楼层策略** 增量（见 [租户访客默认楼层-数据库阶段变更记录.md](../business/租户访客默认楼层-数据库阶段变更记录.md)），属**业务演进**，不是「从 JAR 反编译漏解压」。 |
+| **本地多 `package-info.java`** | 若干模块 | 可忽略 | JAR 未必含 `package-info.class`，脚本会将 `package-info` 记为「多出」。 |
+| **占位桩** | **`cwos-device-pkg-stub`** | 无同名「全量」于 `cw_lib` | 仅为 **`DeviceUpgradeResult`** 等编译占位，与 portal 裁剪配套。 |
+| **无 `src/main/java`（非缺陷）** | **`maven-cloudwalk-cloud/cloudwalk-cloud-common`**（**`4.0.0-Brussels-SRX`**）与 **`maven-cloudwalk-legacy-public/cloudwalk-cloud-common`**（**`3.7.2-Brussels-SRX`**） | **目录下仅有 `pom.xml`，`packaging=pom`** | **`cloudwalk-cloud-common` 在上游即为 BOM/聚合父 POM**，不提供带 `.class` 的业务 JAR；**`cw_lib` 中也不存在 `cloudwalk-cloud-common-*.jar`**，只有各子构件（如 **`cloudwalk-common-result`**）的 `pom` 把 parent 指向该坐标。工作区维护 **两套版本**：**3.7.2**（与 **`反1`** / 历史 JAR 的 parent 一致）与 **4.0.0 stub**（与电梯等 **`cloudwalk.internal.version`** 对齐），**勿混用**。详见 [Maven聚合工程说明](../architecture/Maven聚合工程说明.md)（「为何存在 `cloudwalk-cloud-common` 子模块」及 **§3.x** 中 3.7.2 / 4.0.0 说明）。 |
+
+**说明**：outer 类级对照**不能**发现「同一类内方法体与线上一致」；若需核对 **service** 内既有类（如 **`PersonRuleServiceImpl`**）与 `cw_lib` 字节码是否一致，应对该类单独做反编译 diff 或回归测试。
+
+### `maven-*` 子模块走查：无 `src/main/java`（属正常，非「缺解压」）
+
+以下路径**仅有父 `pom.xml`、无 Java 源码目录**，`packaging` 为 **`pom`**，用于 **BOM / 聚合 / 占位**，与私服中「只发 POM、不发 JAR」的构件一致；**勿**当作反编译漏文件去 **`反1`** 补同名 `src`。
+
+| 路径 | 作用简述 |
+|------|----------|
+| **`maven-cloudwalk-cloud/cloudwalk-cloud-common`** | **`4.0.0`** 父坐标桩，见上文审核表。 |
+| **`maven-cloudwalk-legacy-public/cloudwalk-cloud-common`** | **`3.7.2`** 父 POM，承接 **`cloudwalk-common-result` / `web` / `serial`**。 |
+| **`maven-cwos-resource/cwos-component-resource`** | **`cwos-component-resource`** 聚合父。 |
+| **`maven-cwos-resource/cwos-portal`** | **`cwos-portal`** 聚合父。 |
+| **`maven-intelligent-cwoscomponent/intelligent-cwoscomponent-parent`** | intelligent 组件父 POM。 |
+| 各 **`maven-*/pom.xml` 反应堆根** | 仅 `pom` 聚合，无 `src`。 |
+
+### 反编译（JD-Core）遗留批量排除
+
+大量 **`反1`** 解压的 `.java` 含 **行首 `/*    */` / `/* N */`** 及文件尾部 **`/* Location: ... * JD-Core Version: ... */`**。已提供脚本在 **`maven-*`** 树内批量剔除（**不改**业务逻辑，仅删注释噪声；**`artifacts/decompiled/`** 下归档树默认不处理，除非显式传入路径参数）：
+
+```bash
+cd /path/to/反编译
+# 先预览将改动的文件数
+python3 scripts/strip_jdcore_java_noise.py --dry-run
+# 实际写回（默认处理仓库根下全部 maven-* 目录）
+python3 scripts/strip_jdcore_java_noise.py
+```
+
+写回后建议对常用反应堆执行 **`mvn -DskipTests clean compile`** 做抽样验证。
+
 ## 4. 版本与私服坐标说明
 
 - **`cloudwalk.internal.version`（如 4.0.0-Brussels-SRX）**：表示本仓库 **`cloudwalk-common-event` / `cloudwalk-common-service`** 等**已迁入源码**构件的版本。  
@@ -46,7 +104,7 @@ cd ../maven-cw-elevator-application && mvn -DskipTests clean compile
 |------|------|
 | `maven-cloudwalk-cloud` | 在可访问 Nexus 时，`mvn clean install` 可通过。 |
 | `maven-cw-elevator-application` 之 **common / data** | 已补齐 `spring-web`、`CollectionUtils` 与部分 DTO 反编译错误后，`mvn clean compile` 可编过至 **data** 模块。 |
-| `cw-elevator-application-service` | 依赖 **`cwos-component-resource`、`cwos-portal`、`davinci-manager-storage`** 等父工程，**须私服完整** 方可继续解析。 |
+| `cw-elevator-application-service` | **`cwos-*-resource` / `cwos-portal`** 父链可由 **`maven-cwos-resource`** 本地 install 解决；**`davinci-manager-storage`** 由 **`maven-cloudwalk-intelligent-davinci-manager`**；**`cloudwalk-common-result`/`web`/`serial`、`cwos-sdk-event`、`cloudwalk-intelligent-component-lock`** 由 **`maven-cloudwalk-legacy-public`**（**`反1`** zip）；若仍失败，多为 **其它私服构件** 或 **业务源码**（如反编译残留语法错误）。 |
 
 若仅修改电梯 **data/service 内业务代码**，可在完整依赖环境执行：
 
@@ -57,4 +115,74 @@ mvn -pl cw-elevator-application-service -am -DskipTests clean compile
 
 ---
 
+## 6. 编译日志排查（典型失败链）
+
+以下与一次真实日志一致：`cloudwalk-cloud` 成功 → `intelligent-cwoscomponent-interface` 失败 → 电梯 **common/data** 成功 → **service** 失败。
+
+### 6.1 第一层失败：`intelligent-cwoscomponent-interface`
+
+| 现象 | 含义 |
+|------|------|
+| `Failed to read artifact descriptor for ... cloudwalk-device-sdk-protocol-entity:jar:2.2.0` | 解析该 JAR 的 **有效 POM** 时失败。 |
+| `cloudwalk-device-sdk:pom:2.2.0 (absent) was not found in ... maven-public` | 私服 **没有** 或 **路径不对**：父构件 **`cn.cloudwalk:cloudwalk-device-sdk:2.2.0`**（packaging `pom`）未发布到当前使用的 `repository/maven-public`。 |
+| `This failure was cached in the local repository` | Maven 已把「解析失败」缓存在本地（`~/.m2` 或你配置的 **`localRepository`**，如日志中的 `/data/local/repo`），在 **update 间隔** 内会**不再重试**，表现为持续失败。 |
+
+**处理建议**（择一或组合）：
+
+1. 在 Nexus 补齐 **`cn.cloudwalk:cloudwalk-device-sdk:2.2.0`**（含 `protocol-entity` 子模块坐标），或改用团队约定的 **其他仓库**（`settings.xml` 里增加 `mirror`/`repository`）。  
+2. 强制刷新缓存后重编：  
+   `mvn -U -DskipTests clean install`（`-U` 即 `--update-snapshots`，并促使重新检查 release 元数据）。  
+3. 若确认私服已修好，可删除本地缓存目录后再编（路径示例，按坐标替换）：  
+   `rm -rf ~/.m2/repository/cn/cloudwalk/cloudwalk-device-sdk`  
+   若 `localRepository` 为 `/data/local/repo`，则同样删除其下 `cn/cloudwalk/cloudwalk-device-sdk`。
+
+`intelligent-cwoscomponent-interface` 直接依赖见：
+
+```29:32:maven-intelligent-cwoscomponent/intelligent-cwoscomponent-interface/pom.xml
+        <dependency>
+            <groupId>cn.cloudwalk</groupId>
+            <artifactId>cloudwalk-device-sdk-protocol-entity</artifactId>
+        </dependency>
+```
+
+（版本由反应堆 `dependencyManagement` 中的 **`cloudwalk.device.sdk.version`** 指定。）
+
+---
+
+### 6.2 第二层失败：`cw-elevator-application-service`（依赖未装全时的连锁）
+
+| 现象 | 含义 |
+|------|------|
+| `cwos-component-resource:pom:1.0.0-SNAPSHOT` absent | 接口包 **`cwos-component-resource-interface`** 所引用的 **父 POM** 未在私服。 |
+| `cwos-portal:pom:1.0.0-SNAPSHOT` absent | 同上，**`cwos-portal-interface`** 的父工程未发布。 |
+| `cloudwalk-intelligent-davinci-manager:pom:1.1.7-SNAPSHOT` absent | **`davinci-manager-storage`** 的父 POM 未在私服（或曾失败被缓存）。 |
+| `The POM for ... intelligent-cwoscomponent-rest:jar:3.0.0-xinghewan is missing` | 因 **6.1** 失败，**interface/rest 未 install** 到本地仓库，电梯解析 `intelligent-cwoscomponent-rest` 时只能报「无 POM/无依赖信息」。 |
+
+**结论**：`service` 的失败 **不是** 电梯业务源码语法问题，而是 **Maven 依赖图不完整**（私服缺件 + 上一步 intelligent 未成功）。
+
+**处理建议**：先解决 **6.1** 并执行 `maven-intelligent-cwoscomponent` 全量 `install` 成功；对 **cwos / davinci** 父链优先在本仓库执行 **`maven-cwos-resource`**、**`maven-cloudwalk-intelligent-davinci-manager`** 的 `install`；其余缺失再在 Nexus 补齐，或对构件执行 **`mvn install:install-file`** 安装到本地/私服。
+
+---
+
+### 6.3 警告（非本次失败主因，可后续治理）
+
+| 日志 | 说明 |
+|------|------|
+| `cloudwalk-common-web:jar:3.7.2-Brussels-SRX is invalid` … `cloudwalk-common-result` / `jsoup` **version is missing** | 私服上该 JAR 内嵌的 **POM 不完整**，Maven 构建「有效模型」时告警；**传递依赖可能不完整**。当前 **common/data** 已通过，但若运行期缺类，需在电梯反应堆 **`dependencyManagement`** 中显式补 `jsoup` 等版本。 |
+| 同上对 **`cloudwalk-common-serial`** 的 invalid 警告 | 同上，多为历史发布物 POM 质量问题。 |
+
+---
+
+### 6.4 推荐复现命令（修私服 / 清缓存后）
+
+```bash
+export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
+export PATH="$JAVA_HOME/bin:$PATH"
+cd maven-cloudwalk-cloud && mvn -U -DskipTests clean install
+cd ../maven-intelligent-cwoscomponent && mvn -U -DskipTests clean install
+cd ../maven-cw-elevator-application && mvn -U -DskipTests clean install
+```
+
+---
+
 *随 POM 与私服策略变更请更新本文。*