solid-nextjs

在 Next.js 16 项目中强制执行 SOLID 和 DRY 架构：源文件不得超过 `FUSE_SOLID_MAX_LINES`，内聚性下降时按职责拆分；类型应隔离在 `interfaces/` 目录中（绝不放在组件或页面中）；导出内容必须添加 JSDoc；并采用 module/`modules/cores/` 目录结构。编写任何代码前，必须通过 Context7/Exa 使用当前年份研究最新的 Next.js/React/Prisma 文档，并在创建新工具前搜索现有工具。

为 SOLID 的每个字母提供专门的参考指南（SRP 文件拆分、OCP 组合/插件模式、LSP 契约合规、ISP 基于角色的接口、DIP 构造函数注入/工厂），另有 23 个可直接复制的模板，涵盖组件、hooks、服务、存储、Server Actions、API 路由、验证器、Prisma 单例、i18n 和查询。这是一项横切代码质量技能，而非功能技能——框架 API 本身请参阅 nextjs-16 及其同类技能。

SOLID Next.js - 模块化架构

当前日期（重要）

今天：2026 年 1 月——搜索时务必使用当前年份。 使用“2025”或“2026”进行搜索，绝不要使用往年年份。

强制要求：编码前先研究

重要：先确认今天的日期，然后在编写任何代码之前搜索文档和网页。

1. 使用 Context7 查询 Next.js/React 官方文档
2. 使用 Exa 网页搜索，并在搜索中使用当前年份，了解最新趋势
3. 查看当前年份的 Vercel Blog，了解新功能
4. 确认软件包版本与 Next.js 16 兼容

搜索查询（将 YYYY 替换为当前年份）：

• Next.js [feature] YYYY best practices
• React 19 [component] YYYY
• TypeScript [pattern] YYYY
• Prisma 7 [feature] YYYY

---

代码库分析（强制要求）

在任何实现之前：

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，每个都单独调用一次 Agent，并提供 name：

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 设定的上限是唯一依据
• 内聚性下降时按职责拆分（页面委托给模块，组件通过组合拆分，每个关注点对应一个 Server Action）

2. 模块化架构

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

3. 必须添加 JSDoc

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

4. 接口隔离

modules/auth/src/
├── interfaces/          # Types ONLY
│   ├── user.interface.ts
│   └── session.interface.ts
├── services/            # NO types here
└── components/          # NO types here

---

SOLID 原则（详细指南）

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

1. references/single-responsibility.md - 一个类/函数 = 一个修改理由

   • 在 FUSE_SOLID_MAX_LINES 范围内按职责拆分
   • 组件组合模式
   • Next.js 页面和服务器操作示例

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

   • 插件架构模式
   • 多种实现的提供程序模式
   • 适配器和策略模式
   • 在不更改现有代码的情况下添加功能

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

   • 子类型必须可替代基类型
   • 异常和返回类型契约
   • 测试 LSP 合规性

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

   • 基于角色的接口
   • 避免臃肿的契约
   • 面向客户端的接口

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

   • 构造函数注入模式
   • 用于创建的工厂模式
   • IoC 容器
   • 便于在测试中模拟

概览和快速参考请参见 references/solid-principles.md。

---

代码模板

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

模板	用途
server-component.md	带数据获取的服务器组件
client-component.md	带钩子的客户端组件
service.md	带依赖注入的服务
hook.md	带状态的 React 钩子
interface.md	TypeScript 接口
store.md	带持久化的 Zustand store
action.md	带验证的服务器操作
api-route.md	API 路由处理器
validator.md	Zod 验证模式
factory.md	工厂模式
adapter.md	适配器模式
error.md	自定义错误类
test.md	测试模板
middleware.md	身份验证中间件
prisma.md	Prisma 单例
i18n.md	功能/全局翻译
query.md	数据库查询（Prisma 7）

---

响应指南

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

---

禁止事项

• ❌ 未先调研文档就编写代码（务必先调研）
• ❌ 未查阅当前年份的文档就使用过时 API
• ❌ 源文件超过 FUSE_SOLID_MAX_LINES
• ❌ 在组件文件中定义接口
• ❌ 在 app/ 页面中编写业务逻辑
• ❌ 在组件中直接调用数据库
• ❌ 模块导入其他模块（核心模块除外）
• ❌ 默认使用 'use client'
• ❌ 使用 useEffect 获取数据
• ❌ 导出内容缺少 JSDoc
• ❌ 使用 any 类型
• ❌ 使用 Barrel 导出
• ❌ 未先使用 Grep 搜索就重复编写已有工具函数/辅助函数
• ❌ 复制粘贴逻辑代码块，而不提取为共享函数