guanlan-src/app_backEnd/backend-java

观澜 v2 · 后端（Java + Spring Boot + Swagger）

用户令 2026-09-29：后端完全用 Java + Spring Boot + Swagger 实现（与算法模块经接口交互， 行为与重构前一致，替换后删除对应 Python 源码）。本目录是这条线的起步工程（P12）。

1 现状：链路已通，接口待逐条迁移

项	状态	证据（2026-09-29 实测）
离线编译	✅	mvn -o compile 通过（JDK 1.8.0_202 + Maven 3.8.9 + 用户本地仓）
启动	✅	java -cp target/classes;target/lib/* com.guanlan.backend.GuanlanBackendApplication
Java → 算法服务	✅	GET /java/healthz → {"ok":true,"algorithm_ok":true,"algorithm_version":"2.17.0",...}
Swagger UI	✅	/swagger-ui/index.html 200 · /v3/api-docs 200（OpenAPI 3.0.3）
算法端点代理	✅	GET /java/algorithm/endpoints → 11 个只读端点；/java/algorithm/{name} 按白名单取数
与重构前一致性	⏳	对拍基准是 app_backEnd/app_backEnd_guanlan/contract/http_api_v1.json（42 条端点），逐条迁移、逐条对拍

2 构建与运行（离线）

本机 Maven 仓是残缺的，mvn package 打不出 jar（见 §3 的实逮），所以走 mvn -o compile + 自组装 target/lib/：

python app_backEnd/backend-java/build_offline.py            # 编译 + 组装 target/lib + 打印启动命令
python app_backEnd/backend-java/build_offline.py --run       # 编译后直接起服务（默认 28120）

离线设置文件：F:\temp\_h9\mvn_settings.xml（localRepository 指到用户仓 + offline=true）。 交付形态：随包 JRE 1.8 + target/classes + target/lib/*（或将来能打 fat jar 时改回单 jar）。

3 离线实逮（本机仓缺什么，怎么绕）

现象	原因	处置
mvn package 报 plexus-utils:jar:1.1 has not been downloaded	老版 maven-jar-plugin 3.2.2 的 POM 牵出 plexus-utils 1.1，本机仓只有 1.0.4/1.4.1/…/3.4.1	pom 里给 jar 插件显式顶 plexus-utils:3.4.1
同上，指到 maven-archiver:3.6.0 也缺	本机仓没有 maven-archiver（jar 插件运行期依赖）	放弃 package，改走 compile + 自组装 lib（build_offline.py）
surefire 解析失败（缺 surefire-api/booter/common）	本机仓只有插件本体	pom 把 default-test 绑到 phase=none（本期无单测；测试在 Python 侧契约门里）
打不了 fat jar	缺 spring-boot-loader-tools:2.7.18	spring-boot-maven-plugin 设 skip=true，交付用 classes + lib/
启动即 NoClassDefFoundError: org/mapstruct/factory/Mappers	springfox 3 的映射器运行期要 mapstruct，但它未随 springfox 传递	pom 显式加 org.mapstruct:mapstruct:1.3.1.Final
Springfox 在 Boot 2.6+ 启动失败	路径匹配策略变了	application.yml 设 spring.mvc.pathmatch.matching-strategy=ant_path_matcher

这些都是本机离线环境的实情；到有网/有内网 Maven 源的环境里，把 §3 的绕法逐步换回标准做法即可 （打 fat jar、跑 surefire、加 springdoc）。

4 后续（按冻契约逐条迁移）

1. 按 http_api_v1.json 把现有 Python 后端的 42 条端点搬进本工程（先读接口与静态页，再读 /api/*）；
2. 每搬一条，用 scripts/http_contract_audit.py（Python 门）与 Node 侧冒烟对拍：方法/状态/顶层键一致；
3. 网关按前缀灰度切换（/detail、/cms 指到 Java 或 Python），任一不符立即切回；
4. 全部对拍通过后，才删对应的 Python 后端源码（用户令）。
5. Gateway/Nacos/OAuth2+JWT 待依赖到位（本机仓缺 spring-cloud-gateway、spring-cloud-starter-oauth2、 spring-boot-starter-security；Maven 源不可达）后接入；在此之前保持单体形态。