开发工具和标准

代码格式和样式标准

本项目结合使用自动化格式化工具和样式强制执行，以在 Ruby 和 JavaScript/TypeScript 代码库中保持一致的代码质量。

Prettier 配置

Prettier 通过以下配置处理 JavaScript、TypeScript 和 CSS 格式，配置定义在 .prettierrc1-4

设置	值	目的
`printWidth`	120	代码格式化的最大行长度
`plugins`	`prettier-plugin-tailwindcss`	自动 Tailwind CSS 类排序

RuboCop Ruby 样式强制执行

RuboCop 提供全面的 Ruby 代码样式检查和强制执行。其配置继承自 Rails 特定规则并包含多项自定义。

核心配置结构

继承自 config/.rails-rubocop.yml 以继承 Rails 特定的规则
使用 DisabledByDefault: true 方法，仅启用明确配置的 cops
包含扩展：rubocop-performance、rubocop-rails、rubocop-rspec、rubocop-rake

主要样式强制执行领域

参数、数组、块和哈希的布局对齐
数组字面量和百分号字面量内部的空格管理
块分隔符的一致性
方法定义之间的空行管理

排除的目录

bin/**/*、db/schema.rb、node_modules/**/*
Nomad 配置文件（gumroad_deployer 除外）
tmp/**/*、vendor/bundle/**/*

来源：.rubocop.yml1-83

开发约定和标准

代码组织和命名约定

本项目通过 .cursorrules1-37 强制执行特定的命名模式和组织标准。

约定	标准	示例
变量命名	使用 `product` 而不是 `link`	`product_id` 而不是 `link_id`
用户角色	使用 `buyer` 和 `seller`	`buyer_email` 而不是 `customer_email`
Sidekiq 作业	类名以 "Job" 结尾	`ProcessBacklogJob`
测试描述	避免以 "should" 开头	`"processes payment"` 而不是 `"should process payment"`
电子邮件域名	使用示例域名	测试时使用 `@example.com`

队列优先级系统

Sidekiq 作业优先级遵循严格的指南，分为四个优先级级别

队列选择指南

critical: 仅用于收据/购买邮件
default: 需要及时处理的时间敏感型作业
low: 大部分后台作业（推荐的默认选项）
mongo: 用于一次性脚本和批量迁移的遗留队列

代码质量模式

依赖管理

使用特定导入：import debounce from "lodash/debounce" 而不是 import { debounce } from "lodash"
新 HTTP 请求使用 request 而不是 $.ajax

数据库和模型模式

外部/公共模型标识符使用 Nano ID
新文件避免使用 app/modules/ 目录（遗留位置）
在适当的目录中使用 concerns：app/controllers/concerns/、app/models/concerns/

测试模式

由于可能出现误报，避免使用 to_not have_enqueued_sidekiq_job
改为对 SidekiqWorkerName.jobs.size 进行断言
测试电子邮件地址使用 @example.com

来源：.cursorrules1-37

测试配置

RSpec 配置

RSpec 测试套件使用来自 .rspec1-4 的以下配置：

设置	目的
`--color`	启用彩色输出以提高可读性
`--require spec_helper`	自动为所有测试引入 spec_helper
`--profile`	显示最慢的示例以识别性能问题

测试执行标准

本项目强调并行测试执行和适当的作业测试模式

新功能测试使用功能标志
回填操作避免使用 ActiveRecord 回调
使用 Onetime 任务而非基于回调的数据迁移
使用 lock: :until_executed 模式测试作业去重

来源：.rspec1-4 .cursorrules27-35

预提交质量门

Git 钩子集成

预提交钩子系统在代码提交前强制执行质量标准

该钩子执行 npx lint-staged，它仅对暂存文件运行配置好的格式化工具和代码检查工具，从而确保高效处理。

来源：.githooks/pre-commit1-2

开发工作流集成

工具链协调

开发工具在协调的工作流中协同工作

质量强制执行层

该系统实现了多层质量强制执行

IDE 层面：.cursorrules 在开发过程中提供实时指导
预提交层面：Git 钩子阻止低质量代码被提交
CI 层面：自动化工作流在部署前捕获问题
测试层面：RSpec 配置确保全面的测试覆盖

配置继承模式

RuboCop 继承自 Rails 特定的配置
覆盖导致误报的 problematic cops
仅启用明确配置的规则以实现可预测的行为

来源：.cursorrules1-37 .prettierrc1-4 .rubocop.yml1-83 .rspec1-4 .githooks/pre-commit1-2