# AI 友好项目结构设计指南

> 本指南适用于所有项目，帮助 AI 快速理解模块职责、依赖关系和业务流程

---

## 1. 项目总体设计原则

### 1.1 模块化
- 每个模块（Module）单一职责，明确功能边界
- 避免跨模块调用深层内部函数，只通过接口或导出函数进行通信

### 1.2 层级清晰
- **分层原则（Layered Architecture）**：
  - `core` 核心逻辑
  - `service` 服务/业务逻辑
  - `controller` 控制层/路由层
  - `ui` 界面或前端组件
- AI 能通过路径快速推断模块职责

### 1.3 依赖方向一致
- 只允许高层模块依赖低层模块，禁止低层模块依赖高层模块
- 可用 `PROJECT_MAP.md` 来可视化依赖关系，帮助 AI 理解边界

### 1.4 明确接口（Interface）
- 每个模块导出统一接口，并在模块目录下放置 `module_info.md` 描述：
  - 功能
  - 输入/输出
  - 调用约束

---

## 2. 推荐项目结构

```
project-root/
├─ core/                     # 核心模块，最低依赖层
│   ├─ utils/                # 公共工具函数
│   │   ├─ string_utils.js
│   │   └─ array_utils.js
│   └─ constants.js
├─ service/                  # 业务逻辑层
│   ├─ userService/
│   │   ├─ index.js
│   │   └─ module_info.md
│   └─ orderService/
│       ├─ index.js
│       └─ module_info.md
├─ controller/               # 控制层
│   ├─ userController.js
│   └─ orderController.js
├─ ui/                       # 前端组件层
│   ├─ components/
│   └─ pages/
├─ docs/                     # 项目文档
│   ├─ core/
│   ├─ service/
│   ├─ controller/
│   ├─ ui/
│   ├─ architecture/
│   ├─ README.md
│   └─ _nav.yaml
└─ package.json
```

---

## 3. AI 友好文件规范

### 3.1 模块信息文件（module_info.md）

**每个模块必须包含**：

```markdown
# UserService 模块
## 功能
- 用户信息管理
- 登录/注册逻辑
- 用户权限验证
## 接口
- `createUser(data: UserData): Promise<User>`
- `getUserById(id: string): Promise<User>`
- `validateUserCredentials(username: string, password: string): Promise<boolean>`
## 依赖
- core/utils
- core/constants
## 被调用方
- controller/userController
## 示例
```javascript
import { createUser } from './userService';
const newUser = await createUser({ username: 'Alice', password: '1234' });
console.log(newUser);
```
```
```

### 3.2 输入输出映射文件（*_io.yaml）

**每个服务模块建议包含**：

```yaml
module: userService
inputs:
  - source: controller/userController.createUser
    type: UserData
  - source: controller/userController.getUser
    type: { id: string }
outputs:
  - destination: controller/userController.sendUserCreatedResponse
    type: User
  - destination: controller/userController.sendUserResponse
    type: User
```

### 3.3 项目文档文件

| 文件 | 用途 |
|------|------|
| `PROJECT_MAP.md` | 模块依赖关系可视化 |
| `PROJECT_RULES.md` | 编码和依赖规范 |
| `ARCHITECTURE.md` | 架构说明 |
| `FEATURE_MAP.md` | 功能模块映射 |
| `CALL_MAP.md` | 业务调用链 |
| `_nav.yaml` | 结构化文档路由 |

---

## 4. 文档路由优化

### 4.1 分层路由结构

```
docs/
├─ core/
│   └─ utils.md
├─ service/
│   ├─ userService.md
│   └─ orderService.md
├─ controller/
│   ├─ userController.md
│   └─ orderController.md
├─ architecture/
│   ├─ PROJECT_MAP.md
│   ├─ PROJECT_RULES.md
│   ├─ FEATURE_MAP.md
│   └─ CALL_MAP.md
├─ README.md         # 索引页
└─ _nav.yaml         # 结构化路由文件
```

### 4.2 统一文档结构

每个模块文档保持相同的结构：
1. 功能
2. 接口
3. 输入输出
4. 依赖
5. 被调用方
6. 示例

### 4.3 跨文档引用

使用相对链接引用依赖模块：

```markdown
## 依赖
- [core/utils](../core/utils.md)
- [userService](../service/userService.md)
```

---

## 5. 可视化工具

### 5.1 依赖图生成

**生成脚本（generate_mermaid.js）**：

```javascript
const fs = require('fs');
const path = require('path');
const yaml = require('js-yaml');

const NAV_FILE = path.join(__dirname, 'docs/_nav.yaml');
const OUTPUT_FILE = path.join(__dirname, 'docs/DEPENDENCY_GRAPH.md');

// 读取 _nav.yaml
const navContent = fs.readFileSync(NAV_FILE, 'utf-8');
const navData = yaml.load(navContent);

// 用于存储 Mermaid 节点和依赖
let nodes = [];
let edges = [];

