starRiverProperty/docs/superpowers/data/2026-05-06-component-org-full-java-audit-and-remediation.md

# 组织组件：全量 Java（src/main/java）与部署包逐类核对及解决方案

**日期：** 2026-05-06（**2026-05-06 已执行 P0~P2 落地**，见下节）  
**范围：** `maven-ninca-common-component-organization` 下全部 `**src/main/java`** 源文件，与部署目录  
`部署包/ninca_common_component_organization_01-ninca_common_component_organization/ninca-common-component-organization-V2.9.2_20210730`  
内 `**BOOT-INF/classes` + 四模块 `*-v2.9.2_xinghewan.jar**` 中的字节码 **逐类 `javap -p` 比对**。

---

## 0. 执行记录（P0 → P1 → P2）


| 阶段     | 内容                                                                                                                                                                                                                                                                                                                                                                                                   | 结果                                                                                                                                                                 |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **P0** | 使用 **JDK 8**（`JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64`）执行 `mvn clean package -DskipTests`；抽查 Fat JAR 内嵌 `cwos-component-organization-service-*.jar` 中含 `TenantVisitorFloorPolicyService`、`OrganizationRedisLuaConfiguration`、`ElevatorFeignClientFallback` 等新增类。                                                                                                                                 | **通过**：产物 `cwos-component-organization-starter/target/ninca-common-component-organization-2.9.2-xinghewan.jar`（约 96MB）。**说明：** 必须用 JDK 8 编译，JDK 11+ 会因注解处理器模块封装报错。 |
| **P1** | 用 **CFR 0.152**（`tools/cfr-0.152.jar`，Maven Central 自动下载）反编译现场 `**BOOT-INF/classes/cn/cloudwalk/starter`** 打成的 mini-jar，源码迁入 `**starter/src/main/java**`；`**SelfRegistryHandler**` 从现场 **service** JAR 反编译迁入 `**service/.../SelfRegistryHandler.java`**，并手工修正泛型与 `**CloudwalkResult`/`AtomicDeviceGetResult**` 等与 `**CertRegistryHandler**` 对齐；修正 `**MbGenerator`/`ComponentTaskInitialize**` 反编译瑕疵。 | **通过**：`deploy_only_outer_types` **由 23 降为 0**（源码侧已覆盖原「仅部署」顶层类型）；全仓 `**src/main/java` 现为 605**（+23）。                                                               |
| **P2** | 重新运行 `**deploy_javap_audit.py`**（对齐后的契约快照）。                                                                                                                                                                                                                                                                                                                                                          | **MISSING_DEPLOY 仍为 18**；**DIFFERENT 已降至 18**（`OpenCvUtils`、三工具类构造等已与现场 **IDENTICAL**）；**IDENTICAL 569**（以最新 `tools/out/deploy_javap_audit_main.json` 为准）。  |


**复跑命令（JDK 8）：**

```bash
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"
cd maven-ninca-common-component-organization
mvn -q clean package -DskipTests
python3 tools/deploy_javap_audit.py --workers 16 \
  --write-json tools/out/deploy_javap_audit_main.json \
  --write-markdown tools/out/deploy_javap_audit_main.md
```

**自动化脚本路径：** `maven-ninca-common-component-organization/tools/deploy_javap_audit.py`  
**产物：** `tools/out/deploy_javap_audit_main.json`（全量每文件状态）、`tools/out/deploy_javap_audit_main.md`（节选表）。

**延续审核（Lua / lib / Data JAR XML / 配置）：** [`2026-05-06-component-org-source-vs-deploy-continued-audit.md`](./2026-05-06-component-org-source-vs-deploy-continued-audit.md)  
**现场替换清单：** [`2026-05-06-component-org-release-checklist.md`](./2026-05-06-component-org-release-checklist.md)

---

## 1. 汇总统计（P2 复跑后）


| 状态                       | 数量      | 含义                                                                      |
| ------------------------ | ------- | ----------------------------------------------------------------------- |
| **IDENTICAL**            | **569** | 部署包与当前 `mvn compile` 产物 `**javap -p` 完全一致**（顶层类型签名一致）。                  |
| **DIFFERENT**            | **18**  | 同 FQN 下字段/方法列表等与现场 **不一致**（含业务变更或编译器 synthetic/lambda 差异）。              |
| **MISSING_DEPLOY_JAVAP** | **18**  | 本地可解析，部署 classpath **无该类** → **仓库新增、现场 JAR 未包含**（需 **发布 P0 制品** 后线上才有）。 |


