[ZhaoXingPeng]

关联 Issue

Closes #114

背景（Situation）

PostgreSQL 允许多个 schema 使用同一个表名。db_query_table_exists 原先只按数据库和表名查询，无法确认调用方需要的 tenant_a.users，与表列表、表描述和代码生成路径的 schema 契约不一致。

任务（Task）

为存在性检查增加可选 PostgreSQL schema，保持 MySQL/SQLite 现有行为和成功 Raw Response 的 JSON 可解析性，并确保 schema 值始终通过驱动参数绑定。

行动（Action）

• 在 MCP 输入模型中声明可选 schema。
• PostgreSQL 提供 schema 时追加参数化的 table_schema = %s 条件。
• 成功响应回显 schema；未提供时返回 JSON null。
• 增加输入契约、参数顺序、成功响应和方言兼容回归测试。
• 没有做什么：不改变 MySQL/SQLite SQL、表详情、代码生成或权限策略；未测性能收益。

验证（Verification）

环境：Windows 11，Python 3.12.12 / PostgreSQL stub。

• PYTHONPATH=src python -m pytest tests/unit/ -q：658 passed。
• 定向 schema/MCP 测试：17 passed。
• ruff check src tests、变更文件格式检查和 git diff --check：通过。

实验与证据（Evidence）

stub 对未指定 schema 收到参数 ("app", "users")，对 tenant_a 收到 ("app", "users", "tenant_a")；schema 值不进入 SQL 文本。两种路径的 Raw Response 均可由 json.loads 解析，并回显字符串或 JSON null。未建立真实 PostgreSQL 往返性能基准。

兼容性、风险与回滚

• 公共 API / 数据格式 / 迁移：新增可选输入和成功响应字段，旧客户端不传 schema 仍走原查询。
• 风险与已知限制：本地未运行真实 PostgreSQL 容器；SQLite 没有 schema 过滤，更多方言需另测。
• 回滚：revert 对应提交即可恢复旧存在性查询，不涉及数据。
• 后续 Issue：真实 PostgreSQL catalog/driver 已在 🧪 test(integration): 覆盖真实元数据契约 #133 覆盖，复杂权限与性能另行跟踪。

[ZhaoXingPeng]

问题复现：PostgreSQL 的 tenant_a.users 与 tenant_b.users 可以同时存在，但 db_query_table_exists 原实现只绑定 ("app", "users")，调用方无法表达目标 schema，存在把错误对象判定为存在的风险。该缺口与已有 db_query_tables、db_table_describe 的 schema 能力不一致。

[ZhaoXingPeng]

设计记录：输入 schema 定义为可选字段，仅在 PostgreSQL 分支追加 table_schema = %s。值始终使用驱动参数绑定，不拼接到 SQL；MySQL 继续把 database 作为 schema，SQLite 继续使用单命名空间，从而把新增能力限制在真实需要的方言范围内。

[ZhaoXingPeng]

实验结果：PostgreSQL stub 对未指定 schema 的调用收到 ("app", "users")，对 tenant_a 收到 ("app", "users", "tenant_a")，查询文本仅在第二种情况下出现 schema 条件。两种路径均返回可由 json.loads 解析的 Raw Response，并回显 schema 为字符串或 null。

[ZhaoXingPeng]

验证记录：新增工具输入契约测试、schema 参数绑定测试和成功响应 JSON 测试；定向 MCP 测试 17 项通过，完整 PYTHONPATH=src python -m pytest -q tests/unit 为 658 passed，Ruff lint、变更文件格式检查与 git diff --check 全部通过。

[ZhaoXingPeng]

兼容性与边界：新增 schema 是成功响应的向后兼容字段扩展，旧客户端不传该字段仍走原查询。未建立真实 PostgreSQL 往返性能基准，性能数据未测量；本 PR 只修正对象定位，不宣称性能提升。后续若支持更多带命名空间的数据库，应复用同一输入契约并补充方言测试。