// 遍历模块生成节点
navData.forEach(moduleGroup => {
  moduleGroup.docs.forEach(doc => {
    const moduleName = `${moduleGroup.module}/${doc.name}`;
    nodes.push(moduleName);
    
    // 尝试读取 module_info.md 获取依赖
    const modulePath = path.join(__dirname, 'docs', moduleGroup.module, `${doc.name}.md`);
    if (fs.existsSync(modulePath)) {
      const mdContent = fs.readFileSync(modulePath, 'utf-8');
      const depMatches = [...mdContent.matchAll(/## 依赖\s*([\s\S]*?)(?:##|$)/g)];
      if (depMatches.length) {
        const depText = depMatches[0][1];
        const depLines = depText.split('\n').map(l => l.trim()).filter(Boolean);
        depLines.forEach(depLine => {
          // 解析 Markdown 链接 [模块](路径)
          const match = depLine.match(/\[([^\]]+)\]/);
          if (match) {
            const depModule = match[1].replace(/\//g, '/');
            edges.push({ from: moduleName, to: depModule });
          }
        });
      }
    }
  });
});

// 生成 Mermaid 文件
let mermaidContent = '```mermaid\nflowchart TD\n';

// 添加节点
nodes.forEach(node => {
  const safeNode = node.replace(/\//g, '_');
  mermaidContent += `    ${safeNode}[${node}]\n`;
});

// 添加边
edges.forEach(edge => {
  const fromNode = edge.from.replace(/\//g, '_');
  const toNode = edge.to.replace(/\//g, '_');
  mermaidContent += `    ${fromNode} --> ${toNode}\n`;
});

mermaidContent += '```';

// 写入文件
fs.writeFileSync(OUTPUT_FILE, mermaidContent, 'utf-8');
console.log('✅ DEPENDENCY_GRAPH.md 已生成');
```

### 5.2 调用链生成

**升级版脚本**：同时生成依赖图和调用链

---

## 6. AI 友好特性

### 6.1 模块边界清晰
- 每个模块都有 `module_info.md` + `io_map.yaml`
- 明确的输入输出和依赖关系

### 6.2 依赖透明化
- `PROJECT_MAP.md` 和 `FEATURE_MAP.md` 让 AI 快速理解依赖和功能分类
- 可视化依赖图帮助识别循环依赖

### 6.3 调用链可视化
- `CALL_MAP.md` 让 AI 理解业务流程
- Mermaid 图表直观展示调用关系

### 6.4 标准化接口
- 所有函数和模块都有明确输入输出类型
- 统一的文档结构便于 AI 解析

### 6.5 示例代码
- `examples/` 提供最小调用示例，方便 AI 理解使用方式

---

## 7. 最佳实践

### 7.1 命名规范
- 模块名：小写短横线（kebab-case）
- 函数名：驼峰命名（camelCase）
- 类名：大驼峰命名（PascalCase）
- 常量：全大写（UPPER_CASE）

### 7.2 文件大小限制
- 单文件：≤ 2000 行
- 单函数：≤ 120 行
- 模块：≤ 10 文件

### 7.3 依赖规则
- 高层模块可以依赖低层模块
- 低层模块不能依赖高层模块
- 同级模块可以相互依赖，但要避免循环依赖

### 7.4 文档维护
- 新增模块时更新 `_nav.yaml`
- 修改依赖时更新 `PROJECT_MAP.md`
- 保持文档与代码同步

---

## 8. 工具推荐

### 8.1 依赖分析工具
- **JS/TS**: `madge`、`dependency-cruiser`
- **Python**: `pydeps`

### 8.2 文档生成工具
- **Markdown**: VS Code + Markdown Preview Enhanced
- **Mermaid**: 支持流程图和时序图

### 8.3 代码质量工具
- **ESLint**: 代码风格检查
- **Prettier**: 代码格式化
- **TypeScript**: 类型检查

---

## 9. 模板文件

### 9.1 模块信息模板（module_info.md）

```markdown
# {模块名} 模块
## 功能
- 功能1
- 功能2
- 功能3
## 接口
- `method1(param1: type): returnType`
- `method2(param1: type, param2: type): returnType`
## 输入输出
- 输入: 来源和类型
- 输出: 目标和类型
## 依赖
- [依赖模块1](路径)
- [依赖模块2](路径)
## 被调用方
- 调用方1
- 调用方2
## 示例
```javascript
// 使用示例
```
```
```

### 9.2 输入输出模板（*_io.yaml）

```yaml
module: {模块名}
inputs:
  - source: 来源模块.方法
    type: 输入类型
outputs:
  - destination: 目标模块.方法
    type: 输出类型
```

### 9.3 导航模板（_nav.yaml）

```yaml
- module: core
  docs:
    - name: utils
      path: core/utils.md
    - name: constants
      path: core/constants.md
- module: service
  docs:
    - name: userService
      path: service/userService.md
    - name: orderService
      path: service/orderService.md
```

---

## 10. 总结

AI 友好项目结构的核心是：

1. **清晰的模块边界**：每个模块有明确的职责和接口
2. **一致的依赖方向**：高层依赖低层，避免循环
3. **标准化的文档**：统一结构，便于 AI 解析
4. **可视化的依赖关系**：帮助 AI 理解整体架构
5. **示例代码**：方便 AI 学习使用方式

通过这套结构，AI 可以：
- 快速理解模块职责和依赖关系
- 避免循环依赖和架构混乱
- 定位问题和辅助重构
- 生成符合项目规范的代码

---

*本指南适用于所有项目，可根据具体项目需求进行调整。*