patbond-doc/docs/development/iterations/iteration-1/07-backend-baseline-report.md

07 后端工程基线改造报告（第一迭代）

• 执行人：Senior Developer
• 日期：2026-09-03
• 仓库：patbond-api（改动全部留在工作区，未提交）
• 范围：ADR-001（升 Boot 3）、ADR-002（移除 Nacos）落地 + 审计问题 B1（零测试）、M2（common 依赖污染）、M3（无 Maven Wrapper）、M4（启动文档/配置）整改。不含数据库、JWT、refresh token、OpenAPI（后续工单）。

---

1. 所升版本

项	原值	新值	说明
Spring Boot	2.7.18	3.5.16	3.5 线最新补丁版（写作时 Maven Central 实查）
Spring Cloud	2021.0.9	2025.0.3	与 Boot 3.5 配套版本线；仅使用 OpenFeign
Spring Cloud Alibaba	2021.0.6.0	移除	ADR-002；BOM、两个 nacos starter、spring.config.import 全部删除
Java 基线	17（source/target）	17（<release>17</release> + <parameters>true</parameters>）	release 严格锁定 API 基线；-parameters 是 Boot 3.2+ 参数名推断的硬要求
命名空间	javax.validation	jakarta.validation	6 个源文件迁移，源码中已无任何 javax.*
构建工具	依赖本机 mvn	Maven Wrapper（mvnw，Maven 3.9.16）	mvn wrapper:wrapper 生成

本机默认 JDK 为 26，构建/运行统一以 JAVA_HOME=/usr/lib/jvm/java-17-openjdk 执行（README 已写明）。

2. 改动文件清单

pom（4 个，修改）

• pom.xml：Boot/Cloud 版本升级、删 Alibaba BOM、compiler 改 release+parameters、pin surefire 3.5.2。
• patbond-common/pom.xml：瘦身为纯契约模块——只保留 jakarta.validation-api（compile）+ spring-boot-starter-test（test）；删除 web/amqp/openfeign/loadbalancer/nacos-discovery/nacos-config/hutool/lombok（M2 关闭，对齐开发计划 4.1）。
• patbond-user/pom.xml：自持 starter-web、starter-validation（原经 common 传递），保留 spring-security-crypto，新增 starter-test。
• patbond-auth/pom.xml：自持 starter-web、starter-validation、spring-cloud-starter-openfeign（不显式引 loadbalancer），新增 starter-test。

Java 源码（6 个，修改）

• patbond-auth/.../client/UserClient.java：@FeignClient(name = "patbond-user", url = "${patbond.user-service.url}")（ADR-002 静态地址）。
• AuthController.java、LoginRequest.java、RegisterRequest.java、UserController.java、CreateUserRequest.java、VerifyPasswordRequest.java：javax→jakarta。

配置（按用户中途指示采用 sample 模式：application.yml 保持 git 忽略，sample 入库）

