🐛 fix(codegen): 规范无前缀模板输出路径

[ZhaoXingPeng]

关联 Issue

Closes #165

背景（Situation）

TemplateConfigManager.get_output_path_mapping() 使用 entity/{packageSuffix}/{className}.java 等模板。旧的 JavaCodeGenerator._get_output_path() 在 packageSuffix 为空时直接格式化，得到 entity//Account.java、dao//AccountDao.java 等双分隔符路径。Windows 当前能容忍该路径，但它会污染返回文件路径、日志和下游脚本；跨平台路径比较也可能出现不一致。

任务（Task）

在不改变模板内容、包声明、文件名、输出目录边界或原子 MCP 路径合同的前提下，规范旧 Java 生成器的相对输出路径：空后缀不产生空目录段，有前缀时保留独立包目录。

行动（Action）

• 提交：60b1f2a
• 在 JavaCodeGenerator._get_output_path() 的占位符格式化后调用标准库 os.path.normpath，把归一化限定在静态模板相对路径边界。
• 新增无前缀、有 sys_* 前缀和实际写盘返回路径回归测试。
• 机械格式化本次触碰的历史未格式化 Python 文件，以满足 changed-file format gate；没有改变运行逻辑。
• 不重构原子 codegen 的 _resolve_codegen_output_path，避免扩大公共 MCP 行为；不新增 ADR，这是局部路径实现修复。

验证（Verification）

环境：Windows，仓库 .venv，Python 3.12.12，pytest 9.1.1，Ruff 来自 .venv。

python -m pytest tests/unit/ -q
688 passed in 11.81s

ruff check src/ tests/ scripts/
All checks passed!

ruff format --check（本次修改的 Java generator 与测试文件）
2 files already formatted

git diff --check
无输出

实验与证据（Evidence）

• 固定 Account 表输入、packageSuffix=""：归一化前可复现 out\\entity//Account.java，当前返回相对路径 entity/Account.java。
• 固定 sys_account 与 sys_role 表输入：前缀分析得到 system，当前返回 entity/system/SysAccount.java，没有丢失包层级。
• generate_from_table(..., include_dto_vo=False) 实际写盘后，返回路径相对输出目录为 entity/Account.java，文件存在且仍包含 class Account 与 private Long id。
• 没有运行真实 MySQL/PostgreSQL 或性能实验；这是纯路径格式修复，不宣称吞吐收益。

兼容性、风险与回滚

• 兼容性：模板类别、模板内容、包声明、文件名和输出目录参数保持不变；仅移除由空占位符产生的重复分隔符。
• 风险：os.path.normpath 遵循宿主平台路径规则；模板映射是仓库内静态相对路径，不接受用户提供的任意路径片段。
• 回滚：恢复单一提交 60b1f2a 即可；不涉及数据库、配置迁移或生成物。
• 依赖：本 PR base 为 fix/163-mcp-json-boundary，待前置 PR 🐛 fix(mcp): 统一跨工具驱动值 JSON 序列化 #162、🐛 fix(mcp): 收口全部 MCP 响应 JSON 序列化 #164 按顺序合并后再以 main 为最终基线检查。

后续（Next）

合并前只对最终 HEAD 检查一次 required checks；若未来新增模板映射，继续通过路径回归测试验证空段、前缀和跨平台行为。

[ZhaoXingPeng]

实现完成（2026-09-09）

当前结论

Issue #165 已实现并推送。旧 JavaCodeGenerator 的空 packageSuffix 路径现在在格式化后经 os.path.normpath 归一化，entity//Account.java 不再暴露给调用方；有前缀时包目录保持不变。

变更与设计取舍

• 提交：60b1f2a
• 归一化位于输出路径边界，模板映射和模板内容不变；使用标准库路径语义，避免手写替换误伤合法段。
• 新增无前缀、sys_* 前缀和实际写盘路径测试。
• 本 PR 以 fix/163-mcp-json-boundary 为 base，仅包含本主题一个新增提交，依赖前置序列化 PR 的合并顺序。

验证与证据

• python -m pytest tests/unit/test_java_generator.py tests/unit/test_template_context_builder.py -q：78 passed。
• python -m pytest tests/unit/ -q：688 passed in 11.81s。
• ruff check src/ tests/ scripts/：All checks passed!。
• ruff format --check（2 个变更 Python 文件）：2 files already formatted。
• git diff --check：无输出。

兼容性与下一步

• uv.lock 保持用户未跟踪状态，未进入提交。
• 未查询 CI；按约束只在准备 squash merge 前检查一次 required checks。
• 待前置 PR 🐛 fix(mcp): 统一跨工具驱动值 JSON 序列化 #162、🐛 fix(mcp): 收口全部 MCP 响应 JSON 序列化 #164 合并后，将本 PR base 切回 main 做最终审查。

[ZhaoXingPeng]

验证完成（2026-09-09）

当前结论

路径回归和完整单元测试均已完成。测试证明空后缀和前缀后缀两种输出路径都稳定，实际文件写盘结果与返回值一致；没有观察到模板内容或既有类别注册回归。

变更与设计取舍

• 提交：60b1f2a
• 输入一：Account 表、空 packageSuffix，归一化后的相对路径为 entity/Account.java。
• 输入二：sys_account、sys_role 表，前缀分组为 system，相对路径为 entity/system/SysAccount.java。
• 输出路径使用 Path(...).relative_to(output_dir) 断言，避免把 Windows 分隔符差异误判为功能差异。

验证与证据

• python -m pytest tests/unit/ -q：688 passed in 11.81s。
• 新增断言覆盖 _get_output_path 以及 generate_from_table 实际写盘文件存在性。
• ruff check src/ tests/ scripts/：All checks passed!。
• ruff format --check（本次变更文件）：2 files already formatted。
• git diff --check：无输出。
• 未运行真实数据库、Java/Maven 或性能实验；本次只修复本地路径字符串。

兼容性与下一步

• 公共生成器方法签名、模板类别和输出文件名保持不变；回滚提交为 60b1f2a。
• CI 尚未查询，准备 squash merge 时再检查一次最终 HEAD 的 required checks。
• 后续新模板路径应继续补充空段和前缀回归，避免重新引入双分隔符。