# Project Context

## Purpose
瓜联丨西瓜产业一体化智能管理平台 - 基于微信小程序的多端ERP系统，专注于西瓜产业的采购管理、供应商管理、交付管理等核心业务流程数字化。项目旨在为西瓜产业链提供高效的数字化管理工具，提升供应链效率和透明度。

## Tech Stack

### 前端核心
- **React 18.0.0** + **TypeScript 5.1.6** - 现代化前端开发框架
- **Taro 4.1.7** - 多端跨平台解决方案，支持微信小程序、H5、支付宝等平台
- **Zustand 5.0.3** - 轻量级全局状态管理
- **SWR 2.3.6** - 数据获取和缓存策略

### UI与样式
- **NutUI 3.0.18** - 微信小程序专用React组件库
- **TailwindCSS 4.1** + **PostCSS** - 原子化CSS框架
- **Sass** - CSS预处理器
- **CSS Variables** - 统一主题系统设计

### 开发工具链
- **pnpm workspace** - 包管理和工作空间
- **Webpack 5.94.0** - 构建工具
- **Babel 7.x** + **SWC** - 代码编译
- **ESLint** + **Prettier** + **Husky** - 代码质量和Git钩子
- **Jest 29.3.1** - 单元测试框架

### 数据与网络
- **Axios 1.7.4** - HTTP客户端
- **OpenAPI** - API类型定义生成
- **本地存储** - 数据持久化

## Project Conventions

### Code Style

#### 命名规范
- **组件**: PascalCase (如: CustomTabBar, PurchaseSection)
- **文件**: kebab-case (如: purchase-order-list.tsx)
- **变量/函数**: camelCase (如: getUserInfo, handleSubmit)
- **常量**: SCREAMING_SNAKE_CASE (如: API_BASE_URL)
- **CSS类**: TailwindCSS原子类 + 自定义kebab-case类

#### 代码组织
```
src/
├── pages/           # 页面组件，按业务模块分组
├── components/      # 通用组件，按功能分组
├── services/        # API服务层
├── store/          # 状态管理
├── utils/          # 工具函数
│   ├── format.ts   # 通用格式化工具（日期、距离、金额等）
│   ├── amount.ts   # 金额处理工具（去除小数后多余零）
│   ├── date.ts     # 日期处理工具
│   └── ...         # 其他工具函数
└── types/          # TypeScript类型定义
```

#### TypeScript规范
- 启用严格类型检查
- 优先使用interface定义对象结构
- 使用联合类型和泛型提高类型复用性
- 避免使用any类型，必要时使用unknown

### Architecture Patterns

#### 分层架构
- **表现层**: React组件 + Taro页面
- **业务层**: 业务逻辑组件 + HOC
- **服务层**: API调用 + 数据转换
- **状态层**: Zustand全局状态 + SWR缓存

#### 设计模式
- **HOC模式**: 基础HOC提供全局功能（认证、权限等）
- **组合模式**: 组件按功能分层组合
- **策略模式**: 不同角色的业务逻辑策略
- **观察者模式**: SWR数据订阅和更新

#### 模块化设计
- 按业务功能垂直切分模块
- 模块内部高内聚，模块间低耦合
- 统一的导出和依赖管理

### Testing Strategy
- **单元测试**: Jest + React Testing Library，覆盖核心业务逻辑
- **组件测试**: 关键组件的渲染和交互测试
- **API测试**: 服务层接口调用测试
- **端到端测试**: 关键业务流程的集成测试
- **目标覆盖率**: 核心模块80%以上

### Git Workflow
- **主要分支**: master (生产), develop (开发)
- **功能分支**: feature/功能名，从develop创建
- **修复分支**: hotfix/问题描述，从master创建
- **提交规范**: Conventional Commits，使用中文提交信息
- **代码审查**: 所有PR必须经过代码审查

## Domain Context

### 核心业务模块
1. **采购管理**:
   - 采购单创建、编辑、提交
   - 多级审核流程（采购员→审核员→审批员）
   - 采购历史记录和状态追踪
   - 费用计算和价格管理

2. **供应商管理**:
   - 供应商信息维护
   - 供应商资质管理
   - 采购历史关联

3. **费用管理**:
   - 采购费用计算和展示
   - 金额格式化处理（去除小数点后多余零）
   - 多种费用类型的统一处理

4. **交付管理**:
   - 交付单创建和管理
   - 配送状态跟踪
   - 交付确认和验收

5. **用户权限**:
   - 基于角色的访问控制（RBAC）
   - 功能权限动态分配
   - 多角色身份支持

### 业务流程
- **采购流程**: 需求确认 → 供应商选择 → 采购单创建 → 多级审核 → 执行采购
- **交付流程**: 采购完成 → 交付安排 → 物流跟踪 → 确认收货

### 数据模型关键概念
- **采购单**: 采购业务的核心实体，包含商品、数量、价格、供应商等信息
- **金额格式**: 统一的金额展示格式（0.00→0, 0.10→0.1, 10.00→10, 10.01→10.01）
- **费用计算**: 采购过程中各类费用的计算和展示逻辑
- **角色权限**: 采购员、审核员、审批员等不同角色的操作权限
- **状态流转**: 采购单从创建到完成的完整生命周期管理

## Important Constraints

### 技术约束
- **微信小程序限制**: 包体积限制、API调用限制、UI组件限制
- **多端兼容**: 必须同时支持微信小程序和H5平台
- **性能要求**: 首屏加载时间 < 3秒，操作响应时间 < 1秒
- **离线支持**: 关键数据本地缓存，支持弱网环境

### 业务约束
- **数据一致性**: 采购状态、库存数据等关键信息的实时一致性
- **权限控制**: 严格的基于角色的功能访问控制
- **审计追踪**: 所有操作必须可追溯，支持审计需求
- **数据安全**: 敏感业务数据加密存储和传输

### 合规约束
- **隐私保护**: 遵循数据隐私保护相关法规
- **微信生态**: 符合微信小程序开发规范和审核要求

## External Dependencies

### 微信生态服务
- **微信登录**: 用户身份认证
- **微信支付**: 支付集成（如需要）
- **微信消息推送**: 业务消息通知

### 核心业务API
- **RESTful API**: 后端业务系统接口
- **文件上传服务**: 附件、图片上传
- **PDF生成服务**: 采购单、交付单等文档生成

### 第三方服务
- **地图服务**: 位置相关功能（如需要）
- **统计分析**: 业务数据分析
- **Lottie动画**: 动画效果支持

### 开发与部署
- **CI/CD平台**: 持续集成和部署
- **代码托管**: Git仓库管理
- **包管理**: npm/pnpm私有仓库（如需要）