[ZhaoXingPeng]

关联 Issue

Closes #122

背景（Situation）

现有 scripts/verify_templates.py 能验证 Mustache 模板可被渲染且不存在未展开标签，但不能发现由导入、注解处理器、Jakarta API、Spring Data JPA 或 SpringDoc 依赖组合导致的 Java 编译错误。sb35-java21 是当前面向 Spring Boot 3.5 与 Java 21 的模板组，需要一条可复现的编译级门禁。

本 PR 不把固定样例扩展为真实数据库、应用启动或 HTTP 行为测试；这些属于后续集成测试范围。

任务（Task）

• 用代表性上下文渲染 sb35-java21 的 entity、dao、dto、service、serviceImpl、controller 六层代码。
• 用 Java 21 与 Maven 编译渲染结果，并在 CI 中把结果纳入汇总必需状态。
• 为渲染范围、版本约束、Maven 命令和临时目录清理行为添加单元测试与本地开发命令。

行动（Action）

• 新增 scripts/verify_java_compile.py：构造 Invoice 固定 fixture，覆盖 Long 主键、非空 BigDecimal、可空 OffsetDateTime、DTO、Lombok、Jakarta Validation/Persistence 与 SpringDoc 分支。
• 脚本写入独立临时 Maven 项目，使用 Spring Boot 3.5.5、Java 21、Spring Data JPA、Validation、SpringDoc 2.8.9 和 Lombok，执行 mvn -B -ntp -DskipTests clean compile。
• 成功时删除临时工程；编译失败或传入 --keep-fixture 时保留路径供诊断。新增 4 个单元测试覆盖源文件层级、版本锁定、非交互 Maven 命令和上述清理分支。
• CI 新增 java-compile job，使用 actions/setup-java@v5 安装 Temurin 21；ci-success 依赖该 job。开发文档补充相同本地命令。

验证（Verification）

本地环境：Windows 11 x86_64、Temurin 21.0.12.1、Maven 3.9.16。以下命令均在提交 bc2801c 的工作树执行：

$env:PYTHONPATH='src'; python -m pytest tests/unit/ -q
# 664 passed in 5.42s

$env:PYTHONPATH='src'; python scripts/verify_templates.py
# 26 个 Java 模板均成功渲染

$env:PYTHONPATH='src'; python scripts/verify_java_compile.py
# Compiling 6 source files with javac [release 21]
# BUILD SUCCESS

uv run --isolated --python 3.12 --with-editable . python scripts/verify_java_compile.py
# 安装项目的 53 个运行时依赖后，6 个源文件 BUILD SUCCESS（2.153s）

python -m ruff check scripts/verify_java_compile.py tests/unit/test_java_compile_smoke.py
python -m ruff format --check scripts/verify_java_compile.py tests/unit/test_java_compile_smoke.py
git diff --check
# 均通过

CI YAML 另以 yaml.safe_load 解析成功。最终的本机 compile run 也确认成功后的 fixture 路径不存在，符合默认清理约定。

实验与证据（Evidence）

实验	输入与方法	结果	可证明的边界
E1：编译级 smoke	固定 Invoice 上下文渲染六个 sb35-java21 模板；在临时 Maven 项目运行 batch compile	javac [release 21] 编译 6 个源文件，BUILD SUCCESS	可证明该代表性分支的源代码和所列依赖可在 Java 21 编译；不代表所有表结构或配置分支
E2：CI 同版本复验	Python 3.12 隔离环境安装 editable 项目后执行相同脚本	安装 53 个运行时依赖，Maven 编译成功	覆盖新 CI job 的 Python 主版本与项目依赖安装路径；本机操作系统仍不同于 GitHub Ubuntu runner
E3：临时诊断策略	单元测试分别执行成功默认、失败默认、显式保留三条清理分支	4 个 smoke 单元测试通过；成功 fixture 物理路径检查为 False	可证明脚本不会因成功编译留下 fixture；不模拟 Maven 下载失败或磁盘空间不足

没有测量性能指标，也没有运行真实数据库 DDL、CRUD、Spring Boot 应用启动或 HTTP 接口。现有 Testcontainers 集成套件保持独立，未据此宣称数据库兼容性提升。

兼容性、风险与回滚

