solid-ruby

SOLID Ruby 为 Ruby 4.0+/Rails 8 强制执行模块化架构：每项功能都位于 `app/modules/[feature]/` 下（控制器、服务、仓库、契约、模型），共享代码放在 `app/modules/core/` 中；契约（鸭子类型模块）只能放在 `contracts/` 目录中；每个文件都必须包含 `# frozen_string_literal: true`，且每个公共方法都必须附带 YARD 文档。

编写任何新代码之前，都必须检查 app/modules/core/services 和 app/modules/core/contracts，确保符合 DRY 原则。概览请参阅 solid-principles.md；SRP/OCP/LSP/ISP/DIP 的详细说明请参阅各原则对应的参考文档；模块、服务、契约、模型、错误和测试的脚手架请参阅模板。

SOLID Ruby - 模块化架构

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用都要指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有架构
2. fuse-ai-pilot:research-expert - 通过 Context7 核实 Ruby/Rails 文档
3. fuse-ai-pilot:sniper - 实现后的验证

---

DRY - 创建前优先复用（强制）

编写任何新代码之前：

1. 使用 Grep 搜索代码库，查找类似模块、服务或逻辑
2. 检查共享位置：app/modules/core/services/、app/modules/core/contracts/
3. 如果存在类似代码 -> 扩展或复用，而不是重复创建
4. 如果代码将被 2 个或更多功能使用 -> 在 app/modules/core/ 中创建

---

架构（模块化，强制）

层	位置
控制器	app/modules/[feature]/controllers/
服务	app/modules/[feature]/services/
仓库	app/modules/[feature]/repositories/
契约	app/modules/[feature]/contracts/
模型	app/modules/[feature]/models/
共享	app/modules/core/{services,contracts,concerns}/

绝不使用扁平的 app/ 结构——始终使用 app/modules/[feature]/

---

关键规则（强制）

规则	值
文件行数限制	FUSE_SOLID_MAX_LINES
控制器	保持精简，将任务委托给服务
契约	只能位于 contracts/ 目录（鸭子类型模块）
YARD 文档	每个公共方法都必须有文档
冻结字符串	每个文件都必须包含 # frozen_string_literal: true
Concern	用于共享行为（例如接口）

---

参考指南

概念

主题	参考资料	查阅时机
SOLID 概览	solid-principles.md	快速参考
SRP	single-responsibility.md	类职责过多时
OCP	open-closed.md	添加策略时
LSP	liskov-substitution.md	契约相关
ISP	interface-segregation.md	模块职责过多时
DIP	dependency-inversion.md	依赖注入相关
架构	architecture-patterns.md	模块化 Rails

模板

模板	使用时机
module.md	功能模块结构
service.md	业务逻辑服务
contract.md	鸭子类型契约
model.md	Active Record 模型
error.md	自定义异常
test.md	RSpec 测试

---

禁止事项

反模式	修正方式
文件超过 FUSE_SOLID_MAX_LINES 行	按职责拆分
在模型中编写业务逻辑	提取到服务中
臃肿的控制器	将任务委托给服务
扁平的 app/ 结构	使用 app/modules/[feature]/
上帝类	按职责拆分