5.2 KiB
5.2 KiB
开发工作流
- 如果我向你提一个新需求或一个 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/
开发建议
创建新页面
- 在
src/views/下创建页面目录 - 路由会自动生成，运行
pnpm gen-route - 在页面中使用
<script setup>和 TypeScript - 使用 Naive UI 组件构建界面
添加 API 接口
- 在
src/service/api/中定义接口 - 在
src/typings/api/中定义类型 - 使用
@sa/axios的请求实例 - 在组件中通过
import使用
状态管理
- 在
src/store/modules/创建 store - 使用
defineStore定义 - 在组件中使用
const store = useXxxStore() - 支持持久化存储插件
组件封装
- 评估是否为通用组件
- 在合适的目录下创建组件文件
- 使用 TypeScript 定义 Props 和 Emits
- 添加必要的文档注释
- 考虑组件的可复用性和可维护性
样式编写
- 优先使用 UnoCSS 原子类
- 复杂布局可使用 Flex/Grid 原子类
- 使用主题变量确保主题切换正常
- SCSS 用于特殊样式需求
国际化
- 翻译文件在
src/locales/langs/ - 使用
$t('key')获取翻译 - 新增翻译需同步更新所有语言文件
注意事项
- 严格类型: 确保所有变量、函数都有明确的类型定义
- 响应式规范: 使用
ref、reactive、computed等 Vue 3 响应式 API - 性能优化: 合理使用
computed、watchEffect，避免不必要的重渲染 - 错误处理: API 请求需添加错误处理逻辑
- 权限控制: 涉及权限的功能需配合路由守卫
- 移动端适配: 注意响应式设计，支持移动端访问
- Monorepo: 修改 packages 下的包时注意影响范围
外部资源
AI 协作提示
在协助开发时，请注意：
- 遵循项目现有的代码风格和架构
- 保持 TypeScript 类型的完整性
- 使用 Vue 3 Composition API
- 优先使用项目已有的工具函数和 Hooks
- 注意 Monorepo 架构，正确引用子包
- 样式优先使用 UnoCSS 原子类
- 确保代码符合 ESLint 规则
- 添加必要的注释，特别是复杂逻辑
- 考虑代码的可维护性和扩展性
- 遵循响应式设计原则