solid-generic

SOLID Generic 为不使用框架的纯 TypeScript/Bun/Node.js 代码（CLI 工具、库、脚本、钩子）强制执行模块化架构：接口放在 `modules/[feature]/src/interfaces/` 或用于共享类型的 `modules/cores/interfaces/` 中，绝不能放在实现文件里；文件不超过 100 行（模块少于 80 行、服务少于 60 行、验证器少于 40 行）；每个导出项都附带 JSDoc。

编写任何新代码之前，都必须在 modules/cores/lib、modules/cores/interfaces 和 modules/cores/errors 中检查是否存在重复代码，并将重复 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. 在代码库中搜索相似的函数名称、模式或逻辑
2. 检查共享位置：modules/cores/lib/、modules/cores/interfaces/、modules/cores/errors/
3. 如果存在相似代码 -> 扩展或复用，而不是重复编写
4. 如果代码将被 2 个及以上模块使用 -> 在 modules/cores/ 中创建
5. 将重复的逻辑（出现 3 次及以上）提取为共享辅助工具

---

绝对规则（强制）

1. 文件少于 100 行

• 在 90 行处分拆 - 绝不能超过 100 行
• 模块少于 80 行
• 服务少于 60 行
• 验证器少于 40 行

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 模块	80
service.md	带依赖注入的服务	60
interface.md	TypeScript 接口	-
validator.md	Zod 验证模式	40
factory.md	工厂模式	60
error.md	自定义错误类	40
test.md	Bun test / Vitest	-

---

禁止事项

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