112 lines
4.2 KiB
Markdown
112 lines
4.2 KiB
Markdown
# 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`，保留失败证据并等待用户决定。
|