solid-react

为 React 19 项目强制实施 SOLID 和 DRY 架构：文件少于 100 行（组件少于 50 行，Hook 少于 30 行，服务少于 40 行）；将类型隔离在 `modules/[feature]/src/interfaces/` 中（绝不放在组件文件里）；导出项必须添加 JSDoc；禁止使用类组件；编写新代码前必须搜索现有逻辑和工具（并使用 `jscpd` 检查重复）。

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

SOLID React - 组件架构

代码库分析（必需）

任何实现之前：

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

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

编写任何新代码之前：

1. 在代码库中搜索相似的函数名、模式或逻辑
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，每个 Agent 调用一次，并指定 name：

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

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

---

绝对规则（必需）

1. 文件少于 100 行

• 达到 90 行时拆分——绝不超过 100 行
• 组件少于 50 行（使用组合）
• 每个 Hook 少于 30 行
• 每个服务少于 40 行

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 - 一个函数 = 一个变更理由

   • 在 90 行处拆分文件（组件少于 50 行，Hook 少于 30 行）
   • 组件组合模式
   • 拆分策略

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

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

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

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

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

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

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

   • 构造函数注入模式
   • 工厂模式
   • 用于 DI 的 Context

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

---

代码模板

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

模板	用途	最大行数
component.md	React 函数组件	50
hook.md	使用 TanStack Query 的自定义 Hook	30
service.md	使用依赖注入的服务	40
store.md	带持久化功能的 Zustand store	40
interface.md	TypeScript 接口	-
validator.md	Zod 验证模式	30
factory.md	工厂模式	40
adapter.md	适配器模式	40
error.md	自定义错误类	30
test.md	Vitest + Testing Library	-

---

响应指南

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

---

禁止事项

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