feat(metadata): 下发 SurrealDB relation 物化视图

[Zhaoyikaiii]

背景

为 unify-query 的 relation 查询补充 SurrealDB 原生 materialized view 下发能力，在保留现有 entity、relation 和 liveness 表结构的前提下，预计算 relation liveness 查询字段。

主要改动

• 在 SurrealDBBinding 状态刷新为 Ok 后，通过 BKBase query_sync 下发 SurrealQL。
• 每个 relation 生成 <relation>_materialized_view，直接来源为 <relation>_liveness_record。
• 投影 source_id、target_id、实体主键快照和半开区间时间字段。
• 为正向/反向查询分别生成端点 + 时间区间索引。
• 持久化 definition hash、下发状态、错误和最近下发时间，相同定义不重复执行，失败可在下一轮刷新重试。
• 增加 BKAPP_ENABLE_SURREALDB_MATERIALIZED_VIEW 开关，默认关闭。
• 从 Binding annotations（或 status.storage）解析 SurrealDB namespace/database；缺失时记录失败，不猜测路由。

验证

• ruff check 通过。
• ruff format --check 通过。
• git diff --check 通过。
• 使用本地 SurrealDB 2.4.0 执行代码实际生成的 DDL，确认：
  • view 创建成功；
  • source/target 索引创建成功；
  • relation liveness 更新后 view 自动更新。
• Django 定向 pytest 已补充，但本地环境因 MySQL 未启动、私有 bk-monitor-base 子模块不可访问，未能完整执行。

待确认

• BKBase SurrealDBBinding 实际回传的 namespace/database annotation key。
• BKOP 当前 SurrealDB 版本与 REMOVE TABLE IF EXISTS 重建行为。
• 灰度开启后补充真实 Binding、首次读取和查询等价性验收。

[github-actions]

请在 PR 中添加项目标签，例如：project/monitor、project/apm、project/log、project/public、project/aiops

[github-actions]

请在 PR 中添加类型标签，例如：fix、feat、docs、style、refactor、test、chore、merge, perf

[Zhaoyikaiii]

Review 结论

当前 Draft PR 的 DDL 生成和本地 SurrealDB 验证方向是对的，但暂不建议直接开启灰度，至少需要处理以下问题：

1. relation 删除后不会清理旧 view（阻断）

build_materialized_view_ddl() 只遍历当前 binding.relations 并生成/重建 view。当 relation 从 Binding 配置中删除时，旧的 <relation>_materialized_view 和索引不会被删除，UQ 仍可能路由到已经废弃的 view，造成脏数据或错误结果。

建议在 reconcile 中维护“本次声明的 relation 集合”，通过持久化上一版 relation names 或查询数据库中由 metadata 管理的 view 清单，显式清理已删除 relation；不能只依赖当前 definition hash。

2. DDL 先删后建，失败会导致现有 view 短暂或持续不可用（阻断）

当前每个 relation 的顺序是 REMOVE TABLE IF EXISTS -> DEFINE TABLE -> DEFINE INDEX。如果 source 表不存在、字段投影失败、索引创建失败或 query_sync 在中途失败，旧 view 已经被删除；多 relation 还会出现前面的 view 已删除、后面的 view 未处理的半成功状态。

建议确认目标 BKOP 版本支持的原子/覆盖定义方式，或改成逐 relation 的安全重建流程，并在删除前完成 source/table/field 探针；至少不能将删除与所有 relation 的定义放在一个不可回滚的批次中。

3. namespace/database 路由契约尚未闭合（阻断）

resolve_surrealdb_scope() 只接受 SurrealDBNamespace/SurrealNamespace 与 SurrealDBDatabase/SurrealDatabase annotations，或 status.storage。PR 描述也明确写了这些 key 仍待确认。如果 BKBase 当前没有返回这些字段，功能开启后每次刷新都会进入失败重试，实际不会下发任何 view。

建议先在 BKBase SurrealDBBinding 的实际响应样例或接口契约中固定 key，并补一条真实响应 fixture；不要把 scope 解析留到灰度阶段再猜。

其他建议

• 失败状态目前每次刷新都会重复写错误字段和日志，建议增加 retry backoff 或只在错误内容变化时更新。
• 补充 relation 删除、DDL 中途失败、scope 缺失以及多 relation 部分失败的测试。
• 当前本地 SurrealDB 2.4.0 验证不能替代 BKOP 实际版本验证，尤其是 view 重建语法和多语句失败行为。