solid-react

在 React 19 项目中强制执行 SOLID 和 DRY 架构：源文件不得超过 `FUSE_SOLID_MAX_LINES` 行，并在内聚性下降时按职责拆分；类型隔离在 `modules/[feature]/src/interfaces/` 中（绝不放在组件文件中）；导出项必须添加 JSDoc；禁止使用类组件；编写新代码前必须先搜索现有逻辑／工具（并使用 `jscpd` 检查重复）。

为每个 SOLID 字母提供专属参考指南（SRP 文件拆分、OCP 组合／render-props、LSP 契约合规、ISP 基于角色的 props／context、DIP 通过 Context 进行构造函数注入），另附 10 个可直接复制的模板，涵盖组件、hooks、服务、stores、验证器、工厂和测试。这是一项横切代码质量技能，而非功能技能——React API 本身请参阅 react-19、react-state、react-forms 和 react-tanstack-router。

SOLID React - 组件架构

代码库分析（必须）

任何实现之前：

1. 探索项目结构，了解架构
2. 阅读现有的相关文件，遵循已有模式
3. 识别所用的命名约定、编码风格和模式
4. 了解数据流和依赖关系

DRY - 复用或创建共享代码（必须）

编写任何新代码之前：

1. 使用 grep 搜索代码库，查找相似的函数名、模式或逻辑
2. 检查共享目录：modules/cores/lib/、modules/cores/components/、modules/cores/hooks/
3. 如果存在相似代码 → 扩展／复用，而不是重复编写
4. 如果代码将由 2 个或更多功能使用 → 直接在 modules/cores/ 中创建
5. 将重复出现 3 次或更多次的逻辑提取为共享辅助函数
6. 创建新文件后运行 npx jscpd ./src --threshold 3

---

Agent 工作流（必须）

任何实现之前，并行启动 3 个 Agent，每个分别进行一次带有 name 的 Agent 调用：

1. fuse-ai-pilot:explore-codebase - 分析项目结构和现有模式
2. fuse-ai-pilot:research-expert - 核实所有技术栈技术的最新文档
3. mcp__context7__query-docs - 检查集成兼容性

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

绝对规则（必须）

1. 源文件大小上限

• 源文件不得超过 FUSE_SOLID_MAX_LINES——该 hook 的上限是唯一依据
• 内聚性下降时按职责拆分（通过组合拆分组件，或拆分 hooks、服务）

2. 模块化架构

完整结构（包括功能模块和 cores 目录）请参阅 references/architecture-patterns.md。

3. 必须使用 JSDoc

/**
 * Fetch user by ID from API.
 *
 * @param id - User unique identifier
 * @returns User object or null if not found
 */
export async function getUserById(id: string): Promise<User | null>

4. 接口分离

modules/[feature]/src/interfaces/
├── user.interface.ts
├── post.interface.ts
└── api.interface.ts

绝不要将接口放在组件文件中。

---

SOLID 原则（详细指南）

每项 SOLID 原则都有专属参考指南：

1. references/single-responsibility.md - 一个函数 = 一个变更理由

   • 在 FUSE_SOLID_MAX_LINES 限制内基于职责进行拆分
   • 组件组合模式
   • 拆分策略

2. references/open-closed.md - 通过组合扩展，而非修改

   • 插件架构模式
   • Render props 和插槽
   • 策略模式

3. references/liskov-substitution.md - 契约合规与行为子类型

   • 接口契约
   • 可互换的实现
   • 合规性测试

4. references/interface-segregation.md - 多个精简接口优于一个臃肿接口

   • 基于角色的接口
   • Props 分离
   • Context 拆分

5. references/dependency-inversion.md - 依赖抽象，而非实现

   • 构造函数注入模式
   • 工厂模式
   • 使用 Context 实现依赖注入

概览和速查请参阅 references/solid-principles.md。

---

代码模板

references/templates/ 中可直接复制的代码：

模板	用途
component.md	React 函数组件
hook.md	使用 TanStack Query 的自定义 Hook
service.md	使用依赖注入的服务
store.md	支持持久化的 Zustand store（最多 40 行，所有者规则）
interface.md	TypeScript 接口
validator.md	Zod 验证模式
factory.md	工厂模式
adapter.md	适配器模式
error.md	自定义错误类
test.md	Vitest + Testing Library

每个模板均不超过 FUSE_SOLID_MAX_LINES。

---

响应指南

1. 先调研 - 强制要求：编写任何代码前，先搜索 Context7 + Exa
2. 展示完整代码 - 提供可运行示例，而非代码片段
3. 解释决策 - 说明为何选择此模式，而非其他方案
4. 包含测试 - 始终建议测试用例
5. 处理错误 - 切勿忽略错误，使用错误边界
6. 为所有内容添加类型 - 使用完整的 TypeScript，不使用 any
7. 记录代码 - 为复杂函数编写 JSDoc

---

禁止事项

• 未先调研文档就编写代码（务必先调研）
• 未查看当前年份的文档就使用过时的 API
• 源文件超过 FUSE_SOLID_MAX_LINES
• 在组件文件中定义接口
• 在组件中编写业务逻辑
• 类组件
• 导出内容缺少 JSDoc
• any 类型
• Barrel 导出（index.ts 重新导出）
• 使用 useEffect 获取数据（使用 TanStack Query 或 Router loaders）
• 模块导入另一个模块（核心模块除外）
• 未先使用 Grep 搜索就重复实现已有工具函数/辅助函数
• 复制粘贴逻辑代码块，而不是提取为共享函数