financial-admin/.github/copilot-instructions.md

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 规范
• 使用 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/

常用命令

# 开发
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 前自查

外部资源

• 项目文档
• Naive UI 文档
• UnoCSS 文档
• Vue 3 文档
• Vite 文档
• SoybeanJS 规范

AI 协作提示

在协助开发时，请注意：

1. 遵循项目现有的代码风格和架构
2. 保持 TypeScript 类型的完整性
3. 使用 Vue 3 Composition API
4. 优先使用项目已有的工具函数和 Hooks
5. 注意 Monorepo 架构，正确引用子包
6. 样式优先使用 UnoCSS 原子类
7. 确保代码符合 ESLint 规则
8. 添加必要的注释，特别是复杂逻辑
9. 考虑代码的可维护性和扩展性
10. 遵循响应式设计原则

---

最后更新: 2025-12-24