# SHZ SQL 执行和状态管理

## 适用范围

此流程只适用于当前请求明确授权的全流程开发。`$query-shz-highgo` 仍然只用于只读查询；不得把只读查询脚本改造成写入脚本。写入 SQL 必须使用项目已有的、目标环境明确的受保护执行流程。

## 执行前检查

1. 确认 SQL 文件属于当前任务，并检查 `git status` 和 diff。
2. 阅读 SQL 全文，确认目标 schema、表、权限、事务边界、依赖顺序和是否可重复执行。
3. 优先使用事务、`ON_ERROR_STOP=1`、明确的 `search_path` 和项目已有的连接配置。
4. 对 `DROP`、批量 `UPDATE`、批量 `DELETE`、权限变更和不可逆操作，先做最小只读检查；发现范围不明确时停止并要求用户确认。
5. 不得把密码写入 SQL、命令行、日志或提交。

## 测试环境执行阶段

先在测试环境执行 SQL。对通用 SQL 文件，使用新 skill 的测试执行脚本，并保留显式确认开关：

```bash
CONFIRM_TEST_SQL=yes \
.codex/skills/shz-full-development/scripts/execute-test-sql.sh \
sql/migration_<feature>.sql
```

项目已有针对特定迁移的测试脚本时，优先使用该脚本。执行时记录但不泄露凭据：

- SQL 文件路径和 commit（如果已经提交）；
- 目标环境、数据库和 schema；
- 执行时间；
- 执行命令或受保护流程名称；
- 成功/失败状态和简短响应摘要；
- 执行后的只读验证查询。

测试 SQL 成功后，将 SQL 文件头部状态更新为中文，例如：

```sql
-- 执行状态：测试环境已执行
-- 测试环境：test
-- 测试执行时间：YYYY-MM-DD HH:MM:SS +0800
-- 正式环境：未执行
```

然后将文件名标记为：

```text
migration_<feature>.test-executed.sql
```

不得在此阶段使用 `test-and-production-executed`，也不得声称正式环境已执行。

## 功能测试通过后的正式 SQL 生成

只有以下条件全部满足，才生成正式 SQL：

1. 测试环境 SQL 执行成功；
2. 后端或前端测试、构建和静态检查通过；
3. 测试环境部署成功；
4. 目标功能已通过 Chrome DevTools 流程验证；
5. 相关控制台、网络、日志和只读数据库验证没有未解释的失败；
6. 用户要求的回归范围已经完成。

从测试 SQL 生成正式 SQL 时，保留业务语句和必要的中文状态说明，清除测试环境专属的临时数据、测试账号、测试地址和测试标识。正式 SQL 生成后，将状态更新为：

```sql
-- 执行状态：测试环境已执行，功能验证已通过，正式环境待执行
-- 测试环境：test
-- 测试执行时间：YYYY-MM-DD HH:MM:SS +0800
-- 功能验证时间：YYYY-MM-DD HH:MM:SS +0800
-- 正式环境：待明确授权后执行
```

此时文件名使用：

```text
migration_<feature>.test-verified-production-ready.sql
```

该文件名表示“测试已执行且功能已验证，正式 SQL 已准备好”，不表示正式环境已经执行。

## 正式环境执行后的最终状态

正式环境 SQL 只有在当前请求单独明确授权后才能执行。执行成功后：

1. 使用正式环境批准的执行流程，不得从测试命令或测试地址推导正式命令；
2. 做最小只读验证，确认对象、字段、权限或数据状态符合预期；
3. 在 SQL 文件头部补充正式执行环境和时间；
4. 将文件名改为：

   ```text
   migration_<feature>.test-and-production-executed.sql
   ```

5. 只有在有成功执行证据时，才允许使用 `test-and-production-executed` 文件名。

最终状态示例：

```sql
-- 执行状态：测试环境和正式环境均已执行
-- 测试环境：test
-- 测试执行时间：YYYY-MM-DD HH:MM:SS +0800
-- 功能验证时间：YYYY-MM-DD HH:MM:SS +0800
-- 正式环境：production
-- 正式执行时间：YYYY-MM-DD HH:MM:SS +0800
```

## 失败时的文件状态

- 测试执行失败：保留原文件名和失败记录，不得标记为测试已执行；
- 测试成功但功能失败：最多保留 `test-executed`，不得生成 `test-verified-production-ready`；
- 正式 SQL 已生成但未获正式执行授权：保留 `test-verified-production-ready`；
- 正式执行失败：不得改名为 `test-and-production-executed`，保留失败证据并等待用户决定。