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）：

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-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（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），一般仅用于开发自检，不作为与现场等价对照。