starRiverProperty/maven-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 聚合工程**，仅用于走查与和现网构件对照，**不替代**官方多模块源码树。

## 生成方式

```bash
# 需 /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](ninca-crk-smart-attendance-common/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 中修正，可编译性少一类硬性类型错误。