• 更新 patbond-user/src/main/resources/application.yml.sample（去 Nacos；PATBOND_USER_PORT:8082）。
• 更新 patbond-auth/src/main/resources/application.yml.sample（去 Nacos；PATBOND_AUTH_PORT:8081、patbond.user-service.url: ${PATBOND_USER_SERVICE_URL:http://127.0.0.1:8082}）。
• .gitignore：保留 application.yml 忽略 + .sample 白名单规则（去掉的是 Nacos 时代的内容而非规则本身）。
• 新增 patbond-auth/src/test/resources/application.yml（测试专用配置）：干净检出无 application.yml 时 @SpringBootTest 仍可启动上下文，./mvnw clean test 不依赖复制步骤（已实测：移走本地 yml 后 clean test 依旧 BUILD SUCCESS）。
• 本机的两个真实 application.yml 保留在磁盘（被忽略，不入库），供本地 spring-boot:run 使用。

测试（5 新增，共 21 个用例）

• patbond-common/src/test/.../ApiResponseTest.java（3）。
• patbond-user/src/test/.../UserApplicationTests.java（context loads）+ UserControllerTest.java（9：创建成功/重复 409/参数非法 400、verify-password 成功/错密码 401/未知用户 401、getById 200/404、getByUsername 200+404）。
• patbond-auth/src/test/.../AuthApplicationTests.java（context loads）+ AuthControllerTest.java（7）：UserClient 用 @MockitoBean 替换，不依赖 user 进程；按现状行为断言（业务失败折叠为 400、FeignException 未翻译逃逸 MVC 层）。

其他

• Readme.md：重写——技术栈更新、去 Nacos/RabbitMQ、Maven Wrapper 真实启动命令（含 sample→yml 复制步骤）、环境变量表、内存存储现状注记（M4 关闭）。
• 新增 mvnw、mvnw.cmd、.mvn/wrapper/maven-wrapper.properties。
• 清理三个模块旧 target/（其中 auth/user 的 target/classes/application.yml 曾硬编码 http://patbond.cn:8848/nacos）；全仓 grep 确认除测试注释中对 ADR-002 的引用外无任何 nacos/8848 残留。

3. 验收执行记录

3.1 JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test

[INFO] Tests run: 3, ...  -- in com.patbond.patbond.common.response.ApiResponseTest
[INFO] Tests run: 1, ...  -- in com.patbond.patbond.user.UserApplicationTests
[INFO] Tests run: 9, ...  -- in com.patbond.patbond.user.controller.UserControllerTest
[INFO] Tests run: 7, ...  -- in com.patbond.patbond.auth.controller.AuthControllerTest
[INFO] Tests run: 1, ...  -- in com.patbond.patbond.auth.AuthApplicationTests
[INFO] patbond-api ........................................ SUCCESS
[INFO] patbond-common ..................................... SUCCESS
[INFO] patbond-user ....................................... SUCCESS
[INFO] patbond-auth ....................................... SUCCESS
[INFO] BUILD SUCCESS

合计 21 个测试，0 失败 0 错误（B1 的"0 测试空转"状态解除）。 首轮曾失败：@PathVariable 参数名反射不可用——Boot 3.2+ 行为变化，已在父 pom 加 -parameters 修复后全绿。 补充验证：临时移走两个本地 application.yml（模拟干净检出）后重跑 clean test，仍 BUILD SUCCESS——测试不依赖被忽略的本地配置。

3.2 干净配置启动验证（真实进程，验证后已全部停止）

./mvnw -pl patbond-common install 后两个服务分别 spring-boot:run：

Tomcat started on port 8082 ... Started UserApplication in 1.691 seconds
Tomcat started on port 8081 ... Started AuthApplication in 1.789 seconds

端到端冒烟（auth 经静态 URL Feign 调 user）：

POST /auth/register → {"code":0,...,"userId":1,"username":"smoketest",...}
POST /auth/login    → {"code":0,...,"accessToken":"5c44a5d3...",...}
POST /auth/login（错密码） → HTTP 500        ← 已知问题，见 4.1
GET  /internal/users/1（8082） → {"code":0,...,"username":"smoketest",...}

验证后进程已终止，ss 确认 8081/8082 端口释放，无遗留后台进程。

注意事项：单独 -pl 启动前必须先 install patbond-common，否则会从 ~/.m2 拿到旧快照（首次启动失败正是踩到旧 common 里的 nacos 依赖）；README 启动步骤已包含该命令。

4. 遗留问题（均为计划内后续工单，非本次回归）

1. 错误状态码折叠（审计 M1）：user 返回的 401/409 经 Feign 变成 auth 侧 500/400。AuthControllerTest.loginPropagatesFeignExceptionUnhandled 已把现状钉死为基线，统一异常契约工单动工时该测试会按新契约改写。
2. B2 三件套未动：内存用户存储、不可验证 token、/internal/** 无访问控制——属数据库/JWT 后续工单，本次仅在 README 中如实标注。
3. 无 CI 配置（审计 M3 后半）：Wrapper 已就位，./mvnw clean test 已可作为门禁命令，但 CI 载体（如 GitHub Actions）仍缺。
4. AuthTokenResponse.expiresAt 仍为无时区 LocalDateTime，不符 ISO 8601 约定，随 token 重构一并处理。
5. 旧 common 快照仍在本机 ~/.m2，已被本次 install 覆盖；其他开发机拉取后需重新 ./mvnw -pl patbond-common install。