另：**「仅部署侧顶层类型」** 经 **P1 补源码** 后，脚本统计 `**deploy_only_outer_types = 0`**（见 `deploy_javap_audit_main.json`）。

---

## 2. 总体解决方案（决策树）

1. **以现场为权威（线上稳定优先）**
  - 将 **现场 Fat JAR** 或其中 **四模块 JAR** 纳入制品库；CI 对发布分支构建产物做 `**javap` 契约校验**（或与现场 JAR 二进制对齐）。  
  - 对下面 §4 **DIFFERENT** 类：若需与线上一致，应从 **与现场同源的标签/分支** 迁出代码，或 **接受当前仓库为超前版本** 仅做回归后再发版。
2. **以仓库为权威（迭代与星河湾定制优先）**
  - **发布新版 Fat JAR**，替换现场 `ninca-common-component-organization-V2.9.2_20210730.jar`。  
  - **MISSING_DEPLOY（18）** 全部为仓库侧新增能力（租户访客策略、Redis Lua 装配、大量 Feign Fallback）→ **必须随新版本部署**，否则线上不存在这些类。  
  - **补齐 Starter 源码与资源**（§5），使 **本仓库可完整复现** 现场同等启动行为。
3. **非 Java 资产（与本次 javap 并行结论）**
  - **Lua**：源码 `service/.../lua` 与部署 `BOOT-INF/classes/lua` **已批量 diff 一致**。  
  - **MyBatis XML**：现场 Data JAR 内含 `**mapper/mysql/*.xml`**，仓库 data 模块 **未见同名 XML 提交** → 发布前需 **补齐 XML 与仓库一致** 或 **确认由依赖 JAR 提供**。  
  - **配置**：根目录 `application.properties` 覆盖 BOOT-INF；修正无效行 `**新增配置`**，核对 cron 与 **xhw*** 等业务常量。

---

## 3. MISSING_DEPLOY_JAVAP（18）：仓库有、现场包无 —— 处置

**结论：** 现场运行的是 **旧世代制品**；下列类型已在仓库 **新增或拆分**，需 **升版部署** 后才能与线上一致（或在线上删除引用——不推荐）。


| #    | FQN                                                                                             | 源文件                                                    |
| ---- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| 1    | `cn.cloudwalk.data.organization.entity.TenantVisitorFloorPolicy`                                | `data/.../TenantVisitorFloorPolicy.java`               |
| 2    | `cn.cloudwalk.data.organization.mapper.TenantVisitorFloorPolicyMapper`                          | `data/.../TenantVisitorFloorPolicyMapper.java`         |
| 3    | `cn.cloudwalk.service.organization.config.GroupPersonSynExecutorConfiguration`                  | `service/.../GroupPersonSynExecutorConfiguration.java` |
| 4    | `cn.cloudwalk.service.organization.config.GroupPersonSynPoolProperties`                         | `service/.../GroupPersonSynPoolProperties.java`        |
| 5    | `cn.cloudwalk.service.organization.config.OrganizationRedisLuaConfiguration`                    | `service/.../OrganizationRedisLuaConfiguration.java`   |
| 6    | `cn.cloudwalk.service.organization.policy.TenantVisitorFloorPolicyService`                      | `service/.../TenantVisitorFloorPolicyService.java`     |
| 7–18 | 各类 `*FeignClientFallback` / `EnterpriseFeignClientFallback` / `PineappleEngineClientFallBack` 等 | `service/.../feign/*.java`、`corp/feign/*.java`         |


**解决方案：**  

1. **数据库：** 已若有租户访客策略表结构，保证 **现场 MySQL 与迁移脚本** 与文档一致。
2. **发布：** 使用本仓库 `**mvn package` 产出的 Fat JAR** 替换现场；配置中打开/对齐 **Redis Lua、线程池、Feign** 相关项。
3. **验证：** 租户访客相关 API + 图库同步 + Feign 降级路径 **集成测试**。

---

## 4. DIFFERENT（18）：签名不一致 —— 分类与处置

### 4.1 Starter 入口（结构性）


