solid-generic

SOLID Generic 为不使用框架的纯 TypeScript/Bun/Node.js 代码（CLI 工具、库、脚本、钩子）强制实施模块化架构：接口位于 `modules/[feature]/src/interfaces/` 或用于共享类型的 `modules/cores/interfaces/` 中，绝不放在实现文件中；文件行数不超过 `FUSE_SOLID_MAX_LINES`，且每个文件只承担一项职责；每个导出项都附有 JSDoc。

编写任何新代码之前，都必须在 modules/cores/lib、modules/cores/interfaces 和 modules/cores/errors 中进行 DRY 检查，将重复 3 次或以上的内容提取到共享辅助函数中。5 项 SOLID 原则各自都有详细参考文档（从 single-responsibility.md 到 dependency-inversion.md），此外还提供可直接复制粘贴的模块、服务、接口、验证器、工厂、错误和测试模板。

SOLID Generic - TypeScript / Bun / Node.js

Agent 工作流（必须遵守）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用一次，并设置 name：

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

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

---

DRY - 创建前先复用（必须遵守）

编写任何新代码之前：

1. 使用 Grep 搜索代码库，查找相似的函数名、模式或逻辑
2. 检查共享位置：modules/cores/lib/、modules/cores/interfaces/、modules/cores/errors/
3. 如果存在相似代码 -> 扩展或复用，而不是重复实现
4. 如果代码将由 2 个或更多模块使用 -> 在 modules/cores/ 中创建
5. 将重复的逻辑（出现 3 次或以上）提取为共享辅助函数

---

绝对规则（必须遵守）

1. 文件行数不超过 FUSE_SOLID_MAX_LINES

• 在达到钩子上限之前，拆分混合职责
• 每个模块、服务和验证器只承担一项职责

2. 接口分离（模块化，必须遵守）

modules/[feature]/src/interfaces/   # Feature types
  |- user.interface.ts
  \- service.interface.ts
modules/cores/interfaces/            # Shared types
  \- shared.interface.ts

绝不在实现文件中定义接口。 绝不使用扁平的 src/ 结构——始终使用 modules/。

3. 必须编写 JSDoc

/**
 * Parse configuration from file path.
 *
 * @param filePath - Absolute path to config file
 * @returns Parsed configuration object
 * @throws ConfigError if file is invalid
 */
export function parseConfig(filePath: string): Config

---

SOLID 原则（详细指南）

#	原则	参考文档	核心规则
S	单一职责	single-responsibility.md	一个文件 = 一个更改理由
O	开闭原则	open-closed.md	通过组合扩展，而非修改
L	里氏替换原则	liskov-substitution.md	实现必须遵守接口契约
I	接口隔离原则	interface-segregation.md	多个精简接口优于一个臃肿接口
D	依赖倒置原则	dependency-inversion.md	依赖抽象，并注入依赖

概览请参阅 solid-principles.md，项目结构请参阅 architecture-patterns.md。

---

代码模板

模板	用途
module.md	TypeScript/Bun 模块
service.md	带依赖注入的服务
interface.md	TypeScript 接口
validator.md	Zod 验证模式
factory.md	工厂模式
error.md	自定义错误类
test.md	Bun 测试 / Vitest

---

禁止事项

• 文件行数超过 FUSE_SOLID_MAX_LINES
• 在实现文件中定义接口
• 在入口点编写业务逻辑
• 导出项缺少 JSDoc
• 使用 any 类型
• 使用 Barrel 导出（index.ts 重新导出）
• 未先使用 Grep 搜索就重复实现已有工具函数
• 复制粘贴逻辑代码块，而非提取共享函数
• 依赖具体实现，未使用接口抽象