# 观澜 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/`：

```bash
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 源不可达）后接入；在此之前保持**单体**形态。