feat(PostgreSQL): 支持 jsonb 通用查询条件

[zhou-hao]

目的

• 为 PostgreSQL jsonb 字段补齐与数组字段一致的通用 TermType 查询能力。
• 支持通过 options 在默认行为和 key/jsonb 语义之间切换，减少 data$exist$contains 这类混合语义写法。
• key exists 场景改用 ? / ?| / ?& 操作符，便于匹配 PostgreSQL jsonb_ops GIN 索引。

核心变动

• 新增 PostgresqlJsonbTermFragmentBuilder：
  • 支持 in / nin、contains / ncontains、contained / ncontained、overlap / noverlap。
  • 默认 contains / contained 映射为 @> / <@。
  • 默认 in / overlap 映射为 ?|。
  • 支持 key、keys、any、all、json、contains、contained options 覆盖默认行为。
• 调整 PostgresqlJsonbExistTermFragmentBuilder：
  • key exists 改为生成 JDBC 可转义的 ?? / ??| / ??&，实际 SQL 为 PostgreSQL ? / ?| / ?&。
  • 保留原 exist、exist$any、exist$all、exist$contains、exist$contained 行为入口。
• 调整 SqlUtils：
  • 支持日志渲染和 R2DBC $n 占位符转换时识别 JDBC 风格 ?? / ??| / ??& 转义操作符。
  • 保留普通 x ?? y 文本不误判的回归行为。
• 在 PostgresqlSchemaMetadata 中为 JsonbType 注册通用 TermType builder。
• 补充 builder、column feature 查找链路、JDBC 和 R2DBC 真实 PostgreSQL 集成测试。

设计与测试目标

• 设计稿：不适用；本次为 PostgreSQL 方言已有 jsonb 查询能力的范围内增强，未引入跨模块业务流程或新存储结构。
• 用户确认：已在会话中确认采用“相同 TermType + options 指定行为”的方案；后续根据索引命中要求调整为 ? / ?| / ?& 操作符实现。
• 测试目标：覆盖默认 jsonb containment、key exists any/all、负向条件、column $options 解析、JDBC 与 R2DBC 集成路径。
• 数据权限：不适用；未涉及业务资产或权限控制。
• 数据库兼容与性能：仅 PostgreSQL jsonb 方言能力；key exists 使用 PG 原生 ? / ?| / ?& 操作符以匹配 jsonb_ops GIN 索引能力。未新增复杂分页、聚合或批量写入。
• 注释 / 公共契约：不涉及对外 SPI 契约变更；新增 builder 逻辑与现有 array/jsonb builder 风格一致。SqlUtils 转义逻辑处补充了简要兼容说明。
• TraceHolder 链路追踪：不适用；仅 SQL 片段构建，不涉及关键业务链路或外部 I/O 编排。
• MBean 运维可观测性：不适用；未新增常驻任务、缓存、队列或后台执行器。

测试结果

• 单元/Builder/SqlUtils 回归测试：
  • 命令：mvn -pl hsweb-easy-orm-rdb -Dtest=PostgresqlJsonbExistBuilderCoverageTest,SqlUtilsCoverageTest,SqlUtilsTest,SqlUtilsBranchTest test
  • 结果：73 passed, 0 failed, 0 skipped
  • 覆盖：jsonb 通用 TermType 默认行为、options 覆盖、负向条件、column feature 查找链路、??|/??& 转义还原和原有 JSONB 操作符参数替换回归。
• JDBC 集成测试：
  • 命令：mvn -pl hsweb-easy-orm-rdb -Dtest=PostgresqlBasicTest#testJsonbExistTerm test
  • 结果：1 passed, 0 failed, 0 skipped
  • 环境：Testcontainers postgres:11-alpine
  • 日志确认：JDBC SQL 使用 ?? / ??| / ??&，native SQL 渲染为 ? / ?| / ?&。
• R2DBC 集成测试：
  • 命令：mvn -pl hsweb-easy-orm-rdb -Dtest=PostgresqlReactiveTests#testJsonbExistTerm test
  • 结果：1 passed, 0 failed, 0 skipped
  • 环境：Testcontainers postgres:11-alpine
  • 日志确认：R2DBC SQL 使用 ? / ?| / ?& 并正确转换其他参数为 $n。
• 空白检查：
  • 命令：git diff --check
  • 结果：通过
• 覆盖率（最后一次 jacoco report）：
  • 模块整体 line：8077/9617，83.99%
  • 模块整体 branch：2739/3627，75.52%
  • PostgresqlJsonbTermFragmentBuilder line：40/42，95.24%；branch：16/21，76.19%
  • PostgresqlJsonbExistTermFragmentBuilder line：65/72，90.28%；branch：37/44，84.09%

文档同步情况

• 未更新 README 或独立文档。
• 原因：本次为 RDB PostgreSQL 方言内部查询条件增强，测试证据已放在 PR 描述中；暂无长期用户文档落点需要同步。

风险与说明

• 影响范围：PostgreSQL JsonbType 字段查询条件构建，以及 SqlUtils 对 PostgreSQL JSONB ? 操作符的参数替换/日志渲染识别。
• 兼容性：保留已有 exist 与 exist$any/all/contains/contained 行为入口；SQL 从函数形式调整为可索引操作符形式。
• 数据库范围：仅 PostgreSQL jsonb；其他数据库 JSON 查询不受影响。
• 已知限制：overlap 默认按“任意 key 存在”解释，即 ?|；需要对象 containment 时可使用 contains 或 json option。

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 86.59794% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.24%. Comparing base (68b2764) to head (73abbd0).
⚠️ Report is 46 commits behind head on 4.2.

Files with missing lines	Patch %	Lines
...s/postgres/PostgresqlJsonbTermFragmentBuilder.java	85.41%	2 Missing and 5 partials ⚠️
...tgres/PostgresqlJsonbExistTermFragmentBuilder.java	85.36%	4 Missing and 2 partials ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##                4.2     #113       +/-   ##
=============================================
+ Coverage     64.92%   79.24%   +14.31%     
- Complexity     2341     3357     +1016     
=============================================
  Files           343      374       +31     
  Lines          9375    10834     +1459     
  Branches        940     1284      +344     
=============================================
+ Hits           6087     8585     +2498     
+ Misses         2810     1622     -1188     
- Partials        478      627      +149     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.