rails-query-object

用途

Rails Query Object Generator 是一个用于 Ruby on Rails 项目的 AI 技能，帮助开发者按照 TDD（测试驱动开发）方式创建查询对象（Query Object）。查询对象用于将复杂的数据库查询逻辑从控制器或模型中抽离出来，封装为独立、可测试的类。该技能适用于以下场景：封装复杂查询、聚合统计数据、构建报表，以及需要多租户隔离的查询逻辑。

主要能力

该技能遵循一套明确的项目约定来生成查询对象：

查询对象通过构造函数接收上下文，参数形式为 user: 或 account:。
返回 ActiveRecord::Relation 以支持链式调用，或返回 Hash 用于聚合结果。
提供 call 方法作为主操作入口。
支持多租户，查询按 account 作用域隔离。

技能内置三种查询对象模式：

简单过滤查询：如 StaleLeadsQuery，通过 account.leads.stale 返回过滤后的关系。
聚合查询（多方法）：如 DashboardStatsQuery，包含 upcoming_events、pending_commissions_total、top_vendors、leads_by_status 等多个方法，分别返回关系、数值、分组统计等。
分组查询：如 LeadsByStatusQuery，将记录按状态分组并返回 Hash 结果。

使用方式

该技能采用 TDD 工作流，分为四个步骤：

步骤 1：创建查询测试（RED）

在 spec/queries/[name]_query_spec.rb 中编写测试，包括：

测试构造函数需要 account 参数（缺少时抛出 ArgumentError）。
测试构造函数存储 account。
测试 call 返回预期类型（ActiveRecord::Relation 或 Hash）。
测试只返回当前 account 的资源（多租户隔离）。
测试多租户隔离：account A 不能看到 account B 的数据。

步骤 2：运行测试确认 RED

bundle exec rspec spec/queries/[name]_query_spec.rb

步骤 3：实现查询对象（GREEN）

在 app/queries/[name]_query.rb 中实现类，包含 attr_reader :account、initialize(account:) 和 call 方法。call 方法返回 ActiveRecord::Relation 或 Hash，并附有 @return 文档注释。

步骤 4：运行测试确认 GREEN

bundle exec rspec spec/queries/[name]_query_spec.rb

在控制器中的使用示例：

# 简单查询
def index
  @leads_by_status = LeadsByStatusQuery.new(account: current_account).call
end

# 聚合查询配合 presenter
def index
  stats_query = DashboardStatsQuery.new(user: current_user)
  @stats = DashboardStatsPresenter.new(stats_query)
end

适用场景

需要将复杂数据库查询从控制器或模型中抽离的 Rails 项目。
需要聚合统计数据或构建报表的场景。
需要多租户数据隔离的应用。
希望以 TDD 方式开发查询逻辑的团队。

限制

该技能要求项目使用 RSpec 作为测试框架，并遵循特定的目录结构（spec/queries/ 和 app/queries/）。查询对象约定构造函数接收 user: 或 account: 参数，返回类型为 ActiveRecord::Relation 或 Hash。技能强调多租户隔离测试、返回类型文档化、方法命名清晰，以及复杂查询使用 .includes() 防止 N+1 查询。关于该技能的具体安装方式、收费模式、支持平台等信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制