shz-backend/.codex/skills/shz-full-development/references/sql-workflow.md

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 的测试执行脚本，并保留显式确认开关：

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

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

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

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

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

然后将文件名标记为：

migration_<feature>.test-executed.sql

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

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

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

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

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

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

此时文件名使用：

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

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

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

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

1. 使用正式环境批准的执行流程，不得从测试命令或测试地址推导正式命令；

2. 做最小只读验证，确认对象、字段、权限或数据状态符合预期；

3. 在 SQL 文件头部补充正式执行环境和时间；

4. 将文件名改为：

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

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

最终状态示例：

-- 执行状态：测试环境和正式环境均已执行
-- 测试环境：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，保留失败证据并等待用户决定。