# 消息搜索上线（TiDB）

本文档面向使用 TiDB 部署 AgentTeam 的运维/管理员。

AgentTeam 的消息搜索只有在目标 workspace 的 workspace-global TiDB search projection 完成以下步骤后才会可用：

1. backfill
2. finalize 并创建/验证 TiDB FULLTEXT artifact
3. 显式 promote 为 read-ready

在此之前，AgentTeam 会把该 workspace 的消息搜索视为不可用。新消息写入会在同一事务内更新 `scope_message_search_docs`；运维命令负责回填/修复历史 projection 缺口并维护 readiness 状态。

升级时，AgentTeam 可以把已有 hot search documents 迁入 `scope_message_search_docs`，但不会继承 pre-scope search 的 `read_ready` 状态。搜索必须重新通过下面这组 workspace-global admin 命令 finalize 并 promote 后才可用。

## 必要环境变量

所有命令都需要：

- `AGENTTEAM_DATABASE_DSN`：AgentTeam core TiDB 数据库 DSN
- `AGENTTEAM_WORKSPACE_MESSAGE_SEARCH_WORKSPACE_ID`：要操作的 workspace id（low-level repair/debug 命令只作用于该 workspace 的 workspace-global readiness row）

可选参数：

- `AGENTTEAM_DATABASE_CONNECT_TIMEOUT`：连接超时（默认 `5s`）
- `AGENTTEAM_MESSAGE_SEARCH_BACKFILL_BATCH_SIZE`：backfill 批大小（默认 `1000`）

## 上线流程

### 1）Backfill projection 行

执行：

```bash
agentteam-tidb-admin workspace-message-search-backfill
```

该命令会为历史 hot scope messages 回填 TiDB projection 行。它支持断点续跑，也可以安全地重复执行。

### 2）Finalize projection readiness

执行：

```bash
agentteam-tidb-admin workspace-message-search-finalize
```

Finalize 会校验该 workspace-global projection 没有缺失行，创建或验证 `scope_message_search_docs` 的 `MULTILINGUAL` TiDB FULLTEXT artifact，并记录 finalized 状态。搜索查询使用 TiDB FULLTEXT；不要在缺少必要 TiDB FULLTEXT 能力的部署上 promote。

Finalize 是幂等操作；projection 已 ready 后重复执行不得把 `read_ready` 降级。

Finalize 要求：

- `tidb_enable_fulltext_index = ON`
- 已注册 TiFlash / TiFlash Compute 节点

### 3）Promote 为 read-ready

执行：

```bash
agentteam-tidb-admin workspace-message-search-promote-ready
```

该命令只有在 migration、backfill、finalize 均 complete、FULLTEXT artifact 可见且没有缺失 projection 行时，才会将该 workspace-global projection 的 `read_ready = true`。完成后，AgentTeam Web 才会对该 workspace 暴露消息搜索。

## 查看状态

获取一份 machine-readable 的状态快照：

```bash
agentteam-tidb-admin workspace-message-search-status
```

如果要一次性确保当前数据库里的所有 workspace 都 ready，可执行：

```bash
agentteam-tidb-admin workspace-message-search-ensure-ready
```

该命令会按 `created_at ASC, id ASC` 的确定性顺序枚举所有 workspace；phase 进度日志写到 stderr，最终结果写到 stdout JSON。

## 常见排障

- `AGENTTEAM_DATABASE_DSN is required`
  确保 `AGENTTEAM_DATABASE_DSN` 指向 server 正在使用的 core TiDB 数据库。

- `AGENTTEAM_WORKSPACE_MESSAGE_SEARCH_WORKSPACE_ID is required`
  设置要操作的 workspace id。

- `scope search migration must be complete before backfill` / `scope search readiness not found`
  说明 schema 或 readiness state 未就绪。先走一遍正常的 schema 校验/迁移流程，再重试。升级迁入的历史 documents 仍需重新执行 workspace-global backfill/finalize/promote 后才会开放搜索。

- `scope search backfill must be complete before finalize`
  先执行 `agentteam-tidb-admin workspace-message-search-backfill`，直到它报告 `status=complete`。

- `scope search projection has missing rows; run scope search backfill`
  再执行一次 backfill。新消息写入会持续维护 projection，backfill 用于修复历史缺口。

- `tidb_enable_fulltext_index is not enabled`
  需要开启 `tidb_enable_fulltext_index`，然后重试 finalize。

- `no TiFlash node is registered; scope message search fulltext finalize requires TiFlash`
  需要在 TiDB 集群中启用/接入 TiFlash，然后重试 finalize。

- AgentTeam Web 中该 workspace 仍然看不到搜索结果
  先看 `workspace-message-search-status`，确认 migration、backfill、finalize 均 complete 且 `read_ready` 为 `true`（必要时执行 `workspace-message-search-promote-ready`）。