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 可以：
|
||||
- 快速理解模块职责和依赖关系
|
||||
- 避免循环依赖和架构混乱
|
||||
- 定位问题和辅助重构
|
||||
- 生成符合项目规范的代码
|
||||
|
||||
---
|
||||
|
||||
*本指南适用于所有项目，可根据具体项目需求进行调整。*
|
||||
36
doc/README.md
Normal file
36
doc/README.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# 文档索引
|
||||
|
||||
> 本目录包含适用于所有项目的通用文档
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
- **[AI友好项目结构.md](AI友好项目结构.md)** - AI 友好项目结构设计指南
|
||||
- **[模块信息模板.md](模块信息模板.md)** - 模块信息文档模板
|
||||
- **[输入输出映射模板.yaml](输入输出映射模板.yaml)** - 输入输出映射模板
|
||||
- **[文档导航模板.yaml](文档导航模板.yaml)** - 文档导航模板
|
||||
|
||||
---
|
||||
|
||||
## 文档说明
|
||||
|
||||
本目录旨在提供通用的项目文档和最佳实践，适用于所有类型的项目开发。
|
||||
|
||||
### 主要内容
|
||||
|
||||
- **AI 友好项目结构**：帮助 AI 快速理解模块职责、依赖关系和业务流程
|
||||
- **标准化文档模板**：统一的文档结构和格式
|
||||
- **可视化工具**：依赖图和调用链生成
|
||||
- **最佳实践**：命名规范、文件大小限制、依赖规则等
|
||||
|
||||
### 如何使用
|
||||
|
||||
1. 参考 `ai-friendly-project-structure.md` 设计项目结构
|
||||
2. 使用提供的模板文件创建模块文档
|
||||
3. 运行生成脚本创建依赖图和调用链
|
||||
4. 保持文档与代码同步更新
|
||||
|
||||
---
|
||||
|
||||
*本目录会持续更新，欢迎贡献更多通用文档。*
|
||||
12
doc/文档导航模板.yaml
Normal file
12
doc/文档导航模板.yaml
Normal file
@@ -0,0 +1,12 @@
|
||||
- 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
|
||||
31
doc/模块信息模板.md
Normal file
31
doc/模块信息模板.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 模块信息模板
|
||||
|
||||
> 本模板适用于所有项目的模块信息文档
|
||||
|
||||
---
|
||||
|
||||
## 功能
|
||||
- 功能1
|
||||
- 功能2
|
||||
- 功能3
|
||||
|
||||
## 接口
|
||||
- `method1(param1: type): returnType`
|
||||
- `method2(param1: type, param2: type): returnType`
|
||||
|
||||
## 输入输出
|
||||
- 输入: 来源和类型
|
||||
- 输出: 目标和类型
|
||||
|
||||
## 依赖
|
||||
- [依赖模块1](路径)
|
||||
- [依赖模块2](路径)
|
||||
|
||||
## 被调用方
|
||||
- 调用方1
|
||||
- 调用方2
|
||||
|
||||
## 示例
|
||||
```javascript
|
||||
// 使用示例
|
||||
```
|
||||
7
doc/输入输出映射模板.yaml
Normal file
7
doc/输入输出映射模板.yaml
Normal file
@@ -0,0 +1,7 @@
|
||||
module: {模块名}
|
||||
inputs:
|
||||
- source: 来源模块.方法
|
||||
type: 输入类型
|
||||
outputs:
|
||||
- destination: 目标模块.方法
|
||||
type: 输出类型
|
||||
78
doc/项目规则.md
Normal file
78
doc/项目规则.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# 代码与提交规范 (通用规则)
|
||||
|
||||
> 本文件包含适用于所有项目的通用编码规范
|
||||
|
||||
---
|
||||
|
||||
## 1. 基础规范
|
||||
|
||||
- **使用 TypeScript**；禁止 any（必要场景以 TODO 标注并跟进）
|
||||
- **文件命名**：小写短横线；TypeScript 类型与接口使用大驼峰
|
||||
- **分支命名**：feature/, fix/, docs/, chore/；提交信息以动词开头，中文或英文均可
|
||||
- **变更前**：必须通过构建与基础校验脚本：npm run check
|
||||
- **注释要求**：中文注释，紧贴代码语句，描述意图而非过程；禁止冗长段落
|
||||
|
||||
---
|
||||
|
||||
## 2. Lint 与格式化
|
||||
|
||||
- **ESLint**：插件启用 ESLint（React+TS）；后端暂不强制 ESLint
|
||||
- **代码风格**：统一缩进 2 空格；UTF-8；换行 LF；末尾换行
|
||||
- **编辑器**：建议在本地启用编辑器保存时格式化（遵循 .editorconfig）
|
||||
|
||||
---
|
||||
|
||||
## 3. TypeScript 约束
|
||||
|
||||
- **Strict 模式**：extension/ tsconfig：strict 开启；paths 使用 @/*
|
||||
- **类型安全**：server/ tsconfig：保持严格类型；避免 any 与隐式 any
|
||||
|
||||
---
|
||||
|
||||
## 4. API 约定
|
||||
|
||||
- **响应结构**：所有响应统一结构：{ success: boolean, data?: any, error?: string }
|
||||
- **错误处理**：错误码与信息需清晰、可定位；4xx 为入参错误，5xx 为服务异常
|
||||
- **CORS**：白名单通过环境变量 ALLOWED_ORIGINS 配置
|
||||
- **速率限制**：通过 RATE_LIMIT_REQUESTS 与 RATE_LIMIT_WINDOW_MS 配置
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全与保密
|
||||
|
||||
- **密钥管理**：严禁提交任何密钥或私密配置；环境变量由 .env 管理并忽略提交
|
||||
|
||||
---
|
||||
|
||||
## 6. 提交前校验
|
||||
|
||||
- **严禁全量构建**：为节省服务器/本机开销，日常开发流程中**严禁运行** `npm run build`
|
||||
- **强制自我审计**：开发者（AI）必须在交付代码前，通过 `Read` 与 `GetDiagnostics` 进行逻辑自查与类型校验
|
||||
- **逻辑自查标准**：代码必须细致到“部署即运行”，业务链路必须闭环（如：新增字段必须在 API 响应中体现，且在 Service 中有对应处理）
|
||||
- **禁止跨 AI 审计**：每个窗口仅负责自身代码的业务完整性，无需等待其他 AI 审计，直接交付
|
||||
|
||||
---
|
||||
|
||||
## 7. Todo 列表执行规范
|
||||
|
||||
- **任务同步**：必须通过 `TodoWrite` 工具同步任务进度；每次对话开始时应优先规划或更新任务列表
|
||||
- **任务管理**：在任务列表中所有 `pending` 或 `in_progress` 的任务未处理完成或未记录明确阻塞原因前，严禁主动终止对话回合或将控制权交还给用户
|
||||
- **阻塞处理**：如果任务被阻塞（Blocked），AI 必须在 Todo 或看板中清晰列举出当前遇到的“自我问题”，并遵循 **RCA 强制模板**：
|
||||
- `[CATEGORY]`：(Context Missing / Logic Conflict / API Hallucination / Env Issue)
|
||||
- `[ROOT_CAUSE]`：(具体原因，如：.env 缺少某 Key)
|
||||
- `[MITIGATION]`：(修复建议或 Fallback 路径，如：手动在 .env 补充该 Key 或使用模拟数据)
|
||||
- **流程闭环**：必须遵循“规划 -> 执行 -> 验证 -> 归档”的完整闭环，单次执行应尽可能覆盖多个关联任务以提高效率
|
||||
- **任务描述**：必须使用中文，并清晰定义“核心/架构/业务/UI”等模块属性
|
||||
|
||||
---
|
||||
|
||||
## 8. AI 可读性优先原则
|
||||
|
||||
- **标准命名**：禁止任何语义不明的缩写。变量名与函数名必须具备强描述性，以最大化 IDE 自动补全的预测准确度
|
||||
- **JSDoc 驱动**：在实现逻辑前，必须编写详尽的 JSDoc（含 `@param`, `@returns`, `@throws`）。这不仅是文档，更是为 Autocomplete 提供精准的上下文先验知识
|
||||
- **小函数原则**：单个函数逻辑控制在 30 行以内。函数越短，Autocomplete 的补全信心指数越高，从而减少人工手动输入的 Dollar Usage 成本
|
||||
- **函数命名**：必须表达业务意图（禁止缩写语义漂移），同类逻辑必须复用统一 Service
|
||||
|
||||
---
|
||||
|
||||
*本文件为通用编码规范，项目特定规则请参考 project-specific-rules.md*\n
|
||||
Reference in New Issue
Block a user