# Project Context

## Purpose
ERPTurbo_Admin 是寻鸿科技的企业资源规划（ERP）管理系统，为企业提供全面的生产管理、库存管理、经销商管理、订单处理等核心业务功能。系统旨在提高企业运营效率，实现业务流程数字化和智能化管理。

## Tech Stack

### 前端框架
- **React 18** - 主要UI框架，使用TypeScript开发
- **UmiJS Max 4.4.9** - 企业级React应用框架，提供路由、构建、部署等一体化解决方案
- **Ant Design 5.25.2** - 企业级UI设计语言和组件库
- **Ant Design Pro Components 2.8.6** - 高级业务组件
- **NutUI React 3.0.18** - 移动端UI组件库（用于移动端适配）

### 状态管理
- **Valtio** - 现代化状态管理库
- **DVA** - 数据流方案（兼容性考虑）
- **React Query** - 服务端状态管理和数据获取

### 表单处理
- **Formily 2.3.2** - 企业级表单解决方案
- **@formily/antd-v5** - Formily与Ant Design v5的集成

### 样式和主题
- **TailwindCSS 3.4.17** - 原子化CSS框架
- **antd-style 3.7.1** - Ant Design样式增强方案
- **Styled Components 6.1.17** - CSS-in-JS样式库

### 工具库
- **Lodash 4.17.21** - 实用工具函数库
- **Day.js 1.11.13** - 轻量级日期处理库
- **Axios 1.7.4** - HTTP客户端
- **UUID 10.0.0** - 唯一标识符生成
- **CryptoJS 4.2.0** - 加密解密功能

### 编辑器和文档
- **@wangeditor-next/editor** - 富文本编辑器
- **Markdown-it 14.1.0** - Markdown解析器
- **XLSX 0.18.5** - Excel文件处理

### 地图服务
- **腾讯地图API** - 地图功能集成

### 开发工具
- **TypeScript 5.6.3** - 类型安全的JavaScript超集
- **PNPM** - 包管理器，支持工作空间
- **Prettier 3.3.3** - 代码格式化
- **ESLint** - 代码质量检查
- **Husky 9.1.6** - Git钩子管理
- **Lint-staged 15.2.10** - 暂存文件检查

## Project Conventions

### 代码风格
- **缩进**: 使用Tab缩进，大小为4个空格宽度
- **行长度**: 最大80字符
- **文件编码**: UTF-8
- **换行符**: LF (Unix风格)
- **尾随空格**: 删除所有尾随空格
- **文件结尾**: 所有文件以换行符结尾

### 命名约定
- **组件文件**: PascalCase (例: `UserList.tsx`)
- **函数/变量**: camelCase (例: `getUserList`)
- **常量**: SCREAMING_SNAKE_CASE (例: `API_BASE_URL`)
- **文件/目录**: kebab-case (例: `user-management/`)
- **接口/类型**: PascalCase，以I或T开头可选 (例: `UserVO`, `APIResponse`)

### 目录结构
```
packages/app-operation/src/
├── components/        # 通用组件
├── pages/            # 页面组件
├── services/         # API服务
├── models/           # 数据模型
├── utils/            # 工具函数
├── constants/        # 常量定义
├── layout/           # 布局组件
├── locales/          # 国际化文件
├── assets/           # 静态资源
└── wrappers/         # 高阶组件包装器
```

### 架构模式
- **微前端架构**: 使用PNPM工作空间管理多个应用
- **分层架构**:
  - 表现层 (Presentation): React组件和页面
  - 业务层 (Business): 业务逻辑和状态管理
  - 数据层 (Data): API调用和数据持久化
- **模块化设计**: 按业务领域划分模块 (dealer, product, operation等)
- **组件化开发**: 优先使用可复用组件

### 测试策略
- **当前状态**: 项目暂无专门的测试配置
- **推荐策略**:
  - 单元测试：使用Jest + Testing Library
  - 集成测试：使用Cypress或Playwright
  - 代码覆盖率：目标 > 80%
  - 测试文件命名: `*.test.tsx` 或 `*.spec.tsx`

### Git工作流
- **分支策略**:
  - `master`: 主分支，生产环境代码
  - `feature/*`: 功能开发分支
  - `hotfix/*`: 紧急修复分支
- **提交规范**: 使用Conventional Commits
  - `feat:` 新功能
  - `fix:` 修复bug
  - `refactor:` 重构代码
  - `docs:` 文档更新
  - `style:` 代码格式调整
  - `test:` 测试相关
  - `chore:` 构建过程或辅助工具变动
- **代码质量**: 使用Husky + Lint-staged进行预提交检查

### API设计规范
- **RESTful API**: 遵循REST设计原则
- **OpenAPI**: 使用Swagger进行API文档化
- **数据格式**: 统一使用JSON
- **错误处理**: 标准化错误响应格式
- **分页**: 统一分页参数和响应格式

## Domain Context

### 业务模块
- **经销商管理 (Dealer)**: 经销商信息、返点计算、配置管理
- **产品管理 (Product)**: 产品数据、规格管理
- **订单管理 (Order)**: 订单处理、发货管理
- **基础数据 (Basic Data)**: 生产预付、工人预付、固定费用
- **纸箱管理 (Box)**: 纸箱规格管理
- **系统设置 (Setting)**: 智能识别配置、系统参数

### 核心概念
- **用户角色**: 普通用户、管理员、经销商
- **权限管理**: 基于角色的访问控制 (RBAC)
- **多租户**: 支持多平台/渠道隔离
- **国际化**: 默认中文，支持多语言扩展

## Important Constraints

### 技术约束
- **浏览器支持**: 现代浏览器 (Chrome 80+, Firefox 75+, Safari 13+)
- **响应式设计**: 支持桌面端和移动端
- **性能要求**: 页面加载时间 < 3秒
- **安全要求**:
  - XSS防护
  - CSRF防护
  - 敏感数据加密
  - API鉴权

### 业务约束
- **数据一致性**: 关键业务数据必须保持一致性
- **审计日志**: 重要操作需要记录审计日志
- **数据备份**: 定期备份关键业务数据
- **合规要求**: 符合企业数据管理规范

## External Dependencies

### 云服务
- **阿里云OSS**: 文件存储服务
- **腾讯地图API**: 地图功能服务

### API服务
- **业务API**: 自建后端API服务
- **认证服务**: SSO单点登录服务

### 第三方集成
- **支付接口**: 支付宝、微信支付（预留）
- **短信服务**: 短信通知服务（预留）
- **邮件服务**: 邮件通知服务（预留）

### 开发环境
- **Node.js**: >= 16.0.0
- **PNPM**: >= 8.0.0
- **Git**: >= 2.30.0