📚 docs(roadmap): 整理 v0.3 后续架构与功能路线

[ZhaoXingPeng]

关联 Issue

Refs #116

背景（Situation）

v0.2.x 已具备 MCP 工具、跨方言元数据、原子代码生成、schema 图算法、MCP Apps、AI 语义增强和基础可观测性，但后续工作原先散落在 README、ADR 和 benchmark。路线图 PR 创建后，main 又合入协作内容/编码门禁和主页元数据维护；旧 PR 正文及路线图仍写 658 项测试和过时的正文格式，不能作为当前执行入口。

任务（Task）

将 v0.3 路线图合入当前 main，记录正确基线、已存在的 Testcontainers 证据和剩余 P0 缺口，并将后续 Issue/PR 协议与新七段 PR 正文门禁对齐。该 PR 只规划，不提前实现任何 P0 运行时代码。

行动（Action）

• 新增 docs/roadmap-v0.3.md，定义 P0/P1/P2、依赖、验收证据、风险和发布收尾条件。
• 将基线更新为 main 的 2803b40 和 660 项单元测试；保留 f885f57 作为最近运行时修复基线说明。
• 明确现有 CI 已验证 MySQL fixture 连通性与 PostgreSQL 类型映射，但完整真实数据库 introspection/schema/codegen 矩阵仍是 P0。
• 更新 README 文档导航，并令执行协议使用 关联 Issue、Situation、Task、Action、Verification、Evidence、兼容性/风险/回滚七个章节。
• 没有做什么：不改运行时代码、不宣称性能提升、不实现 Java 编译、完整集成矩阵或发布。

验证（Verification）

git diff --check
通过

python scripts/validate_commit_title.py --title ':books: docs(roadmap): 更新 v0.3 基线与执行门禁'
OK: :books: docs(roadmap): 更新 v0.3 基线与执行门禁

$env:PYTHONPATH='src'; python -m pytest tests/unit/test_commit_metadata.py -q
10 passed in 2.63s

$env:PYTHONPATH='src'; python -m pytest tests/unit -q
当前 main 基线 660 passed（运行时代码未被本 PR 修改）

实验与证据（Evidence）

• 路线图基于 CI 的真实容器作业：MySQL 8.0 fixture 连通性、PostgreSQL 16 类型映射已通过；这不是完整数据库工具链矩阵的替代。
• SQLite describe_table 基准固定为每次 7 次 SQL 往返，额外一次用于 AUTOINCREMENT 识别。
• 没有新的性能实验，也没有用现有的单次或 stub 结果推导 MySQL/PostgreSQL 延迟、吞吐或内存收益。

兼容性、风险与回滚

• 公共 API / 数据格式 / 迁移：无。文档只定义后续工作和证据要求。
• 风险与已知限制：路线图会随当前基线过时；每个 P0 项必须有独立 Issue、PR 和实际运行记录。现有容器测试的覆盖范围必须按文档所述理解，不能夸大。
• 回滚：还原路线图和 README 文档提交即可；无运行时状态或数据迁移。
• 后续 Issue：首个 P0 实现为固定 fixture 的 Java 21 / Spring Boot 3.5 生成代码编译 smoke test。

[ZhaoXingPeng]

现状记录：以 main 的 f885f57 为当前基线，项目已经覆盖 MySQL、PostgreSQL、SQLite 的元数据读取、原子代码生成、schema 图算法、MCP Apps、AI 语义增强和可观测性；近期 #101 至 #115 的修复已纳入该基线。

[ZhaoXingPeng]

路线设计：把真实数据库集成、跨方言契约、Java 编译 smoke test 和最终 CI 门禁列为 P0，原因是这些项目目前最缺少可复现的外部证据；缓存和事件循环边界列为 P1，必须先测量再决定是否改造；方言扩展与 agentic runner 演进不提前宣称完成。

[ZhaoXingPeng]

证据边界：当前完整单元测试为 658 passed，SQLite describe_table 基准固定为每次 7 次 SQL 往返，其中一次用于 AUTOINCREMENT 识别；没有真实 PostgreSQL/MySQL 延迟、吞吐或内存基线，因此路线图明确要求先保存原始实验输入和统计结果，不把理论收益写成性能结论。

[ZhaoXingPeng]

执行约束：后续每个路线项目都必须先建中文 Issue，再建立带编号分支、单主题提交和对应 PR；PR 评论记录复现、设计取舍、实验、测试、兼容性与回滚，评论数量按事实需要决定，不人为固定为三条。

[ZhaoXingPeng]

收尾状态：本 PR 只增加路线图和 README 入口，当前保持 open，不合并、不修改运行时代码。待 P0 项目逐项完成并有集成证据后，再单独安排 CI 和发布门禁。

[ZhaoXingPeng]

基线复核与 P0 选择（2026-09-08）

当前结论

路线图已按当前主线重建。P0 不再笼统描述“补集成测试”：CI 已经真实启动 MySQL 8.0 和 PostgreSQL 16，但现有覆盖只到 MySQL fixture 连通性和 PostgreSQL 类型映射。最先可独立落地的缺口是 Java 生成代码编译 smoke，因为现有模板检查只能发现空输出和未替换 Mustache 标签。

变更与设计取舍

• 路线图提交：19ff935、2a8ff23。
• 当前基线：main 的 2803b40，运行时代码基线包含 f885f57；单元测试为 660 项。
• 不把已有容器 job 从路线图删除：它是可用证据，但将其范围明确限制为当前两类测试，避免“有 Testcontainers”被误读成端到端数据库矩阵完成。
• P0 Java 编译先选择固定 fixture、Java 21 和 Spring Boot 3.5；它能直接验证生成源代码的语法、导入和依赖组合，不依赖真实数据库凭据。

验证与证据

• git diff --check：通过。
• python scripts/validate_commit_title.py --title ':books: docs(roadmap): 更新 v0.3 基线与执行门禁'：通过。
• $env:PYTHONPATH='src'; python -m pytest tests/unit/test_commit_metadata.py -q：10 passed in 2.63s。
• 本机已确认 Maven 3.9.16 与 Temurin JDK 21.0.12 可用；这证明可开始本地编译实验，不代表 CI Java 版本已经固定。

兼容性与下一步

• 本 PR 不改运行时代码、CI job 或性能数据；它仅为后续 PR 建立可审计的验收边界。
• #117 通过新 CI 后合并；随后单独创建 Java compile smoke Issue，设计临时 Maven fixture、依赖版本和 CI job，记录首次真实编译结果与失败边界。