• 兼容性：生成器模板和用户生成代码的公开 API 未改动；仅增加开发验证脚本、测试、文档和 CI job。
• 风险：新 job 会增加一次 Maven 依赖解析和编译时间；网络或 Maven Central 临时不可用会使 required CI 失败。setup-uv 与 GitHub Actions 缓存可减少重复安装，但不消除外部仓库可用性风险。
• 回滚：合并后如该门禁阻塞仓库，可 git revert bc2801c，撤回脚本、测试、文档和 java-compile required dependency，不涉及数据库迁移或用户数据回滚。
• 后续：在独立 Issue 中增加真实数据库生成样例或 Spring 上下文启动验证前，应先明确支持的模板组合与所需运行时依赖，避免把本 compile smoke 的结论扩大为运行时保证。

[ZhaoXingPeng]

里程碑 1：本地编译实验完成

结论。 提交 bc2801c 已在本机真实渲染并编译通过固定的 sb35-java21 fixture。此结论只覆盖该固定上下文的编译可行性，不覆盖真实数据库、Spring 容器启动、HTTP 行为或所有模板开关组合。

实验输入与取舍。 fixture 选用 Invoice，包含 Long id 主键、非空 BigDecimal amount、可空 OffsetDateTime createdAt，并开启 DTO、Lombok、Jakarta、SpringDoc。它同时拉通 entity、dao、dto、service、serviceImpl、controller 六层，刻意没有伪造数据库连接或业务映射行为。临时 POM 固定 Spring Boot 3.5.5、Java 21、Spring Data JPA、Validation、SpringDoc 2.8.9 与 Lombok，避免从调用方项目猜测依赖版本。

环境与命令。 Windows 11 x86_64；Temurin 21.0.12.1；Maven 3.9.16。

$env:PYTHONPATH='src'; python scripts/verify_java_compile.py

实际输出为 Compiling 6 source files with javac [debug parameters release 21]，随后 BUILD SUCCESS，耗时 2.209 s。Python 3.12 的 uv --isolated 环境也安装项目 53 个运行时依赖后复验通过，Maven 编译耗时 2.153 s。

辅助门禁。

$env:PYTHONPATH='src'; python -m pytest tests/unit/ -q
# 664 passed in 5.42s
$env:PYTHONPATH='src'; python scripts/verify_templates.py
# 26 个模板成功渲染
python -m ruff check scripts/verify_java_compile.py tests/unit/test_java_compile_smoke.py
python -m ruff format --check scripts/verify_java_compile.py tests/unit/test_java_compile_smoke.py
git diff --check

上述检查均通过。成功编译后的 fixture 路径经 Test-Path 验证为 False；失败和 --keep-fixture 分支由 4 个新单元测试覆盖，便于故障留档而不会污染成功路径。

风险、回滚与下一步。 新 CI 会受 Maven 中央仓库可用性和依赖下载时间影响，未改变任何生成器公开 API 或用户数据。若远端门禁阻塞，可回滚 bc2801c；其影响仅为撤销该验证 job、脚本、测试和文档。下一步等待 PR #123 的 metadata、Python quality、integration、templates、java-compile、docker 与 package job 实际完成。

[ZhaoXingPeng]

里程碑 2：远端 required CI 全量通过

工作流与提交。 GitHub Actions run 34207293444 针对 PR head bc2801cfd61f954b212dde8f8e79e9e7a4f4cc3e 执行；PR 当前 mergeStateStatus=CLEAN。

实际结果。 11 个检查均为 SUCCESS：Commit and PR policy（5s）、Changed-file format gate（21s）、Python quality 3.11/3.12/3.13（22s/23s/24s）、Template rendering contract（11s）、新增 Generated Java compile smoke（21s）、Database integration tests（42s）、Docker image smoke test（27s）、Python package build smoke test（16s）以及 Required CI status（3s）。

对新增门禁的含义。 Generated Java compile smoke 在 Ubuntu runner 上实际安装 Temurin 21、项目运行时依赖，并执行 scripts/verify_java_compile.py，因此远端独立确认了六个固定 fixture 源文件可由 Maven/JDK 21 编译。该 job 的成功不将编译结论扩大为 Spring Boot 启动成功、真实数据库 CRUD 成功、或所有 Mustache 分支均成功；这些边界与 PR 正文和里程碑 1 保持一致。

合并判断。 没有失败、取消或跳过的 required job，且仅有本 PR 的一个语义单一提交。将使用 squash merge；不包含数据库迁移，出现 CI 基础设施或维护成本问题时可回滚合并提交。