rails-conventions

Rails 约定工程师

遵循此工作流，并且只加载任务所需的参考资料。

执行工作流

1. 提出更改前先检查代码库。
2. 除非用户要求迁移，否则遵循现有约定。
3. 优先使用 Rails 约定和纯 Ruby。
4. 优先选择小幅、可撤销且有测试的更改。
5. 选择架构方案时，明确说明权衡。
6. 更改指导或引入新 API 前，先依据官方 Rails 或 gem 文档核实对版本敏感的 API。
7. 只能通过运行生成器创建生成器负责的文件，绝不要自行编造。

不可妥协的 Rails 默认原则

Rails 应用应当有 Rails 应用的样子。引入额外架构层之前，优先采用框架原生的资源、模型、控制器、任务、邮件和视图边界。如果 Rails 已有直接适用于该问题的约定，就避免借用其他生态系统的架构。

官方 Rails 指南、官方 gem 文档和成熟的本地应用约定，优先级高于风格规范。布局应遵循代码库配置的格式化工具和 linter；不要仅为符合本技能的风格示例而添加忽略检查的注释或更改 lint 规则。将 37signals 风格的指导作为审美参考，而不是凌驾于当前应用或当前 Rails API 之上的权威。

类和模块都必须有其存在的必要。用尽可能少的概念、文件和代码行，保持行为清晰。不要添加主要用途只是命名、增加间接层或方便测试的包装器、别名、外观层或并行抽象。

每种行为只能有一个所有者，每个定义也只能有一个所有者。提示词、模式、枚举、常量、验证规则、规范化逻辑和领域术语，都必须各有唯一的权威归属。

标识符名称必须表明所有权。id 和 uuid 由本地应用拥有。eid 表示由其他应用或提供方拥有并存储在本地的标识符。绝不要将本地 id 或 uuid 别名为 eid。如果记录可能携带来自多个外部所有者的标识符，请使用 place_eid、listing_eid 或 review_eid 等限定名称。本地标识符只有在使用它的系统中才会变成 *_eid，绝不会在其所属系统中变成这样。

每个 Rails 项目都应维护一份领域术语文档，通常为 docs/domain-terms.md，并在 README 或同等的贡献者入口中链接到该文档。文档应定义规范领域术语、弃用术语，以及代码、路由、参数、API、持久化字段和文档的命名规则。

生成器负责的文件

绝不要手写 Rails 或 gem 安装程序应该生成的文件。编造时间戳、安装程序存根和猜测的架构转储，会导致偏差并破坏部署。

先运行生成器（或安装任务），再编辑生成结果：

