feat: 初始化项目结构并添加核心功能模块
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
This commit is contained in:
395
doc/AI友好项目结构.md
Normal file
395
doc/AI友好项目结构.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 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 可以：
|
||||
- 快速理解模块职责和依赖关系
|
||||
- 避免循环依赖和架构混乱
|
||||
- 定位问题和辅助重构
|
||||
- 生成符合项目规范的代码
|
||||
|
||||
---
|
||||
|
||||
*本指南适用于所有项目，可根据具体项目需求进行调整。*
|
||||
Reference in New Issue
Block a user