huang
9795bb9ace
- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards - 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills - 添加 Skills 触发表格，说明各规范的加载时机 - 优化规范文档结构，提升可维护性和可读性
152 lines
3.7 KiB
Markdown
152 lines
3.7 KiB
Markdown
---
|
||
name: db-validation
|
||
description: 数据库验证规范。测试 API 接口、验证业务逻辑、调试数据问题时使用。包含 PostgreSQL MCP 工具使用方法和验证示例。
|
||
---
|
||
|
||
# 数据库验证规范
|
||
|
||
**AI 在测试接口或验证业务逻辑时，必须使用 PostgreSQL MCP 工具直接查询数据库验证数据的正确性。**
|
||
|
||
## 触发条件
|
||
|
||
在以下情况下必须遵守本规范：
|
||
- 测试 API 接口后验证数据
|
||
- 检查数据库表结构
|
||
- 验证数据库迁移结果
|
||
- 调试业务逻辑
|
||
- 验证事务处理
|
||
- 检查数据权限过滤
|
||
|
||
## 何时使用 PostgreSQL MCP
|
||
|
||
### ✅ 必须使用的场景
|
||
|
||
- 测试 API 接口后验证数据是否正确写入数据库
|
||
- 检查数据库表结构是否符合 Model 定义
|
||
- 验证数据库迁移是否成功执行
|
||
- 调试业务逻辑时查看实际数据状态
|
||
- 验证事务是否正确提交或回滚
|
||
- 检查数据权限过滤是否生效
|
||
|
||
### ❌ 不要
|
||
|
||
- 仅依赖 API 响应判断数据是否正确（响应可能只是内存中的临时数据）
|
||
- 通过日志推测数据库状态
|
||
- 假设代码逻辑正确就认为数据正确
|
||
|
||
## 可用的 PostgreSQL MCP 工具
|
||
|
||
```
|
||
1. PostgresListSchemas - 列出所有数据库模式
|
||
2. PostgresListObjects - 列出指定模式下的表/视图/序列
|
||
3. PostgresGetObjectDetails - 查看表结构详情（字段、类型、约束、注释）
|
||
4. PostgresExecuteSql - 执行只读 SQL 查询（SELECT）
|
||
```
|
||
|
||
## 验证示例
|
||
|
||
### 场景 1：测试创建用户接口
|
||
|
||
```
|
||
1. 调用 POST /api/v1/accounts 创建用户
|
||
→ 响应：{"code":0, "data":{"id":123, "username":"testuser"}}
|
||
|
||
2. ✅ 使用 PostgreSQL MCP 验证数据库
|
||
PostgresExecuteSql:
|
||
- sql: "SELECT id, username, user_type, status, created_at FROM tb_account WHERE id = 123"
|
||
|
||
3. 检查查询结果：
|
||
✅ 用户确实已创建
|
||
✅ 字段值与请求参数一致
|
||
✅ status = 1（启用）
|
||
✅ created_at 有值
|
||
```
|
||
|
||
### 场景 2：测试数据权限过滤
|
||
|
||
```
|
||
1. 以代理用户登录，查询店铺列表
|
||
→ 响应：返回 5 个店铺
|
||
|
||
2. ✅ 使用 PostgreSQL MCP 验证过滤逻辑
|
||
PostgresExecuteSql:
|
||
- sql: "SELECT id, shop_name, parent_id FROM tb_shop WHERE deleted_at IS NULL"
|
||
|
||
3. 检查：
|
||
✅ 数据库实际有 10 个店铺
|
||
✅ API 只返回了当前用户及下级的 5 个店铺
|
||
✅ 数据权限过滤生效
|
||
```
|
||
|
||
### 场景 3：验证迁移执行
|
||
|
||
```
|
||
1. 执行迁移：make migrate-up
|
||
|
||
2. ✅ 验证表结构
|
||
PostgresGetObjectDetails:
|
||
- schema_name: "public"
|
||
- object_name: "tb_account"
|
||
- object_type: "table"
|
||
|
||
3. 检查：
|
||
✅ 新字段 enterprise_id 已添加
|
||
✅ 类型为 bigint
|
||
✅ 允许 NULL
|
||
✅ 注释为"企业ID"
|
||
```
|
||
|
||
## 工具使用方法
|
||
|
||
### 查看表结构
|
||
|
||
```
|
||
PostgresGetObjectDetails:
|
||
- schema_name: "public"
|
||
- object_name: "tb_permission"
|
||
- object_type: "table"
|
||
```
|
||
|
||
### 列出所有表
|
||
|
||
```
|
||
PostgresListObjects:
|
||
- schema_name: "public"
|
||
- object_type: "table"
|
||
```
|
||
|
||
### 执行查询
|
||
|
||
```
|
||
PostgresExecuteSql:
|
||
- sql: "SELECT * FROM tb_permission LIMIT 5"
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
### ⚠️ 限制
|
||
|
||
- PostgreSQL MCP 只支持只读查询（SELECT），不能执行 INSERT/UPDATE/DELETE
|
||
- 如需插入测试数据，使用 Go 脚本或迁移文件
|
||
|
||
### ⚠️ 安全
|
||
|
||
- 避免在查询中暴露敏感数据（如密码哈希）
|
||
- 生产环境使用时需谨慎，避免查询大量数据
|
||
|
||
### ✅ 最佳实践
|
||
|
||
- 每次 API 测试后都验证数据库状态
|
||
- 使用 LIMIT 限制查询结果数量（如 `LIMIT 10`）
|
||
- 验证完成后清理测试数据
|
||
|
||
## AI 助手检查清单
|
||
|
||
测试接口后必须：
|
||
|
||
1. ✅ 使用 PostgresExecuteSql 查询相关数据
|
||
2. ✅ 验证数据是否正确写入
|
||
3. ✅ 验证字段值是否符合预期
|
||
4. ✅ 验证关联数据是否正确
|
||
5. ✅ 如有数据权限，验证过滤是否生效
|