| FQN                                                    | 说明                                                                                                                                                | 建议                                                                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `cn.cloudwalk.starter.organization.OrganizationServer` | 现场：**继承 `SpringBootServletInitializer`**，含 **Micrometer、RestTemplate、WAR `configure`** 等；仓库：**极简 `main` + `CloudwalkSessionContextHolder` Bean**。 | **二选一：** (A) 从历史制品/分支 **回收完整 `OrganizationServer` 与 Starter 配置类源码** 入仓库；(B) 明确 **仅支持可执行 Jar 模式**，现场改造启动脚本与监控接入以匹配仓库。 |


### 4.2 Service 公共工具与抽象类（多为编译/细节差异风险）

含：`AbstractImagStoreService`、`ImageEditUtils`、`ImageUtil`、`JsonUtils`、`OkhttpUtil`、`OpenCvUtils`、`ToolUtil`、`ChannelFileReader`。

**逐类核对（DIFFERENT 剩余清单）：** [`2026-05-06-component-org-different-22-per-class-review.md`](./2026-05-06-component-org-different-22-per-class-review.md)（`OpenCvUtils` 已与现场对齐；其余多为 synthetic/**`ImgPersonServiceImpl`** 业务超前等）。

**建议：**  

1. 对每一类执行 `**javap -p` diff 存档**（已由脚本隐含）；若仅 **lambda/synthetic 行** 变化 → **加强集成测试**；若 **公开方法增减** → 走 **代码评审与回归**。
2. 锁定 **JDK 8** 与 **Maven 编译器插件** 版本，减少无谓字节码漂移。

### 4.3 图库 / 设备同步核心业务类

含：`CertRegistryHandler`、`CpDeviceImagePersonServiceImpl`、`CpImageStorePersonManager`、`CpImageStorePersonSynManager`、`CpImageStorePersonValidateManager`、`CpImageStoreServiceImpl`、`CpImageStoreToolServiceImpl`、`DeviceGroupRefChangeEventHandler`、`DevicePersonSyncManager`、`DevicePersonSyncServiceImpl`、`ImgPersonServiceImpl`、`OrganizationServiceImpl`。

**建议：**  

1. `**ImgPersonServiceImpl`**：仓库已含 **租户访客楼层策略** 相关成员与方法 → **领先现场**；发版或回退策略见 §2。
2. `**CpImageStoreToolServiceImpl`** 等：重点复核 **批量删脸、同步日志** 等与现场故障（如 **COUNT 溢出、图片为空**）相关路径。
3. 与 **电梯 / Portal Feign** 联调验证。

### 4.4 Web


| FQN                                                                   | 建议                                                               |
| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `cn.cloudwalk.web.organization.controller.DevicePersonSyncController` | `**javap` 与现场不一致**：核对接口路径、参数 DTO、是否新增接口；做 **API 对拍**（现场 vs 新版本）。 |


---

## 5. 部署包多出、源码未收录问题（P1 已处理）

原 `**deploy_only_outer_fqns` 约 23 项**（含 `**SelfRegistryHandler`**、Starter 下 config/kafka/multipart/task/mybatis 等）已通过 **§0 P1**（CFR 反编译 + 手工修正）迁入仓库；**当前审计脚本 `deploy_only_outer_types = 0`**。

后续维护应以 **本仓库源码** 为准，避免再次只剩 `.class`；生成器 `**MbGenerator`** 内含示例 JDBC 连接串，仅本地生成代码时使用，**勿将密码提交到共享分支外的场景滥用**。

---

## 6. IDENTICAL（569）

约占 `**src/main/java`（605）的 **94.0%**，明细见 `**deploy_javap_audit_main.json`** 中 `status == "IDENTICAL"` 条目。

---

## 7. 与先前抽样文档的关系

早期抽样结论仍有效：`**PersonController`、`CpOrgDeviceKitController**` 在本次 **全量核对中均为 IDENTICAL**；**全量结果** 显示 `**DevicePersonSyncController` 为 DIFFERENT**，需在发版前单独核对。

更早期的简报：`[2026-05-06-component-org-deploy-vs-source-batch-diff-and-javap.md](./2026-05-06-component-org-deploy-vs-source-batch-diff-and-javap.md)` —— 已由 **本文件 + JSON** 取代为 **权威全量清单**。

---

## 8. 附录：测试源码（可选）

若需包含 `**src/test/java`**，运行：

`python3 tools/deploy_javap_audit.py --all-sources ...`

预期大量 `**MISSING_DEPLOY_JAVAP**`（测试类不会打进现场 Fat JAR），**一般仅用于开发自检**，不作为与现场等价对照。