starRiverProperty/backend/ninca-crk-from-lib/AGENTS.md

maven-ninca-crk-from-lib/ — lib 反编译对照工程

OVERVIEW

由交付 fat jar ninca-crk-std-backend-V2.9.2_20210730.jar 的 lib/ 目录中 28 个 ninca-crk-*-2.9.1_210630-SNAPSHOT.jar（四条业务线 × 七层）经 CFR 反编译得到的 Maven 聚合工程，仅用于走查与和现网构件对照，不替代官方多模块源码树。

生成方式

# 需 /tmp/cfr-0.152.jar；缺则先下载 CFR 0.152
python3 scripts/decompile_ninca_crk_lib_modules.py \
  "/path/to/ninca-crk-std-backend-V2.9.2_20210730.jar"

STRUCTURE

• 父工程：pom.xml（ninca-crk-from-lib-reactor）
• 子模块：*-interface、*-common、*-data、*-facade、*-biz、*-service、*-web（access-control / conference-attendance / smart-attendance / visitor-management 各一套）

说明

• 子模块 pom.xml 尽量保留 jar 内 META-INF/maven/**/pom.xml，并改挂本仓库父 POM。
• 四条 *-common：父工程已声明 dependencyManagement，并为各 common 补上与本仓库 maven-cloudwalk-legacy-public/cloudwalk-common-result（3.7.2-Brussels-SRX）、POI 3.15（与电梯工程一致）、Fastjson / Zip4j / ZXing / Servlet API 等坐标；访客 common 另含 spring-web、javax.annotation-api。
• cn.cloudwalk.cloud.*（如 CloudwalkBaseTimes、ServiceException、CloudwalkCallContext）来自 cloudwalk-common-result。编译前请先装入本地仓库，任选其一：
  • 源码安装：cd maven-cloudwalk-legacy-public && mvn install -pl cloudwalk-common-result -am -DskipTests
  • 交付包 lib/：对同名 cloudwalk-common-result-*.jar 执行 mvn install:install-file（版本号需与 ${cloudwalk.common.result.version} 一致）。
• 更高层模块（*-data/*-service/*-web）仍未逐项对齐依赖，整仓 mvn compile 可能继续报错属预期。

ENTRY POINTS

• 无 @SpringBootApplication 主类（本工程为库集合，非独立应用）
• Controllers: 44 个（@RestController），分布于四条业务线的 *-web 模块
• Service Implementations: 94 个（*ServiceImpl）
• Feign 客户端: 1 个（SmsFeign.java，visitor-management-interface）
• 走查入口：ninca-crk-*-web/src/main/java/…/controller/ → 对应 *-service 实现

MODULE COMPLEXITY

模块	Java 文件	备注
smart-attendance-common	207	最复杂：44 个 bean/rule DTO，见 AGENTS.md
access-control-interface	139	Feign 接口 + 参数/结果 DTO
access-control-common	126	QrcodeUtils + 共享工具
其余 26 模块	<110	同构七层模式，根文档覆盖

BUILD PATTERNS

• quartz：仅 portal-resource-stubs 和 conference-attendance-facade 引用
• Spring Boot 2.1.x：仅 conference-attendance-facade，其他模块均用 Spring 4.3.x
• formatter-maven-plugin：版本由父 maven-cloudwalk-cloud/pom.xml 属性控制（2.24.1），引用 docs/style/alibaba-eclipse-codestyle.xml
• javax.servlet-api：部分模块用 provided scope（如 conference-attendance-web）

关联

• 可维护源码入口仍见 maven-ninca-crk/ninca-crk-gpu-std/。

源码正确性走查（CFR，2026-04-30）

规模与用途

• 约 1542 个 .java，28 子模块（四条业务线 × 七层：interface / common / data / facade / biz / service / web）。
• 定位：对照走查与检索，不以「可直接 mvn compile 的工程」为前提。

Maven 与编译

• JDK：父 POM 固定 java.version = 1.8，并通过继承的 maven-compiler-plugin 统一 source / target；子模块不再重复声明编译器属性。maven-enforcer-plugin 在 validate 阶段执行 requireJavaVersion（[1.8,1.9)），须用 JDK 8 启动 Maven，否则会失败。
• 源码侧：access-control-common 等处已用 java.util.Base64 等替代 JDK 内部 API，避免字节码/源码在其他 JDK 上偶然编译时出现符号缺失（与本 reactor 强制 JDK 8 跑 Maven 互为补充）。
• 父 POM 已集中管理 cloudwalk-common-result、Apache POI、Fastjson、Zip4j、ZXing、Guava、Ant、thumbnailator、commons-io、spring-web、javax.servlet-api、javax.annotation-api 等版本；须先安装 cloudwalk-common-result（见上文「说明」）。
• 验证单个 common：cd maven-ninca-crk-from-lib/ninca-crk-access-control-common && mvn -q compiler:compile -DskipTests。
• *-interface 及以上仍缺依赖时需按编译报错逐项补充或使用交付 …/ninca-crk-std-backend-V2.9.2_20210730/lib 中对应 JAR install-file。

CFR 头注释：Could not load the following classes

• 绝大部分 .java 在文件头带有 CFR 列举的「未能加载的类型」，紧接着仍有正常的 import。这是 反编译时 classpath 不完整 的提示，不等于该类在源码树中缺失或方法体必然错误。
• 走查样例：AcsDeviceController、VisitorController 等在注释中列出的类型，下文 import 与调用仍完整可读。

已核实的共性风险（非「猜」）

1. CollectionUtils.split 泛型（四套 *-common）：已从 CFR 误生成的 ArrayList<List<ArrayList<E>>> 修正为 ArrayList<List<E>>（含 split(List, int...) 内同名局部变量）。
2. QrcodeUtils / ExcelUtil / CollectionUtils（access-control-common，并已同步三套 *-common）：去掉 JDK 内部 Base64、field.getType() 误写 Class<Comparable<Date>>，以及 CFR 带来的若干泛型不匹配，便于在 JDK 8、-source/-target 1.8 下通过编译。
3. BusinessIdShardingAlgorithm：catch (UnsupportedEncodingException) 内 throw new UnsupportedOperationException() 无Cause、无信息——可能为字节码等价实现，也可能是反编译简化；若需与现网严格一致应以 class 对照或原始源码为准。
4. 未发现 全树规模上的 /* synthetic */ 标记；UnsupportedOperationException 除上述分表算法与各校 CollectionUtils 拷贝外未见异常模式。

按业务线小结（逐「子模块集合」）

业务线	模块前缀	走查要点
门禁 / 访客相关 API	ninca-crk-access-control-*	open 电梯/记录、device/record/person 与现网电梯应用 Feign 命名可交叉对照；web 层 Spring 注解与表单类完整
会议考勤	ninca-crk-conference-attendance-*	与 access-control 同构七层；common 工具/DTO 与 access-control 风格一致
智能考勤	ninca-crk-smart-attendance-*	含 ShardingSphere 分表算法等 data 层；依赖外部坐标在 POM 中未体现
访客管理	ninca-crk-visitor-management-*	与电梯侧访客/Feign 对照价值最高；*-interface/*-service/*-web CFR 头注释密集，语义仍以正文为准

结论

• 逻辑与接口层面的走查：可作为阅读现网构件行为的参考，尤其 interface + controller + service impl 链路。
• 「源码正确性 = 可编译且与 jar 字节码等价」：当前树 仍不满足（Maven 依赖未补齐）；CollectionUtils.split 泛型 已在四份 common 中修正，可编译性少一类硬性类型错误。