• 迁移：bin/rails generate migration ... / bin/rails g model ...
• 邮件、任务、控制器、脚手架：运行对应的 bin/rails g ...
• 身份验证：如果这是应用采用的方式，则运行 bin/rails generate authentication
• 队列、缓存、cable 安装程序：运行 gem 或 Rails 安装任务 （solid_queue:install、good_job:install 及同类任务）
• 安装程序创建的应用／框架配置种子文件（db/*_schema.rb、 config/queue.yml、bin/jobs 等可执行脚本），如果应用尚无这些文件

生成后，根据本地约定调整文件。不要编造迁移版本号或时间戳。如果环境中无法运行生成器，请说明这一点，并提供用户可运行的确切命令——不要伪造文件。

强制代码库扫描

如有以下文件，请务必先阅读：

• Gemfile
• config/application.rb
• config/routes.rb
• config/environments/*.rb（至少阅读当前目标环境对应的文件）
• app/models/（选取 2-5 个有代表性的模型）
• app/controllers/（选取 2-5 个有代表性的控制器）
• test/ 或 spec/
• 进程/部署入口（Procfile*、bin/jobs、config/deploy*.yml、CI 配置）

记录并遵循观察到的模式：

• 测试框架
• 身份验证/授权方式
• 前端技术栈（Hotwire、React、混合模式）
• 队列后端和运行时拓扑
• API 约定和序列化方式

后台作业后端策略

不要仅仅因为应用使用 Rails 8 就假定其使用 Solid Queue。

按以下顺序检测后端：

1. config.active_job.queue_adapter
2. Gemfile 中的 gem（good_job、solid_queue 等）
3. Worker 运行命令和部署配置

遵循以下规则：

• 如果启用了 good_job，则沿用 good_job 的约定。
• 如果启用了 solid_queue，则沿用 solid_queue 的约定。
• 如果两个 gem 都存在，则以已配置的适配器为准。
• 不要在处理无关任务时隐式迁移队列后端。
• 除非明确要求使用后端特有功能，否则编写与后端无关的 ApplicationJob 代码。

参考资料路由

根据任务加载参考资料：

• 代码风格、格式、命名约定和快速失败策略：STYLE.md
• Rails 8 基线默认设置和升级限制：references/01-baseline-rails-8.md
• 命名、分层和代码组织：references/02-naming-and-structure.md
• Active Record、迁移和数据建模：references/03-models-and-data.md
• PostgreSQL 专属的 Active Record 功能：references/03a-active-record-postgresql.md
• 控制器、参数和请求流程：references/04-controllers-and-params.md
• REST 资源和路由：references/05-routes-rest-and-resources.md
• Hotwire、Turbo 和 Stimulus 模式：references/06-hotwire-turbo-stimulus.md
• 作业架构和适配器检测：references/07-background-jobs-overview.md
• GoodJob 专属模式：references/07a-background-jobs-good_job.md
• Solid Queue 专属模式：references/07b-background-jobs-solid_queue.md
• 性能和缓存策略：references/08-performance-caching-and-db.md
• 安全审查清单：references/09-security-checklist.md
• 测试策略和质量门槛：references/10-testing-strategy.md
• 仅 API 模式和混合模式 API 规范：references/11-api-mode-and-serialization.md
• 受 37signals 启发的风格配置：references/12-37signals-inspired-profile.md
• 代码质量阈值和检测模式：references/13-code-quality-gates.md
• 入站/出站 Webhook 和投递可靠性：references/14-webhooks.md

任务路由

任务	加载
Ruby 风格、命名、方法顺序、快速失败	STYLE.md、references/13-code-quality-gates.md
新模型、迁移、数据不变量、解析器	references/03-models-and-data.md、references/03a-active-record-postgresql.md、references/10-testing-strategy.md
控制器参数、授权、会话、响应	references/04-controllers-and-params.md、references/09-security-checklist.md、references/10-testing-strategy.md
路由或自定义操作	references/05-routes-rest-and-resources.md、references/04-controllers-and-params.md
Hotwire、Turbo、Stimulus	references/06-hotwire-turbo-stimulus.md、references/10-testing-strategy.md
后台作业	references/07-background-jobs-overview.md、特定适配器的 07a 或 07b、references/10-testing-strategy.md
Webhook（传入或传出）	references/14-webhooks.md、references/09-security-checklist.md、references/07-background-jobs-overview.md、references/10-testing-strategy.md
API 端点或序列化器	references/11-api-mode-and-serialization.md、references/04-controllers-and-params.md、references/09-security-checklist.md
性能、缓存、查询工作	references/08-performance-caching-and-db.md、references/03-models-and-data.md
架构或对象边界	references/02-naming-and-structure.md、references/12-37signals-inspired-profile.md

身份验证模式

现有的身份验证方式和本地命名具有权威性。对于全新开发的 Rails 8.1 应用，优先使用内置的身份验证生成器。不要仅为符合风格而重命名 现有的身份验证领域。

实现自定义身份验证时：

• 使用基于密码的身份验证，通过 has_secure_password 使用 bcrypt。
• 使用魔法链接代码（而非完整的魔法链接 URL）进行账户确认和电子邮件验证。
• 对于全新开发的基于账户的应用，可考虑使用 Identity（全局电子邮件）、User（每账户成员身份）和 Session。
• 严格限制身份验证端点的请求频率。
• 使用带有 httponly 和 same_site: :lax 的签名 Cookie 存储会话。

输出约定

对于实现任务，需提供：

1. 通过生成的迁移完成所需的架构变更（参见 Generator-Owned Files）。
2. 遵循本地约定的模型、控制器、视图和作业代码。
3. 符合本地框架的测试，并按职责拆分（参见 references/10-testing-strategy.md）。
4. 简要的风险说明（安全、性能、发布相关问题）。
5. 检查当前文档时，提供与版本相关的 API 资料来源说明。

对于审查任务，优先关注：

1. 正确性和行为回归。
2. 安全性和数据完整性。
3. 性能和可运维性。
4. 测试覆盖缺口。