diff --git a/AGENTS.md b/AGENTS.md index 4c8452f..cf22c4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -326,6 +326,102 @@ router.Post("/shops", handler.Create) - 使用 table-driven tests - 单元测试 < 100ms,集成测试 < 1s +## 数据库验证规范 + +**核心要求:AI 在测试接口或验证业务逻辑时,必须使用 PostgreSQL MCP 工具直接查询数据库验证数据的正确性。** + +### 何时使用 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" +``` + +### 注意事项 + +⚠️ **限制**: +- PostgreSQL MCP 只支持只读查询(SELECT),不能执行 INSERT/UPDATE/DELETE +- 如需插入测试数据,使用 Go 脚本或迁移文件 + +⚠️ **安全**: +- 避免在查询中暴露敏感数据(如密码哈希) +- 生产环境使用时需谨慎,避免查询大量数据 + +✅ **最佳实践**: +- 每次 API 测试后都验证数据库状态 +- 使用 LIMIT 限制查询结果数量(如 `LIMIT 10`) +- 验证完成后清理测试数据 + ## 性能要求 - API P95 响应时间 < 200ms diff --git a/README.md b/README.md index 41353d7..9b61f0d 100644 --- a/README.md +++ b/README.md @@ -815,6 +815,7 @@ rdb.Set(ctx, key, status, time.Hour) ### 开发规范 - **[API 文档生成规范](docs/api-documentation-guide.md)**:路由注册规范、DTO 规范、OpenAPI 文档生成流程 +- **[数据库验证规范](AGENTS.md#数据库验证规范)**:使用 PostgreSQL MCP 验证接口逻辑和业务数据的正确性 - **[开发规范总览](AGENTS.md)**:完整的项目开发规范(必读) ### 功能指南