rails-stack-conventions

Rails Stack 约定

为此项目编写或生成代码时，请遵循以下约定。技术栈：Ruby on Rails、PostgreSQL、Hotwire（Turbo + Stimulus）、Tailwind CSS。

风格： 如果项目使用代码检查工具，请以其作为格式规范的准则。对于跨领域设计原则（DRY、YAGNI、结构化日志记录、按目录制定的规则），请使用 rails-code-conventions。

硬性门槛：测试是实现的准入条件

ALL new code MUST have its test written and validated BEFORE implementation.
  1. Write the spec: bundle exec rspec spec/[path]_spec.rb
  2. Verify it FAILS — output must show the feature does not exist yet
  3. Write the implementation code
  4. Verify it PASSES — run the same spec and confirm green
  5. Refactor if needed, keeping tests green
See rspec-best-practices for the full gate cycle.

功能开发工作流

开发典型功能时，按以下顺序组合各层模式：

1. 模型 — 添加验证、关联和作用域；对循环中使用的任何关联，都使用 includes 预加载
2. 服务对象 — 将非简单的业务逻辑从控制器中提取出来（参见 ruby-service-objects）
3. 控制器 — 保持操作精简；将任务委托给服务；响应 turbo_stream 和 html 格式
4. 视图 / Turbo 配置 — 用 <turbo-frame> 标签包裹动态区域；从控制器广播 turbo_stream 响应
5. Stimulus — 仅当 Turbo 无法单独处理客户端交互时，才添加控制器
6. Tailwind — 在视图中应用工具类；将重复模式提取到局部视图或 Stimulus targets 中

在连接到下一层之前，每个步骤都应能独立测试。

关键代码模式

Hotwire：Turbo Frames

<%# Wrap a section to be replaced without a full page reload %>
<turbo-frame id="order-<%= @order.id %>">
  <%= render "orders/details", order: @order %>
</turbo-frame>

<%# Link that targets only this frame %>
<%= link_to "Edit", edit_order_path(@order), data: { turbo_frame: "order-#{@order.id}" } %>

Hotwire：Turbo Streams（从控制器广播）

respond_to do |format|
  format.turbo_stream do
    render turbo_stream: turbo_stream.replace(
      "order_#{@order.id}",
      partial: "orders/order",
      locals: { order: @order }
    )
  end
  format.html { redirect_to @order }
end

避免 N+1 查询 — 预加载

# BAD — triggers one query per order
@orders = Order.where(user: current_user)
@orders.each { |o| o.line_items.count }

# GOOD — single JOIN via includes
@orders = Order.includes(:line_items).where(user: current_user)

服务对象（将复杂业务逻辑移出控制器）

# Controller stays thin — delegate to service
result = Orders::CreateOrder.call(user: current_user, params: order_params)
if result[:success]
  redirect_to result[:order], notice: "Order created"
else
  @order = Order.new(order_params)
  render :new, status: :unprocessable_entity
end

完整的 .call 模式和响应格式请参见 ruby-service-objects。

安全

此项目使用 Devise 进行身份验证，使用 Pundit 进行授权。对于引入访问受控资源的每项功能，都应应用这些机制。

应避免的问题

问题	正确做法
在视图中编写业务逻辑	使用 helpers、presenters 或 Stimulus 控制器
循环中出现 N+1 查询	在循环前使用 includes 预加载
为了“快速”测试而跳过 FactoryBot	Fixtures 不可靠 — 始终使用 factories
控制器操作包含 15 行以上的业务逻辑	将逻辑提取到服务对象中
模型缺少必填字段的验证	添加存在性／格式验证
视图中嵌入的 Ruby 条件语句超过 10 行	将逻辑移至 presenter 或局部视图
将本应放在 I18n 中的字符串硬编码	使用 t() helpers

集成

Skill	何时串联使用
rails-code-conventions	用于设计原则、结构化日志记录和特定路径规则
rails-code-review	根据这些约定审查现有代码时
ruby-service-objects	将业务逻辑提取到服务对象中时
rspec-best-practices	用于测试约定以及完整的红／绿／重构 TDD 周期
rails-architecture-review	需要超出约定范围进行结构审查时