### 开发工作流

- 如果我向你提一个新需求或一个 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. 遵循响应式设计原则

---