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

# Maven 聚合工程说明（starRiverProperty）

> **适用范围**：本仓库根目录下五个以 `maven-` 为前缀的 **Maven Reactor（聚合父工程）**，用于本地编译、走查与增量修改。  
> **不适用范围**：各工程依赖的大量 **NINCA / 云从内部 JAR** 仍须通过 Nexus 等私服解析，本文仅描述**本仓库内可见的模块边界与协作关系**。

---

## 1. 文档目的

- 说明五个聚合工程各自的 **业务定位、子模块划分、技术栈选型原因**。
- 说明工程之间的 **Maven 依赖与调用链上的协作**（与 `docs/business/` 中接口走查互补：本文偏「工程与构件」，走查文档偏「接口与数据流」）。
- 说明 **`maven-*`** 目录与 **`artifacts/decompiled/`**（源码归档，目录名 `decompiled` 为历史约定）、**运行包目录** `cw-elevator-application-V1.0.0.20211103/` 的分工，避免混淆「可改源码树」与「仅对照归档」。

---

## 2. 五工程一览

| 仓库目录 | 聚合 artifactId（父 POM） | `groupId` | 版本（父 POM） | 子模块（`modules`） |
|----------|---------------------------|-----------|----------------|----------------------|
| `maven-cloudwalk-cloud/` | `cloudwalk-cloud-reactor` | `cn.cloudwalk.cloud` | `3.7.2-Brussels-SRX` | `cloudwalk-cloud-common`、`cloudwalk-common-event`、`cloudwalk-common-service` |
| `maven-cw-elevator-application/` | `cw-elevator-application-reactor` | `cn.cloudwalk.elevator` | `1.0-SNAPSHOT` | `cw-elevator-application-common`、`data`、`service`、`web` |
| `maven-intelligent-cwoscomponent/` | `intelligent-cwoscomponent-reactor` | `cn.cloudwalk.intelligent` | `2.9.2-xinghewan` | `intelligent-cwoscomponent-parent`、`interface`、`rest` |
| `maven-ninca-crk/` | `ninca-crk-reactor` | `cn.cloudwalk.ninca` | `1.0.0` | `ninca-crk-gpu-std` |
| `maven-ninca-qk-alarm/` | `ninca-qk-alarm-reactor` | `cn.cloudwalk.ninca` | `0.0.2-SNAPSHOT` | `ninca-qk-alarm-app-starter`（其下再含 web / interface 等子模块） |

---

## 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 能力；与电梯、智能组件无强绑定，相对 **独立部署单元**。

---

## 4. 工程间依赖与协作（简图）

下列关系表示 **Maven 依赖 / 常见运行时调用方向**，非严格部署拓扑。

```mermaid
flowchart LR
  subgraph cloud [maven-cloudwalk-cloud]
    CE[cloudwalk-common-event]
    CS[cloudwalk-common-service]
  end
  subgraph intel [maven-intelligent-cwoscomponent]
    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
  CE --> ES
  CS --> ES
  IR --> ES
  ES --> EW
  CE --> GPU
  IR -.->|可能被 exclusion| GPU
  CS --> ST
```

**文字归纳**  

- **电梯应用** 依赖 **公共云模块** + **智能组件 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. 文档维护

- 若新增第六个聚合工程，请在本表与各节补充 **目录、artifactId、modules、与其它工程的依赖边**。  
- 若 Spring Boot / Cloud 版本升级，请以各 **`maven-*/pom.xml`** 为准同步更新本文「技术栈摘要」小节。