# 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/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/`

## 常用命令

```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