175 lines
5.2 KiB
Markdown
175 lines
5.2 KiB
Markdown
### 开发工作流
|
|
|
|
- 如果我向你提一个新需求或一个 bug 修复请求，你有不懂的地方，先主动提问，直到你完全理解需求为止。
|
|
|
|
### 核心技术栈
|
|
|
|
- **框架**: 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+
|
|
|
|
## 开发规范
|
|
|
|
### 代码风格
|
|
|
|
- 使用 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/client`
|
|
- API 全部使用safeClient实例 + client.api.admin 发送请求
|
|
- 字段严格遵循每个rpc接口的类型定义
|
|
- 支持请求拦截、响应处理和错误处理
|
|
|
|
### 样式开发
|
|
|
|
- 优先使用 **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/`
|
|
|
|
## 开发建议
|
|
|
|
### 创建新页面
|
|
|
|
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 下的包时注意影响范围
|
|
|
|
## 外部资源
|
|
|
|
- [项目文档](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. 遵循响应式设计原则
|
|
|
|
---
|