> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 提单、大批量导入与 AI 预审实战

本手册面向研发工程师，带你一步步完成一次标准的 DDL/DML 变更工单提交、大批量 `.sql` 文件导入、看懂 AI 预审报告与处理门禁阻断。


![AI SQL 预审弹窗：实时展示阶段进度、折叠指纹组数、风险发现详情与提交审批入口](/screenshots/precheck-zh-CN-dark.png)

AI SQL 预审弹窗：实时展示阶段进度、折叠指纹组数、风险发现详情与提交审批入口

## 1. 创建变更工单操作步骤（`/changes/new`）

1. 在左侧菜单点击 **工单提交（`/changes/new`）**。
2. 依次填写表单：
   - **标题**：简要说明变更目的（例如 `订单表新增结算状态索引`）。
   - **审批流程**：从你的权限组已获授的 `change_review` 流程中选择（注意：多阶段流程会同时列出预发和生产两个目标库，提交前系统会对每个阶段分别预审）。
   - **期望执行时间（可选）**：如希望审批通过后在指定窗口自动由执行人预约，可提前预填。
   - **启用回滚保护**：建议对 `INSERT` / `UPDATE` / `DELETE` 与可逆 DDL 保持开启，执行期自动捕获事务内前像生成回滚 SQL（详见 [回滚工单实战](/features/sql-rollback.md)）。
3. **输入或导入 SQL**：
   - 直接在编辑器粘贴纯 DML 或纯 DDL 语句（**严禁在同一工单混写 DML 与 DDL**，否则报 `2001`；`SELECT` 查询请移步 `/query`）。
   - 若是大批量数据订正，可直接将本地 `.sql` / `.txt` 文件拖入右侧导入区（单工单最高支持 **32 MiB** / **100,000 条语句**，单条上限 **512 KiB**；超过 `512 KiB` 或 `1,000` 条时界面自动切换为虚拟化语句浏览器防卡顿）。
   - 如果暂时不提交，可点击 **保存并返回** 存为草稿（随时在 `/changes/mine` 继续编辑）。

## 2. 运行 AI SQL 预审并读懂结果

点击 **运行 AI 预审** 后，预审弹窗自动打开并实时推进进度条：

1. **阶段 1（词法解析与双指纹折叠）**：
   - 若存在语法错误，弹窗立即返回 `2003 SQL_PARSE_FAILED` 并指出**精确行号、列号、语句序号与方言错误原因**，直接按行号修改即可。
   - 若批量脚本里有 50,000 条同构 `UPDATE` 语句，系统按 Canonical + Dialect 双指纹自动折叠为 `1` 个指纹组（单工单硬上限 `1,000` 组不同模板，超限报 `2006` 需拆单）。
2. **阶段 2（规则校验 + 5 项只读元数据工具探测）**：
   - 系统通过目标库只读账号自动探测真实表结构、索引列顺序、表行数与 `EXPLAIN` 预估扫描行数。
   - 在 **风险发现** 标签页中，你将看到已经自动还原为真实表名/列名的排查说明（模型侧与持久化证据始终保持匿名）。

### 如何判断能不能提交？（3 类发现一眼分辨）

| 发现类型                                    | 页面显示级别           | 能否提交           | 你该怎么处理                                                                          |
| :-------------------------------------- | :--------------- | :------------- | :------------------------------------------------------------------------------ |
| **强制规则命中（`policy_finding`）**            | `Critical`（红）    | **阻断（`2008`）** | 违反了团队启用的内置/自定义规则或表级内部经验（如缺 `WHERE`、缺主键、超过 `max_affect_rows`），**必须修改 SQL** 后重跑预审 |
| **运行时证明无效（`proven_invalid_execution`）** | `Critical`（红）    | **阻断（`2008`）** | 目标库里不存在该表/该列，或重复建已有索引/列，核实目标库表结构并修正 SQL                                         |
| **模型观察建议（`agent_observation`）**         | 最高 `Medium`（黄/蓝） | **放行**         | AI 结合执行计划给出的优化参考，无需强改，审批人也可在工单中看到                                               |
| **元数据不完整（`partial`）**                   | `Partial`（黄）     | **阻断**         | 目标库只读账号缺表权限、网络超时或 PG `search_path` 异常，联系 DBA 检查数据源                              |

### 真实踩坑示例：被门禁拦截后如何修正

假设提交了如下语句：

```sql
-- ❌ 触发两项阻断：1) 无 WHERE/索引全表扫描超过 max_affect_rows；2) 混合了 DDL
UPDATE orders SET status = 'archived' WHERE created_at < '2024-01-01';
ALTER TABLE orders ADD INDEX idx_created_at (created_at);
```

修正做法：

1. **拆分为两笔工单**：先提交纯 DDL 工单为 `created_at` 建索引，待上线生效后再提交纯 DML 工单。
2. 若单批 DML 预估影响行数过大，按主键 ID 区间或日期分批拆单，确保每批在 `max_affect_rows` 阈值与 `100,000` 行回滚保护上限之内。
3. **改完任意一个字符后必须重新点击「运行 AI 预审」**：因为 `run_id` 与 SQL 内容加密绑定，未重跑直接提交会返回 `2001 REVIEW_OUTDATED`。

## 3. 提交审批、退回修改与复用草稿

- 全部阶段预审状态变为 **`通过（ready）`** 后，在 **30 分钟有效期** 内点击弹窗右下角 **提交审批**。
- **被审批人「退回修改（`changes_requested`）」时**：无需新建工单，进入 `/changes/mine` 打开该工单直接修改 SQL，重新通过 AI 预审后点击 **重新提交**，或点击 **作废** 关闭。
- **需要再次执行类似变更时**：打开任意历史工单，点击 **复制为新草稿** 一键带入 SQL 与标题。
