# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个基于 React + Vite + TypeScript 的智慧农业生产管理系统，包含7个主要功能模块：
- 智能农机管理系统 (machinery)
- 地块管理系统 (field)
- 农事管理系统 (operation)
- 资产管理系统 (asset)
- AI模型系统 (ai-model)
- 灌溉控制系统 (irrigation)
- 配置管理系统 (config)

## 开发命令

### 基础命令
- `npm i` - 安装依赖
- `npm run dev` - 启动开发服务器 (端口 3000)
- `npm run build` - 构建生产版本

### 包管理
- 使用 npm 作为包管理工具
- 建议使用 uv 管理 Python 环境（如果需要）

### 代码质量
- 使用 ruff 进行代码格式化
- 遵循 PEP 8 指南和 Python 最佳实践
- 提交信息需符合 Conventional Commits 规范

## 项目架构

### 技术栈
- **前端框架**: React 18 + TypeScript
- **构建工具**: Vite + SWC
- **UI库**: Radix UI + Tailwind CSS
- **状态管理**: React Context (AuthContext)
- **路由**: 自定义基于路径的路由系统
- **图表**: Recharts
- **工具库**: date-fns, clsx, lucide-react

### 目录结构
```
src/
├── components/           # 组件目录
│   ├── ui/              # 基础UI组件 (shadcn/ui)
│   ├── auth/            # 认证相关组件
│   ├── dashboard/       # 各模块主页面组件
│   ├── machinery/       # 农机管理组件
│   ├── field/           # 地块管理组件
│   └── ...              # 其他业务模块组件
├── types/               # TypeScript 类型定义
│   ├── auth.ts          # 认证相关类型
│   ├── navigation.ts    # 导航菜单类型
│   └── ...              # 其他业务类型
├── lib/                 # 工具函数
│   └── authStorage.ts   # 认证存储管理
├── App.tsx              # 主应用组件
├── main.tsx             # 应用入口
└── index.css            # 全局样式
```

### 核心架构模式

#### 路由系统
- 基于路径字符串的自定义路由系统
- 使用 `activePath` 状态管理当前页面
- 路径格式: `/module/submodule/page`

#### 状态管理
- **认证状态**: 通过 AuthContext 管理用户登录状态
- **页面状态**: 每个模块组件接收 `activePath` prop 来渲染对应页面
- **导航状态**: 通过 `activeTab` 和 `activePath` 管理导航

#### 组件结构
- **模块组件**: 每个业务模块有一个主组件，根据 `activePath` 渲染具体页面
- **UI组件**: 基于 shadcn/ui 的可复用组件库
- **业务组件**: 封装具体业务逻辑的组件

#### 类型系统
- 完整的 TypeScript 类型定义
- 按业务模块组织类型文件
- 严格的类型检查

### 认证系统
- 基于 JWT token 的认证机制
- 自动 token 刷新机制
- 支持默认管理员账号自动登录 (admin/admin123)
- 认证信息存储在 localStorage

### 菜单系统
- 层级化菜单结构，支持多级子菜单
- 菜单配置集中定义在 `types/navigation.ts`
- 动态菜单渲染和权限控制

## 开发指南

### 添加新页面
1. 在对应的模块组件中添加路径判断
2. 创建页面组件文件
3. 在 `types/navigation.ts` 中添加菜单项

### 添加新模块
1. 创建模块组件目录和文件
2. 在 `App.tsx` 中添加模块路由
3. 在 `types/navigation.ts` 中定义菜单结构
4. 添加对应的类型定义

### UI组件使用
- 优先使用 `src/components/ui/` 中的组件
- 遵循 shadcn/ui 的设计规范
- 使用 Tailwind CSS 进行样式定制

### 状态管理
- 简单状态使用 React useState
- 复杂状态考虑使用 useReducer 或 Context
- 避免过度抽象

## 原始设计
项目基于 Figma 设计开发，原始设计文件：https://www.figma.com/design/8DbZHcVGcWEyLOjz1PF57B/智慧农业生产管理系统