feat: 新增 AI 开发助手指南文档，包含项目概述、核心技术栈、项目结构及开发规范

2025-12-24 19:07:05 +07:00
parent 38d07a4809
commit d46f696085
1 changed files with 260 additions and 0 deletions
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,260 @@
+# SoybeanAdmin - AI 开发助手指南
+
+## 项目概述
+
+SoybeanAdmin 是一个基于 Vue3 + Vite7 + TypeScript 的清新优雅的中后台管理模板。这是一个 **pnpm monorepo** 架构的项目，包含多个子包。
+
+### 核心技术栈
+
+- **框架**: Vue 3.5.25 (Composition API)
+- **构建工具**: Vite 7
+- **语言**: TypeScript 5.9.3
+- **状态管理**: Pinia 3.0.4
+- **路由**: Vue Router 4.6.3 + Elegant Router
+- **UI 组件库**: Naive UI 2.43.2
+- **样式方案**: UnoCSS 66.5.10 + SCSS
+- **国际化**: Vue I18n 11.2.2
+- **HTTP 客户端**: Axios (自封装) / Alova (可选)
+- **图表库**: ECharts 6.0.0
+- **图标**: Iconify
+- **包管理器**: pnpm 10.5.0+
+- **Node 版本**: 20.19.0+
+
+## 项目结构
+
+### 主要目录说明
+
+```
+soybean-admin/
+├── packages/           # Monorepo 子包目录
+│   ├── alova/         # Alova 网络请求封装
+│   ├── axios/         # Axios 网络请求封装
+│   ├── color/         # 颜色工具包
+│   ├── hooks/         # 通用 Hooks 集合
+│   ├── materials/     # 组件物料库
+│   ├── scripts/       # 脚本工具
+│   ├── uno-preset/    # UnoCSS 预设
+│   └── utils/         # 通用工具函数
+├── src/               # 主应用源码
+│   ├── assets/        # 静态资源
+│   ├── components/    # 公共组件
+│   ├── constants/     # 常量定义
+│   ├── enum/          # 枚举定义
+│   ├── hooks/         # 业务 Hooks
+│   ├── layouts/       # 布局组件
+│   ├── locales/       # 国际化配置
+│   ├── plugins/       # 插件配置
+│   ├── router/        # 路由配置
+│   ├── service/       # API 服务层
+│   ├── store/         # Pinia 状态管理
+│   ├── styles/        # 全局样式
+│   ├── theme/         # 主题配置
+│   ├── typings/       # TypeScript 类型定义
+│   ├── utils/         # 工具函数
+│   └── views/         # 页面视图
+├── build/             # 构建配置
+└── public/            # 公共静态资源
+```
+
+### Monorepo 子包说明
+
+- `@sa/axios`: Axios 封装，包含请求拦截、响应处理、错误处理等
+- `@sa/alova`: Alova 封装，提供另一种网络请求方案
+- `@sa/hooks`: 通用 React Hooks 风格的组合式函数
+- `@sa/utils`: 通用工具函数库
+- `@sa/color`: 颜色处理工具
+- `@sa/materials`: UI 组件物料
+- `@sa/scripts`: 命令行工具脚本
+- `@sa/uno-preset`: UnoCSS 自定义预设
+
+## 开发规范
+
+### 代码风格
+
+- 遵循 [SoybeanJS 规范](https://docs.soybeanjs.cn/zh/standard)
+- 使用 ESLint (@soybeanjs/eslint-config) 进行代码检查
+- 严格的 TypeScript 类型检查
+- 使用 Composition API 和 `<script setup>` 语法
+- 优先使用组合式函数 (Composables) 封装可复用逻辑
+
+### Table页面
+
+- 使用@/components/table/table-base.vue 作为基础表格组件
+- 通过配置项实现增删改查功能
+- 支持分页、排序、筛选等常用功能
+- 使用类型定义确保数据结构一致性
+
+### 命名规范
+
+- **文件命名**: kebab-case (如: `user-profile.vue`)
+- **组件命名**: PascalCase (如: `UserProfile`)
+- **函数/变量**: camelCase (如: `getUserInfo`)
+- **常量**: UPPER_SNAKE_CASE (如: `MAX_COUNT`)
+- **类型/接口**: PascalCase (如: `UserInfo`)
+- **枚举**: PascalCase (如: `UserRole`)
+
+### 路由系统
+
+项目使用 **Elegant Router** 实现文件路由系统：
+
+- 路由文件位于 `src/router/elegant/` 目录
+- 路由自动生成，无需手动配置
+- 支持前端静态路由和后端动态路由
+- 路由类型定义自动生成在 `src/typings/elegant-router.d.ts`
+
+### 状态管理
+
+使用 Pinia 进行状态管理：
+
+- Store 文件位于 `src/store/modules/`
+- 使用 `defineStore` 定义状态
+- 支持 Options API 和 Composition API 两种风格
+- Store 类型已在 `src/store/index.ts` 统一导出
+
+### API 服务
+
+- API 定义位于 `src/service/api/`
+- 使用 `@sa/axios` 封装的请求实例
+- 请求配置在 `src/service/request/` 中
+- 支持 TypeScript 类型定义
+
+### 样式开发
+
+- 优先使用 **UnoCSS** 原子化 CSS
+- 使用 `@sa/uno-preset` 自定义预设
+- 全局样式在 `src/styles/` 目录
+- 主题配置在 `src/theme/` 目录
+- 支持 SCSS 预处理器
+
+### 组件开发
+
+- 公共组件位于 `src/components/`
+- 组件分类：
+  - `common/`: 通用基础组件
+  - `custom/`: 自定义业务组件
+  - `advanced/`: 高级封装组件
+  - `table/`: 表格相关组件
+- 使用 `unplugin-vue-components` 自动导入组件
+
+### 类型定义
+
+- 全局类型定义在 `src/typings/` 目录
+- 每个模块可包含独立的类型文件
+- 使用 `.d.ts` 文件进行类型声明
+- API 类型定义在 `src/typings/api/`
+
+## 常用命令
+
+```bash
+# 开发
+pnpm dev              # 测试环境开发
+pnpm dev:prod         # 生产环境模式开发
+
+# 构建
+pnpm build            # 生产环境构建
+pnpm build:test       # 测试环境构建
+
+# 代码质量
+pnpm lint             # ESLint 检查并修复
+pnpm typecheck        # TypeScript 类型检查
+
+# 工具命令
+pnpm gen-route        # 生成路由
+pnpm cleanup          # 清理项目
+pnpm commit           # Git 提交 (英文)
+pnpm commit:zh        # Git 提交 (中文)
+pnpm release          # 发布版本
+pnpm update-pkg       # 更新依赖包
+```
+
+## 开发建议
+
+### 创建新页面
+
+1. 在 `src/views/` 下创建页面目录
+2. 路由会自动生成，运行 `pnpm gen-route`
+3. 在页面中使用 `<script setup>` 和 TypeScript
+4. 使用 Naive UI 组件构建界面
+
+### 添加 API 接口
+
+1. 在 `src/service/api/` 中定义接口
+2. 在 `src/typings/api/` 中定义类型
+3. 使用 `@sa/axios` 的请求实例
+4. 在组件中通过 `import` 使用
+
+### 状态管理
+
+1. 在 `src/store/modules/` 创建 store
+2. 使用 `defineStore` 定义
+3. 在组件中使用 `const store = useXxxStore()`
+4. 支持持久化存储插件
+
+### 组件封装
+
+1. 评估是否为通用组件
+2. 在合适的目录下创建组件文件
+3. 使用 TypeScript 定义 Props 和 Emits
+4. 添加必要的文档注释
+5. 考虑组件的可复用性和可维护性
+
+### 样式编写
+
+1. 优先使用 UnoCSS 原子类
+2. 复杂布局可使用 Flex/Grid 原子类
+3. 使用主题变量确保主题切换正常
+4. SCSS 用于特殊样式需求
+
+### 国际化
+
+1. 翻译文件在 `src/locales/langs/`
+2. 使用 `$t('key')` 获取翻译
+3. 新增翻译需同步更新所有语言文件
+
+## 注意事项
+
+1. **严格类型**: 确保所有变量、函数都有明确的类型定义
+2. **响应式规范**: 使用 `ref`、`reactive`、`computed` 等 Vue 3 响应式 API
+3. **性能优化**: 合理使用 `computed`、`watchEffect`，避免不必要的重渲染
+4. **错误处理**: API 请求需添加错误处理逻辑
+5. **权限控制**: 涉及权限的功能需配合路由守卫
+6. **移动端适配**: 注意响应式设计，支持移动端访问
+7. **Monorepo**: 修改 packages 下的包时注意影响范围
+
+## 开发工作流
+
+1. **启动项目**: `pnpm dev`
+2. **创建分支**: 遵循 Git Flow 规范
+3. **开发功能**: 遵循项目规范编码
+4. **代码检查**: `pnpm lint` 和 `pnpm typecheck`
+5. **提交代码**: `pnpm commit` 或 `pnpm commit:zh`
+6. **测试验证**: 确保功能正常
+7. **代码审查**: 提交 PR 前自查
+
+## 外部资源
+
+- [项目文档](https://github.com/soybeanjs/soybean-admin)
+- [Naive UI 文档](https://www.naiveui.com/)
+- [UnoCSS 文档](https://unocss.dev/)
+- [Vue 3 文档](https://cn.vuejs.org/)
+- [Vite 文档](https://cn.vitejs.dev/)
+- [SoybeanJS 规范](https://docs.soybeanjs.cn/zh/standard)
+
+## AI 协作提示
+
+在协助开发时，请注意：
+
+1. 遵循项目现有的代码风格和架构
+2. 保持 TypeScript 类型的完整性
+3. 使用 Vue 3 Composition API
+4. 优先使用项目已有的工具函数和 Hooks
+5. 注意 Monorepo 架构，正确引用子包
+6. 样式优先使用 UnoCSS 原子类
+7. 确保代码符合 ESLint 规则
+8. 添加必要的注释，特别是复杂逻辑
+9. 考虑代码的可维护性和扩展性
+10. 遵循响应式设计原则
+
+---
+
+**最后更新**: 2025-12-24